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

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

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

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:

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)

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

Outbound webhooks

Receive a POST from KeystoneIQ when events happen in your workspace. Create and manage endpoints from Settings > Developer (owner only, Growth and Pro plans): set a destination URL, choose events, and copy the signing secret shown at creation. Each endpoint can be toggled off or deleted at any time, and a test delivery can be sent from the same screen.

Events

Delivery format

Each delivery is a POST with Content-Type: application/json and these headers:

Body shape:

{
  "event": "brief.completed",
  "workspace_id": "uuid",
  "timestamp": "2026-07-21T12:00:00.000Z",
  "data": { }
}

data carries the event-specific payload.

Verifying signatures

Compute an HMAC-SHA256 of the raw request body with your endpoint secret and compare it (constant-time) to the value after sha256=:

const crypto = require("crypto");

function verifyKeystoneSignature(rawBody, signatureHeader, secret) {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const received = (signatureHeader || "").replace(/^sha256=/, "");
  return (
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received, "hex"), Buffer.from(expected, "hex"))
  );
}

Reject any delivery whose signature does not verify.

Delivery behavior

• Requests time out after 10 seconds; respond with a 2xx quickly and process asynchronously.
• Each attempt is logged; recent deliveries (status, response) are visible in Settings > Developer.
• Deliveries are not automatically retried, so treat webhooks as notifications and reconcile against the REST endpoints above if you need guaranteed consistency.
• Destination URLs must be publicly reachable; requests to private or internal addresses are blocked.

Errors and HTTP status codes

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.