Strategic Tickets

REST endpoints for Strategic Tickets. Base URL https://api.competlab.com; every request needs a CL-API-Key header (see Authentication). Responses wrap in { item } or { items }; errors in { error }.

List the project’s ticket labels

GET/v1/projects/{projectId}/tickets/labels

List the project’s label list — the only labels a ticket may carry, in the order the project picks them. A label is a name and a colour; a ticket names labels by ID. The list is empty until the project defines a label, in the app or through POST /v1/projects/{projectId}/tickets/labels.

Returns · { items }

Path parameters

Name	Type	Description
`projectId`	`string`	Project ID

Request


curl "https://api.competlab.com/v1/projects/507f1f77bcf86cd799439011/tickets/labels" \
  -H "CL-API-Key: YOUR_COMPETLAB_API_KEY"

Response 200 OK

Example


{
  "items": [
    {
      "id": "3f2a9c6e-1b77-4c1e-9a54-5c7b2f0a91d2",
      "name": "Pricing page",
      "color": "#3b82f6"
    }
  ]
}

Errors

Status	Code	Meaning
401	`api_key_missing` · `api_key_invalid` · `api_key_revoked` · `api_key_expired` · `insufficient_scope`	The `CL-API-Key` is missing, malformed, revoked, expired, or lacks the required scope.
429	`rate_limit_exceeded`	Rate limit exceeded — retry with backoff.

Every error uses the shared { error: { code, message, status } } envelope; code is one of the values listed above.


{
  "error": {
    "code": "api_key_invalid",
    "message": "Invalid API key",
    "status": 401
  }
}

Transient failures (429, 5xx) are safe to retry with exponential backoff.

Create a ticket label

POST/v1/projects/{projectId}/tickets/labels

Add a label to the project’s list. Names are unique within the project and compared without regard to case, so Pricing and pricing cannot both exist. Answers with the whole list. Requires a read_write key.

Returns · { items }

Path parameters

Name	Type	Description
`projectId`	`string`	Project ID

Request body — application/json

Field	Type	Description
`name`	`string`	The label’s name. Unique within the project, compared without regard to case, at most 40 characters. A project holds at most 50 labels.
`color`	`string`	The label’s colour, as hex — `#rrggbb`. It is stored lower-case, which is the form every tracker a ticket may be copied into speaks.

Request


curl -X POST "https://api.competlab.com/v1/projects/507f1f77bcf86cd799439011/tickets/labels" \
  -H "CL-API-Key: YOUR_COMPETLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Pricing page","color":"#3b82f6"}'

Response 200 OK

Example


{
  "items": [
    {
      "id": "3f2a9c6e-1b77-4c1e-9a54-5c7b2f0a91d2",
      "name": "Pricing page",
      "color": "#3b82f6"
    }
  ]
}

Errors

Status	Code	Meaning
400	`invalid_parameters` · `invalid_run_id` · `invalid_check_id` · `bad_request` · `paging_requires_compact_view` · `paging_requires_summary` · `nothing_to_return`	Bad request — the payload failed validation.
401	`api_key_missing` · `api_key_invalid` · `api_key_revoked` · `api_key_expired` · `insufficient_scope`	The `CL-API-Key` is missing, malformed, revoked, expired, or lacks the required scope.
403	`insufficient_scope` · `forbidden`	The key is not permitted to access this resource.
429	`rate_limit_exceeded`	Rate limit exceeded — retry with backoff.

Every error uses the shared { error: { code, message, status } } envelope; code is one of the values listed above.


{
  "error": {
    "code": "invalid_parameters",
    "message": "Domain is required",
    "status": 400
  }
}

Transient failures (429, 5xx) are safe to retry with exponential backoff.

Rename or recolour a ticket label

PATCH/v1/projects/{projectId}/tickets/labels/{labelId}

Rename a label, recolour it, or both. It is one write on the list and touches no ticket, because a ticket holds the label’s ID. Answers with the whole list. Requires a read_write key.

Returns · { items }

Path parameters

Name	Type	Description
`labelId`	`string`	Label ID, as the label list returns it
`projectId`	`string`	Project ID

Request body — application/json

Field	Type	Description
`name`	`string`	The label’s name. Unique within the project, compared without regard to case, at most 40 characters. A project holds at most 50 labels.
`color`	`string`	The label’s colour, as hex — `#rrggbb`. It is stored lower-case, which is the form every tracker a ticket may be copied into speaks.

Request


curl -X PATCH "https://api.competlab.com/v1/projects/507f1f77bcf86cd799439011/tickets/labels/3f2a9c6e-1b77-4c1e-9a54-5c7b2f0a91d2" \
  -H "CL-API-Key: YOUR_COMPETLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Pricing page","color":"#3b82f6"}'

Response 200 OK

Example


{
  "items": [
    {
      "id": "3f2a9c6e-1b77-4c1e-9a54-5c7b2f0a91d2",
      "name": "Pricing page",
      "color": "#3b82f6"
    }
  ]
}

Errors

Status	Code	Meaning
400	`invalid_parameters` · `invalid_run_id` · `invalid_check_id` · `bad_request` · `paging_requires_compact_view` · `paging_requires_summary` · `nothing_to_return`	Bad request — the payload failed validation.
401	`api_key_missing` · `api_key_invalid` · `api_key_revoked` · `api_key_expired` · `insufficient_scope`	The `CL-API-Key` is missing, malformed, revoked, expired, or lacks the required scope.
403	`insufficient_scope` · `forbidden`	The key is not permitted to access this resource.
404	`not_found`	No `label` matches the id in the path.
429	`rate_limit_exceeded`	Rate limit exceeded — retry with backoff.

Every error uses the shared { error: { code, message, status } } envelope; code is one of the values listed above.


{
  "error": {
    "code": "invalid_parameters",
    "message": "Domain is required",
    "status": 400
  }
}

Transient failures (429, 5xx) are safe to retry with exponential backoff.

Delete a ticket label

DELETE/v1/projects/{projectId}/tickets/labels/{labelId}

Remove a label from the project’s list and from every ticket carrying it. Answers with the whole list. Requires a read_write key.

Returns · { items }

Path parameters

Name	Type	Description
`labelId`	`string`	Label ID, as the label list returns it
`projectId`	`string`	Project ID

Request


curl -X DELETE "https://api.competlab.com/v1/projects/507f1f77bcf86cd799439011/tickets/labels/3f2a9c6e-1b77-4c1e-9a54-5c7b2f0a91d2" \
  -H "CL-API-Key: YOUR_COMPETLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response 200 OK

Example


{
  "items": [
    {
      "id": "3f2a9c6e-1b77-4c1e-9a54-5c7b2f0a91d2",
      "name": "Pricing page",
      "color": "#3b82f6"
    }
  ]
}

Errors

Status	Code	Meaning
401	`api_key_missing` · `api_key_invalid` · `api_key_revoked` · `api_key_expired` · `insufficient_scope`	The `CL-API-Key` is missing, malformed, revoked, expired, or lacks the required scope.
403	`insufficient_scope` · `forbidden`	The key is not permitted to access this resource.
404	`not_found`	No `label` matches the id in the path.
429	`rate_limit_exceeded`	Rate limit exceeded — retry with backoff.

Every error uses the shared { error: { code, message, status } } envelope; code is one of the values listed above.


{
  "error": {
    "code": "api_key_invalid",
    "message": "Invalid API key",
    "status": 401
  }
}

Transient failures (429, 5xx) are safe to retry with exponential backoff.

List the people a ticket can be assigned to

GET/v1/projects/{projectId}/tickets/assignees

List the people a ticket in this project can be assigned to — everyone who is currently a member of the organization, each as the same userId and fullName a ticket already carries for its author and its assignee. This is where assigneeUserId comes from: a create or an update that names anyone else is refused. Somebody invited but not yet joined is not here, because a ticket cannot be assigned to them. Nothing about a person beyond their name and id is returned, on this endpoint or any other.

Returns · { items }

Path parameters

Name	Type	Description
`projectId`	`string`	Project ID

Request


curl "https://api.competlab.com/v1/projects/507f1f77bcf86cd799439011/tickets/assignees" \
  -H "CL-API-Key: YOUR_COMPETLAB_API_KEY"

Response 200 OK

Example


{
  "items": [
    {
      "userId": "507f1f77bcf86cd799439011",
      "fullName": "Dana Ellis"
    }
  ]
}

Errors

Status	Code	Meaning
401	`api_key_missing` · `api_key_invalid` · `api_key_revoked` · `api_key_expired` · `insufficient_scope`	The `CL-API-Key` is missing, malformed, revoked, expired, or lacks the required scope.
429	`rate_limit_exceeded`	Rate limit exceeded — retry with backoff.

Every error uses the shared { error: { code, message, status } } envelope; code is one of the values listed above.


{
  "error": {
    "code": "api_key_invalid",
    "message": "Invalid API key",
    "status": 401
  }
}

Transient failures (429, 5xx) are safe to retry with exponential backoff.

List project tickets

GET/v1/projects/{projectId}/tickets

