archastro.platform.v1.resources.knowledge_documents 

  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: 87457d674261
  4
  5from __future__ import annotations
  6
  7import builtins
  8from datetime import datetime
  9from typing import Any, Required, TypedDict
 10
 11from pydantic import BaseModel, Field
 12
 13from ...runtime.http_client import HttpClient, SyncHttpClient
 14from ...types.common import ContextDocument, ContextDocumentContent, ContextIngestion
 15
 16
 17class KnowledgeDocumentUpdateInputContent(TypedDict, total=False):
 18    content_type: str | None
 19    'MIME type of the replacement content, such as `"text/plain"`.'
 20    data: Required[str]
 21    "The replacement document bytes."
 22    data_encoding: str | None
 23    'Encoding of `data`: `"raw"` (default) or `"base64"`.'
 24    filename: str | None
 25    "Original filename for the replacement content."
 26
 27
 28class KnowledgeDocumentUpdateInput(TypedDict, total=False):
 29    "Update a context document"
 30
 31    content: KnowledgeDocumentUpdateInputContent | None
 32    "Inline replacement bytes. Mutually exclusive with `file`."
 33    file: str | None
 34    "ID of an already-uploaded file (`fil_...`). Mutually exclusive with `content`."
 35    metadata: dict[str, Any] | None
 36    "Replacement metadata map. Omit to retain the current metadata."
 37    title: str | None
 38    "Replacement display title. Omit to retain the current title."
 39
 40
 41class KnowledgeDocumentListResponseDataItem(BaseModel):
 42    agent: str | None = Field(
 43        default=None,
 44        description="ID of the agent that owns this document (`agi_...`). `null` if owned by a user or team.",
 45    )
 46    content_hash: str | None = Field(
 47        default=None,
 48        description="Lowercase-hex sha256 of the document's full text, covering content only not `title` or `metadata`. Compare it against a hash of your local copy to decide whether the document needs re-ingesting, without fetching `/content`. `null` for documents ingested before this field existed; it is not backfilled.",
 49    )
 50    created_at: datetime | None = Field(
 51        default=None, description="When the document was created (ISO 8601)."
 52    )
 53    file: str | None = Field(
 54        default=None,
 55        description="ID of the backing storage file (`fil_...`) when the document is file-backed. `null` for inline documents.",
 56    )
 57    id: str = Field(..., description="Context document ID (`cdo_...`).")
 58    metadata: dict[str, Any] | None = Field(
 59        default=None,
 60        description="Arbitrary key-value metadata attached to the document. Shape varies by source type.",
 61    )
 62    source: str | None = Field(
 63        default=None, description="ID of the context source this document belongs to (`cso_...`)."
 64    )
 65    team: str | None = Field(
 66        default=None,
 67        description="ID of the team that owns this document (`tem_...`). `null` if owned by a user or agent.",
 68    )
 69    title: str | None = Field(
 70        default=None,
 71        description="Human-readable display title of the document. `null` if no title has been set.",
 72    )
 73    total_lines: int | None = Field(
 74        default=None,
 75        description="Total number of lines in the document's text content. `0` if the document has no content.",
 76    )
 77    total_size: int | None = Field(
 78        default=None,
 79        description="Total byte size of the document's text content. `0` if the document has no content.",
 80    )
 81    updated_at: datetime | None = Field(
 82        default=None, description="When the document was last modified (ISO 8601)."
 83    )
 84    user: str | None = Field(
 85        default=None,
 86        description="ID of the user that owns this document (`usr_...`). `null` if owned by a team or agent.",
 87    )
 88
 89
 90class KnowledgeDocumentListResponse(BaseModel):
 91    """
 92    Successful response
 93    """
 94
 95    data: list[KnowledgeDocumentListResponseDataItem] = Field(
 96        ..., description="Array of context document objects for the current page."
 97    )
 98    has_next: bool = Field(
 99        ..., description="`true` if a subsequent page exists; `false` when this is the last page."
100    )
101    has_prev: bool = Field(
102        ..., description="`true` if a previous page exists; `false` when this is the first page."
103    )
104    page: int = Field(..., description="The current page number.")
105    page_size: int = Field(..., description="Maximum number of documents returned per page.")
106    total_entries: int = Field(
107        ..., description="Total number of documents matching the applied filters across all pages."
108    )
109    total_pages: int = Field(
110        ..., description="Total number of pages given the current `page_size`."
111    )
112
113
114class AsyncKnowledgeDocumentResource:
115    def __init__(self, http: HttpClient):
116        self._http = http
117
118    async def list(
119        self,
120        *,
121        page: int | None = None,
122        page_size: int | None = None,
123        q: str | None = None,
124        source: builtins.list[str] | None = None,
125        installation: builtins.list[str] | None = None,
126        agent: builtins.list[str] | None = None,
127    ) -> KnowledgeDocumentListResponse:
128        """
129        List context documents
130        Returns a paginated list of context documents visible to the authenticated
131        caller within the scoped app. Results are ordered by creation time
132        descending.
133        Use `q` for a case-insensitive title prefix search. Use `source`,
134        `installation`, or `agent` to narrow results to documents belonging to
135        specific sources, installations, or agents. Multiple values within each
136        filter are treated as OR conditions. Filters may be combined.
137        The response includes page-level metadata so you can navigate through
138        large result sets without cursor tokens.
139
140        Args:
141            page: Page number to return. Defaults to 1.
142            page_size: Number of documents per page. Defaults to 25.
143            q: Case-insensitive prefix filter applied to the document title.
144            source: Return only documents belonging to these source IDs (`cso_...`). Multiple values are OR'd.
145            installation: Return only documents belonging to these installation IDs. Multiple values are OR'd.
146            agent: Return only documents owned by these agent IDs. Multiple values are OR'd.
147
148        Returns:
149            Successful response
150        """
151        query: dict[str, object] = {}
152        if page is not None:
153            query["page"] = page
154        if page_size is not None:
155            query["page_size"] = page_size
156        if q is not None:
157            query["q"] = q
158        if source is not None:
159            query["source"] = source
160        if installation is not None:
161            query["installation"] = installation
162        if agent is not None:
163            query["agent"] = agent
164        return await self._http.request(
165            "/api/v1/knowledge_documents",
166            query=query,
167            response_type=KnowledgeDocumentListResponse,
168        )
169
170    async def delete(self, document: str) -> None:
171        """
172        Delete a context document
173        Permanently deletes a context document and all of its associated chunk
174        items. This action is irreversible.
175        The backing storage file, if any, is not deleted storage files can be
176        shared across multiple documents and are cleaned up separately by the
177        platform's storage garbage collector. The caller must be authenticated
178        and the request must be scoped to the app that owns the document.
179
180        Args:
181            document: Document ID (`cdo_...`) to delete.
182
183        Returns:
184            Empty body. Returns HTTP 204 on success.
185        """
186        await self._http.request(f"/api/v1/knowledge_documents/{document}", method="DELETE")
187
188    async def get(self, document: str) -> ContextDocument:
189        """
190        Retrieve a context document
191        Returns a single context document identified by its ID. The response
192        includes document metadata such as title, size, and ownership fields,
193        but not the document's text content. To read the full or partial content,
194        use the content endpoint.
195        The caller must be authenticated and the request must be scoped to the
196        app that owns the document.
197
198        Args:
199            document: Document ID (`cdo_...`) to retrieve.
200
201        Returns:
202            The requested context document's metadata.
203        """
204        return await self._http.request(
205            f"/api/v1/knowledge_documents/{document}",
206            response_type=ContextDocument,
207        )
208
209    async def update(self, document: str, input: KnowledgeDocumentUpdateInput) -> ContextIngestion:
210        """
211        Update a context document
212        Replaces one document's content while preserving its document ID. The update
213        runs asynchronously through the document's source pipeline: bytes are
214        extracted and chunked, the prior chunks are replaced atomically, and fresh
215        document and chunk embeddings are queued.
216        Supply exactly one of `file` or `content`. Omitted `title` and `metadata`
217        retain their current values. The response is an ingestion that can be polled
218        at `GET /api/v1/knowledge_ingestions/:id` until it reaches `succeeded` or
219        `failed`. `succeeded` means the replacement content and full-text indexes are
220        committed and the embedding refresh is durably queued; vector computation
221        continues in the retryable embedding worker.
222
223        Args:
224            document: Document ID (`cdo_...`) to update.
225            input: Request body.
226            input.content: Inline replacement bytes. Mutually exclusive with `file`.
227            input.file: ID of an already-uploaded file (`fil_...`). Mutually exclusive with `content`.
228            input.metadata: Replacement metadata map. Omit to retain the current metadata.
229            input.title: Replacement display title. Omit to retain the current title.
230
231        Returns:
232            The ingestion performing the document update.
233        """
234        return await self._http.request(
235            f"/api/v1/knowledge_documents/{document}",
236            method="PATCH",
237            body=input,
238            response_type=ContextIngestion,
239        )
240
241    async def content(
242        self,
243        document: str,
244        *,
245        offset: int | None = None,
246        limit: int | None = None,
247        unit: str | None = None,
248    ) -> ContextDocumentContent:
249        """
250        Retrieve a context document's content
251        Returns the full text of a context document, or a slice of it when
252        `offset`, `limit`, and `unit` are supplied. Both file-backed and inline
253        documents are supported; the response shape is the same in either case.
254        When slicing, set `unit` to `"lines"` (default) or `"bytes"`. A line-based
255        slice uses a 1-indexed `offset`; a byte-based slice uses a 0-indexed
256        `offset`. If you omit `offset`, the full document text is returned and the
257        slice-specific response fields (`unit`, `offset`, `limit`, `start_line`,
258        `end_line`, `start_byte`, `end_byte`) are absent.
259        The caller must be authenticated and the request must be scoped to an app
260        that owns the document.
261
262        Args:
263            document: Document ID (`cdo_...`) whose content to retrieve.
264            offset: Starting position for a content slice. When `unit` is `"lines"`, this is a 1-indexed line number. When `unit` is `"bytes"`, this is a 0-indexed byte offset. Omit to return the full document.
265            limit: Maximum number of units to return when slicing. Defaults to 200 when `unit` is `"lines"` and 8192 when `unit` is `"bytes"`.
266            unit: Unit to use for `offset` and `limit`. One of `"lines"` (default) or `"bytes"`.
267
268        Returns:
269            The document's content, optionally sliced by offset and limit.
270        """
271        query: dict[str, object] = {}
272        if offset is not None:
273            query["offset"] = offset
274        if limit is not None:
275            query["limit"] = limit
276        if unit is not None:
277            query["unit"] = unit
278        return await self._http.request(
279            f"/api/v1/knowledge_documents/{document}/content",
280            query=query,
281            response_type=ContextDocumentContent,
282        )
283
284
285class KnowledgeDocumentResource:
286    def __init__(self, http: SyncHttpClient):
287        self._http = http
288
289    def list(
290        self,
291        *,
292        page: int | None = None,
293        page_size: int | None = None,
294        q: str | None = None,
295        source: builtins.list[str] | None = None,
296        installation: builtins.list[str] | None = None,
297        agent: builtins.list[str] | None = None,
298    ) -> KnowledgeDocumentListResponse:
299        """
300        List context documents
301        Returns a paginated list of context documents visible to the authenticated
302        caller within the scoped app. Results are ordered by creation time
303        descending.
304        Use `q` for a case-insensitive title prefix search. Use `source`,
305        `installation`, or `agent` to narrow results to documents belonging to
306        specific sources, installations, or agents. Multiple values within each
307        filter are treated as OR conditions. Filters may be combined.
308        The response includes page-level metadata so you can navigate through
309        large result sets without cursor tokens.
310
311        Args:
312            page: Page number to return. Defaults to 1.
313            page_size: Number of documents per page. Defaults to 25.
314            q: Case-insensitive prefix filter applied to the document title.
315            source: Return only documents belonging to these source IDs (`cso_...`). Multiple values are OR'd.
316            installation: Return only documents belonging to these installation IDs. Multiple values are OR'd.
317            agent: Return only documents owned by these agent IDs. Multiple values are OR'd.
318
319        Returns:
320            Successful response
321        """
322        query: dict[str, object] = {}
323        if page is not None:
324            query["page"] = page
325        if page_size is not None:
326            query["page_size"] = page_size
327        if q is not None:
328            query["q"] = q
329        if source is not None:
330            query["source"] = source
331        if installation is not None:
332            query["installation"] = installation
333        if agent is not None:
334            query["agent"] = agent
335        return self._http.request(
336            "/api/v1/knowledge_documents",
337            query=query,
338            response_type=KnowledgeDocumentListResponse,
339        )
340
341    def delete(self, document: str) -> None:
342        """
343        Delete a context document
344        Permanently deletes a context document and all of its associated chunk
345        items. This action is irreversible.
346        The backing storage file, if any, is not deleted storage files can be
347        shared across multiple documents and are cleaned up separately by the
348        platform's storage garbage collector. The caller must be authenticated
349        and the request must be scoped to the app that owns the document.
350
351        Args:
352            document: Document ID (`cdo_...`) to delete.
353
354        Returns:
355            Empty body. Returns HTTP 204 on success.
356        """
357        self._http.request(f"/api/v1/knowledge_documents/{document}", method="DELETE")
358
359    def get(self, document: str) -> ContextDocument:
360        """
361        Retrieve a context document
362        Returns a single context document identified by its ID. The response
363        includes document metadata such as title, size, and ownership fields,
364        but not the document's text content. To read the full or partial content,
365        use the content endpoint.
366        The caller must be authenticated and the request must be scoped to the
367        app that owns the document.
368
369        Args:
370            document: Document ID (`cdo_...`) to retrieve.
371
372        Returns:
373            The requested context document's metadata.
374        """
375        return self._http.request(
376            f"/api/v1/knowledge_documents/{document}",
377            response_type=ContextDocument,
378        )
379
380    def update(self, document: str, input: KnowledgeDocumentUpdateInput) -> ContextIngestion:
381        """
382        Update a context document
383        Replaces one document's content while preserving its document ID. The update
384        runs asynchronously through the document's source pipeline: bytes are
385        extracted and chunked, the prior chunks are replaced atomically, and fresh
386        document and chunk embeddings are queued.
387        Supply exactly one of `file` or `content`. Omitted `title` and `metadata`
388        retain their current values. The response is an ingestion that can be polled
389        at `GET /api/v1/knowledge_ingestions/:id` until it reaches `succeeded` or
390        `failed`. `succeeded` means the replacement content and full-text indexes are
391        committed and the embedding refresh is durably queued; vector computation
392        continues in the retryable embedding worker.
393
394        Args:
395            document: Document ID (`cdo_...`) to update.
396            input: Request body.
397            input.content: Inline replacement bytes. Mutually exclusive with `file`.
398            input.file: ID of an already-uploaded file (`fil_...`). Mutually exclusive with `content`.
399            input.metadata: Replacement metadata map. Omit to retain the current metadata.
400            input.title: Replacement display title. Omit to retain the current title.
401
402        Returns:
403            The ingestion performing the document update.
404        """
405        return self._http.request(
406            f"/api/v1/knowledge_documents/{document}",
407            method="PATCH",
408            body=input,
409            response_type=ContextIngestion,
410        )
411
412    def content(
413        self,
414        document: str,
415        *,
416        offset: int | None = None,
417        limit: int | None = None,
418        unit: str | None = None,
419    ) -> ContextDocumentContent:
420        """
421        Retrieve a context document's content
422        Returns the full text of a context document, or a slice of it when
423        `offset`, `limit`, and `unit` are supplied. Both file-backed and inline
424        documents are supported; the response shape is the same in either case.
425        When slicing, set `unit` to `"lines"` (default) or `"bytes"`. A line-based
426        slice uses a 1-indexed `offset`; a byte-based slice uses a 0-indexed
427        `offset`. If you omit `offset`, the full document text is returned and the
428        slice-specific response fields (`unit`, `offset`, `limit`, `start_line`,
429        `end_line`, `start_byte`, `end_byte`) are absent.
430        The caller must be authenticated and the request must be scoped to an app
431        that owns the document.
432
433        Args:
434            document: Document ID (`cdo_...`) whose content to retrieve.
435            offset: Starting position for a content slice. When `unit` is `"lines"`, this is a 1-indexed line number. When `unit` is `"bytes"`, this is a 0-indexed byte offset. Omit to return the full document.
436            limit: Maximum number of units to return when slicing. Defaults to 200 when `unit` is `"lines"` and 8192 when `unit` is `"bytes"`.
437            unit: Unit to use for `offset` and `limit`. One of `"lines"` (default) or `"bytes"`.
438
439        Returns:
440            The document's content, optionally sliced by offset and limit.
441        """
442        query: dict[str, object] = {}
443        if offset is not None:
444            query["offset"] = offset
445        if limit is not None:
446            query["limit"] = limit
447        if unit is not None:
448            query["unit"] = unit
449        return self._http.request(
450            f"/api/v1/knowledge_documents/{document}/content",
451            query=query,
452            response_type=ContextDocumentContent,
453        )
class KnowledgeDocumentUpdateInputContent(typing.TypedDict): 
18class KnowledgeDocumentUpdateInputContent(TypedDict, total=False):
19    content_type: str | None
20    'MIME type of the replacement content, such as `"text/plain"`.'
21    data: Required[str]
22    "The replacement document bytes."
23    data_encoding: str | None
24    'Encoding of `data`: `"raw"` (default) or `"base64"`.'
25    filename: str | None
26    "Original filename for the replacement content."
content_type: str | None

