archastro.platform.v1.resources.knowledge_sources

  1# Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License.
  2# This file is auto-generated by @archastro/sdk-generator. Do not edit.
  3# Content hash: 481469aba270
  4
  5from __future__ import annotations
  6
  7import builtins
  8from datetime import datetime
  9from typing import Any, Literal, Required, TypedDict
 10
 11from pydantic import BaseModel, Field
 12
 13from ...runtime.http_client import HttpClient, SyncHttpClient
 14from ...types.common import ContextIngestion, KnowledgeSource, KnowledgeSourceKindListResponse
 15
 16
 17class KnowledgeSourceCreateInput(TypedDict, total=False):
 18    "Create a knowledge source"
 19
 20    agent: str | None
 21    "Agent ID (`agt_...`) that owns this source. Mutually exclusive with `team` and `user`."
 22    metadata: dict[str, Any] | None
 23    "Arbitrary key-value metadata to attach to the source. Returned as-is on reads."
 24    org: str | None
 25    "Organization ID (`org_...`). Required for system-owned sources that have no individual owner (`team`, `user`, or `agent`)."
 26    parent_source: str | None
 27    "Parent knowledge source ID (`ksrc_...`). Use to create a child source."
 28    payload: dict[str, Any] | None
 29    "Type-specific configuration for the source. Shape depends on `type`."
 30    state: str | None
 31    'Initial state of the source. One of `"active"` (default) or `"paused"`. Paused sources do not trigger ingestion automatically.'
 32    team: str | None
 33    "Team ID (`team_...`) that owns this source. Mutually exclusive with `user` and `agent`."
 34    thread: str | None
 35    "Thread ID (`thr_...`) to associate this source with, if applicable."
 36    type: Required[str]
 37    "Knowledge source type. Must be one of the values returned by `GET /api/v1/knowledge_sources/kinds`."
 38    user: str | None
 39    "User ID (`usr_...`) that owns this source. Mutually exclusive with `team` and `agent`."
 40
 41
 42class KnowledgeSourceUpdateInput(TypedDict, total=False):
 43    "Update a knowledge source"
 44
 45    metadata: dict[str, Any] | None
 46    "Arbitrary key-value metadata to attach to the source. Replaces the entire existing `metadata` map when provided."
 47    payload: dict[str, Any] | None
 48    "Type-specific configuration to replace on the source. Shape depends on the source `type`. Replaces the entire existing `payload` when provided."
 49    state: str | None
 50    'Desired state of the source. One of `"active"` or `"paused"`. Paused sources do not trigger ingestion automatically.'
 51
 52
 53class KnowledgeSourceIngestInputContent(TypedDict, total=False):
 54    content_type: str | None
 55    'MIME type of the content, e.g. `"application/pdf"` or `"text/plain"`.'
 56    data: Required[str]
 57    'The raw document bytes. When `data_encoding` is `"base64"`, provide the base64-encoded representation of the binary content.'
 58    data_encoding: str | None
 59    'Encoding format of `data`. One of `"raw"` (default, plain text) or `"base64"` (binary content such as images or PDFs, decoded server-side before storage).'
 60    filename: str | None
 61    'Original filename for the document, e.g. `"report.pdf"`.'
 62
 63
 64class KnowledgeSourceIngestInput(TypedDict, total=False):
 65    "Trigger ingestion on a knowledge source"
 66
 67    content: KnowledgeSourceIngestInputContent | None
 68    "Inline document bytes to push to the source. Mutually exclusive with `file` and `pull`."
 69    dedupe: bool | None
 70    "When `true`, reuse the source's existing document if the pushed content is byte-identical to it, instead of creating a duplicate. The reused document keeps its chunks and embeddings, and `title`/`metadata` from this request are still applied to it. Content that differs in any way always creates a new document. Defaults to `false`, which creates a new document on every push. Push mode only not valid with `pull: true`. Check `metadata.document_reused` on the returned ingestion to see whether a document was actually reused."
 71    file: str | None
 72    "ID of an already-uploaded file (`fil_...`). The runner reads filename and content type from the stored file. Upload the file via `POST /v1/files` first. Mutually exclusive with `content` and `pull`."
 73    metadata: dict[str, Any] | None
 74    "Arbitrary key-value metadata to attach to the ingested document. Applied in push mode only; ignored when `pull: true`."
 75    pull: bool | None
 76    "When `true`, re-triggers ingestion using the source's own configured data. Re-scrapes a `scrape/site`, re-fetches a `web/link`, or re-processes a `file/document`. Mutually exclusive with `file` and `content`. Not valid for `knowledge/documents` sources."
 77    title: str | None
 78    "Display title for the ingested document. Applied in push mode only; ignored when `pull: true`."
 79
 80
 81class KnowledgeSourceSearchInput(TypedDict, total=False):
 82    "Search within a knowledge source"
 83
 84    max_results: int | None
 85    "Maximum number of results to return. The platform applies its own upper bound; omit to use the default."
 86    min_similarity: float | None
 87    'Cosine-similarity floor for the vector leg, 0.0-1.0. Candidates below it are discarded before ranking, so a high value trades recall for precision. Pass `0.0` to disable the floor when a missed match costs more than a weak one note that with no floor every query returns results, so an empty response can no longer be read as "no match". Omit to use the default.'
 88    mode: str | None
 89    'Search algorithm to use. One of `"hybrid"` (default, combines vector and full-text), `"vector"` (semantic similarity only), or `"fulltext"` (keyword matching only).'
 90    query: Required[str]
 91    "Natural language or keyword query string to search for."
 92    recency_days: int | None
 93    "When set, limits results to documents ingested within the last N days. Omit to search across all documents regardless of age."
 94
 95
 96class KnowledgeSourceListResponseDataItem(BaseModel):
 97    agent: str | None = Field(
 98        default=None,
 99        description="ID of the agent that owns this source (`agt_...`). `null` if owned by a human user or team.",
100    )
101    context_installation: str | None = Field(
102        default=None,
103        description="ID of the context installation that provisioned this source (`cin_...`). `null` when the source was created directly rather than through an installation.",
104    )
105    created_at: datetime | None = Field(
106        default=None, description="When this knowledge source was created (ISO 8601)."
107    )
108    id: str = Field(..., description="Knowledge source ID (`cso_...`).")
109    metadata: dict[str, Any] | None = Field(
110        default=None,
111        description="Arbitrary key-value metadata attached to this source. Useful for storing caller-defined labels or references.",
112    )
113    org: str | None = Field(
114        default=None,
115        description="ID of the organization this source belongs to (`org_...`). `null` if not scoped to an org.",
116    )
117    parent_source: str | None = Field(
118        default=None,
119        description="ID of the parent knowledge source (`cso_...`) when this source was derived from another. `null` for top-level sources.",
120    )
121    payload: dict[str, Any] | None = Field(
122        default=None,
123        description="Type-specific configuration object. The keys depend on the source `type`; see the create endpoint for the expected shape per type.",
124    )
125    sandbox: str | None = Field(
126        default=None,
127        description="ID of the developer sandbox this source is scoped to (`sbx_...`). `null` outside sandbox contexts.",
128    )
129    state: str = Field(
130        ...,
131        description='Current lifecycle state of the source. One of `"active"` (ingestion running normally) or `"paused"` (ingestion suspended).',
132    )
133    team: str | None = Field(
134        default=None,
135        description="ID of the team that owns this source (`tea_...`). `null` if owned by a user, agent, or org.",
136    )
137    thread: str | None = Field(
138        default=None,
139        description="ID of the chat thread this source is associated with (`thr_...`). `null` when not thread-scoped.",
140    )
141    type: str = Field(
142        ...,
143        description='Source type identifier (e.g. `"gmail"`, `"github_activity"`). Determines the shape of `payload` and the ingestion behavior.',
144    )
145    updated_at: datetime | None = Field(
146        default=None, description="When this knowledge source was last modified (ISO 8601)."
147    )
148    user: str | None = Field(
149        default=None,
150        description="ID of the user that owns this source (`usr_...`). `null` if owned by a team, agent, or org.",
151    )
152
153
154class KnowledgeSourceListResponse(BaseModel):
155    """
156    Successful response
157    """
158
159    data: list[KnowledgeSourceListResponseDataItem] = Field(
160        ..., description="Array of knowledge source objects for the current page."
161    )
162    has_next: bool = Field(
163        ..., description="`true` if a subsequent page exists, `false` if this is the last page."
164    )
165    has_prev: bool = Field(
166        ..., description="`true` if a previous page exists, `false` if this is the first page."
167    )
168    page: int = Field(..., description="Current page number.")
169    page_size: int = Field(..., description="Number of results returned per page.")
170    total_entries: int = Field(
171        ..., description="Total number of knowledge sources matching the query across all pages."
172    )
173    total_pages: int = Field(..., description="Total number of pages available.")
174
175
176class KnowledgeSourceSearchResponseDataItem(BaseModel):
177    content: str | None = Field(
178        default=None, description="Normalized plain-text content of the matched chunk."
179    )
180    content_type: str | None = Field(
181        default=None, description='MIME type of the content, e.g. `"text/plain"` or `"text/html"`.'
182    )
183    created_at: datetime | None = Field(
184        default=None, description="When this item was indexed into the knowledge base (ISO 8601)."
185    )
186    id: str = Field(..., description="Context item ID (`cim_...`).")
187    kind: Literal["chunk"] = Field(
188        default="chunk",
189        description='Result variant discriminator. Always `"chunk"` for this object type.',
190    )
191    metadata: dict[str, Any] | None = Field(
192        default=None,
193        description="Arbitrary key-value metadata attached to this item by the source connector.",
194    )
195    raw_content: dict[str, Any] | None = Field(
196        default=None,
197        description="Raw content payload as stored by the source connector, before normalization.",
198    )
199    structured_data: str | None = Field(
200        default=None,
201        description="Public ID (`sda_...`) of the structured-data record attached to the source message. Present only for such items on source search.",
202    )
203    structured_data_summary: str | None = Field(
204        default=None,
205        description="Search summary of that record, computed when the request is served. When present, `content` is the indexed text and may be stale.",
206    )
207    type: str | None = Field(
208        default=None,
209        description='Type identifier of the parent knowledge source (e.g. `"gmail"`, `"github_activity"`). Returns `"unknown"` when the source association is not loaded.',
210    )
211
212
213class KnowledgeSourceSearchResponse(BaseModel):
214    """
215    Successful response
216    """
217
218    data: list[KnowledgeSourceSearchResponseDataItem] = Field(
219        ...,
220        description="Array of matching knowledge items ordered by relevance score descending. An item indexed from a message that has structured data attached also carries `structured_data` and `structured_data_summary`, the record's search summary computed at read time. `content` is still the indexed text and may be stale.",
221    )
222    degraded: bool | None = Field(
223        default=None,
224        description="True when a `hybrid` search ran fulltext only because the vector leg was unavailable. Absent when the query was empty.",
225    )
226    effective_mode: Literal["hybrid", "vector", "fulltext"] | None = Field(
227        default=None,
228        description="Retrieval mode that actually ran. Differs from the requested `mode` when a `hybrid` search fell back to `fulltext`. Absent when the query was empty.",
229    )
230
231
232class AsyncKnowledgeSourceKindResource:
233    def __init__(self, http: HttpClient):
234        self._http = http
235
236    async def list(self) -> KnowledgeSourceKindListResponse:
237        """
238        List creatable knowledge source kinds
239        Returns the fixed set of knowledge source types that can be created directly via
240        `POST /api/v1/knowledge_sources`. Use this endpoint to discover valid values for the
241        `type` param before calling the create endpoint.
242        Source kinds populated by server-driven flows such as `webhook/inbound`,
243        `connectors/*/emails`, and `thread/messages` are intentionally excluded from this
244        list, as they cannot be created through the API.
245
246        Returns:
247            List of knowledge source kinds available for creation via the API.
248        """
249        return await self._http.request(
250            "/api/v1/knowledge_sources/kinds",
251            response_type=KnowledgeSourceKindListResponse,
252        )
253
254
255class AsyncKnowledgeSourceResource:
256    def __init__(self, http: HttpClient):
257        self._http = http
258        self.kinds = AsyncKnowledgeSourceKindResource(http)
259
260    async def list(
261        self,
262        *,
263        page: int | None = None,
264        page_size: int | None = None,
265        search: str | None = None,
266        type: str | None = None,
267        team: builtins.list[str] | None = None,
268        thread: builtins.list[str] | None = None,
269        installation: str | None = None,
270        agent: str | None = None,
271        org: str | None = None,
272        owner_scope: Literal["any", "individual", "system"] | None = None,
273    ) -> KnowledgeSourceListResponse:
274        """
275        List knowledge sources
276        Returns a paginated list of knowledge sources visible to the authenticated caller.
277        Results are ordered by creation time descending.
278        Use the `type`, `installation`, `agent`, `org`, and `owner_scope` filters to narrow the
279        result set. Combine `owner_scope: "system"` with `org` to list org-level sources that
280        have no individual owner. Combine `owner_scope: "individual"` with `agent` to list
281        sources owned by a specific agent.
282        Pagination is page-number based. The default page size is 25.
283
284        Args:
285            page: Page number to retrieve. Defaults to 1.
286            page_size: Number of knowledge sources to return per page. Defaults to 25.
287            search: Filter sources whose type contains this string. Case-insensitive substring match.
288            type: Exact knowledge source type to filter by, e.g. `"knowledge/documents"`.
289            team: Exact team IDs whose sources to include.
290            thread: Exact backing thread IDs whose sources to include.
291            installation: Installation ID (`ins_...`). Returns only sources associated with this installation.
292            agent: Agent ID (`agt_...`). Returns only sources owned by or associated with this agent.
293            org: Organization ID (`org_...`). Returns only sources belonging to this organization. Combine with `owner_scope: "system"` to retrieve org-level system sources.
294            owner_scope: Filter by ownership scope. One of `"any"` (default returns all visible sources), `"individual"` (only sources owned by a user, team, or agent), or `"system"` (only sources with no individual owner, typically org-level).
295
296        Returns:
297            Successful response
298        """
299        query: dict[str, object] = {}
300        if page is not None:
301            query["page"] = page
302        if page_size is not None:
303            query["page_size"] = page_size
304        if search is not None:
305            query["search"] = search
306        if type is not None:
307            query["type"] = type
308        if team is not None:
309            query["team"] = team
310        if thread is not None:
311            query["thread"] = thread
312        if installation is not None:
313            query["installation"] = installation
314        if agent is not None:
315            query["agent"] = agent
316        if org is not None:
317            query["org"] = org
318        if owner_scope is not None:
319            query["owner_scope"] = owner_scope
320        return await self._http.request(
321            "/api/v1/knowledge_sources",
322            query=query,
323            response_type=KnowledgeSourceListResponse,
324        )
325
326    async def create(self, input: KnowledgeSourceCreateInput) -> KnowledgeSource:
327        """
328        Create a knowledge source
329        Creates a new knowledge source of the requested type and returns the created object.
330        Only types listed by `GET /api/v1/knowledge_sources/kinds` may be created through this
331        endpoint. Other source types such as `webhook/inbound`, `connectors/*/emails`, and
332        `thread/messages` are provisioned automatically by server-driven flows (webhook
333        auto-provisioning, installation activation, connector lifecycle events) and cannot be
334        created directly via the API.
335        Exactly one of `team`, `user`, `agent`, or `org` must identify the owner of the new
336        source. Omit `org` when an individual owner (`team`, `user`, or `agent`) is supplied;
337        include `org` alone for org-level system-owned sources.
338
339        Args:
340            input: Request body.
341            input.agent: Agent ID (`agt_...`) that owns this source. Mutually exclusive with `team` and `user`.
342            input.metadata: Arbitrary key-value metadata to attach to the source. Returned as-is on reads.
343            input.org: Organization ID (`org_...`). Required for system-owned sources that have no individual owner (`team`, `user`, or `agent`).
344            input.parent_source: Parent knowledge source ID (`ksrc_...`). Use to create a child source.
345            input.payload: Type-specific configuration for the source. Shape depends on `type`.
346            input.state: Initial state of the source. One of `"active"` (default) or `"paused"`. Paused sources do not trigger ingestion automatically.
347            input.team: Team ID (`team_...`) that owns this source. Mutually exclusive with `user` and `agent`.
348            input.thread: Thread ID (`thr_...`) to associate this source with, if applicable.
349            input.type: Knowledge source type. Must be one of the values returned by `GET /api/v1/knowledge_sources/kinds`.
350            input.user: User ID (`usr_...`) that owns this source. Mutually exclusive with `team` and `agent`.
351
352        Returns:
353            The newly created knowledge source.
354        """
355        return await self._http.request(
356            "/api/v1/knowledge_sources",
357            method="POST",
358            body=input,
359            response_type=KnowledgeSource,
360        )
361
362    async def delete(self, source: str) -> None:
363        """
364        Delete a knowledge source
365        Permanently deletes the knowledge source identified by `source`. This action is
366        irreversible all documents, embeddings, and ingestion history associated with the
367        source are removed.
368        The authenticated caller must own the source or have sufficient permissions within its
369        parent organization. Returns `204 No Content` on success.
370
371        Args:
372            source: Knowledge source ID (`ksrc_...`) to delete.
373
374        Returns:
375            Empty response. The source has been permanently deleted.
376        """
377        await self._http.request(f"/api/v1/knowledge_sources/{source}", method="DELETE")
378
379    async def get(self, source: str) -> KnowledgeSource:
380        """
381        Retrieve a knowledge source
382        Returns the knowledge source identified by `source`. The authenticated caller must have
383        access to the source's parent organization or be the individual owner of the source.
384        Use the list endpoint to retrieve many sources at once or to discover sources by type
385        or owner.
386
387        Args:
388            source: Knowledge source ID (`ksrc_...`) to retrieve.
389
390        Returns:
391            The requested knowledge source.
392        """
393        return await self._http.request(
394            f"/api/v1/knowledge_sources/{source}",
395            response_type=KnowledgeSource,
396        )
397
398    async def update(self, source: str, input: KnowledgeSourceUpdateInput) -> KnowledgeSource:
399        """
400        Update a knowledge source
401        Updates the mutable fields of an existing knowledge source and returns the updated
402        object. Only fields provided in the request body are changed; omitted fields retain
403        their current values.
404        You can update the type-specific `payload`, the `metadata` map, and the `state`. To
405        pause a source and prevent automatic ingestion, set `state` to `"paused"`. To resume,
406        set it back to `"active"`.
407
408        Args:
409            source: Knowledge source ID (`ksrc_...`) to update.
410            input: Request body.
411            input.metadata: Arbitrary key-value metadata to attach to the source. Replaces the entire existing `metadata` map when provided.
412            input.payload: Type-specific configuration to replace on the source. Shape depends on the source `type`. Replaces the entire existing `payload` when provided.
413            input.state: Desired state of the source. One of `"active"` or `"paused"`. Paused sources do not trigger ingestion automatically.
414
415        Returns:
416            The updated knowledge source.
417        """
418        return await self._http.request(
419            f"/api/v1/knowledge_sources/{source}",
420            method="PATCH",
421            body=input,
422            response_type=KnowledgeSource,
423        )
424
425    async def ingest(self, source: str, input: KnowledgeSourceIngestInput) -> ContextIngestion:
426        """
427        Trigger ingestion on a knowledge source
428        Starts an ingestion run on the specified knowledge source and returns the ingestion
429        object. Exactly one of two modes must be chosen per request:
430        **Push mode** (`file` or `content`) available for `knowledge/documents` sources only.
431        Supply the document bytes either as a reference to an already-uploaded file (`file`) or
432        as an inline blob (`content`). The runner stores the bytes and indexes the resulting
433        document. `title` and `metadata` are persisted on the document in push mode.
434        **Pull mode** (`pull: true`) re-triggers ingestion using the source's own configured
435        data. Use this to re-scrape a `scrape/site`, re-fetch a `web/link`, or re-process a
436        `file/document`. Not valid for `knowledge/documents` (which has no upstream push new
437        bytes instead) or for source kinds populated by server-driven flows. `title` and
438        `metadata` are ignored in pull mode.
439        If an ingestion is already active for the source, the existing ingestion is returned
440        rather than creating a duplicate.
441
442        Args:
443            source: Knowledge source ID (`ksrc_...`) to ingest.
444            input: Request body.
445            input.content: Inline document bytes to push to the source. Mutually exclusive with `file` and `pull`.
446            input.dedupe: When `true`, reuse the source's existing document if the pushed content is byte-identical to it, instead of creating a duplicate. The reused document keeps its chunks and embeddings, and `title`/`metadata` from this request are still applied to it. Content that differs in any way always creates a new document. Defaults to `false`, which creates a new document on every push. Push mode only not valid with `pull: true`. Check `metadata.document_reused` on the returned ingestion to see whether a document was actually reused.
447            input.file: ID of an already-uploaded file (`fil_...`). The runner reads filename and content type from the stored file. Upload the file via `POST /v1/files` first. Mutually exclusive with `content` and `pull`.
448            input.metadata: Arbitrary key-value metadata to attach to the ingested document. Applied in push mode only; ignored when `pull: true`.
449            input.pull: When `true`, re-triggers ingestion using the source's own configured data. Re-scrapes a `scrape/site`, re-fetches a `web/link`, or re-processes a `file/document`. Mutually exclusive with `file` and `content`. Not valid for `knowledge/documents` sources.
450            input.title: Display title for the ingested document. Applied in push mode only; ignored when `pull: true`.
451
452        Returns:
453            The created ingestion, or an existing active ingestion if one is already running.
454        """
455        return await self._http.request(
456            f"/api/v1/knowledge_sources/{source}/ingest",
457            method="POST",
458            body=input,
459            response_type=ContextIngestion,
460        )
461
462    async def search(
463        self, source: str, input: KnowledgeSourceSearchInput
464    ) -> KnowledgeSourceSearchResponse:
465        """
466        Search within a knowledge source
467        Executes a search query against the indexed documents in a single knowledge source and
468        returns matching results ranked by relevance.
469        Three search modes are supported: `"hybrid"` (default) combines vector similarity and
470        full-text scoring, `"vector"` uses embedding-based semantic search only, and
471        `"fulltext"` uses keyword-based search only. Use `"hybrid"` for most use cases;
472        prefer `"vector"` when semantic meaning matters more than exact terms.
473        Optionally restrict results to documents ingested within the last N days using
474        `recency_days`. Results are ordered by relevance score descending.
475
476        Args:
477            source: Knowledge source ID (`ksrc_...`) to search within.
478            input: Request body.
479            input.max_results: Maximum number of results to return. The platform applies its own upper bound; omit to use the default.
480            input.min_similarity: Cosine-similarity floor for the vector leg, 0.0-1.0. Candidates below it are discarded before ranking, so a high value trades recall for precision. Pass `0.0` to disable the floor when a missed match costs more than a weak one note that with no floor every query returns results, so an empty response can no longer be read as "no match". Omit to use the default.
481            input.mode: Search algorithm to use. One of `"hybrid"` (default, combines vector and full-text), `"vector"` (semantic similarity only), or `"fulltext"` (keyword matching only).
482            input.query: Natural language or keyword query string to search for.
483            input.recency_days: When set, limits results to documents ingested within the last N days. Omit to search across all documents regardless of age.
484
485        Returns:
486            Successful response
487        """
488        return await self._http.request(
489            f"/api/v1/knowledge_sources/{source}/search",
490            method="POST",
491            body=input,
492            response_type=KnowledgeSourceSearchResponse,
493        )
494
495
496class KnowledgeSourceKindResource:
497    def __init__(self, http: SyncHttpClient):
498        self._http = http
499
500    def list(self) -> KnowledgeSourceKindListResponse:
501        """
502        List creatable knowledge source kinds
503        Returns the fixed set of knowledge source types that can be created directly via
504        `POST /api/v1/knowledge_sources`. Use this endpoint to discover valid values for the
505        `type` param before calling the create endpoint.
506        Source kinds populated by server-driven flows such as `webhook/inbound`,
507        `connectors/*/emails`, and `thread/messages` are intentionally excluded from this
508        list, as they cannot be created through the API.
509
510        Returns:
511            List of knowledge source kinds available for creation via the API.
512        """
513        return self._http.request(
514            "/api/v1/knowledge_sources/kinds",
515            response_type=KnowledgeSourceKindListResponse,
516        )
517
518
519class KnowledgeSourceResource:
520    def __init__(self, http: SyncHttpClient):
521        self._http = http
522        self.kinds = KnowledgeSourceKindResource(http)
523
524    def list(
525        self,
526        *,
527        page: int | None = None,
528        page_size: int | None = None,
529        search: str | None = None,
530        type: str | None = None,
531        team: builtins.list[str] | None = None,
532        thread: builtins.list[str] | None = None,
533        installation: str | None = None,
534        agent: str | None = None,
535        org: str | None = None,
536        owner_scope: Literal["any", "individual", "system"] | None = None,
537    ) -> KnowledgeSourceListResponse:
538        """
539        List knowledge sources
540        Returns a paginated list of knowledge sources visible to the authenticated caller.
541        Results are ordered by creation time descending.
542        Use the `type`, `installation`, `agent`, `org`, and `owner_scope` filters to narrow the
543        result set. Combine `owner_scope: "system"` with `org` to list org-level sources that
544        have no individual owner. Combine `owner_scope: "individual"` with `agent` to list
545        sources owned by a specific agent.
546        Pagination is page-number based. The default page size is 25.
547
548        Args:
549            page: Page number to retrieve. Defaults to 1.
550            page_size: Number of knowledge sources to return per page. Defaults to 25.
551            search: Filter sources whose type contains this string. Case-insensitive substring match.
552            type: Exact knowledge source type to filter by, e.g. `"knowledge/documents"`.
553            team: Exact team IDs whose sources to include.
554            thread: Exact backing thread IDs whose sources to include.
555            installation: Installation ID (`ins_...`). Returns only sources associated with this installation.
556            agent: Agent ID (`agt_...`). Returns only sources owned by or associated with this agent.
557            org: Organization ID (`org_...`). Returns only sources belonging to this organization. Combine with `owner_scope: "system"` to retrieve org-level system sources.
558            owner_scope: Filter by ownership scope. One of `"any"` (default returns all visible sources), `"individual"` (only sources owned by a user, team, or agent), or `"system"` (only sources with no individual owner, typically org-level).
559
560        Returns:
561            Successful response
562        """
563        query: dict[str, object] = {}
564        if page is not None:
565            query["page"] = page
566        if page_size is not None:
567            query["page_size"] = page_size
568        if search is not None:
569            query["search"] = search
570        if type is not None:
571            query["type"] = type
572        if team is not None:
573            query["team"] = team
574        if thread is not None:
575            query["thread"] = thread
576        if installation is not None:
577            query["installation"] = installation
578        if agent is not None:
579            query["agent"] = agent
580        if org is not None:
581            query["org"] = org
582        if owner_scope is not None:
583            query["owner_scope"] = owner_scope
584        return self._http.request(
585            "/api/v1/knowledge_sources",
586            query=query,
587            response_type=KnowledgeSourceListResponse,
588        )
589
590    def create(self, input: KnowledgeSourceCreateInput) -> KnowledgeSource:
591        """
592        Create a knowledge source
593        Creates a new knowledge source of the requested type and returns the created object.
594        Only types listed by `GET /api/v1/knowledge_sources/kinds` may be created through this
595        endpoint. Other source types such as `webhook/inbound`, `connectors/*/emails`, and
596        `thread/messages` are provisioned automatically by server-driven flows (webhook
597        auto-provisioning, installation activation, connector lifecycle events) and cannot be
598        created directly via the API.
599        Exactly one of `team`, `user`, `agent`, or `org` must identify the owner of the new
600        source. Omit `org` when an individual owner (`team`, `user`, or `agent`) is supplied;
601        include `org` alone for org-level system-owned sources.
602
603        Args:
604            input: Request body.
605            input.agent: Agent ID (`agt_...`) that owns this source. Mutually exclusive with `team` and `user`.
606            input.metadata: Arbitrary key-value metadata to attach to the source. Returned as-is on reads.
607            input.org: Organization ID (`org_...`). Required for system-owned sources that have no individual owner (`team`, `user`, or `agent`).
608            input.parent_source: Parent knowledge source ID (`ksrc_...`). Use to create a child source.
609            input.payload: Type-specific configuration for the source. Shape depends on `type`.
610            input.state: Initial state of the source. One of `"active"` (default) or `"paused"`. Paused sources do not trigger ingestion automatically.
611            input.team: Team ID (`team_...`) that owns this source. Mutually exclusive with `user` and `agent`.
612            input.thread: Thread ID (`thr_...`) to associate this source with, if applicable.
613            input.type: Knowledge source type. Must be one of the values returned by `GET /api/v1/knowledge_sources/kinds`.
614            input.user: User ID (`usr_...`) that owns this source. Mutually exclusive with `team` and `agent`.
615
616        Returns:
617            The newly created knowledge source.
618        """
619        return self._http.request(
620            "/api/v1/knowledge_sources",
621            method="POST",
622            body=input,
623            response_type=KnowledgeSource,
624        )
625
626    def delete(self, source: str) -> None:
627        """
628        Delete a knowledge source
629        Permanently deletes the knowledge source identified by `source`. This action is
630        irreversible all documents, embeddings, and ingestion history associated with the
631        source are removed.
632        The authenticated caller must own the source or have sufficient permissions within its
633        parent organization. Returns `204 No Content` on success.
634
635        Args:
636            source: Knowledge source ID (`ksrc_...`) to delete.
637
638        Returns:
639            Empty response. The source has been permanently deleted.
640        """
641        self._http.request(f"/api/v1/knowledge_sources/{source}", method="DELETE")
642
643    def get(self, source: str) -> KnowledgeSource:
644        """
645        Retrieve a knowledge source
646        Returns the knowledge source identified by `source`. The authenticated caller must have
647        access to the source's parent organization or be the individual owner of the source.
648        Use the list endpoint to retrieve many sources at once or to discover sources by type
649        or owner.
650
651        Args:
652            source: Knowledge source ID (`ksrc_...`) to retrieve.
653
654        Returns:
655            The requested knowledge source.
656        """
657        return self._http.request(
658            f"/api/v1/knowledge_sources/{source}",
659            response_type=KnowledgeSource,
660        )
661
662    def update(self, source: str, input: KnowledgeSourceUpdateInput) -> KnowledgeSource:
663        """
664        Update a knowledge source
665        Updates the mutable fields of an existing knowledge source and returns the updated
666        object. Only fields provided in the request body are changed; omitted fields retain
667        their current values.
668        You can update the type-specific `payload`, the `metadata` map, and the `state`. To
669        pause a source and prevent automatic ingestion, set `state` to `"paused"`. To resume,
670        set it back to `"active"`.
671
672        Args:
673            source: Knowledge source ID (`ksrc_...`) to update.
674            input: Request body.
675            input.metadata: Arbitrary key-value metadata to attach to the source. Replaces the entire existing `metadata` map when provided.
676            input.payload: Type-specific configuration to replace on the source. Shape depends on the source `type`. Replaces the entire existing `payload` when provided.
677            input.state: Desired state of the source. One of `"active"` or `"paused"`. Paused sources do not trigger ingestion automatically.
678
679        Returns:
680            The updated knowledge source.
681        """
682        return self._http.request(
683            f"/api/v1/knowledge_sources/{source}",
684            method="PATCH",
685            body=input,
686            response_type=KnowledgeSource,
687        )
688
689    def ingest(self, source: str, input: KnowledgeSourceIngestInput) -> ContextIngestion:
690        """
691        Trigger ingestion on a knowledge source
692        Starts an ingestion run on the specified knowledge source and returns the ingestion
693        object. Exactly one of two modes must be chosen per request:
694        **Push mode** (`file` or `content`) available for `knowledge/documents` sources only.
695        Supply the document bytes either as a reference to an already-uploaded file (`file`) or
696        as an inline blob (`content`). The runner stores the bytes and indexes the resulting
697        document. `title` and `metadata` are persisted on the document in push mode.
698        **Pull mode** (`pull: true`) re-triggers ingestion using the source's own configured
699        data. Use this to re-scrape a `scrape/site`, re-fetch a `web/link`, or re-process a
700        `file/document`. Not valid for `knowledge/documents` (which has no upstream push new
701        bytes instead) or for source kinds populated by server-driven flows. `title` and
702        `metadata` are ignored in pull mode.
703        If an ingestion is already active for the source, the existing ingestion is returned
704        rather than creating a duplicate.
705
706        Args:
707            source: Knowledge source ID (`ksrc_...`) to ingest.
708            input: Request body.
709            input.content: Inline document bytes to push to the source. Mutually exclusive with `file` and `pull`.
710            input.dedupe: When `true`, reuse the source's existing document if the pushed content is byte-identical to it, instead of creating a duplicate. The reused document keeps its chunks and embeddings, and `title`/`metadata` from this request are still applied to it. Content that differs in any way always creates a new document. Defaults to `false`, which creates a new document on every push. Push mode only not valid with `pull: true`. Check `metadata.document_reused` on the returned ingestion to see whether a document was actually reused.
711            input.file: ID of an already-uploaded file (`fil_...`). The runner reads filename and content type from the stored file. Upload the file via `POST /v1/files` first. Mutually exclusive with `content` and `pull`.
712            input.metadata: Arbitrary key-value metadata to attach to the ingested document. Applied in push mode only; ignored when `pull: true`.
713            input.pull: When `true`, re-triggers ingestion using the source's own configured data. Re-scrapes a `scrape/site`, re-fetches a `web/link`, or re-processes a `file/document`. Mutually exclusive with `file` and `content`. Not valid for `knowledge/documents` sources.
714            input.title: Display title for the ingested document. Applied in push mode only; ignored when `pull: true`.
715
716        Returns:
717            The created ingestion, or an existing active ingestion if one is already running.
718        """
719        return self._http.request(
720            f"/api/v1/knowledge_sources/{source}/ingest",
721            method="POST",
722            body=input,
723            response_type=ContextIngestion,
724        )
725
726    def search(
727        self, source: str, input: KnowledgeSourceSearchInput
728    ) -> KnowledgeSourceSearchResponse:
729        """
730        Search within a knowledge source
731        Executes a search query against the indexed documents in a single knowledge source and
732        returns matching results ranked by relevance.
733        Three search modes are supported: `"hybrid"` (default) combines vector similarity and
734        full-text scoring, `"vector"` uses embedding-based semantic search only, and
735        `"fulltext"` uses keyword-based search only. Use `"hybrid"` for most use cases;
736        prefer `"vector"` when semantic meaning matters more than exact terms.
737        Optionally restrict results to documents ingested within the last N days using
738        `recency_days`. Results are ordered by relevance score descending.
739
740        Args:
741            source: Knowledge source ID (`ksrc_...`) to search within.
742            input: Request body.
743            input.max_results: Maximum number of results to return. The platform applies its own upper bound; omit to use the default.
744            input.min_similarity: Cosine-similarity floor for the vector leg, 0.0-1.0. Candidates below it are discarded before ranking, so a high value trades recall for precision. Pass `0.0` to disable the floor when a missed match costs more than a weak one note that with no floor every query returns results, so an empty response can no longer be read as "no match". Omit to use the default.
745            input.mode: Search algorithm to use. One of `"hybrid"` (default, combines vector and full-text), `"vector"` (semantic similarity only), or `"fulltext"` (keyword matching only).
746            input.query: Natural language or keyword query string to search for.
747            input.recency_days: When set, limits results to documents ingested within the last N days. Omit to search across all documents regardless of age.
748
749        Returns:
750            Successful response
751        """
752        return self._http.request(
753            f"/api/v1/knowledge_sources/{source}/search",
754            method="POST",
755            body=input,
756            response_type=KnowledgeSourceSearchResponse,
757        )