List the project’s Strategic Tickets, a page at a time — what the team is deciding on and working on, whether a person opened a ticket, your own automation did, or a Strategic Briefing did. By default the list is the board flattened: the columns in board order, and inside each column the order the team keeps — in triage that starts as the order an edition delivered its recommendations, most important first, newest edition on top, until somebody moves them. A ticket carries no order number of its own on this API; its place is where it sits in the list. Each row is a summary: every field except the Markdown description, which include=description adds. pagination.total counts every ticket matching every filter across all pages; pagination.hasMore says a next page exists — ask for page+1. byStatus counts the matches per column whatever status you passed, narrowed by every other filter, so limit=1 with no other filter is the board’s census. One call answers each of these. What to start: status=triage,todo&sort=priority. Quick wins among a briefing’s recommendations: add impactMin=3&maxMinutes=120 — that leaves out every ticket without an edition’s estimate; for those, impactMin=3&effort=low. Overdue: status=triage,todo,in_progress&dueBefore={today}&sort=due. Due this week: status=triage,todo,in_progress&dueFrom={today}&dueBefore={the day after the week ends}. Changed since yesterday: activeSince={the start of the customer's yesterday, as ISO 8601 with its offset — a bare day is midnight UTC}&sort=activity; on a changed ticket, a statusChangedAt later than that means it changed column, and a lastActivityAt later than its updatedAt means a thread entry was written or edited after the ticket’s own last change. Due dates are calendar days with no time zone, so pass the customer’s own today. origin=briefing&briefingRunId={runId} is one edition’s tickets, with {runId} taken from GET /v1/projects/{projectId}/strategic-briefing/history; they are returned whole whatever closed says, so the list matches the count the briefing states. To read neighbours for a move, use sort=board (the default) and the destination column alone: any other read can hide tickets that sit between two rows.

Returns · { items, pagination, byStatus }

Path parameters

Name	Type	Description
`projectId`	`string`	Project ID

Query parameters

Name	Type	Description
`page`	`number`	Page number (1-indexed). Default `1`. Min `1`.
`limit`	`number`	How many tickets per page, 1 to 100; 50 when omitted. Pass `limit=1` when you only need `pagination.total` and `byStatus`. Default `50`. Range `1`–`100`.
`status`	`array<string>`	Return only the tickets in these columns — one, or several separated by commas (`status=todo,in_progress`). Omit it for every column. `byStatus` ignores this filter, so its counts still cover every column, narrowed by every other filter you passed.
`sort`	`string`	The order of the list. `board` (the default) is the board flattened: the columns in board order, each in the order the team keeps — and the only order to read neighbours for a move from. `priority` puts the highest impact first; among the same impact, the least effort first, and among the same effort the fewest minutes of the edition’s estimate; then the earliest due date, then board order. A missing value sorts last at each step. `due` puts the earliest due date first, undated last. `activity` puts the most recently touched first (`lastActivityAt`). Any order but `board` mixes the columns; each ticket carries its `status`. Values: `board`, `priority`, `due`, `activity`. Default `board`.
`closed`	`string`	How much of `done` and `dismissed` to return. `all` (the default) returns them whole; `recent` returns only the tickets that reached those columns within the last 30 days. The other columns are always whole, whichever you pass, and a read narrowed to one edition is whole whatever you pass. Values: `recent`, `all`. Default `all`.
`origin`	`string`	Who opened the ticket, never which dimension it is about (that is `dimension`): `user` — a person in the app; `api` — an API key, which is what everything you write here carries; `briefing` — a Strategic Briefing; `ai_sources` — reserved for a future AI Sources writer, which opens none today, so that value matches none. Values: `user`, `api`, `briefing`, `ai_sources`.
`dimension`	`string`	Return only the tickets a Strategic Briefing opened for one part of its analysis, or `none` for the tickets no part claims — everything a person or an API key opened, and a briefing’s ticket whose edition named none. `agent-readiness` is the key for Agent Adoption — how well a site is set up for AI agents to discover, access and read it. The key predates the name and does not change. One of 15 values (e.g. `ai-visibility`, `ai-sources`, `positioning`, …).
`briefingRunId`	`string`	Return only the tickets one Strategic Briefing edition opened. Take the id from `GET /v1/projects/{projectId}/strategic-briefing/history`, or from `meta.runId` on a briefing read. Nothing a person or an API key opens carries an edition, so this narrows the list to that edition’s tickets whether or not you also pass `origin`. An edition’s tickets are returned whole, the finished and dismissed ones included however long ago they were closed — `closed` has no effect on this read — so the list matches the count the briefing states for that edition.
`assignee`	`string`	Return only the tickets one person owns — their user ID, from `GET /v1/projects/{projectId}/tickets/assignees`. Pass `none` for the tickets nobody owns. A ticket whose owner has left the organization reads as unassigned everywhere, but is still found here by their ID.
`labelId`	`string`	Return only the tickets carrying one label — its ID, from `GET /v1/projects/{projectId}/tickets/labels`. A project’s list is empty until the project defines a label, in the app or through `POST /v1/projects/{projectId}/tickets/labels`.
`number`	`number`	Return the one ticket carrying this number on the board — what a person means by `#14`. It is a name and not an address: this narrows the list, and every endpoint that acts on a ticket still takes its `id`. Min `1`.
`q`	`string`	Return only the tickets whose title or description contains this text, compared without regard to case. It is matched literally — punctuation is text, not a pattern — and threads are not searched. A match in a description is weaker evidence than one in the title: a briefing’s description quotes its grounding, so read the ticket before calling two tickets the same work.
`impactMin`	`number`	Return only the tickets whose impact is at least this, 1 to 4 (1 Minor · 2 Moderate · 3 Significant · 4 Critical; 4 matters most). Tickets nobody sized are left out. A Strategic Briefing sets impact and effort on the tickets it opens, so a value there is the edition’s estimate until a person changes it. Range `1`–`4`.
`effort`	`array<string>`	Return only the tickets sized as one of these — one, or several separated by commas (`effort=low,medium`). Tickets nobody sized are left out. This is the ticket’s size word, not its minutes: a briefing’s `briefing.estimatedMinutes` is the edition’s own time estimate, neither is derived from the other, and a `low` ticket can be an afternoon — when a person asks for something quick, use `maxMinutes`.
`maxMinutes`	`number`	Return only the tickets a Strategic Briefing opened whose edition estimated at most this many minutes of work. A ticket without an edition’s estimate — everything a person or an API key opened, and a briefing’s ticket the edition did not size — is left out; use `effort` for those. Min `1`.
`dueFrom`	`string`	Return only the tickets due on or after this calendar day, `YYYY-MM-DD`. Tickets with no due date are left out. A due date has no time zone, so pass the customer’s own day.
`dueBefore`	`string`	Return only the tickets due strictly before this calendar day, `YYYY-MM-DD`. `dueBefore=<today>` with the open columns (`status=triage,todo,in_progress`) is everything overdue; with `dueFrom` it is a range. Tickets with no due date are left out. A due date has no time zone, so pass the customer’s own day.
`activeSince`	`string`	Return only the tickets something happened to at or after this moment — an edit, a move, or a new thread entry (`lastActivityAt`). ISO 8601 with its offset; a time without one is read as UTC, and `YYYY-MM-DD` is the start of that day in UTC. A deleted ticket is gone and does not appear.
`include`	`array<string>`	What each ticket in the list carries. By default a list is an INDEX: every field except the ticket’s own Markdown `description`, which is then not on the row at all. Pass `include=description` for the bodies — one ticket’s description runs to thousands of characters, so a page fetched with them is large enough to be worth asking for on purpose. `GET …/tickets/{ticketId}` always returns the description whatever you pass here.

Request


curl "https://api.competlab.com/v1/projects/507f1f77bcf86cd799439011/tickets?page=1&limit=50&status=todo&sort=priority&closed=all&origin=briefing&dimension=pricing&briefingRunId=6a3950c06bda450a1372048e&assignee=507f1f77bcf86cd799439031&labelId=3f2a9c6e-1b77-4c1e-9a54-5c7b2f0a91d2&number=14&q=pricing%20page&impactMin=3&effort=low&maxMinutes=120&dueFrom=2026-10-01&dueBefore=2026-10-08&activeSince=2026-09-21&include=description" \
  -H "CL-API-Key: YOUR_COMPETLAB_API_KEY"

Response 200 OK

Example


{
  "items": [
    {
      "id": "507f1f77bcf86cd799439011",
      "number": 14,
      "origin": "api",
      "author": {
        "userId": "507f1f77bcf86cd799439011",
        "fullName": "Dana Ellis"
      },
      "briefing": {
        "runId": "6a3950c06bda450a1372048e",
        "dimension": "pricing",
        "estimatedMinutes": 90,
        "extendsTicketId": "507f1f77bcf86cd799439012"
      },
      "title": "Get onto the 2026 buyer guide",
      "labels": [
        {
          "id": "3f2a9c6e-1b77-4c1e-9a54-5c7b2f0a91d2",
          "name": "Pricing page",
          "color": "#3b82f6"
        }
      ],
      "status": "todo",
      "statusChangedAt": "2026-09-15T10:00:00.000Z",
      "assignee": {
        "userId": "507f1f77bcf86cd799439011",
        "fullName": "Dana Ellis"
      },
      "dueDate": "2026-10-01",
      "effort": "medium",
      "impact": 3,
      "commentCount": 2,
      "deletable": true,
      "createdAt": "2026-09-15T10:00:00.000Z",
      "updatedAt": "2026-09-16T08:30:00.000Z",
      "lastActivityAt": "2026-09-17T11:02:00.000Z",
      "description": "The guide names three of our competitors and not us."
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 47,
    "totalPages": 3,
    "hasMore": true
  },
  "byStatus": {
    "triage": 0,
    "todo": 1,
    "in_progress": 2,
    "done": 3,
    "dismissed": 4
  }
}

Fields

items[] — each entry

Field	Type	Description
`id`	`string`	The ticket’s ID.
`number`	`number \| null`	The ticket’s number on its project’s board — what a person says when they mean this ticket, shown in the app as `#14`. The first ticket a project opens is 1 and each one after it takes the next number, whatever opened it. A number never changes and is never given to a second ticket, so expect gaps: a number no ticket carries belonged to one that was deleted, or to a create that did not finish. `null` on a ticket opened before the board had numbers. Every endpoint takes the ticket’s `id`; none looks a ticket up by its number. Nullable.
`origin`	`string`	What wrote this: `user` — a person working in the app; `api` — an API key, which is what everything you write through this API carries; `briefing` or `ai_sources` — CompetLab itself. The server sets it; a request that sends it is refused. Values: `user`, `api`, `briefing`, `ai_sources`.
`author`	`object \| null`	The person who opened the ticket. `null` where no person did — `origin` says what did. Nullable. See `items[].author`.
`briefing`	`object \| null`	The Strategic Briefing edition this ticket came from, and what that edition proposed. Present where `origin` is `briefing`, `null` on every other ticket. It records what the edition said and does not move when the ticket is edited — the title, the description and the planning fields are the team’s to rewrite; this is not. Nullable. See `items[].briefing`.
`title`	`string`	The ticket’s title.
`labels`	`array<object>`	The ticket’s labels, each resolved to its name and colour, in the project’s own picker order. A ticket carries only labels the project’s list holds. See `items[].labels[]`.
`status`	`string`	The column the ticket sits in. `triage` — nobody has decided yet. `todo` — decided, not started. `in_progress` — being worked on. `done` — finished. `dismissed` — the team decided not to do it. The set is fixed and a project cannot add to it. Change it with the move endpoint, never with an update. Values: `triage`, `todo`, `in_progress`, `done`, `dismissed`.
`statusChangedAt`	`string`	When the ticket last changed column — its creation time until it first moves. Reordering a ticket inside its column does not touch it. ISO-8601.
`assignee`	`object \| null`	The person the ticket is assigned to, or `null` where nobody is. Somebody who has left the organization reads as unassigned here, and nothing is written back. Nullable. See `items[].assignee`.
`dueDate`	`string \| null`	The day the ticket is due, as `YYYY-MM-DD` — a calendar day, with no clock and no time zone, so it is the same day for every reader. `null` where none is set. Nullable.
`effort`	`string \| null`	How much work the ticket is. `null` where nobody has said. Values: `low`, `medium`, `high`. Nullable.
`impact`	`number \| null`	How much the ticket matters, from 1 to 4 (1 Minor · 2 Moderate · 3 Significant · 4 Critical; 4 matters most). `null` where nobody has said. Nullable.
`commentCount`	`number`	How many entries the ticket’s thread holds. Counted when the ticket is read.
`deletable`	`boolean`	Whether this ticket can be deleted. A ticket a Strategic Briefing opened is moved to `dismissed` instead, so that what opened it does not open it again — deleting one is refused. Read this rather than working it out from `origin`.
`createdAt`	`string`	When the ticket was opened. ISO-8601.
`updatedAt`	`string`	When the ticket last changed in any way. ISO-8601.
`lastActivityAt`	`string`	The last time anything happened to this ticket — an edit, a move, or an entry added to its thread. ISO-8601, and never earlier than `updatedAt`. Adding a comment does not change the ticket itself, so `updatedAt` can stand still while a thread fills up: read this field to ask whether a ticket has moved since you last looked, and `updatedAt` to ask whether the ticket itself was rewritten.
`description`	`string`	The ticket’s description, written in Markdown — present only when the list was asked for bodies with `include=description`, and then an empty string where nothing was written. Absent otherwise: a row without it says nothing about whether one exists. `GET …/tickets/{ticketId}` always carries it.

pagination — object

Field	Type	Description
`page`	`number`	Current page number (1-indexed)
`limit`	`number`	Number of items per page
`total`	`number`	Total number of items across all pages
`totalPages`	`number`	Total number of pages
`hasMore`	`boolean`	Whether more pages exist after the current page

byStatus — object

Field	Type	Description
`triage`	`number`
`todo`	`number`
`in_progress`	`number`
`done`	`number`
`dismissed`	`number`

items[].author — object

Field	Type	Description
`userId`	`string`	The person’s user ID.
`fullName`	`string`	The person’s name, as it stands on their CompetLab account.

items[].briefing — object

Field	Type	Description
`runId`	`string`	The edition that opened this ticket. It is the same `runId` that `GET /v1/projects/{projectId}/strategic-briefing/history` lists, so `GET /v1/projects/{projectId}/strategic-briefing/history/{runId}` reads that edition in full.
`dimension`	`string \| null`	The part of the analysis the recommendation came from. It is the edition’s own reading and stays as the edition wrote it, whatever labels the team later puts on the ticket. `null` where the edition named none. `agent-readiness` is the key for Agent Adoption — how well a site is set up for AI agents to discover, access and read it. The key predates the name and does not change. One of 14 values (e.g. `ai-visibility`, `ai-sources`, `positioning`, …). Nullable.
`estimatedMinutes`	`number \| null`	How long the edition estimated the work would take, in minutes. `null` where it gave no estimate — read that as unsized, not as quick. Nullable.
`extendsTicketId`	`string \| null`	The id of the ticket already on the board that this one builds on with a different piece of work; `GET /v1/projects/{projectId}/tickets/{ticketId}` reads it. Set once by the edition that opened this ticket, and said in words in the description. `null` where it builds on none. Nullable.

items[].labels[] — each entry

Field	Type	Description
`id`	`string`	The label’s ID. This is what a ticket’s `labelIds` names when you create or update one.
`name`	`string`	The label’s name. Unique within the project, compared without regard to case.
`color`	`string`	The label’s colour, as lower-case hex — `#rrggbb`. This is the form every tracker a ticket may be copied into speaks.

items[].assignee — object

Field	Type	Description
`userId`	`string`	The person’s user ID.
`fullName`	`string`	The person’s name, as it stands on their CompetLab account.

Paginated — pass page and limit query parameters and follow pagination.hasMore to page through the full set.

Errors

Status	Code	Meaning
400	`invalid_parameters` · `invalid_run_id` · `invalid_check_id` · `bad_request` · `paging_requires_compact_view` · `paging_requires_summary` · `nothing_to_return`	Bad request — the payload failed validation.
401	`api_key_missing` · `api_key_invalid` · `api_key_revoked` · `api_key_expired` · `insufficient_scope`	The `CL-API-Key` is missing, malformed, revoked, expired, or lacks the required scope.
429	`rate_limit_exceeded`	Rate limit exceeded — retry with backoff.

Every error uses the shared { error: { code, message, status } } envelope; code is one of the values listed above.


{
  "error": {
    "code": "invalid_parameters",
    "message": "Domain is required",
    "status": 400
  }
}

Transient failures (429, 5xx) are safe to retry with exponential backoff.

Create a ticket

POST/v1/projects/{projectId}/tickets

Open a ticket on the project’s board. title and status are required — status names the column it lands in and has no default, because where a ticket belongs depends on who opened it. A new ticket lands at the top of its column. Labels are named by ID from the project’s label list, so create the label there first. A board holds at most 5,000 tickets; past that a create is refused with 400 until some are deleted. The ticket is recorded as opened by an API key — origin is api and author is null — which is how the board tells your automation’s tickets from a person’s. Requires a read_write key.

Returns · { item }

Path parameters

Name	Type	Description
`projectId`	`string`	Project ID

Request body — application/json

Field	Type	Description
`title`	`string`	The ticket’s title.
`description`	`string`	The ticket’s description, in Markdown. At most 20000 characters.
`status`	`string`	The column the ticket opens in. Required and with no default: where a ticket belongs depends on who opened it, so a request that does not say is refused rather than landed somewhere plausible. Values: `triage`, `todo`, `in_progress`, `done`, `dismissed`.
`labelIds`	`array<string>`	IDs from the project’s own label list — read it with the labels endpoint, and create a label there before naming it. At most 10 per ticket, each named once.
`assigneeUserId`	`string`	The user ID of a current member of your organization — list them with `GET /v1/projects/{projectId}/tickets/assignees`. A user ID from anywhere else is refused.
`dueDate`	`string`	The day the ticket is due, as `YYYY-MM-DD` — a calendar day, with no clock and no time zone.
`effort`	`string`	How much work the ticket is. Values: `low`, `medium`, `high`.
`impact`	`number`	How much the ticket matters, from 1 to 4 (1 Minor · 2 Moderate · 3 Significant · 4 Critical; 4 matters most).

Request


curl -X POST "https://api.competlab.com/v1/projects/507f1f77bcf86cd799439011/tickets" \
  -H "CL-API-Key: YOUR_COMPETLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Get onto the 2026 buyer guide","description":"The guide names three of our competitors and not us.","status":"triage","labelIds":["3f2a9c6e-1b77-4c1e-9a54-5c7b2f0a91d2"],"assigneeUserId":"507f1f77bcf86cd799439031","dueDate":"2026-10-01","effort":"medium","impact":3}'

Response 200 OK

Example


{
  "item": {
    "id": "507f1f77bcf86cd799439011",
    "number": 14,
    "origin": "api",
    "author": {
      "userId": "507f1f77bcf86cd799439011",
      "fullName": "Dana Ellis"
    },
    "briefing": {
      "runId": "6a3950c06bda450a1372048e",
      "dimension": "pricing",
      "estimatedMinutes": 90,
      "extendsTicketId": "507f1f77bcf86cd799439012"
    },
    "title": "Get onto the 2026 buyer guide",
    "description": "The guide names three of our competitors and not us.",
    "labels": [
      {
        "id": "3f2a9c6e-1b77-4c1e-9a54-5c7b2f0a91d2",
        "name": "Pricing page",
        "color": "#3b82f6"
      }
    ],
    "status": "todo",
    "statusChangedAt": "2026-09-15T10:00:00.000Z",
    "assignee": {
      "userId": "507f1f77bcf86cd799439011",
      "fullName": "Dana Ellis"
    },
    "dueDate": "2026-10-01",
    "effort": "medium",
    "impact": 3,
    "commentCount": 2,
    "deletable": true,
    "createdAt": "2026-09-15T10:00:00.000Z",
    "updatedAt": "2026-09-16T08:30:00.000Z",
    "lastActivityAt": "2026-09-17T11:02:00.000Z"
  }
}

Fields

item — object

Field	Type	Description
`id`	`string`	The ticket’s ID.
`number`	`number \| null`	The ticket’s number on its project’s board — what a person says when they mean this ticket, shown in the app as `#14`. The first ticket a project opens is 1 and each one after it takes the next number, whatever opened it. A number never changes and is never given to a second ticket, so expect gaps: a number no ticket carries belonged to one that was deleted, or to a create that did not finish. `null` on a ticket opened before the board had numbers. Every endpoint takes the ticket’s `id`; none looks a ticket up by its number. Nullable.
`origin`	`string`	What wrote this: `user` — a person working in the app; `api` — an API key, which is what everything you write through this API carries; `briefing` or `ai_sources` — CompetLab itself. The server sets it; a request that sends it is refused. Values: `user`, `api`, `briefing`, `ai_sources`.
`author`	`object \| null`	The person who opened the ticket. `null` where no person did — `origin` says what did. Nullable. See `item.author`.
`briefing`	`object \| null`	The Strategic Briefing edition this ticket came from, and what that edition proposed. Present where `origin` is `briefing`, `null` on every other ticket. It records what the edition said and does not move when the ticket is edited — the title, the description and the planning fields are the team’s to rewrite; this is not. Nullable. See `item.briefing`.
`title`	`string`	The ticket’s title.
`description`	`string`	The ticket’s description, written in Markdown. An empty string where nothing was written. A row of the ticket LIST does not carry it unless the list was asked for bodies (`include=description`) — the key is then absent, never an empty string. Every other answer that returns a ticket — a single read, a create, an update, a move — and every webhook delivery carries it.
`labels`	`array<object>`	The ticket’s labels, each resolved to its name and colour, in the project’s own picker order. A ticket carries only labels the project’s list holds. See `item.labels[]`.
`status`	`string`	The column the ticket sits in. `triage` — nobody has decided yet. `todo` — decided, not started. `in_progress` — being worked on. `done` — finished. `dismissed` — the team decided not to do it. The set is fixed and a project cannot add to it. Change it with the move endpoint, never with an update. Values: `triage`, `todo`, `in_progress`, `done`, `dismissed`.
`statusChangedAt`	`string`	When the ticket last changed column — its creation time until it first moves. Reordering a ticket inside its column does not touch it. ISO-8601.
`assignee`	`object \| null`	The person the ticket is assigned to, or `null` where nobody is. Somebody who has left the organization reads as unassigned here, and nothing is written back. Nullable. See `item.assignee`.
`dueDate`	`string \| null`	The day the ticket is due, as `YYYY-MM-DD` — a calendar day, with no clock and no time zone, so it is the same day for every reader. `null` where none is set. Nullable.
`effort`	`string \| null`	How much work the ticket is. `null` where nobody has said. Values: `low`, `medium`, `high`. Nullable.
`impact`	`number \| null`	How much the ticket matters, from 1 to 4 (1 Minor · 2 Moderate · 3 Significant · 4 Critical; 4 matters most). `null` where nobody has said. Nullable.
`commentCount`	`number`	How many entries the ticket’s thread holds. Counted when the ticket is read.
`deletable`	`boolean`	Whether this ticket can be deleted. A ticket a Strategic Briefing opened is moved to `dismissed` instead, so that what opened it does not open it again — deleting one is refused. Read this rather than working it out from `origin`.
`createdAt`	`string`	When the ticket was opened. ISO-8601.
`updatedAt`	`string`	When the ticket last changed in any way. ISO-8601.
`lastActivityAt`	`string`	The last time anything happened to this ticket — an edit, a move, or an entry added to its thread. ISO-8601, and never earlier than `updatedAt`. Adding a comment does not change the ticket itself, so `updatedAt` can stand still while a thread fills up: read this field to ask whether a ticket has moved since you last looked, and `updatedAt` to ask whether the ticket itself was rewritten.

item.author — object

Field	Type	Description
`userId`	`string`	The person’s user ID.
`fullName`	`string`	The person’s name, as it stands on their CompetLab account.

item.briefing — object

Field	Type	Description
`runId`	`string`	The edition that opened this ticket. It is the same `runId` that `GET /v1/projects/{projectId}/strategic-briefing/history` lists, so `GET /v1/projects/{projectId}/strategic-briefing/history/{runId}` reads that edition in full.
`dimension`	`string \| null`	The part of the analysis the recommendation came from. It is the edition’s own reading and stays as the edition wrote it, whatever labels the team later puts on the ticket. `null` where the edition named none. `agent-readiness` is the key for Agent Adoption — how well a site is set up for AI agents to discover, access and read it. The key predates the name and does not change. One of 14 values (e.g. `ai-visibility`, `ai-sources`, `positioning`, …). Nullable.
`estimatedMinutes`	`number \| null`	How long the edition estimated the work would take, in minutes. `null` where it gave no estimate — read that as unsized, not as quick. Nullable.
`extendsTicketId`	`string \| null`	The id of the ticket already on the board that this one builds on with a different piece of work; `GET /v1/projects/{projectId}/tickets/{ticketId}` reads it. Set once by the edition that opened this ticket, and said in words in the description. `null` where it builds on none. Nullable.

item.labels[] — each entry

Field	Type	Description
`id`	`string`	The label’s ID. This is what a ticket’s `labelIds` names when you create or update one.
`name`	`string`	The label’s name. Unique within the project, compared without regard to case.
`color`	`string`	The label’s colour, as lower-case hex — `#rrggbb`. This is the form every tracker a ticket may be copied into speaks.

item.assignee — object

Field	Type	Description
`userId`	`string`	The person’s user ID.
`fullName`	`string`	The person’s name, as it stands on their CompetLab account.

Errors

Status	Code	Meaning
400	`invalid_parameters` · `invalid_run_id` · `invalid_check_id` · `bad_request` · `paging_requires_compact_view` · `paging_requires_summary` · `nothing_to_return`	Bad request — the payload failed validation.
401	`api_key_missing` · `api_key_invalid` · `api_key_revoked` · `api_key_expired` · `insufficient_scope`	The `CL-API-Key` is missing, malformed, revoked, expired, or lacks the required scope.
403	`insufficient_scope` · `forbidden`	The key is not permitted to access this resource.
429	`rate_limit_exceeded`	Rate limit exceeded — retry with backoff.

Every error uses the shared { error: { code, message, status } } envelope; code is one of the values listed above.


{
  "error": {
    "code": "invalid_parameters",
    "message": "Domain is required",
    "status": 400
  }
}

Transient failures (429, 5xx) are safe to retry with exponential backoff.

Get a ticket

GET/v1/projects/{projectId}/tickets/{ticketId}

Get one ticket: its description, its labels resolved to name and colour, its assignee, its dates, and how many entries its thread holds. On a ticket a Strategic Briefing opened, briefing names the edition it came from; it is null on every other ticket. An ID that belongs to another project answers 404 exactly as an ID that exists nowhere does.

Returns · { item }

Path parameters

Name	Type	Description
`ticketId`	`string`	Ticket ID
`projectId`	`string`	Project ID

Request


curl "https://api.competlab.com/v1/projects/507f1f77bcf86cd799439011/tickets/507f1f77bcf86cd799439011" \
  -H "CL-API-Key: YOUR_COMPETLAB_API_KEY"

Response 200 OK

Example


{
  "item": {
    "id": "507f1f77bcf86cd799439011",
    "number": 14,
    "origin": "api",
    "author": {
      "userId": "507f1f77bcf86cd799439011",
      "fullName": "Dana Ellis"
    },
    "briefing": {
      "runId": "6a3950c06bda450a1372048e",
      "dimension": "pricing",
      "estimatedMinutes": 90,
      "extendsTicketId": "507f1f77bcf86cd799439012"
    },
    "title": "Get onto the 2026 buyer guide",
    "description": "The guide names three of our competitors and not us.",
    "labels": [
      {
        "id": "3f2a9c6e-1b77-4c1e-9a54-5c7b2f0a91d2",
        "name": "Pricing page",
        "color": "#3b82f6"
      }
    ],
    "status": "todo",
    "statusChangedAt": "2026-09-15T10:00:00.000Z",
    "assignee": {
      "userId": "507f1f77bcf86cd799439011",
      "fullName": "Dana Ellis"
    },
    "dueDate": "2026-10-01",
    "effort": "medium",
    "impact": 3,
    "commentCount": 2,
    "deletable": true,
    "createdAt": "2026-09-15T10:00:00.000Z",
    "updatedAt": "2026-09-16T08:30:00.000Z",
    "lastActivityAt": "2026-09-17T11:02:00.000Z"
  }
}

Fields

item — object

Field	Type	Description
`id`	`string`	The ticket’s ID.
`number`	`number \| null`	The ticket’s number on its project’s board — what a person says when they mean this ticket, shown in the app as `#14`. The first ticket a project opens is 1 and each one after it takes the next number, whatever opened it. A number never changes and is never given to a second ticket, so expect gaps: a number no ticket carries belonged to one that was deleted, or to a create that did not finish. `null` on a ticket opened before the board had numbers. Every endpoint takes the ticket’s `id`; none looks a ticket up by its number. Nullable.
`origin`	`string`	What wrote this: `user` — a person working in the app; `api` — an API key, which is what everything you write through this API carries; `briefing` or `ai_sources` — CompetLab itself. The server sets it; a request that sends it is refused. Values: `user`, `api`, `briefing`, `ai_sources`.
`author`	`object \| null`	The person who opened the ticket. `null` where no person did — `origin` says what did. Nullable. See `item.author`.
`briefing`	`object \| null`	The Strategic Briefing edition this ticket came from, and what that edition proposed. Present where `origin` is `briefing`, `null` on every other ticket. It records what the edition said and does not move when the ticket is edited — the title, the description and the planning fields are the team’s to rewrite; this is not. Nullable. See `item.briefing`.
`title`	`string`	The ticket’s title.
`description`	`string`	The ticket’s description, written in Markdown. An empty string where nothing was written. A row of the ticket LIST does not carry it unless the list was asked for bodies (`include=description`) — the key is then absent, never an empty string. Every other answer that returns a ticket — a single read, a create, an update, a move — and every webhook delivery carries it.
`labels`	`array<object>`	The ticket’s labels, each resolved to its name and colour, in the project’s own picker order. A ticket carries only labels the project’s list holds. See `item.labels[]`.
`status`	`string`	The column the ticket sits in. `triage` — nobody has decided yet. `todo` — decided, not started. `in_progress` — being worked on. `done` — finished. `dismissed` — the team decided not to do it. The set is fixed and a project cannot add to it. Change it with the move endpoint, never with an update. Values: `triage`, `todo`, `in_progress`, `done`, `dismissed`.
`statusChangedAt`	`string`	When the ticket last changed column — its creation time until it first moves. Reordering a ticket inside its column does not touch it. ISO-8601.
`assignee`	`object \| null`	The person the ticket is assigned to, or `null` where nobody is. Somebody who has left the organization reads as unassigned here, and nothing is written back. Nullable. See `item.assignee`.
`dueDate`	`string \| null`	The day the ticket is due, as `YYYY-MM-DD` — a calendar day, with no clock and no time zone, so it is the same day for every reader. `null` where none is set. Nullable.
`effort`	`string \| null`	How much work the ticket is. `null` where nobody has said. Values: `low`, `medium`, `high`. Nullable.
`impact`	`number \| null`	How much the ticket matters, from 1 to 4 (1 Minor · 2 Moderate · 3 Significant · 4 Critical; 4 matters most). `null` where nobody has said. Nullable.
`commentCount`	`number`	How many entries the ticket’s thread holds. Counted when the ticket is read.
`deletable`	`boolean`	Whether this ticket can be deleted. A ticket a Strategic Briefing opened is moved to `dismissed` instead, so that what opened it does not open it again — deleting one is refused. Read this rather than working it out from `origin`.
`createdAt`	`string`	When the ticket was opened. ISO-8601.
`updatedAt`	`string`	When the ticket last changed in any way. ISO-8601.
`lastActivityAt`	`string`	The last time anything happened to this ticket — an edit, a move, or an entry added to its thread. ISO-8601, and never earlier than `updatedAt`. Adding a comment does not change the ticket itself, so `updatedAt` can stand still while a thread fills up: read this field to ask whether a ticket has moved since you last looked, and `updatedAt` to ask whether the ticket itself was rewritten.

item.author — object

Field	Type	Description
`userId`	`string`	The person’s user ID.
`fullName`	`string`	The person’s name, as it stands on their CompetLab account.

item.briefing — object

Field	Type	Description
`runId`	`string`	The edition that opened this ticket. It is the same `runId` that `GET /v1/projects/{projectId}/strategic-briefing/history` lists, so `GET /v1/projects/{projectId}/strategic-briefing/history/{runId}` reads that edition in full.
`dimension`	`string \| null`	The part of the analysis the recommendation came from. It is the edition’s own reading and stays as the edition wrote it, whatever labels the team later puts on the ticket. `null` where the edition named none. `agent-readiness` is the key for Agent Adoption — how well a site is set up for AI agents to discover, access and read it. The key predates the name and does not change. One of 14 values (e.g. `ai-visibility`, `ai-sources`, `positioning`, …). Nullable.
`estimatedMinutes`	`number \| null`	How long the edition estimated the work would take, in minutes. `null` where it gave no estimate — read that as unsized, not as quick. Nullable.
`extendsTicketId`	`string \| null`	The id of the ticket already on the board that this one builds on with a different piece of work; `GET /v1/projects/{projectId}/tickets/{ticketId}` reads it. Set once by the edition that opened this ticket, and said in words in the description. `null` where it builds on none. Nullable.

item.labels[] — each entry

Field	Type	Description
`id`	`string`	The label’s ID. This is what a ticket’s `labelIds` names when you create or update one.
`name`	`string`	The label’s name. Unique within the project, compared without regard to case.
`color`	`string`	The label’s colour, as lower-case hex — `#rrggbb`. This is the form every tracker a ticket may be copied into speaks.

item.assignee — object

Field	Type	Description
`userId`	`string`	The person’s user ID.
`fullName`	`string`	The person’s name, as it stands on their CompetLab account.

Errors

Status	Code	Meaning
400	`invalid_parameters` · `invalid_run_id` · `invalid_check_id` · `bad_request` · `paging_requires_compact_view` · `paging_requires_summary` · `nothing_to_return`	Bad request — the payload failed validation.
401	`api_key_missing` · `api_key_invalid` · `api_key_revoked` · `api_key_expired` · `insufficient_scope`	The `CL-API-Key` is missing, malformed, revoked, expired, or lacks the required scope.
404	`not_found`	No `ticket` matches the id in the path.
429	`rate_limit_exceeded`	Rate limit exceeded — retry with backoff.

Every error uses the shared { error: { code, message, status } } envelope; code is one of the values listed above.


{
  "error": {
    "code": "invalid_parameters",
    "message": "Domain is required",
    "status": 400
  }
}

Transient failures (429, 5xx) are safe to retry with exponential backoff.

Update a ticket

PATCH/v1/projects/{projectId}/tickets/{ticketId}

Change a ticket’s content and planning fields. Omit a field to leave it as it is, send a value to replace it, send null to clear it. The description and the labels are cleared by their own empty value instead — "" and [] — because for those an empty value is a real one. A column, and a place inside one, are a move and are not accepted here, so a ticket can never change column as a side effect of an edit. Requires a read_write key.

Returns · { item }

Path parameters

Name	Type	Description
`ticketId`	`string`	Ticket ID
`projectId`	`string`	Project ID

Request body — application/json

Field	Type	Description
`title`	`string`	The ticket’s title.
`description`	`string`	The ticket’s description, in Markdown. At most 20000 characters. Send `""` to clear it.
`labelIds`	`array<string>`	IDs from the project’s own label list — read it with the labels endpoint, and create a label there before naming it. At most 10 per ticket, each named once. The list replaces what the ticket holds; send `[]` to clear it.
`assigneeUserId`	`string \| null`	The user ID of a current member of your organization — list them with `GET /v1/projects/{projectId}/tickets/assignees`. A user ID from anywhere else is refused. Send `null` to leave the ticket unassigned. Nullable.
`dueDate`	`string \| null`	The day the ticket is due, as `YYYY-MM-DD` — a calendar day, with no clock and no time zone. Send `null` to take the due date off. Nullable.
`effort`	`string \| null`	How much work the ticket is. Send `null` to take it off. Values: `low`, `medium`, `high`. Nullable.
`impact`	`number \| null`	How much the ticket matters, from 1 to 4 (1 Minor · 2 Moderate · 3 Significant · 4 Critical; 4 matters most). Send `null` to take it off. Nullable.

Request


curl -X PATCH "https://api.competlab.com/v1/projects/507f1f77bcf86cd799439011/tickets/507f1f77bcf86cd799439011" \
  -H "CL-API-Key: YOUR_COMPETLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Get onto the 2026 buyer guide","description":"The guide names three of our competitors and not us.","labelIds":["3f2a9c6e-1b77-4c1e-9a54-5c7b2f0a91d2"],"assigneeUserId":"507f1f77bcf86cd799439031","dueDate":"2026-10-01","effort":"medium","impact":3}'