MIME type of the replacement content, such as "text/plain".

data: Required[str]

The replacement document bytes.

data_encoding: str | None

Encoding of data: "raw" (default) or "base64".

filename: str | None

Original filename for the replacement content.

class KnowledgeDocumentUpdateInput(typing.TypedDict): 
29class KnowledgeDocumentUpdateInput(TypedDict, total=False):
30    "Update a context document"
31
32    content: KnowledgeDocumentUpdateInputContent | None
33    "Inline replacement bytes. Mutually exclusive with `file`."
34    file: str | None
35    "ID of an already-uploaded file (`fil_...`). Mutually exclusive with `content`."
36    metadata: dict[str, Any] | None
37    "Replacement metadata map. Omit to retain the current metadata."
38    title: str | None
39    "Replacement display title. Omit to retain the current title."

Update a context document

content: KnowledgeDocumentUpdateInputContent | None

Inline replacement bytes. Mutually exclusive with file.

file: str | None

ID of an already-uploaded file (fil_...). Mutually exclusive with content.

metadata: dict[str, typing.Any] | None

Replacement metadata map. Omit to retain the current metadata.

title: str | None

Replacement display title. Omit to retain the current title.

class KnowledgeDocumentListResponseDataItem(pydantic.main.BaseModel): 
42class KnowledgeDocumentListResponseDataItem(BaseModel):
43    agent: str | None = Field(
44        default=None,
45        description="ID of the agent that owns this document (`agi_...`). `null` if owned by a user or team.",
46    )
47    content_hash: str | None = Field(
48        default=None,
49        description="Lowercase-hex sha256 of the document's full text, covering content only not `title` or `metadata`. Compare it against a hash of your local copy to decide whether the document needs re-ingesting, without fetching `/content`. `null` for documents ingested before this field existed; it is not backfilled.",
50    )
51    created_at: datetime | None = Field(
52        default=None, description="When the document was created (ISO 8601)."
53    )
54    file: str | None = Field(
55        default=None,
56        description="ID of the backing storage file (`fil_...`) when the document is file-backed. `null` for inline documents.",
57    )
58    id: str = Field(..., description="Context document ID (`cdo_...`).")
59    metadata: dict[str, Any] | None = Field(
60        default=None,
61        description="Arbitrary key-value metadata attached to the document. Shape varies by source type.",
62    )
63    source: str | None = Field(
64        default=None, description="ID of the context source this document belongs to (`cso_...`)."
65    )
66    team: str | None = Field(
67        default=None,
68        description="ID of the team that owns this document (`tem_...`). `null` if owned by a user or agent.",
69    )
70    title: str | None = Field(
71        default=None,
72        description="Human-readable display title of the document. `null` if no title has been set.",
73    )
74    total_lines: int | None = Field(
75        default=None,
76        description="Total number of lines in the document's text content. `0` if the document has no content.",
77    )
78    total_size: int | None = Field(
79        default=None,
80        description="Total byte size of the document's text content. `0` if the document has no content.",
81    )
82    updated_at: datetime | None = Field(
83        default=None, description="When the document was last modified (ISO 8601)."
84    )
85    user: str | None = Field(
86        default=None,
87        description="ID of the user that owns this document (`usr_...`). `null` if owned by a team or agent.",
88    )

