Context0 API Reference

2026-09-16: Knowledge base permission refactoring: four behavior changes

This refactoring changes knowledge base authorization from "allow unless explicitly denied" to default-deny, with roles viewer < editor < owner. The following four changes affect the observable behavior of existing callers. Confirm them before you upgrade (items 1 and 4 are relaxations; items 2 and 3 are tightened restrictions or code changes):

1. Public knowledge base default level raised to writable.visibility=workspace (alias public): the default role of any member in the workspace is editor. Members can not only search and read, but also upload and delete documents in the knowledge base (including documents uploaded by others). If this is not desired, change the knowledge base to private and grant permissions as needed, or add an explicit viewer row for specific members (see "Knowledge base permissions (ACL)" in the Knowledge section).

2. ACL row expiration is a hard invalidation. An authorization row with an expired expires_at is treated as nonexistent: callers fall back directly to the knowledge base default level (public knowledge base: editor / private knowledge base: no access), and no residual "once authorized" permissions are retained. Expired rows still appear in the ACL list for easier cleanup.

3. Cross-workspace responses on the graph data plane changed from 403 to 404.GET /v1/knowledge-bases/{kbId}/graph/nodes|edges previously returned 403, and now returns 404 when the knowledge base ID (kbId) belongs to another workspace or does not exist (without leaking the existence of the knowledge base ID). Clients that fall back on the 403 branch must also accept 404.

4. User Key knowledge base deletion no longer recognizes only the creator.DELETE /v1/knowledge/bases/{id} previously applied a separate "creator" check for User Keys: a member explicitly granted owner received my_role=owner but still could not delete the knowledge base. This is now unified into the ACL decision chain: owner is sufficient to delete.

Insufficient permissions uniformly returns 403 + code=40303 (ACL_FORBIDDEN). A knowledge base ID that belongs to another workspace or does not exist uniformly returns 404. Knowledge base detail and list responses add my_role / role_source / can_manage_acl, so callers can render entries accordingly instead of probing permissions by "trying once to see whether a 403 is returned".

POST /v1/context/ingest

Writes a batch of conversation messages to a specified session and triggers subsequent memory extraction and deduplication.

curl -X POST http://<host>:4040/v1/context/ingest \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess-2026-08-19-001",
    "user_id": "alice",
    "messages": [
      {"role": "user", "content": "I have been learning Rust recently"},
      {"role": "assistant", "content": "Rust is a systems programming language focused on safety and performance."}
    ],
    "extract_mode": "eager"
  }'

{
  "code": 0, "msg": "ok",
  "data": {
    "session_id": "sess-2026-08-19-001",
    "session_internal_id": 42,
    "message_ids": [
      {"id": 1, "seq": 1},
      {"id": 2, "seq": 2}
    ],
    "event_id": 789
  },
  "trace_id": "trace-001"
}

POST /v1/context/assemble

Assembles LLM-facing context PromptBlocks based on a query and returns recalled memories and source references. This is the core endpoint that agents call on every conversation turn.

curl -X POST http://<host>:4040/v1/context/assemble \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess-2026-08-19-001",
    "query": "What is Rust's ownership mechanism?",
    "token_budget": 4096,
    "recall": {"top_k": 10, "cosine_threshold": 0.3}
  }'

{
  "code": 0, "msg": "ok",
  "data": {
    "prompt_blocks": [
      {"role": "system", "tag": "user_profile", "content": "The user is learning Rust...", "tokens": 42, "sources": ["memory:mem_1_2_abc"]},
      {"role": "system", "tag": "memory_recall", "content": "- The user likes systems programming\n- ...", "tokens": 128, "sources": ["memory:mem_1_2_def"]},
      {"role": "system", "tag": "recent_history", "content": "...", "tokens": 256, "sources": []}
    ],
    "token_used": 426,
    "token_budget": 4096,
    "trace_id": "trace-001",
    "stats": {
      "recall_total": 5,
      "recall_kept": 3,
      "messages_total": 20,
      "messages_kept": 10,
      "took_ms": 142,
      "multimodal_kept": 0
    }
  }
}

POST /v1/context/compact

Incrementally compresses the session context, folding the earliest active messages into leaf summaries by chunk_size.

curl -X POST http://<host>:4040/v1/context/compact \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"session_id": "sess-2026-08-19-001", "keep_recent_n": 30}'

{
  "code": 0, "msg": "ok",
  "data": {
    "session_id": "sess-2026-08-19-001",
    "session_internal_id": 42,
    "summary_message_id": 101,
    "compacted_message_count": 20,
    "summary_token_count": 180,
    "active_message_count": 50,
    "depth": 0,
    "source_seq_range": [1, 20]
  }
}

POST /v1/context/flush

Persists short-term context as long-term memories and events.

curl -X POST http://<host>:4040/v1/context/flush \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"session_id": "sess-2026-08-19-001", "compact_first": true}'

{
  "code": 0, "msg": "ok",
  "data": {
    "session_id": "sess-2026-08-19-001",
    "session_internal_id": 42,
    "status": "flushed",
    "flushed_at": "2026-08-19T10:30:00Z",
    "compact_summary": {
      "session_id": "sess-2026-08-19-001",
      "compacted_message_count": 20,
      "summary_token_count": 180,
      "active_message_count": 30
    },
    "evolve_event_id": 1001
  }
}

POST /v1/context/lifecycle

Reports context lifecycle events and drives the session state machine by dispatching on action. action=start creates or opens a session and returns the first-screen assembled PromptBlocks; action=end closes the session and returns closing statistics.

POST /v1/sessions

Creates a session or retrieves an existing one (idempotent). If the externalId already exists, the existing session is returned.

curl -X POST http://<host>:4040/v1/sessions \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"external_id": "sess-2026-08-19-001", "agent_id": "my-agent", "user_id": "alice"}'

{
  "code": 0, "msg": "ok",
  "data": {
    "session": {
      "id": 1,
      "external_id": "sess-2026-08-19-001",
      "agent_id": "my-agent",
      "user_id": "alice",
      "status": "open",
      "title": null,
      "message_count": 0,
      "total_tokens": 0,
      "session_key": null,
      "parent_session_id": null,
      "created_at": "2026-08-19T10:00:00Z",
      "updated_at": "2026-08-19T10:00:00Z",
      "closed_at": null
    },
    "created": true
  }
}

GET /v1/sessions

Lists sessions of the current tenant by page. A User Key sees only its own sessions; Owner Key sees the entire workspace.

curl "http://<host>:4040/v1/sessions?status=open&page_size=10" \
  -H "X-API-Key: $API_KEY"

GET /v1/sessions/{id}

Retrieves details of a specified session.{id} is the externalId or the internal ID.

curl "http://<host>:4040/v1/sessions/sess-2026-08-19-001" \
  -H "X-API-Key: $API_KEY"

PATCH /v1/sessions/{id}

Partially updates session attributes (such as title or metadata).

curl -X PATCH http://<host>:4040/v1/sessions/sess-2026-08-19-001 \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"title": "Rust study session"}'

POST /v1/sessions/{id}/messages

Appends a batch of messages to a session.

curl -X POST http://<host>:4040/v1/sessions/sess-2026-08-19-001/messages \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "What is a borrow checker?"}]}'

GET /v1/sessions/{id}/messages

Pulls session messages incrementally by since_seq or in reverse order by before_seq.

curl "http://<host>:4040/v1/sessions/sess-2026-08-19-001/messages?since_seq=0&limit=50" \
  -H "X-API-Key: $API_KEY"

PUT /v1/sessions/{id}/close

