Upload Content

Select a knowledge base

Register a Knowledge with contents_db on AgentOS, an Agent or a Team. Read the actual generated ID from GET /config under knowledge.knowledge_instances; use that knowledge_id in the request's selector. It is not an arbitrary Knowledge.id. A selector is required when multiple instances make the request ambiguous (400); no configured knowledge base returns 503. If both selectors are supplied, knowledge_id takes precedence over db_id.

Ingestion and search also require suitable readers, vector storage, an embedder where needed, and their dependencies and credentials. See Knowledge.

Content access

Scoped callers can read their own and shared content; other-owned records return 404. JWT user scoping requires user isolation, while non-admin service-account PAT users always self-scope. A scoped caller cannot modify, refresh or delete shared content (403). Authentication alone does not enable JWT user isolation.

Submit content

Send one nonempty content source: file, text_content or url. For example, with KNOWLEDGE_ID from /config and your AgentOS server running locally:

curl --fail-with-body \
  "http://127.0.0.1:7777/knowledge/content?knowledge_id=$KNOWLEDGE_ID" \
  -H "Authorization: Bearer $OS_SECURITY_KEY" \
  -F 'name=Session guide' -F 'text_content=Sessions group an agent conversation.' \
  -F 'metadata={"category":"guide"}'

Provide metadata as a JSON object. Current main can accept an empty request or malformed metadata instead of returning the generated 400 error, so validate your input before submission.

Choose a valid reader_id from the installed configuration when selecting a chunker. An unresolved reader ID silently falls back, and chunker settings are applied only when a reader is resolved.

Processing status

202 acknowledges an in-process background task, not successful persistence or ingestion. Work is not a durable queue job and can be lost on process restart. Poll the returned ID's status; a row can initially be absent, or remain absent if processing never creates it. The owner is captured before background processing starts.

curl --request POST 'https://example.com/knowledge/content'

{  "id": "content-123",  "name": "example-document.pdf",  "description": "Sample document for processing",  "metadata": {    "category": "documentation",    "priority": "high"  },  "status": "processing"}

{  "detail": "string",  "error_id": "string",  "error_type": "string"}

{  "detail": "string",  "error_id": "string",  "error_type": "string"}

{  "detail": "string",  "error_id": "string",  "error_type": "string"}

{  "detail": "string"}

{  "detail": "string",  "error_id": "string",  "error_type": "string"}