Overview
Every call goes to https://api.promptev.ai with a project API key. The key names the project, so nothing about the project is in the request. A key reads and writes only its own project.
| Route | What it does |
|---|
| POST /api/v1/documents | Upload files into the project’s knowledge base. Multipart: one files part per file, and an optional mode. |
| POST /api/v1/knowledge | Read the project’s knowledge base. JSON: an action and that action’s fields, the same as the knowledge tool. |
Every route, field and answer is in the HTTP API reference.
Your API key
Make a key in the promptev app, under your project’s API keys. It starts with fk_. Keep it in an environment variable, not in your shell history or in a script.
export PROMPTEV_API_KEY=fk_...
Upload files
Send each file as a files part. Up to 20 files per call, 25 MB each. The files go into the project’s Uploads source, the same one the app writes to, so the project’s agents can use them on the next turn. Uploading identical bytes again updates the document, it does not make a copy.
curl -X POST https://api.promptev.ai/api/v1/documents \
-H "Authorization: Bearer $PROMPTEV_API_KEY" \
-F "files=@handbook.pdf" \
-F "files=@policies/refunds.pdf"
# The same, and also build the Context Graph (entities and relationships)
curl -X POST https://api.promptev.ai/api/v1/documents \
-H "Authorization: Bearer $PROMPTEV_API_KEY" \
-F "files=@contracts.pdf" \
-F "mode=graph"
{
"results": [
{"filename": "handbook.pdf", "status": "ok", "document_id": "...", "chunks": 42, ...},
{"filename": "refunds.pdf", "status": "ok", "document_id": "...", "chunks": 6, ...}
]
}An upload returns when every file is ready. A long scan can take minutes, so do not give curl a short --max-time. mode=graph works when the Context Graph is available for the workspace (see Settings).
Search
Start with discover to see what is in the knowledge base, then search for passages or get_doc for one whole document.
curl -X POST https://api.promptev.ai/api/v1/knowledge \
-H "Authorization: Bearer $PROMPTEV_API_KEY" \
-H "Content-Type: application/json" \
-d '{"action": "discover"}'curl -X POST 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}'{
"success": true,
"hits": [
{"document_id": "...", "document_name": "Refund policy", "chunk_text": "...",
"score": 0.83, "source_id": "...", "chunk_idx": 4}
],
...
}curl -X POST https://api.promptev.ai/api/v1/knowledge \
-H "Authorization: Bearer $PROMPTEV_API_KEY" \
-H "Content-Type: application/json" \
-d '{"action": "get_doc", "document_id": "3f2b8c1e-5a4d-4e8f-9b61-2c7d0a9e4f10"}'Pipe the answer through jq to read it in the terminal:
curl -s -X POST 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}' \
| jq -r '.hits[] | "\(.score) \(.document_name)"'All 13 actions and their fields are in the knowledge tool reference. A knowledge call costs 1 credit, and a search 1 more (5 more when the Context Graph is searched). There is no extra API-call charge.
SDK one-liners
The same calls through the promptev SDKs, when you want the answer as data rather than JSON text.
pip install promptev
# Upload
python -c 'from promptev import PromptevClient; import os; print(PromptevClient(api_key=os.environ["PROMPTEV_API_KEY"]).upload_document("handbook.pdf").status)'
# Search
python -c 'from promptev import PromptevClient; import os, json; c = PromptevClient(api_key=os.environ["PROMPTEV_API_KEY"]); print(json.dumps(c.search_knowledge_base("search", query="how many days do customers have to ask for a refund", top_k=5), indent=2))'npm install @promptev/client
# Search (Node 18+, ES module)
node --input-type=module -e '
import { PromptevClient } from "@promptev/client";
const client = new PromptevClient({ apiKey: process.env.PROMPTEV_API_KEY });
const found = await client.searchKnowledgeBase("search", { query: "how many days do customers have to ask for a refund", top_k: 5 });
console.log(JSON.stringify(found, null, 2));
'Status codes
| Status | Meaning |
|---|
| 200 | The answer. For /documents, one row per file, each with its own status and error: one failed file never fails the batch. |
| 401, 403 | The key is missing, malformed, revoked or expired. |
| 402 | The workspace is out of credits. |
| 404 | The key’s project was not found. |
| 422 | The knowledge base could not answer: an unknown action, a missing field, or an action that is off. The body says why in one sentence. |
| 429 | A rate limit refused it. Wait and try again. |