!!! abstract "Usage Documentation" Models

A base class for creating Pydantic models.

Attributes:
  • __class_vars__: The names of the class variables defined on the model.
  • __private_attributes__: Metadata about the private attributes of the model.
  • __signature__: The synthesized __init__ [Signature][inspect.Signature] of the model.
  • __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
  • __pydantic_core_schema__: The core schema of the model.
  • __pydantic_custom_init__: Whether the model has a custom __init__ function.
  • __pydantic_decorators__: Metadata containing the decorators defined on the model. This replaces Model.__validators__ and Model.__root_validators__ from Pydantic V1.
  • __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models. The origin and args items map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and the parameter item maps to the __parameter__ attribute of generic classes.
  • __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
  • __pydantic_post_init__: The name of the post-init method for the model, if defined.
  • __pydantic_root_model__: Whether the model is a [RootModel][pydantic.root_model.RootModel].
  • __pydantic_serializer__: The pydantic-core SchemaSerializer used to dump instances of the model.
  • __pydantic_validator__: The pydantic-core SchemaValidator used to validate instances of the model.
  • __pydantic_fields__: A dictionary of field names and their corresponding [FieldInfo][pydantic.fields.FieldInfo] objects.
  • __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects.
  • __pydantic_extra__: A dictionary containing extra values, if [extra][pydantic.config.ConfigDict.extra] is set to 'allow'.
  • __pydantic_fields_set__: The names of fields explicitly set during instantiation.
  • __pydantic_private__: Values of private attributes set on the model instance.
