Build on your bid decisions.
Pull your pursuits, bid calls, deadlines and results out of Paavya and into your dashboards, your CRM and Claude. Pick what you are building and follow its steps. Everything here works today unless it says Coming soon.
What are you building?
- Available Build a dashboard Pipeline by stage, bid calls and fit scores, what is due, and win and loss results. Start here
- Available Sync your CRM Keep pursuits and results in step with your CRM or data warehouse. Start here
- Available Connect Claude Ask Claude what is due, why you bid, and how bids ended, through Paavya's MCP server. Start here
- Coming soon Sync your knowledge Bring approved content from SharePoint or Confluence into your Library. See what works today
Quickstart: your first call in three steps
-
Get a key
In Paavya, an owner or admin opens Settings › API, names the key after what will use it, picks its scopes and presses Create key. Copy the key then: it is shown once. The API is on the Growth and Team plans.
-
Check it
Keep the key on your server, in an environment variable, then call
health. It needs no scope, so it tells a wrong key from a key that cannot do something.export PAAVYA_KEY="pv_live_..." curl https://app.paavya.com/api/v1/health \ -H "Authorization: Bearer $PAAVYA_KEY"It worked if you see
"ok": trueand your key's scopes. A401means the key is wrong or revoked. -
Read your pursuits
curl "https://app.paavya.com/api/v1/pursuits?limit=5" \ -H "Authorization: Bearer $PAAVYA_KEY"A pursuit is a bid your team is weighing or answering. Each one comes back with its name, buyer, stage, status, due date, contract value, the bid call and its fit score.
{ "data": [{ "id": "8f0c…", "name": "SCADA upgrade", "status": "in-progress", "stage": "decide", "due_date": "2026-12-04", "buyer": "City of Riverbend", "value": 4200000, "fit_score": 72, "decision": { "call": "bid", "rationale": "We hold the incumbent work.", "decided_at": "2026-11-01T14:02:00Z", "revisit_on": null }, "created_at": "…", "updated_at": "…" }], "limit": 5, "offset": 0 }
Build a dashboard
Show leadership the pipeline, what is due, and how bids ended, in the BI tool or internal page they already read.
Do this next
- Make a key with
pursuits:readandoutcomes:read. Nothing else: a dashboard never writes. - Pull
/v1/pursuitsfor the pipeline, paging withlimitandoffsetuntil a page comes back short. - Pull
/v1/deadlinesfor what is due, and/v1/outcomesfor results. - Refresh every few minutes from your server, never from the browser.
// Node 18+: pipeline by stage, bid calls, and results
const base = 'https://app.paavya.com/api/v1';
const headers = { Authorization: `Bearer ${process.env.PAAVYA_KEY}` };
const get = async (path) => {
const r = await fetch(base + path, { headers });
if (!r.ok) throw new Error((await r.json()).error.message);
return r.json();
};
const pursuits = [];
for (let offset = 0; ; offset += 100) {
const page = await get(`/pursuits?limit=100&offset=${offset}`);
pursuits.push(...page.data);
if (page.data.length < 100) break;
}
const byStage = {};
for (const p of pursuits) byStage[p.stage || 'none'] = (byStage[p.stage || 'none'] || 0) + 1;
const due = (await get('/deadlines?within_days=14')).data; // late ones first
const results = (await get('/outcomes?limit=100')).data;
const won = results.filter((o) => o.kind === 'award_won').length;
const lost = results.filter((o) => o.kind === 'award_lost').length;
console.log({ byStage, dueSoon: due.length, late: due.filter((d) => d.late).length, won, lost });What each field means
- fit_score is out of 100, from Paavya's bid read. It is not a chance of winning.
nullmeans not scored yet. - decision.call is
bid,holdorno-bid, as your team recorded it, with the reason they gave.nullmeans no call yet. - due_date is the response date. value is the contract value when a number is on record. Either can be
null. - Deadlines lists open pursuits only (not sent, not declined, not archived), late ones first with
"late": true. Days are counted in UTC.
Sync your CRM
Keep each pursuit and its result in step with your CRM or warehouse, keyed on Paavya's pursuit id.
Using Salesforce? Start with Paavya's Salesforce connector under Settings › Connectors: an admin sets it up once, with no code. Use the API for any other CRM, or for your own mapping.
Do this next
- Make a key with
pursuits:read. Addoutcomes:writeonly if your CRM should send results back. - Every 15 minutes, ask for what changed since your last run and upsert each row on its
id. - Store the time you asked, and use it as
updated_sincenext time. - When a deal closes in your CRM, send the result to Paavya with
POST /v1/outcomes.
# What changed since the last run
curl "https://app.paavya.com/api/v1/pursuits?updated_since=2026-11-17T09:00:00Z&limit=100" \
-H "Authorization: Bearer $PAAVYA_KEY"
# Send a result back. A loss needs a reason. This cannot be undone.
curl -X POST https://app.paavya.com/api/v1/outcomes \
-H "Authorization: Bearer $PAAVYA_KEY" -H "Content-Type: application/json" \
-d '{"project_id":"8f0c…","kind":"award_lost","reason_key":"price"}'- kind is
award_won,award_lostorno_decision. A loss needsreason_key, as it does in the app. - A result is added to the record and never edited. Test with a key that lacks
outcomes:writeuntil your mapping is right. - Coming soon Webhooks for a new matching opportunity, a bid call recorded and a result recorded, so you stop polling. Until then, poll as above.
Connect Claude
Paavya runs an MCP server, so Claude can read your pipeline and answer in your words: what is due, why you bid, how bids ended. It uses the same key, scopes and limits as the API.
- Server address
https://app.paavya.com/api/mcp- Transport
- Streamable HTTP
- Sign in
- A Paavya API key, sent as
Authorization: Bearer pv_live_...
Do this next
- Make a key named for the person or team using Claude, with
pursuits:readandoutcomes:read. Addoutcomes:writeonly if Claude should record results; Claude asks before it does. - Add the server to the Claude you use, below.
- Ask:
What's due in the next two weeks?
orWhy did we decide to bid on the SCADA upgrade?
Claude Code
claude mcp add --transport http paavya https://app.paavya.com/api/mcp \
--header "Authorization: Bearer $PAAVYA_KEY"Claude on the web and desktop
Add Paavya as a custom connector: in Claude, open Settings › Connectors › Add custom connector, enter the server address, and add the request header Authorization with the value Bearer and your key. On a Team or Enterprise plan, an owner may need to add it for your organization.
Your own app, through the Claude API
Pass Paavya to the Messages API's MCP connector as a server with "type": "url", "url": "https://app.paavya.com/api/mcp" and your key as authorization_token. Anthropic's MCP connector guide has the current request format.
What Claude can do with Paavya
| Tool | What it does | Scope |
|---|---|---|
check_connection | Confirms the key works and lists what it may do. | None |
list_pursuits | The pipeline: name, buyer, stage, due date, value, bid call and fit. | pursuits:read |
get_pursuit | One pursuit by its id. | pursuits:read |
get_bid_decision | The bid call with what it rested on: the reason, the recommendation, conditions and the evidence as it stood. | pursuits:read |
list_deadlines | What is due in the next N days, late ones first. | pursuits:read |
list_outcomes | Results recorded on pursuits, with the reason for a loss. | outcomes:read |
record_outcome | Records how a bid ended. The only write, and it cannot be undone. | outcomes:write |
- Claude only sees the tools your key's scopes allow. A read-only key gives Claude nothing it could change.
- Coming soon Signing in with your Paavya account instead of pasting a key.
Sync your knowledge
A knowledge API to keep approved content from SharePoint, Confluence and other systems in step with your Paavya Library is coming soon.
What works today
- In Paavya, open Library and press Add to Library.
- Upload files or a whole folder, pick files from Google Drive, or import a spreadsheet or a Loopio or Responsive export.
- Approve what you want reused. Paavya drafts only from approved answers, and a person approves each one.
To bring SharePoint or Confluence content in now, export the pages or documents and add them as files. Tell us which system you need first, and we will tell you when the API reaches it.
Keys and scopes
| Scope | Lets a key | Endpoints |
|---|---|---|
pursuits:read | Read pursuits, bid calls and deadlines | GET /v1/pursuits, /v1/pursuits/{id}, /v1/deadlines |
outcomes:read | Read recorded results | GET /v1/outcomes |
outcomes:write | Record a result | POST /v1/outcomes |
- Only an owner or admin makes or revokes a key, in Settings › API. A key works for your whole company, and it already knows which company: you never send a company id.
- Shown once. Paavya keeps only a fingerprint of the key. If you lose it, revoke it and make another.
- Scopes are fixed when the key is made. Give each key only what it needs. A company can hold 10 live keys.
- Call from a server. Send the key in the
Authorizationheader, never in a URL. The API answers no browser calls, so a key never ends up in a web page. - Revoking is instant. Anything using the key stops on its next call.
Sandbox data
A sandbox company with sample pursuits, so you can build before you connect real data, is coming soon. Until then, build against your own company with a key that only reads: reading never changes anything in Paavya. Add outcomes:write last, once your integration is right.
Limits
- Calls per key
- 100,000 a month, counted from the 1st (UTC). MCP calls count too.
- Rows per page
- Up to 100, with
limitandoffset. The default is 25. - Per second
- No per-second limit yet. Poll every few minutes, not in a loop; a limit is coming.
When something goes wrong
Every error has the same shape. Branch on type; show message to a person.
{ "error": { "type": "forbidden", "message": "This key lacks outcomes:read." } }| Type | Status | What to do |
|---|---|---|
unauthorized | 401 | The key is missing, wrong or revoked. Check the header, or make a new key. |
forbidden | 403 | The key works but lacks the scope named in the message. Make a key with it. |
not_found | 404 | No such endpoint, or the id is not one of your company's pursuits. |
bad_request | 400 | The message names the parameter or field to fix. An unknown parameter is refused, so a typo never returns everything. |
method_not_allowed | 405 | Use the method the message names. |
rate_limited | 429 | The key reached its monthly calls. It resets on the 1st, or use another key. |
server_error | 500 | Ours. Retry after a minute; if it keeps happening, tell us. |
- An empty list is an answer.
"data": []means nothing matched: no pursuits yet, nothing due in that window, or you paged past the end. - In Claude, a refused tool comes back as a sentence Claude reads to you, such as which scope the key lacks.
- Every response carries
X-Paavya-Api-Version. Fields are only ever added: read the ones you need and ignore the rest.
Coming next
- Coming soonWebhooksA new matching opportunity, a bid call recorded, a result recorded.
- Coming soonKnowledge APISync approved content from SharePoint, Confluence and more.
- Coming soonSandbox companySample pursuits to build against.
- Coming soonSign in to Claude with PaavyaConnect without pasting a key.
Building something this page does not cover? Tell us what you need.