Context Engine: guide

Overview

The Context Engine is the knowledge layer of promptev. You give it your documents (PDF, Word, Excel, CSV, slides and more). It finds the passages that answer a question, reads whole documents, works out figures from your spreadsheets, and shows how people, companies and things connect. Every answer cites its sources, and each caller sees only what they are allowed to see.

promptev hosts the engine. You use it in two ways: ingestion (put documents in) and retrieval (search them). The same knowledge tool is behind every way in: the SDKs, the HTTP API, MCP and the agents you build in promptev. Every sample comes in Python and TypeScript: pick one with the toggle at the top of the page.

1 · Get a project API key

Open your project in the promptev console and create a key under the project’s API keys. It starts with fk_. A key belongs to one project: it reads and writes that project’s knowledge base and nothing else, so no call names a project.

Send it as Authorization: Bearer fk_.... Keep it on your server. Never put it in a browser or a mobile app.

2 · Install an SDK

Both SDKs are version 1.3.0. The Python SDK needs Python 3.8 or later.The JavaScript SDK runs anywhere fetch does.

pip install promptev

npm install @promptev/client

from promptev import PromptevClient

client = PromptevClient(api_key="fk_...")

import { PromptevClient } from "@promptev/client";

const client = new PromptevClient({ apiKey: "fk_..." });

3 · Upload documents

An upload goes into the project’s knowledge base, in the same Uploads source the console writes to. The project’s agents can use it on their next turn. Each file gets its own result: one file that fails never fails the others.

result = client.upload_document("handbook.pdf")
print(result.status, result.document_id, result.chunks)

# Up to 20 files per call, 25 MB each
results = client.upload_documents(["refunds.pdf", "pricing.xlsx"])
for r in results:
    print(r.filename, r.status, r.error or "")

# Also extract people, companies and how they connect (the Context Graph)
client.upload_document("org-chart.pdf", mode="graph")

import { readFile } from "node:fs/promises";

const { results } = await client.uploadDocument(
  { name: "handbook.pdf", content: await readFile("handbook.pdf") },
  { mode: "hybrid" } // or "graph" to build the Context Graph as well
);
for (const r of results) console.log(r.filename, r.status, r.error ?? "");

For a large or changing set of files, connect the source in the console instead (Google Drive, SharePoint and OneDrive, Slack, Dropbox, Atlassian and more). promptev keeps it in sync, and the same calls search it.

4 · Search the knowledge base

One method reads the knowledge base: you name an action and pass its fields. Start with discover to see what is there, then search for passages or get_doc for a whole document.

overview = client.search_knowledge_base("discover")

found = client.search_knowledge_base("search", query="how many days do customers have to ask for a refund", top_k=5)
for hit in found["hits"]:
    print(hit["document_name"], hit["score"], hit["chunk_text"][:80])

doc = client.search_knowledge_base("get_doc", document_id=found["hits"][0]["document_id"])

const overview = await client.searchKnowledgeBase("discover");

const found = await client.searchKnowledgeBase("search", { query: "how many days do customers have to ask for a refund", top_k: 5 });
for (const hit of found.hits) console.log(hit.document_name, hit.score, hit.chunk_text);

const doc = await client.searchKnowledgeBase("get_doc", { document_id: found.hits[0].document_id });

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
    }
  ]
}

5 · Knowledge actions

The same actions work from the SDKs, the HTTP API and MCP. The SDKs list them in KNOWLEDGE_ACTIONS. The graph actions need documents uploaded in graph mode; discover says which actions your project can run.

top_k defaults to 10. mode on a search is "hybrid" or "graph"; leave it out and the right one is chosen for you. Full field notes are on the knowledge tool page.

6 · HTTP

No SDK needed. The base URL is https://api.promptev.ai, with the same Bearer key.

curl https://api.promptev.ai/api/v1/documents \
  -H "Authorization: Bearer $PROMPTEV_API_KEY" \
  -F "[email protected]" \
  -F "[email protected]"

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}'

Every field, response and status code is on the HTTP API page.

7 · MCP

Every promptev project has its own MCP server. Add it to any MCP client with the project’s URL and key from the console. Its search_knowledge_base tool is the same tool, with the same actions and fields, and its upload_document tool adds a file. The tool describes itself to the model, so the model knows to call discover first.

8 · Permissions

Each search returns only what the caller may see. A project API key reads its whole project and nothing outside it. People in the promptev app see only what their access allows, also when an agent searches for them. Answers cite their sources, so every claim can be checked.

9 · Your models, your database

A workspace can bring its own:

These are workspace settings in promptev. The SDK and API calls on this page stay the same. To run the whole platform in your own cloud or on premises, ask about Enterprise.

10 · Cost

Calls are paid in credits, at $0.005 a credit.

Knowledge calls from the SDKs and the HTTP API cost the same as on MCP, with no extra API-call charge. The rates are the same for every workspace, including one on its own database and models.

11 · Errors

The SDKs raise one error class per status. Each carries the message, the status code and, when the server said which, the field at fault. A 502, 503 or 504 is retried for you, then raised as ServerError.