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