archastro.platform.v1.resources.knowledge_documents 

  1# Copyright (c) 2026 ArchAstro Inc. All Rights Reserved.
  2# This file is auto-generated by @archastro/sdk-generator. Do not edit.
  3# Content hash: 3db377281f7d
  4
  5from __future__ import annotations
  6
  7import builtins
  8from datetime import datetime
  9from typing import Any
 10
 11from pydantic import BaseModel, Field
 12
 13from ...runtime.http_client import HttpClient, SyncHttpClient
 14from ...types.common import ContextDocument, ContextDocumentContent
 15
 16
 17class KnowledgeDocumentListResponseDataItem(BaseModel):
 18    agent: str | None = Field(
 19        default=None,
 20        description="ID of the agent that owns this document (`agi_...`). `null` if owned by a user or team.",
 21    )
 22    created_at: datetime | None = Field(
 23        default=None, description="When the document was created (ISO 8601)."
 24    )
 25    file: str | None = Field(
 26        default=None,
 27        description="ID of the backing storage file (`fil_...`) when the document is file-backed. `null` for inline documents.",
 28    )
 29    id: str = Field(..., description="Context document ID (`cdo_...`).")
 30    metadata: dict[str, Any] | None = Field(
 31        default=None,
 32        description="Arbitrary key-value metadata attached to the document. Shape varies by source type.",
 33    )
 34    source: str | None = Field(
 35        default=None, description="ID of the context source this document belongs to (`cso_...`)."
 36    )
 37    team: str | None = Field(
 38        default=None,
 39        description="ID of the team that owns this document (`tem_...`). `null` if owned by a user or agent.",
 40    )
 41    title: str | None = Field(
 42        default=None,
 43        description="Human-readable display title of the document. `null` if no title has been set.",
 44    )
 45    total_lines: int | None = Field(
 46        default=None,
 47        description="Total number of lines in the document's text content. `0` if the document has no content.",
 48    )
 49    total_size: int | None = Field(
 50        default=None,
 51        description="Total byte size of the document's text content. `0` if the document has no content.",
 52    )
 53    updated_at: datetime | None = Field(
 54        default=None, description="When the document was last modified (ISO 8601)."
 55    )
 56    user: str | None = Field(
 57        default=None,
 58        description="ID of the user that owns this document (`usr_...`). `null` if owned by a team or agent.",
 59    )
 60
 61
 62class KnowledgeDocumentListResponse(BaseModel):
 63    """
 64    Successful response
 65    """
 66
 67    data: list[KnowledgeDocumentListResponseDataItem] = Field(
 68        ..., description="Array of context document objects for the current page."
 69    )
 70    has_next: bool = Field(
 71        ..., description="`true` if a subsequent page exists; `false` when this is the last page."
 72    )
 73    has_prev: bool = Field(
 74        ..., description="`true` if a previous page exists; `false` when this is the first page."
 75    )
 76    page: int = Field(..., description="The current page number.")
 77    page_size: int = Field(..., description="Maximum number of documents returned per page.")
 78    total_entries: int = Field(
 79        ..., description="Total number of documents matching the applied filters across all pages."
 80    )
 81    total_pages: int = Field(
 82        ..., description="Total number of pages given the current `page_size`."
 83    )
 84
 85
 86class AsyncKnowledgeDocumentResource:
 87    def __init__(self, http: HttpClient):
 88        self._http = http
 89
 90    async def list(
 91        self,
 92        *,
 93        page: int | None = None,
 94        page_size: int | None = None,
 95        q: str | None = None,
 96        source: builtins.list[str] | None = None,
 97        installation: builtins.list[str] | None = None,
 98        agent: builtins.list[str] | None = None,
 99    ) -> KnowledgeDocumentListResponse:
