Build on Issuelane

Every request carries an API token in the Authorization header. A workspace admin creates an agent and its tokens in Settings, Agents. A token belongs to one workspace and holds scopes: workspace:read for every read, and tasks:write to create and change tasks and comments. The base URL is https://api-issuelane.cublya.com/v1.

curl https://api-issuelane.cublya.com/v1/workspaces/$WORKSPACE_ID/tasks?limit=50 \
  -H "Authorization: Bearer $ISSUELANE_TOKEN"

Changes made with a token are recorded under the agent’s name in every task’s history. A browser session is not accepted here; use a token.

Every list answers { "data": [...], "nextCursor": "..." }. To read the next page, send the same request with cursor set to nextCursor; it is null on the last page. Keep the filters and the order the same while paging: a cursor from a different list is refused. Pages hold up to 100 items, 50 unless you set limit.

To keep a copy in sync, list tasks with order=CREATED once, then poll with updated_since, or better, subscribe to webhooks.

Every error has the same shape. Switch on type, show message, and quote requestId if you report a problem. A 422 lists the refused fields in errors.

{
  "error": {
    "type": "validation_failed",
    "message": "title cannot be null",
    "requestId": "01J…",
    "errors": [{ "field": "title", "message": "title cannot be null" }]
  }
}

The types are unauthorized (401), forbidden (403), not_found (404), conflict (409), payload_too_large (413), validation_failed (422), rate_limited (429), internal_error (500) and unavailable (503).

Send an Idempotency-Key header holding a UUID you generate once per intended write. If the connection drops and you retry with the same key, you get the first result back and nothing is written twice. Reusing a key for a different request is a 409.

Each token may make 600 requests and 60 writes a minute. All the tokens of one workspace share 300 writes a minute. The windows are fixed and 60 seconds long. Over a limit the answer is 429 with a Retry-After header in seconds; wait that long, then retry.

A workspace admin adds endpoints in Settings, Webhooks, and picks the events each one is sent. Every delivery is a POST with a JSON body:

{
  "id": "msg_5f0c7a1e9b2d4c6e8a0b1c2d3e4f5a6b",
  "type": "task.updated",
  "timestamp": "2026-10-28T19:42:07.512301Z",
  "data": {
    "workspaceId": "4b0e1c7e-…",
    "seq": 1842,
    "entityId": "9d3f2a10-…",
    "actorId": "1c5e8b22-…",
    "object": { "id": "9d3f2a10-…", "identifier": "WEB-42", "title": "…", "stateId": "…" }
  }
}

data.object has the same fields as the matching API object. If a body would be larger than 256 KB, object is empty and data.truncated is true; read the resource through the API.

The events:

• task.created
• task.updated
• task.deleted
• comment.created
• comment.updated
• comment.deleted
• project.created
• project.updated
• label.created
• label.updated
• label.deleted
• state.created
• state.updated
• task_relation.created
• task_relation.deleted
• attachment.created
• attachment.deleted
• member.created
• member.deleted

webhook.test is sent when an admin presses Send test.

Verifying a delivery

Each delivery carries the Standard Webhooks headers webhook-id, webhook-timestamp and webhook-signature. The signature is v1, followed by a base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{body}, keyed with the bytes after the secret’s whsec_ prefix. Any Standard Webhooks library verifies it, or:

import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody is the request body exactly as received, before any JSON parsing.
export function verify(secret, headers, rawBody) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  // Refuse anything older or newer than five minutes: it may be a replay.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = createHmac("sha256", key)
    .update(`${id}.${timestamp}.${rawBody}`)
    .digest("base64");
  return headers["webhook-signature"].split(" ").some((entry) => {
    const [version, signature] = entry.split(",");
    return (
      version === "v1" &&
      signature.length === expected.length &&
      timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
    );
  });
}

For receivers that already check it, X-Hub-Signature-256 carries sha256= and a hex HMAC-SHA256 of the body alone, keyed with the whole secret as shown. It does not cover the timestamp, so check webhook-timestamp yourself.

Retries and ordering

Answer with any 2xx within 10 seconds. Anything else, redirects included, is a failure and is retried after 5 seconds, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours, 10 hours: 8 attempts over about a day. Delivery is at least once and not ordered, so use webhook-id to ignore a message you have already handled and data.seq to order changes to one workspace. An endpoint that fails 20 times in a row for more than 24 hours is turned off, and the settings page says why. The delivery log keeps 30 days of attempts, and any delivery can be sent again from it.

Where deliveries go

Endpoints must be public https URLs. Private, loopback, link-local and reserved addresses are refused when the endpoint is saved, and checked again on every delivery after the name is resolved, so a name that later points inward is refused too.

The machine-readable description is served at https://api-issuelane.cublya.com/v1/openapi.json (OpenAPI 3.1). Version 1 only grows: fields and endpoints are added, never removed or changed. A breaking change would be /v2, beside this one.