/\ ATFGraph /docs
README Downloads
HTTP API & schemas / ATFGraph
Framework reference

This article is retained from the existing framework docs. Self-hosting commands and server-admin access differ from the managed CLI workflow. Start with Get started for the installed product.

Knowledge API

Store scoped documents, retrieve chunks with BM25 scores and citations, and inspect collection statistics.

Operations

OperationMethodPath
deleteKnowledgeDocumentPOST/api/v2/knowledge/delete
getKnowledgeDocumentPOST/api/v2/knowledge/get
listKnowledgeDocumentsPOST/api/v2/knowledge/list
putKnowledgeDocumentPOST/api/v2/knowledge/put
putKnowledgeBatchPOST/api/v2/knowledge/put-batch
searchKnowledgePOST/api/v2/knowledge/search
knowledgeStatsPOST/api/v2/knowledge/stats

deleteKnowledgeDocument

POST /api/v2/knowledge/delete

Requires: invoke role, worker role

Tombstone one document, keeping its revision monotonic. deleted:false when no live document existed. expected_revision mismatches are 409 revision_conflict.

Generated Python client internals: atfgraph._generated.api.knowledge_api.KnowledgeApi.delete_knowledge_document()

Request body

KnowledgeDelete (required)

{
  "doc_id": "string",
  "scope": "session"
}

Responses

StatusBodyMeaning
200KnowledgeDeletedSuccessful operation
400ErrorResponseStructured API error
401ErrorResponseMissing or invalid credentials
403ErrorResponseRole or ownership denied
404ErrorResponseResource unavailable to this identity
409ErrorResponseRevision, idempotency, immutable version or lease conflict
413ErrorResponseStructured API error
422ErrorResponseCapability input/output schema violation
429ErrorResponseCapacity exceeded
500ErrorResponseStructured API error
503ErrorResponseStructured API error

Example response 200

{
  "deleted": false,
  "doc_id": "string",
  "revision": 0
}

getKnowledgeDocument

POST /api/v2/knowledge/get

Requires: invoke role, worker role

Read one document with its chunks (include_chunks defaults to true). A missing or deleted document returns found:false with the doc_id rather than 404.

Generated Python client internals: atfgraph._generated.api.knowledge_api.KnowledgeApi.get_knowledge_document()

Request body

KnowledgeGet (required)

{
  "doc_id": "string",
  "scope": "session"
}

Responses

StatusBodyMeaning
200KnowledgeDocumentSuccessful operation
400ErrorResponseStructured API error
401ErrorResponseMissing or invalid credentials
403ErrorResponseRole or ownership denied
404ErrorResponseResource unavailable to this identity
409ErrorResponseRevision, idempotency, immutable version or lease conflict
413ErrorResponseStructured API error
422ErrorResponseCapability input/output schema violation
429ErrorResponseCapacity exceeded
500ErrorResponseStructured API error
503ErrorResponseStructured API error

Example response 200

{
  "chunks": 0,
  "created_at": 0,
  "doc_id": "string",
  "found": false,
  "items": [
    {
      "citation": "string",
      "metadata": {
        "key": {}
      },
      "ordinal": 0,
      "page": 0,
      "text": "string",
      "tokens": 0
    }
  ],
  "metadata": {
    "key": {}
  },
  "principal": "string",
  "revision": 0,
  "text_bytes": 0,
  "title": "string",
  "tokens": 0,
  "updated_at": 0
}

listKnowledgeDocuments

POST /api/v2/knowledge/list

Requires: invoke role, worker role

Page live documents of one scope in ascending doc_id order with an optional literal prefix. cursor is the last doc_id of the previous page; a null next_cursor is the last page.

Generated Python client internals: atfgraph._generated.api.knowledge_api.KnowledgeApi.list_knowledge_documents()

Request body

KnowledgeListQuery (required)

{
  "scope": "session"
}

Responses

StatusBodyMeaning
200KnowledgeListingSuccessful operation
400ErrorResponseStructured API error
401ErrorResponseMissing or invalid credentials
403ErrorResponseRole or ownership denied
404ErrorResponseResource unavailable to this identity
409ErrorResponseRevision, idempotency, immutable version or lease conflict
413ErrorResponseStructured API error
422ErrorResponseCapability input/output schema violation
429ErrorResponseCapacity exceeded
500ErrorResponseStructured API error
503ErrorResponseStructured API error

Example response 200

{
  "items": [
    {
      "chunks": 0,
      "doc_id": "string",
      "metadata": {
        "key": {}
      },
      "revision": 0,
      "text_bytes": 0,
      "title": "string",
      "tokens": 0,
      "updated_at": 0
    }
  ],
  "next_cursor": "string"
}

putKnowledgeDocument

POST /api/v2/knowledge/put

Requires: invoke role, worker role

Write or replace one document in a memory scope. Provide exactly one of text (chunked server-side, optional chunk size/overlap) or chunks (1-2000 caller chunks). doc_id is 1-256 printable characters; text is at most 1 MiB, each chunk at most 32 KiB, metadata at most 16384 canonical bytes. expected_revision is compare-and-set (0 means must not exist; 409 revision_conflict). Scopes hold at most 20000 documents and 200000 chunks (422 scope_full). Writes do not append to the memory change feed.

Generated Python client internals: atfgraph._generated.api.knowledge_api.KnowledgeApi.put_knowledge_document()

Request body

KnowledgePut (required)

{
  "doc_id": "string",
  "scope": "session"
}

Responses

