@spec content(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.GetApiV1KnowledgeDocumentsDocumentContent.Params.t()
) ::
  {:ok, ArchAstro.Types.ContextDocumentContent.t()}
  | {:error, ArchAstro.Error.reason()}

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.

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

@spec delete(ArchAstro.Client.t(), String.t()) ::
  {:ok, :ok} | {:error, ArchAstro.Error.reason()}

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.

Empty body. Returns HTTP 204 on success.

@spec get(ArchAstro.Client.t(), String.t()) ::
  {:ok, ArchAstro.Types.ContextDocument.t()}
  | {:error, ArchAstro.Error.reason()}

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.

The requested context document's metadata.

@spec list(
  ArchAstro.Client.t(),
  ArchAstro.Types.Operations.GetApiV1KnowledgeDocuments.Params.t()
) ::
  {:ok, ArchAstro.Types.Operations.GetApiV1KnowledgeDocuments.Response.t()}
  | {:error, ArchAstro.Error.reason()}

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.

Successful response

@spec update(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.PatchApiV1KnowledgeDocumentsDocument.Input.t()
) ::
  {:ok, ArchAstro.Types.ContextIngestion.t()}
  | {:error, ArchAstro.Error.reason()}

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.

The ingestion performing the document update.