100        """
101        List context documents
102        Returns a paginated list of context documents visible to the authenticated
103        caller within the scoped app. Results are ordered by creation time
104        descending.
105        Use `q` for a case-insensitive title prefix search. Use `source`,
106        `installation`, or `agent` to narrow results to documents belonging to
107        specific sources, installations, or agents. Multiple values within each
108        filter are treated as OR conditions. Filters may be combined.
109        The response includes page-level metadata so you can navigate through
110        large result sets without cursor tokens.
111
112        Args:
113            page: Page number to return. Defaults to 1.
114            page_size: Number of documents per page. Defaults to 25.
115            q: Case-insensitive prefix filter applied to the document title.
116            source: Return only documents belonging to these source IDs (`cso_...`). Multiple values are OR'd.
117            installation: Return only documents belonging to these installation IDs. Multiple values are OR'd.
118            agent: Return only documents owned by these agent IDs. Multiple values are OR'd.
119
120        Returns:
121            Successful response
122        """
123        query: dict[str, object] = {}
124        if page is not None:
125            query["page"] = page
126        if page_size is not None:
127            query["page_size"] = page_size
128        if q is not None:
129            query["q"] = q
130        if source is not None:
131            query["source"] = source
132        if installation is not None:
133            query["installation"] = installation
134        if agent is not None:
135            query["agent"] = agent
136        return await self._http.request(
137            "/api/v1/knowledge_documents",
138            query=query,
139            response_type=KnowledgeDocumentListResponse,
140        )
141
142    async def delete(self, document: str) -> None:
143        """
144        Delete a context document
145        Permanently deletes a context document and all of its associated chunk
146        items. This action is irreversible.
147        The backing storage file, if any, is not deleted storage files can be
148        shared across multiple documents and are cleaned up separately by the
149        platform's storage garbage collector. The caller must be authenticated
150        and the request must be scoped to the app that owns the document.
151
152        Args:
153            document: Document ID (`cdo_...`) to delete.
154
155        Returns:
156            Empty body. Returns HTTP 204 on success.
157        """
158        await self._http.request(f"/api/v1/knowledge_documents/{document}", method="DELETE")
159
160    async def get(self, document: str) -> ContextDocument:
161        """
162        Retrieve a context document
163        Returns a single context document identified by its ID. The response
164        includes document metadata such as title, size, and ownership fields,
165        but not the document's text content. To read the full or partial content,
166        use the content endpoint.
167        The caller must be authenticated and the request must be scoped to the
168        app that owns the document.
169
170        Args:
171            document: Document ID (`cdo_...`) to retrieve.
172
173        Returns:
174            The requested context document's metadata.
175        """
176        return await self._http.request(
177            f"/api/v1/knowledge_documents/{document}",
178            response_type=ContextDocument,
179        )
180
181    async def content(
182        self,
183        document: str,
184        *,
185        offset: int | None = None,
186        limit: int | None = None,
187        unit: str | None = None,
188    ) -> ContextDocumentContent:
189        """
190        Retrieve a context document's content
191        Returns the full text of a context document, or a slice of it when
192        `offset`, `limit`, and `unit` are supplied. Both file-backed and inline
193        documents are supported; the response shape is the same in either case.
194        When slicing, set `unit` to `"lines"` (default) or `"bytes"`. A line-based
195        slice uses a 1-indexed `offset`; a byte-based slice uses a 0-indexed
196        `offset`. If you omit `offset`, the full document text is returned and the
197        slice-specific response fields (`unit`, `offset`, `limit`, `start_line`,
198        `end_line`, `start_byte`, `end_byte`) are absent.
199        The caller must be authenticated and the request must be scoped to an app
200        that owns the document.
201
202        Args:
203            document: Document ID (`cdo_...`) whose content to retrieve.
204            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.
205            limit: Maximum number of units to return when slicing. Defaults to 200 when `unit` is `"lines"` and 8192 when `unit` is `"bytes"`.
206            unit: Unit to use for `offset` and `limit`. One of `"lines"` (default) or `"bytes"`.
207
208        Returns:
209            The document's content, optionally sliced by offset and limit.
210        """
211        query: dict[str, object] = {}
212        if offset is not None:
213            query["offset"] = offset
214        if limit is not None:
215            query["limit"] = limit
216        if unit is not None:
217            query["unit"] = unit
218        return await self._http.request(
219            f"/api/v1/knowledge_documents/{document}/content",
220            query=query,
221            response_type=ContextDocumentContent,
222        )
223
224
225class KnowledgeDocumentResource:
226    def __init__(self, http: SyncHttpClient):
227        self._http = http
228
229    def list(
230        self,
231        *,
232        page: int | None = None,
233        page_size: int | None = None,
234        q: str | None = None,
235        source: builtins.list[str] | None = None,
236        installation: builtins.list[str] | None = None,
237        agent: builtins.list[str] | None = None,
238    ) -> KnowledgeDocumentListResponse:
239        """
240        List context documents
241        Returns a paginated list of context documents visible to the authenticated
242        caller within the scoped app. Results are ordered by creation time
243        descending.
244        Use `q` for a case-insensitive title prefix search. Use `source`,
245        `installation`, or `agent` to narrow results to documents belonging to
246        specific sources, installations, or agents. Multiple values within each
247        filter are treated as OR conditions. Filters may be combined.
248        The response includes page-level metadata so you can navigate through
249        large result sets without cursor tokens.
250
251        Args:
252            page: Page number to return. Defaults to 1.
253            page_size: Number of documents per page. Defaults to 25.
254            q: Case-insensitive prefix filter applied to the document title.
255            source: Return only documents belonging to these source IDs (`cso_...`). Multiple values are OR'd.
256            installation: Return only documents belonging to these installation IDs. Multiple values are OR'd.
257            agent: Return only documents owned by these agent IDs. Multiple values are OR'd.
258
259        Returns:
260            Successful response
261        """
262        query: dict[str, object] = {}
263        if page is not None:
264            query["page"] = page
265        if page_size is not None:
266            query["page_size"] = page_size
267        if q is not None:
268            query["q"] = q
269        if source is not None:
270            query["source"] = source
271        if installation is not None:
272            query["installation"] = installation
273        if agent is not None:
274            query["agent"] = agent
275        return self._http.request(
276            "/api/v1/knowledge_documents",
277            query=query,
278            response_type=KnowledgeDocumentListResponse,
279        )
280
281    def delete(self, document: str) -> None:
282        """
283        Delete a context document
284        Permanently deletes a context document and all of its associated chunk
285        items. This action is irreversible.
286        The backing storage file, if any, is not deleted storage files can be
287        shared across multiple documents and are cleaned up separately by the
288        platform's storage garbage collector. The caller must be authenticated
289        and the request must be scoped to the app that owns the document.
290
291        Args:
292            document: Document ID (`cdo_...`) to delete.
293
294        Returns:
295            Empty body. Returns HTTP 204 on success.
296        """
297        self._http.request(f"/api/v1/knowledge_documents/{document}", method="DELETE")
298
299    def get(self, document: str) -> ContextDocument:
300        """
301        Retrieve a context document
302        Returns a single context document identified by its ID. The response
303        includes document metadata such as title, size, and ownership fields,
304        but not the document's text content. To read the full or partial content,
305        use the content endpoint.
306        The caller must be authenticated and the request must be scoped to the
307        app that owns the document.
308
309        Args:
310            document: Document ID (`cdo_...`) to retrieve.
311
312        Returns:
313            The requested context document's metadata.
314        """
315        return self._http.request(
316            f"/api/v1/knowledge_documents/{document}",
317            response_type=ContextDocument,
318        )
319
320    def content(
321        self,
322        document: str,
323        *,
324        offset: int | None = None,
325        limit: int | None = None,
326        unit: str | None = None,
327    ) -> ContextDocumentContent:
328        """
329        Retrieve a context document's content
330        Returns the full text of a context document, or a slice of it when
331        `offset`, `limit`, and `unit` are supplied. Both file-backed and inline
332        documents are supported; the response shape is the same in either case.
333        When slicing, set `unit` to `"lines"` (default) or `"bytes"`. A line-based
334        slice uses a 1-indexed `offset`; a byte-based slice uses a 0-indexed
335        `offset`. If you omit `offset`, the full document text is returned and the
336        slice-specific response fields (`unit`, `offset`, `limit`, `start_line`,
337        `end_line`, `start_byte`, `end_byte`) are absent.
338        The caller must be authenticated and the request must be scoped to an app
339        that owns the document.
340
341        Args:
342            document: Document ID (`cdo_...`) whose content to retrieve.
343            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.
344            limit: Maximum number of units to return when slicing. Defaults to 200 when `unit` is `"lines"` and 8192 when `unit` is `"bytes"`.
345            unit: Unit to use for `offset` and `limit`. One of `"lines"` (default) or `"bytes"`.
346
347        Returns:
348            The document's content, optionally sliced by offset and limit.
349        """
350        query: dict[str, object] = {}
351        if offset is not None:
352            query["offset"] = offset
353        if limit is not None:
354            query["limit"] = limit
355        if unit is not None:
356            query["unit"] = unit
357        return self._http.request(
358            f"/api/v1/knowledge_documents/{document}/content",
359            query=query,
360            response_type=ContextDocumentContent,
361        )
class KnowledgeDocumentListResponseDataItem(pydantic.main.BaseModel): 
18class KnowledgeDocumentListResponseDataItem(BaseModel):
19    agent: str | None = Field(
20        default=None,
21        description="ID of the agent that owns this document (`agi_...`). `null` if owned by a user or team.",
22    )
23    created_at: datetime | None = Field(
24        default=None, description="When the document was created (ISO 8601)."
25    )
26    file: str | None = Field(
27        default=None,
28        description="ID of the backing storage file (`fil_...`) when the document is file-backed. `null` for inline documents.",
29    )
30    id: str = Field(..., description="Context document ID (`cdo_...`).")
31    metadata: dict[str, Any] | None = Field(
32        default=None,
33        description="Arbitrary key-value metadata attached to the document. Shape varies by source type.",
34    )
35    source: str | None = Field(
36        default=None, description="ID of the context source this document belongs to (`cso_...`)."
37    )
38    team: str | None = Field(
39        default=None,
40        description="ID of the team that owns this document (`tem_...`). `null` if owned by a user or agent.",
41    )
42    title: str | None = Field(
43        default=None,
44        description="Human-readable display title of the document. `null` if no title has been set.",
45    )
46    total_lines: int | None = Field(
47        default=None,
48        description="Total number of lines in the document's text content. `0` if the document has no content.",
49    )
50    total_size: int | None = Field(
51        default=None,
52        description="Total byte size of the document's text content. `0` if the document has no content.",
53    )
54    updated_at: datetime | None = Field(
55        default=None, description="When the document was last modified (ISO 8601)."
56    )
57    user: str | None = Field(
58        default=None,
59        description="ID of the user that owns this document (`usr_...`). `null` if owned by a team or agent.",
60    )

