archastro.platform.v1.resources.knowledge_sources

  1# Copyright (c) 2026 ArchAstro Inc. All Rights Reserved.
  2# This file is auto-generated by @archastro/sdk-generator. Do not edit.
  3# Content hash: 709d3b629164
  4
  5from __future__ import annotations
  6
  7from datetime import datetime
  8from typing import Any, Literal, Required, TypedDict
  9
 10from pydantic import BaseModel, Field
 11
 12from ...runtime.http_client import HttpClient, SyncHttpClient
 13from ...types.common import ContextIngestion, KnowledgeSource, KnowledgeSourceKindListResponse
 14
 15
 16class KnowledgeSourceCreateInput(TypedDict, total=False):
 17    "Create a knowledge source"
 18
 19    agent: str | None
 20    "Agent ID (`agt_...`) that owns this source. Mutually exclusive with `team` and `user`."
 21    metadata: dict[str, Any] | None
 22    "Arbitrary key-value metadata to attach to the source. Returned as-is on reads."
 23    org: str | None
 24    "Organization ID (`org_...`). Required for system-owned sources that have no individual owner (`team`, `user`, or `agent`)."
 25    parent_source: str | None
 26    "Parent knowledge source ID (`ksrc_...`). Use to create a child source."
 27    payload: dict[str, Any] | None
 28    "Type-specific configuration for the source. Shape depends on `type`."
 29    state: str | None
 30    'Initial state of the source. One of `"active"` (default) or `"paused"`. Paused sources do not trigger ingestion automatically.'
 31    team: str | None
 32    "Team ID (`team_...`) that owns this source. Mutually exclusive with `user` and `agent`."
 33    thread: str | None
 34    "Thread ID (`thr_...`) to associate this source with, if applicable."
 35    type: Required[str]
 36    "Knowledge source type. Must be one of the values returned by `GET /api/v1/knowledge_sources/kinds`."
 37    user: str | None
 38    "User ID (`usr_...`) that owns this source. Mutually exclusive with `team` and `agent`."
 39
 40
 41class KnowledgeSourceUpdateInput(TypedDict, total=False):
 42    "Update a knowledge source"
 43
 44    metadata: dict[str, Any] | None
 45    "Arbitrary key-value metadata to attach to the source. Replaces the entire existing `metadata` map when provided."
 46    payload: dict[str, Any] | None
 47    "Type-specific configuration to replace on the source. Shape depends on the source `type`. Replaces the entire existing `payload` when provided."
 48    state: str | None
 49    'Desired state of the source. One of `"active"` or `"paused"`. Paused sources do not trigger ingestion automatically.'
 50
 51
 52class KnowledgeSourceIngestInputContent(TypedDict, total=False):
 53    content_type: str | None
 54    'MIME type of the content, e.g. `"application/pdf"` or `"text/plain"`.'
 55    data: Required[str]
 56    'The raw document bytes. When `data_encoding` is `"base64"`, provide the base64-encoded representation of the binary content.'
 57    data_encoding: str | None
 58    'Encoding format of `data`. One of `"raw"` (default, plain text) or `"base64"` (binary content such as images or PDFs, decoded server-side before storage).'
 59    filename: str | None
 60    'Original filename for the document, e.g. `"report.pdf"`.'
 61
 62
 63class KnowledgeSourceIngestInput(TypedDict, total=False):
 64    "Trigger ingestion on a knowledge source"
 65
 66    content: KnowledgeSourceIngestInputContent | None
 67    "Inline document bytes to push to the source. Mutually exclusive with `file` and `pull`."
 68    file: str | None
 69    "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`."
 70    metadata: dict[str, Any] | None
 71    "Arbitrary key-value metadata to attach to the ingested document. Applied in push mode only; ignored when `pull: true`."
 72    pull: bool | None
 73    "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."
 74    title: str | None
 75    "Display title for the ingested document. Applied in push mode only; ignored when `pull: true`."
 76
 77
 78class KnowledgeSourceListResponseDataItem(BaseModel):
 79    agent: str | None = Field(
 80        default=None,
 81        description="ID of the agent that owns this source (`agt_...`). `null` if owned by a human user or team.",
 82    )
 83    context_installation: str | None = Field(
 84        default=None,
 85        description="ID of the context installation that provisioned this source (`cin_...`). `null` when the source was created directly rather than through an installation.",
 86    )
 87    created_at: datetime | None = Field(
 88        default=None, description="When this knowledge source was created (ISO 8601)."
 89    )
 90    id: str = Field(..., description="Knowledge source ID (`cso_...`).")
 91    metadata: dict[str, Any] | None = Field(
 92        default=None,
 93        description="Arbitrary key-value metadata attached to this source. Useful for storing caller-defined labels or references.",
 94    )
 95    org: str | None = Field(
 96        default=None,
 97        description="ID of the organization this source belongs to (`org_...`). `null` if not scoped to an org.",
 98    )
 99    parent_source: str | None = Field(
100        default=None,
101        description="ID of the parent knowledge source (`cso_...`) when this source was derived from another. `null` for top-level sources.",
102    )
103    payload: dict[str, Any] | None = Field(
104        default=None,
105        description="Type-specific configuration object. The keys depend on the source `type`; see the create endpoint for the expected shape per type.",
106    )
107    sandbox: str | None = Field(
108        default=None,
109        description="ID of the developer sandbox this source is scoped to (`sbx_...`). `null` outside sandbox contexts.",
110    )
111    state: str = Field(
112        ...,
113        description='Current lifecycle state of the source. One of `"active"` (ingestion running normally) or `"paused"` (ingestion suspended).',
114    )
115    team: str | None = Field(
116        default=None,
117        description="ID of the team that owns this source (`tea_...`). `null` if owned by a user, agent, or org.",
118    )
119    thread: str | None = Field(
120        default=None,
121        description="ID of the chat thread this source is associated with (`thr_...`). `null` when not thread-scoped.",
122    )
123    type: str = Field(
124        ...,
125        description='Source type identifier (e.g. `"gmail"`, `"github_activity"`). Determines the shape of `payload` and the ingestion behavior.',
126    )
127    updated_at: datetime | None = Field(
128        default=None, description="When this knowledge source was last modified (ISO 8601)."
129    )
130    user: str | None = Field(
131        default=None,
132        description="ID of the user that owns this source (`usr_...`). `null` if owned by a team, agent, or org.",
133    )
134
135
136class KnowledgeSourceListResponse(BaseModel):
137    """
138    Successful response
139    """
140
141    data: list[KnowledgeSourceListResponseDataItem] = Field(
142        ..., description="Array of knowledge source objects for the current page."
143    )
144    has_next: bool = Field(
145        ..., description="`true` if a subsequent page exists, `false` if this is the last page."
146    )
147    has_prev: bool = Field(
148        ..., description="`true` if a previous page exists, `false` if this is the first page."
149    )
150    page: int = Field(..., description="Current page number.")
151    page_size: int = Field(..., description="Number of results returned per page.")
152    total_entries: int = Field(
153        ..., description="Total number of knowledge sources matching the query across all pages."
154    )
155    total_pages: int = Field(..., description="Total number of pages available.")
156
157
158class AsyncKnowledgeSourceKindResource:
159    def __init__(self, http: HttpClient):
160        self._http = http
161
162    async def list(self) -> KnowledgeSourceKindListResponse:
163        """
164        List creatable knowledge source kinds
165        Returns the fixed set of knowledge source types that can be created directly via
166        `POST /api/v1/knowledge_sources`. Use this endpoint to discover valid values for the
167        `type` param before calling the create endpoint.
168        Source kinds populated by server-driven flows such as `webhook/inbound`,
169        `connectors/*/emails`, and `thread/messages` are intentionally excluded from this
170        list, as they cannot be created through the API.
171
172        Returns:
173            List of knowledge source kinds available for creation via the API.
174        """
175        return await self._http.request(
176            "/api/v1/knowledge_sources/kinds",
177            response_type=KnowledgeSourceKindListResponse,
178        )
179
180
181class AsyncKnowledgeSourceResource:
182    def __init__(self, http: HttpClient):
183        self._http = http
184        self.kinds = AsyncKnowledgeSourceKindResource(http)
185
186    async def list(
187        self,
188        *,
189        page: int | None = None,
190        page_size: int | None = None,
191        search: str | None = None,
192        type: str | None = None,
193        installation: str | None = None,
194        agent: str | None = None,
195        org: str | None = None,
196        owner_scope: Literal["any", "individual", "system"] | None = None,
197    ) -> KnowledgeSourceListResponse:
198        """
199        List knowledge sources
200        Returns a paginated list of knowledge sources visible to the authenticated caller.
201        Results are ordered by creation time descending.
202        Use the `type`, `installation`, `agent`, `org`, and `owner_scope` filters to narrow the
203        result set. Combine `owner_scope: "system"` with `org` to list org-level sources that
204        have no individual owner. Combine `owner_scope: "individual"` with `agent` to list
205        sources owned by a specific agent.
206        Pagination is page-number based. The default page size is 25.
207
208        Args:
209            page: Page number to retrieve. Defaults to 1.
210            page_size: Number of knowledge sources to return per page. Defaults to 25.
211            search: Filter sources whose type contains this string. Case-insensitive substring match.
212            type: Exact knowledge source type to filter by, e.g. `"knowledge/documents"`.
213            installation: Installation ID (`ins_...`). Returns only sources associated with this installation.
214            agent: Agent ID (`agt_...`). Returns only sources owned by or associated with this agent.
215            org: Organization ID (`org_...`). Returns only sources belonging to this organization. Combine with `owner_scope: "system"` to retrieve org-level system sources.
216            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).
217
218        Returns:
219            Successful response
220        """
221        query: dict[str, object] = {}
222        if page is not None:
223            query["page"] = page
224        if page_size is not None:
225            query["page_size"] = page_size
226        if search is not None:
227            query["search"] = search
228        if type is not None:
229            query["type"] = type
230        if installation is not None:
231            query["installation"] = installation
232        if agent is not None:
233            query["agent"] = agent
234        if org is not None:
235            query["org"] = org
236        if owner_scope is not None:
237            query["owner_scope"] = owner_scope
238        return await self._http.request(
239            "/api/v1/knowledge_sources",
240            query=query,
241            response_type=KnowledgeSourceListResponse,
242        )
243
244    async def create(self, input: KnowledgeSourceCreateInput) -> KnowledgeSource:
245        """
246        Create a knowledge source
247        Creates a new knowledge source of the requested type and returns the created object.
248        Only types listed by `GET /api/v1/knowledge_sources/kinds` may be created through this
249        endpoint. Other source types such as `webhook/inbound`, `connectors/*/emails`, and
250        `thread/messages` are provisioned automatically by server-driven flows (webhook
251        auto-provisioning, installation activation, connector lifecycle events) and cannot be
252        created directly via the API.
253        Exactly one of `team`, `user`, `agent`, or `org` must identify the owner of the new
254        source. Omit `org` when an individual owner (`team`, `user`, or `agent`) is supplied;
255        include `org` alone for org-level system-owned sources.
256
257        Args:
258            input: Request body.
259            input.agent: Agent ID (`agt_...`) that owns this source. Mutually exclusive with `team` and `user`.
260            input.metadata: Arbitrary key-value metadata to attach to the source. Returned as-is on reads.
261            input.org: Organization ID (`org_...`). Required for system-owned sources that have no individual owner (`team`, `user`, or `agent`).
262            input.parent_source: Parent knowledge source ID (`ksrc_...`). Use to create a child source.
263            input.payload: Type-specific configuration for the source. Shape depends on `type`.
264            input.state: Initial state of the source. One of `"active"` (default) or `"paused"`. Paused sources do not trigger ingestion automatically.
265            input.team: Team ID (`team_...`) that owns this source. Mutually exclusive with `user` and `agent`.
266            input.thread: Thread ID (`thr_...`) to associate this source with, if applicable.
267            input.type: Knowledge source type. Must be one of the values returned by `GET /api/v1/knowledge_sources/kinds`.
268            input.user: User ID (`usr_...`) that owns this source. Mutually exclusive with `team` and `agent`.
269
270        Returns:
271            The newly created knowledge source.
272        """
273        return await self._http.request(
274            "/api/v1/knowledge_sources",
275            method="POST",
276            body=input,
277            response_type=KnowledgeSource,
278        )
279
280    async def delete(self, source: str) -> None:
281        """
282        Delete a knowledge source
283        Permanently deletes the knowledge source identified by `source`. This action is
284        irreversible all documents, embeddings, and ingestion history associated with the
285        source are removed.
286        The authenticated caller must own the source or have sufficient permissions within its
287        parent organization. Returns `204 No Content` on success.
288
289        Args:
290            source: Knowledge source ID (`ksrc_...`) to delete.
291
292        Returns:
293            Empty response. The source has been permanently deleted.
294        """
295        await self._http.request(f"/api/v1/knowledge_sources/{source}", method="DELETE")
296
297    async def get(self, source: str) -> KnowledgeSource:
298        """
299        Retrieve a knowledge source
300        Returns the knowledge source identified by `source`. The authenticated caller must have
301        access to the source's parent organization or be the individual owner of the source.
302        Use the list endpoint to retrieve many sources at once or to discover sources by type
303        or owner.
304
305        Args:
306            source: Knowledge source ID (`ksrc_...`) to retrieve.
307
308        Returns:
309            The requested knowledge source.
310        """
311        return await self._http.request(
312            f"/api/v1/knowledge_sources/{source}",
313            response_type=KnowledgeSource,
314        )
315
316    async def update(self, source: str, input: KnowledgeSourceUpdateInput) -> KnowledgeSource:
317        """
318        Update a knowledge source
319        Updates the mutable fields of an existing knowledge source and returns the updated
320        object. Only fields provided in the request body are changed; omitted fields retain
321        their current values.
322        You can update the type-specific `payload`, the `metadata` map, and the `state`. To
323        pause a source and prevent automatic ingestion, set `state` to `"paused"`. To resume,
324        set it back to `"active"`.
325
326        Args:
327            source: Knowledge source ID (`ksrc_...`) to update.
328            input: Request body.
329            input.metadata: Arbitrary key-value metadata to attach to the source. Replaces the entire existing `metadata` map when provided.
330            input.payload: Type-specific configuration to replace on the source. Shape depends on the source `type`. Replaces the entire existing `payload` when provided.
331            input.state: Desired state of the source. One of `"active"` or `"paused"`. Paused sources do not trigger ingestion automatically.
332
333        Returns:
334            The updated knowledge source.
335        """
336        return await self._http.request(
337            f"/api/v1/knowledge_sources/{source}",
338            method="PATCH",
339            body=input,
340            response_type=KnowledgeSource,
341        )
342
343    async def ingest(self, source: str, input: KnowledgeSourceIngestInput) -> ContextIngestion:
344        """
345        Trigger ingestion on a knowledge source
346        Starts an ingestion run on the specified knowledge source and returns the ingestion
347        object. Exactly one of two modes must be chosen per request:
348        **Push mode** (`file` or `content`) available for `knowledge/documents` sources only.
349        Supply the document bytes either as a reference to an already-uploaded file (`file`) or
350        as an inline blob (`content`). The runner stores the bytes and indexes the resulting
351        document. `title` and `metadata` are persisted on the document in push mode.
352        **Pull mode** (`pull: true`) re-triggers ingestion using the source's own configured
353        data. Use this to re-scrape a `scrape/site`, re-fetch a `web/link`, or re-process a
354        `file/document`. Not valid for `knowledge/documents` (which has no upstream push new
355        bytes instead) or for source kinds populated by server-driven flows. `title` and
356        `metadata` are ignored in pull mode.
357        If an ingestion is already active for the source, the existing ingestion is returned
358        rather than creating a duplicate.
359
360        Args:
361            source: Knowledge source ID (`ksrc_...`) to ingest.
362            input: Request body.
363            input.content: Inline document bytes to push to the source. Mutually exclusive with `file` and `pull`.
364            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`.
365            input.metadata: Arbitrary key-value metadata to attach to the ingested document. Applied in push mode only; ignored when `pull: true`.
366            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.
367            input.title: Display title for the ingested document. Applied in push mode only; ignored when `pull: true`.
368
369        Returns:
370            The created ingestion, or an existing active ingestion if one is already running.
371        """
372        return await self._http.request(
373            f"/api/v1/knowledge_sources/{source}/ingest",
374            method="POST",
375            body=input,
376            response_type=ContextIngestion,
377        )
378
379
380class KnowledgeSourceKindResource:
381    def __init__(self, http: SyncHttpClient):
382        self._http = http
383
384    def list(self) -> KnowledgeSourceKindListResponse:
385        """
386        List creatable knowledge source kinds
387        Returns the fixed set of knowledge source types that can be created directly via
388        `POST /api/v1/knowledge_sources`. Use this endpoint to discover valid values for the
389        `type` param before calling the create endpoint.
390        Source kinds populated by server-driven flows such as `webhook/inbound`,
391        `connectors/*/emails`, and `thread/messages` are intentionally excluded from this
392        list, as they cannot be created through the API.
393
394        Returns:
395            List of knowledge source kinds available for creation via the API.
396        """
397        return self._http.request(
398            "/api/v1/knowledge_sources/kinds",
399            response_type=KnowledgeSourceKindListResponse,
400        )
401
402
403class KnowledgeSourceResource:
404    def __init__(self, http: SyncHttpClient):
405        self._http = http
406        self.kinds = KnowledgeSourceKindResource(http)
407
408    def list(
409        self,
410        *,
411        page: int | None = None,
412        page_size: int | None = None,
413        search: str | None = None,
414        type: str | None = None,
415        installation: str | None = None,
416        agent: str | None = None,
417        org: str | None = None,
418        owner_scope: Literal["any", "individual", "system"] | None = None,
419    ) -> KnowledgeSourceListResponse:
420        """
421        List knowledge sources
422        Returns a paginated list of knowledge sources visible to the authenticated caller.
423        Results are ordered by creation time descending.
424        Use the `type`, `installation`, `agent`, `org`, and `owner_scope` filters to narrow the
425        result set. Combine `owner_scope: "system"` with `org` to list org-level sources that
426        have no individual owner. Combine `owner_scope: "individual"` with `agent` to list
427        sources owned by a specific agent.
428        Pagination is page-number based. The default page size is 25.
429
430        Args:
431            page: Page number to retrieve. Defaults to 1.
432            page_size: Number of knowledge sources to return per page. Defaults to 25.
433            search: Filter sources whose type contains this string. Case-insensitive substring match.
434            type: Exact knowledge source type to filter by, e.g. `"knowledge/documents"`.
435            installation: Installation ID (`ins_...`). Returns only sources associated with this installation.
436            agent: Agent ID (`agt_...`). Returns only sources owned by or associated with this agent.
437            org: Organization ID (`org_...`). Returns only sources belonging to this organization. Combine with `owner_scope: "system"` to retrieve org-level system sources.
438            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).
439
440        Returns:
441            Successful response
442        """
443        query: dict[str, object] = {}
444        if page is not None:
445            query["page"] = page
446        if page_size is not None:
447            query["page_size"] = page_size
448        if search is not None:
449            query["search"] = search
450        if type is not None:
451            query["type"] = type
452        if installation is not None:
453            query["installation"] = installation
454        if agent is not None:
455            query["agent"] = agent
456        if org is not None:
457            query["org"] = org
458        if owner_scope is not None:
459            query["owner_scope"] = owner_scope
460        return self._http.request(
461            "/api/v1/knowledge_sources",
462            query=query,
463            response_type=KnowledgeSourceListResponse,
464        )
465
466    def create(self, input: KnowledgeSourceCreateInput) -> KnowledgeSource:
467        """
468        Create a knowledge source
469        Creates a new knowledge source of the requested type and returns the created object.
470        Only types listed by `GET /api/v1/knowledge_sources/kinds` may be created through this
471        endpoint. Other source types such as `webhook/inbound`, `connectors/*/emails`, and
472        `thread/messages` are provisioned automatically by server-driven flows (webhook
473        auto-provisioning, installation activation, connector lifecycle events) and cannot be
474        created directly via the API.
475        Exactly one of `team`, `user`, `agent`, or `org` must identify the owner of the new
476        source. Omit `org` when an individual owner (`team`, `user`, or `agent`) is supplied;
477        include `org` alone for org-level system-owned sources.
478
479        Args:
480            input: Request body.
481            input.agent: Agent ID (`agt_...`) that owns this source. Mutually exclusive with `team` and `user`.
482            input.metadata: Arbitrary key-value metadata to attach to the source. Returned as-is on reads.
483            input.org: Organization ID (`org_...`). Required for system-owned sources that have no individual owner (`team`, `user`, or `agent`).
484            input.parent_source: Parent knowledge source ID (`ksrc_...`). Use to create a child source.
485            input.payload: Type-specific configuration for the source. Shape depends on `type`.
486            input.state: Initial state of the source. One of `"active"` (default) or `"paused"`. Paused sources do not trigger ingestion automatically.
487            input.team: Team ID (`team_...`) that owns this source. Mutually exclusive with `user` and `agent`.
488            input.thread: Thread ID (`thr_...`) to associate this source with, if applicable.
489            input.type: Knowledge source type. Must be one of the values returned by `GET /api/v1/knowledge_sources/kinds`.
490            input.user: User ID (`usr_...`) that owns this source. Mutually exclusive with `team` and `agent`.
491
492        Returns:
493            The newly created knowledge source.
494        """
495        return self._http.request(
496            "/api/v1/knowledge_sources",
497            method="POST",
498            body=input,
499            response_type=KnowledgeSource,
500        )
501
502    def delete(self, source: str) -> None:
503        """
504        Delete a knowledge source
505        Permanently deletes the knowledge source identified by `source`. This action is
506        irreversible all documents, embeddings, and ingestion history associated with the
507        source are removed.
508        The authenticated caller must own the source or have sufficient permissions within its
509        parent organization. Returns `204 No Content` on success.
510
511        Args:
512            source: Knowledge source ID (`ksrc_...`) to delete.
513
514        Returns:
515            Empty response. The source has been permanently deleted.
516        """
517        self._http.request(f"/api/v1/knowledge_sources/{source}", method="DELETE")
518
519    def get(self, source: str) -> KnowledgeSource:
520        """
521        Retrieve a knowledge source
522        Returns the knowledge source identified by `source`. The authenticated caller must have
523        access to the source's parent organization or be the individual owner of the source.
524        Use the list endpoint to retrieve many sources at once or to discover sources by type
525        or owner.
526
527        Args:
528            source: Knowledge source ID (`ksrc_...`) to retrieve.
529
530        Returns:
531            The requested knowledge source.
532        """
533        return self._http.request(
534            f"/api/v1/knowledge_sources/{source}",
535            response_type=KnowledgeSource,
536        )
537
538    def update(self, source: str, input: KnowledgeSourceUpdateInput) -> KnowledgeSource:
539        """
540        Update a knowledge source
541        Updates the mutable fields of an existing knowledge source and returns the updated
542        object. Only fields provided in the request body are changed; omitted fields retain
543        their current values.
544        You can update the type-specific `payload`, the `metadata` map, and the `state`. To
545        pause a source and prevent automatic ingestion, set `state` to `"paused"`. To resume,
546        set it back to `"active"`.
547
548        Args:
549            source: Knowledge source ID (`ksrc_...`) to update.
550            input: Request body.
551            input.metadata: Arbitrary key-value metadata to attach to the source. Replaces the entire existing `metadata` map when provided.
552            input.payload: Type-specific configuration to replace on the source. Shape depends on the source `type`. Replaces the entire existing `payload` when provided.
553            input.state: Desired state of the source. One of `"active"` or `"paused"`. Paused sources do not trigger ingestion automatically.
554
555        Returns:
556            The updated knowledge source.
557        """
558        return self._http.request(
559            f"/api/v1/knowledge_sources/{source}",
560            method="PATCH",
561            body=input,
562            response_type=KnowledgeSource,
563        )
564
565    def ingest(self, source: str, input: KnowledgeSourceIngestInput) -> ContextIngestion:
566        """
567        Trigger ingestion on a knowledge source
568        Starts an ingestion run on the specified knowledge source and returns the ingestion
569        object. Exactly one of two modes must be chosen per request:
570        **Push mode** (`file` or `content`) available for `knowledge/documents` sources only.
571        Supply the document bytes either as a reference to an already-uploaded file (`file`) or
572        as an inline blob (`content`). The runner stores the bytes and indexes the resulting
573        document. `title` and `metadata` are persisted on the document in push mode.
574        **Pull mode** (`pull: true`) re-triggers ingestion using the source's own configured
575        data. Use this to re-scrape a `scrape/site`, re-fetch a `web/link`, or re-process a
576        `file/document`. Not valid for `knowledge/documents` (which has no upstream push new
577        bytes instead) or for source kinds populated by server-driven flows. `title` and
578        `metadata` are ignored in pull mode.
579        If an ingestion is already active for the source, the existing ingestion is returned
580        rather than creating a duplicate.
581
582        Args:
583            source: Knowledge source ID (`ksrc_...`) to ingest.
584            input: Request body.
585            input.content: Inline document bytes to push to the source. Mutually exclusive with `file` and `pull`.
586            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`.
587            input.metadata: Arbitrary key-value metadata to attach to the ingested document. Applied in push mode only; ignored when `pull: true`.
588            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.
589            input.title: Display title for the ingested document. Applied in push mode only; ignored when `pull: true`.
590
591        Returns:
592            The created ingestion, or an existing active ingestion if one is already running.
593        """
594        return self._http.request(
595            f"/api/v1/knowledge_sources/{source}/ingest",
596            method="POST",
597            body=input,
598            response_type=ContextIngestion,
599        )