Developers

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.

Quickstart: your first call in three steps

  1. 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.

  2. 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": true and your key's scopes. A 401 means the key is wrong or revoked.

  3. 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
    }
Available

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

  1. Make a key with pursuits:read and outcomes:read. Nothing else: a dashboard never writes.
  2. Pull /v1/pursuits for the pipeline, paging with limit and offset until a page comes back short.
  3. Pull /v1/deadlines for what is due, and /v1/outcomes for results.
  4. 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. null means not scored yet.
  • decision.call is bid, hold or no-bid, as your team recorded it, with the reason they gave. null means 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.
Available

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

  1. Make a key with pursuits:read. Add outcomes:write only if your CRM should send results back.
  2. Every 15 minutes, ask for what changed since your last run and upsert each row on its id.
  3. Store the time you asked, and use it as updated_since next time.
  4. 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_lost or no_decision. A loss needs reason_key, as it does in the app.
  • A result is added to the record and never edited. Test with a key that lacks outcomes:write until 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.
Available

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

  1. Make a key named for the person or team using Claude, with pursuits:read and outcomes:read. Add outcomes:write only if Claude should record results; Claude asks before it does.
  2. Add the server to the Claude you use, below.
  3. Ask: What's due in the next two weeks? or Why 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

ToolWhat it doesScope
check_connectionConfirms the key works and lists what it may do.None
list_pursuitsThe pipeline: name, buyer, stage, due date, value, bid call and fit.pursuits:read
get_pursuitOne pursuit by its id.pursuits:read
get_bid_decisionThe bid call with what it rested on: the reason, the recommendation, conditions and the evidence as it stood.pursuits:read
list_deadlinesWhat is due in the next N days, late ones first.pursuits:read
list_outcomesResults recorded on pursuits, with the reason for a loss.outcomes:read
record_outcomeRecords 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.
Coming soon

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

  1. In Paavya, open Library and press Add to Library.
  2. Upload files or a whole folder, pick files from Google Drive, or import a spreadsheet or a Loopio or Responsive export.
  3. 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

ScopeLets a keyEndpoints
pursuits:readRead pursuits, bid calls and deadlinesGET /v1/pursuits, /v1/pursuits/{id}, /v1/deadlines
outcomes:readRead recorded resultsGET /v1/outcomes
outcomes:writeRecord a resultPOST /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 Authorization header, 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.
Coming soon

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 limit and offset. 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." } }
TypeStatusWhat to do
unauthorized401The key is missing, wrong or revoked. Check the header, or make a new key.
forbidden403The key works but lacks the scope named in the message. Make a key with it.
not_found404No such endpoint, or the id is not one of your company's pursuits.
bad_request400The message names the parameter or field to fix. An unknown parameter is refused, so a typo never returns everything.
method_not_allowed405Use the method the message names.
rate_limited429The key reached its monthly calls. It resets on the 1st, or use another key.
server_error500Ours. 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.