agent: str | None = None

ID of the agent that owns this document (agi_...). null if owned by a user or team.

content_hash: str | None = None

Lowercase-hex sha256 of the document's full text, covering content only not title or metadata. Compare it against a hash of your local copy to decide whether the document needs re-ingesting, without fetching /content. null for documents ingested before this field existed; it is not backfilled.

created_at: datetime.datetime | None = None

When the document was created (ISO 8601).

file: str | None = None

ID of the backing storage file (fil_...) when the document is file-backed. null for inline documents.

id: str = PydanticUndefined

Context document ID (cdo_...).

metadata: dict[str, typing.Any] | None = None

Arbitrary key-value metadata attached to the document. Shape varies by source type.

source: str | None = None

ID of the context source this document belongs to (cso_...).

team: str | None = None

ID of the team that owns this document (tem_...). null if owned by a user or agent.

title: str | None = None

Human-readable display title of the document. null if no title has been set.

total_lines: int | None = None

Total number of lines in the document's text content. 0 if the document has no content.

total_size: int | None = None

Total byte size of the document's text content. 0 if the document has no content.

updated_at: datetime.datetime | None = None

When the document was last modified (ISO 8601).

user: str | None = None

ID of the user that owns this document (usr_...). null if owned by a team or agent.

class KnowledgeDocumentListResponse(pydantic.main.BaseModel): 
 91class KnowledgeDocumentListResponse(BaseModel):
 92    """
 93    Successful response
 94    """
 95
 96    data: list[KnowledgeDocumentListResponseDataItem] = Field(
 97        ..., description="Array of context document objects for the current page."
 98    )
 99    has_next: bool = Field(
100        ..., description="`true` if a subsequent page exists; `false` when this is the last page."
101    )
102    has_prev: bool = Field(
103        ..., description="`true` if a previous page exists; `false` when this is the first page."
104    )
105    page: int = Field(..., description="The current page number.")
106    page_size: int = Field(..., description="Maximum number of documents returned per page.")
107    total_entries: int = Field(
108        ..., description="Total number of documents matching the applied filters across all pages."
109    )
110    total_pages: int = Field(
111        ..., description="Total number of pages given the current `page_size`."
112    )

Successful response

data: list[KnowledgeDocumentListResponseDataItem] = PydanticUndefined

Array of context document objects for the current page.

has_next: bool = PydanticUndefined

true if a subsequent page exists; false when this is the last page.

has_prev: bool = PydanticUndefined

true if a previous page exists; false when this is the first page.

page: int = PydanticUndefined

The current page number.

page_size: int = PydanticUndefined

Maximum number of documents returned per page.

total_entries: int = PydanticUndefined

Total number of documents matching the applied filters across all pages.

total_pages: int = PydanticUndefined

Total number of pages given the current page_size.

class AsyncKnowledgeDocumentResource: 
115class AsyncKnowledgeDocumentResource:
116    def __init__(self, http: HttpClient):
117        self._http = http
118
119    async def list(
120        self,
121        *,
122        page: int | None = None,
123        page_size: int | None = None,
124        q: str | None = None,
125        source: builtins.list[str] | None = None,
126        installation: builtins.list[str] | None = None,
127        agent: builtins.list[str] | None = None,
128    ) -> KnowledgeDocumentListResponse:
129        """
130        List context documents
131        Returns a paginated list of context documents visible to the authenticated
132        caller within the scoped app. Results are ordered by creation time
133        descending.
134        Use `q` for a case-insensitive title prefix search. Use `source`,
135        `installation`, or `agent` to narrow results to documents belonging to
136        specific sources, installations, or agents. Multiple values within each
137        filter are treated as OR conditions. Filters may be combined.
138        The response includes page-level metadata so you can navigate through
139        large result sets without cursor tokens.
140
141        Args:
142            page: Page number to return. Defaults to 1.
143            page_size: Number of documents per page. Defaults to 25.
144            q: Case-insensitive prefix filter applied to the document title.
145            source: Return only documents belonging to these source IDs (`cso_...`). Multiple values are OR'd.
146            installation: Return only documents belonging to these installation IDs. Multiple values are OR'd.
147            agent: Return only documents owned by these agent IDs. Multiple values are OR'd.
148
149        Returns:
150            Successful response
151        """
152        query: dict[str, object] = {}
153        if page is not None:
154            query["page"] = page
155        if page_size is not None:
156            query["page_size"] = page_size
157        if q is not None:
158            query["q"] = q
159        if source is not None:
160            query["source"] = source
161        if installation is not None:
162            query["installation"] = installation
163        if agent is not None:
164            query["agent"] = agent
165        return await self._http.request(
166            "/api/v1/knowledge_documents",
167            query=query,
168            response_type=KnowledgeDocumentListResponse,
169        )
170
171    async def delete(self, document: str) -> None:
172        """
173        Delete a context document
174        Permanently deletes a context document and all of its associated chunk
175        items. This action is irreversible.
176        The backing storage file, if any, is not deleted storage files can be
177        shared across multiple documents and are cleaned up separately by the
178        platform's storage garbage collector. The caller must be authenticated
179        and the request must be scoped to the app that owns the document.
180
181        Args:
182            document: Document ID (`cdo_...`) to delete.
183
184        Returns:
185            Empty body. Returns HTTP 204 on success.
186        """
187        await self._http.request(f"/api/v1/knowledge_documents/{document}", method="DELETE")
188
189    async def get(self, document: str) -> ContextDocument:
190        """
191        Retrieve a context document
192        Returns a single context document identified by its ID. The response
193        includes document metadata such as title, size, and ownership fields,
194        but not the document's text content. To read the full or partial content,
195        use the content endpoint.
196        The caller must be authenticated and the request must be scoped to the
197        app that owns the document.
198
199        Args:
200            document: Document ID (`cdo_...`) to retrieve.
201
202        Returns:
203            The requested context document's metadata.
204        """
205        return await self._http.request(
206            f"/api/v1/knowledge_documents/{document}",
207            response_type=ContextDocument,
208        )
209
210    async def update(self, document: str, input: KnowledgeDocumentUpdateInput) -> ContextIngestion:
211        """
212        Update a context document
213        Replaces one document's content while preserving its document ID. The update
214        runs asynchronously through the document's source pipeline: bytes are
215        extracted and chunked, the prior chunks are replaced atomically, and fresh
216        document and chunk embeddings are queued.
217        Supply exactly one of `file` or `content`. Omitted `title` and `metadata`
218        retain their current values. The response is an ingestion that can be polled
219        at `GET /api/v1/knowledge_ingestions/:id` until it reaches `succeeded` or
220        `failed`. `succeeded` means the replacement content and full-text indexes are
221        committed and the embedding refresh is durably queued; vector computation
222        continues in the retryable embedding worker.
223
224        Args:
225            document: Document ID (`cdo_...`) to update.
226            input: Request body.
227            input.content: Inline replacement bytes. Mutually exclusive with `file`.
228            input.file: ID of an already-uploaded file (`fil_...`). Mutually exclusive with `content`.
229            input.metadata: Replacement metadata map. Omit to retain the current metadata.
230            input.title: Replacement display title. Omit to retain the current title.
231
232        Returns:
233            The ingestion performing the document update.
234        """
235        return await self._http.request(
236            f"/api/v1/knowledge_documents/{document}",
237            method="PATCH",
238            body=input,
239            response_type=ContextIngestion,
240        )
241
242    async def content(
243        self,
244        document: str,
245        *,
246        offset: int | None = None,
247        limit: int | None = None,
248        unit: str | None = None,
249    ) -> ContextDocumentContent:
250        """
251        Retrieve a context document's content
252        Returns the full text of a context document, or a slice of it when
253        `offset`, `limit`, and `unit` are supplied. Both file-backed and inline
254        documents are supported; the response shape is the same in either case.
255        When slicing, set `unit` to `"lines"` (default) or `"bytes"`. A line-based
256        slice uses a 1-indexed `offset`; a byte-based slice uses a 0-indexed
257        `offset`. If you omit `offset`, the full document text is returned and the
258        slice-specific response fields (`unit`, `offset`, `limit`, `start_line`,
259        `end_line`, `start_byte`, `end_byte`) are absent.
260        The caller must be authenticated and the request must be scoped to an app
261        that owns the document.
262
263        Args:
264            document: Document ID (`cdo_...`) whose content to retrieve.
265            offset: Starting position for a content slice. When `unit` is `"lines"`, this is a 1-indexed line number. When `unit` is `"bytes"`, this is a 0-indexed byte offset. Omit to return the full document.
266            limit: Maximum number of units to return when slicing. Defaults to 200 when `unit` is `"lines"` and 8192 when `unit` is `"bytes"`.
267            unit: Unit to use for `offset` and `limit`. One of `"lines"` (default) or `"bytes"`.
268
269        Returns:
270            The document's content, optionally sliced by offset and limit.
271        """
272        query: dict[str, object] = {}
273        if offset is not None:
274            query["offset"] = offset
275        if limit is not None:
276            query["limit"] = limit
277        if unit is not None:
278            query["unit"] = unit
279        return await self._http.request(
280            f"/api/v1/knowledge_documents/{document}/content",
281            query=query,
282            response_type=ContextDocumentContent,
283        )
AsyncKnowledgeDocumentResource(http: archastro.platform.runtime.http_client.HttpClient) 
116    def __init__(self, http: HttpClient):
117        self._http = http
async def list( self, *, page: int | None = None, page_size: int | None = None, q: str | None = None, source: list[str] | None = None, installation: list[str] | None = None, agent: list[str] | None = None) -> KnowledgeDocumentListResponse: 
119    async def list(
120        self,
121        *,
122        page: int | None = None,
123        page_size: int | None = None,
124        q: str | None = None,
125        source: builtins.list[str] | None = None,
126        installation: builtins.list[str] | None = None,
127        agent: builtins.list[str] | None = None,
128    ) -> KnowledgeDocumentListResponse:
129        """
130        List context documents
131        Returns a paginated list of context documents visible to the authenticated
132        caller within the scoped app. Results are ordered by creation time
133        descending.
134        Use `q` for a case-insensitive title prefix search. Use `source`,
135        `installation`, or `agent` to narrow results to documents belonging to
136        specific sources, installations, or agents. Multiple values within each
137        filter are treated as OR conditions. Filters may be combined.
138        The response includes page-level metadata so you can navigate through
139        large result sets without cursor tokens.
140
141        Args:
142            page: Page number to return. Defaults to 1.
143            page_size: Number of documents per page. Defaults to 25.
144            q: Case-insensitive prefix filter applied to the document title.
145            source: Return only documents belonging to these source IDs (`cso_...`). Multiple values are OR'd.
146            installation: Return only documents belonging to these installation IDs. Multiple values are OR'd.
147            agent: Return only documents owned by these agent IDs. Multiple values are OR'd.
148
149        Returns:
150            Successful response
151        """
152        query: dict[str, object] = {}
153        if page is not None:
154            query["page"] = page
155        if page_size is not None:
156            query["page_size"] = page_size
157        if q is not None:
158            query["q"] = q
159        if source is not None:
160            query["source"] = source
161        if installation is not None:
162            query["installation"] = installation
163        if agent is not None:
164            query["agent"] = agent
165        return await self._http.request(
166            "/api/v1/knowledge_documents",
167            query=query,
168            response_type=KnowledgeDocumentListResponse,
169        )