Closes a session and optionally generates a handoff summary.

curl -X PUT http://<host>:4040/v1/sessions/sess-2026-08-19-001/close \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"generate_summary": true}'

DELETE /v1/sessions/{id}

Physically deletes a specified session and its messages.

curl -X DELETE http://<host>:4040/v1/sessions/sess-2026-08-19-001 \
  -H "X-API-Key: $API_KEY"

GET /v1/sessions/{id}/inheritance

Returns the inheritance chain of a session, showing cross-session context transfer relationships.

curl "http://<host>:4040/v1/sessions/sess-2026-08-19-001/inheritance" \
  -H "X-API-Key: $API_KEY"

GET /v1/sessions/stats

Returns aggregated session statistics (total/active/closed/inherited/cumulative tokens).

curl "http://<host>:4040/v1/sessions/stats" -H "X-API-Key: $API_KEY"

{
  "code": 0, "msg": "ok",
  "data": {
    "total": 5,
    "open": 4,
    "closed": 1,
    "inherited": 0,
    "total_tokens": 32
  }
}

GET /v1/sessions/{id}/token-stats

Returns token usage statistics of a specified session, including per-role token counts and the tokenizer used.

curl "http://<host>:4040/v1/sessions/3/token-stats" -H "X-API-Key: $API_KEY"

{
  "code": 0, "msg": "ok",
  "data": {
    "total_tokens": 26,
    "message_count": 4,
    "by_role": {
      "user": 23,
      "assistant": 3
    },
    "token_estimator": "cl100k_base"
  }
}

POST /v1/memories

Mem0-compatible memory creation API. Automatically triggers deduplication and distillation.

curl -X POST http://<host>:4040/v1/memories \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "I like using the Vim editor"},
      {"role": "assistant", "content": "OK, I noted your preference for Vim."}
    ],
    "user_id": "alice"
  }'

{"results": [{"id": "mem_1_2_abc123", "memory": "User prefers using the Vim editor", "event": "ADD"}]}

POST /v3/memories/add

V3 memory write. Returns a Box response containing memory_id / event_id / created. Request parameters: same as POST /v1/memories.

curl -X POST http://<host>:4040/v3/memories/add \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "My tech stack is Java + Spring Boot"}],
    "user_id": "alice"
  }'

{"code": 0, "msg": "ok", "data": {"memory_id": "mem_1_2_def456", "event_id": "evt_789", "created": true}}

POST /v3/memories

Mem0 v1.1 SDK-compatible memory list API. Entity filter parameters (user_id / agent_id / run_id) can be placed at the top level of the request body or in the filters map. Pagination is controlled through query parameters. Returns the same pagination envelope as Mem0 cloud (bare JSON, without the Box wrapper).

curl -X POST "http://<host>:4040/v3/memories?page=1&page_size=50" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id": "alice"}'

{
  "count": 156,
  "next": "/v3/memories/?page=2&page_size=50",
  "previous": null,
  "results": [
    {"id": "mem_1_2_abc123", "memory": "User prefers using the Vim editor", "metadata": {}}
  ]
}

POST /v3/entity_cards/{id}/edit

Performs a partial update on the role / preferences / attributes of an L0 entity card. Only the fields provided are overwritten; fields not provided (null) remain unchanged.

curl -X POST http://<host>:4040/v3/entity_cards/card_1_2_alice/edit \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"role": "Senior backend engineer", "preferences": ["Java", "Spring Boot"]}'

{
  "code": 0, "msg": "ok",
  "data": {
    "card_id": "card_1_2_alice",
    "metadata": {"role": "Senior backend engineer", "preferences": ["Java", "Spring Boot"], "attributes": {}}
  }
}

GET /v1/memories

Lists memories by page, filtered by user_id / agent_id / run_id. Mem0-compatible bare JSON array response.

curl "http://<host>:4040/v1/memories?user_id=alice&limit=20" \
  -H "X-API-Key: $API_KEY"

GET /v1/memories/{id}

Retrieves details of a single memory by memory_id.

curl "http://<host>:4040/v1/memories/mem_1_2_abc123" -H "X-API-Key: $API_KEY"

PUT /v1/memories/{id}

Updates the content or metadata of a specified memory.

curl -X PUT http://<host>:4040/v1/memories/mem_1_2_abc123 \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"text": "User prefers using the Neovim editor"}'

DELETE /v1/memories/{id}

Deletes a single memory.

curl -X DELETE http://<host>:4040/v1/memories/mem_1_2_abc123 -H "X-API-Key: $API_KEY"

{"message": "memory deleted", "id": "mem_1_2_abc123"}

DELETE /v1/memories/clear

Bulk cleanup of memories, deleting by scope. This is an irreversible operation and requires confirm=true.

curl -X DELETE http://<host>:4040/v1/memories/clear \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"confirm": true, "scope": "all"}'

{"message": "memories cleared", "deleted": 42, "scope": "all"}

POST /v1/memories/search

V1 memory semantic search. L1-only (no L2 source-text BM25 recall), serving as the Mem0 baseline path.

curl -X POST http://<host>:4040/v1/memories/search \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"query": "What editor does the user like?", "user_id": "alice", "limit": 5}'

[
  {"id": "mem_1_2_abc123", "memory": "User prefers using the Vim editor", "score": 0.92, "metadata": {}},
  {"id": "mem_1_2_def456", "memory": "The user uses Neovim plugins", "score": 0.85, "metadata": {}}
]

POST /v2/memories/search

V2 memory search with L1 + L2 source-text BM25 recall. Compared with V1, it additionally performs BM25 search over L2 source texts, suitable for scenarios that require source traceability.

curl -X POST "$HOST/v2/memories/search"

POST /v3/memories/search

V3 search in the Mem0 v1.1 SDK-compatible format.user_id entity parameters are placed in the filters map.

curl -X POST http://<host>:4040/v3/memories/search \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"query": "The user's tech stack", "filters": {"user_id": "alice"}, "limit": 10}'

{"results": [{"id": "mem_1_2_def456", "memory": "The user's tech stack is Java + Spring Boot", "score": 0.88}]}

POST /v1/memories/{id}/pin

Pins a memory to raise its recall priority.

curl -X POST http://<host>:4040/v1/memories/mem_1_2_abc123/pin -H "X-API-Key: $API_KEY"

POST /v1/memories/{id}/unpin

Unpins a memory.

curl -X POST http://<host>:4040/v1/memories/mem_1_2_abc123/unpin -H "X-API-Key: $API_KEY"

POST /v3/memories/{id}/invalidate

Marks a memory as invalid (invalid_at=now()) so that it is no longer recalled by search.

curl -X POST http://<host>:4040/v3/memories/mem_1_2_abc123/invalidate -H "X-API-Key: $API_KEY"

{"code": 0, "msg": "ok", "data": {"id": "mem_1_2_abc123", "invalid_at": "2026-08-19T10:30:00Z"}}

POST /v3/memories/{id}/promote

Promotes session-scoped memories to user scope so that they persist across sessions.

curl -X POST http://<host>:4040/v3/memories/mem_1_2_abc123/promote -H "X-API-Key: $API_KEY"

GET /v1/memories/{id}/history

Returns all version change records of a specified memory. Mem0-compatible bare JSON array.

curl "http://<host>:4040/v1/memories/mem_1_2_abc123/history" -H "X-API-Key: $API_KEY"

[
  {"id": 1, "version": 1, "event_type": "ADD", "content_after": "User prefers Vim", "created_at": "2026-08-19T10:00:00Z"},
  {"id": 2, "version": 2, "event_type": "UPDATE", "content_before": "User prefers Vim", "content_after": "User prefers Neovim", "created_at": "2026-08-19T11:00:00Z"}
]

