Developers

API

The API lives at https://breef.app/api/v1. Requests and answers are JSON. Each request acts for the account whose API key it carries, and only ever sees that account’s tasks.

Authentication

Create a key in Settings → Integrations → API keys. It starts with brf_ and is shown once, so keep it somewhere safe. Send it with every request:

Authorization: Bearer brf_…

Breef keeps only a fingerprint of each key, so a lost key can’t be shown again: revoke it in Settings and create another. A revoked key stops working straight away, and so does every key if the account leaves Foresight.

Tasks

A list answers {"data": [ …tasks ], "next_cursor": "…" }, with next_cursor null on the last page. Everything else answers {"data": task}.

curl https://breef.app/api/v1/tasks?status=suggested \
  -H "Authorization: Bearer brf_…"

curl -X POST https://breef.app/api/v1/tasks/k57f3…/accept \
  -H "Authorization: Bearer brf_…" \
  -d '{"due_date": "2026-10-20"}'

The task object

{
  "id": "k57f3x0c8w2m4n6q8r0t2v4y6a8c0e2g",
  "title": "Send the signed contract",
  "status": "open",
  "due_date": "2026-10-16",
  "reason": "Marco needs the signed contract before Friday.",
  "created_at": "2026-10-09T08:12:44.120Z",
  "email": {
    "from": { "name": "Marco Bianchi", "address": "marco@studio.it" },
    "subject": "Contract for the October project",
    "received_at": "2026-10-09T08:11:02.000Z"
  }
}

status is open, suggested, done or dismissed. due_date and reason may be null. email is the email the task came from: its sender, subject and date, never its text. It’s null once Breef has deleted the email, after 30 days.

Errors and limits

Errors answer {"error": {"code": "…", "message": "…"}} with the matching status: 401 unauthorized (no key, or not a valid one), 403 plan_required, 404 not_found (also for another account’s task), 409 invalid_transition (for example, accepting something that isn’t a suggestion), 400 invalid_request or invalid_date, and 429 rate_limited. Each key may make 120 requests a minute; past that, wait for the number of seconds in the Retry-After header.

Webhooks

Add a webhook in Settings → Integrations: an https:// address on the public internet, and the events it should receive. Breef sends a POST with a JSON body when:

• task.created: Breef made a task from an email, or a suggestion was accepted (in Breef, through the API, or by a confident reply in the same thread).
• task.suggested: Breef wasn’t sure an email needs you, and it’s waiting for your review.

{
  "id": "evt_V2hZc1RhbXBsZUV2ZW50SWQ",
  "type": "task.created",
  "created_at": "2026-10-09T08:12:44.512Z",
  "data": {
    "task": { "id": "k57f3…", "title": "Send the signed contract", "status": "open", … }
  }
}

data.task is the same task object the API returns. “Send test” in Settings sends a webhook.test event to check your endpoint.

Checking a delivery came from Breef

Deliveries are signed the Standard Webhooks way, so any of its libraries can check them, with the whsec_… secret shown when you added the webhook. Each request carries webhook-id, webhook-timestamp (Unix seconds) and webhook-signature (v1, and a base64 HMAC-SHA256 of id.timestamp.body). Check it against the raw body, before parsing it. In Node.js:

import crypto from "node:crypto";

// secret: the whsec_… shown when you added the webhook.
function fromBreef(secret, headers, body) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  // Refuse anything older than 5 minutes, so a captured request can't be replayed.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = crypto.createHmac("sha256", key).update(`${id}.${timestamp}.${body}`).digest("base64");
  return headers["webhook-signature"].split(" ").some((signature) =>
    signature.startsWith("v1,") &&
    signature.length === expected.length + 3 &&
    crypto.timingSafeEqual(Buffer.from(signature.slice(3)), Buffer.from(expected))
  );
}

Answers and retries

Answer with any 2xx status within 10 seconds. Anything else counts as a failure, and Breef tries again after 1 minute, 5 minutes, 30 minutes, 2 hours and 8 hours, with the same webhook-id, so a retry can be told apart from a new event. Redirects aren’t followed. After 20 failures in a row a webhook pauses, and Settings shows it, with a button to resume.

Your data

A webhook sends task details, including the sender and subject of the email behind each task, to the address you choose. Once there, they’re handled by whoever runs that address, under their terms. See the Privacy Policy.