Response 200 OK

Example


{
  "item": {
    "id": "507f1f77bcf86cd799439011",
    "number": 14,
    "origin": "api",
    "author": {
      "userId": "507f1f77bcf86cd799439011",
      "fullName": "Dana Ellis"
    },
    "briefing": {
      "runId": "6a3950c06bda450a1372048e",
      "dimension": "pricing",
      "estimatedMinutes": 90,
      "extendsTicketId": "507f1f77bcf86cd799439012"
    },
    "title": "Get onto the 2026 buyer guide",
    "description": "The guide names three of our competitors and not us.",
    "labels": [
      {
        "id": "3f2a9c6e-1b77-4c1e-9a54-5c7b2f0a91d2",
        "name": "Pricing page",
        "color": "#3b82f6"
      }
    ],
    "status": "todo",
    "statusChangedAt": "2026-09-15T10:00:00.000Z",
    "assignee": {
      "userId": "507f1f77bcf86cd799439011",
      "fullName": "Dana Ellis"
    },
    "dueDate": "2026-10-01",
    "effort": "medium",
    "impact": 3,
    "commentCount": 2,
    "deletable": true,
    "createdAt": "2026-09-15T10:00:00.000Z",
    "updatedAt": "2026-09-16T08:30:00.000Z",
    "lastActivityAt": "2026-09-17T11:02:00.000Z"
  }
}