GET /v1/memories/{id}/source-texts

Views the L2 original conversation messages that produced this L1 memory (traceability).

curl "http://<host>:4040/v1/memories/mem_1_2_abc123/source-texts" -H "X-API-Key: $API_KEY"

GET /v1/memories/distill-prompt

Queries the distillation rule configuration and effective status of the current member. OWNER permissions are not required; every authenticated member can manage their own distillation rules.

curl "http://<host>:4040/v1/memories/distill-prompt" -H "X-API-Key: $API_KEY"

{
  "code": 0, "msg": "ok",
  "data": {
    "configured": true,
    "custom_prompt": "Focus on extracting the user's tech stack preferences and workflow habits",
    "enabled": true,
    "rollout_enabled": true,
    "effective": true,
    "effective_source": "member_level",
    "updated_at": "2026-08-19T10:00:00Z",
    "member_id": 2
  }
}

PUT /v1/memories/distill-prompt

Creates or updates the distillation rules of the current member and returns the complete updated state.

curl -X PUT http://<host>:4040/v1/memories/distill-prompt \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"custom_prompt": "Focus on extracting the user's tech stack preferences and workflow habits", "enabled": true}'

DELETE /v1/memories/distill-prompt

Deletes the distillation rules of the current member (idempotent). After deletion, it falls back to the workspace default or built-in prompt.

curl -X DELETE http://<host>:4040/v1/memories/distill-prompt -H "X-API-Key: $API_KEY"

{"code": 0, "msg": "ok", "data": null}

POST /v3/memories/{id}/feedback

Submits memory feedback signals (thumbs up/down / explicit/implicit feedback). Negative feedback triggers the Dream counter-evidence pipeline.

curl -X POST http://<host>:4040/v3/memories/mem_1_2_abc123/feedback \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"signal_type": "negative_explicit", "recall_path": "vector", "corrected_content": "The user has switched from Vim to Neovim"}'

GET /v3/memories/{id}/feedback

Queries the feedback history of a specified memory by page.

curl -X GET "$HOST/v3/memories/{id}/feedback"

GET /v1/memories/stats

Returns aggregated memory statistics (total/facts/entities/source texts). Box-wrapped response.

curl "http://<host>:4040/v1/memories/stats?user_id=alice" -H "X-API-Key: $API_KEY"

{"code": 0, "msg": "ok", "data": {"total": 156, "facts": 120, "entities": 12, "sources": 24}}

GET /v1/memories/relations

Queries the memory relationship graph (nodes + edges) of a specified entity for visualizing associations between memories. Returns the relationship network centered on entity_id within the specified depth.

curl "http://<host>:4040/v1/memories/relations?entity_id=alice&depth=2" -H "X-API-Key: $API_KEY"

{
  "code": 0, "msg": "ok",
  "data": {
    "nodes": [
      {"id": "alice", "label": "alice"},
      {"id": "rust-project", "label": "rust-project"}
    ],
    "edges": [
      {"from": "alice", "to": "rust-project", "label": "works_on"}
    ]
  }
}

GET /v1/memory_promotions

Lists memory promotion records of the current member by page (including manually initiated and scheduled promotions).

curl "http://<host>:4040/v1/memory_promotions?page=0&pageSize=10" -H "X-API-Key: $API_KEY"

{
  "code": 0, "msg": "ok",
  "data": {
    "content": [
      {
        "id": 1,
        "topic": "Summarize this week's architecture decisions",
        "title": null,
        "status": "generating",
        "source_type": "scheduled",
        "target_member_id": 4,
        "memory_count": 0,
        "verification_degraded": false,
        "created_at": "2026-09-16T01:03:20Z",
        "updated_at": "2026-09-16T01:03:20Z"
      }
    ],
    "total_elements": 1,
    "total_pages": 1
  }
}

POST /v1/memory_promotions/generate

Manually initiates a memory promotion run that distills the current member's memories into knowledge document candidates based on topic.

curl -X POST "http://<host>:4040/v1/memory_promotions/generate" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"topic": "Summarize this week's architecture decisions", "target_kb_id": 3}'

GET /v1/memory_promotions/{promotionId}

Retrieves details of a specified promotion record.

curl "http://<host>:4040/v1/memory_promotions/1" -H "X-API-Key: $API_KEY"

Appendix: V1/V2/V3 search version differences

Knowledge base permissions (ACL)

All four endpoints require the owner permission of this knowledge base: Owner Key passes globally; the knowledge base creator and members granted the owner role are delegated administrators; other members get 403 (40303); a kbId in another workspace or nonexistent returns 404.

Three semantics you must understand first:

• An explicit row is the final decision, not a lower bound. Writing a viewer row on a public knowledge base demotes the member from the default editor to read-only, rather than "at least viewer".

• denied is an action, not a permission level. It is used to completely turn off a member's default level on a public knowledge base; it does not appear in my_role (when access is denied, my_role is null, role_source is denied).

• expiration is a hard invalidation. An expired row is equivalent to no row at all, so the caller falls back to the knowledge base default level (public knowledge base: editor / private knowledge base: no access). Expired rows are still listed in the GET .../acl results for easier cleanup; to determine whether a row has expired, compare expires_at with the current time.

# Grant edit permission to member 42, expiring in 7 days
curl -X POST http://<host>:4040/v1/knowledge/bases/1/acl \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"subject_type": "member", "subject_id": "42", "role": "editor", "expires_at": "2026-09-23T00:00:00Z"}'

# Demote member 43 on a public knowledge base to read-only (an explicit row is the final decision, not "at least viewer")
curl -X POST http://<host>:4040/v1/knowledge/bases/1/acl \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"subject_type": "member", "subject_id": "43", "role": "viewer"}'

# Completely turn off the default level of member 44 on a public knowledge base
curl -X POST http://<host>:4040/v1/knowledge/bases/1/acl \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"subject_type": "member", "subject_id": "44", "role": "denied"}'

{"code": 0, "msg": "ok", "data": {"id": 7, "kb_id": 1, "workspace_id": 1, "subject_type": "member", "subject_id": "42", "role": "editor", "granted_by": "2", "granted_at": "2026-09-16T10:00:00Z", "expires_at": "2026-09-23T00:00:00Z", "subject_name": "alice", "subject_user_id": "u-alice"}}

curl "http://<host>:4040/v1/knowledge/bases/1/acl/candidates" -H "X-API-Key: $API_KEY"

{"code": 0, "msg": "ok", "data": [
  {"member_id": 42, "user_id": "u-alice", "name": "alice", "current_role": "editor"},
  {"member_id": 43, "user_id": "u-bob", "name": "bob", "current_role": null}
]}

curl -X DELETE http://<host>:4040/v1/knowledge/bases/1/acl/7 -H "X-API-Key: $API_KEY"

POST /v1/knowledge/bases

Creates a knowledge base.visibility When not provided, the default value depends on the key type: User Key → private, Owner Key → workspace; when explicitly provided, the provided value takes precedence (User Key can also create public knowledge bases).

curl -X POST http://<host>:4040/v1/knowledge/bases \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Project documentation library", "description": "Stores project technical documentation"}'

{"code": 0, "msg": "ok", "data": {"id": 1, "name": "Project documentation library", "description": "Stores project technical documentation", "visibility": "workspace", "wiki_enabled": false, "created_at": "2026-08-19T10:00:00Z", "my_role": "owner", "role_source": "owner_member", "can_manage_acl": true}}