List context documents Returns a paginated list of context documents visible to the authenticated caller within the scoped app. Results are ordered by creation time descending. Use q for a case-insensitive title prefix search. Use source, installation, or agent to narrow results to documents belonging to specific sources, installations, or agents. Multiple values within each filter are treated as OR conditions. Filters may be combined. The response includes page-level metadata so you can navigate through large result sets without cursor tokens.

Arguments:
  • page: Page number to return. Defaults to 1.
  • page_size: Number of documents per page. Defaults to 25.
  • q: Case-insensitive prefix filter applied to the document title.
  • source: Return only documents belonging to these source IDs (cso_...). Multiple values are OR'd.
  • installation: Return only documents belonging to these installation IDs. Multiple values are OR'd.
  • agent: Return only documents owned by these agent IDs. Multiple values are OR'd.
Returns:

Successful response

async def delete(self, document: str) -> None: 
171    async def delete(self, document: str) -> None:
172        """
173        Delete a context document
174        Permanently deletes a context document and all of its associated chunk
175        items. This action is irreversible.
176        The backing storage file, if any, is not deleted storage files can be
177        shared across multiple documents and are cleaned up separately by the
178        platform's storage garbage collector. The caller must be authenticated
179        and the request must be scoped to the app that owns the document.
180
181        Args:
182            document: Document ID (`cdo_...`) to delete.
183
184        Returns:
185            Empty body. Returns HTTP 204 on success.
186        """
187        await self._http.request(f"/api/v1/knowledge_documents/{document}", method="DELETE")

Delete a context document Permanently deletes a context document and all of its associated chunk items. This action is irreversible. The backing storage file, if any, is not deleted storage files can be shared across multiple documents and are cleaned up separately by the platform's storage garbage collector. The caller must be authenticated and the request must be scoped to the app that owns the document.

Arguments:
  • document: Document ID (cdo_...) to delete.
Returns:

Empty body. Returns HTTP 204 on success.

async def get(self, document: str) -> archastro.platform.types.common.ContextDocument: 
189    async def get(self, document: str) -> ContextDocument:
190        """
191        Retrieve a context document
192        Returns a single context document identified by its ID. The response
193        includes document metadata such as title, size, and ownership fields,
194        but not the document's text content. To read the full or partial content,
195        use the content endpoint.
196        The caller must be authenticated and the request must be scoped to the
197        app that owns the document.
198
199        Args:
200            document: Document ID (`cdo_...`) to retrieve.
201
202        Returns:
203            The requested context document's metadata.
204        """
205        return await self._http.request(
206            f"/api/v1/knowledge_documents/{document}",
207            response_type=ContextDocument,
208        )

Retrieve a context document Returns a single context document identified by its ID. The response includes document metadata such as title, size, and ownership fields, but not the document's text content. To read the full or partial content, use the content endpoint. The caller must be authenticated and the request must be scoped to the app that owns the document.

Arguments:
  • document: Document ID (cdo_...) to retrieve.
Returns:

The requested context document's metadata.

