Skip to navigation
API referenceKnowledge Sources

Read source readiness

Poll for ready/fallback/failed. No ingestion on read.

Authentication

AuthorizationBearer

Create and manage workspace-owned keys through the existing app session routes, outside this public API. Creator and manager identities are audit actors only. Key validity follows workspace policy, expiry and explicit revocation, independently of creator membership. Do not include a workspace-selection header.

Path parameters

source_idstringRequired1-128 characters
Resource identity within the authenticated workspace.

Response headers

X-Request-IdstringOptional
Safe server request correlation ID.
ETagstringOptional

Strong knowledge-source revision. Use this ETag for edits to this resource. Draft ETags cover complete authoring inputs.

RateLimit-LimitintegerOptional
Requests allowed in the current window for the tightest applicable limit.
RateLimit-RemainingintegerOptional
Requests left in the current window.
RateLimit-ResetintegerOptional
Seconds until the current window resets.

Response

Read source readiness.
idstring<=128 characters
Opaque kb identifier. Do not parse its contents.
namestring
kindstring

Open response vocabulary. Preserve unknown values; never assume they mean success.

statestring

pending and ingesting are in progress: keep polling. Settled states: ready (retrieval-ready), fallback (text could not be indexed but can be frozen as bounded prompt context when the source is in an agent library), failed (read failure), archived (hidden from new library selection; retained published evidence keeps working). Open response vocabulary. Preserve unknown values; never assume they mean success.

revisionstring
created_atdatetime
failurestring or null
Safe registered reason.
content_sha256string or null
content_bytesinteger or null>=0
media_typestring or null
ingested_atdatetime or null
updated_atdatetime
ownerobject
resource_keystring or nullformat: "^[A-Za-z0-9][A-Za-z0-9._:~-]{0,127}$"1-128 characters

Optional caller-chosen resource key: an opaque external identifier that matches your own record (for example a CRM ID, a configuration-file ID or a UUID) to this resource. Rasen still generates the canonical id; use id in paths and references. Case-sensitive, compared exactly, never normalized or parsed. 1-128 characters from A-Z a-z 0-9 . _ : ~ - and starting with a letter or digit; UUIDs and ULIDs are valid. Unique per resource type within one workspace; separate environment workspaces can reuse the same key. Set only at creation and immutable afterwards. A create with a key that already exists returns 409 resource_key_conflict with details.existing_id; it never updates or returns the existing resource. Not an Idempotency-Key: that header identifies one request intent for 24 hours, and a same-intent replay returns its original receipt before the resource-key check runs. Uniqueness includes archived resources. A key becomes free again only after its resource is permanently deleted or erased (a deleted secret or a deleted knowledge source); archive never frees it.

poll_after_secondsinteger or null>=1
Seconds to wait before the next read while state is pending or ingesting. Null when the state is settled.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error