!!! 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.

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): 
63class KnowledgeDocumentListResponse(BaseModel):
64    """
65    Successful response
66    """
67
68    data: list[KnowledgeDocumentListResponseDataItem] = Field(
69        ..., description="Array of context document objects for the current page."
70    )
71    has_next: bool = Field(
72        ..., description="`true` if a subsequent page exists; `false` when this is the last page."
73    )
74    has_prev: bool = Field(
75        ..., description="`true` if a previous page exists; `false` when this is the first page."
76    )
77    page: int = Field(..., description="The current page number.")
78    page_size: int = Field(..., description="Maximum number of documents returned per page.")
79    total_entries: int = Field(
80        ..., description="Total number of documents matching the applied filters across all pages."
81    )
82    total_pages: int = Field(
83        ..., description="Total number of pages given the current `page_size`."
84    )

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: 
 87class AsyncKnowledgeDocumentResource:
 88    def __init__(self, http: HttpClient):
 89        self._http = http
 90
 91    async def list(
 92        self,
 93        *,
 94        page: int | None = None,
 95        page_size: int | None = None,
 96        q: str | None = None,
 97        source: builtins.list[str] | None = None,
 98        installation: builtins.list[str] | None = None,
 99        agent: builtins.list[str] | None = None,
100    ) -> KnowledgeDocumentListResponse:
101        """
102        List context documents
103        Returns a paginated list of context documents visible to the authenticated
104        caller within the scoped app. Results are ordered by creation time
105        descending.
106        Use `q` for a case-insensitive title prefix search. Use `source`,
107        `installation`, or `agent` to narrow results to documents belonging to
108        specific sources, installations, or agents. Multiple values within each
109        filter are treated as OR conditions. Filters may be combined.
110        The response includes page-level metadata so you can navigate through
111        large result sets without cursor tokens.
112
113        Args:
114            page: Page number to return. Defaults to 1.
115            page_size: Number of documents per page. Defaults to 25.
116            q: Case-insensitive prefix filter applied to the document title.
117            source: Return only documents belonging to these source IDs (`cso_...`). Multiple values are OR'd.
118            installation: Return only documents belonging to these installation IDs. Multiple values are OR'd.
119            agent: Return only documents owned by these agent IDs. Multiple values are OR'd.
120
121        Returns:
122            Successful response
123        """
124        query: dict[str, object] = {}
125        if page is not None:
126            query["page"] = page
127        if page_size is not None:
128            query["page_size"] = page_size
129        if q is not None:
130            query["q"] = q
131        if source is not None:
132            query["source"] = source
133        if installation is not None:
134            query["installation"] = installation
135        if agent is not None:
136            query["agent"] = agent
137        return await self._http.request(
138            "/api/v1/knowledge_documents",
139            query=query,
140            response_type=KnowledgeDocumentListResponse,
141        )
142
143    async def delete(self, document: str) -> None:
144        """
145        Delete a context document
146        Permanently deletes a context document and all of its associated chunk
147        items. This action is irreversible.
148        The backing storage file, if any, is not deleted storage files can be
149        shared across multiple documents and are cleaned up separately by the
150        platform's storage garbage collector. The caller must be authenticated
151        and the request must be scoped to the app that owns the document.
152
153        Args:
154            document: Document ID (`cdo_...`) to delete.
155
156        Returns:
157            Empty body. Returns HTTP 204 on success.
158        """
159        await self._http.request(f"/api/v1/knowledge_documents/{document}", method="DELETE")
160
161    async def get(self, document: str) -> ContextDocument:
162        """
163        Retrieve a context document
164        Returns a single context document identified by its ID. The response
165        includes document metadata such as title, size, and ownership fields,
166        but not the document's text content. To read the full or partial content,
167        use the content endpoint.
168        The caller must be authenticated and the request must be scoped to the
169        app that owns the document.
170
171        Args:
172            document: Document ID (`cdo_...`) to retrieve.
173
174        Returns:
175            The requested context document's metadata.
176        """
177        return await self._http.request(
178            f"/api/v1/knowledge_documents/{document}",
179            response_type=ContextDocument,
180        )
181
182    async def content(
183        self,
184        document: str,
185        *,
186        offset: int | None = None,
187        limit: int | None = None,
188        unit: str | None = None,
189    ) -> ContextDocumentContent:
190        """
191        Retrieve a context document's content
192        Returns the full text of a context document, or a slice of it when
193        `offset`, `limit`, and `unit` are supplied. Both file-backed and inline
194        documents are supported; the response shape is the same in either case.
195        When slicing, set `unit` to `"lines"` (default) or `"bytes"`. A line-based
196        slice uses a 1-indexed `offset`; a byte-based slice uses a 0-indexed
197        `offset`. If you omit `offset`, the full document text is returned and the
198        slice-specific response fields (`unit`, `offset`, `limit`, `start_line`,
199        `end_line`, `start_byte`, `end_byte`) are absent.
200        The caller must be authenticated and the request must be scoped to an app
201        that owns the document.
202
203        Args:
204            document: Document ID (`cdo_...`) whose content to retrieve.
205            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.
206            limit: Maximum number of units to return when slicing. Defaults to 200 when `unit` is `"lines"` and 8192 when `unit` is `"bytes"`.
207            unit: Unit to use for `offset` and `limit`. One of `"lines"` (default) or `"bytes"`.
208
209        Returns:
210            The document's content, optionally sliced by offset and limit.
211        """
212        query: dict[str, object] = {}
213        if offset is not None:
214            query["offset"] = offset
215        if limit is not None:
216            query["limit"] = limit
217        if unit is not None:
218            query["unit"] = unit
219        return await self._http.request(
220            f"/api/v1/knowledge_documents/{document}/content",
221            query=query,
222            response_type=ContextDocumentContent,
223        )
AsyncKnowledgeDocumentResource(http: archastro.platform.runtime.http_client.HttpClient) 
88    def __init__(self, http: HttpClient):
89        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: 
 91    async def list(
 92        self,
 93        *,
 94        page: int | None = None,
 95        page_size: int | None = None,
 96        q: str | None = None,
 97        source: builtins.list[str] | None = None,
 98        installation: builtins.list[str] | None = None,
 99        agent: builtins.list[str] | None = None,
100    ) -> KnowledgeDocumentListResponse:
101        """
102        List context documents
103        Returns a paginated list of context documents visible to the authenticated
104        caller within the scoped app. Results are ordered by creation time
105        descending.
106        Use `q` for a case-insensitive title prefix search. Use `source`,
107        `installation`, or `agent` to narrow results to documents belonging to
108        specific sources, installations, or agents. Multiple values within each
109        filter are treated as OR conditions. Filters may be combined.
110        The response includes page-level metadata so you can navigate through
111        large result sets without cursor tokens.
112
113        Args:
114            page: Page number to return. Defaults to 1.
115            page_size: Number of documents per page. Defaults to 25.
116            q: Case-insensitive prefix filter applied to the document title.
117            source: Return only documents belonging to these source IDs (`cso_...`). Multiple values are OR'd.
118            installation: Return only documents belonging to these installation IDs. Multiple values are OR'd.
119            agent: Return only documents owned by these agent IDs. Multiple values are OR'd.
120
121        Returns:
122            Successful response
123        """
124        query: dict[str, object] = {}
125        if page is not None:
126            query["page"] = page
127        if page_size is not None:
128            query["page_size"] = page_size
129        if q is not None:
130            query["q"] = q
131        if source is not None:
132            query["source"] = source
133        if installation is not None:
134            query["installation"] = installation
135        if agent is not None:
136            query["agent"] = agent
137        return await self._http.request(
138            "/api/v1/knowledge_documents",
139            query=query,
140            response_type=KnowledgeDocumentListResponse,
141        )

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: 
143    async def delete(self, document: str) -> None:
144        """
145        Delete a context document
146        Permanently deletes a context document and all of its associated chunk
147        items. This action is irreversible.
148        The backing storage file, if any, is not deleted storage files can be
149        shared across multiple documents and are cleaned up separately by the
150        platform's storage garbage collector. The caller must be authenticated
151        and the request must be scoped to the app that owns the document.
152
153        Args:
154            document: Document ID (`cdo_...`) to delete.
155
156        Returns:
157            Empty body. Returns HTTP 204 on success.
158        """
159        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: 
161    async def get(self, document: str) -> ContextDocument:
162        """
163        Retrieve a context document
164        Returns a single context document identified by its ID. The response
165        includes document metadata such as title, size, and ownership fields,
166        but not the document's text content. To read the full or partial content,
167        use the content endpoint.
168        The caller must be authenticated and the request must be scoped to the
169        app that owns the document.
170
171        Args:
172            document: Document ID (`cdo_...`) to retrieve.
173
174        Returns:
175            The requested context document's metadata.
176        """
177        return await self._http.request(
178            f"/api/v1/knowledge_documents/{document}",
179            response_type=ContextDocument,
180        )

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 content( self, document: str, *, offset: int | None = None, limit: int | None = None, unit: str | None = None) -> archastro.platform.types.common.ContextDocumentContent: 
182    async def content(
183        self,
184        document: str,
185        *,
186        offset: int | None = None,
187        limit: int | None = None,
188        unit: str | None = None,
189    ) -> ContextDocumentContent:
190        """
191        Retrieve a context document's content
192        Returns the full text of a context document, or a slice of it when
193        `offset`, `limit`, and `unit` are supplied. Both file-backed and inline
194        documents are supported; the response shape is the same in either case.
195        When slicing, set `unit` to `"lines"` (default) or `"bytes"`. A line-based
196        slice uses a 1-indexed `offset`; a byte-based slice uses a 0-indexed
197        `offset`. If you omit `offset`, the full document text is returned and the
198        slice-specific response fields (`unit`, `offset`, `limit`, `start_line`,
199        `end_line`, `start_byte`, `end_byte`) are absent.
200        The caller must be authenticated and the request must be scoped to an app
201        that owns the document.
202
203        Args:
204            document: Document ID (`cdo_...`) whose content to retrieve.
205            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.
206            limit: Maximum number of units to return when slicing. Defaults to 200 when `unit` is `"lines"` and 8192 when `unit` is `"bytes"`.
207            unit: Unit to use for `offset` and `limit`. One of `"lines"` (default) or `"bytes"`.
208
209        Returns:
210            The document's content, optionally sliced by offset and limit.
211        """
212        query: dict[str, object] = {}
213        if offset is not None:
214            query["offset"] = offset
215        if limit is not None:
216            query["limit"] = limit
217        if unit is not None:
218            query["unit"] = unit
219        return await self._http.request(
220            f"/api/v1/knowledge_documents/{document}/content",
221            query=query,
222            response_type=ContextDocumentContent,
223        )

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: 
226class KnowledgeDocumentResource:
227    def __init__(self, http: SyncHttpClient):
228        self._http = http
229
230    def list(
231        self,
232        *,
233        page: int | None = None,
234        page_size: int | None = None,
235        q: str | None = None,
236        source: builtins.list[str] | None = None,
237        installation: builtins.list[str] | None = None,
238        agent: builtins.list[str] | None = None,
239    ) -> KnowledgeDocumentListResponse:
240        """
241        List context documents
242        Returns a paginated list of context documents visible to the authenticated
243        caller within the scoped app. Results are ordered by creation time
244        descending.
245        Use `q` for a case-insensitive title prefix search. Use `source`,
246        `installation`, or `agent` to narrow results to documents belonging to
247        specific sources, installations, or agents. Multiple values within each
248        filter are treated as OR conditions. Filters may be combined.
249        The response includes page-level metadata so you can navigate through
250        large result sets without cursor tokens.
251
252        Args:
253            page: Page number to return. Defaults to 1.
254            page_size: Number of documents per page. Defaults to 25.
255            q: Case-insensitive prefix filter applied to the document title.
256            source: Return only documents belonging to these source IDs (`cso_...`). Multiple values are OR'd.
257            installation: Return only documents belonging to these installation IDs. Multiple values are OR'd.
258            agent: Return only documents owned by these agent IDs. Multiple values are OR'd.
259
260        Returns:
261            Successful response
262        """
263        query: dict[str, object] = {}
264        if page is not None:
265            query["page"] = page
266        if page_size is not None:
267            query["page_size"] = page_size
268        if q is not None:
269            query["q"] = q
270        if source is not None:
271            query["source"] = source
272        if installation is not None:
273            query["installation"] = installation
274        if agent is not None:
275            query["agent"] = agent
276        return self._http.request(
277            "/api/v1/knowledge_documents",
278            query=query,
279            response_type=KnowledgeDocumentListResponse,
280        )
281
282    def delete(self, document: str) -> None:
283        """
284        Delete a context document
285        Permanently deletes a context document and all of its associated chunk
286        items. This action is irreversible.
287        The backing storage file, if any, is not deleted storage files can be
288        shared across multiple documents and are cleaned up separately by the
289        platform's storage garbage collector. The caller must be authenticated
290        and the request must be scoped to the app that owns the document.
291
292        Args:
293            document: Document ID (`cdo_...`) to delete.
294
295        Returns:
296            Empty body. Returns HTTP 204 on success.
297        """
298        self._http.request(f"/api/v1/knowledge_documents/{document}", method="DELETE")
299
300    def get(self, document: str) -> ContextDocument:
301        """
302        Retrieve a context document
303        Returns a single context document identified by its ID. The response
304        includes document metadata such as title, size, and ownership fields,
305        but not the document's text content. To read the full or partial content,
306        use the content endpoint.
307        The caller must be authenticated and the request must be scoped to the
308        app that owns the document.
309
310        Args:
311            document: Document ID (`cdo_...`) to retrieve.
312
313        Returns:
314            The requested context document's metadata.
315        """
316        return self._http.request(
317            f"/api/v1/knowledge_documents/{document}",
318            response_type=ContextDocument,
319        )
320
321    def content(
322        self,
323        document: str,
324        *,
325        offset: int | None = None,
326        limit: int | None = None,
327        unit: str | None = None,
328    ) -> ContextDocumentContent:
329        """
330        Retrieve a context document's content
331        Returns the full text of a context document, or a slice of it when
332        `offset`, `limit`, and `unit` are supplied. Both file-backed and inline
333        documents are supported; the response shape is the same in either case.
334        When slicing, set `unit` to `"lines"` (default) or `"bytes"`. A line-based
335        slice uses a 1-indexed `offset`; a byte-based slice uses a 0-indexed
336        `offset`. If you omit `offset`, the full document text is returned and the
337        slice-specific response fields (`unit`, `offset`, `limit`, `start_line`,
338        `end_line`, `start_byte`, `end_byte`) are absent.
339        The caller must be authenticated and the request must be scoped to an app
340        that owns the document.
341
342        Args:
343            document: Document ID (`cdo_...`) whose content to retrieve.
344            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.
345            limit: Maximum number of units to return when slicing. Defaults to 200 when `unit` is `"lines"` and 8192 when `unit` is `"bytes"`.
346            unit: Unit to use for `offset` and `limit`. One of `"lines"` (default) or `"bytes"`.
347
348        Returns:
349            The document's content, optionally sliced by offset and limit.
350        """
351        query: dict[str, object] = {}
352        if offset is not None:
353            query["offset"] = offset
354        if limit is not None:
355            query["limit"] = limit
356        if unit is not None:
357            query["unit"] = unit
358        return self._http.request(
359            f"/api/v1/knowledge_documents/{document}/content",
360            query=query,
361            response_type=ContextDocumentContent,
362        )
KnowledgeDocumentResource(http: archastro.platform.runtime.http_client.SyncHttpClient) 
227    def __init__(self, http: SyncHttpClient):
228        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: 
230    def list(
231        self,
232        *,
233        page: int | None = None,
234        page_size: int | None = None,
235        q: str | None = None,
236        source: builtins.list[str] | None = None,
237        installation: builtins.list[str] | None = None,
238        agent: builtins.list[str] | None = None,
239    ) -> KnowledgeDocumentListResponse:
240        """
241        List context documents
242        Returns a paginated list of context documents visible to the authenticated
243        caller within the scoped app. Results are ordered by creation time
244        descending.
245        Use `q` for a case-insensitive title prefix search. Use `source`,
246        `installation`, or `agent` to narrow results to documents belonging to
247        specific sources, installations, or agents. Multiple values within each
248        filter are treated as OR conditions. Filters may be combined.
249        The response includes page-level metadata so you can navigate through
250        large result sets without cursor tokens.
251
252        Args:
253            page: Page number to return. Defaults to 1.
254            page_size: Number of documents per page. Defaults to 25.
255            q: Case-insensitive prefix filter applied to the document title.
256            source: Return only documents belonging to these source IDs (`cso_...`). Multiple values are OR'd.
257            installation: Return only documents belonging to these installation IDs. Multiple values are OR'd.
258            agent: Return only documents owned by these agent IDs. Multiple values are OR'd.
259
260        Returns:
261            Successful response
262        """
263        query: dict[str, object] = {}
264        if page is not None:
265            query["page"] = page
266        if page_size is not None:
267            query["page_size"] = page_size
268        if q is not None:
269            query["q"] = q
270        if source is not None:
271            query["source"] = source
272        if installation is not None:
273            query["installation"] = installation
274        if agent is not None:
275            query["agent"] = agent
276        return self._http.request(
277            "/api/v1/knowledge_documents",
278            query=query,
279            response_type=KnowledgeDocumentListResponse,
280        )

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: 
282    def delete(self, document: str) -> None:
283        """
284        Delete a context document
285        Permanently deletes a context document and all of its associated chunk
286        items. This action is irreversible.
287        The backing storage file, if any, is not deleted storage files can be
288        shared across multiple documents and are cleaned up separately by the
289        platform's storage garbage collector. The caller must be authenticated
290        and the request must be scoped to the app that owns the document.
291
292        Args:
293            document: Document ID (`cdo_...`) to delete.
294
295        Returns:
296            Empty body. Returns HTTP 204 on success.
297        """
298        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: 
300    def get(self, document: str) -> ContextDocument:
301        """
302        Retrieve a context document
303        Returns a single context document identified by its ID. The response
304        includes document metadata such as title, size, and ownership fields,
305        but not the document's text content. To read the full or partial content,
306        use the content endpoint.
307        The caller must be authenticated and the request must be scoped to the
308        app that owns the document.
309
310        Args:
311            document: Document ID (`cdo_...`) to retrieve.
312
313        Returns:
314            The requested context document's metadata.
315        """
316        return self._http.request(
317            f"/api/v1/knowledge_documents/{document}",
318            response_type=ContextDocument,
319        )

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 content( self, document: str, *, offset: int | None = None, limit: int | None = None, unit: str | None = None) -> archastro.platform.types.common.ContextDocumentContent: 
321    def content(
322        self,
323        document: str,
324        *,
325        offset: int | None = None,
326        limit: int | None = None,
327        unit: str | None = None,
328    ) -> ContextDocumentContent:
329        """
330        Retrieve a context document's content
331        Returns the full text of a context document, or a slice of it when
332        `offset`, `limit`, and `unit` are supplied. Both file-backed and inline
333        documents are supported; the response shape is the same in either case.
334        When slicing, set `unit` to `"lines"` (default) or `"bytes"`. A line-based
335        slice uses a 1-indexed `offset`; a byte-based slice uses a 0-indexed
336        `offset`. If you omit `offset`, the full document text is returned and the
337        slice-specific response fields (`unit`, `offset`, `limit`, `start_line`,
338        `end_line`, `start_byte`, `end_byte`) are absent.
339        The caller must be authenticated and the request must be scoped to an app
340        that owns the document.
341
342        Args:
343            document: Document ID (`cdo_...`) whose content to retrieve.
344            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.
345            limit: Maximum number of units to return when slicing. Defaults to 200 when `unit` is `"lines"` and 8192 when `unit` is `"bytes"`.
346            unit: Unit to use for `offset` and `limit`. One of `"lines"` (default) or `"bytes"`.
347
348        Returns:
349            The document's content, optionally sliced by offset and limit.
350        """
351        query: dict[str, object] = {}
352        if offset is not None:
353            query["offset"] = offset
354        if limit is not None:
355            query["limit"] = limit
356        if unit is not None:
357            query["unit"] = unit
358        return self._http.request(
359            f"/api/v1/knowledge_documents/{document}/content",
360            query=query,
361            response_type=ContextDocumentContent,
362        )

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.