async def update( self, document: str, input: KnowledgeDocumentUpdateInput) -> archastro.platform.types.common.ContextIngestion: 
210    async def update(self, document: str, input: KnowledgeDocumentUpdateInput) -> ContextIngestion:
211        """
212        Update a context document
213        Replaces one document's content while preserving its document ID. The update
214        runs asynchronously through the document's source pipeline: bytes are
215        extracted and chunked, the prior chunks are replaced atomically, and fresh
216        document and chunk embeddings are queued.
217        Supply exactly one of `file` or `content`. Omitted `title` and `metadata`
218        retain their current values. The response is an ingestion that can be polled
219        at `GET /api/v1/knowledge_ingestions/:id` until it reaches `succeeded` or
220        `failed`. `succeeded` means the replacement content and full-text indexes are
221        committed and the embedding refresh is durably queued; vector computation
222        continues in the retryable embedding worker.
223
224        Args:
225            document: Document ID (`cdo_...`) to update.
226            input: Request body.
227            input.content: Inline replacement bytes. Mutually exclusive with `file`.
228            input.file: ID of an already-uploaded file (`fil_...`). Mutually exclusive with `content`.
229            input.metadata: Replacement metadata map. Omit to retain the current metadata.
230            input.title: Replacement display title. Omit to retain the current title.
231
232        Returns:
233            The ingestion performing the document update.
234        """
235        return await self._http.request(
236            f"/api/v1/knowledge_documents/{document}",
237            method="PATCH",
238            body=input,
239            response_type=ContextIngestion,
240        )

Update a context document Replaces one document's content while preserving its document ID. The update runs asynchronously through the document's source pipeline: bytes are extracted and chunked, the prior chunks are replaced atomically, and fresh document and chunk embeddings are queued. Supply exactly one of file or content. Omitted title and metadata retain their current values. The response is an ingestion that can be polled at GET /api/v1/knowledge_ingestions/:id until it reaches succeeded or failed. succeeded means the replacement content and full-text indexes are committed and the embedding refresh is durably queued; vector computation continues in the retryable embedding worker.

Arguments:
  • document: Document ID (cdo_...) to update.
  • input: Request body.
  • input.content: Inline replacement bytes. Mutually exclusive with file.
  • input.file: ID of an already-uploaded file (fil_...). Mutually exclusive with content.
  • input.metadata: Replacement metadata map. Omit to retain the current metadata.
  • input.title: Replacement display title. Omit to retain the current title.
Returns:

The ingestion performing the document update.

async def content( self, document: str, *, offset: int | None = None, limit: int | None = None, unit: str | None = None) -> archastro.platform.types.common.ContextDocumentContent: 
242    async def content(
243        self,
244        document: str,
245        *,
246        offset: int | None = None,
247        limit: int | None = None,
248        unit: str | None = None,
249    ) -> ContextDocumentContent:
250        """
251        Retrieve a context document's content
252        Returns the full text of a context document, or a slice of it when
253        `offset`, `limit`, and `unit` are supplied. Both file-backed and inline
254        documents are supported; the response shape is the same in either case.
255        When slicing, set `unit` to `"lines"` (default) or `"bytes"`. A line-based
256        slice uses a 1-indexed `offset`; a byte-based slice uses a 0-indexed
257        `offset`. If you omit `offset`, the full document text is returned and the
258        slice-specific response fields (`unit`, `offset`, `limit`, `start_line`,
259        `end_line`, `start_byte`, `end_byte`) are absent.
260        The caller must be authenticated and the request must be scoped to an app
261        that owns the document.
262
263        Args:
264            document: Document ID (`cdo_...`) whose content to retrieve.
265            offset: Starting position for a content slice. When `unit` is `"lines"`, this is a 1-indexed line number. When `unit` is `"bytes"`, this is a 0-indexed byte offset. Omit to return the full document.
266            limit: Maximum number of units to return when slicing. Defaults to 200 when `unit` is `"lines"` and 8192 when `unit` is `"bytes"`.
267            unit: Unit to use for `offset` and `limit`. One of `"lines"` (default) or `"bytes"`.
268
269        Returns:
270            The document's content, optionally sliced by offset and limit.
271        """
272        query: dict[str, object] = {}
273        if offset is not None:
274            query["offset"] = offset
275        if limit is not None:
276            query["limit"] = limit
277        if unit is not None:
278            query["unit"] = unit
279        return await self._http.request(
280            f"/api/v1/knowledge_documents/{document}/content",
281            query=query,
282            response_type=ContextDocumentContent,
283        )

Retrieve a context document's content Returns the full text of a context document, or a slice of it when offset, limit, and unit are supplied. Both file-backed and inline documents are supported; the response shape is the same in either case. When slicing, set unit to "lines" (default) or "bytes". A line-based slice uses a 1-indexed offset; a byte-based slice uses a 0-indexed offset. If you omit offset, the full document text is returned and the slice-specific response fields (unit, offset, limit, start_line, end_line, start_byte, end_byte) are absent. The caller must be authenticated and the request must be scoped to an app that owns the document.

Arguments:
  • document: Document ID (cdo_...) whose content to retrieve.
  • offset: Starting position for a content slice. When unit is "lines", this is a 1-indexed line number. When unit is "bytes", this is a 0-indexed byte offset. Omit to return the full document.
  • limit: Maximum number of units to return when slicing. Defaults to 200 when unit is "lines" and 8192 when unit is "bytes".
  • unit: Unit to use for offset and limit. One of "lines" (default) or "bytes".
Returns:

The document's content, optionally sliced by offset and limit.