Fields

item — object

Field	Type	Description
`id`	`string`	The ticket’s ID.
`number`	`number \| null`	The ticket’s number on its project’s board — what a person says when they mean this ticket, shown in the app as `#14`. The first ticket a project opens is 1 and each one after it takes the next number, whatever opened it. A number never changes and is never given to a second ticket, so expect gaps: a number no ticket carries belonged to one that was deleted, or to a create that did not finish. `null` on a ticket opened before the board had numbers. Every endpoint takes the ticket’s `id`; none looks a ticket up by its number. Nullable.
`origin`	`string`	What wrote this: `user` — a person working in the app; `api` — an API key, which is what everything you write through this API carries; `briefing` or `ai_sources` — CompetLab itself. The server sets it; a request that sends it is refused. Values: `user`, `api`, `briefing`, `ai_sources`.
`author`	`object \| null`	The person who opened the ticket. `null` where no person did — `origin` says what did. Nullable. See `item.author`.
`briefing`	`object \| null`	The Strategic Briefing edition this ticket came from, and what that edition proposed. Present where `origin` is `briefing`, `null` on every other ticket. It records what the edition said and does not move when the ticket is edited — the title, the description and the planning fields are the team’s to rewrite; this is not. Nullable. See `item.briefing`.
`title`	`string`	The ticket’s title.
`description`	`string`	The ticket’s description, written in Markdown. An empty string where nothing was written. A row of the ticket LIST does not carry it unless the list was asked for bodies (`include=description`) — the key is then absent, never an empty string. Every other answer that returns a ticket — a single read, a create, an update, a move — and every webhook delivery carries it.
`labels`	`array<object>`	The ticket’s labels, each resolved to its name and colour, in the project’s own picker order. A ticket carries only labels the project’s list holds. See `item.labels[]`.
`status`	`string`	The column the ticket sits in. `triage` — nobody has decided yet. `todo` — decided, not started. `in_progress` — being worked on. `done` — finished. `dismissed` — the team decided not to do it. The set is fixed and a project cannot add to it. Change it with the move endpoint, never with an update. Values: `triage`, `todo`, `in_progress`, `done`, `dismissed`.
`statusChangedAt`	`string`	When the ticket last changed column — its creation time until it first moves. Reordering a ticket inside its column does not touch it. ISO-8601.
`assignee`	`object \| null`	The person the ticket is assigned to, or `null` where nobody is. Somebody who has left the organization reads as unassigned here, and nothing is written back. Nullable. See `item.assignee`.
`dueDate`	`string \| null`	The day the ticket is due, as `YYYY-MM-DD` — a calendar day, with no clock and no time zone, so it is the same day for every reader. `null` where none is set. Nullable.
`effort`	`string \| null`	How much work the ticket is. `null` where nobody has said. Values: `low`, `medium`, `high`. Nullable.
`impact`	`number \| null`	How much the ticket matters, from 1 to 4 (1 Minor · 2 Moderate · 3 Significant · 4 Critical; 4 matters most). `null` where nobody has said. Nullable.
`commentCount`	`number`	How many entries the ticket’s thread holds. Counted when the ticket is read.
`deletable`	`boolean`	Whether this ticket can be deleted. A ticket a Strategic Briefing opened is moved to `dismissed` instead, so that what opened it does not open it again — deleting one is refused. Read this rather than working it out from `origin`.
`createdAt`	`string`	When the ticket was opened. ISO-8601.
`updatedAt`	`string`	When the ticket last changed in any way. ISO-8601.
`lastActivityAt`	`string`	The last time anything happened to this ticket — an edit, a move, or an entry added to its thread. ISO-8601, and never earlier than `updatedAt`. Adding a comment does not change the ticket itself, so `updatedAt` can stand still while a thread fills up: read this field to ask whether a ticket has moved since you last looked, and `updatedAt` to ask whether the ticket itself was rewritten.

