REST API reference

KeystoneIQ exposes a versioned REST API (/api/v1/*) for automation: Zapier, Make, custom scripts, and internal tools. Use it to read briefs, enqueue deal brief jobs, and add intelligence to your workspace.

Who can use it

Requirement	Details
Plan	Growth or Pro. API keys and `/api/v1/*` are not available on Free or Starter plans.
Keys	Create and revoke keys in the app: Developer in the left sidebar (workspace owners only).
Scope	Every request is scoped to the workspace tied to the API key. There is no cross-workspace access.

If the workspace is on Free or Starter, protected routes return 402 with upgrade_required: true.

Base URL

Use your production app host (replace with your deployment):

https://YOUR_APP_DOMAIN

Example full paths:

GET  https://YOUR_APP_DOMAIN/api/v1/briefs
POST https://YOUR_APP_DOMAIN/api/v1/intelligence

Production API base: https://keystoneiq.ai. For local development, use your local origin (e.g. http://localhost:3000).

Authentication

Send the API key on every request:

Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Best practices

Treat keys like passwords: store in a secret manager, never commit to git, never embed in client-side browser code.
Rotate if a key is exposed: revoke in Developer, create a new key, update Zapier/Make or your integration.
Only owners can create or revoke keys; team members use the product via normal login, not this Bearer API.

Capabilities overview

Capability	Method & path	Purpose
List briefs	`GET /api/v1/briefs`	Paginated list of brief metadata (id, type, timestamps). Optional filters.
Get brief	`GET /api/v1/briefs/{id}`	Full brief including `content` and `content_json`.
Trigger deal brief	`POST /api/v1/jobs/trigger-deal-brief`	Queue a deal brief job for a synced deal (by `deal_id` or HubSpot id).
Add intelligence	`POST /api/v1/intelligence`	Append structured intel (notes, recaps, evidence) linked to deals/competitors/products.

Session-only features (browser cookie auth), such as some brief feedback endpoints, are not part of this Bearer API; they are for the web app. See internal architecture docs if you need feedback/ROI APIs.

`GET /api/v1/briefs`

List briefs for the workspace, newest first.

Query parameters

Parameter	Description
`limit`	Optional. Default `10`, maximum `50`.
`type`	Optional. One of: `weekly`, `deep_research`, `deal_brief`.
`product_id`	Optional. UUID. Limits to a single product line.

Example response

{
  "briefs": [
    {
      "id": "uuid",
      "created_at": "2025-03-10T12:00:00.000Z",
      "updated_at": "2025-03-10T12:00:00.000Z",
      "type": "weekly"
    }
  ]
}

Rate limit: 60 requests per workspace per hour (v1_briefs_list).

`GET /api/v1/briefs/{id}`

Fetch one brief by UUID. Returns 404 if the brief does not exist or belongs to another workspace.

Response fields include: id, created_at, updated_at, type, content, content_json.

Rate limit: 100 requests per workspace per hour (v1_briefs_get).

`POST /api/v1/jobs/trigger-deal-brief`

Queues a deal brief generation job for an existing deal.

Body (JSON). Provide one of:

Field	Description
`deal_id`	KeystoneIQ deal UUID (from CRM sync or manual deals).
`hubspot_deal_id`	HubSpot deal ID string. The deal must already be synced into KeystoneIQ.

Example

{ "deal_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" }

{ "hubspot_deal_id": "123456789" }

Success response

{ "ok": true, "deal_id": "uuid" }

If a pending deal-brief job already exists for that deal, the API may return 200 with skipped: true and reason: "pending_deal_brief_exists" to avoid duplicate work.

Rate limit: 5 deal-brief triggers per workspace per hour (rolling window). On limit, response is 429 with Retry-After (e.g. 720 seconds).

`POST /api/v1/intelligence`

Adds an intelligence item (e.g. call notes, win/loss notes, competitor evidence) to the workspace.

Body (JSON)

Field	Required	Description
`content`	Yes	Text body (trimmed; large content is capped server-side).
`item_type`	No	`deal_note`, `win_note`, `loss_note`, `competitor_evidence`, `call_recap`, or `general` (default).
`deal_id`	No	UUID. Must be a deal in this workspace.
`competitor_id`	No	UUID. Must be a competitor in this workspace.
`product_id`	No	UUID. Must be a product in this workspace.

Example

{
  "content": "Discovery call: prospect evaluating us vs Acme on enterprise SSO.",
  "item_type": "deal_note",
  "deal_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Success response

{
  "item": {
    "id": "uuid",
    "item_type": "deal_note",
    "created_at": "2025-03-10T12:00:00.000Z"
  }
}

Rate limit: 30 requests per workspace per hour (intelligence).

Errors and HTTP status codes

Status	Meaning
200	Success.
400	Bad request. Invalid JSON, missing required fields, invalid UUIDs.
401	Missing/invalid API key or wrong `Authorization` format.
402	API access requires Growth or Pro plan. Upgrade from Settings > Billing.
404	Resource not found (e.g. brief, deal, competitor not in workspace).
429	Rate limit exceeded. Back off and honor `Retry-After` when present.
500	Server error. Retry with backoff; contact support if persistent.

Error bodies are JSON with an error string; rate limits may include retry_after (seconds).

Automation (Zapier & Make)

For step-by-step setup (triggers, actions, troubleshooting), see Zapier & Make setup. The same API key and endpoints power those integrations.

Audit

API usage is logged for security and compliance (successful and failed calls where applicable). Revoking a key immediately stops new requests using that key.