StatusBodyMeaning
200KnowledgeWriteResultSuccessful operation
400ErrorResponseStructured API error
401ErrorResponseMissing or invalid credentials
403ErrorResponseRole or ownership denied
404ErrorResponseResource unavailable to this identity
409ErrorResponseRevision, idempotency, immutable version or lease conflict
413ErrorResponseStructured API error
422ErrorResponseCapability input/output schema violation
429ErrorResponseCapacity exceeded
500ErrorResponseStructured API error
503ErrorResponseStructured API error

Example response 200

{
  "chunks": 0,
  "created": false,
  "doc_id": "string",
  "postings": 0,
  "revision": 0,
  "terms": 0,
  "tokens": 0
}

putKnowledgeBatch

POST /api/v2/knowledge/put-batch

Requires: invoke role, worker role

Write 1-100 documents in one transaction: any failure writes nothing. Duplicate doc_ids are rejected and the combined text is bounded to 4 MiB.

Generated Python client internals: atfgraph._generated.api.knowledge_api.KnowledgeApi.put_knowledge_batch()

Request body

KnowledgePutBatch (required)

{
  "documents": [
    {
      "doc_id": "string"
    }
  ],
  "scope": "session"
}

Responses

StatusBodyMeaning
200KnowledgeBatchResultSuccessful operation
400ErrorResponseStructured API error
401ErrorResponseMissing or invalid credentials
403ErrorResponseRole or ownership denied
404ErrorResponseResource unavailable to this identity
409ErrorResponseRevision, idempotency, immutable version or lease conflict
413ErrorResponseStructured API error
422ErrorResponseCapability input/output schema violation
429ErrorResponseCapacity exceeded
500ErrorResponseStructured API error
503ErrorResponseStructured API error

Example response 200

{
  "chunks": 0,
  "documents": 0,
  "items": [
    {
      "chunks": 0,
      "created": false,
      "doc_id": "string",
      "postings": 0,
      "revision": 0,
      "terms": 0,
      "tokens": 0
    }
  ]
}

searchKnowledge

POST /api/v2/knowledge/search

Requires: invoke role, worker role

Lexical BM25 search (k1 = 1.2, b = 0.75) over the chunks of one scope. Tokenisation lower-cases, splits camelCase and acronyms, and indexes ideographs per character; the same rules apply to queries. Results are ordered by score descending, then doc_id, then ordinal, identically on every page and process. filters are exact JSON equality against document metadata (at most 32 keys); doc_id restricts to one document; min_score floors the score. A query without indexable terms returns items:[] with terms:[] and status 200. There is no embedding index; use memory/vector for embeddings.

Generated Python client internals: atfgraph._generated.api.knowledge_api.KnowledgeApi.search_knowledge()

Request body

KnowledgeSearch (required)

{
  "query": "string",
  "scope": "session"
}

Responses

StatusBodyMeaning
200KnowledgeHitsSuccessful operation
400ErrorResponseStructured API error
401ErrorResponseMissing or invalid credentials
403ErrorResponseRole or ownership denied
404ErrorResponseResource unavailable to this identity
409ErrorResponseRevision, idempotency, immutable version or lease conflict
413ErrorResponseStructured API error
422ErrorResponseCapability input/output schema violation
429ErrorResponseCapacity exceeded
500ErrorResponseStructured API error
503ErrorResponseStructured API error

Example response 200

{
  "corpus_chunks": 0,
  "items": [
    {
      "chunk_metadata": {
        "key": {}
      },
      "citation": "string",
      "doc_id": "string",
      "matched_terms": [
        "string"
      ],
      "metadata": {
        "key": {}
      },
      "ordinal": 0,
      "page": 0,
      "score": 0.0,
      "text": "string",
      "title": "string",
      "tokens": 0
    }
  ],
  "next_offset": 0,
  "offset": 0,
  "scanned": 0,
  "strategy": "bm25",
  "terms": [
    "string"
  ],
  "top_k": 0,
  "total": 0
}

knowledgeStats

POST /api/v2/knowledge/stats

Requires: invoke role, worker role

Live corpus counts for one scope (documents, chunks, tokens, bytes, distinct terms, postings), the strategy and the bounds the store enforces.

Generated Python client internals: atfgraph._generated.api.knowledge_api.KnowledgeApi.knowledge_stats()

Request body

KnowledgeScope (required)

{
  "scope": "session"
}

Responses

StatusBodyMeaning
200KnowledgeStatsSuccessful operation
400ErrorResponseStructured API error
401ErrorResponseMissing or invalid credentials
403ErrorResponseRole or ownership denied
404ErrorResponseResource unavailable to this identity
409ErrorResponseRevision, idempotency, immutable version or lease conflict
413ErrorResponseStructured API error
422ErrorResponseCapability input/output schema violation
429ErrorResponseCapacity exceeded
500ErrorResponseStructured API error
503ErrorResponseStructured API error

Example response 200

{
  "average_chunk_tokens": 0.0,
  "chunks": 0,
  "documents": 0,
  "limits": {
    "chunk_bytes": 0,
    "chunk_chars": {
      "default": 0,
      "max": 0,
      "min": 0
    },
    "chunk_overlap_default": 0,
    "chunks_per_document": 0,
    "chunks_per_scope": 0,
    "doc_id_chars": 0,
    "documents_per_batch": 0,
    "documents_per_scope": 0,
    "list_limit": 0,
    "metadata_bytes": 0,
    "offset": 0,
    "query_chars": 0,
    "query_terms": 0,
    "term_chars": 0,
    "text_bytes": 0,
    "title_chars": 0,
    "top_k": 0
  },
  "postings": 0,
  "scope": "session",
  "strategy": "bm25",
  "terms": 0,
  "text_bytes": 0,
  "tokens": 0
}
ATFGraph documentationHosted workflow · Framework reference