class KnowledgeDocumentResource: 
286class KnowledgeDocumentResource:
287    def __init__(self, http: SyncHttpClient):
288        self._http = http
289
290    def list(
291        self,
292        *,
293        page: int | None = None,
294        page_size: int | None = None,
295        q: str | None = None,
296        source: builtins.list[str] | None = None,
297        installation: builtins.list[str] | None = None,
298        agent: builtins.list[str] | None = None,
299    ) -> KnowledgeDocumentListResponse:
300        """
301        List context documents
302        Returns a paginated list of context documents visible to the authenticated
303        caller within the scoped app. Results are ordered by creation time
304        descending.
305        Use `q` for a case-insensitive title prefix search. Use `source`,
306        `installation`, or `agent` to narrow results to documents belonging to
307        specific sources, installations, or agents. Multiple values within each
308        filter are treated as OR conditions. Filters may be combined.
309        The response includes page-level metadata so you can navigate through
310        large result sets without cursor tokens.
311
312        Args:
313            page: Page number to return. Defaults to 1.
314            page_size: Number of documents per page. Defaults to 25.
315            q: Case-insensitive prefix filter applied to the document title.
316            source: Return only documents belonging to these source IDs (`cso_...`). Multiple values are OR'd.
317            installation: Return only documents belonging to these installation IDs. Multiple values are OR'd.
318            agent: Return only documents owned by these agent IDs. Multiple values are OR'd.
319
320        Returns:
321            Successful response
322        """
323        query: dict[str, object] = {}
324        if page is not None:
325            query["page"] = page
326        if page_size is not None:
327            query["page_size"] = page_size
328        if q is not None:
329            query["q"] = q
330        if source is not None:
331            query["source"] = source
332        if installation is not None:
333            query["installation"] = installation
334        if agent is not None:
335            query["agent"] = agent
336        return self._http.request(
337            "/api/v1/knowledge_documents",
338            query=query,
339            response_type=KnowledgeDocumentListResponse,
340        )
341
342    def delete(self, document: str) -> None:
343        """
344        Delete a context document
345        Permanently deletes a context document and all of its associated chunk
346        items. This action is irreversible.
347        The backing storage file, if any, is not deleted storage files can be
348        shared across multiple documents and are cleaned up separately by the
349        platform's storage garbage collector. The caller must be authenticated
350        and the request must be scoped to the app that owns the document.
351
352        Args:
353            document: Document ID (`cdo_...`) to delete.
354
355        Returns:
356            Empty body. Returns HTTP 204 on success.
357        """
358        self._http.request(f"/api/v1/knowledge_documents/{document}", method="DELETE")
359
360    def get(self, document: str) -> ContextDocument:
361        """
362        Retrieve a context document
363        Returns a single context document identified by its ID. The response
364        includes document metadata such as title, size, and ownership fields,
365        but not the document's text content. To read the full or partial content,
366        use the content endpoint.
367        The caller must be authenticated and the request must be scoped to the
368        app that owns the document.
369
370        Args:
371            document: Document ID (`cdo_...`) to retrieve.
372
373        Returns:
374            The requested context document's metadata.
375        """
376        return self._http.request(
377            f"/api/v1/knowledge_documents/{document}",
378            response_type=ContextDocument,
379        )
380
381    def update(self, document: str, input: KnowledgeDocumentUpdateInput) -> ContextIngestion:
382        """
383        Update a context document
384        Replaces one document's content while preserving its document ID. The update
385        runs asynchronously through the document's source pipeline: bytes are
386        extracted and chunked, the prior chunks are replaced atomically, and fresh
387        document and chunk embeddings are queued.
388        Supply exactly one of `file` or `content`. Omitted `title` and `metadata`
389        retain their current values. The response is an ingestion that can be polled
390        at `GET /api/v1/knowledge_ingestions/:id` until it reaches `succeeded` or
391        `failed`. `succeeded` means the replacement content and full-text indexes are
392        committed and the embedding refresh is durably queued; vector computation
393        continues in the retryable embedding worker.
394
395        Args:
396            document: Document ID (`cdo_...`) to update.
397            input: Request body.
398            input.content: Inline replacement bytes. Mutually exclusive with `file`.
399            input.file: ID of an already-uploaded file (`fil_...`). Mutually exclusive with `content`.
400            input.metadata: Replacement metadata map. Omit to retain the current metadata.
401            input.title: Replacement display title. Omit to retain the current title.
402
403        Returns:
404            The ingestion performing the document update.
405        """
406        return self._http.request(
407            f"/api/v1/knowledge_documents/{document}",
408            method="PATCH",
409            body=input,
410            response_type=ContextIngestion,
411        )
412
413    def content(
414        self,
415        document: str,
416        *,
417        offset: int | None = None,
418        limit: int | None = None,
419        unit: str | None = None,
420    ) -> ContextDocumentContent:
421        """
422        Retrieve a context document's content
423        Returns the full text of a context document, or a slice of it when
424        `offset`, `limit`, and `unit` are supplied. Both file-backed and inline
425        documents are supported; the response shape is the same in either case.
426        When slicing, set `unit` to `"lines"` (default) or `"bytes"`. A line-based
427        slice uses a 1-indexed `offset`; a byte-based slice uses a 0-indexed
428        `offset`. If you omit `offset`, the full document text is returned and the
429        slice-specific response fields (`unit`, `offset`, `limit`, `start_line`,
430        `end_line`, `start_byte`, `end_byte`) are absent.
431        The caller must be authenticated and the request must be scoped to an app
432        that owns the document.
433
434        Args:
435            document: Document ID (`cdo_...`) whose content to retrieve.
436            offset: Starting position for a content slice. When `unit` is `"lines"`, this is a 1-indexed line number. When `unit` is `"bytes"`, this is a 0-indexed byte offset. Omit to return the full document.
437            limit: Maximum number of units to return when slicing. Defaults to 200 when `unit` is `"lines"` and 8192 when `unit` is `"bytes"`.
438            unit: Unit to use for `offset` and `limit`. One of `"lines"` (default) or `"bytes"`.
439
440        Returns:
441            The document's content, optionally sliced by offset and limit.
442        """
443        query: dict[str, object] = {}
444        if offset is not None:
445            query["offset"] = offset
446        if limit is not None:
447            query["limit"] = limit
448        if unit is not None:
449            query["unit"] = unit
450        return self._http.request(
451            f"/api/v1/knowledge_documents/{document}/content",
452            query=query,
453            response_type=ContextDocumentContent,
454        )
KnowledgeDocumentResource(http: archastro.platform.runtime.http_client.SyncHttpClient) 
287    def __init__(self, http: SyncHttpClient):
288        self._http = http
def list( self, *, page: int | None = None, page_size: int | None = None, q: str | None = None, source: list[str] | None = None, installation: list[str] | None = None, agent: list[str] | None = None) -> KnowledgeDocumentListResponse: 
290    def list(
291        self,
292        *,
293        page: int | None = None,
294        page_size: int | None = None,
295        q: str | None = None,
296        source: builtins.list[str] | None = None,
297        installation: builtins.list[str] | None = None,
298        agent: builtins.list[str] | None = None,
299    ) -> KnowledgeDocumentListResponse:
300        """
301        List context documents
302        Returns a paginated list of context documents visible to the authenticated
303        caller within the scoped app. Results are ordered by creation time
304        descending.
305        Use `q` for a case-insensitive title prefix search. Use `source`,
306        `installation`, or `agent` to narrow results to documents belonging to
307        specific sources, installations, or agents. Multiple values within each
308        filter are treated as OR conditions. Filters may be combined.
309        The response includes page-level metadata so you can navigate through
310        large result sets without cursor tokens.
311
312        Args:
313            page: Page number to return. Defaults to 1.
314            page_size: Number of documents per page. Defaults to 25.
315            q: Case-insensitive prefix filter applied to the document title.
316            source: Return only documents belonging to these source IDs (`cso_...`). Multiple values are OR'd.
317            installation: Return only documents belonging to these installation IDs. Multiple values are OR'd.
318            agent: Return only documents owned by these agent IDs. Multiple values are OR'd.
319
320        Returns:
321            Successful response
322        """
323        query: dict[str, object] = {}
324        if page is not None:
325            query["page"] = page
326        if page_size is not None:
327            query["page_size"] = page_size
328        if q is not None:
329            query["q"] = q
330        if source is not None:
331            query["source"] = source
332        if installation is not None:
333            query["installation"] = installation
334        if agent is not None:
335            query["agent"] = agent
336        return self._http.request(
337            "/api/v1/knowledge_documents",
338            query=query,
339            response_type=KnowledgeDocumentListResponse,
340        )

List context documents Returns a paginated list of context documents visible to the authenticated caller within the scoped app. Results are ordered by creation time descending. Use q for a case-insensitive title prefix search. Use source, installation, or agent to narrow results to documents belonging to specific sources, installations, or agents. Multiple values within each filter are treated as OR conditions. Filters may be combined. The response includes page-level metadata so you can navigate through large result sets without cursor tokens.

Arguments:
  • page: Page number to return. Defaults to 1.
  • page_size: Number of documents per page. Defaults to 25.
  • q: Case-insensitive prefix filter applied to the document title.
  • source: Return only documents belonging to these source IDs (cso_...). Multiple values are OR'd.
  • installation: Return only documents belonging to these installation IDs. Multiple values are OR'd.
  • agent: Return only documents owned by these agent IDs. Multiple values are OR'd.
Returns:

Successful response

