REST API (Pro plan)

Pull live data out of Coffield.io into your own dashboards, business intelligence tools, or custom internal apps. The REST API is read-only — it never changes your agents, leads, or conversations — and it is scoped to your workspace so a token can never see another customer's data.

Available on the Pro plan and above. If your workspace is on Starter or Growth, the REST API card on the External integrations page will show an amber upgrade notice instead of a token form. Upgrade from Account → Subscriptions to enable it.

#What you can do with it

• Build a custom executive dashboard that shows new leads and conversation volume next to your other KPIs.
• Pipe lead data into Looker Studio, Power BI, Tableau, Metabase, or a Google Sheet via Apps Script.
• Feed conversation transcripts into your internal analytics warehouse.
• Sync agent activity into a Slack channel via a small script.

#What you cannot do with it

• Create, update, or delete records. The API is read-only by design.
• See data outside your own workspace.
• Bypass your subscription limits — every request counts toward a fair-use rate cap (default 600/minute per token).

#Step 1 — Create a token

1. Sign in to your workspace.
2. Open Settings → External integrations.
3. Scroll to the REST API card. You will see a green banner that says "REST API is included with your plan" and your Base URL (for example, https://coffield.io/api/v1).
4. Under Create a new token:
   • Token name — something memorable, e.g. "Looker Studio – Sales" or "Internal dashboard".
   • Expires in (days) — leave blank for a token that never expires, or pick a number (we recommend 90 days for security).
5. Click Create token.

A green box will appear at the top of the card with your new token — something like 12|abcd1234.... Copy it now. For security, this is the only time the full token will ever be shown. Save it in your password manager, secrets vault, or directly into the tool that will use it.

Click I have saved it — dismiss to hide the box.

You can have up to 5 active tokens per workspace. The counter at the top of the card shows how many you have in use.

#Step 2 — Use the token

Every request must include an Authorization header with your token, and an Accept: application/json header.

#Quick test from the command line

curl -H "Authorization: Bearer 12|abcd1234..." \
     -H "Accept: application/json" \
     https://coffield.io/api/v1/me

You should see something like:

{
  "tenant": {
    "id": 1,
    "uuid": "6106b3a0-1eab-4afd-90b9-c41f45e1f62e",
    "name": "Acme Inc workspace"
  },
  "token": {
    "name": "Looker Studio – Sales",
    "abilities": ["api:rest", "tenant:1"],
    "last_used_at": "2026-06-08T00:29:06+00:00"
  }
}

If you get a 401 Unauthorized, double-check the token was copied in full and the Bearer prefix is included. If you get 403 tier_not_entitled, your workspace has dropped off the Pro plan.

#Available endpoints

All endpoints return JSON and use standard pagination (?page=1 for paged lists; up to 100 per page via ?per_page=).

#Site crawl automation

The Pro REST API lets you keep your agent's knowledge fresh without logging into the dashboard.

# Trigger a crawl for agent #12, up to 100 pages (will be clamped to your tier cap)
curl -X POST \
     -H "Authorization: Bearer 12|abcd1234..." \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -d '{"agent_id": 12, "max_pages": 100}' \
     https://coffield.io/api/v1/crawls

You'll get back a 202 Accepted with the new crawl id, the requested page count, and the page count we actually queued (clamped to your tier limit). The crawl runs in the background — typically a minute or two for small sites.

Pair it with a webhook so you find out when the crawl is done:

1. Create a webhook endpoint in Settings → External integrations → Outbound webhooks that subscribes to crawl.completed and crawl.failed.
2. Your endpoint will receive a signed POST with the crawl summary as soon as the run finishes.
3. (Optional) Have your endpoint call GET /api/v1/crawls/{id}/diff?against={priorId} to see exactly which pages changed and decide whether to email your team.

Use cases:

• Nightly cron that re-crawls your site after content publishes, then posts the diff into Slack.
• After a marketing campaign launch, trigger a crawl and review only the changed pages in your dashboard.
• Track competitor site changes (with their permission and in compliance with their robots.txt).

#Triggering workflows

Workflows are reusable recipes (sequences of steps like "log a message → fire a webhook event → wait 2 seconds"). See the Workflows chapter for the full picture.

# Trigger workflow #5 with an optional input payload
curl -X POST \
     -H "Authorization: Bearer 12|abcd1234..." \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -d '{"input": {"campaign": "Spring Promo"}}' \
     https://coffield.io/api/v1/workflows/5/runs

You'll get back 202 Accepted with the new run id. Poll GET /api/v1/workflow-runs/{id} to watch it complete. The response includes step-by-step output so you can see exactly which steps succeeded.

Tier gating: Workflows are Growth+, but the REST API itself is Pro+ — so triggering via the API requires Pro or above. Pro is capped at 1,000 workflow runs per tenant per day.

Common patterns:

• Run a workflow from your CRM whenever a deal moves to a new stage.
• Run a workflow from a scheduled job (cron, GitHub Actions) at a specific time of day.
• Run a workflow from your support tool to broadcast a status update to every webhook downstream.

#Example: pull this week's new leads

curl -H "Authorization: Bearer 12|abcd1234..." \
     -H "Accept: application/json" \
     "https://coffield.io/api/v1/leads?status=new&per_page=100"

#Example: get a transcript

curl -H "Authorization: Bearer 12|abcd1234..." \
     -H "Accept: application/json" \
     https://coffield.io/api/v1/conversations/42/messages

#Connecting to a third-party tool

Most BI and dashboarding tools have a "REST API connector" or "JSON data source" option. The exact wording varies, but you will always need:

• URL — pick the endpoint from the list above.
• Authentication — choose Bearer token and paste in your full token.
• Headers — add Accept: application/json if asked.

Specific tools we've helped customers connect:

• Google Sheets — use Apps Script's UrlFetchApp.fetch() with headers: { Authorization: 'Bearer ...' }.
• Looker Studio / Power BI — use the "Web connector" or "Web data source".
• Zapier / Make.com — use the "Webhooks" app's GET action; set the auth header manually.
• n8n — use the HTTP Request node, set Authentication = "Header Auth", header name = Authorization, value = Bearer 12|abcd1234....

#Rate limit

Each token is limited to 600 requests per minute by default. If you hit the limit you will see a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait. This is plenty for any human-facing dashboard; if you are hammering the API in a tight loop, please add a short delay between calls.

#Security best practices

• Never paste your token into a public spreadsheet, Slack channel, GitHub repo, or any other place strangers can read.
• Use a separate token per integration (Looker, Sheets, Zapier each get their own). That way, if one leaks, you only have to revoke that one.
• Pick an expiration. Tokens that never expire are convenient, but they also never go away — even if the laptop they live on is lost.
• Revoke a token the moment you stop needing it.

#Revoking a token

1. Go to Settings → External integrations → REST API.
2. In the tokens table, click Revoke next to the token you want to kill.
3. Confirm. The token stops working immediately — any tool using it will start getting 401 Unauthorized on its next request.

You can always create a new one.

#Troubleshooting

Still stuck? Email support@coffield.io with the time of the failing request and the endpoint URL — we can look it up in the audit log.