@spec create(
  ArchAstro.Client.t(),
  ArchAstro.Types.Operations.PostApiV1KnowledgeSources.Input.t()
) ::
  {:ok, ArchAstro.Types.KnowledgeSource.t()}
  | {:error, ArchAstro.Error.reason()}

Create a knowledge source

Creates a new knowledge source of the requested type and returns the created object.

Only types listed by GET /api/v1/knowledge_sources/kinds may be created through this endpoint. Other source types — such as webhook/inbound, connectors/*/emails, and thread/messages — are provisioned automatically by server-driven flows (webhook auto-provisioning, installation activation, connector lifecycle events) and cannot be created directly via the API.

Exactly one of team, user, agent, or org must identify the owner of the new source. Omit org when an individual owner (team, user, or agent) is supplied; include org alone for org-level system-owned sources.

The newly created knowledge source.

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

Delete a knowledge source

Permanently deletes the knowledge source identified by source. This action is irreversible — all documents, embeddings, and ingestion history associated with the source are removed.

The authenticated caller must own the source or have sufficient permissions within its parent organization. Returns 204 No Content on success.

Empty response. The source has been permanently deleted.

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

Retrieve a knowledge source

Returns the knowledge source identified by source. The authenticated caller must have access to the source's parent organization or be the individual owner of the source.

Use the list endpoint to retrieve many sources at once or to discover sources by type or owner.

The requested knowledge source.

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

Trigger ingestion on a knowledge source

Starts an ingestion run on the specified knowledge source and returns the ingestion object. Exactly one of two modes must be chosen per request:

Push mode (file or content) — available for knowledge/documents sources only. Supply the document bytes either as a reference to an already-uploaded file (file) or as an inline blob (content). The runner stores the bytes and indexes the resulting document. title and metadata are persisted on the document in push mode.

Pull mode (pull: true) — re-triggers ingestion using the source's own configured data. Use this to re-scrape a scrape/site, re-fetch a web/link, or re-process a file/document. Not valid for knowledge/documents (which has no upstream — push new bytes instead) or for source kinds populated by server-driven flows. title and metadata are ignored in pull mode.

If an ingestion is already active for the source, the existing ingestion is returned rather than creating a duplicate.

The created ingestion, or an existing active ingestion if one is already running.

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

List knowledge sources

Returns a paginated list of knowledge sources visible to the authenticated caller. Results are ordered by creation time descending.

Use the type, installation, agent, org, and owner_scope filters to narrow the result set. Combine owner_scope: "system" with org to list org-level sources that have no individual owner. Combine owner_scope: "individual" with agent to list sources owned by a specific agent.

Pagination is page-number based. The default page size is 25.

Successful response

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

Update a knowledge source

Updates the mutable fields of an existing knowledge source and returns the updated object. Only fields provided in the request body are changed; omitted fields retain their current values.

You can update the type-specific payload, the metadata map, and the state. To pause a source and prevent automatic ingestion, set state to "paused". To resume, set it back to "active".

The updated knowledge source.