Context Engine HTTP API reference

Overview

The Context Engine is hosted by promptev. The base URL is https://api.promptev.ai. The Python and TypeScript SDKs call these same routes, so use them when you can: they check limits before sending, retry passing errors and raise one error class per status.

Authentication

Create a project API key under the project’s API keys in the promptev console. Send it on every request:

Authorization: Bearer fk_...

A key belongs to one project. It reads and writes that project’s knowledge base and nothing outside it, so no request names a project. Keep the key on your server.

POST /api/v1/documents

Put documents into the project, in the same Uploads source the console writes to. The project’s agents can use them on their next turn. The request returns when every file is ready, so allow a long timeout for large files.

curl https://api.promptev.ai/api/v1/documents \
  -H "Authorization: Bearer $PROMPTEV_API_KEY" \
  -F "files=@handbook.pdf" \
  -F "files=@pricing.xlsx" \
  -F "mode=graph"

# Replace the uploaded handbook.pdf in place instead of adding a second one
curl https://api.promptev.ai/api/v1/documents \
  -H "Authorization: Bearer $PROMPTEV_API_KEY" \
  -F "files=@handbook.pdf" \
  -F "update=handbook.pdf"

The answer has one row per file, in order. A file that fails is reported in its own row (status "failed" and an error) and never fails the others:

{
  "results": [
    {
      "filename": "handbook.pdf",
      "status": "…",
      "document_id": "…",
      "chunks": 42,
      "units": 12,
      "error": null
    },
    {
      "filename": "pricing.xlsx",
      "status": "failed",
      "document_id": null,
      "chunks": 0,
      "units": 0,
      "error": "…"
    }
  ]
}

An upload costs 1 credit per page, slide or MB, at least 1 per file.

POST /api/v1/knowledge

Read the project’s knowledge base. It is the same tool, with the same actions and fields, as search_knowledge_base on the project’s MCP server. The body is a JSON object: action plus that action’s fields. Start with discover.

curl https://api.promptev.ai/api/v1/knowledge \
  -H "Authorization: Bearer $PROMPTEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "discover"}'

curl https://api.promptev.ai/api/v1/knowledge \
  -H "Authorization: Bearer $PROMPTEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "search", "query": "how many days do customers have to ask for a refund", "top_k": 5}'

curl https://api.promptev.ai/api/v1/knowledge \
  -H "Authorization: Bearer $PROMPTEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "get_doc", "document_id": "…"}'

Each call costs 1 credit, plus 1 for a search (5 when the graph is searched). There is no extra API-call charge.

Actions and fields

The graph actions (get_neighbors, traverse, find_related, community_summary) need documents uploaded in graph mode. discover says which actions the project can run.

Responses

A search answers with hits, best first:

{
  "hits": [
    {
      "document_id": "…",
      "document_name": "refund-policy.pdf",
      "chunk_text": "Refunds are accepted within 30 days …",
      "score": 0.82,
      "source_id": "…",
      "chunk_idx": 4
    }
  ]
}

discover and list page through documents. When has_more is true, send next_cursor back as cursor, or simply send next_page as the next body:

{
  "documents": [
    { "id": "…", "name": "handbook.pdf", "source_id": "…", "kind": "text" }
  ],
  "count": 50,
  "has_more": true,
  "next_cursor": "…",
  "next_page": { "action": "list", "cursor": "…" }
}

An answer may carry a next_action: the next call, already filled in. Errors carry a message that says what to fix. field is there when the server knows which field is at fault:

{
  "error": {
    "message": "…",
    "field": "files"
  }
}

Status codes