item.author — object

Field	Type	Description
`userId`	`string`	The person’s user ID.
`fullName`	`string`	The person’s name, as it stands on their CompetLab account.

item.briefing — object

Field	Type	Description
`runId`	`string`	The edition that opened this ticket. It is the same `runId` that `GET /v1/projects/{projectId}/strategic-briefing/history` lists, so `GET /v1/projects/{projectId}/strategic-briefing/history/{runId}` reads that edition in full.
`dimension`	`string \| null`	The part of the analysis the recommendation came from. It is the edition’s own reading and stays as the edition wrote it, whatever labels the team later puts on the ticket. `null` where the edition named none. `agent-readiness` is the key for Agent Adoption — how well a site is set up for AI agents to discover, access and read it. The key predates the name and does not change. One of 14 values (e.g. `ai-visibility`, `ai-sources`, `positioning`, …). Nullable.
`estimatedMinutes`	`number \| null`	How long the edition estimated the work would take, in minutes. `null` where it gave no estimate — read that as unsized, not as quick. Nullable.
`extendsTicketId`	`string \| null`	The id of the ticket already on the board that this one builds on with a different piece of work; `GET /v1/projects/{projectId}/tickets/{ticketId}` reads it. Set once by the edition that opened this ticket, and said in words in the description. `null` where it builds on none. Nullable.

item.labels[] — each entry

Field	Type	Description
`id`	`string`	The label’s ID. This is what a ticket’s `labelIds` names when you create or update one.
`name`	`string`	The label’s name. Unique within the project, compared without regard to case.
`color`	`string`	The label’s colour, as lower-case hex — `#rrggbb`. This is the form every tracker a ticket may be copied into speaks.

item.assignee — object

Field	Type	Description
`userId`	`string`	The person’s user ID.
`fullName`	`string`	The person’s name, as it stands on their CompetLab account.

Errors

Status	Code	Meaning
400	`invalid_parameters` · `invalid_run_id` · `invalid_check_id` · `bad_request` · `paging_requires_compact_view` · `paging_requires_summary` · `nothing_to_return`	Bad request — the payload failed validation.
401	`api_key_missing` · `api_key_invalid` · `api_key_revoked` · `api_key_expired` · `insufficient_scope`	The `CL-API-Key` is missing, malformed, revoked, expired, or lacks the required scope.
403	`insufficient_scope` · `forbidden`	The key is not permitted to access this resource.
404	`not_found`	No `ticket` matches the id in the path.
429	`rate_limit_exceeded`	Rate limit exceeded — retry with backoff.