def delete(self, document: str) -> None: 
342    def delete(self, document: str) -> None:
343        """
344        Delete a context document
345        Permanently deletes a context document and all of its associated chunk
346        items. This action is irreversible.
347        The backing storage file, if any, is not deleted storage files can be
348        shared across multiple documents and are cleaned up separately by the
349        platform's storage garbage collector. The caller must be authenticated
350        and the request must be scoped to the app that owns the document.
351
352        Args:
353            document: Document ID (`cdo_...`) to delete.
354
355        Returns:
356            Empty body. Returns HTTP 204 on success.
357        """
358        self._http.request(f"/api/v1/knowledge_documents/{document}", method="DELETE")

Delete a context document Permanently deletes a context document and all of its associated chunk items. This action is irreversible. The backing storage file, if any, is not deleted storage files can be shared across multiple documents and are cleaned up separately by the platform's storage garbage collector. The caller must be authenticated and the request must be scoped to the app that owns the document.

Arguments:
  • document: Document ID (cdo_...) to delete.
Returns:

Empty body. Returns HTTP 204 on success.

def get(self, document: str) -> archastro.platform.types.common.ContextDocument: 
360    def get(self, document: str) -> ContextDocument:
361        """
362        Retrieve a context document
363        Returns a single context document identified by its ID. The response
364        includes document metadata such as title, size, and ownership fields,
365        but not the document's text content. To read the full or partial content,
366        use the content endpoint.
367        The caller must be authenticated and the request must be scoped to the
368        app that owns the document.
369
370        Args:
371            document: Document ID (`cdo_...`) to retrieve.
372
373        Returns:
374            The requested context document's metadata.
375        """
376        return self._http.request(
377            f"/api/v1/knowledge_documents/{document}",
378            response_type=ContextDocument,
379        )

Retrieve a context document Returns a single context document identified by its ID. The response includes document metadata such as title, size, and ownership fields, but not the document's text content. To read the full or partial content, use the content endpoint. The caller must be authenticated and the request must be scoped to the app that owns the document.

Arguments:
  • document: Document ID (cdo_...) to retrieve.
Returns:

The requested context document's metadata.

def update( self, document: str, input: KnowledgeDocumentUpdateInput) -> archastro.platform.types.common.ContextIngestion: 
381    def update(self, document: str, input: KnowledgeDocumentUpdateInput) -> ContextIngestion:
382        """
383        Update a context document
384        Replaces one document's content while preserving its document ID. The update
385        runs asynchronously through the document's source pipeline: bytes are
386        extracted and chunked, the prior chunks are replaced atomically, and fresh
387        document and chunk embeddings are queued.
388        Supply exactly one of `file` or `content`. Omitted `title` and `metadata`
389        retain their current values. The response is an ingestion that can be polled
390        at `GET /api/v1/knowledge_ingestions/:id` until it reaches `succeeded` or
391        `failed`. `succeeded` means the replacement content and full-text indexes are
392        committed and the embedding refresh is durably queued; vector computation
393        continues in the retryable embedding worker.
394
395        Args:
396            document: Document ID (`cdo_...`) to update.
397            input: Request body.
398            input.content: Inline replacement bytes. Mutually exclusive with `file`.
399            input.file: ID of an already-uploaded file (`fil_...`). Mutually exclusive with `content`.
400            input.metadata: Replacement metadata map. Omit to retain the current metadata.
401            input.title: Replacement display title. Omit to retain the current title.
402
403        Returns:
404            The ingestion performing the document update.
405        """
406        return self._http.request(
407            f"/api/v1/knowledge_documents/{document}",
408            method="PATCH",
409            body=input,
410            response_type=ContextIngestion,
411        )

Update a context document Replaces one document's content while preserving its document ID. The update runs asynchronously through the document's source pipeline: bytes are extracted and chunked, the prior chunks are replaced atomically, and fresh document and chunk embeddings are queued. Supply exactly one of file or content. Omitted title and metadata retain their current values. The response is an ingestion that can be polled at GET /api/v1/knowledge_ingestions/:id until it reaches succeeded or failed. succeeded means the replacement content and full-text indexes are committed and the embedding refresh is durably queued; vector computation continues in the retryable embedding worker.

Arguments:
  • document: Document ID (cdo_...) to update.
  • input: Request body.
  • input.content: Inline replacement bytes. Mutually exclusive with file.
  • input.file: ID of an already-uploaded file (fil_...). Mutually exclusive with content.
  • input.metadata: Replacement metadata map. Omit to retain the current metadata.
  • input.title: Replacement display title. Omit to retain the current title.
Returns:

The ingestion performing the document update.

def content( self, document: str, *, offset: int | None = None, limit: int | None = None, unit: str | None = None) -> archastro.platform.types.common.ContextDocumentContent: 
413    def content(
414        self,
415        document: str,
416        *,
417        offset: int | None = None,
418        limit: int | None = None,
419        unit: str | None = None,
420    ) -> ContextDocumentContent:
421        """
422        Retrieve a context document's content
423        Returns the full text of a context document, or a slice of it when
424        `offset`, `limit`, and `unit` are supplied. Both file-backed and inline
425        documents are supported; the response shape is the same in either case.
426        When slicing, set `unit` to `"lines"` (default) or `"bytes"`. A line-based
427        slice uses a 1-indexed `offset`; a byte-based slice uses a 0-indexed
428        `offset`. If you omit `offset`, the full document text is returned and the
429        slice-specific response fields (`unit`, `offset`, `limit`, `start_line`,
430        `end_line`, `start_byte`, `end_byte`) are absent.
431        The caller must be authenticated and the request must be scoped to an app
432        that owns the document.
433
434        Args:
435            document: Document ID (`cdo_...`) whose content to retrieve.
436            offset: Starting position for a content slice. When `unit` is `"lines"`, this is a 1-indexed line number. When `unit` is `"bytes"`, this is a 0-indexed byte offset. Omit to return the full document.
437            limit: Maximum number of units to return when slicing. Defaults to 200 when `unit` is `"lines"` and 8192 when `unit` is `"bytes"`.
438            unit: Unit to use for `offset` and `limit`. One of `"lines"` (default) or `"bytes"`.
439
440        Returns:
441            The document's content, optionally sliced by offset and limit.
442        """
443        query: dict[str, object] = {}
444        if offset is not None:
445            query["offset"] = offset
446        if limit is not None:
447            query["limit"] = limit
448        if unit is not None:
449            query["unit"] = unit
450        return self._http.request(
451            f"/api/v1/knowledge_documents/{document}/content",
452            query=query,
453            response_type=ContextDocumentContent,
454        )

Retrieve a context document's content Returns the full text of a context document, or a slice of it when offset, limit, and unit are supplied. Both file-backed and inline documents are supported; the response shape is the same in either case. When slicing, set unit to "lines" (default) or "bytes". A line-based slice uses a 1-indexed offset; a byte-based slice uses a 0-indexed offset. If you omit offset, the full document text is returned and the slice-specific response fields (unit, offset, limit, start_line, end_line, start_byte, end_byte) are absent. The caller must be authenticated and the request must be scoped to an app that owns the document.

Arguments:
  • document: Document ID (cdo_...) whose content to retrieve.
  • offset: Starting position for a content slice. When unit is "lines", this is a 1-indexed line number. When unit is "bytes", this is a 0-indexed byte offset. Omit to return the full document.
  • limit: Maximum number of units to return when slicing. Defaults to 200 when unit is "lines" and 8192 when unit is "bytes".
  • unit: Unit to use for offset and limit. One of "lines" (default) or "bytes".
Returns:

The document's content, optionally sliced by offset and limit.