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.
2,500 free credits · no card · model calls go to your provider on your own keys
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. It is open source under Apache-2.0, so that boundary is something you can read rather than something you have to take on trust.
You bring 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 retrieval engine is published on its own under Apache-2.0, as a Python package and a JavaScript one over the same schema. The full engine guide covers installing it, ingesting, searching and serving it yourself.
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, SQLite, 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.
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.
For the retrieval engine on its own — ingesting, searching and serving it inside your own software — the packages and the step-by-step reference are on the context engine guide.
Each project is itself a Model Context Protocol server at its own URL, so an MCP client — a coding tool, an assistant, anything that speaks the protocol — gets that project’s knowledge and its governed tools with the caller’s permissions intact. Same agents, same approval rules, same audit trail, reached through a different door.
Authorise with a scoped API key created under API inside the project. One server per project, and the key’s grants decide what it can reach.
{
"mcpServers": {
"promptev": {
"url": "https://app.promptev.ai/mcp/acme/ops",
"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. 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.
One URL per project gives an MCP client that project’s knowledge and governed tools, with the same permissions a person would have.
<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 · Pricing
Promptev is pay as you go. A new workspace is granted 2,500 credits once, at signup, with no card required and no seats to buy; after that you buy credits when you need them, from $5, with receipts always available and invoices as an option. Auto top-up keeps a busy workspace running without anyone watching the balance. Nothing is withheld behind a tier — single sign-on, audit, approvals and the rest are in the product for every workspace, including a free one. Enterprise is an annual licence for a custom deployment in your own cloud account or on your own premises, sized to your estate rather than to a seat count — [email protected]. The full detail is on the pricing page.
| Work | Credits |
|---|---|
| A chat turn | 1 |
| Each tool call | 1 |
| An API call | 1 |
| A knowledge search | 1 per source pack it reads |
| A graph search | 5 |
| Model tokens | Billed by your provider, on your keys |
11 · FAQ
No. A new workspace is granted 2,500 credits once, at signup — room to connect a source, read a real document and hold a genuine conversation with an agent. After that you buy credits when you need them, from $5. There are no seats, no monthly plans, and no feature held behind a tier.
Your own. Promptev is bring-your-own-key and does not sell model tokens: 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, eight 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.
A chat turn is 1 credit, each tool call is 1 credit, an API call is 1 credit, a knowledge search is 1 credit for each source pack it reads, and a graph search is 5. Reading a document into knowledge costs credits by its size. Model tokens are billed by your own provider on your own keys and are never marked up by us.
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.
No. There is no add-on and no plan to be on. An agent answering an MCP client, or a call to its URL, is billed exactly as any other turn — a credit for the turn and a credit for each tool call it makes.
Start here
2,500 credits, granted once, with no card. If you would rather be walked through it, we will do that instead.