Every error uses the shared { error: { code, message, status } } envelope; code is one of the values listed above.


{
  "error": {
    "code": "invalid_parameters",
    "message": "Domain is required",
    "status": 400
  }
}

Transient failures (429, 5xx) are safe to retry with exponential backoff.

Delete a ticket

DELETE/v1/projects/{projectId}/tickets/{ticketId}

Delete a ticket and its thread. A ticket a Strategic Briefing opened cannot be deleted — move it to dismissed instead, so that what opened it does not open it again. Read deletable on the ticket first; deleting one that is not is refused with 400. Requires a read_write key.

Returns · { item }

Path parameters

Name	Type	Description
`ticketId`	`string`	Ticket ID
`projectId`	`string`	Project ID

Request


curl -X DELETE "https://api.competlab.com/v1/projects/507f1f77bcf86cd799439011/tickets/507f1f77bcf86cd799439011" \
  -H "CL-API-Key: YOUR_COMPETLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response 200 OK

Example


{
  "item": {
    "success": true,
    "id": "507f1f77bcf86cd799439011"
  }
}

Errors

Status	Code	Meaning
400	`invalid_parameters` · `invalid_run_id` · `invalid_check_id` · `bad_request` · `paging_requires_compact_view` · `paging_requires_summary` · `nothing_to_return`	Bad request — the payload failed validation.
401	`api_key_missing` · `api_key_invalid` · `api_key_revoked` · `api_key_expired` · `insufficient_scope`	The `CL-API-Key` is missing, malformed, revoked, expired, or lacks the required scope.
403	`insufficient_scope` · `forbidden`	The key is not permitted to access this resource.
404	`not_found`	No `ticket` matches the id in the path.
429	`rate_limit_exceeded`	Rate limit exceeded — retry with backoff.

Every error uses the shared { error: { code, message, status } } envelope; code is one of the values listed above.


{
  "error": {
    "code": "invalid_parameters",
    "message": "Domain is required",
    "status": 400
  }
}

Transient failures (429, 5xx) are safe to retry with exponential backoff.

Move a ticket

PATCH/v1/projects/{projectId}/tickets/{ticketId}/move

Move a ticket to another column, or reorder it inside the one it is in. Name the destination column, then where it goes: position=top or position=bottom, or the two tickets it will sit between — beforeId is the one directly ABOVE it, afterId the one directly BELOW; name either or both. A request naming a position and a neighbour is refused. Omitting everything puts it at the bottom — the opposite of a new ticket, which lands at the top. There is no index to compute — you name neighbours you can see and the server works out the order, so two clients moving tickets at the same time converge on one order instead of overwriting each other. A neighbour that has been deleted, or now sits in another column, is not used; if you named both and the one below now sits above the one above, the one above is kept; if neither can be used, the ticket goes to the bottom. A move never fails because your view of the board was a moment old. The answer says where it landed: placement.above and placement.below are its neighbours now, and placement.ignored names each neighbour you named that was not used and why — other_column most often means you read it off another column’s list. An empty ignored means every neighbour you named was used, not that nothing sits between them: compare above and below with what you named, and if they differ and the exact place matters, re-read that column in board order and move again. Reordering inside a column leaves statusChangedAt alone. Requires a read_write key.

Returns · { item, placement }

Path parameters

Name	Type	Description
`ticketId`	`string`	Ticket ID
`projectId`	`string`	Project ID

Request body — application/json

Field	Type	Description
`status`	`string`	The column the ticket ends up in. Always the destination, never a change flag — reordering a ticket inside the column it already sits in names that column. Values: `triage`, `todo`, `in_progress`, `done`, `dismissed`.
`beforeId`	`string`	The ticket that will sit directly ABOVE this one. Name either neighbour or both. Omitting both puts the ticket at the BOTTOM of the destination column — which is its first card when that column is empty.
`afterId`	`string`	The ticket that will sit directly BELOW this one. To put a ticket at the TOP of a column, send the ticket currently first there as `afterId`, and no `beforeId`.
`position`	`string`	The top or the bottom of the destination column, without reading the column first. Name a position OR neighbours: a request carrying both is refused. Omitting everything puts the ticket at the bottom. Values: `top`, `bottom`.

Request


curl -X PATCH "https://api.competlab.com/v1/projects/507f1f77bcf86cd799439011/tickets/507f1f77bcf86cd799439011/move" \
  -H "CL-API-Key: YOUR_COMPETLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"in_progress","beforeId":"507f1f77bcf86cd799439012","afterId":"507f1f77bcf86cd799439013","position":"top"}'

Response 200 OK

Example


{
  "item": {
    "id": "507f1f77bcf86cd799439011",
    "number": 14,
    "origin": "api",
    "author": {
      "userId": "507f1f77bcf86cd799439011",
      "fullName": "Dana Ellis"
    },
    "briefing": {
      "runId": "6a3950c06bda450a1372048e",
      "dimension": "pricing",
      "estimatedMinutes": 90,
      "extendsTicketId": "507f1f77bcf86cd799439012"
    },
    "title": "Get onto the 2026 buyer guide",
    "description": "The guide names three of our competitors and not us.",
    "labels": [
      {
        "id": "3f2a9c6e-1b77-4c1e-9a54-5c7b2f0a91d2",
        "name": "Pricing page",
        "color": "#3b82f6"
      }
    ],
    "status": "todo",
    "statusChangedAt": "2026-09-15T10:00:00.000Z",
    "assignee": {
      "userId": "507f1f77bcf86cd799439011",
      "fullName": "Dana Ellis"
    },
    "dueDate": "2026-10-01",
    "effort": "medium",
    "impact": 3,
    "commentCount": 2,
    "deletable": true,
    "createdAt": "2026-09-15T10:00:00.000Z",
    "updatedAt": "2026-09-16T08:30:00.000Z",
    "lastActivityAt": "2026-09-17T11:02:00.000Z"
  },
  "placement": {
    "status": "triage",
    "above": {
      "id": "507f1f77bcf86cd799439012",
      "number": 12,
      "title": "Publish the integrations page"
    },
    "below": {
      "id": "507f1f77bcf86cd799439012",
      "number": 12,
      "title": "Publish the integrations page"
    },
    "ignored": [
      {
        "id": "507f1f77bcf86cd799439014",
        "as": "beforeId",
        "reason": "not_found",
        "status": "triage"
      }
    ]
  }
}

Fields

item — object

Field	Type	Description
`id`	`string`	The ticket’s ID.
`number`	`number \| null`	The ticket’s number on its project’s board — what a person says when they mean this ticket, shown in the app as `#14`. The first ticket a project opens is 1 and each one after it takes the next number, whatever opened it. A number never changes and is never given to a second ticket, so expect gaps: a number no ticket carries belonged to one that was deleted, or to a create that did not finish. `null` on a ticket opened before the board had numbers. Every endpoint takes the ticket’s `id`; none looks a ticket up by its number. Nullable.
`origin`	`string`	What wrote this: `user` — a person working in the app; `api` — an API key, which is what everything you write through this API carries; `briefing` or `ai_sources` — CompetLab itself. The server sets it; a request that sends it is refused. Values: `user`, `api`, `briefing`, `ai_sources`.
`author`	`object \| null`	The person who opened the ticket. `null` where no person did — `origin` says what did. Nullable. See `item.author`.
`briefing`	`object \| null`	The Strategic Briefing edition this ticket came from, and what that edition proposed. Present where `origin` is `briefing`, `null` on every other ticket. It records what the edition said and does not move when the ticket is edited — the title, the description and the planning fields are the team’s to rewrite; this is not. Nullable. See `item.briefing`.
`title`	`string`	The ticket’s title.
`description`	`string`	The ticket’s description, written in Markdown. An empty string where nothing was written. A row of the ticket LIST does not carry it unless the list was asked for bodies (`include=description`) — the key is then absent, never an empty string. Every other answer that returns a ticket — a single read, a create, an update, a move — and every webhook delivery carries it.
`labels`	`array<object>`	The ticket’s labels, each resolved to its name and colour, in the project’s own picker order. A ticket carries only labels the project’s list holds. See `item.labels[]`.
`status`	`string`	The column the ticket sits in. `triage` — nobody has decided yet. `todo` — decided, not started. `in_progress` — being worked on. `done` — finished. `dismissed` — the team decided not to do it. The set is fixed and a project cannot add to it. Change it with the move endpoint, never with an update. Values: `triage`, `todo`, `in_progress`, `done`, `dismissed`.
`statusChangedAt`	`string`	When the ticket last changed column — its creation time until it first moves. Reordering a ticket inside its column does not touch it. ISO-8601.
`assignee`	`object \| null`	The person the ticket is assigned to, or `null` where nobody is. Somebody who has left the organization reads as unassigned here, and nothing is written back. Nullable. See `item.assignee`.
`dueDate`	`string \| null`	The day the ticket is due, as `YYYY-MM-DD` — a calendar day, with no clock and no time zone, so it is the same day for every reader. `null` where none is set. Nullable.
`effort`	`string \| null`	How much work the ticket is. `null` where nobody has said. Values: `low`, `medium`, `high`. Nullable.
`impact`	`number \| null`	How much the ticket matters, from 1 to 4 (1 Minor · 2 Moderate · 3 Significant · 4 Critical; 4 matters most). `null` where nobody has said. Nullable.
`commentCount`	`number`	How many entries the ticket’s thread holds. Counted when the ticket is read.
`deletable`	`boolean`	Whether this ticket can be deleted. A ticket a Strategic Briefing opened is moved to `dismissed` instead, so that what opened it does not open it again — deleting one is refused. Read this rather than working it out from `origin`.
`createdAt`	`string`	When the ticket was opened. ISO-8601.
`updatedAt`	`string`	When the ticket last changed in any way. ISO-8601.
`lastActivityAt`	`string`	The last time anything happened to this ticket — an edit, a move, or an entry added to its thread. ISO-8601, and never earlier than `updatedAt`. Adding a comment does not change the ticket itself, so `updatedAt` can stand still while a thread fills up: read this field to ask whether a ticket has moved since you last looked, and `updatedAt` to ask whether the ticket itself was rewritten.

placement — object

Field	Type	Description
`status`	`string`	The column the ticket is in now. Values: `triage`, `todo`, `in_progress`, `done`, `dismissed`.
`above`	`object \| null`	The ticket directly above it now. `null` when it is first in the column. Nullable. See `placement.above`.
`below`	`object \| null`	The ticket directly below it now. `null` when it is last in the column. Nullable. See `placement.below`.
`ignored`	`array<object>`	Every neighbour the request named that was not used, and why. Empty when every neighbour you named was used — which alone does not mean the ticket sits right next to them: compare `above` and `below` with what you named, and if they differ and the exact place matters, re-read that column in board order and move again. See `placement.ignored[]`.

