Workspace
Your companyMembers and roles, billing and credits, storage, the audit trail, connector settings, single sign-on and the model keys. One workspace is one company.
Documentation
Promptev builds AI agents that answer from your company’s own documents and data, and that act through the tools your team already uses, limited, always, to what the person asking is allowed to see. This page is the whole surface end to end: what a workspace is, how to get a working agent this afternoon, and how to run one from your own code.
01 · Overview
Promptev is context-aware AI for a company. It reads the files, wikis, mailboxes and tickets your team already works in; it answers questions from them and shows the documents an answer came from; and it acts through the same tools a person would use, filing a ticket, writing to a sheet, sending a message, querying a database.
The part that decides what a model is allowed to know is the context engine, and it carries the identity of the person asking into the search itself, so material they could not open is never retrieved for them. promptev hosts it, and you reach it through the SDKs, the API and MCP.
Agents run on PromptevAI or on your own model keys, and you choose whether Promptev runs it for you, runs in your own cloud account, or runs on your own machines.
Two layers, and everything else lives inside them.
Members and roles, billing and credits, storage, the audit trail, connector settings, single sign-on and the model keys. One workspace is one company.
Its own agents, knowledge, tools and API keys. A finance project and a support project never see each other’s material, so a project is the boundary you draw when work must stay separate.
Instructions in plain words, a model, the knowledge it may use and the tools it may call, each tool with its own approval rule. Agents live inside a project.
Knowledge, tools and connectors live in a project rather than in the workspace, which is what makes the separation real: a source connected for finance is not reachable from the support project unless you connect it there too.
Roles decide who may build and who may only talk. Owner and admin run the workspace; an editor builds agents, knowledge and tools inside a project; a viewer talks to agents and nothing else, which is the right role for most staff. Projects carry their own roles as well, so one person can build in one project and only chat in another.
02 · Quickstart
An afternoon is a realistic first result. Nothing here needs code, and nothing here needs a card.
Create a workspace, then a project. Inside the project open Connectors, choose the service, and authorise it once with your own account, then pick exactly what Promptev should read: a particular Drive folder, a Confluence space, a Jira project, rather than everything you can see. You can also simply upload files under Knowledge. Permissions travel with the content either way, and a connected source stays in step as its files change.
Paste a key for the provider you already use under AI providers. Then create an agent in the project: say what it should do in the language you would use with a colleague, attach the knowledge it may use, choose the model, and add the tools it may call, giving each tool its approval rule. Test it in the built-in chat before anyone else sees it.
Invite people under Members and they can talk to it in the App. Or attach it to Slack or WhatsApp, drop it on your own site with one script tag, share a hosted portal link, or call it from your own code. Same agent, same permissions, same audit trail, whichever door it is reached through.
Ask it something you already know the answer to. A grounded answer comes back with the documents it came from, and you can open them.
03 · Knowledge
Files you upload, documents, presentations, spreadsheets, scans and images, and sources you connect. A project can hold several knowledge bases, each with its own sources, so a staff handbook and a contract archive need not be one pile.
Those sixteen services are reached through seven app registrations, because Google’s products share one application, Microsoft’s share another, and Jira and Confluence share an Atlassian one, so a company approves seven applications, not sixteen. Use Promptev’s verified applications to start in minutes, or register your own so the consent screen your staff see carries your company’s name.
Text, tables and layout are extracted; scanned pages and images are read by a vision model on your own key; and sensitive values can be masked before anything is stored. You can watch each file being read and re-read one on demand if its source changed.
An answer arrives with the documents it came from, and you can open them. An agent that cannot find the answer is expected to say so rather than fill the gap.
This is the part that matters. The identity and groups of the person asking are part of the search itself, so a document someone could not open is never fetched in the first place, not fetched and filtered out afterwards. One agent can therefore answer a finance director and a contractor correctly, on the same question, without two copies of it and without a rule somebody has to remember to write.
The knowledge base is yours to use from your own code too, through the Python SDK and the JavaScript one, the HTTP API and the project MCP server: put documents in, then search them with the same permissions. The context engine guide covers uploading and searching, and the reference pages cover the knowledge tool, the HTTP API, the command line, settings and benchmarks.
04 · Agents
An agent is made of four things, all of them editable by someone who does not write code.
Every tool an agent holds is set to exactly one of these, by whoever builds the agent.
A refusal grants nothing, the next call asks afresh. An approval rule an admin set when registering a tool is the floor: an agent’s own setting may tighten it, never weaken it. Requests reach the people you name in the App, by e-mail or in Slack, and they expire rather than waiting forever. Everything an agent does, approved or not, lands in an audit trail a person can read.
05 · Tools
The eight apps you connect are 16 services and 198 built-in tools once the sub-services are counted. Everything beyond them is a configuration task rather than a feature request.
Across 16 services: files and folders, mail, calendars, spreadsheets, documents and slides, issues, boards, repositories, pipelines, wiki pages, channels and messages.
Point Promptev at any REST or HTTP endpoint, an internal service, a partner’s API, a product with no ready-made connector, describe its inputs, and it becomes a tool an agent calls. Nothing about it is second-class: the same approval rules, the same audit trail.
Attach a Model Context Protocol server you run or trust and its tools appear beside the built-in ones. It works in the other direction too, see the MCP server below.
Agents query your databases in plain language and hand back tables or charts. PostgreSQL, MySQL, MariaDB, SQL Server, Oracle, ClickHouse and Snowflake. Read-only by default, and you choose which schemas and tables are even visible.
So the practical answer to “do you integrate with X?” is yes, through a connector where one exists, and otherwise through an HTTP tool, a database connection or an MCP server, without waiting for us to build anything.
06 · Orchestrations
An orchestration is a team. You place agents from a project on a canvas and connect them so each does a part and passes the work along, a lead that decides who to call, and the specialists it calls.
A run can pause for an approval and resume where it left off rather than starting again, and it is visible while it happens and afterwards: what each agent did, what it called, what it produced.
Because a team of agents is not a request and a response, a call to an orchestration is accepted rather than answered, a run id comes back immediately and the work continues without you.
07 · The API
Every agent and every orchestration has an always-on callable URL. Post to it from a script, a form, a scheduler, a workflow tool, or your own product.
https://<host>/api/hooks/<slug>/<token>The token in the path is the authorization. There is no separate header to send. It is shown once, when you generate it, and regenerating it revokes the old URL, so treat the whole URL as a secret, keep it out of source control, and rotate it if it ever leaks. A wrong token and a URL that never existed answer identically, so nothing can be learned by guessing.
The host is your workspace’s: app.promptev.ai for a workspace Promptev runs, or your own hostname for a deployment in your cloud or on your premises.
Send a JSON body with a message. The agent runs and the answer comes back in the response, this door waits, because a call to a single agent almost always wants its reply.
curl -X POST \
https://app.promptev.ai/api/hooks/support-triage/9f3c…a71 \
-H 'Content-Type: application/json' \
-d '{"message": "Summarise ticket 4821 and draft a reply."}'200 OK
{
"status": "ok",
"answer": "Ticket 4821 is a billing question about the March invoice…",
"usage": { "input": 4180, "output": 260 }
}An HTTP request cannot wait out a human, so if the agent reaches a tool that needs an approval the call returns straight away saying so, with the id of the request now waiting and the tool it is waiting on. Approve it in Promptev, then call again.
202 Accepted
{
"status": "pending_approval",
"approval_id": "8b41c0e2-…",
"tool": "jira_create_issue"
}The JSON body’s keys are that orchestration’s own declared input keys, exactly the fields its intake form shows, so the manual and the programmatic entry points agree. A team of agents is not a request and a response, so the call is accepted and you get a run id to follow.
curl -X POST \
https://app.promptev.ai/api/hooks/month-end-close/4d81…c02 \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: close-2026-03' \
-d '{"period": "2026-03", "entity": "Acme GmbH"}'202 Accepted
{
"run_id": "0a9f2d64-…",
"status": "accepted"
}When an orchestration declares one of its inputs as a file input, send the request as multipart/form-data instead of JSON: one part named payload carrying the JSON body you would otherwise have sent, and one part per file named after the input it fills — so an orchestration with a contract file input takes contract parts. That is what lets one call fill two different file inputs. A part named after something that is not a file input is refused rather than quietly ignored, because a dropped file becomes an answer that ignored your document. At most five files per call.
curl -X POST \
https://app.promptev.ai/api/hooks/contract-review/4d81…c02 \
-H 'Idempotency-Key: contract-8891' \
-F 'payload={"matter": "Acme renewal"}' \
-F 'contract=@./acme-renewal.pdf' \
-F 'contract=@./acme-addendum.pdf'Put plainly: use JSON when there are no files, multipart when there are. The endpoint accepts either, and everything else, the token in the path, the input keys, idempotency, the response, is unchanged.
An input the orchestration declares as required must be present in the body. A call that omits one is refused with a 422 naming the field, so the error tells you which value was missing rather than only that something was wrong.
Send an Idempotency-Key header, an order number, a message id, a UUID, anything stable for that piece of work. A retried call carrying the same key returns the run it already started instead of starting a second one, which is what you want from a network you do not control. Two identical bodies with no key are treated as two real events, because they often are.
The callable URL above is one URL for one agent, and its token travels in the address, right for handing to Zapier or a no-code tool, tedious when your own software talks to several agents. For that there is a second door: a scoped API key, created under API inside a project, sent as a normal Authorization header.
A key belongs to one project. It reaches every published agent and orchestration in that project by name, and nothing outside it, an orchestration in a sibling project answers the same “not found” an invented name does. What the key may retrieve is its own grant, set when you create it; it is never workspace-wide.
curl -X POST \
https://api.promptev.ai/api/v1/orchestrations/month-end-close/run \
-H 'Authorization: Bearer fk_…' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: close-2026-03' \
-d '{"period": "2026-03", "entity": "Acme GmbH"}'It answers 202 with a run id, exactly as the callable URL does. Read the outcome when you want it:
curl https://api.promptev.ai/api/v1/runs/0a9f2d64-… \
-H 'Authorization: Bearer fk_…'200 OK
{
"run_id": "0a9f2d64-…",
"orchestration": "month-end-close",
"status": "delivered",
"created_at": "2026-03-01T09:00:04Z",
"output": "March closed. Three accruals needed adjustment…"
}status is running while the team works, then delivered, or awaiting_review if the orchestration asks a person to sign off. output appears only once there is one, so you are never handed a half-written answer to act on.
The key also reads and writes its project’s knowledge base through the Context Engine. Ingestion puts documents in; retrieval searches them and answers only with what the project holds.
https://api.promptev.ai/api/v1/documentscurl -X POST https://api.promptev.ai/api/v1/documents \
-H 'Authorization: Bearer fk_…' \
-F 'files=@./handbook.pdf' \
-F 'files=@./refund-policy.docx'import { PromptevClient } from "@promptev/client";
const client = new PromptevClient({ apiKey: process.env.PROMPTEV_API_KEY });
// files: File or Blob objects, or { name, content } pairs
const { results } = await client.uploadDocument(files);
for (const r of results) console.log(r.filename, r.status, r.document_id);from promptev import PromptevClient
client = PromptevClient(api_key=os.environ["PROMPTEV_API_KEY"])
results = client.upload_documents(["handbook.pdf", "refund-policy.docx"])
for r in results:
print(r.filename, r.status, r.document_id)Up to 20 files per call, 25 MB each. Add -F 'mode=graph' to build the Context Graph from them as well.
https://api.promptev.ai/api/v1/knowledgecurl -X POST https://api.promptev.ai/api/v1/knowledge \
-H 'Authorization: Bearer fk_…' \
-H 'Content-Type: application/json' \
-d '{"action": "search", "query": "how many days do customers have to ask for a refund", "top_k": 5}'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 });
for (const hit of found.hits) console.log(hit.document_name, hit.score, hit.chunk_text);from promptev import PromptevClient
client = PromptevClient(api_key=os.environ["PROMPTEV_API_KEY"])
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"])200 OK
{
"success": true,
"hits": [
{
"document_id": "1d3b0c71-…",
"document_name": "refund-policy.docx",
"chunk_text": "Customers can ask for a refund within 30 days…",
"score": 0.82
}
]
}action is any action of the knowledge tool: discover to see what is there, search for passages, get_doc for one document, and the rest on the knowledge tool page. The full request and response shapes are on the HTTP API page.
Two clients wrap that surface: @promptev/client on npm and promptev on PyPI. They stream a chat turn from an agent, put documents into the project’s knowledge, and start an orchestration and follow it:
import PromptevClient from "@promptev/client";
const client = new PromptevClient({ apiKey: process.env.PROMPTEV_API_KEY });
const started = await client.runOrchestration("month-end-close", {
period: "2026-03",
});
let run = await client.getRun(started.run_id);
while (run.status === "running" || run.status === "revising") {
await new Promise((r) => setTimeout(r, 2000));
run = await client.getRun(started.run_id);
}
console.log(run.output);from promptev import PromptevClient
client = PromptevClient(api_key=os.environ["PROMPTEV_API_KEY"])
started = client.run_orchestration("month-end-close", {"period": "2026-03"})
run = client.get_run(started.run_id)
while not run.done:
time.sleep(2)
run = client.get_run(started.run_id)
print(run.output)Files work the same way they do over curl, one part per file, named after the input it fills:
# The part is named after the input it fills.
client.run_orchestration(
"contract-review",
{"matter": "Acme renewal"},
files={"contract": "acme-renewal.pdf"},
)Every Python method has an async twin (arun_orchestration, aget_run), and both clients bound a batch locally before it goes on the wire, so a file that is too large is refused without spending the call. Pass an idempotency key and a retried start returns the run you already made; without one the clients deliberately do not retry a start, because only you can say whether two calls are one event.
Ingestion and retrieval in the clients: upload_document and search_knowledge_base in Python, uploadDocument and searchKnowledgeBase in JavaScript, shown above beside each curl. Every option, return shape and error is on the Python SDK page and the TypeScript SDK page.
promptev speaks the Model Context Protocol in two ways, for two different jobs. Both follow the latest version of the protocol, and both keep the same permissions, approval rules and audit trail as the App.
One address for everyone, https://api.promptev.ai/mcp. Add it to Claude, Claude Code, ChatGPT, Cursor, GitHub Copilot, Windsurf, Gemini or any MCP client that supports remote servers and sign in with your promptev account: no key to copy. On the sign-in page you pick one workspace and choose what the app may do, from reading your projects to creating agents, attaching knowledge and tools, and publishing. The app then works as you, with your own role and project permissions, never more.
{
"mcpServers": {
"promptev": {
"url": "https://api.promptev.ai/mcp"
}
}
}Each project is also an MCP server at its own address, for tools and services rather than people. Authorise with a scoped API key created under API inside the project; the key’s grants decide what it can reach, and it can expire or be revoked.
{
"mcpServers": {
"promptev-ops": {
"url": "https://api.promptev.ai/api/v1/mcp/acme/ops/mcp",
"headers": { "Authorization": "Bearer pk_…" }
}
}
}The client discovers what is there rather than loading all of it: it lists the tools and the agents in the project, searches the knowledge base, calls a tool, or calls an agent and lets that agent’s own instructions, knowledge and tools do the work. A tool that needs a person’s approval asks right in the client when the client can show it, and otherwise waits for an admin in the App or by e-mail. There is no separate charge for MCP, a turn and its tool calls are billed like any other.
08 · Channels
The same agent, with the same permissions and the same audit trail, wherever you put it. Nothing is rebuilt per channel.
A branded page for one agent, restricted to the people you name or to your company’s e-mail domain. The quickest way to give a team something to use before anything is embedded.
A chat box on your site. It renders in the page rather than in a frame, so it can carry your styling, and it answers only on the origins you allow.
In channels and direct messages, answering in the thread it was asked in. Approvals can be answered in Slack too.
For the people who will never open another tool. Documents, images and voice notes come in, and a generated file goes back out as a file.
The endpoint documented above, plus scoped API keys per project. Post to it from a script, a scheduler or your product.
Sign in from Claude, ChatGPT or any MCP client to build in your workspace as yourself, or give a tool one project’s knowledge and agents with a scoped key.
<script src="https://app.promptev.ai/embed.js"
data-agent="support-website"
data-theme="auto"></script>09 · Security & data
Promptev’s use of information received from Google APIs adheres to the Google API Services User Data Policy, including the Limited Use requirements.
10 · FAQ
PromptevAI, promptev’s own models, with no key, its cost deducted from your credits. Or bring your own key: you paste a key for the provider you already use, and model calls go straight to that provider on your credentials, for chat, for embedding, and for reading scanned pages. A self-hosted or OpenAI-compatible endpoint of your own works the same way, so a model running inside your network is a supported choice rather than a special case.
No. The identity and groups of the person asking are part of the retrieval query itself, so a document they could not open is never fetched, not fetched and then filtered out. That is why one agent can answer a finance director and a contractor correctly, on the same question, without two copies of it.
Eight apps arrive ready: Google Workspace, Microsoft 365, Dropbox, Confluence, Jira, Azure DevOps, Slack and WhatsApp, which are 16 services and 198 tools between them. Everything else is reached three ways that do not wait on us: any REST or HTTP API as an HTTP tool, seven database engines as database tools, and any MCP server you run or trust. All three obey the same approval rules and land in the same audit trail as a built-in tool.
Managed by Promptev, inside your own cloud account in whatever region you choose, or fully on your own machines. The product is the same in all three. Independently of that, a workspace can run its documents, embeddings and retrieval on a database you own, and keep files in your own cloud bucket.
Every tool an agent holds carries one of three rules. No approval, it just runs, which is right for reading. Ask once, the first call to that tool in a conversation stops for a person, and once approved the rest of that conversation runs. Always ask, every call stops, however many there are. A refusal grants nothing: the next call asks again. Requests reach a person in the App, by e-mail or in Slack, and they expire rather than waiting forever.