GET /v1/knowledge/bases

In paginated mode, every row carries my_role / role_source / can_manage_acl (see the field table in the knowledge base details below for field meanings), so callers can directly render the availability of the "upload/delete/permission management" entries.compact=true streamlined catalog contains only name / description / doc_count / updated_at (also listing only accessible knowledge bases), without role fields.

curl "http://<host>:4040/v1/knowledge/bases?page_size=10" -H "X-API-Key: $API_KEY"

GET /v1/knowledge/bases/{id}

Retrieves details of a specified knowledge base. Requires viewer or higher permissions; insufficient permissions return 403 (40303). A kbId that belongs to another workspace or does not exist returns 404.

curl "http://<host>:4040/v1/knowledge/bases/1" -H "X-API-Key: $API_KEY"

{"code": 0, "msg": "ok", "data": {"id": 1, "workspace_id": 1, "name": "Project documentation library", "description": "Stores project technical documentation", "visibility": "workspace", "owner_member_id": 2, "doc_count": 42, "graph_enabled": false, "wiki_enabled": false, "created_at": "2026-08-19T10:00:00Z", "updated_at": "2026-08-19T10:00:00Z", "my_role": "editor", "role_source": "kb_default", "can_manage_acl": false}}

DELETE /v1/knowledge/bases/{id}

Deletes a knowledge base. Requires the owner permission of this knowledge base. The decision is fully consistent with my_role: Owner Key passes globally, the knowledge base creator is always owner, and members explicitly granted owner can also delete it. Insufficient permissions return 403 (40303); a knowledge base in another workspace or nonexistent returns 404 (a repeated delete returns 404 the second time).

curl -X DELETE http://<host>:4040/v1/knowledge/bases/1 -H "X-API-Key: $API_KEY"

POST /v1/knowledge/bases/{kbId}/documents/upload

Uploads a document to a specified knowledge base. Multimodal content is supported (text/PDF/image/audio). Identical content is idempotent. Requires editor or higher permissions (members of a public knowledge base are editor by default); insufficient permissions return 403 (40303); a kbId in another workspace or nonexistent returns 404.

curl -X POST http://<host>:4040/v1/knowledge/bases/1/documents/upload \
  -H "X-API-Key: $API_KEY" \
  -F "file=@./docs/architecture.md" \
  -F "title=Architecture design document"

POST /v1/knowledge/documents

Creates a document from a URL or text content (flat API; knowledge_base_id is specified in the body). Requires editor or higher permissions of the target knowledge base; insufficient permissions return 403 (40303); a knowledge base in another workspace or nonexistent returns 404.

curl -X POST http://<host>:4040/v1/knowledge/documents \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"knowledge_base_id": 1, "title": "API design guidelines", "content": "RESTful APIs should..."}'

GET /v1/knowledge/bases/{kbId}/documents

Lists documents in a specified knowledge base by page. Requires viewer or higher permissions of the target knowledge base; insufficient permissions return 403 (40303); a kbId in another workspace or nonexistent returns 404.

curl "http://<host>:4040/v1/knowledge/bases/1/documents?size=10" -H "X-API-Key: $API_KEY"

POST /v1/knowledge/documents/reindex

Re-queues an existing document through the normal knowledge.ingest flow, used for rebuilding existing documents after an embedding fingerprint / model, chunking, or index configuration release. Requires editor or higher permissions.

Safety and concurrency contract:

• workspace/member is derived only from X-API-Key; the request body does not provide it workspace_id.

• knowledge_base_id must belong to the current workspace, and document_id must belong to this KB; crossing workspaces returns 404 and insufficient ACL returns 403.

• expected_ingest_revision must use the value just read from the document list. On success the revision increments by one and the new event_id is returned; replaying an old revision returns 409 to avoid duplicate rebuilds.

• Only one document is rebuilt per call. The document status update and outbox enqueue happen within one short transaction; embedding / OSS / OpenSearch run asynchronously after the transaction commits.

curl -X POST http://<host>:4040/v1/knowledge/documents/reindex \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"knowledge_base_id":1,"document_id":42,"expected_ingest_revision":3}'

GET /v1/knowledge/documents/{id}

Retrieves document details. Requires viewer or higher permissions of the target knowledge base; insufficient permissions return 403 (40303); a document in another workspace or nonexistent returns 404.

curl "http://<host>:4040/v1/knowledge/documents/42" -H "X-API-Key: $API_KEY"

DELETE /v1/knowledge/documents/{id}

Deleting a document requires editor or higher permission on the knowledge base the document belongs to (it does not require being the uploader — in a public knowledge base any member can by default delete documents uploaded by others; see behavior change 1 in the overview "2026-09-16 knowledge base permission refactoring"). Insufficient permission returns 403 (40303); a document that crosses workspaces or does not exist returns 404.

curl -X DELETE http://<host>:4040/v1/knowledge/documents/42 -H "X-API-Key: $API_KEY"

POST /v1/knowledge/search

Performs hybrid search (BM25 + vector + RRF fusion) over knowledge bases accessible to the tenant.

curl -X POST http://<host>:4040/v1/knowledge/search \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"query": "How do I configure OpenSearch?", "kb_ids": [1, 2], "top_k": 5}'

{
  "code": 0, "msg": "ok",
  "data": [
    {
      "chunk_id": "chunk_001",
      "document_id": "42",
      "knowledge_base_id": "1",
      "title": "OpenSearch Configuration Guide",
      "snippet": "OpenSearch requires configuring cluster.name, node.name...",
      "score": 0.91,
      "position": 0,
      "rerank_score": 0.95,
      "modality": "text",
      "block_type": "text"
    }
  ]
}

GET /v1/knowledge/bases/{kbId}/tuning

Reads the search tuning parameters of a specified knowledge base (requires viewer or higher permissions). A null field means "use the global default" (top_k=5 / rerank=true / hybrid_weight=0.7 / graph_weight=0.3 / chunk_size=800 / chunk_overlap=100).

curl "http://<host>:4040/v1/knowledge/bases/1/tuning" -H "X-API-Key: $API_KEY"

{
  "code": 0, "msg": "ok",
  "data": {
    "top_k": 8,
    "rerank_enabled": true,
    "hybrid_weight": 0.5,
    "chunk_size": 800,
    "chunk_overlap": 100,
    "rrf_k": 60,
    "recall_multiplier": 3,
    "query_rewrite_enabled": false,
    "enable_contextual_retrieval": false,
    "graph_weight": null,
    "graph_skip_extensions": null,
    "enable_parent_child": null
  }
}

PUT /v1/knowledge/bases/{kbId}/tuning

Partially updates knowledge base tuning parameters (patch semantics; only the provided keys are overwritten). Requires editor or higher permissions. The request body is any subset of the tuning fields, with field names consistent with the GET /v1/knowledge/bases/{kbId}/tuning response.

curl -X PUT http://<host>:4040/v1/knowledge/bases/1/tuning \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"top_k": 8, "rerank_enabled": true}'

PUT /v1/knowledge/bases/{kbId}/settings

Updates knowledge base settings - the quality review switch, the knowledge graph switch, and visibility. At least one of the three fields must be provided (requires the owner permission of this knowledge base).

curl -X PUT http://<host>:4040/v1/knowledge/bases/1/settings \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"review_enabled": true, "graph_enabled": false, "visibility": "private"}'

{"code": 0, "msg": "ok", "data": {"kb_id": 1, "review_enabled": true, "graph_enabled": false, "visibility": "private"}}

GET /v1/knowledge/bases/{kbId}/index-stats