item.author — object

Field	Type	Description
`userId`	`string`	The person’s user ID.
`fullName`	`string`	The person’s name, as it stands on their CompetLab account.

item.briefing — object

Field	Type	Description
`runId`	`string`	The edition that opened this ticket. It is the same `runId` that `GET /v1/projects/{projectId}/strategic-briefing/history` lists, so `GET /v1/projects/{projectId}/strategic-briefing/history/{runId}` reads that edition in full.
`dimension`	`string \| null`	The part of the analysis the recommendation came from. It is the edition’s own reading and stays as the edition wrote it, whatever labels the team later puts on the ticket. `null` where the edition named none. `agent-readiness` is the key for Agent Adoption — how well a site is set up for AI agents to discover, access and read it. The key predates the name and does not change. One of 14 values (e.g. `ai-visibility`, `ai-sources`, `positioning`, …). Nullable.
`estimatedMinutes`	`number \| null`	How long the edition estimated the work would take, in minutes. `null` where it gave no estimate — read that as unsized, not as quick. Nullable.
`extendsTicketId`	`string \| null`	The id of the ticket already on the board that this one builds on with a different piece of work; `GET /v1/projects/{projectId}/tickets/{ticketId}` reads it. Set once by the edition that opened this ticket, and said in words in the description. `null` where it builds on none. Nullable.

item.labels[] — each entry

Field	Type	Description
`id`	`string`	The label’s ID. This is what a ticket’s `labelIds` names when you create or update one.
`name`	`string`	The label’s name. Unique within the project, compared without regard to case.
`color`	`string`	The label’s colour, as lower-case hex — `#rrggbb`. This is the form every tracker a ticket may be copied into speaks.

item.assignee — object

Field	Type	Description
`userId`	`string`	The person’s user ID.
`fullName`	`string`	The person’s name, as it stands on their CompetLab account.

placement.above — object

Field	Type	Description
`id`	`string`	The neighbour’s ID.
`number`	`number \| null`	Its number on the board, as a person says it. `null` on a ticket that has none. Nullable.
`title`	`string`	Its title.

placement.below — object

Field	Type	Description
`id`	`string`	The neighbour’s ID.
`number`	`number \| null`	Its number on the board, as a person says it. `null` on a ticket that has none. Nullable.
`title`	`string`	Its title.

placement.ignored[] — each entry

Field	Type	Description
`id`	`string`	The neighbour ID the request named.
`as`	`string`	Which neighbour it was named as. Values: `beforeId`, `afterId`.
`reason`	`string`	Why it was not used: `not_found` — deleted, or never on this project; `other_column` — on this project but in another column, most often read off the wrong column’s list; `out_of_order` — both are in the column, but the one named as `afterId` now sits above `beforeId`, and `beforeId` was kept; `self` — the moved ticket named as its own neighbour. Values: `not_found`, `other_column`, `out_of_order`, `self`.
`status`	`string \| null`	The column that ticket sits in now — for `self`, the column the moved ticket is now in. `null` only where it was not found. Values: `triage`, `todo`, `in_progress`, `done`, `dismissed`. Nullable.

Errors

Status	Code	Meaning
400	`invalid_parameters` · `invalid_run_id` · `invalid_check_id` · `bad_request` · `paging_requires_compact_view` · `paging_requires_summary` · `nothing_to_return`	Bad request — the payload failed validation.
401	`api_key_missing` · `api_key_invalid` · `api_key_revoked` · `api_key_expired` · `insufficient_scope`	The `CL-API-Key` is missing, malformed, revoked, expired, or lacks the required scope.
403	`insufficient_scope` · `forbidden`	The key is not permitted to access this resource.
404	`not_found`	No `ticket` matches the id in the path.
429	`rate_limit_exceeded`	Rate limit exceeded — retry with backoff.

Every error uses the shared { error: { code, message, status } } envelope; code is one of the values listed above.


{
  "error": {
    "code": "invalid_parameters",
    "message": "Domain is required",
    "status": 400
  }
}

Transient failures (429, 5xx) are safe to retry with exponential backoff.

List a ticket’s comments

GET/v1/projects/{projectId}/tickets/{ticketId}/comments

List a ticket’s thread, oldest first and whole — nothing pages it, so nothing is counted twice. Each entry says what wrote it: a person working in the app, or an API key.

Returns · { items }

Path parameters

Name	Type	Description
`ticketId`	`string`	Ticket ID
`projectId`	`string`	Project ID

Request


curl "https://api.competlab.com/v1/projects/507f1f77bcf86cd799439011/tickets/507f1f77bcf86cd799439011/comments" \
  -H "CL-API-Key: YOUR_COMPETLAB_API_KEY"

Response 200 OK

Example


{
  "items": [
    {
      "id": "507f1f77bcf86cd799439021",
      "ticketId": "507f1f77bcf86cd799439011",
      "origin": "api",
      "author": {
        "userId": "507f1f77bcf86cd799439011",
        "fullName": "Dana Ellis"
      },
      "body": "Reached the editor on 14 Sep; they update the guide quarterly.",
      "edited": false,
      "createdAt": "2026-09-15T10:05:00.000Z",
      "updatedAt": "2026-09-15T10:05:00.000Z",
      "briefing": {
        "runId": "6a3950c06bda450a1372048e",
        "kind": "result",
        "editionNumber": 5,
        "completedAt": "2026-10-05T06:12:00.000Z"
      }
    }
  ]
}

Fields

items[] — each entry

Field	Type	Description
`id`	`string`	The entry’s ID.
`ticketId`	`string`	The ticket this entry belongs to.
`origin`	`string`	What wrote this: `user` — a person working in the app; `api` — an API key, which is what everything you write through this API carries; `briefing` or `ai_sources` — CompetLab itself. The server sets it; a request that sends it is refused. Values: `user`, `api`, `briefing`, `ai_sources`.
`author`	`object \| null`	The person who wrote the entry. `null` where no person did — `origin` says what did. Nullable. See `items[].author`.
`body`	`string`	The entry’s text, written in Markdown.
`edited`	`boolean`	Whether the entry was rewritten after it was first written. The server answers it — do not work it out by comparing the two timestamps below, or two surfaces will say different things about the same entry.
`createdAt`	`string`	When the entry was written. ISO-8601.
`updatedAt`	`string`	When the entry was last rewritten, or when it was written. ISO-8601.
`briefing`	`object \| null`	Set only on a comment a Strategic Briefing wrote; null on every comment a person or an API key wrote. runId names the edition; kind says why it exists: result — Measured after close: the check before the ticket opened beside the first check after it closed; basis_weaker — Reason weaker: what the ticket rests on moved, and its reason is weaker for it; basis_stronger — Reason stronger: the same, stronger; basis_changed — Reason changed: it moved, and the edition cannot say whether that makes the reason weaker or stronger; basis_gone — Reason gone: measured again, and what the ticket rests on is no longer there (for example the page no longer names any competitor). Never a check that failed — a page we could not read is not a page that names nobody. The body is dated facts and never a cause: report it as the comment states it, never as the fix having worked. Nullable. See `items[].briefing`.

items[].author — object

Field	Type	Description
`userId`	`string`	The person’s user ID.
`fullName`	`string`	The person’s name, as it stands on their CompetLab account.

items[].briefing — object

Field	Type	Description
`runId`	`string`	The edition that wrote this comment. It is the same `runId` that `GET /v1/projects/{projectId}/strategic-briefing/history` lists, so `GET /v1/projects/{projectId}/strategic-briefing/history/{runId}` reads that edition in full.
`kind`	`string \| null`	Why the comment exists — see `briefing` above for what each value means. `null` on a kind this API does not know yet; the comment is still there. Values: `result`, `basis_changed`, `basis_weaker`, `basis_stronger`, `basis_gone`. Nullable.
`editionNumber`	`number \| null`	The edition’s number in the project’s series of Strategic Briefings — what a person means by “edition 5”. `null` where that edition has since been replaced. Nullable.
`completedAt`	`string \| null`	When the edition finished, ISO-8601 — the same moment its own envelope calls `completedAt`. `null` where that edition has since been replaced. Nullable.

Errors

Status	Code	Meaning
400	`invalid_parameters` · `invalid_run_id` · `invalid_check_id` · `bad_request` · `paging_requires_compact_view` · `paging_requires_summary` · `nothing_to_return`	Bad request — the payload failed validation.
401	`api_key_missing` · `api_key_invalid` · `api_key_revoked` · `api_key_expired` · `insufficient_scope`	The `CL-API-Key` is missing, malformed, revoked, expired, or lacks the required scope.
404	`not_found`	No `ticket` matches the id in the path.
429	`rate_limit_exceeded`	Rate limit exceeded — retry with backoff.

Every error uses the shared { error: { code, message, status } } envelope; code is one of the values listed above.


{
  "error": {
    "code": "invalid_parameters",
    "message": "Domain is required",
    "status": 400
  }
}

Transient failures (429, 5xx) are safe to retry with exponential backoff.

Add a ticket comment

POST/v1/projects/{projectId}/tickets/{ticketId}/comments

Add an entry to a ticket’s thread, written in Markdown. The entry is recorded as written by an API key. A thread holds at most 500 entries. Requires a read_write key.

Returns · { item }

Path parameters

Name	Type	Description
`ticketId`	`string`	Ticket ID
`projectId`	`string`	Project ID

Request body — application/json

Field	Type	Description
`body`	`string`	The entry’s text, in Markdown. At most 20000 characters. It is stored exactly as it is sent — leading whitespace is a code block in the dialect that draws it, so nothing is trimmed off the ends.

Request


curl -X POST "https://api.competlab.com/v1/projects/507f1f77bcf86cd799439011/tickets/507f1f77bcf86cd799439011/comments" \
  -H "CL-API-Key: YOUR_COMPETLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"body":"Reached the editor on 14 Sep; they update the guide quarterly."}'

Response 200 OK

Example


{
  "item": {
    "id": "507f1f77bcf86cd799439021",
    "ticketId": "507f1f77bcf86cd799439011",
    "origin": "api",
    "author": {
      "userId": "507f1f77bcf86cd799439011",
      "fullName": "Dana Ellis"
    },
    "body": "Reached the editor on 14 Sep; they update the guide quarterly.",
    "edited": false,
    "createdAt": "2026-09-15T10:05:00.000Z",
    "updatedAt": "2026-09-15T10:05:00.000Z",
    "briefing": {
      "runId": "6a3950c06bda450a1372048e",
      "kind": "result",
      "editionNumber": 5,
      "completedAt": "2026-10-05T06:12:00.000Z"
    }
  }
}

Fields

item — object