Views the index statistics of this knowledge base - document count, chunk count, index size, ingestion queue depth, and last ingestion time. Requires viewer or higher permissions of the target knowledge base; insufficient permissions return 403 (40303); a kbId in another workspace or nonexistent returns 404.

curl "http://<host>:4040/v1/knowledge/bases/1/index-stats" -H "X-API-Key: $API_KEY"

{"code": 0, "msg": "ok", "data": {"kb_id": 1, "kb_name": "Project documentation library", "doc_count": 42, "chunks_count": 1380, "index_size_bytes": 10485760, "ingest_queue_depth": 0, "last_ingest_at": "2026-09-16T09:31:00Z"}}

GET /v1/knowledge-bases/{kbId}/graph/nodes

Views the graph entity nodes of this knowledge base by page (pagerank descending). Requires viewer or higher permissions.

curl "http://<host>:4040/v1/knowledge-bases/1/graph/nodes?page=0&size=50" -H "X-API-Key: $API_KEY"

{"code": 0, "msg": "ok", "data": {"page": 0, "size": 50, "nodes": [{"id": "…", "label": "PolarDB-X", "type": "product", "pagerank": 0.42}]}}

GET /v1/knowledge-bases/{kbId}/graph/edges

Views the 1-hop adjacency subgraph of an entity (nodes + edges). Requires viewer or higher permissions.depth currently supports only 1 hop and is kept for API compatibility.

curl "http://<host>:4040/v1/knowledge-bases/1/graph/edges?node=PolarDB-X&depth=1" -H "X-API-Key: $API_KEY"

{"code": 0, "msg": "ok", "data": {"nodes": [{"id": "…", "label": "PolarDB-X", "type": "product", "pagerank": 0.42}], "edges": [{"from": "PolarDB-X", "to": "CN", "predicate": "part_of", "weight": 0.8}]}}

Graph data-plane clearing and rebuilding

No request body is needed; both return Box; paths use knowledge-bases hyphens. A User Key with knowledge base owner permission can call them; viewer / editor cannot. Resources are validated by workspace/KB, reusing the original graph guard / barrier; the rebuild count indicates the number enqueued, not synchronous completion, and existing review is not bypassed.

Graph conflict detection and manual review (added 2026-09-16)

Two kinds of silently adjudicated signals during multi-document consolidation - cross-document type divergence of the same entity (type_conflict) and the same alias claimed by multiple entities (alias_conflict) - can be scanned and queued on demand for manual adjudication by editor+. Detection is a synchronous read-only scan (zero LLM, no graph writes); type / alias decisions and graph update events commit in the same transaction and take effect after background consolidation. The feature is gated by context.knowledge.graph.conflict-detection.enabled (default: true); when disabled, the endpoints return 404.

Example:

# Trigger detection (editor+)
curl -X POST "http://<host>:4040/v1/knowledge-bases/1/graph/conflicts/detect" -H "X-API-Key: $API_KEY"

{"code": 0, "msg": "ok", "data": {"scanned_documents": 12, "conflicts": 3, "opened": 2, "refreshed": 1, "staled": 0}}

# Type conflict adjudication: choose the correct type (chosen_type must be in the candidate set, otherwise 400)
curl -X POST "http://<host>:4040/v1/knowledge-bases/1/graph/conflicts/11/decision" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"action":"resolve","chosen_type":"project"}'

# Alias conflict adjudication: choose the alias owner / dismiss without further reminders
curl -X POST "http://<host>:4040/v1/knowledge-bases/1/graph/conflicts/12/decision" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"action":"resolve","chosen_owner":"Alibaba Cloud"}'
curl -X POST "http://<host>:4040/v1/knowledge-bases/1/graph/conflicts/12/decision" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" -d '{"action":"dismiss"}'

• Adjudication semantics: resolved means the decision and update events are committed, not that the graph update is complete. Both type / alias are updated asynchronously by the graph-consolidate worker; failures retry per the existing event policy, and a failed event enqueue rolls back the decision as well. Manual alias decisions take precedence over old mappings; type decisions apply to the final entity after alias merging and continue to replay in later consolidations.dismiss, a conflict with the same fingerprint (payload_hash) is not reopened; open rows whose signals disappear turn stale, and revive to open when reproduced; resolved/dismissed conflicts are not reopened by repeated detection. The conflict list is read-only awareness for viewer; detection and adjudication are write operations (403). Conflict records are cleaned up synchronously when a knowledge base or workspace is deleted.

• Entity auto-confirmation keeps the context.knowledge.graph.consolidate.auto-confirm.containment-enabled configuration name, but only allows candidates with identical names under existing normalization rules to be confirmed directly; mere substring containment (such as PolarDB / PolarDB-X) still requires disambiguation. Jaccard auto-confirmation still needs explicit enablement and is disabled by default.

Graph management plane route convergence (updated 2026-09-16)

The management plane (OPS port 8080, Owner Key) graph routes now pass kb_id as a query param, in the same form as /ops/knowledge/wiki/**. The old path-parameter version remains available and will be removed after it enters the deprecation cycle.

Both route groups share one implementation; request/response JSON, authentication (Owner Key), and the workspace fence (cross-workspace 403) are verbatim identical; size remains capped at 1000. The change follows the backend red line: "/ops/** routes must not contain @PathVariable; identifiers go through query params or the body".

The same convergence batch includes the promotion delete API: the new DELETE /ops/promotion/delete?promotionId=, while the old DELETE /ops/promotion/{promotionId} also remains available during the deprecation cycle.

GET /v1/knowledge/wiki/config?kb_id=<id>

Views the generation switch and deployment capabilities of a single knowledge base. Requires knowledge base read permission. Returns Box<SettingsDto>:

{"code":0,"msg":"ok","data":{"kb_id":1,"wiki_enabled":false,"build_available":true,"search_available":true,"wiki_config":{"wiki_language":"Chinese","extraction_granularity":"standard","content_instructions":""}}}

PUT /v1/knowledge/wiki/config?kb_id=<id>

Sets the continuous generation switch and generation configuration for a single knowledge base. This requires the knowledge base owner (management permission); a User Key with the corresponding role is sufficient. At least one of wiki_enabled and wiki_config must be provided; the old switch-only request remains valid. In DATA, wiki_config is a JSON object:

{"wiki_enabled":true,"wiki_config":{"wiki_language":"Chinese","extraction_granularity":"focused","content_instructions":"Focus on architecture decisions"}}

POST /v1/knowledge/wiki/backfill?kb_id=<id>

Backfills existing indexed documents for a knowledge base with Wiki enabled. Requires the knowledge base owner (management permissions). No request body is needed. Returns:

{"code":0,"msg":"ok","data":{"kb_id":1,"status":"accepted","enqueued":3}}

PUT /ops/knowledge/wiki/config?kb_id=<id> (advanced generation configuration)

Using the management plane address and the workspace Owner Key, you can set the wiki_config JSON string. This legacy OPS contract is retained and is not changed to the DATA object format; for knowledge base page configuration, prefer the data plane endpoint described above. Knowledge base owner identity is not the same as the workspace Owner Key.

curl -X PUT "http://<host>:8080/ops/knowledge/wiki/config?kb_id=1" \
  -H "X-API-Key: $OWNER_KEY" -H "Content-Type: application/json" \
  -d '{"wiki_config":"{\"extraction_granularity\":\"focused\",\"wiki_language\":\"Chinese\",\"content_instructions\":\"Focus on architecture decisions\"}"}'

Configuration changes do not imply immediate rebuilding of historical pages. For complete getting-started steps, see Build a RAG + Wiki enterprise knowledge base.

Wiki data-plane page management and task summaries

prefix /v1/knowledge/wiki, and all return Box. viewer is read-only; editor can edit / publish / archive / restore pages, regenerate a single page, and retry failed tasks of this knowledge base; configuration, ACL, and knowledge-base-wide backfill still require the knowledge base owner. Global ES repair remains OPS-only and is not open to ordinary knowledge base roles.

Paging for pages, dead letters, and logs requires page to be non-negative and size to be 1-200; invalid values are rejected. The paged data contains pagination fields such as content / total_elements, not a bare array. Pages, target folders, dead letters, and their associated source documents must belong to an authorized workspace/KB; out-of-scope resources cannot be accessed by borrowing a valid kb_id. The parent_id when creating/updating a folder must also be in the same knowledge base.

• status and page_type are closed value domains, validated against a whitelist on the write side; any value outside the domain returns 400 40001:

  • status ∈ draft / published / archived. Search and recall index only published, the backlink graph recognizes only published and resolvable draft, /stats counts only published_pages / draft_pages, and the console's publish / archive / restore buttons render only under draft / archived - writing an out-of-domain value makes the page disappear from all four places at once.

  • page_type ∈ entity / concept / summary / index (the four actually produced by the generation side). When not provided, the default is entity. Title resolution and deduplication candidates look only at entity / concept.GET /pages?type= filter values are likewise limited to these four.

• slug and title is required and cannot be blank; leading/trailing spaces are trimmed by the same rule as wikilink targets; slug is up to 256 characters and title is up to 512 characters; exceeding a limit returns 400 with the column budget in the message. A missing or blank slug is a validation error (40001) and no longer falls through to storage-layer constraints (the historical behavior was 40009 missing or invalid required column: slug).

• The category request field for page updates is category, while the response still uses category_path; slug is not modified. Setting status=published publishes a draft or restores an archived page; setting status=archived carries the archive semantics of the UI "delete", not a physical deletion. Before editing the body, first request /pages/{pageId}?for_edit=true to get the complete body; truncated content from a budgeted read must not be saved back.

• Regeneration first checks the ownership of all sources, then queues the still-valid sources of the same knowledge base; a manual page without valid sources or with all sources deleted returns 409 instead of pretending to be queued. Retrying a dead letter must verify the ownership of both the dead letter and the associated document; on success it is queued and the dead-letter record is removed. Neither accepted nor retried implies that model processing has completed.

• Dead-letter summary fields: id, knowledge_id, fail_count, created_at, error_code=WIKI_DISTILL_FAILED, last_error (fixed to "Distillation failed; please retry or contact the administrator"). Log summary fields: id, action, summary, created_at; action is only distill_batch / distill_coverage / link_validation / other, and summary is a fixed redacted message. Neither API returns raw model results or provider errors.

POST /v1/knowledge/wiki/search

Performs BM25 full-text search over Wiki distillation pages and returns the hit list (without full bodies). Unlike /v1/knowledge/search (chunk-level hybrid search), Wiki search targets distilled structured knowledge pages. Only status=published pages can be searched (enforced server-side); a draft page can be published by an editor through the data-plane page update or the original management-plane publish, and appears in search results only after index synchronization.

curl -X POST http://<host>:4040/v1/knowledge/wiki/search \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"query": "Deployment process", "knowledge_base_ids": [1], "top_k": 5}'

{
  "code": 0, "msg": "ok",
  "data": [
    {
      "id": "101",
      "title": "Deployment Guide",
      "slug": "deploy-guide",
      "page_type": "concept",
      "category": "Operations",
      "summary": "Introduces Docker Compose and the image deployment process",
      "snippet": "...prepare DASHSCOPE_API_KEY in .env before deployment...",
      "score": 8.42
    }
  ]
}

GET /v1/knowledge/wiki/pages/{pageId}

Reads a Wiki page from MySQL by page ID (including the markdown body). A normal read checks read permission against the page's actual knowledge base and follows the output budget; for_edit=true requires editor write permission of the page's actual knowledge base, returns the complete body, and ignores the normal read budget. A client cannot bypass page ownership by substituting another kb_id.

curl "http://<host>:4040/v1/knowledge/wiki/pages/101" -H "X-API-Key: $API_KEY"

{
  "code": 0, "msg": "ok",
  "data": {
    "id": 101,
    "knowledge_base_id": 1,
    "slug": "deploy-guide",
    "title": "Deployment Guide",
    "page_type": "concept",
    "category_path": "Operations/Deployment",
    "summary": "Introduces Docker Compose and the image deployment process",
    "content_markdown": "# Deployment Guide\n...",
    "source_refs": "[\"doc:42\"]",
    "aliases": "deployment,deploy",
    "status": "published",
    "view_count": 12,
    "created_at": "2026-08-19T10:00:00Z",
    "updated_at": "2026-08-19T11:00:00Z"
  }
}

GET /v1/knowledge/wiki/pages/by-slug

Reads a Wiki page by knowledge base ID + slug (response structure same as above).

curl "http://<host>:4040/v1/knowledge/wiki/pages/by-slug?kb_id=1&slug=deploy-guide" \
  -H "X-API-Key: $API_KEY"

GET /v1/knowledge/wiki/folders

Lists the Wiki folder structure of a specified knowledge base, optionally filtered by parent folder.

curl "http://<host>:4040/v1/knowledge/wiki/folders?kb_id=1" -H "X-API-Key: $API_KEY"

{
  "code": 0, "msg": "ok",
  "data": [
    {"id": 10, "knowledge_base_id": 1, "name": "Operations", "path": "/Operations", "parent_id": null, "sort_order": 0}
  ]
}

GET /v1/knowledge/wiki/read

The core endpoint of the Read step. Reads the full Wiki page by kb_id + slug and returns the out_links / in_links slug list and neighbor page summary cards (neighbors) so that agents can navigate and expand along the link graph (Expand).

curl "http://<host>:4040/v1/knowledge/wiki/read?kb_id=1&slug=deploy-guide" \
  -H "X-API-Key: $API_KEY"

{
  "code": 0, "msg": "ok",
  "data": {
    "page": {
      "id": 101,
      "knowledge_base_id": 1,
      "slug": "deploy-guide",
      "title": "Deployment Guide",
      "page_type": "concept",
      "content_markdown": "# Deployment Guide\n...",
      "status": "published"
    },
    "out_links": ["env-config", "docker-compose"],
    "in_links": ["getting-started"],
    "neighbors": [
      {
        "id": 102,
        "slug": "env-config",
        "title": "Environment Variable Configuration",
        "page_type": "entity",
        "summary": "Introduces the key variables in .env (truncated to 150 characters)",
        "direction": "out"
      },
      {
        "id": 99,
        "slug": "getting-started",
        "title": "Getting Started",
        "page_type": "concept",
        "summary": "5-minute getting started guide",
        "direction": "in"
      }
    ]
  }
}

GET /v1/knowledge/wiki/pages/{pageId}/sources

The source tracing endpoint. Lists the source documents of a Wiki page (including short-lived signed OSS download links, TTL 1800s) and, by default, 10 representative chunk snippets per document (configurable via context.wiki.source-query.preview-chunks) for checking distilled content against the sources.

curl "http://<host>:4040/v1/knowledge/wiki/pages/101/sources" -H "X-API-Key: $API_KEY"

{
  "code": 0, "msg": "ok",
  "data": [
    {
      "document_id": 42,
      "title": "deployment-manual.pdf",
      "source_url": null,
      "file_path": "docs/deploy.pdf",
      "mime_type": "application/pdf",
      "oss_presigned_url": "/v1/files/download?key=...&expires=...&signature=...",
      "total_chunks": 128,
      "chunks": [
        {"chunk_id": "42_3", "position": 3, "content": "...prepare .env before deployment..."}
      ]
    }
  ]
}

POST /v1/knowledge/wiki/issues

Flags quality issues (outdated/inaccurate/missing/broken links) on Wiki page content for background review and re-distillation. Requires editor write permission of the page's real knowledge base; viewer cannot submit - this is an authorization fix for the read-only role. Success returns 200 (Box-wrapped).

curl -X POST http://<host>:4040/v1/knowledge/wiki/issues \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"page_id": 101, "issue_type": "outdated", "description": "The deployment port has changed from 8080 to 4040"}'

{"code": 0, "msg": "ok", "data": {"id": 7, "status": "open"}}

GET /v1/knowledge/documents/{id}/images

Lists images extracted from a document (OSS originals + short-lived signed download links + Vision descriptions/OCR text). Requires reader or higher permissions. Crossing workspaces / nonexistent returns 404.

curl "http://<host>:4040/v1/knowledge/documents/42/images" -H "X-API-Key: $API_KEY"

{
  "code": 0, "msg": "ok",
  "data": [
    {
      "oss_key": "ws1/doc42/img_001.png",
      "signed_url": "https://oss.example.com/...&Signature=...",
      "page_number": 3,
      "block_type": "image",
      "section_path": "Architecture/Storage layer",
      "caption": "Storage trio architecture diagram: PolarDB-X + PolarDB-X Search + OSS"
    }
  ]
}

Document immutable source revisions (added 2026-09-16)

prefix: /v1/knowledge/bases/{kbId}/documents/{docId}/revisions. All responses follow Box<T> (business data is in data), and every call re-checks the current knowledge base viewer permissions. A revision ID that crosses the workspace / knowledge base / document returns 404; a historical ID is not an authorization credential. After the source storage read or PDF rendering finishes, the current permission state is queried again; an ACL downgrade or a public-to-private switch committed in the meantime will not return the body based on stale permissions cached within the request.

• Revision fields: id (business UUID), number, snapshot_hash, source, created_at, author_member_id (may be null for old records).source contains the source, original hash / OSS key, title, metadata, and document metadata snapshot; parsing coverage is provided through the separate /parsed API; no knowledge-base-wide release manifest is stored. The new revision produced by a restore records its origin in source.restored_from_revision_id; this audit note does not participate in the snapshot_hash of the source content. The technical ingest_revision, projection_generation is not the business revision ID. Identical snapshots are not recreated; a metadata change or A→B→A produces a new business revision. restore keeps the document ID / external_id, first validates the original outside a transaction, then performs CAS within a short transaction and generates the new source revision and the existing ingest outbox; it does not restore old permissions, old review decisions, or Wiki / graph derivations, and it is not equivalent to a knowledge-base-wide release rollback. This API does not imply that content has been reviewed or published.

• New capture and restore are disabled by default: context.knowledge.revisions.capture-enabled=false. Set it to true only after confirming that all readers / writers / workers / GC have been upgraded to a compatible version; old programs do not recognize historical references, and a mere epoch or switch cannot isolate an old GC. Disabling capture does not disable the protection or reading of existing historical objects. When an old original lacks a verifiable content_hash, no historical baseline is forged.

• Source fields: revision_id, source_hash, mime_type, encoding (utf-8 or base64), content. Explicitly fails when the original SHA-256 check fails, the object is missing, or the 16 MiB online preview budget is exceeded; when uploading with attachments, the main file check uses the fixed metadata_json.content_sha256. PDFs return page, total_pages, mime_type=image/png, base64 content; each file has up to 1,000 pages, each page up to 1,200x1,600, and the server renders at most 2 pages concurrently. Binary originals and parsing evidence are provided separately.

• Parsed fields: revision_id, source_hash, artifact_hash, text, blocks, coverage, created_at.blocks retains only page_number, block_type, section_path, text and does not persist signed URLs. On a successfully committed ingestion, an immutable parse is retained per (revision_id, ingest_revision); retries of the same ingestion do not overwrite evidence, and re-ingestion can add parses so that an initially partial parse can be repaired. Reads verify content digests; Ontology tasks pin artifact_hash, and later re-parsing does not change the evidence of old tasks. Coverage status is complete / partial / unknown; unknown must not be treated as complete. A single parse artifact is capped at 12,000,000 bytes, and a workspace defaults to at most 1 GiB (context.knowledge.revisions.max-parsed-bytes-per-workspace), counted against the workspace logical storage quota.

• The retention policy has two layers. Automatic trimming: each time a revision is added, the latest N revisions are kept according to context.knowledge.revisions.max-kept-per-document (default 5), and the excess is physically deleted along with the parsing artifacts. Hard limits: by default a single document has at most 1,000 revisions (max-per-document), and the workspace historical source file bundle is at most 50 GiB (max-retained-bytes-per-workspace); when exceeded, new writes are rejected rather than history being silently deleted. Originals / sidecars that have historical references are not deleted when the current document is updated; the history of that scope is deleted only when the knowledge base / workspace is deleted. Logical historical bytes count toward the workspace storage quota. Currently it deduplicates by document/source_hash bundle and takes the maximum byte count in the records, rather than a per-OSS-object ledger; derived attachments generated later under the same source_hash cannot be precisely measured this way. This is not the final implementation of per-release reference counting / retention windows / physical billing.

• ctxdb0 read wiring: knowledge documents versions <document-id> --source <name-or-id> --page 0 --limit 20 --json and knowledge documents source <document-id> --source <name-or-id> --revision <business-revision-uuid> --json. The latter keeps the source response JSON and encoding as-is; permission / missing / corruption errors fail directly without calling the current document detail as a substitute; no release pin or semantic verify capability is added. The single-document restore command is knowledge documents restore <document-id> --source <name-or-id> --revision <business-revision-uuid> --expected-revision <current-head-uuid> --json, using the same editor permission and concurrency check.

Ontology knowledge base (managing catalog, candidate versions, and validation)

prefix: /v1/knowledge/bases/{kbId}/ontology; all use the Box wrapper (code, msg, data, trace_id); the fields below all refer to data. An Ontology belongs to a single KB; reading requires viewer, while saving, structural validation, discovery, referencing, deactivation, and deletion require editor. viewer is read-only. All resources are restricted by the current workspace/member/KB permissions. Saving yields a candidate definition and does not automatically change existing Wiki / graphs; after an explicit apply, new graph and Wiki tasks pin the selected definition, and documents still follow existing review.

curl -X POST "http://<host>:4040/v1/knowledge/bases/1/ontology/discoveries" \
  -H "X-API-Key: $API_KEY" \
  -F 'files=@sample-a.pdf' -F 'files=@sample-b.txt' \
  -F 'options={"request_id":"sample-request-001","ontology_discovery_instructions":"Focus only on products and terms","graph_extraction_instructions":"Keep source evidence during extraction"};type=application/json'

{
  "expected_version_id": null,
  "schema": {
    "types": [{"id":"indicator","name":"Indicator","aliases":["metric"],"attributes":[{"id":"value","name":"Value","valueType":"number","required":true,"allowedUnits":["u_test"]}]}],
    "relations": []
  },
  "instructions": {"ontology_discovery_instructions":"Output only candidates with source evidence", "graph_extraction_instructions":"Strictly follow the fixed types and units"}
}

Approval notifications (added 2026-09-16, disabled by default)

prefix: /v1/knowledge/bases/{kbId}/review-notifications. All return Box<T>, and configuration, delivery records, and retries all require the current knowledge base owner.

• The notification is written to the outbox within the committing transaction of the original review's final accepted, shared by automatic and manual review.accepted_pending, rejection, or failed activation does not send an "approved" notification; a rolled-back transaction leaves no notification. Notifications are sent asynchronously; failures use the existing event retry mechanism and do not roll back the document review status. Notifications are generated only for new approvals after enablement; historical approvals are not backfilled.

• The webhook is a JSON POST containing event_id (stable notification UUID), type=knowledge.document.review_approved, knowledge_base_id, document_id, review_id, revision_id (null when history is not captured), content_hash, approved_at. The document full text is not included. The request headers Idempotency-Key and X-Context0-Event-Id are both this UUID; receivers should deduplicate by it. Delivery may repeat when sending succeeds but local acknowledgment fails; exactly-once is not promised. 2xx means success; other statuses mean failure.

• status is pending / delivered / cancelled; pending with event_status=dead means automatic retries are exhausted and the owner can retry manually. After disabling or changing the subscription, notifications of the old configuration that have not started sending are cancelled and will not be delivered to the new address; in-flight HTTP requests may still complete. Retries keep the same event number.

• Address restrictions are validated both at save time and at actual DNS connection time: redirects, URL credentials, fragments, cloud metadata addresses, link-local, and reserved addresses are prohibited. Private/loopback networks are denied by default; internal receivers must be configured one by one with exact hostnames by an administrator in context.knowledge.review-notifications.allowed-internal-hosts, and cannot be bypassed via the API. The connection timeout is 5 seconds and the response timeout is 10 seconds; response bodies are not read, and URLs containing receiver tokens are not written to failure logs. Scheduled sending is enabled by default (context.knowledge.review-notifications.scheduled-enabled=true); nothing is sent without an enabled subscription.

Pinned-revision Ontology discovery / extraction async tasks (compatible protocol)

prefix: /v1/knowledge/bases/{kbId}/ontology. The server-side context.knowledge.ontology-tasks.enabled currently defaults to true; with an explicit false, old task creation / retries return a validation error and no worker is registered.context.knowledge.ontology-tasks.scheduled-enabled defaults to true and controls polling; both configurations should follow the actual deployment override values. New sample discovery shares this worker and switch; when explicitly disabled, sample creation / retries return a feature-disabled error. Existing event outbox / lease / retry queues are reused, with no new Agent runtime.

• extract must specify a pinned Ontology version; discover may optionally use an existing version, and instructions are pinned with that version. Each run takes 1-4 revisions of the same knowledge base, supporting retained text originals and PDF / Office files with existing historical parses, with a total length of at most 32,000 characters; each knowledge base has at most 8 queued / processing tasks. Source revision / original hash / parse artifact hash and coverage, schema / instructions, system templateVersion / hash, model configuration digest, and sampling budget form the input fingerprint; duplicate inputs return the same task. Failed tasks are not silently retried by repeated creation; the original author can explicitly retry, and changed input dependencies require creating a new task. By default each knowledge base retains at most 1,000 tasks and 1,000 Ontology versions (context.knowledge.ontology-tasks.max-retained-per-kb / context.knowledge.ontology.max-versions-per-kb); the cap rejects new entries without automatically deleting history.

• Statuses use the existing event statuses (pending / processing / done / dead). Truncated model results, run configuration changes, or lost permissions cause failures; a worker that lost its lease must not write back. Results contain candidate, issues, valid, authority=unreviewed_candidate, coverage.scope=selected_originals_only, coverage.corpus_complete=false. done only means the task finished, and valid only means structural and literal evidence passed; neither is formal publishing. Accepting a schema requires explicitly saving a candidate, then applying it through /active; the compatible task panel allows editing the candidate JSON while the original model results remain retained. The new Ontology catalog uses independent sample discovery and version disposition; it does not show the removed revision trial-run / canvas panels, nor equate version referencing, editing, or deletion with the old per-item candidate accept / merge / reject. Document review continues to use the existing review mechanism; knowledge-base-wide publishing, knowledge-base-wide version rollback, and expert double review are out of scope for this simplification.

• discover output is {schema,candidates}. Every type, property, and relation must have a corresponding provenance candidate; path use respectively types.TYPE_ID, types.TYPE_ID.attributes.ATTRIBUTE_ID, relations.RELATION_ID; each item contains an independent id, a finite number in 0-1 confidence, and a non-empty evidence. At most 100 items; missing items / duplicate paths / undeclared paths all return blocking issues; high confidence does not exempt anchor validation. extract output uses the facts format above. Task references may come only from the revisions selected in the request; other unselected sources of the same knowledge base cannot be introduced. After events are cleaned by the retention policy, tasks with results remain done and tasks without results show expired; retry cannot recreate lost events.

Search quality benchmark (gold standard + scoring runs)

POST /v1/multimodal/upload

Uploads a multimodal resource (image/audio/document) and returns queued status; OCR/ASR/transcription is extracted later by the async scheduler.

curl -X POST "http://<host>:4040/v1/multimodal/upload" \
  -H "X-API-Key: $API_KEY" \
  -F "file=@/path/to/image.png" \
  -F "modality=image"

{"code": 0, "msg": "ok", "data": {"resource_id": "res_abc123", "ingest_status": "queued"}}

GET /v1/multimodal

Lists multimodal resources of the current tenant by page, ordered by created_at descending. A lightweight projection without heavy fields such as OCR/ASR/transcription.

curl "http://<host>:4040/v1/multimodal?page=0&size=20" -H "X-API-Key: $API_KEY"

{
  "code": 0, "msg": "ok",
  "data": {
    "content": [
      {
        "resource_id": "res_abc123",
        "modality": "image",
        "mime": "image/png",
        "oss_url": "http://context0.example.com/v1/files/download?key=...&expires=...&signature=...",
        "thumbnail_url": null,
        "size_bytes": 20480,
        "ingest_status": "done",
        "memory_id": "mem_1_2_abc",
        "session_id": "sess-2026-08-19-001",
        "member_id": 2,
        "created_at": "2026-08-19T10:00:00Z",
        "updated_at": "2026-08-19T10:00:05Z"
      }
    ],
    "total_elements": 1,
    "total_pages": 1,
    "number": 0,
    "size": 20
  }
}

GET /v1/multimodal/{resourceId}

Retrieves multimodal resource details, including OCR / ASR / transcription text and metadata. Cross-tenant access returns 404.

curl "http://<host>:4040/v1/multimodal/res_abc123" -H "X-API-Key: $API_KEY"

{
  "code": 0, "msg": "ok",
  "data": {
    "resource_id": "res_abc123",
    "modality": "image",
    "mime": "image/png",
    "oss_url": "http://context0.example.com/v1/files/download?key=...&expires=...&signature=...",
    "thumbnail_url": null,
    "size_bytes": 20480,
    "transcribed_text": null,
    "ocr": {"text": "Architecture diagram annotation text"},
    "asr": null,
    "metadata": {},
    "memory_id": "mem_1_2_abc",
    "session_id": "sess-2026-08-19-001",
    "member_id": 2,
    "ingest_status": "done",
    "created_at": "2026-08-19T10:00:00Z",
    "updated_at": "2026-08-19T10:00:05Z"
  }
}

GET /v1/multimodal/{resourceId}/url

Generates a temporary pre-signed download URL for a resource (each call mints a new link; long-lived links are not stored). Cross-tenant access returns 404.