Field	Type	Description
`id`	`string`	The entry’s ID.
`ticketId`	`string`	The ticket this entry belongs to.
`origin`	`string`	What wrote this: `user` — a person working in the app; `api` — an API key, which is what everything you write through this API carries; `briefing` or `ai_sources` — CompetLab itself. The server sets it; a request that sends it is refused. Values: `user`, `api`, `briefing`, `ai_sources`.
`author`	`object \| null`	The person who wrote the entry. `null` where no person did — `origin` says what did. Nullable. See `item.author`.
`body`	`string`	The entry’s text, written in Markdown.
`edited`	`boolean`	Whether the entry was rewritten after it was first written. The server answers it — do not work it out by comparing the two timestamps below, or two surfaces will say different things about the same entry.
`createdAt`	`string`	When the entry was written. ISO-8601.
`updatedAt`	`string`	When the entry was last rewritten, or when it was written. ISO-8601.
`briefing`	`object \| null`	Set only on a comment a Strategic Briefing wrote; null on every comment a person or an API key wrote. runId names the edition; kind says why it exists: result — Measured after close: the check before the ticket opened beside the first check after it closed; basis_weaker — Reason weaker: what the ticket rests on moved, and its reason is weaker for it; basis_stronger — Reason stronger: the same, stronger; basis_changed — Reason changed: it moved, and the edition cannot say whether that makes the reason weaker or stronger; basis_gone — Reason gone: measured again, and what the ticket rests on is no longer there (for example the page no longer names any competitor). Never a check that failed — a page we could not read is not a page that names nobody. The body is dated facts and never a cause: report it as the comment states it, never as the fix having worked. Nullable. See `item.briefing`.

item.author — object

Field	Type	Description
`userId`	`string`	The person’s user ID.
`fullName`	`string`	The person’s name, as it stands on their CompetLab account.

item.briefing — object

Field	Type	Description
`runId`	`string`	The edition that wrote this comment. It is the same `runId` that `GET /v1/projects/{projectId}/strategic-briefing/history` lists, so `GET /v1/projects/{projectId}/strategic-briefing/history/{runId}` reads that edition in full.
`kind`	`string \| null`	Why the comment exists — see `briefing` above for what each value means. `null` on a kind this API does not know yet; the comment is still there. Values: `result`, `basis_changed`, `basis_weaker`, `basis_stronger`, `basis_gone`. Nullable.
`editionNumber`	`number \| null`	The edition’s number in the project’s series of Strategic Briefings — what a person means by “edition 5”. `null` where that edition has since been replaced. Nullable.
`completedAt`	`string \| null`	When the edition finished, ISO-8601 — the same moment its own envelope calls `completedAt`. `null` where that edition has since been replaced. Nullable.

Errors

Status	Code	Meaning
400	`invalid_parameters` · `invalid_run_id` · `invalid_check_id` · `bad_request` · `paging_requires_compact_view` · `paging_requires_summary` · `nothing_to_return`	Bad request — the payload failed validation.
401	`api_key_missing` · `api_key_invalid` · `api_key_revoked` · `api_key_expired` · `insufficient_scope`	The `CL-API-Key` is missing, malformed, revoked, expired, or lacks the required scope.
403	`insufficient_scope` · `forbidden`	The key is not permitted to access this resource.
404	`not_found`	No `ticket` matches the id in the path.
429	`rate_limit_exceeded`	Rate limit exceeded — retry with backoff.

Every error uses the shared { error: { code, message, status } } envelope; code is one of the values listed above.


{
  "error": {
    "code": "invalid_parameters",
    "message": "Domain is required",
    "status": 400
  }
}

Transient failures (429, 5xx) are safe to retry with exponential backoff.

Edit a ticket comment

PATCH/v1/projects/{projectId}/tickets/{ticketId}/comments/{commentId}

Rewrite an entry this API wrote. An entry a person wrote in the app is theirs to edit there, and rewriting it here answers 403 forbidden. The text is the only part of an entry anyone may change. Requires a read_write key.

Returns · { item }

Path parameters

Name	Type	Description
`ticketId`	`string`	Ticket ID
`commentId`	`string`	Comment ID
`projectId`	`string`	Project ID

Request body — application/json

Field	Type	Description
`body`	`string`	The entry’s text, in Markdown. At most 20000 characters. It is stored exactly as it is sent — leading whitespace is a code block in the dialect that draws it, so nothing is trimmed off the ends.

Request


curl -X PATCH "https://api.competlab.com/v1/projects/507f1f77bcf86cd799439011/tickets/507f1f77bcf86cd799439011/comments/507f1f77bcf86cd799439021" \
  -H "CL-API-Key: YOUR_COMPETLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"body":"Reached the editor on 14 Sep; they update the guide quarterly."}'

Response 200 OK

Example


{
  "item": {
    "id": "507f1f77bcf86cd799439021",
    "ticketId": "507f1f77bcf86cd799439011",
    "origin": "api",
    "author": {
      "userId": "507f1f77bcf86cd799439011",
      "fullName": "Dana Ellis"
    },
    "body": "Reached the editor on 14 Sep; they update the guide quarterly.",
    "edited": false,
    "createdAt": "2026-09-15T10:05:00.000Z",
    "updatedAt": "2026-09-15T10:05:00.000Z",
    "briefing": {
      "runId": "6a3950c06bda450a1372048e",
      "kind": "result",
      "editionNumber": 5,
      "completedAt": "2026-10-05T06:12:00.000Z"
    }
  }
}

Fields

item — object

Field	Type	Description
`id`	`string`	The entry’s ID.
`ticketId`	`string`	The ticket this entry belongs to.
`origin`	`string`	What wrote this: `user` — a person working in the app; `api` — an API key, which is what everything you write through this API carries; `briefing` or `ai_sources` — CompetLab itself. The server sets it; a request that sends it is refused. Values: `user`, `api`, `briefing`, `ai_sources`.
`author`	`object \| null`	The person who wrote the entry. `null` where no person did — `origin` says what did. Nullable. See `item.author`.
`body`	`string`	The entry’s text, written in Markdown.
`edited`	`boolean`	Whether the entry was rewritten after it was first written. The server answers it — do not work it out by comparing the two timestamps below, or two surfaces will say different things about the same entry.
`createdAt`	`string`	When the entry was written. ISO-8601.
`updatedAt`	`string`	When the entry was last rewritten, or when it was written. ISO-8601.
`briefing`	`object \| null`	Set only on a comment a Strategic Briefing wrote; null on every comment a person or an API key wrote. runId names the edition; kind says why it exists: result — Measured after close: the check before the ticket opened beside the first check after it closed; basis_weaker — Reason weaker: what the ticket rests on moved, and its reason is weaker for it; basis_stronger — Reason stronger: the same, stronger; basis_changed — Reason changed: it moved, and the edition cannot say whether that makes the reason weaker or stronger; basis_gone — Reason gone: measured again, and what the ticket rests on is no longer there (for example the page no longer names any competitor). Never a check that failed — a page we could not read is not a page that names nobody. The body is dated facts and never a cause: report it as the comment states it, never as the fix having worked. Nullable. See `item.briefing`.

item.author — object

Field	Type	Description
`userId`	`string`	The person’s user ID.
`fullName`	`string`	The person’s name, as it stands on their CompetLab account.

item.briefing — object

Field	Type	Description
`runId`	`string`	The edition that wrote this comment. It is the same `runId` that `GET /v1/projects/{projectId}/strategic-briefing/history` lists, so `GET /v1/projects/{projectId}/strategic-briefing/history/{runId}` reads that edition in full.
`kind`	`string \| null`	Why the comment exists — see `briefing` above for what each value means. `null` on a kind this API does not know yet; the comment is still there. Values: `result`, `basis_changed`, `basis_weaker`, `basis_stronger`, `basis_gone`. Nullable.
`editionNumber`	`number \| null`	The edition’s number in the project’s series of Strategic Briefings — what a person means by “edition 5”. `null` where that edition has since been replaced. Nullable.
`completedAt`	`string \| null`	When the edition finished, ISO-8601 — the same moment its own envelope calls `completedAt`. `null` where that edition has since been replaced. Nullable.

Errors

Status	Code	Meaning
400	`invalid_parameters` · `invalid_run_id` · `invalid_check_id` · `bad_request` · `paging_requires_compact_view` · `paging_requires_summary` · `nothing_to_return`	Bad request — the payload failed validation.
401	`api_key_missing` · `api_key_invalid` · `api_key_revoked` · `api_key_expired` · `insufficient_scope`	The `CL-API-Key` is missing, malformed, revoked, expired, or lacks the required scope.
403	`insufficient_scope` · `forbidden`	The key is not permitted to access this resource.
404	`not_found`	No `comment` matches the id in the path.
429	`rate_limit_exceeded`	Rate limit exceeded — retry with backoff.

Every error uses the shared { error: { code, message, status } } envelope; code is one of the values listed above.


{
  "error": {
    "code": "invalid_parameters",
    "message": "Domain is required",
    "status": 400
  }
}

Transient failures (429, 5xx) are safe to retry with exponential backoff.

Delete a ticket comment

DELETE/v1/projects/{projectId}/tickets/{ticketId}/comments/{commentId}

Delete an entry from a ticket’s thread. A key reaches any entry on the ticket, whoever wrote it: a key is issued by an owner or an admin and acts with that authority. Requires a read_write key.

Returns · { item }

Path parameters

Name	Type	Description
`ticketId`	`string`	Ticket ID
`commentId`	`string`	Comment ID
`projectId`	`string`	Project ID

Request


curl -X DELETE "https://api.competlab.com/v1/projects/507f1f77bcf86cd799439011/tickets/507f1f77bcf86cd799439011/comments/507f1f77bcf86cd799439021" \
  -H "CL-API-Key: YOUR_COMPETLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response 200 OK

Example


{
  "item": {
    "success": true,
    "id": "507f1f77bcf86cd799439011"
  }
}

Errors

Status	Code	Meaning
400	`invalid_parameters` · `invalid_run_id` · `invalid_check_id` · `bad_request` · `paging_requires_compact_view` · `paging_requires_summary` · `nothing_to_return`	Bad request — the payload failed validation.
401	`api_key_missing` · `api_key_invalid` · `api_key_revoked` · `api_key_expired` · `insufficient_scope`	The `CL-API-Key` is missing, malformed, revoked, expired, or lacks the required scope.
403	`insufficient_scope` · `forbidden`	The key is not permitted to access this resource.
404	`not_found`	No `comment` matches the id in the path.
429	`rate_limit_exceeded`	Rate limit exceeded — retry with backoff.

Every error uses the shared { error: { code, message, status } } envelope; code is one of the values listed above.


{
  "error": {
    "code": "invalid_parameters",
    "message": "Domain is required",
    "status": 400
  }
}

Transient failures (429, 5xx) are safe to retry with exponential backoff.

Field	Type	Description
`success`	`boolean`	Always true. A delete that did not happen answers with an error instead.
`id`	`string`	The ID of what was deleted.