DocsDevelopers
REST API · v1

API reference

Telos exposes a REST API over the same service layer the app uses. Every response includes a HATEOAS actions array, and every error includes a machine-actionable suggestion. OpenAPI 3.1 spec at /api/v1/openapi.json.

Auth

Authentication

Authenticate with a bearer token in the Authorization header. Keys start with telos_live_ and carry a role (engineer, pm, em, executive, admin) that determines which fields are returned. Keys are issued from inside the app at Configurations → API Keys. If you do not have an organization yet, sign up.

Third-party OAuth apps authenticate the same way with access tokens starting telos_oat_, issued by POST /api/oauth/token (authorization_code with PKCE, refresh_token rotation). Send users to GET /oauth/authorize with client_id, redirect_uri, response_type=code, scope, and state to request consent; an org admin approves on the consent screen. Unlike API keys, an OAuth token's granted scopes are its entire permission set.

Add actor=app to the authorize URL for a grant that acts as your app rather than the approving admin: it survives the admin leaving the org and its writes are attributed to the app. The token endpoint accepts client credentials in the body or as HTTP Basic auth, and POST /api/oauth/revoke (RFC 7009) revokes a token and its refresh family, e.g. on uninstall.

curl
curl -X GET 'https://www.telos-app.com/api/v1/visions' \
  -H 'Authorization: Bearer telos_live_…'
Lists

Pagination

List endpoints use cursor pagination. Pass cursor from the previous response's meta.pagination.nextCursor to fetch the next page. Default page size is 50; max is 200 via the limit parameter, and the same two numbers apply on MCP and the CLI: an action pages identically on every transport. There is no sort parameter; each list has one fixed order. The same actions array surfaces the next page as a rel: "next" link, so agents can walk pagination without parsing meta.

response
{
  "ok": true,
  "data": [ /* … items … */ ],
  "meta": {
    "requestId": "01H8X3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-05-18T14:23:11.842Z",
    "pagination": {
      "cursor": null,
      "nextCursor": "eyJpZCI6IjAxIH0=",
      "hasMore": true
    }
  },
  "actions": [
    { "rel": "next", "href": "/api/v1/visions?cursor=eyJpZCI6IjAxIH0=" }
  ]
}
Failure modes

Errors

Errors return a non-2xx status with a body in the standard envelope. The suggestion field is written for LLMs: it states what the caller should do differently. Status codes: 400 validation, 401 missing/invalid credentials, 403 role-gated, 404 not found, 409 conflict (idempotency or state), 422 business-rule violation (e.g. validation gate), 429 rate-limited, 5xx internal.

response
{
  "ok": false,
  "error": {
    "code": "validation_failed",
    "message": "Field 'narrative' must be at least 1 character",
    "suggestion": "Provide a non-empty narrative. The minimum is 1 character."
  },
  "meta": { "requestId": "01H8X3F4S0Z9KMQ4N6PYZR7C5A", "timestamp": "…" }
}
One round trip

Batch

POST /api/v1/batch executes up to 20 operations in a single request. Each operation runs independently; the response is a 207 multi-status whose data contains the per-operation envelopes keyed by the id you supplied. Send an Idempotency-Key header on the batch request to make retries safe.

request body
{
  "operations": [
    { "id": "1", "method": "POST", "path": "/api/v1/objectives", "body": { /* … */ } },
    { "id": "2", "method": "GET",  "path": "/api/v1/visions/abc" }
  ]
}
Throughput

Rate limits

Each key gets 600 requests/minute on a sliding window. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (epoch seconds). Over the limit returns 429 with a Retry-After header — back off for that many seconds, or fold several calls into one POST /api/v1/batch.

For agents

Assembled context

GET /api/v1/ai/context/vision/{id} returns a vision and its objectives, metrics, opportunities, and tasks assembled into one payload alongside a ready-to-use system prompt and a list of the mutation endpoints an agent can call next — so a model can ground itself in one request instead of walking the graph. Requires vision:read.

Resource

Visions

GET/api/v1/visions

List visions

List strategic visions with cursor pagination: the company vision first, then product visions. Optionally filter by kind (company, product).

Parameters
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
kindquery · stringoptional
Vision kind filter
Returns · 200 — List visions
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
namestringrequired
numberintegerrequired
kind"company" | "product"required
narrativestringrequired
versionintegerrequired
ownerIdobjectrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/visions' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "name": "string",
      "number": 0,
      "kind": "company",
      "narrative": "string",
      "version": 0,
      "ownerId": null,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/visions

Create a vision

Create a vision: the company vision (kind 'company', one per org) or a product vision (kind 'product'). The narrative is the persuasive 2-5 year story, not a slogan.

Request body · required
namestringrequired
kind"company" | "product"optional
narrativestringrequired
Returns · 201 — Create a vision
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
namestringrequired
numberintegerrequired
kind"company" | "product"required
narrativestringrequired
versionintegerrequired
ownerIdobjectrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/visions' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "name": "string",
    "number": 0,
    "kind": "company",
    "narrative": "string",
    "version": 0,
    "ownerId": null,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/visions/{id}

Get a vision

Get a vision by UUID or by its per-org ref (VIS-12).

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Get a vision
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
namestringrequired
numberintegerrequired
kind"company" | "product"required
narrativestringrequired
versionintegerrequired
ownerIdobjectrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/visions/{id}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "name": "string",
    "number": 0,
    "kind": "company",
    "narrative": "string",
    "version": 0,
    "ownerId": null,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
PATCH/api/v1/visions/{id}

Update a vision

Update a vision's name or narrative. Edits are versioned.

Parameters
idpath · stringrequired
id path parameter
Request body · required
namestringoptional
narrativestringoptional
Returns · 200 — Update a vision
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
namestringrequired
numberintegerrequired
kind"company" | "product"required
narrativestringrequired
versionintegerrequired
ownerIdobjectrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
PATCH request
curl -X PATCH 'https://www.telos-app.com/api/v1/visions/{id}' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "name": "string",
    "number": 0,
    "kind": "company",
    "narrative": "string",
    "version": 0,
    "ownerId": null,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/visions/{id}/versions

List a vision's version history

Version snapshots of a vision, newest first, with cursor pagination. Every name or narrative edit creates one.

Parameters
idpath · stringrequired
id path parameter
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
Returns · 200 — List a vision's version history
oktruerequired
dataobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/visions/{id}/versions' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": null,
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/visions/{id}/objectives

List objectives for a vision

The objectives anchored to this vision, with cursor pagination. Returns objective rows, so it needs objective:read as well as vision:read.

Parameters
idpath · stringrequired
id path parameter
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
Returns · 200 — List objectives for a vision
oktruerequired
dataobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/visions/{id}/objectives' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": null,
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/visions/{id}/children

Count a vision's children

Blast radius of a vision: how many objectives, opportunities and tasks hang off it. Objectives link by FK; opportunities and tasks by their visionPath prefix. 404 when the vision is not one of yours — zero children and no such vision are different answers.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Count a vision's children
oktruerequired
dataobjectrequired
Show child attributes ›
objectivesintegerrequired
opportunitiesintegerrequired
tasksintegerrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/visions/{id}/children' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "objectives": 0,
    "opportunities": 0,
    "tasks": 0
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/visions/{id}/versions/{version}/rename

Rename a vision version

Label one snapshot in a vision's version history. An empty note clears the label, so the version falls back to 'v{n}'.

Parameters
idpath · stringrequired
id path parameter
versionpath · stringrequired
version path parameter
Request body · required
notestringrequired
Version label; empty clears it
Returns · 200 — Rename a vision version
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
visionIdstring<uuid>required
versionintegerrequired
namestringrequired
narrativestringrequired
changeNotestringrequired
createdAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/visions/{id}/versions/{version}/rename' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "visionId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "version": 0,
    "name": "string",
    "narrative": "string",
    "changeNote": "string",
    "createdAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
Resource

Objectives

GET/api/v1/objectives

List objectives

List strategic objectives with cursor pagination. Filter by vision, by the metric they are anchored to, by DRI (pass your own user id from whoami for 'my objectives'), or by status.

Parameters
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
visionIdquery · string<uuid>optional
Vision UUID filter
metricIdquery · string<uuid>optional
Anchor metric UUID filter
driIdquery · string<uuid>optional
DRI user UUID filter
statusquery · stringoptional
Objective status filter. One of: active, achieved, abandoned
Returns · 200 — List objectives
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
visionIdstring<uuid>required
numberintegerrequired
titlestringrequired
descriptionstringrequired
metricIdobjectrequired
targetOperatorobjectrequired
targetNumericstringrequired
startNumericstringrequired
driIdstring<uuid>required
deadlinestringrequired
horizonobjectrequired
status"active" | "achieved" | "abandoned"required
visionVersionintegerrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/objectives' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "visionId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "number": 0,
      "title": "string",
      "description": "string",
      "metricId": null,
      "targetOperator": null,
      "targetNumeric": "string",
      "startNumeric": "string",
      "driId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "deadline": "string",
      "horizon": null,
      "status": "active",
      "visionVersion": 0,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/objectives

Create an objective

Create a strategic objective under a vision. Requires a DRI. The metric block (metricId, operator, target) is optional: goals with no clean measurement are created without one and can be anchored later.

Request body · required
titlestringrequired
descriptionstringoptional
deadlinestring<date-time>optional
visionIdstring<uuid>required
driIdstring<uuid>required
horizon"short" | "long"optional
metricobjectoptional
Show child attributes ›
metricIdstring<uuid>required
operator"gte" | "lte" | "eq"required
targetnumberrequired
startValuenumberoptional
Returns · 201 — Create an objective
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
visionIdstring<uuid>required
numberintegerrequired
titlestringrequired
descriptionstringrequired
metricIdobjectrequired
targetOperatorobjectrequired
targetNumericstringrequired
startNumericstringrequired
driIdstring<uuid>required
deadlinestringrequired
horizonobjectrequired
status"active" | "achieved" | "abandoned"required
visionVersionintegerrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/objectives' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "visionId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "number": 0,
    "title": "string",
    "description": "string",
    "metricId": null,
    "targetOperator": null,
    "targetNumeric": "string",
    "startNumeric": "string",
    "driId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "deadline": "string",
    "horizon": null,
    "status": "active",
    "visionVersion": 0,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/objectives/{id}

Get an objective

Get an objective by UUID or by its per-org ref (OBJ-12).

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Get an objective
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
visionIdstring<uuid>required
numberintegerrequired
titlestringrequired
descriptionstringrequired
metricIdobjectrequired
targetOperatorobjectrequired
targetNumericstringrequired
startNumericstringrequired
driIdstring<uuid>required
deadlinestringrequired
horizonobjectrequired
status"active" | "achieved" | "abandoned"required
visionVersionintegerrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/objectives/{id}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "visionId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "number": 0,
    "title": "string",
    "description": "string",
    "metricId": null,
    "targetOperator": null,
    "targetNumeric": "string",
    "startNumeric": "string",
    "driId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "deadline": "string",
    "horizon": null,
    "status": "active",
    "visionVersion": 0,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
PATCH/api/v1/objectives/{id}

Update an objective

Update an objective's title, description, deadline, DRI, or status.

Parameters
idpath · stringrequired
id path parameter
Request body · required
visionIdstring<uuid>optional
titlestringoptional
descriptionstringoptional
deadlineobjectoptional
driIdstring<uuid>optional
horizonobjectoptional
status"active" | "achieved" | "abandoned"optional
Returns · 200 — Update an objective
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
visionIdstring<uuid>required
numberintegerrequired
titlestringrequired
descriptionstringrequired
metricIdobjectrequired
targetOperatorobjectrequired
targetNumericstringrequired
startNumericstringrequired
driIdstring<uuid>required
deadlinestringrequired
horizonobjectrequired
status"active" | "achieved" | "abandoned"required
visionVersionintegerrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
PATCH request
curl -X PATCH 'https://www.telos-app.com/api/v1/objectives/{id}' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "visionId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "number": 0,
    "title": "string",
    "description": "string",
    "metricId": null,
    "targetOperator": null,
    "targetNumeric": "string",
    "startNumeric": "string",
    "driId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "deadline": "string",
    "horizon": null,
    "status": "active",
    "visionVersion": 0,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
DELETE/api/v1/objectives/{id}

Delete an objective

Permanently delete an objective.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Delete an objective
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
deletedtruerequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
DELETE request
curl -X DELETE 'https://www.telos-app.com/api/v1/objectives/{id}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "deleted": true
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/objectives/{id}/opportunities

Get the opportunities linked to an objective

The complete set of opportunities linked to this objective, with their link metadata, alphabetically by title. Not paginated: it is a roll-up of one objective's trace, ordered on a value derived after the query, so there is no stable cursor to page it on. Use `list_opportunities` for a paged walk of the org's opportunities.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Get the opportunities linked to an objective
oktruerequired
dataobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/objectives/{id}/opportunities' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": null,
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/objectives/{id}/set-metric

Set an objective's metric

Replace which metric an objective points at, change its target shape (operator, target, start value), or pass metricId: null to clear the anchor entirely. An objective has at most one metric, and operator and target travel with it.

Parameters
idpath · stringrequired
id path parameter
Request body · required
metricIdobjectrequired
Metric UUID to anchor to; null clears the anchor
operator"gte" | "lte" | "eq"optional
Comparison operator. One of: gte, lte, eq
targetobjectoptional
Target value on the metric
startValueobjectoptional
Value the objective started from; null clears it
Returns · 200 — Set an objective's metric
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
visionIdstring<uuid>required
numberintegerrequired
titlestringrequired
descriptionstringrequired
metricIdobjectrequired
targetOperatorobjectrequired
targetNumericstringrequired
startNumericstringrequired
driIdstring<uuid>required
deadlinestringrequired
horizonobjectrequired
status"active" | "achieved" | "abandoned"required
visionVersionintegerrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/objectives/{id}/set-metric' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "visionId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "number": 0,
    "title": "string",
    "description": "string",
    "metricId": null,
    "targetOperator": null,
    "targetNumeric": "string",
    "startNumeric": "string",
    "driId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "deadline": "string",
    "horizon": null,
    "status": "active",
    "visionVersion": 0,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/objectives/alignment

Read the alignment grid

Every objective in the org as a column, plus the objectives and non-cancelled opportunities that claim to move them as rows. Each row carries `serves`: one entry per objective it advances, with kind 'primary' (this is what the row is really for) or 'supporting'. A primary objective→objective link is also the nesting parent. Not paginated: columns, rows and marks are one picture and a page cursor would draw a lying one; it is clamped instead. Use `list_objectives` for a paged walk.

Returns · 200 — Read the alignment grid
oktruerequired
dataobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/objectives/alignment' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": null,
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/objectives/{id}/nesting

Get an objective's parent and sub-objectives

The objective one level up (`parent`), the objectives one level down (`children`), and the supporting ties in both directions (`alsoServes`, `supportedBy`). Nesting is one level deep, so this is the whole tree around an objective, not a slice of it. Not paginated: it is bounded by the org's objective count and read as one shape.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Get an objective's parent and sub-objectives
oktruerequired
dataobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/objectives/{id}/nesting' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": null,
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/objectives/{id}/set-alignment-link

Point an objective or opportunity at an objective

Set, change or clear one claim in the alignment grid. Pass kind 'primary' for 'this is what the source is really for', 'supporting' for a secondary contribution, or null to remove the link. An objective may sit under at most one primary parent, and nesting is one level deep: a parent may not itself be a sub-objective.

Parameters
idpath · stringrequired
id path parameter
Request body · required
sourceType"objective" | "opportunity"required
What is doing the serving
sourceIdstring<uuid>required
Objective or opportunity UUID
kindobjectrequired
How hard the source pushes. One of: primary, supporting; null clears the link
Returns · 200 — Point an objective or opportunity at an objective
oktruerequired
dataobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/objectives/{id}/set-alignment-link' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": null,
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/objectives/{id}/claims

Get the customer claims on an objective

Every open customer insight tied to this objective, each with its estimated delta, committed date and the work items that satisfy it (conditionStatus: no_work, in_progress, delivered, broken). Not paginated: the claim set is assembled from three queries and ordered after the fact, so there is no stable cursor to page it on. Use `list_insights --objective-id` for a paged walk of the same insights.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Get the customer claims on an objective
oktruerequired
dataobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/objectives/{id}/claims' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": null,
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
Resource

Metrics

GET/api/v1/metrics

List metrics

List metrics tracked by the organisation, with cursor pagination. Filter by steward (pass your own user id from whoami for 'my metrics').

Parameters
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
stewardIdquery · string<uuid>optional
Steward user UUID filter
Returns · 200 — List metrics
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
numberintegerrequired
namestringrequired
descriptionstringrequired
currentValuestringrequired
unit"percentage" | "count" | "currency" | "ratio" | "duration" | "custom"required
stewardIdobjectrequired
dataSourceType"manual" | "integration" | "system"required
dataSourceConfigobjectrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/metrics' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "number": 0,
      "name": "string",
      "description": "string",
      "currentValue": "string",
      "unit": "percentage",
      "stewardId": null,
      "dataSourceType": "manual",
      "dataSourceConfig": null,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/metrics

Create a metric

Create a metric (name, unit, optional data source and steward).

Request body · required
namestringrequired
descriptionstringoptional
currentValueobjectoptional
Starting value
unit"percentage" | "count" | "currency" | "ratio" | "duration" | "custom"required
dataSourceType"manual" | "integration" | "system"optional
dataSourceConfigobjectoptional
stewardIdstring<uuid>optional
Returns · 201 — Create a metric
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
numberintegerrequired
namestringrequired
descriptionstringrequired
currentValuestringrequired
unit"percentage" | "count" | "currency" | "ratio" | "duration" | "custom"required
stewardIdobjectrequired
dataSourceType"manual" | "integration" | "system"required
dataSourceConfigobjectrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/metrics' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "number": 0,
    "name": "string",
    "description": "string",
    "currentValue": "string",
    "unit": "percentage",
    "stewardId": null,
    "dataSourceType": "manual",
    "dataSourceConfig": null,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/metrics/{id}

Get a metric

Get a metric by UUID or by its per-org ref (MET-12).

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Get a metric
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
numberintegerrequired
namestringrequired
descriptionstringrequired
currentValuestringrequired
unit"percentage" | "count" | "currency" | "ratio" | "duration" | "custom"required
stewardIdobjectrequired
dataSourceType"manual" | "integration" | "system"required
dataSourceConfigobjectrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/metrics/{id}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "number": 0,
    "name": "string",
    "description": "string",
    "currentValue": "string",
    "unit": "percentage",
    "stewardId": null,
    "dataSourceType": "manual",
    "dataSourceConfig": null,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
PATCH/api/v1/metrics/{id}

Update a metric

Update a metric's name, description, unit, data source, or steward.

Parameters
idpath · stringrequired
id path parameter
Request body · required
namestringoptional
descriptionstringoptional
currentValueobjectoptional
Latest value
unit"percentage" | "count" | "currency" | "ratio" | "duration" | "custom"optional
dataSourceType"manual" | "integration" | "system"optional
dataSourceConfigobjectoptional
stewardIdobjectoptional
Returns · 200 — Update a metric
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
numberintegerrequired
namestringrequired
descriptionstringrequired
currentValuestringrequired
unit"percentage" | "count" | "currency" | "ratio" | "duration" | "custom"required
stewardIdobjectrequired
dataSourceType"manual" | "integration" | "system"required
dataSourceConfigobjectrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
PATCH request
curl -X PATCH 'https://www.telos-app.com/api/v1/metrics/{id}' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "number": 0,
    "name": "string",
    "description": "string",
    "currentValue": "string",
    "unit": "percentage",
    "stewardId": null,
    "dataSourceType": "manual",
    "dataSourceConfig": null,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
DELETE/api/v1/metrics/{id}

Delete a metric

Permanently delete a metric.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Delete a metric
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
deletedtruerequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
DELETE request
curl -X DELETE 'https://www.telos-app.com/api/v1/metrics/{id}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "deleted": true
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/metrics/{id}/values

List metric values

Recorded values for a metric, oldest first, with cursor pagination over the whole series. Optionally filter by date (since).

Parameters
idpath · stringrequired
id path parameter
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
sincequeryoptional
Only values recorded at or after this time
Returns · 200 — List metric values
oktruerequired
dataobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/metrics/{id}/values' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": null,
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/metrics/{id}/values

Record a metric value

Record an observed value for a metric. recordedAt defaults to now; pass it to backfill history.

Parameters
idpath · stringrequired
id path parameter
Request body · required
valueobjectrequired
Observed value
recordedAtstring<date-time>optional
notestringoptional
source"manual" | "integration" | "system"optional
Returns · 201 — Record a metric value
oktruerequired
dataobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/metrics/{id}/values' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": null,
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/metrics/builtins

List built-in metrics Telos can track

The catalog of metrics Telos computes from its own data (task throughput, lead/cycle time, time in status, cycle predictability), with whether each is already tracked in this workspace.

Parameters
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
Returns · 200 — List built-in metrics Telos can track
oktruerequired
dataobject[][]required
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/metrics/builtins' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    [
      {
        "key": "string",
        "label": "string",
        "description": "string",
        "unit": "string",
        "source": "telos",
        "cadence": "week",
        "params": {
          "categoryId": "optional",
          "statusType": "required",
          "userId": "optional"
        },
        "trackedMetricId": null
      }
    ]
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/metrics/track-builtin

Start tracking a built-in metric

Create a system-sourced metric from the built-in catalog. Telos backfills recent history and keeps it current nightly; its readings cannot be entered by hand. Some builtins take params: an optional category scope, or a required status group for time-in-status.

Request body · required
key"tasks_completed_per_week" | "task_lead_time_days" | "task_cycle_time_days" | "time_in_status_days" | "cycle_predictability" | "github_prs_per_week" | "github_commits_per_week" | "github_releases_per_week"required
Catalog key, from list-builtins
categoryIdstring<uuid>optional
Scope to one task category
statusType"backlog" | "todo" | "in_progress" | "completed" | "cancelled" | "duplicate"optional
Status group to measure (required for time_in_status_days)
userIdstring<uuid>optional
Scope a GitHub builtin to one engineer's mapped logins
Returns · 201 — Start tracking a built-in metric
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
namestringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/metrics/track-builtin' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "name": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/metrics/{id}/opportunities

Get the opportunities betting on a metric

The complete set of opportunities that reach this metric through the objectives anchored to it, alphabetically by title. Not paginated: it is a roll-up of one metric's trace, ordered after the query, so there is no stable cursor to page it on. Use `objective list --metric-id` for the objectives themselves, and `list_opportunities` when you want a paged walk. 404 when the metric is not one of yours — an empty list means nobody is betting on it.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Get the opportunities betting on a metric
oktruerequired
dataobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/metrics/{id}/opportunities' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": null,
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/metrics/{id}/dependents

Count what depends on a metric

Blast radius before deleting or re-anchoring a metric: how many opportunities and objectives it carries, and how many of those opportunities are still live bets.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Count what depends on a metric
oktruerequired
dataobjectrequired
Show child attributes ›
opportunityCountintegerrequired
validatedOrShippedOpportunityCountintegerrequired
objectiveCountintegerrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/metrics/{id}/dependents' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "opportunityCount": 0,
    "validatedOrShippedOpportunityCount": 0,
    "objectiveCount": 0
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
Resource

Opportunities

GET/api/v1/opportunities

List opportunities

List opportunities with cursor pagination. Optionally filter by lifecycle state or team.

Parameters
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
statequery · stringoptional
Opportunity lifecycle state filter
teamIdquery · string<uuid>optional
Team UUID filter
leadUserIdquery · string<uuid>optional
Lead UUID filter. Pass your own user id (whoami) for 'my opportunities'
Returns · 200 — List opportunities
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
titlestringrequired
numberintegerrequired
estimatedCoststringrequired
costEstimatorIdobjectrequired
leadIdobjectrequired
teamIdobjectrequired
templateIdobjectrequired
status"backlog" | "in_progress" | "completed" | "cancelled"required
cancellationCategoryobjectrequired
cancellationReasonstringrequired
cancelledAtstringrequired
cancelledByUserIdobjectrequired
priorityobjectrequired
visionVersionobjectrequired
visionPathstringrequired
strategyVersionStampobjectrequired
prdstringrequired
prototypesobjectrequired
aiSynthesisobjectrequired
plannedStartstringrequired
plannedDurationDaysobjectrequired
dueDatestringrequired
isHardDeadlinebooleanrequired
categoryIdobjectrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/opportunities' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "title": "string",
      "number": 0,
      "estimatedCost": "string",
      "costEstimatorId": null,
      "leadId": null,
      "teamId": null,
      "templateId": null,
      "status": "backlog",
      "cancellationCategory": null,
      "cancellationReason": "string",
      "cancelledAt": "string",
      "cancelledByUserId": null,
      "priority": null,
      "visionVersion": null,
      "visionPath": "string",
      "strategyVersionStamp": null,
      "prd": "string",
      "prototypes": null,
      "aiSynthesis": null,
      "plannedStart": "string",
      "plannedDurationDays": null,
      "dueDate": "string",
      "isHardDeadline": true,
      "categoryId": null,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/opportunities

Create an opportunity

Create a work opportunity. The description seeds the PRD (or a PRD template does, when omitted). Optionally set lead, team, template, category, initial objective links, tags, and values for active scoring criteria. A patternPromotion additionally requires insight:update because it actions the pattern and links evidence atomically. Financial fields are ACL-gated.

Request body · required
titlestringrequired
descriptionstringoptional
leadIdstring<uuid>optional
teamIdobjectoptional
templateIdstring<uuid>optional
initialState"backlog" | "in_progress"optional
categoryIdobjectoptional
objectiveLinksobject[]optional
Show child attributes ›
objectiveIdstring<uuid>required
tagIdsstring<uuid>[]optional
scoresobject[]optional
Show child attributes ›
criterionIdstring<uuid>required
valueintegerrequired
dueDatestring<date>optional
prdTemplateIdobjectoptional
patternPromotionobjectoptional
Show child attributes ›
patternIdstring<uuid>required
insightIdsstring<uuid>[]required
Returns · 201 — Create an opportunity
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
titlestringrequired
numberintegerrequired
estimatedCoststringrequired
costEstimatorIdobjectrequired
leadIdobjectrequired
teamIdobjectrequired
templateIdobjectrequired
status"backlog" | "in_progress" | "completed" | "cancelled"required
cancellationCategoryobjectrequired
cancellationReasonstringrequired
cancelledAtstringrequired
cancelledByUserIdobjectrequired
priorityobjectrequired
visionVersionobjectrequired
visionPathstringrequired
strategyVersionStampobjectrequired
prdstringrequired
prototypesobjectrequired
aiSynthesisobjectrequired
plannedStartstringrequired
plannedDurationDaysobjectrequired
dueDatestringrequired
isHardDeadlinebooleanrequired
categoryIdobjectrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/opportunities' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "title": "string",
    "number": 0,
    "estimatedCost": "string",
    "costEstimatorId": null,
    "leadId": null,
    "teamId": null,
    "templateId": null,
    "status": "backlog",
    "cancellationCategory": null,
    "cancellationReason": "string",
    "cancelledAt": "string",
    "cancelledByUserId": null,
    "priority": null,
    "visionVersion": null,
    "visionPath": "string",
    "strategyVersionStamp": null,
    "prd": "string",
    "prototypes": null,
    "aiSynthesis": null,
    "plannedStart": "string",
    "plannedDurationDays": null,
    "dueDate": "string",
    "isHardDeadline": true,
    "categoryId": null,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/opportunities/{id}

Get an opportunity

Get a specific opportunity by id.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Get an opportunity
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
titlestringrequired
numberintegerrequired
estimatedCoststringrequired
costEstimatorIdobjectrequired
leadIdobjectrequired
teamIdobjectrequired
templateIdobjectrequired
status"backlog" | "in_progress" | "completed" | "cancelled"required
cancellationCategoryobjectrequired
cancellationReasonstringrequired
cancelledAtstringrequired
cancelledByUserIdobjectrequired
priorityobjectrequired
visionVersionobjectrequired
visionPathstringrequired
strategyVersionStampobjectrequired
prdstringrequired
prototypesobjectrequired
aiSynthesisobjectrequired
plannedStartstringrequired
plannedDurationDaysobjectrequired
dueDatestringrequired
isHardDeadlinebooleanrequired
categoryIdobjectrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/opportunities/{id}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "title": "string",
    "number": 0,
    "estimatedCost": "string",
    "costEstimatorId": null,
    "leadId": null,
    "teamId": null,
    "templateId": null,
    "status": "backlog",
    "cancellationCategory": null,
    "cancellationReason": "string",
    "cancelledAt": "string",
    "cancelledByUserId": null,
    "priority": null,
    "visionVersion": null,
    "visionPath": "string",
    "strategyVersionStamp": null,
    "prd": "string",
    "prototypes": null,
    "aiSynthesis": null,
    "plannedStart": "string",
    "plannedDurationDays": null,
    "dueDate": "string",
    "isHardDeadline": true,
    "categoryId": null,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
PATCH/api/v1/opportunities/{id}

Update an opportunity

Update an opportunity's title, lead, team, PRD body, or tag set. Editing the PRD clears any cached AI synthesis. Lifecycle moves go through set_opportunity_state, write_template_handoff (template steps) or reject_opportunity, not here.

Parameters
idpath · stringrequired
id path parameter
Request body · required
titlestringoptional
leadIdobjectoptional
teamIdobjectoptional
categoryIdobjectoptional
dueDateobjectoptional
prdstringoptional
tagIdsstring<uuid>[]optional
Replace the opportunity's whole tag set; omit to leave tags alone
Returns · 200 — Update an opportunity
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
titlestringrequired
numberintegerrequired
estimatedCoststringrequired
costEstimatorIdobjectrequired
leadIdobjectrequired
teamIdobjectrequired
templateIdobjectrequired
status"backlog" | "in_progress" | "completed" | "cancelled"required
cancellationCategoryobjectrequired
cancellationReasonstringrequired
cancelledAtstringrequired
cancelledByUserIdobjectrequired
priorityobjectrequired
visionVersionobjectrequired
visionPathstringrequired
strategyVersionStampobjectrequired
prdstringrequired
prototypesobjectrequired
aiSynthesisobjectrequired
plannedStartstringrequired
plannedDurationDaysobjectrequired
dueDatestringrequired
isHardDeadlinebooleanrequired
categoryIdobjectrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
PATCH request
curl -X PATCH 'https://www.telos-app.com/api/v1/opportunities/{id}' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "title": "string",
    "number": 0,
    "estimatedCost": "string",
    "costEstimatorId": null,
    "leadId": null,
    "teamId": null,
    "templateId": null,
    "status": "backlog",
    "cancellationCategory": null,
    "cancellationReason": "string",
    "cancelledAt": "string",
    "cancelledByUserId": null,
    "priority": null,
    "visionVersion": null,
    "visionPath": "string",
    "strategyVersionStamp": null,
    "prd": "string",
    "prototypes": null,
    "aiSynthesis": null,
    "plannedStart": "string",
    "plannedDurationDays": null,
    "dueDate": "string",
    "isHardDeadline": true,
    "categoryId": null,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
DELETE/api/v1/opportunities/{id}

Delete an opportunity

Permanently delete an opportunity and its dependency edges. Prefer reject_opportunity to record a won't-build decision; delete is for mistakes, not outcomes.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Delete an opportunity
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
DELETE request
curl -X DELETE 'https://www.telos-app.com/api/v1/opportunities/{id}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/opportunities/{id}/tasks

List tasks attached to an opportunity

The tasks attached to this opportunity, with cursor pagination.

Parameters
idpath · stringrequired
id path parameter
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
Returns · 200 — List tasks attached to an opportunity
oktruerequired
dataobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/opportunities/{id}/tasks' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": null,
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/opportunities/{ref}/context

Get an opportunity's full context bundle

Get everything needed to act on an opportunity in one call: the opportunity and PRD, linked objectives, the customer(s), comments, linked insights, the active template step, and any linked PRs. Sections you lack the read capability for (e.g. customers, insights) come back null. Pass the opportunity ref (e.g. OPP-23).

Parameters
refpath · stringrequired
ref path parameter
Returns · 200 — Get an opportunity's full context bundle
oktruerequired
dataobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/opportunities/{ref}/context' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": null,
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/opportunities/{id}/scorecard

Get an opportunity's scorecard

Get an opportunity's scorecard: the org's active scoring criteria (name, normalized decimal weight, invert), the shared 1-5 values with attribution, and the computed 0-100 total (null until every non-zero-weight criterion is scored). Positive active weights sum to 1 and correspond to the percentages shown in Settings; zero-weight criteria do not affect the total.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Get an opportunity's scorecard
oktruerequired
dataobjectrequired
Show child attributes ›
evidenceobjectrequired
Show child attributes ›
linkedCustomerCountintegerrequired
linkedArrTotalnumberrequired
mustCountintegerrequired
shouldCountintegerrequired
criteriaobject[]required
Show child attributes ›
idstring<uuid>required
namestringrequired
weightnumberrequired
invertbooleanrequired
positionintegerrequired
valuesobject[]required
Show child attributes ›
criterionIdstring<uuid>required
valueintegerrequired
updatedAtstringrequired
scoredByobjectrequired
totalobjectrequired
scoredCountintegerrequired
activeCountintegerrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/opportunities/{id}/scorecard' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "evidence": {
      "linkedCustomerCount": 0,
      "linkedArrTotal": 0,
      "mustCount": 0,
      "shouldCount": 0
    },
    "criteria": [
      {
        "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "name": "string",
        "weight": 0,
        "invert": true,
        "position": 0
      }
    ],
    "values": [
      {
        "criterionId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "value": 0,
        "updatedAt": "string",
        "scoredBy": null
      }
    ],
    "total": null,
    "scoredCount": 0,
    "activeCount": 0
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
PATCH/api/v1/opportunities/{id}/scores/{criterionId}

Set a scorecard value

Set one scorecard value on an opportunity: a shared 1-5 value for one of the org's scoring criteria (last write wins, attributed to the caller). Use get_opportunity_scorecard for criteria ids and the computed total.

Parameters
idpath · stringrequired
id path parameter
criterionIdpath · stringrequired
criterionId path parameter
Request body · required
valueobjectrequired
Score value on the 1-5 scale
Returns · 200 — Set a scorecard value
oktruerequired
dataobjectrequired
Show child attributes ›
evidenceobjectrequired
Show child attributes ›
linkedCustomerCountintegerrequired
linkedArrTotalnumberrequired
mustCountintegerrequired
shouldCountintegerrequired
criteriaobject[]required
Show child attributes ›
idstring<uuid>required
namestringrequired
weightnumberrequired
invertbooleanrequired
positionintegerrequired
valuesobject[]required
Show child attributes ›
criterionIdstring<uuid>required
valueintegerrequired
updatedAtstringrequired
scoredByobjectrequired
totalobjectrequired
scoredCountintegerrequired
activeCountintegerrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
PATCH request
curl -X PATCH 'https://www.telos-app.com/api/v1/opportunities/{id}/scores/{criterionId}' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "evidence": {
      "linkedCustomerCount": 0,
      "linkedArrTotal": 0,
      "mustCount": 0,
      "shouldCount": 0
    },
    "criteria": [
      {
        "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "name": "string",
        "weight": 0,
        "invert": true,
        "position": 0
      }
    ],
    "values": [
      {
        "criterionId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "value": 0,
        "updatedAt": "string",
        "scoredBy": null
      }
    ],
    "total": null,
    "scoredCount": 0,
    "activeCount": 0
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
DELETE/api/v1/opportunities/{id}/scores/{criterionId}

Clear a scorecard value

Clear one scorecard value on an opportunity (the total returns to null until re-scored).

Parameters
idpath · stringrequired
id path parameter
criterionIdpath · stringrequired
criterionId path parameter
Returns · 200 — Clear a scorecard value
oktruerequired
dataobjectrequired
Show child attributes ›
evidenceobjectrequired
Show child attributes ›
linkedCustomerCountintegerrequired
linkedArrTotalnumberrequired
mustCountintegerrequired
shouldCountintegerrequired
criteriaobject[]required
Show child attributes ›
idstring<uuid>required
namestringrequired
weightnumberrequired
invertbooleanrequired
positionintegerrequired
valuesobject[]required
Show child attributes ›
criterionIdstring<uuid>required
valueintegerrequired
updatedAtstringrequired
scoredByobjectrequired
totalobjectrequired
scoredCountintegerrequired
activeCountintegerrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
DELETE request
curl -X DELETE 'https://www.telos-app.com/api/v1/opportunities/{id}/scores/{criterionId}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "evidence": {
      "linkedCustomerCount": 0,
      "linkedArrTotal": 0,
      "mustCount": 0,
      "shouldCount": 0
    },
    "criteria": [
      {
        "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "name": "string",
        "weight": 0,
        "invert": true,
        "position": 0
      }
    ],
    "values": [
      {
        "criterionId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "value": 0,
        "updatedAt": "string",
        "scoredBy": null
      }
    ],
    "total": null,
    "scoredCount": 0,
    "activeCount": 0
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/opportunities/{id}/link-objective

Link an objective to an opportunity

Tie an opportunity to an objective (membership only: 'this bet claims to matter for that number'). Impact evidence lives on insights, not the link.

Parameters
idpath · stringrequired
id path parameter
Request body · required
objectiveIdstring<uuid>required
Returns · 201 — Link an objective to an opportunity
oktruerequired
dataobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/opportunities/{id}/link-objective' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": null,
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/opportunities/{id}/reject-via-template

Reject an opportunity and skip remaining template steps

Reject an opportunity: skips remaining template steps, lands it on the Cancelled terminal step (or flips a template-less one to cancelled), and records the categorized won't-build decision on the thread.

Parameters
idpath · stringrequired
id path parameter
Request body · required
category"no_demand" | "not_aligned" | "not_viable" | "not_now" | "duplicate" | "other"required
reasonstringrequired
Returns · 200 — Reject an opportunity and skip remaining template steps
oktruerequired
dataobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/opportunities/{id}/reject-via-template' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": null,
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/opportunities/{id}/updates

List an opportunity's status updates

The status updates posted on this opportunity, newest first. These are the same rows that reach every linked customer's feed; plain discussion comments are separate.

Parameters
idpath · stringrequired
id path parameter
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
Returns · 200 — List an opportunity's status updates
oktruerequired
dataobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/opportunities/{id}/updates' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": null,
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/opportunities/{id}/post-update

Post an opportunity status update

Post a status update on an opportunity, authored by the key's user. It lands in the opportunity's updates stream and flows into every linked customer's feed. For a plain discussion comment, use create_comment.

Parameters
idpath · stringrequired
id path parameter
Request body · required
bodystringrequired
The update text
Returns · 201 — Post an opportunity status update
oktruerequired
dataobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/opportunities/{id}/post-update' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": null,
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/opportunities/{id}/set-state

Set an opportunity's lifecycle state

Move an opportunity between backlog, in_progress and completed. On a template-bearing opportunity this drives the template (activating resumes the step it paused on, completing lands the Completed terminal step); a template-less one flips its status column. To record a won't-build decision use reject_opportunity, which takes the category and reason this action deliberately has no room for.

Parameters
idpath · stringrequired
id path parameter
Request body · required
state"backlog" | "in_progress" | "completed"required
Target lifecycle state. One of: backlog, in_progress, completed
Returns · 200 — Set an opportunity's lifecycle state
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
titlestringrequired
numberintegerrequired
estimatedCoststringrequired
costEstimatorIdobjectrequired
leadIdobjectrequired
teamIdobjectrequired
templateIdobjectrequired
status"backlog" | "in_progress" | "completed" | "cancelled"required
cancellationCategoryobjectrequired
cancellationReasonstringrequired
cancelledAtstringrequired
cancelledByUserIdobjectrequired
priorityobjectrequired
visionVersionobjectrequired
visionPathstringrequired
strategyVersionStampobjectrequired
prdstringrequired
prototypesobjectrequired
aiSynthesisobjectrequired
plannedStartstringrequired
plannedDurationDaysobjectrequired
dueDatestringrequired
isHardDeadlinebooleanrequired
categoryIdobjectrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/opportunities/{id}/set-state' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "title": "string",
    "number": 0,
    "estimatedCost": "string",
    "costEstimatorId": null,
    "leadId": null,
    "teamId": null,
    "templateId": null,
    "status": "backlog",
    "cancellationCategory": null,
    "cancellationReason": "string",
    "cancelledAt": "string",
    "cancelledByUserId": null,
    "priority": null,
    "visionVersion": null,
    "visionPath": "string",
    "strategyVersionStamp": null,
    "prd": "string",
    "prototypes": null,
    "aiSynthesis": null,
    "plannedStart": "string",
    "plannedDurationDays": null,
    "dueDate": "string",
    "isHardDeadline": true,
    "categoryId": null,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/opportunities/{id}/prototypes

Add a prototype to an opportunity

Attach a prototype to an opportunity, attributed to the key's user. Provide exactly one of `url` (http(s) only) or `fileId` (a previously uploaded file). Returns the opportunity's whole prototype list.

Parameters
idpath · stringrequired
id path parameter
Request body · required
urlstring<uri>optional
fileIdstring<uuid>optional
titlestringrequired
Returns · 201 — Add a prototype to an opportunity
oktruerequired
dataobjectrequired
Show child attributes ›
opportunityIdstring<uuid>required
prototypesobject[]required
Show child attributes ›
urlstringrequired
titlestringrequired
addedByUserIdstring<uuid>required
addedAtstringrequired
fileIdstring<uuid>optional
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/opportunities/{id}/prototypes' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "opportunityId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "prototypes": [
      {
        "url": "string",
        "title": "string",
        "addedByUserId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "addedAt": "string",
        "fileId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A"
      }
    ]
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
DELETE/api/v1/opportunities/{id}/prototypes

Remove a prototype link from an opportunity

Detach a prototype from an opportunity by its URL. Returns the remaining prototype list.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Remove a prototype link from an opportunity
oktruerequired
dataobjectrequired
Show child attributes ›
opportunityIdstring<uuid>required
prototypesobject[]required
Show child attributes ›
urlstringrequired
titlestringrequired
addedByUserIdstring<uuid>required
addedAtstringrequired
fileIdstring<uuid>optional
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
DELETE request
curl -X DELETE 'https://www.telos-app.com/api/v1/opportunities/{id}/prototypes' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "opportunityId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "prototypes": [
      {
        "url": "string",
        "title": "string",
        "addedByUserId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "addedAt": "string",
        "fileId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A"
      }
    ]
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/opportunities/{id}/synthesize

Draft a PRD from the opportunity's evidence

Run the org's configured LLM over the opportunity's insights, customers, prototypes and strategy context and return a draft PRD in markdown. The result is cached for an hour (cached=true, ageMs, and staleSinceLastSynth report the cache's age and how many insights landed since); pass bypassCache to re-draft. This returns a draft — it never writes the PRD, which is what update is for.

Parameters
idpath · stringrequired
id path parameter
Request body · required
bypassCacheobjectoptional
Ignore the cached draft and re-run the model
Returns · 200 — Draft a PRD from the opportunity's evidence
oktruerequired
dataobjectrequired
Show child attributes ›
markdownstringrequired
generatedAtstringrequired
modelstringrequired
cachedbooleanrequired
insightCountAtGenintegerrequired
ageMsintegerrequired
staleSinceLastSynthintegerrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/opportunities/{id}/synthesize' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "markdown": "string",
    "generatedAt": "string",
    "model": "string",
    "cached": true,
    "insightCountAtGen": 0,
    "ageMs": 0,
    "staleSinceLastSynth": 0
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/opportunities/{id}/risks

List an opportunity's validation risks and votes

The four validation risks (value, usability, feasibility, viability) for one opportunity: each risk's aggregate and every teammate's vote with its note.

Parameters
idpath · stringrequired
id path parameter
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
Returns · 200 — List an opportunity's validation risks and votes
oktruerequired
dataobject[]required
Show child attributes ›
opportunityRiskIdstring<uuid>required
risk"value" | "usability" | "feasibility" | "viability"required
aggregate"unset" | "approve" | "risky" | "reject"required
votesobject[]required
Show child attributes ›
userIdstring<uuid>required
userNamestringrequired
userAvatarUrlobjectrequired
vote"approve" | "risky" | "reject"required
notestringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/opportunities/{id}/risks' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "opportunityRiskId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "risk": "value",
      "aggregate": "unset",
      "votes": [
        {
          "userId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
          "userName": "string",
          "userAvatarUrl": null,
          "vote": "approve",
          "note": "string",
          "updatedAt": "string"
        }
      ]
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/opportunities/{id}/risks/{risk}

Vote on one of an opportunity's validation risks

Record the key's user vote (approve, risky, reject) plus a note on one validation risk. One vote per user per risk, last write wins. Returns all four risks with their recomputed aggregates.

Parameters
idpath · stringrequired
id path parameter
riskpath · stringrequired
risk path parameter
Request body · required
vote"approve" | "risky" | "reject"required
notestringrequired
Returns · 200 — Vote on one of an opportunity's validation risks
oktruerequired
dataobject[]required
Show child attributes ›
opportunityRiskIdstring<uuid>required
risk"value" | "usability" | "feasibility" | "viability"required
aggregate"unset" | "approve" | "risky" | "reject"required
votesobject[]required
Show child attributes ›
userIdstring<uuid>required
userNamestringrequired
userAvatarUrlobjectrequired
vote"approve" | "risky" | "reject"required
notestringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/opportunities/{id}/risks/{risk}' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": [
    {
      "opportunityRiskId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "risk": "value",
      "aggregate": "unset",
      "votes": [
        {
          "userId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
          "userName": "string",
          "userAvatarUrl": null,
          "vote": "approve",
          "note": "string",
          "updatedAt": "string"
        }
      ]
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/opportunities/{id}/apply-prd-template

Apply a PRD template to an opportunity

Write a PRD template's markdown into an opportunity's PRD, replacing the body or appending to it. Use list_prd_templates for template ids. This writes the OPPORTUNITY, not the template, so it is gated on opportunity:update; the template's own read ACL still applies.

Parameters
idpath · stringrequired
id path parameter
Request body · required
templateIdstring<uuid>required
mode"replace" | "append"required
Returns · 200 — Apply a PRD template to an opportunity
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
titlestringrequired
numberintegerrequired
estimatedCoststringrequired
costEstimatorIdobjectrequired
leadIdobjectrequired
teamIdobjectrequired
templateIdobjectrequired
status"backlog" | "in_progress" | "completed" | "cancelled"required
cancellationCategoryobjectrequired
cancellationReasonstringrequired
cancelledAtstringrequired
cancelledByUserIdobjectrequired
priorityobjectrequired
visionVersionobjectrequired
visionPathstringrequired
strategyVersionStampobjectrequired
prdstringrequired
prototypesobjectrequired
aiSynthesisobjectrequired
plannedStartstringrequired
plannedDurationDaysobjectrequired
dueDatestringrequired
isHardDeadlinebooleanrequired
categoryIdobjectrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/opportunities/{id}/apply-prd-template' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "title": "string",
    "number": 0,
    "estimatedCost": "string",
    "costEstimatorId": null,
    "leadId": null,
    "teamId": null,
    "templateId": null,
    "status": "backlog",
    "cancellationCategory": null,
    "cancellationReason": "string",
    "cancelledAt": "string",
    "cancelledByUserId": null,
    "priority": null,
    "visionVersion": null,
    "visionPath": "string",
    "strategyVersionStamp": null,
    "prd": "string",
    "prototypes": null,
    "aiSynthesis": null,
    "plannedStart": "string",
    "plannedDurationDays": null,
    "dueDate": "string",
    "isHardDeadline": true,
    "categoryId": null,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/opportunities/scoring-criteria

List the org's scoring criteria

The org's scorecard criteria (name, weight, invert, order) — the inputs every opportunity scorecard is scored against. Positive active weights are normalized decimal shares that sum to 1 (the Settings surface shows the same values as percentages totaling 100%); a newly added zero-weight criterion is allocation-neutral. Read-only on the wire, and a pure read: defining criteria is a workspace-settings act gated on scoring_criteria:manage and kept in-app, so an org that has never configured scoring answers with an empty list rather than being seeded by your GET.

Parameters
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
includeArchivedqueryoptional
Include archived criteria (kept for historical scores)
Returns · 200 — List the org's scoring criteria
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
namestringrequired
weightnumberrequired
invertbooleanrequired
positionintegerrequired
archivedAtstringrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/opportunities/scoring-criteria' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "name": "string",
      "weight": 0,
      "invert": true,
      "position": 0,
      "archivedAt": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/opportunities/{id}/phases

List an opportunity's delivery phases

An opportunity's phases in delivery order. A phase is a milestone, not work: it carries a title, an owner, and one target date, and it spawns no task. Its band on the plan runs from the previous phase's target to its own, and is open ended when it has none. taskCount and doneCount count only leaf tasks - work with no live children - because a task with children is a container and counting both would report the same work twice; cancelled and duplicate work is left out of the ratio entirely, since it can never complete. Set a task's phase with update_task.

Parameters
idpath · stringrequired
id path parameter
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
Returns · 200 — List an opportunity's delivery phases
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
positionintegerrequired
titlestringrequired
targetDatestringrequired
ownerUserIdobjectrequired
taskCountintegerrequired
doneCountintegerrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/opportunities/{id}/phases' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "position": 0,
      "title": "string",
      "targetDate": "string",
      "ownerUserId": null,
      "taskCount": 0,
      "doneCount": 0
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/opportunities/{id}/phases

Add a delivery phase to an opportunity

Append a phase to an opportunity's delivery arc. A phase is a milestone, not work: a title, one optional target date, an optional owner. It spawns no task. Phases do not require a template - an opportunity that never ran one can still have them. New phases land last; use reorder_opportunity_phases to place one.

Parameters
idpath · stringrequired
id path parameter
Request body · required
titlestringrequired
targetDateobjectoptional
ownerUserIdobjectoptional
Returns · 201 — Add a delivery phase to an opportunity
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
positionintegerrequired
titlestringrequired
targetDatestringrequired
ownerUserIdobjectrequired
taskCountintegerrequired
doneCountintegerrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/opportunities/{id}/phases' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "position": 0,
    "title": "string",
    "targetDate": "string",
    "ownerUserId": null,
    "taskCount": 0,
    "doneCount": 0
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/opportunities/{id}/unphased-task-count

Count an opportunity's unphased work

How many of an opportunity's top level tasks no phase claims. Work is never hidden by being unphased - it is its own group at the end of the arc - so this is what says whether that group exists at all. Counts top level tasks only, for the same reason list_opportunity_phases counts leaves: a container and its children are one piece of work, not two.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Count an opportunity's unphased work
oktruerequired
dataobjectrequired
Show child attributes ›
countintegerrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/opportunities/{id}/unphased-task-count' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "count": 0
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/opportunities/phases/{fromPhaseId}/handoff

Write the handoff note out of a finished phase

Post the handoff note a finished phase owes its successor. It lands as an update on the opportunity, so it reads in the same stream as everything else the team said about the work, and it closes the pending handoff on whichever phase was waiting on this one. An empty note is a no-op: the note is encouraged, never required, and skipping leaves the phase's pending handoff open rather than posting a hollow update.

Parameters
fromPhaseIdpath · stringrequired
fromPhaseId path parameter
Request body · required
notestringrequired
What the next owner needs to know
Returns · 200 — Write the handoff note out of a finished phase
oktruerequired
dataobjectrequired
Show child attributes ›
updateIdobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/opportunities/phases/{fromPhaseId}/handoff' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "updateId": null
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
PATCH/api/v1/opportunities/phases/{phaseId}

Rename, re-date or re-own a phase

Change a phase's title, target date or owner. Sending a null target date makes the phase open ended, which means the band after it can no longer be anchored. Use list_opportunity_phases for phase ids.

Parameters
phaseIdpath · stringrequired
phaseId path parameter
Request body · required
titlestringoptional
targetDateobjectoptional
ownerUserIdobjectoptional
Returns · 200 — Rename, re-date or re-own a phase
oktruerequired
dataobjectrequired
Show child attributes ›
oktruerequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
PATCH request
curl -X PATCH 'https://www.telos-app.com/api/v1/opportunities/phases/{phaseId}' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "ok": true
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
DELETE/api/v1/opportunities/phases/{phaseId}

Remove a phase

Delete a phase. The work filed under it is not deleted: those tasks become unphased and stay on the opportunity. Remaining phases close the gap so the arc stays contiguous.

Parameters
phaseIdpath · stringrequired
phaseId path parameter
Returns · 200 — Remove a phase
oktruerequired
dataobjectrequired
Show child attributes ›
oktruerequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
DELETE request
curl -X DELETE 'https://www.telos-app.com/api/v1/opportunities/phases/{phaseId}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "ok": true
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/opportunities/{id}/reorder-phases

Reorder an opportunity's phases

Set the delivery order of every phase at once. The list must name each of the opportunity's phases exactly once: a partial order would strand whatever it left out at a position it no longer owns. Order decides the bands, because a phase's band runs from the previous phase's target date to its own.

Parameters
idpath · stringrequired
id path parameter
Request body · required
orderedIdsstring<uuid>[]required
Returns · 200 — Reorder an opportunity's phases
oktruerequired
dataobjectrequired
Show child attributes ›
oktruerequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/opportunities/{id}/reorder-phases' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "ok": true
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
Resource

Tasks

GET/api/v1/tasks/planned-work-summary

Summarise planned work

Coverage of the planned work in one window: how much of it carries an explicit estimate, a planning window, an opportunity tie, and current source data. Estimate values are totalled per team and per unit and are never blended across either.

Returns · 200 — Summarise planned work
oktruerequired
dataobjectrequired
Show child attributes ›
itemCountintegerrequired
coverageobjectrequired
Show child attributes ›
estimateobjectrequired
Show child attributes ›
coveredintegerrequired
totalintegerrequired
scheduleobjectrequired
Show child attributes ›
coveredintegerrequired
totalintegerrequired
alignmentobjectrequired
Show child attributes ›
coveredintegerrequired
totalintegerrequired
freshnessobjectrequired
Show child attributes ›
coveredintegerrequired
totalintegerrequired
teamsobject[]required
Show child attributes ›
telosTeamIdobjectrequired
coverageobjectrequired
Show child attributes ›
estimateobjectrequired
Show child attributes ›
coveredintegerrequired
totalintegerrequired
scheduleobjectrequired
Show child attributes ›
coveredintegerrequired
totalintegerrequired
alignmentobjectrequired
Show child attributes ›
coveredintegerrequired
totalintegerrequired
freshnessobjectrequired
Show child attributes ›
coveredintegerrequired
totalintegerrequired
explicitEstimateTotalsobject[]required
Show child attributes ›
unit"minutes" | "points" | "original_time" | "unknown"required
valuenumberrequired
itemCountintegerrequired
mixedUnitsbooleanrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/tasks/planned-work-summary' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "itemCount": 0,
    "coverage": {
      "estimate": {
        "covered": 0,
        "total": 0
      },
      "schedule": {
        "covered": 0,
        "total": 0
      },
      "alignment": {
        "covered": 0,
        "total": 0
      },
      "freshness": {
        "covered": 0,
        "total": 0
      }
    },
    "teams": [
      {
        "telosTeamId": null,
        "coverage": {
          "estimate": {
            "covered": 0,
            "total": 0
          },
          "schedule": {
            "covered": 0,
            "total": 0
          },
          "alignment": {
            "covered": 0,
            "total": 0
          },
          "freshness": {
            "covered": 0,
            "total": 0
          }
        },
        "explicitEstimateTotals": [
          {
            "unit": "minutes",
            "value": 0,
            "itemCount": 0
          }
        ],
        "mixedUnits": true
      }
    ]
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/tasks/planned-work-gaps

Get planned work gaps

The grouped queue of what is missing from the planned-work read model: unestimated, unscheduled, unteamed and unaligned work, teams mixing estimate units, and source work whose binding has stopped converging. Each group names why it changes the calculation and where to fix it.

Returns · 200 — Get planned work gaps
oktruerequired
dataobjectrequired
Show child attributes ›
scanTruncatedbooleanrequired
groupsobject[]required
Show child attributes ›
group"unestimated" | "unscheduled" | "no_team" | "no_opportunity" | "mixed_units_in_team" | "stale_or_paused_source" | "source_outside_team_selection" | "unbound_source_work_not_inventoried"required
titlestringrequired
countobjectrequired
truncatedbooleanrequired
whyItChangesTheCalculationstringrequired
ownerRolestringrequired
editSurfacestringrequired
telosCanWritebooleanrequired
rowsobject[]required
Show child attributes ›
source"telos" | "linear" | "jira"required
sourceItemIdstringrequired
telosTaskIdstring<uuid>optional
telosTeamIdstring<uuid>optional
missingstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/tasks/planned-work-gaps' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "scanTruncated": true,
    "groups": [
      {
        "group": "unestimated",
        "title": "string",
        "count": null,
        "truncated": true,
        "whyItChangesTheCalculation": "string",
        "ownerRole": "string",
        "editSurface": "string",
        "telosCanWrite": true,
        "rows": [
          {
            "source": "telos",
            "sourceItemId": "string",
            "telosTaskId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
            "telosTeamId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
            "missing": "string"
          }
        ]
      }
    ]
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/tasks

List tasks

List tasks with cursor pagination. Optionally filter by opportunity, stable lifecycle status, concrete statusId, priority, team, owner, or to work that no cycle holds yet.

Parameters
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
opportunityIdquery · string<uuid>optional
Opportunity UUID filter
statusquery · stringoptional
Task status filter
statusIdquery · string<uuid>optional
Concrete workspace status UUID filter
priorityquery · stringoptional
Task priority filter
teamIdquery · string<uuid>optional
Team UUID filter
ownerUserIdquery · string<uuid>optional
Owner UUID filter. Pass your own user id (whoami) for 'my assignments'
noCyclequeryoptional
Only work bound to no cycle: the pool a cycle is planned from
Returns · 200 — List tasks
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
opportunityIdobjectrequired
teamIdobjectrequired
ownerUserIdobjectrequired
parentTaskIdobjectrequired
subtaskPositionobjectrequired
templateIdobjectrequired
categoryIdobjectrequired
titlestringrequired
prefixstringrequired
numberintegerrequired
descriptionstringrequired
contentstringrequired
status"backlog" | "todo" | "in_progress" | "completed" | "cancelled" | "duplicate"required
statusIdobjectrequired
completedAtstringrequired
priority"low" | "medium" | "high" | "urgent"required
visionPathstringrequired
estimateMinutesobjectrequired
estimateUnitobjectrequired
phaseInstanceIdobjectrequired
onboardingStepInstanceIdobjectrequired
phaseIdobjectrequired
plannedStartstringrequired
plannedDurationDaysobjectrequired
dueDatestringrequired
isHardDeadlinebooleanrequired
cycleIdobjectrequired
cycleBoundAtstringrequired
cycleRolloverCountintegerrequired
cycleRolloverCountIsLowerBoundbooleanrequired
queuePositionintegerrequired
recurrenceIdobjectrequired
createdByUserIdobjectrequired
createdAtstringrequired
updatedAtstringrequired
statusNamestringoptional
statusColorstringoptional
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/tasks' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "opportunityId": null,
      "teamId": null,
      "ownerUserId": null,
      "parentTaskId": null,
      "subtaskPosition": null,
      "templateId": null,
      "categoryId": null,
      "title": "string",
      "prefix": "string",
      "number": 0,
      "description": "string",
      "content": "string",
      "status": "backlog",
      "statusId": null,
      "completedAt": "string",
      "priority": "low",
      "visionPath": "string",
      "estimateMinutes": null,
      "estimateUnit": null,
      "phaseInstanceId": null,
      "onboardingStepInstanceId": null,
      "phaseId": null,
      "plannedStart": "string",
      "plannedDurationDays": null,
      "dueDate": "string",
      "isHardDeadline": true,
      "cycleId": null,
      "cycleBoundAt": "string",
      "cycleRolloverCount": 0,
      "cycleRolloverCountIsLowerBound": true,
      "queuePosition": 0,
      "recurrenceId": null,
      "createdByUserId": null,
      "createdAt": "string",
      "updatedAt": "string",
      "statusName": "string",
      "statusColor": "string"
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/tasks

Create a task

Create a task using the stable lifecycle status, optionally refined by a concrete workspace statusId (which wins). The task may attach to an opportunity or stand alone. Optionally seed subtasks, owner, team, category, template, and tags in the same call.

Request body · required
titlestringrequired
descriptionstringoptional
contentstringoptional
status"backlog" | "todo" | "in_progress" | "completed" | "cancelled" | "duplicate"optional
statusIdstring<uuid>optional
priority"low" | "medium" | "high" | "urgent"optional
opportunityIdstring<uuid>optional
phaseIdobjectoptional
teamIdobjectoptional
ownerIdobjectoptional
categoryIdobjectoptional
parentTaskIdstring<uuid>optional
subtaskPositionobjectoptional
Position among the parent's subtasks
subtasksobject[]optional
Show child attributes ›
titlestringrequired
ownerIdobjectoptional
positionintegeroptional
dueDatestring<date-time>optional
templateIdstring<uuid>optional
onboardingStepInstanceIdstring<uuid>optional
estimateMinutesobjectoptional
Estimate in minutes
estimateUnitobjectoptional
dueDatestring<date-time>optional
tagIdsstring<uuid>[]optional
patternPromotionobjectoptional
Show child attributes ›
patternIdstring<uuid>required
insightIdsstring<uuid>[]required
confirmedRepostringoptional
Repository to dispatch an agent owner against, when prompted
Returns · 201 — Create a task
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
opportunityIdobjectrequired
teamIdobjectrequired
ownerUserIdobjectrequired
parentTaskIdobjectrequired
subtaskPositionobjectrequired
templateIdobjectrequired
categoryIdobjectrequired
titlestringrequired
prefixstringrequired
numberintegerrequired
descriptionstringrequired
contentstringrequired
status"backlog" | "todo" | "in_progress" | "completed" | "cancelled" | "duplicate"required
statusIdobjectrequired
completedAtstringrequired
priority"low" | "medium" | "high" | "urgent"required
visionPathstringrequired
estimateMinutesobjectrequired
estimateUnitobjectrequired
phaseInstanceIdobjectrequired
onboardingStepInstanceIdobjectrequired
phaseIdobjectrequired
plannedStartstringrequired
plannedDurationDaysobjectrequired
dueDatestringrequired
isHardDeadlinebooleanrequired
cycleIdobjectrequired
cycleBoundAtstringrequired
cycleRolloverCountintegerrequired
cycleRolloverCountIsLowerBoundbooleanrequired
queuePositionintegerrequired
recurrenceIdobjectrequired
createdByUserIdobjectrequired
createdAtstringrequired
updatedAtstringrequired
statusNamestringoptional
statusColorstringoptional
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/tasks' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "opportunityId": null,
    "teamId": null,
    "ownerUserId": null,
    "parentTaskId": null,
    "subtaskPosition": null,
    "templateId": null,
    "categoryId": null,
    "title": "string",
    "prefix": "string",
    "number": 0,
    "description": "string",
    "content": "string",
    "status": "backlog",
    "statusId": null,
    "completedAt": "string",
    "priority": "low",
    "visionPath": "string",
    "estimateMinutes": null,
    "estimateUnit": null,
    "phaseInstanceId": null,
    "onboardingStepInstanceId": null,
    "phaseId": null,
    "plannedStart": "string",
    "plannedDurationDays": null,
    "dueDate": "string",
    "isHardDeadline": true,
    "cycleId": null,
    "cycleBoundAt": "string",
    "cycleRolloverCount": 0,
    "cycleRolloverCountIsLowerBound": true,
    "queuePosition": 0,
    "recurrenceId": null,
    "createdByUserId": null,
    "createdAt": "string",
    "updatedAt": "string",
    "statusName": "string",
    "statusColor": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/tasks/{id}

Get a task

Get a specific task by id.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Get a task
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
opportunityIdobjectrequired
teamIdobjectrequired
ownerUserIdobjectrequired
parentTaskIdobjectrequired
subtaskPositionobjectrequired
templateIdobjectrequired
categoryIdobjectrequired
titlestringrequired
prefixstringrequired
numberintegerrequired
descriptionstringrequired
contentstringrequired
status"backlog" | "todo" | "in_progress" | "completed" | "cancelled" | "duplicate"required
statusIdobjectrequired
completedAtstringrequired
priority"low" | "medium" | "high" | "urgent"required
visionPathstringrequired
estimateMinutesobjectrequired
estimateUnitobjectrequired
phaseInstanceIdobjectrequired
onboardingStepInstanceIdobjectrequired
phaseIdobjectrequired
plannedStartstringrequired
plannedDurationDaysobjectrequired
dueDatestringrequired
isHardDeadlinebooleanrequired
cycleIdobjectrequired
cycleBoundAtstringrequired
cycleRolloverCountintegerrequired
cycleRolloverCountIsLowerBoundbooleanrequired
queuePositionintegerrequired
recurrenceIdobjectrequired
createdByUserIdobjectrequired
createdAtstringrequired
updatedAtstringrequired
statusNamestringoptional
statusColorstringoptional
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/tasks/{id}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "opportunityId": null,
    "teamId": null,
    "ownerUserId": null,
    "parentTaskId": null,
    "subtaskPosition": null,
    "templateId": null,
    "categoryId": null,
    "title": "string",
    "prefix": "string",
    "number": 0,
    "description": "string",
    "content": "string",
    "status": "backlog",
    "statusId": null,
    "completedAt": "string",
    "priority": "low",
    "visionPath": "string",
    "estimateMinutes": null,
    "estimateUnit": null,
    "phaseInstanceId": null,
    "onboardingStepInstanceId": null,
    "phaseId": null,
    "plannedStart": "string",
    "plannedDurationDays": null,
    "dueDate": "string",
    "isHardDeadline": true,
    "cycleId": null,
    "cycleBoundAt": "string",
    "cycleRolloverCount": 0,
    "cycleRolloverCountIsLowerBound": true,
    "queuePosition": 0,
    "recurrenceId": null,
    "createdByUserId": null,
    "createdAt": "string",
    "updatedAt": "string",
    "statusName": "string",
    "statusColor": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
PATCH/api/v1/tasks/{id}

Update a task

Update a task's fields. Status remains the stable lifecycle vocabulary; statusId optionally selects a concrete workspace status and wins when both are sent. For a bare status move prefer set-status, which also auto-assigns ownerless work.

Parameters
idpath · stringrequired
id path parameter
Request body · required
titlestringoptional
descriptionstringoptional
contentstringoptional
status"backlog" | "todo" | "in_progress" | "completed" | "cancelled" | "duplicate"optional
statusIdstring<uuid>optional
priority"low" | "medium" | "high" | "urgent"optional
opportunityIdobjectoptional
phaseIdobjectoptional
teamIdobjectoptional
templateIdstring<uuid>optional
categoryIdobjectoptional
estimateMinutesobjectoptional
Estimate in minutes; null clears it
estimateUnitobjectoptional
dueDateobjectoptional
tagIdsstring<uuid>[]optional
Replace the task's whole tag set; omit to leave tags alone
Returns · 200 — Update a task
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
opportunityIdobjectrequired
teamIdobjectrequired
ownerUserIdobjectrequired
parentTaskIdobjectrequired
subtaskPositionobjectrequired
templateIdobjectrequired
categoryIdobjectrequired
titlestringrequired
prefixstringrequired
numberintegerrequired
descriptionstringrequired
contentstringrequired
status"backlog" | "todo" | "in_progress" | "completed" | "cancelled" | "duplicate"required
statusIdobjectrequired
completedAtstringrequired
priority"low" | "medium" | "high" | "urgent"required
visionPathstringrequired
estimateMinutesobjectrequired
estimateUnitobjectrequired
phaseInstanceIdobjectrequired
onboardingStepInstanceIdobjectrequired
phaseIdobjectrequired
plannedStartstringrequired
plannedDurationDaysobjectrequired
dueDatestringrequired
isHardDeadlinebooleanrequired
cycleIdobjectrequired
cycleBoundAtstringrequired
cycleRolloverCountintegerrequired
cycleRolloverCountIsLowerBoundbooleanrequired
queuePositionintegerrequired
recurrenceIdobjectrequired
createdByUserIdobjectrequired
createdAtstringrequired
updatedAtstringrequired
statusNamestringoptional
statusColorstringoptional
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
PATCH request
curl -X PATCH 'https://www.telos-app.com/api/v1/tasks/{id}' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "opportunityId": null,
    "teamId": null,
    "ownerUserId": null,
    "parentTaskId": null,
    "subtaskPosition": null,
    "templateId": null,
    "categoryId": null,
    "title": "string",
    "prefix": "string",
    "number": 0,
    "description": "string",
    "content": "string",
    "status": "backlog",
    "statusId": null,
    "completedAt": "string",
    "priority": "low",
    "visionPath": "string",
    "estimateMinutes": null,
    "estimateUnit": null,
    "phaseInstanceId": null,
    "onboardingStepInstanceId": null,
    "phaseId": null,
    "plannedStart": "string",
    "plannedDurationDays": null,
    "dueDate": "string",
    "isHardDeadline": true,
    "cycleId": null,
    "cycleBoundAt": "string",
    "cycleRolloverCount": 0,
    "cycleRolloverCountIsLowerBound": true,
    "queuePosition": 0,
    "recurrenceId": null,
    "createdByUserId": null,
    "createdAt": "string",
    "updatedAt": "string",
    "statusName": "string",
    "statusColor": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
DELETE/api/v1/tasks/{id}

Delete a task

Permanently delete a task. Its time entries, tags, checklist items, and insight links go with it, and its dependency edges are cleared; any subtasks are detached and survive as standalone tasks. To retire work without losing the record, set its status to cancelled instead.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Delete a task
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
deletedtruerequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
DELETE request
curl -X DELETE 'https://www.telos-app.com/api/v1/tasks/{id}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "deleted": true
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/tasks/{id}/post-update

Post a development update

Post one development update for this task. It appears in Development Updates and reaches every customer linked through the task's insights.

Parameters
idpath · stringrequired
id path parameter
Request body · required
bodystringrequired
Returns · 200 — Post a development update
oktruerequired
dataobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/tasks/{id}/post-update' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": null,
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/tasks/{id}/updates

List development updates

List development updates posted on this task.

Parameters
idpath · stringrequired
id path parameter
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
Returns · 200 — List development updates
oktruerequired
dataobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/tasks/{id}/updates' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": null,
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/tasks/{id}/set-status

Set a task's status

Set a task's stable lifecycle status, optionally refined by a concrete workspace statusId which wins. Moving ownerless work to a todo/in_progress status assigns the caller.

Parameters
idpath · stringrequired
id path parameter
Request body · required
status"backlog" | "todo" | "in_progress" | "completed" | "cancelled" | "duplicate"required
statusIdstring<uuid>optional
Returns · 200 — Set a task's status
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
opportunityIdobjectrequired
teamIdobjectrequired
ownerUserIdobjectrequired
parentTaskIdobjectrequired
subtaskPositionobjectrequired
templateIdobjectrequired
categoryIdobjectrequired
titlestringrequired
prefixstringrequired
numberintegerrequired
descriptionstringrequired
contentstringrequired
status"backlog" | "todo" | "in_progress" | "completed" | "cancelled" | "duplicate"required
statusIdobjectrequired
completedAtstringrequired
priority"low" | "medium" | "high" | "urgent"required
visionPathstringrequired
estimateMinutesobjectrequired
estimateUnitobjectrequired
phaseInstanceIdobjectrequired
onboardingStepInstanceIdobjectrequired
phaseIdobjectrequired
plannedStartstringrequired
plannedDurationDaysobjectrequired
dueDatestringrequired
isHardDeadlinebooleanrequired
cycleIdobjectrequired
cycleBoundAtstringrequired
cycleRolloverCountintegerrequired
cycleRolloverCountIsLowerBoundbooleanrequired
queuePositionintegerrequired
recurrenceIdobjectrequired
createdByUserIdobjectrequired
createdAtstringrequired
updatedAtstringrequired
statusNamestringoptional
statusColorstringoptional
autoAssignedOwnerstring<uuid>optional
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/tasks/{id}/set-status' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "opportunityId": null,
    "teamId": null,
    "ownerUserId": null,
    "parentTaskId": null,
    "subtaskPosition": null,
    "templateId": null,
    "categoryId": null,
    "title": "string",
    "prefix": "string",
    "number": 0,
    "description": "string",
    "content": "string",
    "status": "backlog",
    "statusId": null,
    "completedAt": "string",
    "priority": "low",
    "visionPath": "string",
    "estimateMinutes": null,
    "estimateUnit": null,
    "phaseInstanceId": null,
    "onboardingStepInstanceId": null,
    "phaseId": null,
    "plannedStart": "string",
    "plannedDurationDays": null,
    "dueDate": "string",
    "isHardDeadline": true,
    "cycleId": null,
    "cycleBoundAt": "string",
    "cycleRolloverCount": 0,
    "cycleRolloverCountIsLowerBound": true,
    "queuePosition": 0,
    "recurrenceId": null,
    "createdByUserId": null,
    "createdAt": "string",
    "updatedAt": "string",
    "statusName": "string",
    "statusColor": "string",
    "autoAssignedOwner": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/tasks/{id}/set-owner

Set a task's owner

Assign the single accountable owner, or pass null to unassign. Reassigning away from an agent owner cancels its in-flight run; assigning an agent owner dispatches a new one, and confirmedRepo answers the repository prompt that dispatch raises when the target repo is ambiguous.

Parameters
idpath · stringrequired
id path parameter
Request body · required
ownerUserIdobjectrequired
New owner's user UUID, or null to leave the task unassigned
confirmedRepostringoptional
Repository to dispatch an agent owner against, when prompted
Returns · 200 — Set a task's owner
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
opportunityIdobjectrequired
teamIdobjectrequired
ownerUserIdobjectrequired
parentTaskIdobjectrequired
subtaskPositionobjectrequired
templateIdobjectrequired
categoryIdobjectrequired
titlestringrequired
prefixstringrequired
numberintegerrequired
descriptionstringrequired
contentstringrequired
status"backlog" | "todo" | "in_progress" | "completed" | "cancelled" | "duplicate"required
statusIdobjectrequired
completedAtstringrequired
priority"low" | "medium" | "high" | "urgent"required
visionPathstringrequired
estimateMinutesobjectrequired
estimateUnitobjectrequired
phaseInstanceIdobjectrequired
onboardingStepInstanceIdobjectrequired
phaseIdobjectrequired
plannedStartstringrequired
plannedDurationDaysobjectrequired
dueDatestringrequired
isHardDeadlinebooleanrequired
cycleIdobjectrequired
cycleBoundAtstringrequired
cycleRolloverCountintegerrequired
cycleRolloverCountIsLowerBoundbooleanrequired
queuePositionintegerrequired
recurrenceIdobjectrequired
createdByUserIdobjectrequired
createdAtstringrequired
updatedAtstringrequired
statusNamestringoptional
statusColorstringoptional
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/tasks/{id}/set-owner' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "opportunityId": null,
    "teamId": null,
    "ownerUserId": null,
    "parentTaskId": null,
    "subtaskPosition": null,
    "templateId": null,
    "categoryId": null,
    "title": "string",
    "prefix": "string",
    "number": 0,
    "description": "string",
    "content": "string",
    "status": "backlog",
    "statusId": null,
    "completedAt": "string",
    "priority": "low",
    "visionPath": "string",
    "estimateMinutes": null,
    "estimateUnit": null,
    "phaseInstanceId": null,
    "onboardingStepInstanceId": null,
    "phaseId": null,
    "plannedStart": "string",
    "plannedDurationDays": null,
    "dueDate": "string",
    "isHardDeadline": true,
    "cycleId": null,
    "cycleBoundAt": "string",
    "cycleRolloverCount": 0,
    "cycleRolloverCountIsLowerBound": true,
    "queuePosition": 0,
    "recurrenceId": null,
    "createdByUserId": null,
    "createdAt": "string",
    "updatedAt": "string",
    "statusName": "string",
    "statusColor": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/tasks/{id}/assign-cycle

Preview assigning a task to a cycle

Return the proposed planning move and blast-radius impact for assigning this task to a cycle. This does not write; submit the returned move through the planning commit step to apply it, or call move-cycle to preview and apply in one step.

Parameters
idpath · stringrequired
id path parameter
Request body · required
cycleIdstring<uuid>required
Cycle UUID
Returns · 200 — Preview assigning a task to a cycle
oktruerequired
dataobjectrequired
Show child attributes ›
moveobjectrequired
Show child attributes ›
itemKind"task"required
itemIdstring<uuid>required
plannedStartstring<date>required
durationDaysintegerrequired
impactobjectrequired
Show child attributes ›
scheduleobject[]required
strategyobject[]required
clientobject[]required
promisesobject[]required
Show child attributes ›
taskIdstring<uuid>required
taskRefstringrequired
taskTitlestringrequired
fromCycleIdstring<uuid>required
fromCycleNumberintegerrequired
fromCycleNamestringrequired
fromTeamLabelstringrequired
insightIdstring<uuid>required
customerIdstring<uuid>required
customerNamestringrequired
customerNumberintegerrequired
customerLogoUrlstringrequired
deadlinestringrequired
moscowobjectrequired
toCycleIdobjectrequired
toCycleNumberobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/tasks/{id}/assign-cycle' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "move": {
      "itemKind": "task",
      "itemId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "plannedStart": "string",
      "durationDays": 0
    },
    "impact": {
      "schedule": [
        null
      ],
      "strategy": [
        null
      ],
      "client": [
        null
      ],
      "promises": [
        {
          "taskId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
          "taskRef": "string",
          "taskTitle": "string",
          "fromCycleId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
          "fromCycleNumber": 0,
          "fromCycleName": "string",
          "fromTeamLabel": "string",
          "insightId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
          "customerId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
          "customerName": "string",
          "customerNumber": 0,
          "customerLogoUrl": "string",
          "deadline": "string",
          "moscow": null,
          "toCycleId": null,
          "toCycleNumber": null
        }
      ]
    }
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/tasks/{id}/move-cycle

Move a task into a cycle

Assign a task to a cycle and apply the move, the write assign-cycle only previews. A move that takes live work out of a started cycle a customer promise rides on is refused with PROMISE_BREAKS, and the error carries the breaking {taskId, insightId} pairs: send them back as acknowledgedBreaks to proceed, with announceToCustomers to post the change to each affected customer.

Parameters
idpath · stringrequired
id path parameter
Request body · required
cycleIdstring<uuid>required
Cycle UUID to move the task into
acknowledgedBreaksobject[]optional
The {taskId, insightId} pairs a prior PROMISE_BREAKS refusal returned
Show child attributes ›
taskIdstring<uuid>required
insightIdstring<uuid>required
announceToCustomersobjectoptional
Post the schedule change to each acknowledged customer's activity log
Returns · 200 — Move a task into a cycle
oktruerequired
dataobjectrequired
Show child attributes ›
moveobjectrequired
Show child attributes ›
itemKind"task"required
itemIdstring<uuid>required
plannedStartstring<date>required
durationDaysintegerrequired
promiseBreaksintegerrequired
announcedintegerrequired
announceFailedintegerrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/tasks/{id}/move-cycle' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "move": {
      "itemKind": "task",
      "itemId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "plannedStart": "string",
      "durationDays": 0
    },
    "promiseBreaks": 0,
    "announced": 0,
    "announceFailed": 0
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/tasks/count-by-status

Count tasks per lifecycle status

True totals for the six stable lifecycle status types under the same filters `list` takes. Custom named statuses deliberately roll up to their parent type, preserving the aggregate answer to 'how much work is in flight'.

Returns · 200 — Count tasks per lifecycle status
oktruerequired
dataobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/tasks/count-by-status' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {},
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/tasks/{ref}/attach-session

Pin a coding session to a task

Attach the coding session working this task, so the engineer can resume it later (the task page offers `claude --resume <sessionId>`) and model usage can be attributed. Idempotent per (provider, sessionId, task); call again with inputTokens/outputTokens/costCents totals to report usage — the stored session updates in place. A session attached to several tasks is several refs, each carrying the session's full totals, so spend double-counts until aggregation dedupes by session.

Parameters
refpath · stringrequired
ref path parameter
Request body · required
providerstringrequired
Session provider slug, e.g. "claude-code"
sessionIdstringrequired
The provider's session id
modelstringoptional
Model id used in the session
inputTokensobjectoptional
Session input-token total
outputTokensobjectoptional
Session output-token total
costCentsobjectoptional
Estimated session cost, cents
Returns · 200 — Pin a coding session to a task
oktruerequired
dataobjectrequired
Show child attributes ›
taskIdstring<uuid>required
createdbooleanrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/tasks/{ref}/attach-session' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "taskId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "created": true
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/tasks/{id}/time-in-status

Time a task has spent in each status

Wall-clock totals per workflow status, folded from the task's status-transition ledger. One row per concrete status the task has visited (named custom statuses stay distinct; rows with no resolvable status fall back to the lifecycle type), with `current` marking the status still accruing. Imported history is only as complete as the source provided.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Time a task has spent in each status
oktruerequired
dataobject[]required
Show child attributes ›
type"backlog" | "todo" | "in_progress" | "completed" | "cancelled" | "duplicate"required
statusIdobjectrequired
statusNamestringrequired
totalMsintegerrequired
currentbooleanrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/tasks/{id}/time-in-status' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "type": "backlog",
      "statusId": null,
      "statusName": "string",
      "totalMs": 0,
      "current": true
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/tasks/{ref}/context

Get a task's full context bundle

Get everything needed to act on a task in one call: the task spec, its parent opportunity and PRD, the customer(s), comments, linked insights, the active template step, and any linked PRs. Sections you lack the read capability for (e.g. the parent opportunity, customers, insights) come back null. Pass the task ref (e.g. TF-24).

Parameters
refpath · stringrequired
ref path parameter
Returns · 200 — Get a task's full context bundle
oktruerequired
dataobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/tasks/{ref}/context' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": null,
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
Resource

Recurring Tasks

GET/api/v1/recurring-tasks

List recurring tasks

List recurring-task definitions with cursor pagination: each one's schedule (human-readable cadence + next occurrence), team, owner, and template. These are the definitions a background sweep materializes into real tasks; use list to see the tasks they produced.

Parameters
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
Returns · 200 — List recurring tasks
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
teamIdstring<uuid>required
namestringrequired
rrulestringrequired
dtstartstringrequired
tzidstringrequired
activebooleanrequired
titlestringrequired
descriptionstringrequired
contentstringrequired
priority"low" | "medium" | "high" | "urgent"required
ownerUserIdobjectrequired
categoryIdobjectrequired
templateIdobjectrequired
estimateMinutesobjectrequired
tagIdsobjectrequired
dueOffsetDaysintegerrequired
lastMaterializedOccurrencestringrequired
createdByUserIdobjectrequired
createdAtstringrequired
updatedAtstringrequired
teamobjectrequired
Show child attributes ›
idstring<uuid>required
namestringrequired
prefixstringrequired
ownerobjectrequired
cadenceTextstringrequired
nextOccurrencestringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/recurring-tasks' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "teamId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "name": "string",
      "rrule": "string",
      "dtstart": "string",
      "tzid": "string",
      "active": true,
      "title": "string",
      "description": "string",
      "content": "string",
      "priority": "low",
      "ownerUserId": null,
      "categoryId": null,
      "templateId": null,
      "estimateMinutes": null,
      "tagIds": null,
      "dueOffsetDays": 0,
      "lastMaterializedOccurrence": "string",
      "createdByUserId": null,
      "createdAt": "string",
      "updatedAt": "string",
      "team": {
        "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "name": "string",
        "prefix": "string"
      },
      "owner": null,
      "cadenceText": "string",
      "nextOccurrence": "string"
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/recurring-tasks

Create a recurring task

Define a recurring task: an RRULE schedule plus a task template. A background sweep creates one real task for the given team on every occurrence (status todo, due = occurrence + dueOffsetDays). This creates the DEFINITION, not a single task — use create for a one-off. rrule is an iCal RRULE string (e.g. 'FREQ=WEEKLY;BYDAY=MO'); dtstart/tzid default to now/UTC and it never backfills.

Request body · required
namestringrequired
Label for the recurring-task definition (not the task title)
teamIdstring<uuid>required
Team the generated tasks belong to
rrulestringrequired
iCal RRULE string, e.g. 'FREQ=WEEKLY;BYDAY=MO' or 'FREQ=MONTHLY;BYMONTHDAY=1'
dtstartstring<date-time>optional
Recurrence start (ISO 8601). Defaults to now
tzidstringoptional
IANA timezone the cadence reads in. Defaults to UTC
activeobjectoptional
Start the definition running
titlestringrequired
descriptionstringoptional
contentstringoptional
priority"low" | "medium" | "high" | "urgent"optional
ownerUserIdstring<uuid>required
Required. Owns every task this definition generates.
categoryIdobjectoptional
templateIdobjectoptional
estimateMinutesobjectoptional
Estimate in minutes on each generated task
tagIdsstring<uuid>[]optional
dueOffsetDaysobjectoptional
Days after the occurrence the generated task is due
Returns · 201 — Create a recurring task
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
teamIdstring<uuid>required
namestringrequired
rrulestringrequired
dtstartstringrequired
tzidstringrequired
activebooleanrequired
titlestringrequired
descriptionstringrequired
contentstringrequired
priority"low" | "medium" | "high" | "urgent"required
ownerUserIdobjectrequired
categoryIdobjectrequired
templateIdobjectrequired
estimateMinutesobjectrequired
tagIdsobjectrequired
dueOffsetDaysintegerrequired
lastMaterializedOccurrencestringrequired
createdByUserIdobjectrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/recurring-tasks' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "teamId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "name": "string",
    "rrule": "string",
    "dtstart": "string",
    "tzid": "string",
    "active": true,
    "title": "string",
    "description": "string",
    "content": "string",
    "priority": "low",
    "ownerUserId": null,
    "categoryId": null,
    "templateId": null,
    "estimateMinutes": null,
    "tagIds": null,
    "dueOffsetDays": 0,
    "lastMaterializedOccurrence": "string",
    "createdByUserId": null,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/recurring-tasks/{id}

Get a recurring task

Get a recurring-task definition by id: the stored row (rrule, template, active flag). The human-readable cadence, next occurrence, team and owner are list-only.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Get a recurring task
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
teamIdstring<uuid>required
namestringrequired
rrulestringrequired
dtstartstringrequired
tzidstringrequired
activebooleanrequired
titlestringrequired
descriptionstringrequired
contentstringrequired
priority"low" | "medium" | "high" | "urgent"required
ownerUserIdobjectrequired
categoryIdobjectrequired
templateIdobjectrequired
estimateMinutesobjectrequired
tagIdsobjectrequired
dueOffsetDaysintegerrequired
lastMaterializedOccurrencestringrequired
createdByUserIdobjectrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/recurring-tasks/{id}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "teamId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "name": "string",
    "rrule": "string",
    "dtstart": "string",
    "tzid": "string",
    "active": true,
    "title": "string",
    "description": "string",
    "content": "string",
    "priority": "low",
    "ownerUserId": null,
    "categoryId": null,
    "templateId": null,
    "estimateMinutes": null,
    "tagIds": null,
    "dueOffsetDays": 0,
    "lastMaterializedOccurrence": "string",
    "createdByUserId": null,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
PATCH/api/v1/recurring-tasks/{id}

Update a recurring task

Update a definition's schedule, template, or active flag. Editing the schedule recomputes forward from now, never retroactively.

Parameters
idpath · stringrequired
id path parameter
Request body · required
namestringoptional
Label for the recurring-task definition (not the task title)
teamIdstring<uuid>optional
Team the generated tasks belong to
rrulestringoptional
iCal RRULE string, e.g. 'FREQ=WEEKLY;BYDAY=MO' or 'FREQ=MONTHLY;BYMONTHDAY=1'
dtstartstring<date-time>optional
Recurrence start (ISO 8601). Defaults to now
tzidstringoptional
IANA timezone the cadence reads in. Defaults to UTC
activeobjectoptional
true resumes, false pauses
titlestringoptional
descriptionstringoptional
contentstringoptional
priority"low" | "medium" | "high" | "urgent"optional
ownerUserIdstring<uuid>optional
Required. Owns every task this definition generates.
categoryIdobjectoptional
templateIdobjectoptional
estimateMinutesobjectoptional
Estimate in minutes on each generated task
tagIdsstring<uuid>[]optional
dueOffsetDaysobjectoptional
Days after the occurrence the generated task is due
Returns · 200 — Update a recurring task
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
teamIdstring<uuid>required
namestringrequired
rrulestringrequired
dtstartstringrequired
tzidstringrequired
activebooleanrequired
titlestringrequired
descriptionstringrequired
contentstringrequired
priority"low" | "medium" | "high" | "urgent"required
ownerUserIdobjectrequired
categoryIdobjectrequired
templateIdobjectrequired
estimateMinutesobjectrequired
tagIdsobjectrequired
dueOffsetDaysintegerrequired
lastMaterializedOccurrencestringrequired
createdByUserIdobjectrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
PATCH request
curl -X PATCH 'https://www.telos-app.com/api/v1/recurring-tasks/{id}' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "teamId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "name": "string",
    "rrule": "string",
    "dtstart": "string",
    "tzid": "string",
    "active": true,
    "title": "string",
    "description": "string",
    "content": "string",
    "priority": "low",
    "ownerUserId": null,
    "categoryId": null,
    "templateId": null,
    "estimateMinutes": null,
    "tagIds": null,
    "dueOffsetDays": 0,
    "lastMaterializedOccurrence": "string",
    "createdByUserId": null,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
DELETE/api/v1/recurring-tasks/{id}

Delete a recurring task

Delete a recurring-task definition. Tasks it already created stay; no new ones are generated.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Delete a recurring task
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
DELETE request
curl -X DELETE 'https://www.telos-app.com/api/v1/recurring-tasks/{id}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/recurring-tasks/{id}/set-active

Pause or resume a recurring task

Pause or resume a recurring-task definition. Paused definitions stop materializing tasks; resuming never backfills the paused gap.

Parameters
idpath · stringrequired
id path parameter
Request body · required
activeobjectrequired
true to resume, false to pause
Returns · 200 — Pause or resume a recurring task
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
teamIdstring<uuid>required
namestringrequired
rrulestringrequired
dtstartstringrequired
tzidstringrequired
activebooleanrequired
titlestringrequired
descriptionstringrequired
contentstringrequired
priority"low" | "medium" | "high" | "urgent"required
ownerUserIdobjectrequired
categoryIdobjectrequired
templateIdobjectrequired
estimateMinutesobjectrequired
tagIdsobjectrequired
dueOffsetDaysintegerrequired
lastMaterializedOccurrencestringrequired
createdByUserIdobjectrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/recurring-tasks/{id}/set-active' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "teamId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "name": "string",
    "rrule": "string",
    "dtstart": "string",
    "tzid": "string",
    "active": true,
    "title": "string",
    "description": "string",
    "content": "string",
    "priority": "low",
    "ownerUserId": null,
    "categoryId": null,
    "templateId": null,
    "estimateMinutes": null,
    "tagIds": null,
    "dueOffsetDays": 0,
    "lastMaterializedOccurrence": "string",
    "createdByUserId": null,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
Resource

Customers

GET/api/v1/customers

List customers

List customers with cursor pagination. Optionally filter by status.

Parameters
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
statusquery · stringoptional
Customer status filter
ownerIdquery · string<uuid>optional
Owner (DRI) user UUID filter; pair with whoami to list your own accounts
Returns · 200 — List customers
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
namestringrequired
numberintegerrequired
logoUrlobjectrequired
logoFileIdobjectrequired
websiteobjectrequired
contentstringrequired
arrstringrequired
status"prospect" | "onboarding" | "pilot" | "live" | "churned" | "lost"required
healthobjectrequired
healthChangedAtstringrequired
ownerIdobjectrequired
onboardingTemplateIdobjectrequired
customerSincestringrequired
billingSourceOrgIdobjectrequired
lastReviewedAtstringrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/customers' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "name": "string",
      "number": 0,
      "logoUrl": null,
      "logoFileId": null,
      "website": null,
      "content": "string",
      "arr": "string",
      "status": "prospect",
      "health": null,
      "healthChangedAt": "string",
      "ownerId": null,
      "onboardingTemplateId": null,
      "customerSince": "string",
      "billingSourceOrgId": null,
      "lastReviewedAt": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/customers

Create a customer

Create a customer account (name plus optional profile, owner, ARR, and lifecycle status; status defaults to prospect).

Request body · required
namestringrequired
logoUrlobjectoptional
websiteobjectoptional
contentstringoptional
status"prospect" | "onboarding" | "pilot" | "live" | "churned" | "lost"optional
ownerIdstring<uuid>optional
arrstringoptional
customerSinceobjectoptional
ISO 8601 date or datetime
Returns · 201 — Create a customer
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
namestringrequired
numberintegerrequired
logoUrlobjectrequired
logoFileIdobjectrequired
websiteobjectrequired
contentstringrequired
arrstringrequired
status"prospect" | "onboarding" | "pilot" | "live" | "churned" | "lost"required
healthobjectrequired
healthChangedAtstringrequired
ownerIdobjectrequired
onboardingTemplateIdobjectrequired
customerSincestringrequired
billingSourceOrgIdobjectrequired
lastReviewedAtstringrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/customers' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "name": "string",
    "number": 0,
    "logoUrl": null,
    "logoFileId": null,
    "website": null,
    "content": "string",
    "arr": "string",
    "status": "prospect",
    "health": null,
    "healthChangedAt": "string",
    "ownerId": null,
    "onboardingTemplateId": null,
    "customerSince": "string",
    "billingSourceOrgId": null,
    "lastReviewedAt": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/customers/{id}

Get a customer

Get a customer by UUID or by ref (e.g. CUS-12).

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Get a customer
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
namestringrequired
numberintegerrequired
logoUrlobjectrequired
logoFileIdobjectrequired
websiteobjectrequired
contentstringrequired
arrstringrequired
status"prospect" | "onboarding" | "pilot" | "live" | "churned" | "lost"required
healthobjectrequired
healthChangedAtstringrequired
ownerIdobjectrequired
onboardingTemplateIdobjectrequired
customerSincestringrequired
billingSourceOrgIdobjectrequired
lastReviewedAtstringrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/customers/{id}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "name": "string",
    "number": 0,
    "logoUrl": null,
    "logoFileId": null,
    "website": null,
    "content": "string",
    "arr": "string",
    "status": "prospect",
    "health": null,
    "healthChangedAt": "string",
    "ownerId": null,
    "onboardingTemplateId": null,
    "customerSince": "string",
    "billingSourceOrgId": null,
    "lastReviewedAt": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
PATCH/api/v1/customers/{id}

Update a customer

Update a customer's profile, owner, ARR, health, or lifecycle status. Moving to churned/lost requires a reason (stored as an insight rooted at the customer); moving to onboarding activates the org's default onboarding template.

Parameters
idpath · stringrequired
id path parameter
Request body · required
namestringoptional
logoUrlobjectoptional
logoFileIdobjectoptional
websiteobjectoptional
contentstringoptional
status"prospect" | "onboarding" | "pilot" | "live" | "churned" | "lost"optional
health"healthy" | "at_risk" | "critical"optional
ownerIdobjectoptional
arrobjectoptional
customerSinceobjectoptional
reasonstringoptional
Returns · 200 — Update a customer
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
namestringrequired
numberintegerrequired
logoUrlobjectrequired
logoFileIdobjectrequired
websiteobjectrequired
contentstringrequired
arrstringrequired
status"prospect" | "onboarding" | "pilot" | "live" | "churned" | "lost"required
healthobjectrequired
healthChangedAtstringrequired
ownerIdobjectrequired
onboardingTemplateIdobjectrequired
customerSincestringrequired
billingSourceOrgIdobjectrequired
lastReviewedAtstringrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
PATCH request
curl -X PATCH 'https://www.telos-app.com/api/v1/customers/{id}' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "name": "string",
    "number": 0,
    "logoUrl": null,
    "logoFileId": null,
    "website": null,
    "content": "string",
    "arr": "string",
    "status": "prospect",
    "health": null,
    "healthChangedAt": "string",
    "ownerId": null,
    "onboardingTemplateId": null,
    "customerSince": "string",
    "billingSourceOrgId": null,
    "lastReviewedAt": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
DELETE/api/v1/customers/{id}

Delete a customer

Hard-delete an account and its insights. Contacts, events, reviews, updates, and opportunity links go with it; linked opportunities survive.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Delete a customer
oktruerequired
dataobjectrequired
Show child attributes ›
deletedtruerequired
idstring<uuid>required
namestringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
DELETE request
curl -X DELETE 'https://www.telos-app.com/api/v1/customers/{id}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "deleted": true,
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "name": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/customers/{id}/contacts

List a customer's contacts

List the named people on a customer account, primary contact first, then newest. Use a contact's id to attribute an insight to the person who said it.

Parameters
idpath · stringrequired
id path parameter
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
Returns · 200 — List a customer's contacts
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
customerIdstring<uuid>required
namestringrequired
titleobjectrequired
role"economic_buyer" | "champion" | "decision_maker" | "technical" | "end_user" | "executive" | "other"required
emailobjectrequired
phoneobjectrequired
notesstringrequired
isPrimarybooleanrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/customers/{id}/contacts' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "customerId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "name": "string",
      "title": null,
      "role": "economic_buyer",
      "email": null,
      "phone": null,
      "notes": "string",
      "isPrimary": true,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/customers/{id}/contacts

Add a contact to a customer

Add a named person to a customer account (name plus optional title, role, email, phone, and notes). Marking the contact primary demotes the account's existing primary.

Parameters
idpath · stringrequired
id path parameter
Request body · required
namestringrequired
titlestringoptional
role"economic_buyer" | "champion" | "decision_maker" | "technical" | "end_user" | "executive" | "other"optional
emailobjectoptional
phonestringoptional
notesstringoptional
isPrimaryobjectoptional
Make this the account's primary contact
Returns · 201 — Add a contact to a customer
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
customerIdstring<uuid>required
namestringrequired
titleobjectrequired
role"economic_buyer" | "champion" | "decision_maker" | "technical" | "end_user" | "executive" | "other"required
emailobjectrequired
phoneobjectrequired
notesstringrequired
isPrimarybooleanrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/customers/{id}/contacts' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "customerId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "name": "string",
    "title": null,
    "role": "economic_buyer",
    "email": null,
    "phone": null,
    "notes": "string",
    "isPrimary": true,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
PATCH/api/v1/customers/{id}/contacts/{contactId}

Update a customer contact

Update a contact's details. Promoting a contact to primary demotes the account's existing primary.

Parameters
idpath · stringrequired
id path parameter
contactIdpath · stringrequired
contactId path parameter
Request body · required
namestringoptional
titleobjectoptional
role"economic_buyer" | "champion" | "decision_maker" | "technical" | "end_user" | "executive" | "other"optional
emailobjectoptional
phoneobjectoptional
notesobjectoptional
isPrimaryobjectoptional
Make this the account's primary contact
Returns · 200 — Update a customer contact
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
customerIdstring<uuid>required
namestringrequired
titleobjectrequired
role"economic_buyer" | "champion" | "decision_maker" | "technical" | "end_user" | "executive" | "other"required
emailobjectrequired
phoneobjectrequired
notesstringrequired
isPrimarybooleanrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
PATCH request
curl -X PATCH 'https://www.telos-app.com/api/v1/customers/{id}/contacts/{contactId}' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "customerId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "name": "string",
    "title": null,
    "role": "economic_buyer",
    "email": null,
    "phone": null,
    "notes": "string",
    "isPrimary": true,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
DELETE/api/v1/customers/{id}/contacts/{contactId}

Delete a customer contact

Remove a contact from a customer account. Insights attributed to the contact survive and fall back to the customer as their demand root.

Parameters
idpath · stringrequired
id path parameter
contactIdpath · stringrequired
contactId path parameter
Returns · 200 — Delete a customer contact
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
deletedtruerequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
DELETE request
curl -X DELETE 'https://www.telos-app.com/api/v1/customers/{id}/contacts/{contactId}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "deleted": true
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/customers/{id}/opportunities

List a customer's linked opportunities

The opportunities tied to this account, most-active first. `stepInstanceId` is the onboarding milestone the link is pinned to (null when unpinned).

Parameters
idpath · stringrequired
id path parameter
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
Returns · 200 — List a customer's linked opportunities
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
titlestringrequired
numberintegerrequired
statestringrequired
leadNamestringrequired
stepInstanceIdobjectrequired
updatedAtstringrequired
linkedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/customers/{id}/opportunities' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "title": "string",
      "number": 0,
      "state": "string",
      "leadName": "string",
      "stepInstanceId": null,
      "updatedAt": "string",
      "linkedAt": "string"
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/customers/{id}/opportunities

Link an opportunity to a customer

Tie an opportunity to an account and set where it sits in the account's onboarding: the call is idempotent and always leaves the link pinned to `stepInstanceId`, so omitting it (or passing null) unpins. Re-call to re-pin.

Parameters
idpath · stringrequired
id path parameter
Request body · required
opportunityIdstring<uuid>required
Opportunity UUID
stepInstanceIdobjectoptional
Returns · 201 — Link an opportunity to a customer
oktruerequired
dataobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/customers/{id}/opportunities' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": null,
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
DELETE/api/v1/customers/{id}/opportunities/{opportunityId}

Unlink an opportunity from a customer

Remove the tie between an account and an opportunity. The opportunity itself survives.

Parameters
idpath · stringrequired
id path parameter
opportunityIdpath · stringrequired
opportunityId path parameter
Returns · 200 — Unlink an opportunity from a customer
oktruerequired
dataobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
DELETE request
curl -X DELETE 'https://www.telos-app.com/api/v1/customers/{id}/opportunities/{opportunityId}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": null,
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/customers/{id}/updates

List a customer's update feed

The account's update stream, newest first: notes posted on the customer plus progress posted on any opportunity the account reaches (linked or through its insights).

Parameters
idpath · stringrequired
id path parameter
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
Returns · 200 — List a customer's update feed
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
authorIdstring<uuid>required
authorNamestringrequired
authorAvatarUrlstringrequired
bodystringrequired
customerIdobjectrequired
opportunityIdobjectrequired
opportunityTitlestringrequired
opportunityNumberobjectrequired
createdAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/customers/{id}/updates' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "authorId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "authorName": "string",
      "authorAvatarUrl": "string",
      "body": "string",
      "customerId": null,
      "opportunityId": null,
      "opportunityTitle": "string",
      "opportunityNumber": null,
      "createdAt": "string"
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/customers/{id}/updates

Post a customer update

Post an account note to the customer's feed, authored by the key's user. It notifies the account's subscribers and mirrors into the org's customer-updates channel. Opportunity progress goes through post_opportunity_update instead.

Parameters
idpath · stringrequired
id path parameter
Request body · required
bodystringrequired
The update text
Returns · 201 — Post a customer update
oktruerequired
dataobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/customers/{id}/updates' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": null,
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/customers/commitments

List every dated client promise

Every dated promise made to a client across the org (an open insight carrying a deadline), soonest first so overdue leads, resolved to the work delivering it. `atRisk` flags a near deadline with nothing in flight.

Parameters
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
Returns · 200 — List every dated client promise
oktruerequired
dataobject[]required
Show child attributes ›
insightIdstring<uuid>required
customerIdstring<uuid>required
customerNamestringrequired
customerRefstringrequired
titlestringrequired
verbatimstringrequired
moscowstringrequired
deadlinestringrequired
overduebooleanrequired
atRiskbooleanrequired
workobject[]required
Show child attributes ›
kind"opportunity" | "task"required
refstringrequired
titlestringrequired
inFlightbooleanrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/customers/commitments' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "insightId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "customerId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "customerName": "string",
      "customerRef": "string",
      "title": "string",
      "verbatim": "string",
      "moscow": "string",
      "deadline": "string",
      "overdue": true,
      "atRisk": true,
      "work": [
        {
          "kind": "opportunity",
          "ref": "string",
          "title": "string",
          "inFlight": true
        }
      ]
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/customers/{id}/arr

List a customer's ARR history

The account's ARR level series oldest first: each point is 'ARR was this much from this date'. Deltas are derived between consecutive points, never stored.

Parameters
idpath · stringrequired
id path parameter
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
Returns · 200 — List a customer's ARR history
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
customerIdstring<uuid>required
atstringrequired
arrnumberrequired
notestringrequired
actorNamestringrequired
actorAvatarUrlstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/customers/{id}/arr' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "customerId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "at": "string",
      "arr": 0,
      "note": "string",
      "actorName": "string",
      "actorAvatarUrl": "string"
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/customers/{id}/arr

Record an ARR level for a customer

Record what the account's ARR was from a given date. A point dated at or after the latest recorded level also updates the account's current ARR; an earlier one only backfills history. Future dates are rejected: this records what happened, not forecasts.

Parameters
idpath · stringrequired
id path parameter
Request body · required
atobjectrequired
The date the level took effect
arrobjectrequired
ARR level from that date
notestringoptional
Why it changed
Returns · 201 — Record an ARR level for a customer
oktruerequired
dataobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/customers/{id}/arr' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": null,
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
DELETE/api/v1/customers/{id}/arr/{arrPointId}

Delete an ARR history point

Remove one point from the account's ARR series (typo repair). The account's current ARR is not recomputed.

Parameters
idpath · stringrequired
id path parameter
arrPointIdpath · stringrequired
arrPointId path parameter
Returns · 200 — Delete an ARR history point
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
deletedtruerequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
DELETE request
curl -X DELETE 'https://www.telos-app.com/api/v1/customers/{id}/arr/{arrPointId}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "deleted": true
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/customers/arr-summary

Org-wide ARR roll-up and movement

The portfolio view of revenue in one call: `stats` totals ARR and account count per lifecycle position (live, pilot, onboarding, prospect), and `waterfall` gives ARR gained/lost/net per month over the requested window, derived from the same level series.

Returns · 200 — Org-wide ARR roll-up and movement
oktruerequired
dataobjectrequired
Show child attributes ›
statsobjectrequired
Show child attributes ›
liveobjectrequired
Show child attributes ›
totalArrnumberrequired
customerCountintegerrequired
pilotobjectrequired
Show child attributes ›
totalArrnumberrequired
customerCountintegerrequired
onboardingobjectrequired
Show child attributes ›
totalArrnumberrequired
customerCountintegerrequired
prospectobjectrequired
Show child attributes ›
totalArrnumberrequired
customerCountintegerrequired
waterfallobjectrequired
Show child attributes ›
monthsobject[]required
Show child attributes ›
monthstringrequired
gainednumberrequired
lostnumberrequired
netnumberrequired
netTotalnumberrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/customers/arr-summary' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "stats": {
      "live": {
        "totalArr": 0,
        "customerCount": 0
      },
      "pilot": {
        "totalArr": 0,
        "customerCount": 0
      },
      "onboarding": {
        "totalArr": 0,
        "customerCount": 0
      },
      "prospect": {
        "totalArr": 0,
        "customerCount": 0
      }
    },
    "waterfall": {
      "months": [
        {
          "month": "string",
          "gained": 0,
          "lost": 0,
          "net": 0
        }
      ],
      "netTotal": 0
    }
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/customers/{id}/reviews

List a customer's stored reviews

The account's pre-meeting reviews, newest first: what the client had going on in each stored date window. Summaries only; read one with get_customer_review.

Parameters
idpath · stringrequired
id path parameter
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
Returns · 200 — List a customer's stored reviews
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
windowFromstringrequired
windowTostringrequired
createdAtstringrequired
createdByNamestringrequired
createdByAvatarUrlstringrequired
hasNarrativebooleanrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/customers/{id}/reviews' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "windowFrom": "string",
      "windowTo": "string",
      "createdAt": "string",
      "createdByName": "string",
      "createdByAvatarUrl": "string",
      "hasNarrative": true
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/customers/{id}/reviews

Generate a customer review

Build and store a review of everything that happened on the account between `from` and now: asks recorded, work shipped, updates posted, commitments missed. Writes an LLM narrative when the org has one configured; the digest stands on its own without it.

Parameters
idpath · stringrequired
id path parameter
Request body · required
fromobjectrequired
Window start; the window ends now
Returns · 201 — Generate a customer review
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
customerIdstring<uuid>required
windowFromstringrequired
windowTostringrequired
digestobjectrequired
narrativestringrequired
createdAtstringrequired
createdByNamestringrequired
createdByAvatarUrlstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/customers/{id}/reviews' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "customerId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "windowFrom": "string",
    "windowTo": "string",
    "digest": {},
    "narrative": "string",
    "createdAt": "string",
    "createdByName": "string",
    "createdByAvatarUrl": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/customers/{id}/reviews/{reviewId}

Get a stored customer review

One stored review in full: the digest (new asks, shipped work, updates, overdue commitments, delayed work, stuck asks) plus the generated narrative when there is one.

Parameters
idpath · stringrequired
id path parameter
reviewIdpath · stringrequired
reviewId path parameter
Returns · 200 — Get a stored customer review
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
customerIdstring<uuid>required
windowFromstringrequired
windowTostringrequired
digestobjectrequired
narrativestringrequired
createdAtstringrequired
createdByNamestringrequired
createdByAvatarUrlstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/customers/{id}/reviews/{reviewId}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "customerId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "windowFrom": "string",
    "windowTo": "string",
    "digest": {},
    "narrative": "string",
    "createdAt": "string",
    "createdByName": "string",
    "createdByAvatarUrl": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/customers/{id}/onboarding

Get a customer's onboarding state

The account's onboarding in one call: every milestone in order with the active one flagged, the ARR tranche each unlocks, and the work sitting on it (opportunities pinned to the milestone plus bespoke tasks). `hasOnboarding` is false when the account was never started.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Get a customer's onboarding state
oktruerequired
dataobjectrequired
Show child attributes ›
hasOnboardingbooleanrequired
stepsobject[]required
Show child attributes ›
stepInstanceIdstring<uuid>required
titlestringrequired
positionintegerrequired
currentbooleanrequired
arrUnlocknumberrequired
rowsobject[]required
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/customers/{id}/onboarding' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "hasOnboarding": true,
    "steps": [
      {
        "stepInstanceId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "title": "string",
        "position": 0,
        "current": true,
        "arrUnlock": 0,
        "rows": [
          {}
        ]
      }
    ]
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/customers/{id}/onboarding

Start or swap a customer's onboarding template

Put the account on an onboarding template. Starting seeds the milestones and moves a prospect to onboarding; passing a different templateId on an account that already started swaps it. Omitting templateId uses the org's default customer onboarding template.

Parameters
idpath · stringrequired
id path parameter
Request body · required
templateIdstring<uuid>optional
Onboarding template UUID; defaults to the org's customer default
Returns · 201 — Start or swap a customer's onboarding template
oktruerequired
dataobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/customers/{id}/onboarding' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": null,
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/customers/{id}/onboarding/advance

Move a customer to another onboarding milestone

Move the account to a milestone, naming it either by the account's own step instance (stepInstanceId) or by the template's template step (stepId). The move lands in the account's update feed so every stage change is on the record. This does not end onboarding: use complete_customer_onboarding for that.

Parameters
idpath · stringrequired
id path parameter
Request body · required
stepInstanceIdstring<uuid>optional
Onboarding milestone (template step instance) UUID
stepIdstring<uuid>optional
Template step UUID, resolved to this customer's milestone
messagestringoptional
Handoff note
markCompleteobjectoptional
Mark the milestone being left as completed
Returns · 200 — Move a customer to another onboarding milestone
oktruerequired
dataobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/customers/{id}/onboarding/advance' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": null,
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/customers/{id}/onboarding/complete

Complete a customer's onboarding and take the account live

End onboarding: lands the account on the template's Completed step, flips a prospect/onboarding/pilot account to live, stamps customerSince, and notifies subscribers. Never resurrects a churned or lost account.

Parameters
idpath · stringrequired
id path parameter
Request body · required
messagestringoptional
Go-live note
Returns · 200 — Complete a customer's onboarding and take the account live
oktruerequired
dataobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/customers/{id}/onboarding/complete' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": null,
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
PATCH/api/v1/customers/{id}/onboarding/steps/{stepInstanceId}

Update one of a customer's onboarding milestones

Set what a milestone owns: its DRI, the ARR tranche it unlocks on completion (null clears), and an existing task attached to it. Every field is optional; only what you pass is written. Attaching a task writes the task row, so passing taskId also requires task:update.

Parameters
idpath · stringrequired
id path parameter
stepInstanceIdpath · stringrequired
stepInstanceId path parameter
Request body · required
driUserIdstring<uuid>optional
New DRI user UUID
arrUnlockobjectoptional
ARR unlocked when the milestone completes; null clears it
taskIdstring<uuid>optional
Existing task to attach to this milestone
Returns · 200 — Update one of a customer's onboarding milestones
oktruerequired
dataobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
PATCH request
curl -X PATCH 'https://www.telos-app.com/api/v1/customers/{id}/onboarding/steps/{stepInstanceId}' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": null,
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/customers/{id}/onboarding/steps/{stepInstanceId}/work

Create work on a customer's onboarding milestone

Create a new work item as a go-live requirement on a milestone. kind 'task' is bespoke per-client work (data migration, training) and requires task:create; kind 'opportunity' is a product bet, created and pinned to the milestone, and requires opportunity:create. customer:create alone is not enough — the row lands in the work graph. Returns the new item's kind and id. To attach work that already exists, use update_customer_onboarding_step (tasks) or link_customer_opportunity.

Parameters
idpath · stringrequired
id path parameter
stepInstanceIdpath · stringrequired
stepInstanceId path parameter
Request body · required
kind"task" | "opportunity"required
Bespoke client work, or a product opportunity
titlestringrequired
Work item title
Returns · 201 — Create work on a customer's onboarding milestone
oktruerequired
dataobjectrequired
Show child attributes ›
kind"task" | "opportunity"required
idstring<uuid>required
titlestringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/customers/{id}/onboarding/steps/{stepInstanceId}/work' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "kind": "task",
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "title": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
Resource

Activities

GET/api/v1/activities

List an entity's activity

The activity log for one entity, newest first, with cursor pagination: who changed which field, from what to what, and when. Requires the read capability of the entity you are asking about. Read it before proposing a change so you know what already happened.

Parameters
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
entityTypequery · stringrequired
Entity type. One of: opportunity, task, customer, insight
entityIdquery · string<uuid>required
Entity UUID
Returns · 200 — List an entity's activity
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
kindstringrequired
actorIdstring<uuid>required
actorNamestringrequired
actorAvatarUrlstringrequired
sourcestringrequired
payloadobjectrequired
Show child attributes ›
changesobject[]optional
Show child attributes ›
fieldstringrequired
fromobjectrequired
toobjectrequired
fromNamestringoptional
toNamestringoptional
assigneeIdstring<uuid>optional
assigneeNamestringoptional
createdAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/activities' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "kind": "string",
      "actorId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "actorName": "string",
      "actorAvatarUrl": "string",
      "source": "string",
      "payload": {
        "changes": [
          {
            "field": "string",
            "from": null,
            "to": null,
            "fromName": "string",
            "toName": "string"
          }
        ],
        "assigneeId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "assigneeName": "string"
      },
      "createdAt": "string"
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
Resource

Agent Runs

GET/api/v1/agent-runs

List coding-agent runs

Coding-agent dispatch history with cursor pagination, newest first. Supply exactly one of taskId (one task's runs, with the repo and branch the agent worked in) or integrationId (one connector's runs, with each run's task ref). The field the other filter would have told you comes back null.

Parameters
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
taskIdquery · string<uuid>optional
List one task's runs
integrationIdquery · string<uuid>optional
List one integration's runs
Returns · 200 — List coding-agent runs
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
taskIdobjectrequired
taskRefstringrequired
taskTitlestringrequired
integrationIdobjectrequired
providerstringrequired
statusstringrequired
repoNamestringrequired
branchstringrequired
prUrlstringrequired
providerUrlstringrequired
summarystringrequired
errorstringrequired
createdAtstringrequired
startedAtstringrequired
finishedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/agent-runs' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "taskId": null,
      "taskRef": "string",
      "taskTitle": "string",
      "integrationId": null,
      "provider": "string",
      "status": "string",
      "repoName": "string",
      "branch": "string",
      "prUrl": "string",
      "providerUrl": "string",
      "summary": "string",
      "error": "string",
      "createdAt": "string",
      "startedAt": "string",
      "finishedAt": "string"
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/agent-runs/{id}/cancel

Cancel a coding-agent run

Stop an in-flight coding-agent run: the provider session is cancelled best-effort and the run lands in the terminal `cancelled` state with a summary. Cancelling an already-finished run returns it unchanged.

Parameters
idpath · stringrequired
id path parameter
Request body · required

Empty object.

Returns · 200 — Cancel a coding-agent run
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
taskIdobjectrequired
taskRefstringrequired
taskTitlestringrequired
integrationIdobjectrequired
providerstringrequired
statusstringrequired
repoNamestringrequired
branchstringrequired
prUrlstringrequired
providerUrlstringrequired
summarystringrequired
errorstringrequired
createdAtstringrequired
startedAtstringrequired
finishedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/agent-runs/{id}/cancel' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "taskId": null,
    "taskRef": "string",
    "taskTitle": "string",
    "integrationId": null,
    "provider": "string",
    "status": "string",
    "repoName": "string",
    "branch": "string",
    "prUrl": "string",
    "providerUrl": "string",
    "summary": "string",
    "error": "string",
    "createdAt": "string",
    "startedAt": "string",
    "finishedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
Resource

Categories

GET/api/v1/categories

List categories

List the org's categories in display order (used to group templates and to classify time entries).

Parameters
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
Returns · 200 — List categories
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
slugstringrequired
labelstringrequired
colorstringrequired
sortOrderintegerrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/categories' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "slug": "string",
      "label": "string",
      "color": "string",
      "sortOrder": 0,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/categories

Create a category

Create a category. The slug is derived from the label; color is a theme token or hex value.

Request body · required
labelstringrequired
colorstringrequired
sortOrderobjectoptional
Display position among the org's categories
Returns · 201 — Create a category
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
slugstringrequired
labelstringrequired
colorstringrequired
sortOrderintegerrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/categories' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "slug": "string",
    "label": "string",
    "color": "string",
    "sortOrder": 0,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/categories/{id}

Get a category

Get one category: its label, slug, color and sort order. Categories group tasks and opportunities and classify time entries; the system Bug and Incident categories are present in every org.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Get a category
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
slugstringrequired
labelstringrequired
colorstringrequired
sortOrderintegerrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/categories/{id}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "slug": "string",
    "label": "string",
    "color": "string",
    "sortOrder": 0,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
PATCH/api/v1/categories/{id}

Update a category

Update a category's label, color, or sort order. The slug never changes.

Parameters
idpath · stringrequired
id path parameter
Request body · required
labelstringoptional
colorstringoptional
sortOrderobjectoptional
Display position among the org's categories
Returns · 200 — Update a category
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
slugstringrequired
labelstringrequired
colorstringrequired
sortOrderintegerrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
PATCH request
curl -X PATCH 'https://www.telos-app.com/api/v1/categories/{id}' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "slug": "string",
    "label": "string",
    "color": "string",
    "sortOrder": 0,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
DELETE/api/v1/categories/{id}

Delete a category

Delete a category. The system Bug and Incident categories can't be deleted, nor can a category time entries still reference.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Delete a category
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
deletedtruerequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
DELETE request
curl -X DELETE 'https://www.telos-app.com/api/v1/categories/{id}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "deleted": true
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
Resource

Comments

GET/api/v1/comments

List comments

List a discussion thread, newest first, with cursor pagination. Pass entityType and entityId for an entity's top-level comments, or parentId for the replies threaded under one comment. Rows carry the author, reaction aggregate, and (for top-level rows) the reply count.

Parameters
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
entityTypequery · stringoptional
Entity the comments hang off (with entityId)
entityIdquery · string<uuid>optional
Entity UUID (with entityType)
parentIdquery · string<uuid>optional
Read this top-level comment's thread replies instead
Returns · 200 — List comments
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
authorIdstring<uuid>required
authorNamestringrequired
authorAvatarUrlstringrequired
bodystringrequired
kind"user" | "update" | "external"required
externalSourcestringrequired
editedAtstringrequired
createdAtstringrequired
replyCountintegerrequired
lastReplyAtstringrequired
reactionsobject[]required
Show child attributes ›
emojistringrequired
countintegerrequired
userIdsstring<uuid>[]required
userNamesstring[]required
hasMebooleanrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/comments' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "authorId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "authorName": "string",
      "authorAvatarUrl": "string",
      "body": "string",
      "kind": "user",
      "externalSource": "string",
      "editedAt": "string",
      "createdAt": "string",
      "replyCount": 0,
      "lastReplyAt": "string",
      "reactions": [
        {
          "emoji": "string",
          "count": 0,
          "userIds": [
            "01J9Z3F4S0Z9KMQ4N6PYZR7C5A"
          ],
          "userNames": [
            "string"
          ],
          "hasMe": true
        }
      ]
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/comments

Post a comment

Post a comment on a task or opportunity, authored by the key's user. It lands on the entity's discussion thread. For an opportunity status broadcast that flows into linked customers' feeds, use post_opportunity_update instead.

Request body · required
entityType"task" | "opportunity"required
entityIdstring<uuid>required
bodystringrequired
kind"user" | "update"optional
Returns · 201 — Post a comment
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
authorIdstring<uuid>required
entityTypestringrequired
entityIdstring<uuid>required
kindstringrequired
externalAuthorobjectrequired
externalSourceobjectrequired
bodystringrequired
parentIdobjectrequired
editedAtstringrequired
createdAtstringrequired
updateIdobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/comments' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "authorId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "entityType": "string",
    "entityId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "kind": "string",
    "externalAuthor": null,
    "externalSource": null,
    "body": "string",
    "parentId": null,
    "editedAt": "string",
    "createdAt": "string",
    "updateId": null
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
PATCH/api/v1/comments/{id}

Edit a comment

Edit one of your own comments; it is marked edited. Only the author may edit a comment, and comments ingested from an integration cannot be edited.

Parameters
idpath · stringrequired
id path parameter
Request body · required
bodystringrequired
Returns · 200 — Edit a comment
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
authorIdstring<uuid>required
entityTypestringrequired
entityIdstring<uuid>required
kindstringrequired
externalAuthorobjectrequired
externalSourceobjectrequired
bodystringrequired
parentIdobjectrequired
editedAtstringrequired
createdAtstringrequired
updateIdobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
PATCH request
curl -X PATCH 'https://www.telos-app.com/api/v1/comments/{id}' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "authorId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "entityType": "string",
    "entityId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "kind": "string",
    "externalAuthor": null,
    "externalSource": null,
    "body": "string",
    "parentId": null,
    "editedAt": "string",
    "createdAt": "string",
    "updateId": null
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
DELETE/api/v1/comments/{id}

Delete a comment

Delete one of your own comments. Its thread replies cascade with it, and their file attachments are swept. Only the author (or an org manager) may delete it.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Delete a comment
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
deletedtruerequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
DELETE request
curl -X DELETE 'https://www.telos-app.com/api/v1/comments/{id}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "deleted": true
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/comments/{id}/reactions

Add or remove your reaction to a comment

Set whether the authenticated user reacts to a comment with an emoji. Absolute, not a toggle: `on` is the state you want, so a retried call never silently removes the reaction it just added. Returns the comment's full reaction aggregate.

Parameters
idpath · stringrequired
id path parameter
Request body · required
emojistringrequired
Emoji to react with
onobjectrequired
true adds your reaction, false removes it
Returns · 200 — Add or remove your reaction to a comment
oktruerequired
dataobjectrequired
Show child attributes ›
commentIdstring<uuid>required
reactionsobject[]required
Show child attributes ›
emojistringrequired
countintegerrequired
userIdsstring<uuid>[]required
userNamesstring[]required
hasMebooleanrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/comments/{id}/reactions' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "commentId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "reactions": [
      {
        "emoji": "string",
        "count": 0,
        "userIds": [
          "01J9Z3F4S0Z9KMQ4N6PYZR7C5A"
        ],
        "userNames": [
          "string"
        ],
        "hasMe": true
      }
    ]
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
Resource

Cycle Config

PATCH/api/v1/cycle-config/default-estimate

Set the default estimate for unestimated work

Set the organisation-wide minutes counted for an unestimated task in cycle capacity, load and burnup math. It changes what every cycle's numbers mean, so it is workspace administration and requires cycle:manage.

Request body · required
defaultEstimateMinutesobjectrequired
Minutes an unestimated task counts for (1 to twenty workdays)
Returns · 200 — Set the default estimate for unestimated work
oktruerequired
dataobjectrequired
Show child attributes ›
defaultEstimateMinutesintegerrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
PATCH request
curl -X PATCH 'https://www.telos-app.com/api/v1/cycle-config/default-estimate' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "defaultEstimateMinutes": 0
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/cycle-config

Get cycle configuration

Get the organisation's cycle-planning configuration. Null means it has never been configured.

Returns · 200 — Get cycle configuration
oktruerequired
dataobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/cycle-config' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": null,
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
PATCH/api/v1/cycle-config

Configure cycle planning

Configure cycle planning for the organisation. Cycle configuration is workspace administration and requires cycle:manage.

Request body · required
enabledobjectrequired
Whether cycle planning is enabled for the organisation
mode"org" | "team"required
Whether cycles are organisation-wide or per enabled team
autoRolloverobjectrequired
Whether completed cycles automatically roll unfinished work forward
durationWeeksobjectrequired
Cycle duration in whole weeks (1–8)
cooldownWeeksobjectrequired
Whole-week gap between adjacent cycles (0–3)
upcomingCountobjectrequired
Number of active or future cycles to keep generated
startDatestringrequired
UTC calendar anchor for the organisation cycle grid
teamConfigsobject[]optional
Per-team cadence settings when mode is team
Show child attributes ›
teamIdstring<uuid>required
enabledobjectrequired
Boolean
autoRolloverobjectrequired
Boolean
durationWeeksobjectrequired
cooldownWeeksobjectrequired
upcomingCountobjectrequired
startDatestringrequired
UTC calendar anchor for this team's cycle grid
Returns · 200 — Configure cycle planning
oktruerequired
dataobjectrequired
Show child attributes ›
orgIdstring<uuid>required
enabledbooleanrequired
mode"org" | "team"required
autoRolloverbooleanrequired
durationWeeksintegerrequired
cooldownWeeksintegerrequired
upcomingCountintegerrequired
startDatestringrequired
createdAtstringrequired
updatedAtstringrequired
teamConfigsobject[]required
Show child attributes ›
teamIdstring<uuid>required
enabledbooleanrequired
autoRolloverbooleanrequired
durationWeeksintegerrequired
cooldownWeeksintegerrequired
upcomingCountintegerrequired
startDatestringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
PATCH request
curl -X PATCH 'https://www.telos-app.com/api/v1/cycle-config' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "enabled": true,
    "mode": "org",
    "autoRollover": true,
    "durationWeeks": 0,
    "cooldownWeeks": 0,
    "upcomingCount": 0,
    "startDate": "string",
    "createdAt": "string",
    "updatedAt": "string",
    "teamConfigs": [
      {
        "teamId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "enabled": true,
        "autoRollover": true,
        "durationWeeks": 0,
        "cooldownWeeks": 0,
        "upcomingCount": 0,
        "startDate": "string"
      }
    ]
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
Resource

Cycles

GET/api/v1/cycles

List cycles

List the organisation's retained cycle windows with cursor pagination. Reading never generates new windows.

Parameters
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
Returns · 200 — List cycles
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
scope"org" | "team"required
teamIdobjectrequired
teamLabelobjectrequired
numberintegerrequired
nameobjectrequired
goalstringrequired
startsAtstringrequired
endsAtstringrequired
committedAtstringrequired
digestVersionobjectrequired
digestobjectrequired
closedAtstringrequired
rolloverState"pending" | "running" | "done" | "skipped"required
rolloverStartedAtstringrequired
rolloverCompletedAtstringrequired
rolledOverCountobjectrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/cycles' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "scope": "org",
      "teamId": null,
      "teamLabel": null,
      "number": 0,
      "name": null,
      "goal": "string",
      "startsAt": "string",
      "endsAt": "string",
      "committedAt": "string",
      "digestVersion": null,
      "digest": null,
      "closedAt": "string",
      "rolloverState": "pending",
      "rolloverStartedAt": "string",
      "rolloverCompletedAt": "string",
      "rolledOverCount": null,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/cycles/{id}

Get a cycle

Get one cycle window and its lifecycle state.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Get a cycle
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
scope"org" | "team"required
teamIdobjectrequired
teamLabelobjectrequired
numberintegerrequired
nameobjectrequired
goalstringrequired
startsAtstringrequired
endsAtstringrequired
committedAtstringrequired
digestVersionobjectrequired
digestobjectrequired
closedAtstringrequired
rolloverState"pending" | "running" | "done" | "skipped"required
rolloverStartedAtstringrequired
rolloverCompletedAtstringrequired
rolledOverCountobjectrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/cycles/{id}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "scope": "org",
    "teamId": null,
    "teamLabel": null,
    "number": 0,
    "name": null,
    "goal": "string",
    "startsAt": "string",
    "endsAt": "string",
    "committedAt": "string",
    "digestVersion": null,
    "digest": null,
    "closedAt": "string",
    "rolloverState": "pending",
    "rolloverStartedAt": "string",
    "rolloverCompletedAt": "string",
    "rolledOverCount": null,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
PATCH/api/v1/cycles/{id}

Update a future cycle

Change the identity, grid, or half-open window of an open, uncommitted future cycle.

Parameters
idpath · stringrequired
id path parameter
Request body · required
nameobjectoptional
goalobjectoptional
startsAtstringoptional
endsAtstringoptional
scope"org" | "team"optional
teamIdobjectoptional
Returns · 200 — Update a future cycle
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
scope"org" | "team"required
teamIdobjectrequired
teamLabelobjectrequired
numberintegerrequired
nameobjectrequired
goalstringrequired
startsAtstringrequired
endsAtstringrequired
committedAtstringrequired
digestVersionobjectrequired
digestobjectrequired
closedAtstringrequired
rolloverState"pending" | "running" | "done" | "skipped"required
rolloverStartedAtstringrequired
rolloverCompletedAtstringrequired
rolledOverCountobjectrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
PATCH request
curl -X PATCH 'https://www.telos-app.com/api/v1/cycles/{id}' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "scope": "org",
    "teamId": null,
    "teamLabel": null,
    "number": 0,
    "name": null,
    "goal": "string",
    "startsAt": "string",
    "endsAt": "string",
    "committedAt": "string",
    "digestVersion": null,
    "digest": null,
    "closedAt": "string",
    "rolloverState": "pending",
    "rolloverStartedAt": "string",
    "rolloverCompletedAt": "string",
    "rolledOverCount": null,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
DELETE/api/v1/cycles/{id}

Delete an empty future cycle

Delete an open, uncommitted future cycle only when no task of any status references it.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Delete an empty future cycle
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
scope"org" | "team"required
teamIdobjectrequired
teamLabelobjectrequired
numberintegerrequired
nameobjectrequired
goalstringrequired
startsAtstringrequired
endsAtstringrequired
committedAtstringrequired
digestVersionobjectrequired
digestobjectrequired
closedAtstringrequired
rolloverState"pending" | "running" | "done" | "skipped"required
rolloverStartedAtstringrequired
rolloverCompletedAtstringrequired
rolledOverCountobjectrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
DELETE request
curl -X DELETE 'https://www.telos-app.com/api/v1/cycles/{id}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "scope": "org",
    "teamId": null,
    "teamLabel": null,
    "number": 0,
    "name": null,
    "goal": "string",
    "startsAt": "string",
    "endsAt": "string",
    "committedAt": "string",
    "digestVersion": null,
    "digest": null,
    "closedAt": "string",
    "rolloverState": "pending",
    "rolloverStartedAt": "string",
    "rolloverCompletedAt": "string",
    "rolledOverCount": null,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/cycles/grids

List the cycle grids

List the grids cycles are generated on: one row for the organisation in org mode, or one row per cycle-enabled team in team mode. Answers which teamId every other cycle read should be narrowed by.

Returns · 200 — List the cycle grids
oktruerequired
dataobjectrequired
Show child attributes ›
enabledbooleanrequired
modeobjectrequired
gridsobject[]required
Show child attributes ›
teamIdobjectrequired
teamLabelstringrequired
teamSlugstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/cycles/grids' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "enabled": true,
    "mode": null,
    "grids": [
      {
        "teamId": null,
        "teamLabel": "string",
        "teamSlug": "string"
      }
    ]
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/cycles/stats

List one grid's cycles with delivery stats

List one grid's cycle windows newest first, each decorated with derived delivery analytics: lifecycle status, capacity and committed days, scope, work added after start, work spilled out, work completed, success percentage, and the customer commitments falling due inside the window. Closed cycles read their frozen close-time digest, open ones read live bindings.

Parameters
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
teamIdqueryoptional
Team UUID of the grid to read; omit for the organisation grid
Returns · 200 — List one grid's cycles with delivery stats
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
scope"org" | "team"required
teamIdobjectrequired
teamLabelobjectrequired
numberintegerrequired
nameobjectrequired
goalstringrequired
startsAtstringrequired
endsAtstringrequired
committedAtstringrequired
digestVersionobjectrequired
digestobjectrequired
closedAtstringrequired
rolloverState"pending" | "running" | "done" | "skipped"required
rolloverStartedAtstringrequired
rolloverCompletedAtstringrequired
rolledOverCountobjectrequired
createdAtstringrequired
updatedAtstringrequired
status"completed" | "current" | "upcoming" | "planned"required
capacityDaysintegerrequired
scopeCountintegerrequired
addedCountobjectrequired
spilledCountobjectrequired
completedCountintegerrequired
successPctobjectrequired
commitmentsCountintegerrequired
committedDaysintegerrequired
plannedCountintegerrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/cycles/stats' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "scope": "org",
      "teamId": null,
      "teamLabel": null,
      "number": 0,
      "name": null,
      "goal": "string",
      "startsAt": "string",
      "endsAt": "string",
      "committedAt": "string",
      "digestVersion": null,
      "digest": null,
      "closedAt": "string",
      "rolloverState": "pending",
      "rolloverStartedAt": "string",
      "rolloverCompletedAt": "string",
      "rolledOverCount": null,
      "createdAt": "string",
      "updatedAt": "string",
      "status": "completed",
      "capacityDays": 0,
      "scopeCount": 0,
      "addedCount": null,
      "spilledCount": null,
      "completedCount": 0,
      "successPct": null,
      "commitmentsCount": 0,
      "committedDays": 0,
      "plannedCount": 0
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/cycles/by-number/{grid}/{number}

Get a cycle by grid and number

Resolve the cycle a grid numbers as N, the addressing the /cycles/{grid}/{number} deep links use. The grid is a team slug, or the literal 'org' for the organisation grid. Answers with the cycle plus its team slug and derived lifecycle status.

Parameters
gridpath · stringrequired
grid path parameter
numberpath · stringrequired
number path parameter
Returns · 200 — Get a cycle by grid and number
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
scope"org" | "team"required
teamIdobjectrequired
teamLabelobjectrequired
numberintegerrequired
nameobjectrequired
goalstringrequired
startsAtstringrequired
endsAtstringrequired
committedAtstringrequired
digestVersionobjectrequired
digestobjectrequired
closedAtstringrequired
rolloverState"pending" | "running" | "done" | "skipped"required
rolloverStartedAtstringrequired
rolloverCompletedAtstringrequired
rolledOverCountobjectrequired
createdAtstringrequired
updatedAtstringrequired
teamSlugstringrequired
status"completed" | "current" | "upcoming" | "planned"required
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/cycles/by-number/{grid}/{number}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "scope": "org",
    "teamId": null,
    "teamLabel": null,
    "number": 0,
    "name": null,
    "goal": "string",
    "startsAt": "string",
    "endsAt": "string",
    "committedAt": "string",
    "digestVersion": null,
    "digest": null,
    "closedAt": "string",
    "rolloverState": "pending",
    "rolloverStartedAt": "string",
    "rolloverCompletedAt": "string",
    "rolledOverCount": null,
    "createdAt": "string",
    "updatedAt": "string",
    "teamSlug": "string",
    "status": "completed"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/cycles/{id}/burnup

Get a cycle's burnup series

Get the daily cumulative scope and completed series across a cycle's window, in estimate days. Scope rises as work is bound after the start; completions land on their completion day, with post-window completions clamped onto the final point. Closed cycles read their frozen close-time digest.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Get a cycle's burnup series
oktruerequired
dataobjectrequired
Show child attributes ›
startsAtstringrequired
endsAtstringrequired
unit"days"required
pointsobject[]required
Show child attributes ›
datestringrequired
scopeDaysnumberrequired
completedDaysnumberrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/cycles/{id}/burnup' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "startsAt": "string",
    "endsAt": "string",
    "unit": "days",
    "points": [
      {
        "date": "string",
        "scopeDays": 0,
        "completedDays": 0
      }
    ]
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/cycles/{id}/breakdown

Break a cycle's work down by owner, priority and team

Group a cycle's member work by owner, by priority and by team, each with a count and a percentage of the cycle's scope. The composition summary; ask task list with a cycle filter for the rows themselves.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Break a cycle's work down by owner, priority and team
oktruerequired
dataobjectrequired
Show child attributes ›
scopeintegerrequired
assigneesobject[]required
Show child attributes ›
keystringrequired
labelstringrequired
avatarUrlstringrequired
countintegerrequired
pctOfScopenumberrequired
prioritiesobject[]required
Show child attributes ›
keystringrequired
labelstringrequired
avatarUrlstringrequired
countintegerrequired
pctOfScopenumberrequired
teamsobject[]required
Show child attributes ›
keystringrequired
labelstringrequired
avatarUrlstringrequired
countintegerrequired
pctOfScopenumberrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/cycles/{id}/breakdown' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "scope": 0,
    "assignees": [
      {
        "key": "string",
        "label": "string",
        "avatarUrl": "string",
        "count": 0,
        "pctOfScope": 0
      }
    ],
    "priorities": [
      {
        "key": "string",
        "label": "string",
        "avatarUrl": "string",
        "count": 0,
        "pctOfScope": 0
      }
    ],
    "teams": [
      {
        "key": "string",
        "label": "string",
        "avatarUrl": "string",
        "count": 0,
        "pctOfScope": 0
      }
    ]
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/cycles/options

Search cycles for a picker

A bounded, searchable window over every retained cycle, grouped by grid and newest window first, for building a cycle selector. Matches name or number. The answer carries the unbounded total, so a caller can tell a partial window from a complete one; cycle list is the paginated read that walks them all.

Returns · 200 — Search cycles for a picker
oktruerequired
dataobjectrequired
Show child attributes ›
dataobject[]required
Show child attributes ›
idstring<uuid>required
numberintegerrequired
namestringrequired
startsAtstringrequired
endsAtstringrequired
teamIdobjectrequired
teamNamestringrequired
isCurrentbooleanrequired
totalintegerrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/cycles/options' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "number": 0,
        "name": "string",
        "startsAt": "string",
        "endsAt": "string",
        "teamId": null,
        "teamName": "string",
        "isCurrent": true
      }
    ],
    "total": 0
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/cycles/impact-candidates

List the cycles work can still be assigned to

The active and future cycles of every enabled grid, current window first: the only windows a task may be assigned to. Narrow by teamId to one task's effective grid. Retained history is excluded by design and never displaces these rows.

Returns · 200 — List the cycles work can still be assigned to
oktruerequired
dataobjectrequired
Show child attributes ›
rowsobject[]required
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
scope"org" | "team"required
teamIdobjectrequired
teamLabelobjectrequired
numberintegerrequired
nameobjectrequired
goalstringrequired
startsAtstringrequired
endsAtstringrequired
committedAtstringrequired
digestVersionobjectrequired
digestobjectrequired
closedAtstringrequired
rolloverState"pending" | "running" | "done" | "skipped"required
rolloverStartedAtstringrequired
rolloverCompletedAtstringrequired
rolledOverCountobjectrequired
createdAtstringrequired
updatedAtstringrequired
totalintegerrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/cycles/impact-candidates' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "rows": [
      {
        "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "scope": "org",
        "teamId": null,
        "teamLabel": null,
        "number": 0,
        "name": null,
        "goal": "string",
        "startsAt": "string",
        "endsAt": "string",
        "committedAt": "string",
        "digestVersion": null,
        "digest": null,
        "closedAt": "string",
        "rolloverState": "pending",
        "rolloverStartedAt": "string",
        "rolloverCompletedAt": "string",
        "rolledOverCount": null,
        "createdAt": "string",
        "updatedAt": "string"
      }
    ],
    "total": 0
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/cycles/{id}/verdict

Get a cycle verdict

Get the immutable close-time verdict for a committed cycle, if it has closed.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Get a cycle verdict
oktruerequired
dataobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/cycles/{id}/verdict' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": null,
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/cycles/{id}/rollover

Roll over an ended cycle now

Explicitly move unfinished work from an ended cycle to its next window. This can resume a cycle parked because automatic rollover is off.

Parameters
idpath · stringrequired
id path parameter
Request body · required

Empty object.

Returns · 200 — Roll over an ended cycle now
oktruerequired
dataobjectrequired
Show child attributes ›
completedbooleanrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/cycles/{id}/rollover' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "completed": true
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/cycles/{id}/commit

Commit a cycle baseline

Capture the one-shot opening commitment digest for a cycle. The baseline cannot be replaced after commitment.

Parameters
idpath · stringrequired
id path parameter
Request body · required

Empty object.

Returns · 200 — Commit a cycle baseline
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
scope"org" | "team"required
teamIdobjectrequired
teamLabelobjectrequired
numberintegerrequired
nameobjectrequired
goalstringrequired
startsAtstringrequired
endsAtstringrequired
committedAtstringrequired
digestVersionobjectrequired
digestobjectrequired
closedAtstringrequired
rolloverState"pending" | "running" | "done" | "skipped"required
rolloverStartedAtstringrequired
rolloverCompletedAtstringrequired
rolledOverCountobjectrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/cycles/{id}/commit' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "scope": "org",
    "teamId": null,
    "teamLabel": null,
    "number": 0,
    "name": null,
    "goal": "string",
    "startsAt": "string",
    "endsAt": "string",
    "committedAt": "string",
    "digestVersion": null,
    "digest": null,
    "closedAt": "string",
    "rolloverState": "pending",
    "rolloverStartedAt": "string",
    "rolloverCompletedAt": "string",
    "rolledOverCount": null,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/cycles/{id}/commitments

List a cycle's customer commitments

List the customer promises falling due inside a cycle's window, attributed to its grid, with delivery coverage: delivered, covered, at risk (with breach days), or uncovered.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — List a cycle's customer commitments
oktruerequired
dataobjectrequired
Show child attributes ›
dataobject[]required
Show child attributes ›
insightIdstring<uuid>required
customerIdstring<uuid>required
customerNamestringrequired
customerLogoUrlstringrequired
verbatimstringrequired
moscowobjectrequired
deadlinestringrequired
statusstringrequired
state"delivered" | "covered" | "at_risk" | "uncovered"required
breachDaysintegerrequired
coveringRefstringrequired
coveringTitlestringrequired
coveringKindobjectrequired
totalintegerrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/cycles/{id}/commitments' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "data": [
      {
        "insightId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "customerId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "customerName": "string",
        "customerLogoUrl": "string",
        "verbatim": "string",
        "moscow": null,
        "deadline": "string",
        "status": "string",
        "state": "delivered",
        "breachDays": 0,
        "coveringRef": "string",
        "coveringTitle": "string",
        "coveringKind": null
      }
    ],
    "total": 0
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/cycles/commitments

List several cycles' customer commitments at once

Read the customer promises of up to twenty cycle windows in one call, each answering exactly what cycle commitments answers for that window: the promises falling due inside it, attributed to its grid, with delivery coverage. Ids outside the organisation are dropped rather than reported. For a planning horizon of cycle columns; ask cycle commitments for one window.

Returns · 200 — List several cycles' customer commitments at once
oktruerequired
dataobjectrequired
Show child attributes ›
cyclesobject[]required
Show child attributes ›
cycleIdstring<uuid>required
dataobject[]required
Show child attributes ›
insightIdstring<uuid>required
customerIdstring<uuid>required
customerNamestringrequired
customerLogoUrlstringrequired
verbatimstringrequired
moscowobjectrequired
deadlinestringrequired
statusstringrequired
state"delivered" | "covered" | "at_risk" | "uncovered"required
breachDaysintegerrequired
coveringRefstringrequired
coveringTitlestringrequired
coveringKindobjectrequired
totalintegerrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/cycles/commitments' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "cycles": [
      {
        "cycleId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "data": [
          {
            "insightId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
            "customerId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
            "customerName": "string",
            "customerLogoUrl": "string",
            "verbatim": "string",
            "moscow": null,
            "deadline": "string",
            "status": "string",
            "state": "delivered",
            "breachDays": 0,
            "coveringRef": "string",
            "coveringTitle": "string",
            "coveringKind": null
          }
        ],
        "total": 0
      }
    ]
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/cycles/{id}/load

Get a cycle's load per person

Break a cycle's live membership down by owner as assigned minutes against that person's capacity for the window: one workday per weekday, the unit estimates are written in. Unestimated work counts at the organisation default and unowned work answers in its own bucket. Everyone carrying work gets a row; the grid's idle members fill the remaining seats and the rest are counted in idleOmitted, so a large roster does not have to be paged. Completed members stay in the load because the window's capacity was spent on them.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Get a cycle's load per person
oktruerequired
dataobjectrequired
Show child attributes ›
unit"minutes"required
peopleobject[]required
Show child attributes ›
userIdstring<uuid>required
namestringrequired
avatarUrlstringrequired
assignedMinutesintegerrequired
capacityMinutesintegerrequired
unassignedMinutesintegerrequired
idleOmittedintegerrequired
capacityBasisobjectrequired
Show child attributes ›
businessDaysintegerrequired
minutesPerDayintegerrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/cycles/{id}/load' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "unit": "minutes",
    "people": [
      {
        "userId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "name": "string",
        "avatarUrl": "string",
        "assignedMinutes": 0,
        "capacityMinutes": 0
      }
    ],
    "unassignedMinutes": 0,
    "idleOmitted": 0,
    "capacityBasis": {
      "businessDays": 0,
      "minutesPerDay": 0
    }
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/cycles/load

Get several cycles' load per person at once

Read the per-person load of up to twenty cycle windows in one call, each answering exactly what cycle load answers for that window: assigned minutes by owner against that window's own capacity. Ids outside the organisation are dropped rather than reported. For a planning horizon of cycle columns; ask cycle load for one window.

Returns · 200 — Get several cycles' load per person at once
oktruerequired
dataobjectrequired
Show child attributes ›
cyclesobject[]required
Show child attributes ›
unit"minutes"required
peopleobject[]required
Show child attributes ›
userIdstring<uuid>required
namestringrequired
avatarUrlstringrequired
assignedMinutesintegerrequired
capacityMinutesintegerrequired
unassignedMinutesintegerrequired
idleOmittedintegerrequired
capacityBasisobjectrequired
Show child attributes ›
businessDaysintegerrequired
minutesPerDayintegerrequired
cycleIdstring<uuid>required
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/cycles/load' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "cycles": [
      {
        "unit": "minutes",
        "people": [
          {
            "userId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
            "name": "string",
            "avatarUrl": "string",
            "assignedMinutes": 0,
            "capacityMinutes": 0
          }
        ],
        "unassignedMinutes": 0,
        "idleOmitted": 0,
        "capacityBasis": {
          "businessDays": 0,
          "minutesPerDay": 0
        },
        "cycleId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A"
      }
    ]
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/cycles/{id}/events

List a cycle's ledger events

List the cycle's informational ledger, newest first: scope added after start, promises at risk on entry, promises moved out, and promises unfinished at close.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — List a cycle's ledger events
oktruerequired
dataobjectrequired
Show child attributes ›
dataobject[]required
Show child attributes ›
idstring<uuid>required
kind"scope_added" | "scope_moved" | "scope_removed" | "promise_at_risk_on_entry" | "promise_moved_out" | "promise_unfinished_at_close"required
taskIdobjectrequired
insightIdobjectrequired
actorobjectrequired
payloadobjectrequired
Show child attributes ›
taskRefstringoptional
taskTitlestringoptional
customerNamestringoptional
deadlinestringoptional
projectedEndstringoptional
toCycleNumberintegeroptional
createdAtstringrequired
totalintegerrequired
nextCursorobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/cycles/{id}/events' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "kind": "scope_added",
        "taskId": null,
        "insightId": null,
        "actor": null,
        "payload": {
          "taskRef": "string",
          "taskTitle": "string",
          "customerName": "string",
          "deadline": "string",
          "projectedEnd": "string",
          "toCycleNumber": 0
        },
        "createdAt": "string"
      }
    ],
    "total": 0,
    "nextCursor": null
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/cycles/{id}/impact

Get cycle impact

Preview the selected cycle's standing commitments, rollover effects, and cross-team collisions without mutating work.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Get cycle impact
oktruerequired
dataobjectrequired
Show child attributes ›
cycleobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
scope"org" | "team"required
teamIdobjectrequired
teamLabelobjectrequired
numberintegerrequired
nameobjectrequired
goalstringrequired
startsAtstringrequired
endsAtstringrequired
committedAtstringrequired
digestVersionobjectrequired
digestobjectrequired
closedAtstringrequired
rolloverState"pending" | "running" | "done" | "skipped"required
rolloverStartedAtstringrequired
rolloverCompletedAtstringrequired
rolledOverCountobjectrequired
createdAtstringrequired
updatedAtstringrequired
assignmentobjectrequired
standingobjectrequired
Show child attributes ›
objectivesobject[]required
Show child attributes ›
idstring<uuid>required
numberintegerrequired
titlestringrequired
statusstringrequired
deadlinestringrequired
breachedbooleanrequired
promisesobject[]required
Show child attributes ›
idstring<uuid>required
customerIdobjectrequired
moscowstringrequired
deadlinestringrequired
capacityobject[]required
Show child attributes ›
userIdstring<uuid>required
userNamestringrequired
assignedMinutesintegerrequired
availableMinutesintegerrequired
rolloverobjectrequired
Show child attributes ›
targetobjectrequired
movesobject[]required
Show child attributes ›
itemKind"task"required
itemIdstring<uuid>required
plannedStartstringrequired
durationDaysintegeroptional
impactobjectrequired
crossTeamobject[]required
Show child attributes ›
idstring<uuid>required
itemKind"task" | "opportunity"required
itemIdstring<uuid>required
dependsOnKind"task" | "opportunity"required
dependsOnIdstring<uuid>required
sourceTeamIdobjectrequired
targetTeamIdobjectrequired
isCrossTeambooleanrequired
sourceobjectrequired
Show child attributes ›
kind"task" | "opportunity"required
idstring<uuid>required
titlestringrequired
refstringrequired
targetobjectrequired
Show child attributes ›
kind"task" | "opportunity"required
idstring<uuid>required
titlestringrequired
refstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/cycles/{id}/impact' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "cycle": {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "scope": "org",
      "teamId": null,
      "teamLabel": null,
      "number": 0,
      "name": null,
      "goal": "string",
      "startsAt": "string",
      "endsAt": "string",
      "committedAt": "string",
      "digestVersion": null,
      "digest": null,
      "closedAt": "string",
      "rolloverState": "pending",
      "rolloverStartedAt": "string",
      "rolloverCompletedAt": "string",
      "rolledOverCount": null,
      "createdAt": "string",
      "updatedAt": "string"
    },
    "assignment": null,
    "standing": {
      "objectives": [
        {
          "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
          "number": 0,
          "title": "string",
          "status": "string",
          "deadline": "string",
          "breached": true
        }
      ],
      "promises": [
        {
          "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
          "customerId": null,
          "moscow": "string",
          "deadline": "string"
        }
      ],
      "capacity": [
        {
          "userId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
          "userName": "string",
          "assignedMinutes": 0,
          "availableMinutes": 0
        }
      ]
    },
    "rollover": {
      "target": null,
      "moves": [
        {
          "itemKind": "task",
          "itemId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
          "plannedStart": "string",
          "durationDays": 0
        }
      ],
      "impact": null
    },
    "crossTeam": [
      {
        "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "itemKind": "task",
        "itemId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "dependsOnKind": "task",
        "dependsOnId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "sourceTeamId": null,
        "targetTeamId": null,
        "isCrossTeam": true,
        "source": {
          "kind": "task",
          "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
          "title": "string",
          "ref": "string"
        },
        "target": {
          "kind": "task",
          "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
          "title": "string",
          "ref": "string"
        }
      }
    ]
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
Resource

External Stakeholders

GET/api/v1/external-stakeholders

List other stakeholders

List the org's other stakeholders (named demand voices with no Telos seat), alphabetically, each with how many insights it roots. Use one's id as externalStakeholderId when recording an insight. Returns at most 500; an org past that needs the in-app directory.

Parameters
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
Returns · 200 — List other stakeholders
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
namestringrequired
createdByUserIdobjectrequired
createdAtstringrequired
usageCountintegerrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/external-stakeholders' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "name": "string",
      "createdByUserId": null,
      "createdAt": "string",
      "usageCount": 0
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/external-stakeholders

Create an other stakeholder

Create a named demand voice with no Telos seat, for rooting insights. Deduplicated case-insensitively on name: an existing voice with the same name is returned instead of a second row, so the same person typed twice stays one voice.

Request body · required
namestringrequired
Returns · 201 — Create an other stakeholder
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
namestringrequired
createdByUserIdobjectrequired
createdAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/external-stakeholders' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "name": "string",
    "createdByUserId": null,
    "createdAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
Resource

Files

GET/api/v1/files

List file metadata

List file metadata with cursor pagination. Pass entityType AND entityId together for one entity's attachments (oldest first); omit both for the org-wide manifest (newest first). Bytes never travel this API — `get` returns a short-lived presigned download URL. Rides file:manage because the unfiltered form is the same org manifest the in-app admin surface gates on it.

Parameters
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
entityTypequery · stringoptional
Attachment target entity type; requires entityId
entityIdquery · string<uuid>optional
Attachment target UUID; requires entityType
Returns · 200 — List file metadata
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
originalNamestringrequired
mimeTypestringrequired
sizeBytesnumberrequired
status"pending" | "processing" | "clean" | "failed"required
uploadedByIdstring<uuid>required
uploadedByNamestringrequired
createdAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/files' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "originalName": "string",
      "mimeType": "string",
      "sizeBytes": 0,
      "status": "pending",
      "uploadedById": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "uploadedByName": "string",
      "createdAt": "string"
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/files

Request a presigned file upload

Step 1 of 2. Reserves the file row and returns `uploadUrl` plus the `fields` of a presigned POST; send the bytes to that URL yourself, then call confirm-upload with the ETag storage returned. `sha256` must be the lowercase hex digest of the exact bytes you will send — it is bound into the upload policy, so storage rejects a mismatch. Passing entityType/entityId attaches the file to that entity as soon as it lands.

Request body · required
filenamestringrequired
mimeTypestringrequired
sizeobjectrequired
Byte length of the file you are about to upload
sha256stringrequired
entityType"vision" | "objective" | "metric" | "opportunity" | "task" | "team" | "user" | "task_assignment" | "webhook_subscription" | "template" | "template_step" | "template_step_instance" | "template_checklist_instance" | "strategy" | "strategy_version" | "vision_version" | "notification" | "comment" | "customer" | "customer_update" | "customer_document" | "insight" | "opportunity_risk" | "file" | "tag" | "tag_theme" | "prd_template" | "room" | "message" | "comment_thread" | "time_entry" | "org" | "scoring_criterion" | "cycle"optional
entityIdstring<uuid>optional
Returns · 201 — Request a presigned file upload
oktruerequired
dataobjectrequired
Show child attributes ›
fileIdstring<uuid>required
uploadUrlstringrequired
fieldsobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/files' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "fileId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "uploadUrl": "string",
    "fields": {}
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/files/{id}

Get a file's metadata and download URL

Get one file's metadata. Once the upload has been scanned and processed (status `clean`) the response carries `downloadUrl`, a presigned GET valid for about 15 minutes; while the file is pending, processing, or failed that field is null and `status` / `processingError` say why.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Get a file's metadata and download URL
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
dataRegionstringrequired
originalNamestringrequired
mimeTypestringrequired
sniffedMimeTypeobjectrequired
sizeBytesintegerrequired
sha256objectrequired
status"pending" | "processing" | "clean" | "failed"required
uploadedByIdstring<uuid>required
processingErrorstringrequired
createdAtstringrequired
downloadUrlstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/files/{id}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "dataRegion": "string",
    "originalName": "string",
    "mimeType": "string",
    "sniffedMimeType": null,
    "sizeBytes": 0,
    "sha256": null,
    "status": "pending",
    "uploadedById": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "processingError": "string",
    "createdAt": "string",
    "downloadUrl": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
DELETE/api/v1/files/{id}

Delete a file

Permanently delete a file: the stored object, its thumbnail, the row, and every attachment pointing at it. Irreversible.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Delete a file
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
deletedtruerequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
DELETE request
curl -X DELETE 'https://www.telos-app.com/api/v1/files/{id}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "deleted": true
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/files/storage-usage

Get the org's storage usage

Bytes currently held against the org's storage quota, the quota itself, and the percentage used. Check this before a large upload: request-upload refuses anything that would cross the quota.

Returns · 200 — Get the org's storage usage
oktruerequired
dataobjectrequired
Show child attributes ›
usedBytesnumberrequired
quotaBytesnumberrequired
usedPercentnumberrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/files/storage-usage' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "usedBytes": 0,
    "quotaBytes": 0,
    "usedPercent": 0
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/files/{id}/confirm

Confirm a completed file upload

Step 2 of 2. Tells Telos the bytes landed, which moves the file to `processing` and queues the integrity check (size, checksum, MIME sniff) that ends in `clean` or `failed`. Idempotent: confirming an already-confirmed file returns its current state.

Parameters
idpath · stringrequired
id path parameter
Request body · required
etagstringrequired
Returns · 200 — Confirm a completed file upload
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
dataRegionstringrequired
originalNamestringrequired
mimeTypestringrequired
sniffedMimeTypeobjectrequired
sizeBytesintegerrequired
sha256objectrequired
status"pending" | "processing" | "clean" | "failed"required
uploadedByIdstring<uuid>required
processingErrorstringrequired
createdAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/files/{id}/confirm' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "dataRegion": "string",
    "originalName": "string",
    "mimeType": "string",
    "sniffedMimeType": null,
    "sizeBytes": 0,
    "sha256": null,
    "status": "pending",
    "uploadedById": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "processingError": "string",
    "createdAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/files/{id}/attachments

Attach a file to an entity

Bind an existing file to an entity so it shows on that entity's attachments rail. Idempotent, and one file may be attached to several entities.

Parameters
idpath · stringrequired
id path parameter
Request body · required
entityType"vision" | "objective" | "metric" | "opportunity" | "task" | "team" | "user" | "task_assignment" | "webhook_subscription" | "template" | "template_step" | "template_step_instance" | "template_checklist_instance" | "strategy" | "strategy_version" | "vision_version" | "notification" | "comment" | "customer" | "customer_update" | "customer_document" | "insight" | "opportunity_risk" | "file" | "tag" | "tag_theme" | "prd_template" | "room" | "message" | "comment_thread" | "time_entry" | "org" | "scoring_criterion" | "cycle"required
entityIdstring<uuid>required
Returns · 200 — Attach a file to an entity
oktruerequired
dataobjectrequired
Show child attributes ›
fileIdstring<uuid>required
entityTypestringrequired
entityIdstring<uuid>required
attachedbooleanrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/files/{id}/attachments' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "fileId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "entityType": "string",
    "entityId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "attached": true
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
DELETE/api/v1/files/{id}/attachments

Detach a file from an entity

Remove one entity's link to a file. The file itself survives with its other attachments; use delete to destroy it.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Detach a file from an entity
oktruerequired
dataobjectrequired
Show child attributes ›
fileIdstring<uuid>required
entityTypestringrequired
entityIdstring<uuid>required
attachedbooleanrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
DELETE request
curl -X DELETE 'https://www.telos-app.com/api/v1/files/{id}/attachments' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "fileId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "entityType": "string",
    "entityId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "attached": true
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
Resource

Import Runs

GET/api/v1/import-runs

List import runs

The org's bulk-import runs (Linear, Jira, CSV) with cursor pagination, newest first: source, status (pending/running/paused/completed/partial/failed), per-phase counts, error text, and timings. Starting a run is in-app only; use this to find the run to watch.

Parameters
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
Returns · 200 — List import runs
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
sourcestringrequired
status"pending" | "running" | "paused" | "completed" | "partial" | "failed"required
configobjectrequired
countsobjectrequired
checkpointobjectrequired
errorstringrequired
createdBystring<uuid>required
startedAtstringrequired
finishedAtstringrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/import-runs' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "source": "string",
      "status": "pending",
      "config": null,
      "counts": null,
      "checkpoint": null,
      "error": "string",
      "createdBy": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "startedAt": "string",
      "finishedAt": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/import-runs/{id}

Get an import run

One import run's durable row: source, status, the sanitized run plan, accumulated per-phase counts, resume checkpoint, error text, and timings. Poll it to watch a run progress; a status of completed, partial, or failed is terminal.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Get an import run
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
sourcestringrequired
status"pending" | "running" | "paused" | "completed" | "partial" | "failed"required
configobjectrequired
countsobjectrequired
checkpointobjectrequired
errorstringrequired
createdBystring<uuid>required
startedAtstringrequired
finishedAtstringrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/import-runs/{id}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "source": "string",
    "status": "pending",
    "config": null,
    "counts": null,
    "checkpoint": null,
    "error": "string",
    "createdBy": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "startedAt": "string",
    "finishedAt": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
Resource

Insights

GET/api/v1/insights

List insights

List customer insights (the customer-voice evidence layer). Filters compose: lifecycle status, demand root (customer), linked work (opportunity/task/objective), review team, recorder, tag, and full-text search over the verbatim. Archived insights are hidden unless includeArchived is set.

Parameters
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
statusquery · stringoptional
Insight lifecycle status filter
customerIdquery · string<uuid>optional
Customer UUID filter
opportunityIdquery · string<uuid>optional
Only insights linked to this opportunity
taskIdquery · string<uuid>optional
Only insights linked to this task
objectiveIdquery · string<uuid>optional
Only insights linked to this objective
reviewTeamIdquery · string<uuid>optional
Only insights routed to this team's review queue
recordedByUserIdquery · string<uuid>optional
Only insights recorded by this user (whoami for your own)
tagIdquery · string<uuid>optional
Only insights carrying this tag
searchquery · stringoptional
Full-text match on the verbatim
includeArchivedqueryoptional
Include archived insights (default false)
reviewQueuequeryoptional
Your own review queue: insights routed to teams you are the insight reviewer for, plus your own insights sent back for context. Replaces the other filters when set.
Returns · 200 — List insights
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
customerIdobjectrequired
customerNamestringrequired
customerRefstringrequired
customerLogoUrlstringrequired
customerLogoFileIdstringrequired
stakeholderUserIdobjectrequired
stakeholderNamestringrequired
stakeholderUserSlugstringrequired
stakeholderAvatarUrlstringrequired
externalStakeholderIdobjectrequired
externalStakeholderNamestringrequired
contactIdobjectrequired
contactNamestringrequired
verbatimstringrequired
sourcestringrequired
status"created" | "review" | "need_context" | "active" | "rejected" | "delivered" | "stale"required
statusChangedAtstringrequired
statusNotestringrequired
reviewTeamIdobjectrequired
reviewTeamNamestringrequired
reviewRequestedAtstringrequired
rejectionCategorystringrequired
moscowobjectrequired
deadlinestringrequired
recordedByUserIdstring<uuid>required
recordedByUserNamestringrequired
recordedByUserAvatarUrlstringrequired
recordedAtstringrequired
archivedAtstringrequired
pinnedbooleanoptional
goLivebooleanoptional
linksobject[]required
Show child attributes ›
entityType"opportunity" | "task" | "objective"required
entityIdstring<uuid>required
titlestringoptional
refstringoptional
state"backlog" | "in_progress" | "completed" | "cancelled"optional
blockingbooleanoptional
tagsobject[]required
Show child attributes ›
idstring<uuid>required
namestringrequired
themeIdobjectrequired
themeNamestringrequired
colorstringrequired
themeColorstringrequired
impactsobject[]required
Show child attributes ›
objectiveIdstring<uuid>required
objectiveTitlestringrequired
objectiveRefstringrequired
estimatedDeltastringrequired
metricUnitstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/insights' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "customerId": null,
      "customerName": "string",
      "customerRef": "string",
      "customerLogoUrl": "string",
      "customerLogoFileId": "string",
      "stakeholderUserId": null,
      "stakeholderName": "string",
      "stakeholderUserSlug": "string",
      "stakeholderAvatarUrl": "string",
      "externalStakeholderId": null,
      "externalStakeholderName": "string",
      "contactId": null,
      "contactName": "string",
      "verbatim": "string",
      "source": "string",
      "status": "created",
      "statusChangedAt": "string",
      "statusNote": "string",
      "reviewTeamId": null,
      "reviewTeamName": "string",
      "reviewRequestedAt": "string",
      "rejectionCategory": "string",
      "moscow": null,
      "deadline": "string",
      "recordedByUserId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "recordedByUserName": "string",
      "recordedByUserAvatarUrl": "string",
      "recordedAt": "string",
      "archivedAt": "string",
      "pinned": true,
      "goLive": true,
      "links": [
        {
          "entityType": "opportunity",
          "entityId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
          "title": "string",
          "ref": "string",
          "state": "backlog",
          "blocking": true
        }
      ],
      "tags": [
        {
          "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
          "name": "string",
          "themeId": null,
          "themeName": "string",
          "color": "string",
          "themeColor": "string"
        }
      ],
      "impacts": [
        {
          "objectiveId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
          "objectiveTitle": "string",
          "objectiveRef": "string",
          "estimatedDelta": "string",
          "metricUnit": "string"
        }
      ]
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/insights

Create an insight

Record a customer insight (one discrete signal, not a whole document). Roots at exactly one demand source: a customer, an internal stakeholder (org user), or an other stakeholder (externalStakeholderId — a named voice with no Telos seat). Optionally set source, moscow priority, deadline, tagIds for clustering, a reviewTeamId to route it into a team's review queue, and attach to an opportunity/task/objective.

Request body · required
customerIdobjectoptional
stakeholderUserIdobjectoptional
externalStakeholderIdobjectoptional
contactIdobjectoptional
verbatimstringrequired
source"interview" | "support" | "sales" | "async" | "observation" | "submission" | "community"required
moscowobjectoptional
deadlineobjectoptional
reviewTeamIdobjectoptional
attachToOpportunityIdstring<uuid>optional
attachToTaskIdstring<uuid>optional
attachToObjectiveIdstring<uuid>optional
pinnedobjectoptional
Pin the link created by attachToOpportunityId
tagIdsstring<uuid>[]optional
Returns · 201 — Create an insight
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
customerIdobjectrequired
customerNamestringrequired
customerRefstringrequired
customerLogoUrlstringrequired
customerLogoFileIdstringrequired
stakeholderUserIdobjectrequired
stakeholderNamestringrequired
stakeholderUserSlugstringrequired
stakeholderAvatarUrlstringrequired
externalStakeholderIdobjectrequired
externalStakeholderNamestringrequired
contactIdobjectrequired
contactNamestringrequired
verbatimstringrequired
sourcestringrequired
status"created" | "review" | "need_context" | "active" | "rejected" | "delivered" | "stale"required
statusChangedAtstringrequired
statusNotestringrequired
reviewTeamIdobjectrequired
reviewTeamNamestringrequired
reviewRequestedAtstringrequired
rejectionCategorystringrequired
moscowobjectrequired
deadlinestringrequired
recordedByUserIdstring<uuid>required
recordedByUserNamestringrequired
recordedByUserAvatarUrlstringrequired
recordedAtstringrequired
archivedAtstringrequired
pinnedbooleanoptional
goLivebooleanoptional
linksobject[]required
Show child attributes ›
entityType"opportunity" | "task" | "objective"required
entityIdstring<uuid>required
titlestringoptional
refstringoptional
state"backlog" | "in_progress" | "completed" | "cancelled"optional
blockingbooleanoptional
tagsobject[]required
Show child attributes ›
idstring<uuid>required
namestringrequired
themeIdobjectrequired
themeNamestringrequired
colorstringrequired
themeColorstringrequired
impactsobject[]required
Show child attributes ›
objectiveIdstring<uuid>required
objectiveTitlestringrequired
objectiveRefstringrequired
estimatedDeltastringrequired
metricUnitstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/insights' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "customerId": null,
    "customerName": "string",
    "customerRef": "string",
    "customerLogoUrl": "string",
    "customerLogoFileId": "string",
    "stakeholderUserId": null,
    "stakeholderName": "string",
    "stakeholderUserSlug": "string",
    "stakeholderAvatarUrl": "string",
    "externalStakeholderId": null,
    "externalStakeholderName": "string",
    "contactId": null,
    "contactName": "string",
    "verbatim": "string",
    "source": "string",
    "status": "created",
    "statusChangedAt": "string",
    "statusNote": "string",
    "reviewTeamId": null,
    "reviewTeamName": "string",
    "reviewRequestedAt": "string",
    "rejectionCategory": "string",
    "moscow": null,
    "deadline": "string",
    "recordedByUserId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "recordedByUserName": "string",
    "recordedByUserAvatarUrl": "string",
    "recordedAt": "string",
    "archivedAt": "string",
    "pinned": true,
    "goLive": true,
    "links": [
      {
        "entityType": "opportunity",
        "entityId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "title": "string",
        "ref": "string",
        "state": "backlog",
        "blocking": true
      }
    ],
    "tags": [
      {
        "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "name": "string",
        "themeId": null,
        "themeName": "string",
        "color": "string",
        "themeColor": "string"
      }
    ],
    "impacts": [
      {
        "objectiveId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "objectiveTitle": "string",
        "objectiveRef": "string",
        "estimatedDelta": "string",
        "metricUnit": "string"
      }
    ]
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/insights/{id}

Get an insight

Get an insight with its demand root, links, tags, and committed impacts.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Get an insight
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
customerIdobjectrequired
customerNamestringrequired
customerRefstringrequired
customerLogoUrlstringrequired
customerLogoFileIdstringrequired
stakeholderUserIdobjectrequired
stakeholderNamestringrequired
stakeholderUserSlugstringrequired
stakeholderAvatarUrlstringrequired
externalStakeholderIdobjectrequired
externalStakeholderNamestringrequired
contactIdobjectrequired
contactNamestringrequired
verbatimstringrequired
sourcestringrequired
status"created" | "review" | "need_context" | "active" | "rejected" | "delivered" | "stale"required
statusChangedAtstringrequired
statusNotestringrequired
reviewTeamIdobjectrequired
reviewTeamNamestringrequired
reviewRequestedAtstringrequired
rejectionCategorystringrequired
moscowobjectrequired
deadlinestringrequired
recordedByUserIdstring<uuid>required
recordedByUserNamestringrequired
recordedByUserAvatarUrlstringrequired
recordedAtstringrequired
archivedAtstringrequired
pinnedbooleanoptional
goLivebooleanoptional
linksobject[]required
Show child attributes ›
entityType"opportunity" | "task" | "objective"required
entityIdstring<uuid>required
titlestringoptional
refstringoptional
state"backlog" | "in_progress" | "completed" | "cancelled"optional
blockingbooleanoptional
tagsobject[]required
Show child attributes ›
idstring<uuid>required
namestringrequired
themeIdobjectrequired
themeNamestringrequired
colorstringrequired
themeColorstringrequired
impactsobject[]required
Show child attributes ›
objectiveIdstring<uuid>required
objectiveTitlestringrequired
objectiveRefstringrequired
estimatedDeltastringrequired
metricUnitstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/insights/{id}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "customerId": null,
    "customerName": "string",
    "customerRef": "string",
    "customerLogoUrl": "string",
    "customerLogoFileId": "string",
    "stakeholderUserId": null,
    "stakeholderName": "string",
    "stakeholderUserSlug": "string",
    "stakeholderAvatarUrl": "string",
    "externalStakeholderId": null,
    "externalStakeholderName": "string",
    "contactId": null,
    "contactName": "string",
    "verbatim": "string",
    "source": "string",
    "status": "created",
    "statusChangedAt": "string",
    "statusNote": "string",
    "reviewTeamId": null,
    "reviewTeamName": "string",
    "reviewRequestedAt": "string",
    "rejectionCategory": "string",
    "moscow": null,
    "deadline": "string",
    "recordedByUserId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "recordedByUserName": "string",
    "recordedByUserAvatarUrl": "string",
    "recordedAt": "string",
    "archivedAt": "string",
    "pinned": true,
    "goLive": true,
    "links": [
      {
        "entityType": "opportunity",
        "entityId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "title": "string",
        "ref": "string",
        "state": "backlog",
        "blocking": true
      }
    ],
    "tags": [
      {
        "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "name": "string",
        "themeId": null,
        "themeName": "string",
        "color": "string",
        "themeColor": "string"
      }
    ],
    "impacts": [
      {
        "objectiveId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "objectiveTitle": "string",
        "objectiveRef": "string",
        "estimatedDelta": "string",
        "metricUnit": "string"
      }
    ]
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
PATCH/api/v1/insights/{id}

Update an insight

Update an insight's verbatim, source, demand root, contact, moscow priority, or deadline. The service keeps exactly one demand root after the merge.

Parameters
idpath · stringrequired
id path parameter
Request body · required
verbatimstringoptional
source"interview" | "support" | "sales" | "async" | "observation" | "submission" | "community"optional
customerIdobjectoptional
stakeholderUserIdobjectoptional
externalStakeholderIdobjectoptional
contactIdobjectoptional
moscowobjectoptional
deadlineobjectoptional
Returns · 200 — Update an insight
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
customerIdobjectrequired
customerNamestringrequired
customerRefstringrequired
customerLogoUrlstringrequired
customerLogoFileIdstringrequired
stakeholderUserIdobjectrequired
stakeholderNamestringrequired
stakeholderUserSlugstringrequired
stakeholderAvatarUrlstringrequired
externalStakeholderIdobjectrequired
externalStakeholderNamestringrequired
contactIdobjectrequired
contactNamestringrequired
verbatimstringrequired
sourcestringrequired
status"created" | "review" | "need_context" | "active" | "rejected" | "delivered" | "stale"required
statusChangedAtstringrequired
statusNotestringrequired
reviewTeamIdobjectrequired
reviewTeamNamestringrequired
reviewRequestedAtstringrequired
rejectionCategorystringrequired
moscowobjectrequired
deadlinestringrequired
recordedByUserIdstring<uuid>required
recordedByUserNamestringrequired
recordedByUserAvatarUrlstringrequired
recordedAtstringrequired
archivedAtstringrequired
pinnedbooleanoptional
goLivebooleanoptional
linksobject[]required
Show child attributes ›
entityType"opportunity" | "task" | "objective"required
entityIdstring<uuid>required
titlestringoptional
refstringoptional
state"backlog" | "in_progress" | "completed" | "cancelled"optional
blockingbooleanoptional
tagsobject[]required
Show child attributes ›
idstring<uuid>required
namestringrequired
themeIdobjectrequired
themeNamestringrequired
colorstringrequired
themeColorstringrequired
impactsobject[]required
Show child attributes ›
objectiveIdstring<uuid>required
objectiveTitlestringrequired
objectiveRefstringrequired
estimatedDeltastringrequired
metricUnitstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
PATCH request
curl -X PATCH 'https://www.telos-app.com/api/v1/insights/{id}' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "customerId": null,
    "customerName": "string",
    "customerRef": "string",
    "customerLogoUrl": "string",
    "customerLogoFileId": "string",
    "stakeholderUserId": null,
    "stakeholderName": "string",
    "stakeholderUserSlug": "string",
    "stakeholderAvatarUrl": "string",
    "externalStakeholderId": null,
    "externalStakeholderName": "string",
    "contactId": null,
    "contactName": "string",
    "verbatim": "string",
    "source": "string",
    "status": "created",
    "statusChangedAt": "string",
    "statusNote": "string",
    "reviewTeamId": null,
    "reviewTeamName": "string",
    "reviewRequestedAt": "string",
    "rejectionCategory": "string",
    "moscow": null,
    "deadline": "string",
    "recordedByUserId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "recordedByUserName": "string",
    "recordedByUserAvatarUrl": "string",
    "recordedAt": "string",
    "archivedAt": "string",
    "pinned": true,
    "goLive": true,
    "links": [
      {
        "entityType": "opportunity",
        "entityId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "title": "string",
        "ref": "string",
        "state": "backlog",
        "blocking": true
      }
    ],
    "tags": [
      {
        "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "name": "string",
        "themeId": null,
        "themeName": "string",
        "color": "string",
        "themeColor": "string"
      }
    ],
    "impacts": [
      {
        "objectiveId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "objectiveTitle": "string",
        "objectiveRef": "string",
        "estimatedDelta": "string",
        "metricUnit": "string"
      }
    ]
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
DELETE/api/v1/insights/{id}

Delete an insight

Permanently delete an insight and its links. Prefer the review lifecycle (set-status rejected/archived) to record an outcome; delete is for mistakes.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Delete an insight
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
deletedtruerequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
DELETE request
curl -X DELETE 'https://www.telos-app.com/api/v1/insights/{id}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "deleted": true
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/insights/{id}/attach

Attach an insight

Link an existing insight to an opportunity, task, or objective (optionally pinned). Call it once per insight to attach a whole cluster of related insights to one opportunity.

Parameters
idpath · stringrequired
id path parameter
Request body · required
entityType"opportunity" | "task" | "objective"required
entityIdstring<uuid>required
pinnedobjectoptional
Pin the new link
Returns · 200 — Attach an insight
oktruerequired
dataobjectrequired
Show child attributes ›
oktruerequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/insights/{id}/attach' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "ok": true
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/insights/{id}/detach

Detach an insight

Remove the link between an insight and an opportunity, task, or objective. The insight survives; only the tie goes.

Parameters
idpath · stringrequired
id path parameter
Request body · required
entityType"opportunity" | "task" | "objective"required
entityIdstring<uuid>required
Returns · 200 — Detach an insight
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
customerIdobjectrequired
customerNamestringrequired
customerRefstringrequired
customerLogoUrlstringrequired
customerLogoFileIdstringrequired
stakeholderUserIdobjectrequired
stakeholderNamestringrequired
stakeholderUserSlugstringrequired
stakeholderAvatarUrlstringrequired
externalStakeholderIdobjectrequired
externalStakeholderNamestringrequired
contactIdobjectrequired
contactNamestringrequired
verbatimstringrequired
sourcestringrequired
status"created" | "review" | "need_context" | "active" | "rejected" | "delivered" | "stale"required
statusChangedAtstringrequired
statusNotestringrequired
reviewTeamIdobjectrequired
reviewTeamNamestringrequired
reviewRequestedAtstringrequired
rejectionCategorystringrequired
moscowobjectrequired
deadlinestringrequired
recordedByUserIdstring<uuid>required
recordedByUserNamestringrequired
recordedByUserAvatarUrlstringrequired
recordedAtstringrequired
archivedAtstringrequired
pinnedbooleanoptional
goLivebooleanoptional
linksobject[]required
Show child attributes ›
entityType"opportunity" | "task" | "objective"required
entityIdstring<uuid>required
titlestringoptional
refstringoptional
state"backlog" | "in_progress" | "completed" | "cancelled"optional
blockingbooleanoptional
tagsobject[]required
Show child attributes ›
idstring<uuid>required
namestringrequired
themeIdobjectrequired
themeNamestringrequired
colorstringrequired
themeColorstringrequired
impactsobject[]required
Show child attributes ›
objectiveIdstring<uuid>required
objectiveTitlestringrequired
objectiveRefstringrequired
estimatedDeltastringrequired
metricUnitstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/insights/{id}/detach' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "customerId": null,
    "customerName": "string",
    "customerRef": "string",
    "customerLogoUrl": "string",
    "customerLogoFileId": "string",
    "stakeholderUserId": null,
    "stakeholderName": "string",
    "stakeholderUserSlug": "string",
    "stakeholderAvatarUrl": "string",
    "externalStakeholderId": null,
    "externalStakeholderName": "string",
    "contactId": null,
    "contactName": "string",
    "verbatim": "string",
    "source": "string",
    "status": "created",
    "statusChangedAt": "string",
    "statusNote": "string",
    "reviewTeamId": null,
    "reviewTeamName": "string",
    "reviewRequestedAt": "string",
    "rejectionCategory": "string",
    "moscow": null,
    "deadline": "string",
    "recordedByUserId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "recordedByUserName": "string",
    "recordedByUserAvatarUrl": "string",
    "recordedAt": "string",
    "archivedAt": "string",
    "pinned": true,
    "goLive": true,
    "links": [
      {
        "entityType": "opportunity",
        "entityId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "title": "string",
        "ref": "string",
        "state": "backlog",
        "blocking": true
      }
    ],
    "tags": [
      {
        "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "name": "string",
        "themeId": null,
        "themeName": "string",
        "color": "string",
        "themeColor": "string"
      }
    ],
    "impacts": [
      {
        "objectiveId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "objectiveTitle": "string",
        "objectiveRef": "string",
        "estimatedDelta": "string",
        "metricUnit": "string"
      }
    ]
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/insights/{id}/set-link

Set the flags on an insight's link

Set the flags on an existing insight link: pinned (surface it at the top of the work item's evidence rail) and blocking (this client ask blocks the work). Blocking is opportunity/task only — an objective cannot be blocked by a client ask. Pass at least one flag; omitted flags are left alone.

Parameters
idpath · stringrequired
id path parameter
Request body · required
entityType"opportunity" | "task" | "objective"required
The linked entity's kind
entityIdstring<uuid>required
The linked entity's UUID
pinnedobjectoptional
Pin or unpin the link
blockingobjectoptional
Flag or unflag the link as blocking (opportunity/task only)
Returns · 200 — Set the flags on an insight's link
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
customerIdobjectrequired
customerNamestringrequired
customerRefstringrequired
customerLogoUrlstringrequired
customerLogoFileIdstringrequired
stakeholderUserIdobjectrequired
stakeholderNamestringrequired
stakeholderUserSlugstringrequired
stakeholderAvatarUrlstringrequired
externalStakeholderIdobjectrequired
externalStakeholderNamestringrequired
contactIdobjectrequired
contactNamestringrequired
verbatimstringrequired
sourcestringrequired
status"created" | "review" | "need_context" | "active" | "rejected" | "delivered" | "stale"required
statusChangedAtstringrequired
statusNotestringrequired
reviewTeamIdobjectrequired
reviewTeamNamestringrequired
reviewRequestedAtstringrequired
rejectionCategorystringrequired
moscowobjectrequired
deadlinestringrequired
recordedByUserIdstring<uuid>required
recordedByUserNamestringrequired
recordedByUserAvatarUrlstringrequired
recordedAtstringrequired
archivedAtstringrequired
pinnedbooleanoptional
goLivebooleanoptional
linksobject[]required
Show child attributes ›
entityType"opportunity" | "task" | "objective"required
entityIdstring<uuid>required
titlestringoptional
refstringoptional
state"backlog" | "in_progress" | "completed" | "cancelled"optional
blockingbooleanoptional
tagsobject[]required
Show child attributes ›
idstring<uuid>required
namestringrequired
themeIdobjectrequired
themeNamestringrequired
colorstringrequired
themeColorstringrequired
impactsobject[]required
Show child attributes ›
objectiveIdstring<uuid>required
objectiveTitlestringrequired
objectiveRefstringrequired
estimatedDeltastringrequired
metricUnitstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/insights/{id}/set-link' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "customerId": null,
    "customerName": "string",
    "customerRef": "string",
    "customerLogoUrl": "string",
    "customerLogoFileId": "string",
    "stakeholderUserId": null,
    "stakeholderName": "string",
    "stakeholderUserSlug": "string",
    "stakeholderAvatarUrl": "string",
    "externalStakeholderId": null,
    "externalStakeholderName": "string",
    "contactId": null,
    "contactName": "string",
    "verbatim": "string",
    "source": "string",
    "status": "created",
    "statusChangedAt": "string",
    "statusNote": "string",
    "reviewTeamId": null,
    "reviewTeamName": "string",
    "reviewRequestedAt": "string",
    "rejectionCategory": "string",
    "moscow": null,
    "deadline": "string",
    "recordedByUserId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "recordedByUserName": "string",
    "recordedByUserAvatarUrl": "string",
    "recordedAt": "string",
    "archivedAt": "string",
    "pinned": true,
    "goLive": true,
    "links": [
      {
        "entityType": "opportunity",
        "entityId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "title": "string",
        "ref": "string",
        "state": "backlog",
        "blocking": true
      }
    ],
    "tags": [
      {
        "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "name": "string",
        "themeId": null,
        "themeName": "string",
        "color": "string",
        "themeColor": "string"
      }
    ],
    "impacts": [
      {
        "objectiveId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "objectiveTitle": "string",
        "objectiveRef": "string",
        "estimatedDelta": "string",
        "metricUnit": "string"
      }
    ]
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/insights/{id}/set-status

Set an insight's review outcome

Move an insight to a review outcome. This is the whole lifecycle in one action: created, review, need_context, active, rejected, delivered, stale, or archived. `rejected` requires a note (the reason, 5-1000 chars) and a rejectionCategory, and publishes the decision to the org and to the customer's feed. `need_context` requires a note (the question, 5-1000 chars) and sends the insight back to whoever recorded it. `archived` hides it from every default list without deleting it. Returns the insight.

Parameters
idpath · stringrequired
id path parameter
Request body · required
status"created" | "review" | "need_context" | "active" | "rejected" | "delivered" | "stale" | "archived"required
Destination review outcome
notestringoptional
Why: the rejection reason, the context question, or a free note on any other transition
rejectionCategory"out_of_scope" | "duplicate" | "not_aligned" | "not_now" | "insufficient_value" | "other"optional
Required when status is rejected
Returns · 200 — Set an insight's review outcome
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
customerIdobjectrequired
customerNamestringrequired
customerRefstringrequired
customerLogoUrlstringrequired
customerLogoFileIdstringrequired
stakeholderUserIdobjectrequired
stakeholderNamestringrequired
stakeholderUserSlugstringrequired
stakeholderAvatarUrlstringrequired
externalStakeholderIdobjectrequired
externalStakeholderNamestringrequired
contactIdobjectrequired
contactNamestringrequired
verbatimstringrequired
sourcestringrequired
status"created" | "review" | "need_context" | "active" | "rejected" | "delivered" | "stale"required
statusChangedAtstringrequired
statusNotestringrequired
reviewTeamIdobjectrequired
reviewTeamNamestringrequired
reviewRequestedAtstringrequired
rejectionCategorystringrequired
moscowobjectrequired
deadlinestringrequired
recordedByUserIdstring<uuid>required
recordedByUserNamestringrequired
recordedByUserAvatarUrlstringrequired
recordedAtstringrequired
archivedAtstringrequired
pinnedbooleanoptional
goLivebooleanoptional
linksobject[]required
Show child attributes ›
entityType"opportunity" | "task" | "objective"required
entityIdstring<uuid>required
titlestringoptional
refstringoptional
state"backlog" | "in_progress" | "completed" | "cancelled"optional
blockingbooleanoptional
tagsobject[]required
Show child attributes ›
idstring<uuid>required
namestringrequired
themeIdobjectrequired
themeNamestringrequired
colorstringrequired
themeColorstringrequired
impactsobject[]required
Show child attributes ›
objectiveIdstring<uuid>required
objectiveTitlestringrequired
objectiveRefstringrequired
estimatedDeltastringrequired
metricUnitstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/insights/{id}/set-status' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "customerId": null,
    "customerName": "string",
    "customerRef": "string",
    "customerLogoUrl": "string",
    "customerLogoFileId": "string",
    "stakeholderUserId": null,
    "stakeholderName": "string",
    "stakeholderUserSlug": "string",
    "stakeholderAvatarUrl": "string",
    "externalStakeholderId": null,
    "externalStakeholderName": "string",
    "contactId": null,
    "contactName": "string",
    "verbatim": "string",
    "source": "string",
    "status": "created",
    "statusChangedAt": "string",
    "statusNote": "string",
    "reviewTeamId": null,
    "reviewTeamName": "string",
    "reviewRequestedAt": "string",
    "rejectionCategory": "string",
    "moscow": null,
    "deadline": "string",
    "recordedByUserId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "recordedByUserName": "string",
    "recordedByUserAvatarUrl": "string",
    "recordedAt": "string",
    "archivedAt": "string",
    "pinned": true,
    "goLive": true,
    "links": [
      {
        "entityType": "opportunity",
        "entityId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "title": "string",
        "ref": "string",
        "state": "backlog",
        "blocking": true
      }
    ],
    "tags": [
      {
        "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "name": "string",
        "themeId": null,
        "themeName": "string",
        "color": "string",
        "themeColor": "string"
      }
    ],
    "impacts": [
      {
        "objectiveId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "objectiveTitle": "string",
        "objectiveRef": "string",
        "estimatedDelta": "string",
        "metricUnit": "string"
      }
    ]
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/insights/{id}/set-review-team

Route an insight to a team's review queue

Route an insight to a team for review (this moves it to status review and notifies the team's insight reviewer), or pass null to pull it back out of review. Clearing returns a live insight to active when it has linked work and created when it does not; a terminal insight keeps its outcome. Returns the insight.

Parameters
idpath · stringrequired
id path parameter
Request body · required
reviewTeamIdobjectrequired
Team UUID to route to, or null to clear the review team
Returns · 200 — Route an insight to a team's review queue
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
customerIdobjectrequired
customerNamestringrequired
customerRefstringrequired
customerLogoUrlstringrequired
customerLogoFileIdstringrequired
stakeholderUserIdobjectrequired
stakeholderNamestringrequired
stakeholderUserSlugstringrequired
stakeholderAvatarUrlstringrequired
externalStakeholderIdobjectrequired
externalStakeholderNamestringrequired
contactIdobjectrequired
contactNamestringrequired
verbatimstringrequired
sourcestringrequired
status"created" | "review" | "need_context" | "active" | "rejected" | "delivered" | "stale"required
statusChangedAtstringrequired
statusNotestringrequired
reviewTeamIdobjectrequired
reviewTeamNamestringrequired
reviewRequestedAtstringrequired
rejectionCategorystringrequired
moscowobjectrequired
deadlinestringrequired
recordedByUserIdstring<uuid>required
recordedByUserNamestringrequired
recordedByUserAvatarUrlstringrequired
recordedAtstringrequired
archivedAtstringrequired
pinnedbooleanoptional
goLivebooleanoptional
linksobject[]required
Show child attributes ›
entityType"opportunity" | "task" | "objective"required
entityIdstring<uuid>required
titlestringoptional
refstringoptional
state"backlog" | "in_progress" | "completed" | "cancelled"optional
blockingbooleanoptional
tagsobject[]required
Show child attributes ›
idstring<uuid>required
namestringrequired
themeIdobjectrequired
themeNamestringrequired
colorstringrequired
themeColorstringrequired
impactsobject[]required
Show child attributes ›
objectiveIdstring<uuid>required
objectiveTitlestringrequired
objectiveRefstringrequired
estimatedDeltastringrequired
metricUnitstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/insights/{id}/set-review-team' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "customerId": null,
    "customerName": "string",
    "customerRef": "string",
    "customerLogoUrl": "string",
    "customerLogoFileId": "string",
    "stakeholderUserId": null,
    "stakeholderName": "string",
    "stakeholderUserSlug": "string",
    "stakeholderAvatarUrl": "string",
    "externalStakeholderId": null,
    "externalStakeholderName": "string",
    "contactId": null,
    "contactName": "string",
    "verbatim": "string",
    "source": "string",
    "status": "created",
    "statusChangedAt": "string",
    "statusNote": "string",
    "reviewTeamId": null,
    "reviewTeamName": "string",
    "reviewRequestedAt": "string",
    "rejectionCategory": "string",
    "moscow": null,
    "deadline": "string",
    "recordedByUserId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "recordedByUserName": "string",
    "recordedByUserAvatarUrl": "string",
    "recordedAt": "string",
    "archivedAt": "string",
    "pinned": true,
    "goLive": true,
    "links": [
      {
        "entityType": "opportunity",
        "entityId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "title": "string",
        "ref": "string",
        "state": "backlog",
        "blocking": true
      }
    ],
    "tags": [
      {
        "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "name": "string",
        "themeId": null,
        "themeName": "string",
        "color": "string",
        "themeColor": "string"
      }
    ],
    "impacts": [
      {
        "objectiveId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "objectiveTitle": "string",
        "objectiveRef": "string",
        "estimatedDelta": "string",
        "metricUnit": "string"
      }
    ]
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/insights/{id}/set-tags

Set an insight's tags

Replace an insight's tag set (tags are how insights cluster into themes). Pass the full list you want, not a delta; an empty list clears them. Create or look up tag ids with the tag actions. Returns the insight.

Parameters
idpath · stringrequired
id path parameter
Request body · required
tagIdsstring<uuid>[]required
The complete tag set for this insight; replaces what is there
Returns · 200 — Set an insight's tags
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
customerIdobjectrequired
customerNamestringrequired
customerRefstringrequired
customerLogoUrlstringrequired
customerLogoFileIdstringrequired
stakeholderUserIdobjectrequired
stakeholderNamestringrequired
stakeholderUserSlugstringrequired
stakeholderAvatarUrlstringrequired
externalStakeholderIdobjectrequired
externalStakeholderNamestringrequired
contactIdobjectrequired
contactNamestringrequired
verbatimstringrequired
sourcestringrequired
status"created" | "review" | "need_context" | "active" | "rejected" | "delivered" | "stale"required
statusChangedAtstringrequired
statusNotestringrequired
reviewTeamIdobjectrequired
reviewTeamNamestringrequired
reviewRequestedAtstringrequired
rejectionCategorystringrequired
moscowobjectrequired
deadlinestringrequired
recordedByUserIdstring<uuid>required
recordedByUserNamestringrequired
recordedByUserAvatarUrlstringrequired
recordedAtstringrequired
archivedAtstringrequired
pinnedbooleanoptional
goLivebooleanoptional
linksobject[]required
Show child attributes ›
entityType"opportunity" | "task" | "objective"required
entityIdstring<uuid>required
titlestringoptional
refstringoptional
state"backlog" | "in_progress" | "completed" | "cancelled"optional
blockingbooleanoptional
tagsobject[]required
Show child attributes ›
idstring<uuid>required
namestringrequired
themeIdobjectrequired
themeNamestringrequired
colorstringrequired
themeColorstringrequired
impactsobject[]required
Show child attributes ›
objectiveIdstring<uuid>required
objectiveTitlestringrequired
objectiveRefstringrequired
estimatedDeltastringrequired
metricUnitstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/insights/{id}/set-tags' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "customerId": null,
    "customerName": "string",
    "customerRef": "string",
    "customerLogoUrl": "string",
    "customerLogoFileId": "string",
    "stakeholderUserId": null,
    "stakeholderName": "string",
    "stakeholderUserSlug": "string",
    "stakeholderAvatarUrl": "string",
    "externalStakeholderId": null,
    "externalStakeholderName": "string",
    "contactId": null,
    "contactName": "string",
    "verbatim": "string",
    "source": "string",
    "status": "created",
    "statusChangedAt": "string",
    "statusNote": "string",
    "reviewTeamId": null,
    "reviewTeamName": "string",
    "reviewRequestedAt": "string",
    "rejectionCategory": "string",
    "moscow": null,
    "deadline": "string",
    "recordedByUserId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "recordedByUserName": "string",
    "recordedByUserAvatarUrl": "string",
    "recordedAt": "string",
    "archivedAt": "string",
    "pinned": true,
    "goLive": true,
    "links": [
      {
        "entityType": "opportunity",
        "entityId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "title": "string",
        "ref": "string",
        "state": "backlog",
        "blocking": true
      }
    ],
    "tags": [
      {
        "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "name": "string",
        "themeId": null,
        "themeName": "string",
        "color": "string",
        "themeColor": "string"
      }
    ],
    "impacts": [
      {
        "objectiveId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "objectiveTitle": "string",
        "objectiveRef": "string",
        "estimatedDelta": "string",
        "metricUnit": "string"
      }
    ]
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/insights/{id}/set-impact

Set an insight's objective impacts

Replace the insight's impact ties: which objectives it moves, and by how much. This is the only place a number is typed on an insight; work ties carry no delta. Pass the full list, not a delta; an empty list clears them. Returns the insight.

Parameters
idpath · stringrequired
id path parameter
Request body · required
impactsobject[]required
The complete impact set; replaces what is there
Show child attributes ›
objectiveIdstring<uuid>required
Objective UUID
estimatedDeltanumberrequired
Estimated movement on the objective's metric, or null
Returns · 200 — Set an insight's objective impacts
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
customerIdobjectrequired
customerNamestringrequired
customerRefstringrequired
customerLogoUrlstringrequired
customerLogoFileIdstringrequired
stakeholderUserIdobjectrequired
stakeholderNamestringrequired
stakeholderUserSlugstringrequired
stakeholderAvatarUrlstringrequired
externalStakeholderIdobjectrequired
externalStakeholderNamestringrequired
contactIdobjectrequired
contactNamestringrequired
verbatimstringrequired
sourcestringrequired
status"created" | "review" | "need_context" | "active" | "rejected" | "delivered" | "stale"required
statusChangedAtstringrequired
statusNotestringrequired
reviewTeamIdobjectrequired
reviewTeamNamestringrequired
reviewRequestedAtstringrequired
rejectionCategorystringrequired
moscowobjectrequired
deadlinestringrequired
recordedByUserIdstring<uuid>required
recordedByUserNamestringrequired
recordedByUserAvatarUrlstringrequired
recordedAtstringrequired
archivedAtstringrequired
pinnedbooleanoptional
goLivebooleanoptional
linksobject[]required
Show child attributes ›
entityType"opportunity" | "task" | "objective"required
entityIdstring<uuid>required
titlestringoptional
refstringoptional
state"backlog" | "in_progress" | "completed" | "cancelled"optional
blockingbooleanoptional
tagsobject[]required
Show child attributes ›
idstring<uuid>required
namestringrequired
themeIdobjectrequired
themeNamestringrequired
colorstringrequired
themeColorstringrequired
impactsobject[]required
Show child attributes ›
objectiveIdstring<uuid>required
objectiveTitlestringrequired
objectiveRefstringrequired
estimatedDeltastringrequired
metricUnitstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/insights/{id}/set-impact' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "customerId": null,
    "customerName": "string",
    "customerRef": "string",
    "customerLogoUrl": "string",
    "customerLogoFileId": "string",
    "stakeholderUserId": null,
    "stakeholderName": "string",
    "stakeholderUserSlug": "string",
    "stakeholderAvatarUrl": "string",
    "externalStakeholderId": null,
    "externalStakeholderName": "string",
    "contactId": null,
    "contactName": "string",
    "verbatim": "string",
    "source": "string",
    "status": "created",
    "statusChangedAt": "string",
    "statusNote": "string",
    "reviewTeamId": null,
    "reviewTeamName": "string",
    "reviewRequestedAt": "string",
    "rejectionCategory": "string",
    "moscow": null,
    "deadline": "string",
    "recordedByUserId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "recordedByUserName": "string",
    "recordedByUserAvatarUrl": "string",
    "recordedAt": "string",
    "archivedAt": "string",
    "pinned": true,
    "goLive": true,
    "links": [
      {
        "entityType": "opportunity",
        "entityId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "title": "string",
        "ref": "string",
        "state": "backlog",
        "blocking": true
      }
    ],
    "tags": [
      {
        "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "name": "string",
        "themeId": null,
        "themeName": "string",
        "color": "string",
        "themeColor": "string"
      }
    ],
    "impacts": [
      {
        "objectiveId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "objectiveTitle": "string",
        "objectiveRef": "string",
        "estimatedDelta": "string",
        "metricUnit": "string"
      }
    ]
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/insights/blocking

List the insights blocking a work item

The client-voiced blockers on one opportunity or task: open insights whose link to it is flagged blocking. Use it before promising a delivery date.

Parameters
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
itemKindquery · stringrequired
The work item's kind
itemIdquery · string<uuid>required
The work item's UUID
Returns · 200 — List the insights blocking a work item
oktruerequired
dataobject[]required
Show child attributes ›
insightIdstring<uuid>required
verbatimstringrequired
customerIdobjectrequired
customerNamestringrequired
customerRefstringrequired
customerLogoUrlstringrequired
customerLogoFileIdstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/insights/blocking' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "insightId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "verbatim": "string",
      "customerId": null,
      "customerName": "string",
      "customerRef": "string",
      "customerLogoUrl": "string",
      "customerLogoFileId": "string"
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/insights/{id}/similar

Find near-duplicate insights and past rejections

Embedding-similarity signals for one insight: near-duplicate insights the org already holds, and near-duplicate asks it already REJECTED (with the reason, the category, and who said no). No LLM call. Read this before recording or reviewing a signal so the org does not relitigate a decision it already made.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Find near-duplicate insights and past rejections
oktruerequired
dataobjectrequired
Show child attributes ›
similarobject[]required
Show child attributes ›
idstring<uuid>required
verbatimstringrequired
voicestringrequired
voiceAvatarUrlstringrequired
statusstringrequired
distancenumberrequired
rejectionsobject[]required
Show child attributes ›
idstring<uuid>required
verbatimstringrequired
voicestringrequired
voiceAvatarUrlstringrequired
statusstringrequired
distancenumberrequired
rejectionCategorystringrequired
reasonstringrequired
rejectedAtstringrequired
rejectedByNamestringrequired
rejectedByAvatarUrlstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/insights/{id}/similar' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "similar": [
      {
        "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "verbatim": "string",
        "voice": "string",
        "voiceAvatarUrl": "string",
        "status": "string",
        "distance": 0
      }
    ],
    "rejections": [
      {
        "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "verbatim": "string",
        "voice": "string",
        "voiceAvatarUrl": "string",
        "status": "string",
        "distance": 0,
        "rejectionCategory": "string",
        "reason": "string",
        "rejectedAt": "string",
        "rejectedByName": "string",
        "rejectedByAvatarUrl": "string"
      }
    ]
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/insights/patterns

Read the insight pattern board

The pattern board: semantic clusters of open insights that a human-triggered judge has already scored against the vision, strategies and objectives, plus the raw similarity graph (nodes and edges) behind them. `enabled` and `embeddingModelConfigured` tell you whether clustering is running at all; `unjudgedCount` is how many current clusters have no verdict yet; `truncated` means more open insights exist than the newest window considered.

Returns · 200 — Read the insight pattern board
oktruerequired
dataobjectrequired
Show child attributes ›
patternsobject[]required
Show child attributes ›
idstring<uuid>required
verdictIdstring<uuid>required
titlestringrequired
summarystringrequired
alignment"aligned" | "partial" | "misaligned"required
alignmentReasoningstringrequired
recommendationstringrequired
matchedOpportunityIdobjectrequired
matchedOpportunityTitlestringrequired
matchedOpportunityNumberobjectrequired
matchedObjectivesobject[]required
Show child attributes ›
idstring<uuid>required
titlestringrequired
status"suggested" | "actioned" | "dismissed"required
sizeintegerrequired
clientCountintegerrequired
memberIdsstring<uuid>[]required
membersobject[]required
Show child attributes ›
idstring<uuid>required
verbatimstringrequired
sourceobjectrequired
workItemsobject[]required
Show child attributes ›
idstring<uuid>required
entityType"opportunity" | "task"required
entityIdobjectrequired
refstringrequired
titlestringrequired
source"spawned" | "attached"required
unlinkedInsightCountintegerrequired
unlinkedInsightsobject[]required
Show child attributes ›
idstring<uuid>required
verbatimstringrequired
sourceobjectrequired
suggestedTagobjectrequired
unjudgedCountintegerrequired
candidatesobject[]required
Show child attributes ›
sizeintegerrequired
clientCountintegerrequired
previewstring[]required
rejectedobject[]required
Show child attributes ›
idstring<uuid>required
titlestringrequired
reasoningstringrequired
sizeintegerrequired
generatedAtstringrequired
nodesobject[]required
Show child attributes ›
idstring<uuid>required
verbatimstringrequired
sourceobjectrequired
statusstringrequired
moscowstringrequired
deadlinestringrequired
linkedbooleanrequired
clusterIdstringrequired
edgesobject[]required
Show child attributes ›
sourcestring<uuid>required
targetstring<uuid>required
weightnumberrequired
enabledbooleanrequired
embeddingModelConfiguredbooleanrequired
truncatedbooleanrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/insights/patterns' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "patterns": [
      {
        "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "verdictId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "title": "string",
        "summary": "string",
        "alignment": "aligned",
        "alignmentReasoning": "string",
        "recommendation": "string",
        "matchedOpportunityId": null,
        "matchedOpportunityTitle": "string",
        "matchedOpportunityNumber": null,
        "matchedObjectives": [
          {
            "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
            "title": "string"
          }
        ],
        "status": "suggested",
        "size": 0,
        "clientCount": 0,
        "memberIds": [
          "01J9Z3F4S0Z9KMQ4N6PYZR7C5A"
        ],
        "members": [
          {
            "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
            "verbatim": "string",
            "source": null
          }
        ],
        "workItems": [
          {
            "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
            "entityType": "opportunity",
            "entityId": null,
            "ref": "string",
            "title": "string",
            "source": "spawned"
          }
        ],
        "unlinkedInsightCount": 0,
        "unlinkedInsights": [
          {
            "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
            "verbatim": "string",
            "source": null
          }
        ],
        "suggestedTag": null
      }
    ],
    "unjudgedCount": 0,
    "candidates": [
      {
        "size": 0,
        "clientCount": 0,
        "preview": [
          "string"
        ]
      }
    ],
    "rejected": [
      {
        "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "title": "string",
        "reasoning": "string",
        "size": 0,
        "generatedAt": "string"
      }
    ],
    "nodes": [
      {
        "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "verbatim": "string",
        "source": null,
        "status": "string",
        "moscow": "string",
        "deadline": "string",
        "linked": true,
        "clusterId": "string"
      }
    ],
    "edges": [
      {
        "source": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "target": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "weight": 0
      }
    ],
    "enabled": true,
    "embeddingModelConfigured": true,
    "truncated": true
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/insights/patterns/{patternId}/accept

Accept an insight pattern (deprecated)

Deprecated compatibility action for clients from before atomic pattern promotion. It records the pattern as actioned but cannot record a work association because the legacy request carries no target. New callers must create work with patternPromotion or use attach-pattern-work.

Parameters
patternIdpath · stringrequired
patternId path parameter
Request body · required

Empty object.

Returns · 200 — Accept an insight pattern (deprecated)
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
acceptedbooleanrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/insights/patterns/{patternId}/accept' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "accepted": true
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/insights/patterns/{patternId}/dismiss

Dismiss an insight pattern

Dismiss a scored pattern. It leaves the board and suppresses future candidates that substantially overlap its members, so the same cluster does not come back every run.

Parameters
patternIdpath · stringrequired
patternId path parameter
Request body · required

Empty object.

Returns · 200 — Dismiss an insight pattern
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
dismissedtruerequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/insights/patterns/{patternId}/dismiss' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "dismissed": true
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/insights/patterns/{patternId}/attach-work

Attach a pattern to existing work

Action a suggested insight pattern by attaching its current insights to an existing opportunity or task. The lifecycle transition, work association, and evidence links commit atomically.

Parameters
patternIdpath · stringrequired
patternId path parameter
Request body · required
entityType"opportunity" | "task"required
entityIdstring<uuid>required
Returns · 200 — Attach a pattern to existing work
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
attachedtruerequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/insights/patterns/{patternId}/attach-work' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "attached": true
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/insights/patterns/{patternId}/link-insights

Link new pattern insights

Link selected, currently unlinked insights in an actioned pattern to one or more associated live work items. Membership and existing links are recomputed server-side, so stale or manually linked selections are safely skipped.

Parameters
patternIdpath · stringrequired
patternId path parameter
Request body · required
workItemIdsstring<uuid>[]required
Pattern-work association UUIDs
insightIdsstring<uuid>[]required
Selected current pattern insight UUIDs
Returns · 200 — Link new pattern insights
oktruerequired
dataobjectrequired
Show child attributes ›
linkedCountintegerrequired
remainingCountintegerrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/insights/patterns/{patternId}/link-insights' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "linkedCount": 0,
    "remainingCount": 0
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
Resource

Integrations

GET/api/v1/integrations

List integrations

List the org's installed integrations: connector type, name, status, health counters, and the non-secret config (watched channels, repo maps). Stored credentials are never returned. Import-only sources are excluded, matching the in-app directory.

Parameters
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
Returns · 200 — List integrations
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
connectorTypestringrequired
namestringrequired
configobjectrequired
externalAccountIdobjectrequired
statusstringrequired
installedByUserIdstring<uuid>required
agentUserIdobjectrequired
lastEventAtstringrequired
lastErrorAtstringrequired
consecutiveFailuresintegerrequired
lastRejectedAtstringrequired
rejectedCountintegerrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/integrations' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "connectorType": "string",
      "name": "string",
      "config": null,
      "externalAccountId": null,
      "status": "string",
      "installedByUserId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "agentUserId": null,
      "lastEventAt": "string",
      "lastErrorAt": "string",
      "consecutiveFailures": 0,
      "lastRejectedAt": "string",
      "rejectedCount": 0,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/integrations/{id}

Get an integration

Get one integration's connector type, name, status, health counters, and non-secret config. Stored credentials are never returned.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Get an integration
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
connectorTypestringrequired
namestringrequired
configobjectrequired
externalAccountIdobjectrequired
statusstringrequired
installedByUserIdstring<uuid>required
agentUserIdobjectrequired
lastEventAtstringrequired
lastErrorAtstringrequired
consecutiveFailuresintegerrequired
lastRejectedAtstringrequired
rejectedCountintegerrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/integrations/{id}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "connectorType": "string",
    "name": "string",
    "config": null,
    "externalAccountId": null,
    "status": "string",
    "installedByUserId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "agentUserId": null,
    "lastEventAt": "string",
    "lastErrorAt": "string",
    "consecutiveFailures": 0,
    "lastRejectedAt": "string",
    "rejectedCount": 0,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/integrations/{id}/events

List an integration's delivery log

The integration's inbound/outbound delivery ledger with cursor pagination, newest first: kind, status, dedup key, attempt count, error text, and timings. The raw third-party payload and request headers are deliberately withheld — they carry provider verification tokens and signature headers.

Parameters
idpath · stringrequired
id path parameter
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
statusquery · stringoptional
kindquery · stringoptional
Returns · 200 — List an integration's delivery log
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
integrationIdstring<uuid>required
kind"webhook" | "command" | "interaction" | "poll" | "outbound" | "backfill"required
status"received" | "processing" | "succeeded" | "failed" | "skipped_duplicate"required
dedupKeystringrequired
attemptsintegerrequired
errorstringrequired
receivedAtstringrequired
processedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/integrations/{id}/events' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "integrationId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "kind": "webhook",
      "status": "received",
      "dedupKey": "string",
      "attempts": 0,
      "error": "string",
      "receivedAt": "string",
      "processedAt": "string"
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
Resource

Messages

GET/api/v1/messages

List a room's messages

List a room's top-level messages, newest first, with cursor pagination (service-capped at 100 per page). Rows carry author, reactions, attachments, and thread reply counts; fetch a thread's replies with the thread action. Requires read access to the room (member, or any org user for an open group channel).

Parameters
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
roomIdquery · string<uuid>required
Room UUID
Returns · 200 — List a room's messages
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
roomIdstring<uuid>required
authorIdobjectrequired
authorNamestringrequired
authorAvatarUrlstringrequired
kind"user" | "system" | "vibe" | "customer_update"required
bodystringrequired
payloadobjectrequired
editedAtstringrequired
pinnedAtstringrequired
createdAtstringrequired
replyCountintegerrequired
lastReplyAtstringrequired
reactionsobject[]required
Show child attributes ›
emojistringrequired
countintegerrequired
userIdsstring<uuid>[]required
userNamesstring[]required
hasMebooleanrequired
attachmentsobject[]required
Show child attributes ›
fileIdstring<uuid>required
originalNamestringrequired
mimeTypestringrequired
sizeBytesnumberrequired
thumbnailKeystringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/messages' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "roomId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "authorId": null,
      "authorName": "string",
      "authorAvatarUrl": "string",
      "kind": "user",
      "body": "string",
      "payload": null,
      "editedAt": "string",
      "pinnedAt": "string",
      "createdAt": "string",
      "replyCount": 0,
      "lastReplyAt": "string",
      "reactions": [
        {
          "emoji": "string",
          "count": 0,
          "userIds": [
            "01J9Z3F4S0Z9KMQ4N6PYZR7C5A"
          ],
          "userNames": [
            "string"
          ],
          "hasMe": true
        }
      ],
      "attachments": [
        {
          "fileId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
          "originalName": "string",
          "mimeType": "string",
          "sizeBytes": 0,
          "thumbnailKey": "string"
        }
      ]
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/messages

Post a message

Post a message to a room you can read, authored by the key's user. Pass parentId (a top-level message UUID) to reply in its thread; threads are two-level. @Name mentions in the body notify the named org members.

Request body · required
roomIdstring<uuid>required
Room UUID
bodystringrequired
Message body (markdown, max 10000 chars)
parentIdstring<uuid>optional
Top-level message UUID to reply to in its thread
Returns · 201 — Post a message
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
roomIdstring<uuid>required
authorIdobjectrequired
authorNamestringrequired
authorAvatarUrlstringrequired
kind"user" | "system" | "vibe" | "customer_update"required
bodystringrequired
payloadobjectrequired
editedAtstringrequired
pinnedAtstringrequired
createdAtstringrequired
replyCountintegerrequired
lastReplyAtstringrequired
reactionsobject[]required
Show child attributes ›
emojistringrequired
countintegerrequired
userIdsstring<uuid>[]required
userNamesstring[]required
hasMebooleanrequired
attachmentsobject[]required
Show child attributes ›
fileIdstring<uuid>required
originalNamestringrequired
mimeTypestringrequired
sizeBytesnumberrequired
thumbnailKeystringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/messages' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "roomId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "authorId": null,
    "authorName": "string",
    "authorAvatarUrl": "string",
    "kind": "user",
    "body": "string",
    "payload": null,
    "editedAt": "string",
    "pinnedAt": "string",
    "createdAt": "string",
    "replyCount": 0,
    "lastReplyAt": "string",
    "reactions": [
      {
        "emoji": "string",
        "count": 0,
        "userIds": [
          "01J9Z3F4S0Z9KMQ4N6PYZR7C5A"
        ],
        "userNames": [
          "string"
        ],
        "hasMe": true
      }
    ],
    "attachments": [
      {
        "fileId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "originalName": "string",
        "mimeType": "string",
        "sizeBytes": 0,
        "thumbnailKey": "string"
      }
    ]
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/messages/{id}/thread

List a message's thread replies

List the replies threaded under a top-level message, newest first, with cursor pagination. Requires read access to the message's room.

Parameters
idpath · stringrequired
id path parameter
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
Returns · 200 — List a message's thread replies
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
roomIdstring<uuid>required
authorIdobjectrequired
authorNamestringrequired
authorAvatarUrlstringrequired
kind"user" | "system" | "vibe" | "customer_update"required
bodystringrequired
payloadobjectrequired
editedAtstringrequired
pinnedAtstringrequired
createdAtstringrequired
replyCountintegerrequired
lastReplyAtstringrequired
reactionsobject[]required
Show child attributes ›
emojistringrequired
countintegerrequired
userIdsstring<uuid>[]required
userNamesstring[]required
hasMebooleanrequired
attachmentsobject[]required
Show child attributes ›
fileIdstring<uuid>required
originalNamestringrequired
mimeTypestringrequired
sizeBytesnumberrequired
thumbnailKeystringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/messages/{id}/thread' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "roomId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "authorId": null,
      "authorName": "string",
      "authorAvatarUrl": "string",
      "kind": "user",
      "body": "string",
      "payload": null,
      "editedAt": "string",
      "pinnedAt": "string",
      "createdAt": "string",
      "replyCount": 0,
      "lastReplyAt": "string",
      "reactions": [
        {
          "emoji": "string",
          "count": 0,
          "userIds": [
            "01J9Z3F4S0Z9KMQ4N6PYZR7C5A"
          ],
          "userNames": [
            "string"
          ],
          "hasMe": true
        }
      ],
      "attachments": [
        {
          "fileId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
          "originalName": "string",
          "mimeType": "string",
          "sizeBytes": 0,
          "thumbnailKey": "string"
        }
      ]
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/messages/pinned

List pinned messages

List pinned messages, most recently pinned first, with cursor pagination. Pass roomId to scope to one room you can read; omit it for every pin across the rooms you are a member of. Rows are message rows — read the room's name with get_room.

Parameters
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
roomIdquery · string<uuid>optional
Scope to a single room
Returns · 200 — List pinned messages
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
roomIdstring<uuid>required
authorIdobjectrequired
authorNamestringrequired
authorAvatarUrlstringrequired
kind"user" | "system" | "vibe" | "customer_update"required
bodystringrequired
payloadobjectrequired
editedAtstringrequired
pinnedAtstringrequired
createdAtstringrequired
replyCountintegerrequired
lastReplyAtstringrequired
reactionsobject[]required
Show child attributes ›
emojistringrequired
countintegerrequired
userIdsstring<uuid>[]required
userNamesstring[]required
hasMebooleanrequired
attachmentsobject[]required
Show child attributes ›
fileIdstring<uuid>required
originalNamestringrequired
mimeTypestringrequired
sizeBytesnumberrequired
thumbnailKeystringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/messages/pinned' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "roomId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "authorId": null,
      "authorName": "string",
      "authorAvatarUrl": "string",
      "kind": "user",
      "body": "string",
      "payload": null,
      "editedAt": "string",
      "pinnedAt": "string",
      "createdAt": "string",
      "replyCount": 0,
      "lastReplyAt": "string",
      "reactions": [
        {
          "emoji": "string",
          "count": 0,
          "userIds": [
            "01J9Z3F4S0Z9KMQ4N6PYZR7C5A"
          ],
          "userNames": [
            "string"
          ],
          "hasMe": true
        }
      ],
      "attachments": [
        {
          "fileId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
          "originalName": "string",
          "mimeType": "string",
          "sizeBytes": 0,
          "thumbnailKey": "string"
        }
      ]
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
PATCH/api/v1/messages/{id}

Update a message

Rewrite the body of one of your own messages; it is marked edited. Only the author may edit a message, and system messages cannot be edited. Returns the same enriched message shape create and list return.

Parameters
idpath · stringrequired
id path parameter
Request body · required
bodystringrequired
Message body (markdown, max 10000 chars)
Returns · 200 — Update a message
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
roomIdstring<uuid>required
authorIdobjectrequired
authorNamestringrequired
authorAvatarUrlstringrequired
kind"user" | "system" | "vibe" | "customer_update"required
bodystringrequired
payloadobjectrequired
editedAtstringrequired
pinnedAtstringrequired
createdAtstringrequired
replyCountintegerrequired
lastReplyAtstringrequired
reactionsobject[]required
Show child attributes ›
emojistringrequired
countintegerrequired
userIdsstring<uuid>[]required
userNamesstring[]required
hasMebooleanrequired
attachmentsobject[]required
Show child attributes ›
fileIdstring<uuid>required
originalNamestringrequired
mimeTypestringrequired
sizeBytesnumberrequired
thumbnailKeystringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
PATCH request
curl -X PATCH 'https://www.telos-app.com/api/v1/messages/{id}' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "roomId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "authorId": null,
    "authorName": "string",
    "authorAvatarUrl": "string",
    "kind": "user",
    "body": "string",
    "payload": null,
    "editedAt": "string",
    "pinnedAt": "string",
    "createdAt": "string",
    "replyCount": 0,
    "lastReplyAt": "string",
    "reactions": [
      {
        "emoji": "string",
        "count": 0,
        "userIds": [
          "01J9Z3F4S0Z9KMQ4N6PYZR7C5A"
        ],
        "userNames": [
          "string"
        ],
        "hasMe": true
      }
    ],
    "attachments": [
      {
        "fileId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "originalName": "string",
        "mimeType": "string",
        "sizeBytes": 0,
        "thumbnailKey": "string"
      }
    ]
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
DELETE/api/v1/messages/{id}

Delete a message

Delete one of your own messages (soft delete; attachments are swept). Only the author may delete it on this surface.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Delete a message
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
deletedtruerequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
DELETE request
curl -X DELETE 'https://www.telos-app.com/api/v1/messages/{id}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "deleted": true
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/messages/{id}/pinned

Pin or unpin a message

Pin a message to its room, or unpin it. Absolute, not a toggle: pass pinned true or false and repeating the call leaves the same state. Any member who can read the room can curate its pins.

Parameters
idpath · stringrequired
id path parameter
Request body · required
pinnedobjectrequired
true pins the message, false unpins it
Returns · 200 — Pin or unpin a message
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
pinnedbooleanrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/messages/{id}/pinned' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "pinned": true
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/messages/{id}/reactions

Add or remove your reaction to a message

Set whether the authenticated user reacts to a message with an emoji. Absolute, not a toggle: `on` is the state you want, so a retried call never silently removes the reaction it just added. Returns the message's full reaction aggregate.

Parameters
idpath · stringrequired
id path parameter
Request body · required
emojistringrequired
Emoji to react with
onobjectrequired
true adds your reaction, false removes it
Returns · 200 — Add or remove your reaction to a message
oktruerequired
dataobjectrequired
Show child attributes ›
messageIdstring<uuid>required
reactionsobject[]required
Show child attributes ›
emojistringrequired
countintegerrequired
userIdsstring<uuid>[]required
userNamesstring[]required
hasMebooleanrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/messages/{id}/reactions' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "messageId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "reactions": [
      {
        "emoji": "string",
        "count": 0,
        "userIds": [
          "01J9Z3F4S0Z9KMQ4N6PYZR7C5A"
        ],
        "userNames": [
          "string"
        ],
        "hasMe": true
      }
    ]
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
Resource

Notifications

GET/api/v1/notifications

List notifications

List the authenticated user's notifications, newest first, with cursor pagination. Filter to unread only, pinned only, or a set of notification types.

Parameters
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
unreadOnlyqueryoptional
Only return unread notifications
pinnedOnlyqueryoptional
Only return pinned notifications
typesqueryoptional
Only return these notification types. JSON array on MCP, comma-separated on REST and CLI. One of: strategy.published, strategy.updated, vision.published, customer.update_posted, customer.went_live, insight.assigned, insight.needs_context, insight.rejected, opportunity.completed, opportunity.cancelled, objective.committed_date_breach, cycle.scope_changed, template.step_assigned, task.handoff, task.agent_run_completed, task.agent_run_failed, task.agent_run_cancelled, comment.mention, comment.thread_reply, doc.mention, room.invited, room.mentioned, community.mentioned, good_vibes.shoutout
Returns · 200 — List notifications
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
userIdstring<uuid>required
typestringrequired
entityTypestringrequired
entityIdstring<uuid>required
actorIdobjectrequired
sourceIdobjectrequired
titlestringrequired
bodystringrequired
linkUrlobjectrequired
readAtstringrequired
pinnedAtstringrequired
groupKeyobjectrequired
createdAtstringrequired
actorobjectrequired
myReactionstringrequired
repliedbooleanrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/notifications' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "userId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "type": "string",
      "entityType": "string",
      "entityId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "actorId": null,
      "sourceId": null,
      "title": "string",
      "body": "string",
      "linkUrl": null,
      "readAt": "string",
      "pinnedAt": "string",
      "groupKey": null,
      "createdAt": "string",
      "actor": null,
      "myReaction": "string",
      "replied": true
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/notifications/unread-count

Get unread notification count

Count the authenticated user's unread notifications.

Returns · 200 — Get unread notification count
oktruerequired
dataobjectrequired
Show child attributes ›
countintegerrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/notifications/unread-count' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "count": 0
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/notifications/{id}/read

Mark a notification read

Mark one of your notifications read.

Parameters
idpath · stringrequired
id path parameter
Request body · required

Empty object.

Returns · 200 — Mark a notification read
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
userIdstring<uuid>required
typestringrequired
entityTypestringrequired
entityIdstring<uuid>required
actorIdobjectrequired
sourceIdobjectrequired
titlestringrequired
bodystringrequired
linkUrlobjectrequired
readAtstringrequired
pinnedAtstringrequired
groupKeyobjectrequired
createdAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/notifications/{id}/read' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "userId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "type": "string",
    "entityType": "string",
    "entityId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "actorId": null,
    "sourceId": null,
    "title": "string",
    "body": "string",
    "linkUrl": null,
    "readAt": "string",
    "pinnedAt": "string",
    "groupKey": null,
    "createdAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/notifications/read-all

Mark all notifications read

Mark all of your notifications read.

Request body · required

Empty object.

Returns · 200 — Mark all notifications read
oktruerequired
dataobjectrequired
Show child attributes ›
oktruerequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/notifications/read-all' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "ok": true
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/notifications/{id}/pin

Pin a notification

Pin one of your notifications so it stays at the top of the inbox.

Parameters
idpath · stringrequired
id path parameter
Request body · required

Empty object.

Returns · 200 — Pin a notification
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
userIdstring<uuid>required
typestringrequired
entityTypestringrequired
entityIdstring<uuid>required
actorIdobjectrequired
sourceIdobjectrequired
titlestringrequired
bodystringrequired
linkUrlobjectrequired
readAtstringrequired
pinnedAtstringrequired
groupKeyobjectrequired
createdAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/notifications/{id}/pin' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "userId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "type": "string",
    "entityType": "string",
    "entityId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "actorId": null,
    "sourceId": null,
    "title": "string",
    "body": "string",
    "linkUrl": null,
    "readAt": "string",
    "pinnedAt": "string",
    "groupKey": null,
    "createdAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/notifications/{id}/unpin

Unpin a notification

Unpin one of your notifications.

Parameters
idpath · stringrequired
id path parameter
Request body · required

Empty object.

Returns · 200 — Unpin a notification
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
userIdstring<uuid>required
typestringrequired
entityTypestringrequired
entityIdstring<uuid>required
actorIdobjectrequired
sourceIdobjectrequired
titlestringrequired
bodystringrequired
linkUrlobjectrequired
readAtstringrequired
pinnedAtstringrequired
groupKeyobjectrequired
createdAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/notifications/{id}/unpin' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "userId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "type": "string",
    "entityType": "string",
    "entityId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "actorId": null,
    "sourceId": null,
    "title": "string",
    "body": "string",
    "linkUrl": null,
    "readAt": "string",
    "pinnedAt": "string",
    "groupKey": null,
    "createdAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/notifications/{id}/unsubscribe

Unsubscribe at notification source

Unsubscribe from the entity a notification came from, muting its future notifications for you.

Parameters
idpath · stringrequired
id path parameter
Request body · required

Empty object.

Returns · 200 — Unsubscribe at notification source
oktruerequired
dataobjectrequired
Show child attributes ›
entityTypestringrequired
entityIdstring<uuid>required
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/notifications/{id}/unsubscribe' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "entityType": "string",
    "entityId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
Resource

Prd Templates

GET/api/v1/prd-templates

List PRD templates

List the PRD templates visible to the key's user: shared (org-wide) templates plus those owned by the user's teams. Pass allTeams to read the whole org catalog instead, which additionally requires prd_template:update.

Parameters
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
allTeamsqueryoptional
Return every template in the org, including other teams' (requires prd_template:update)
Returns · 200 — List PRD templates
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
teamIdobjectrequired
namestringrequired
contentstringrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/prd-templates' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "teamId": null,
      "name": "string",
      "content": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/prd-templates

Create a PRD template

Create a PRD template (markdown scaffold for opportunity PRDs). teamId scopes it to a team; omit for a shared org-wide template, which requires the prd_template:update capability.

Request body · required
namestringrequired
contentstringrequired
teamIdobjectoptional
Returns · 201 — Create a PRD template
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
teamIdobjectrequired
namestringrequired
contentstringrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/prd-templates' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "teamId": null,
    "name": "string",
    "content": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/prd-templates/{id}

Get a PRD template

Get one PRD template: its name, markdown content, and team scope (teamId null means shared org-wide). Visible when the template is shared or owned by one of the key user's teams. Writing it into an opportunity is apply_opportunity_prd_template.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Get a PRD template
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
teamIdobjectrequired
namestringrequired
contentstringrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/prd-templates/{id}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "teamId": null,
    "name": "string",
    "content": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
PATCH/api/v1/prd-templates/{id}

Update a PRD template

Update a PRD template's name, content, or team scope.

Parameters
idpath · stringrequired
id path parameter
Request body · required
namestringoptional
contentstringoptional
teamIdobjectoptional
Returns · 200 — Update a PRD template
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
teamIdobjectrequired
namestringrequired
contentstringrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
PATCH request
curl -X PATCH 'https://www.telos-app.com/api/v1/prd-templates/{id}' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "teamId": null,
    "name": "string",
    "content": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
DELETE/api/v1/prd-templates/{id}

Delete a PRD template

Delete a PRD template. Opportunities that already applied it keep their PRD content.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Delete a PRD template
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
deletedtruerequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
DELETE request
curl -X DELETE 'https://www.telos-app.com/api/v1/prd-templates/{id}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "deleted": true
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
Resource

Roles

GET/api/v1/roles

List roles

The org's roles with the permission grants each one confers, so you can see who can do what before proposing a change. Creating, renaming, deleting a role and rewriting its grants are in-app only.

Parameters
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
Returns · 200 — List roles
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
slugstringrequired
displayNamestringrequired
isSystembooleanrequired
permissionsstring[]required
grantsobject[]required
Show child attributes ›
permissionstringrequired
scope"global" | "team"required
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/roles' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "slug": "string",
      "displayName": "string",
      "isSystem": true,
      "permissions": [
        "string"
      ],
      "grants": [
        {
          "permission": "string",
          "scope": "global"
        }
      ]
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
Resource

Rooms

GET/api/v1/rooms

List rooms

List rooms with cursor pagination. Scope 'mine' (default) returns the rooms you are a member of (DMs, group channels, system rooms) with unread counts and your per-room state, most recently active first. Scope 'open' returns every live open group channel in the org — the channel browser — with isSubscribed telling you which ones you are already in; the per-membership fields are null on those rows. Archived channels appear in neither scope.

Parameters
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
scopequery · stringoptional
'mine' (default) for your rooms, 'open' for joinable open channels
Returns · 200 — List rooms
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
kindstringrequired
visibilitystringrequired
systemTypeobjectrequired
nameobjectrequired
slugstringrequired
dmKeyobjectrequired
descriptionstringrequired
createdByIdobjectrequired
archivedAtstringrequired
lastMessageAtstringrequired
createdAtstringrequired
updatedAtstringrequired
unreadCountintegerrequired
pinnedAtstringrequired
notificationLevelobjectrequired
lastReadAtstringrequired
myRoleobjectrequired
dmUserobjectrequired
draftBodystringrequired
draftUpdatedAtstringrequired
isSubscribedbooleanrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/rooms' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "kind": "string",
      "visibility": "string",
      "systemType": null,
      "name": null,
      "slug": "string",
      "dmKey": null,
      "description": "string",
      "createdById": null,
      "archivedAt": "string",
      "lastMessageAt": "string",
      "createdAt": "string",
      "updatedAt": "string",
      "unreadCount": 0,
      "pinnedAt": "string",
      "notificationLevel": null,
      "lastReadAt": "string",
      "myRole": null,
      "dmUser": null,
      "draftBody": "string",
      "draftUpdatedAt": "string",
      "isSubscribed": true
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/rooms

Create a group channel

Create a group channel with at least one other org member; the creator becomes its admin. Visibility 'open' (default) lets any org user read and join; 'private' is invite-only. For a DM use find_or_create_dm.

Request body · required
namestringrequired
descriptionstringoptional
memberIdsstring<uuid>[]required
visibility"open" | "private"optional
Returns · 201 — Create a group channel
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
kindstringrequired
visibilitystringrequired
systemTypeobjectrequired
nameobjectrequired
slugstringrequired
dmKeyobjectrequired
descriptionstringrequired
createdByIdobjectrequired
archivedAtstringrequired
lastMessageAtstringrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/rooms' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "kind": "string",
    "visibility": "string",
    "systemType": null,
    "name": null,
    "slug": "string",
    "dmKey": null,
    "description": "string",
    "createdById": null,
    "archivedAt": "string",
    "lastMessageAt": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/rooms/{id}

Get a room

Get a room by UUID with your membership role. Members always read; any org user reads an open group channel; a private group, DM, or system room without a membership row is forbidden.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Get a room
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
kindstringrequired
visibilitystringrequired
systemTypeobjectrequired
nameobjectrequired
slugstringrequired
dmKeyobjectrequired
descriptionstringrequired
createdByIdobjectrequired
archivedAtstringrequired
lastMessageAtstringrequired
createdAtstringrequired
updatedAtstringrequired
myRoleobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/rooms/{id}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "kind": "string",
    "visibility": "string",
    "systemType": null,
    "name": null,
    "slug": "string",
    "dmKey": null,
    "description": "string",
    "createdById": null,
    "archivedAt": "string",
    "lastMessageAt": "string",
    "createdAt": "string",
    "updatedAt": "string",
    "myRole": null
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
PATCH/api/v1/rooms/{id}

Update a group channel

Rename a group channel or edit its description. Room-admin only; DMs and system rooms cannot be edited.

Parameters
idpath · stringrequired
id path parameter
Request body · required
namestringoptional
descriptionstringoptional
Returns · 200 — Update a group channel
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
kindstringrequired
visibilitystringrequired
systemTypeobjectrequired
nameobjectrequired
slugstringrequired
dmKeyobjectrequired
descriptionstringrequired
createdByIdobjectrequired
archivedAtstringrequired
lastMessageAtstringrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
PATCH request
curl -X PATCH 'https://www.telos-app.com/api/v1/rooms/{id}' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "kind": "string",
    "visibility": "string",
    "systemType": null,
    "name": null,
    "slug": "string",
    "dmKey": null,
    "description": "string",
    "createdById": null,
    "archivedAt": "string",
    "lastMessageAt": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/rooms/{id}/archive

Archive a group channel

Archive a group channel, removing it from everyone's room list. Terminal: rooms have no hard delete. Room-admin only; DMs and system rooms cannot be archived.

Parameters
idpath · stringrequired
id path parameter
Request body · required

Empty object.

Returns · 200 — Archive a group channel
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
archivedtruerequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/rooms/{id}/archive' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "archived": true
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/rooms/dm

Open a DM with an org member

Get the direct-message room you share with another org member, creating it if it does not exist yet. Idempotent: the same pair always resolves to the same room. You cannot DM yourself, and the other user must be in your org.

Request body · required
otherUserIdstring<uuid>required
Org member to open the DM with
Returns · 200 — Open a DM with an org member
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
kindstringrequired
visibilitystringrequired
systemTypeobjectrequired
nameobjectrequired
slugstringrequired
dmKeyobjectrequired
descriptionstringrequired
createdByIdobjectrequired
archivedAtstringrequired
lastMessageAtstringrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/rooms/dm' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "kind": "string",
    "visibility": "string",
    "systemType": null,
    "name": null,
    "slug": "string",
    "dmKey": null,
    "description": "string",
    "createdById": null,
    "archivedAt": "string",
    "lastMessageAt": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/rooms/{id}/members

List a room's members

List the members of a room you can read, oldest join first, with each member's room role. Requires read access to the room (member, or any org user for an open group channel).

Parameters
idpath · stringrequired
id path parameter
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
Returns · 200 — List a room's members
oktruerequired
dataobject[]required
Show child attributes ›
userIdstring<uuid>required
namestringrequired
avatarUrlstringrequired
role"member" | "admin"required
joinedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/rooms/{id}/members' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "userId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "name": "string",
      "avatarUrl": "string",
      "role": "member",
      "joinedAt": "string"
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/rooms/{id}/members

Add a member to a group channel

Add an org member to a group channel. Room-admin only, and the user must be in your org; DMs and system rooms refuse membership changes. Idempotent: adding an existing member is a no-op.

Parameters
idpath · stringrequired
id path parameter
Request body · required
userIdstring<uuid>required
Org member to add
Returns · 201 — Add a member to a group channel
oktruerequired
dataobjectrequired
Show child attributes ›
roomIdstring<uuid>required
userIdstring<uuid>required
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/rooms/{id}/members' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "roomId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "userId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
DELETE/api/v1/rooms/{id}/members/{userId}

Remove a member from a group channel

Remove a member from a group channel. Room-admin only, and an admin cannot remove themselves (hand the room off first); DMs and system rooms refuse membership changes.

Parameters
idpath · stringrequired
id path parameter
userIdpath · stringrequired
userId path parameter
Returns · 200 — Remove a member from a group channel
oktruerequired
dataobjectrequired
Show child attributes ›
roomIdstring<uuid>required
userIdstring<uuid>required
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
DELETE request
curl -X DELETE 'https://www.telos-app.com/api/v1/rooms/{id}/members/{userId}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "roomId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "userId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
PATCH/api/v1/rooms/{id}/membership

Set your own membership state in a room

Set the authenticated user's own state on a room: join or leave an open group channel (joined), pin it to the top of your room list (pinned), and choose how much it notifies you (notificationLevel). Every field is absolute, not a toggle, so repeating the call is a no-op. Fields apply in the order join, pin, notification level, leave; you must be able to read the room at all, pinning or muting a room you are not a member of is forbidden, and only live (non-archived) open group channels can be joined this way.

Parameters
idpath · stringrequired
id path parameter
Request body · required
joinedobjectoptional
true joins an open group channel, false leaves it
pinnedobjectoptional
Pin the room to the top of your list
notificationLevel"all" | "mentions" | "muted"optional
How much the room notifies you: all, mentions, muted
Returns · 200 — Set your own membership state in a room
oktruerequired
dataobjectrequired
Show child attributes ›
roomIdstring<uuid>required
userIdstring<uuid>required
joinedbooleanrequired
pinnedbooleanrequired
notificationLevelobjectrequired
roleobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
PATCH request
curl -X PATCH 'https://www.telos-app.com/api/v1/rooms/{id}/membership' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "roomId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "userId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "joined": true,
    "pinned": true,
    "notificationLevel": null,
    "role": null
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
Resource

Strategies

GET/api/v1/strategies

List strategies

List strategies with cursor pagination. Optionally filter by status (draft, active, archived).

Parameters
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
statusquery · stringoptional
Strategy status filter
Returns · 200 — List strategies
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
namestringrequired
numberintegerrequired
contentstringrequired
versionintegerrequired
ownerIdobjectrequired
statusstringrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/strategies' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "name": "string",
      "number": 0,
      "content": "string",
      "version": 0,
      "ownerId": null,
      "status": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/strategies

Create a strategy

Create a strategy (name plus a markdown content body). Starts as a draft.

Request body · required
namestringrequired
contentstringoptional
status"draft" | "active" | "archived"optional
Returns · 201 — Create a strategy
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
namestringrequired
numberintegerrequired
contentstringrequired
versionintegerrequired
ownerIdobjectrequired
statusstringrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/strategies' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "name": "string",
    "number": 0,
    "content": "string",
    "version": 0,
    "ownerId": null,
    "status": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/strategies/{id}

Get a strategy

Get a strategy by UUID or by its per-org ref (STR-12).

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Get a strategy
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
namestringrequired
numberintegerrequired
contentstringrequired
versionintegerrequired
ownerIdobjectrequired
statusstringrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/strategies/{id}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "name": "string",
    "number": 0,
    "content": "string",
    "version": 0,
    "ownerId": null,
    "status": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
PATCH/api/v1/strategies/{id}

Update a strategy

Update a strategy's name or content. An optional changeNote labels the version this edit creates. Owner-only; ACL enforced by the service.

Parameters
idpath · stringrequired
id path parameter
Request body · required
namestringoptional
contentstringoptional
changeNotestringoptional
Returns · 200 — Update a strategy
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
namestringrequired
numberintegerrequired
contentstringrequired
versionintegerrequired
ownerIdobjectrequired
statusstringrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
PATCH request
curl -X PATCH 'https://www.telos-app.com/api/v1/strategies/{id}' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "name": "string",
    "number": 0,
    "content": "string",
    "version": 0,
    "ownerId": null,
    "status": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/strategies/{id}/publish

Publish a strategy

Publish a draft strategy, making it the active version. Owner-only; ACL enforced by the service.

Parameters
idpath · stringrequired
id path parameter
Request body · required

Empty object.

Returns · 200 — Publish a strategy
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
namestringrequired
numberintegerrequired
contentstringrequired
versionintegerrequired
ownerIdobjectrequired
statusstringrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/strategies/{id}/publish' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "name": "string",
    "number": 0,
    "content": "string",
    "version": 0,
    "ownerId": null,
    "status": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/strategies/{id}/archive

Archive a strategy

Archive a strategy, retiring it from the active set. Owner-only; ACL enforced by the service.

Parameters
idpath · stringrequired
id path parameter
Request body · required

Empty object.

Returns · 200 — Archive a strategy
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
namestringrequired
numberintegerrequired
contentstringrequired
versionintegerrequired
ownerIdobjectrequired
statusstringrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/strategies/{id}/archive' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "name": "string",
    "number": 0,
    "content": "string",
    "version": 0,
    "ownerId": null,
    "status": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/strategies/{id}/versions

List a strategy's version history

Version snapshots of a strategy, newest first, with cursor pagination. Every content edit creates one.

Parameters
idpath · stringrequired
id path parameter
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
Returns · 200 — List a strategy's version history
oktruerequired
dataobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/strategies/{id}/versions' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": null,
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/strategies/{id}/versions/{version}/rename

Rename a strategy version

Label one snapshot in a strategy's version history. An empty note clears the label, so the version falls back to 'v{n}'. Owner-only; ACL enforced by the service.

Parameters
idpath · stringrequired
id path parameter
versionpath · stringrequired
version path parameter
Request body · required
notestringrequired
Version label; empty clears it
Returns · 200 — Rename a strategy version
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
strategyIdstring<uuid>required
versionintegerrequired
namestringrequired
contentstringrequired
changeNotestringrequired
createdAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/strategies/{id}/versions/{version}/rename' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "strategyId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "version": 0,
    "name": "string",
    "content": "string",
    "changeNote": "string",
    "createdAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
Resource

Subscriptions

GET/api/v1/subscriptions

Check whether you follow an entity

Report whether the authenticated user currently follows an entity, i.e. receives its notifications. False covers both never-subscribed and explicitly muted.

Returns · 200 — Check whether you follow an entity
oktruerequired
dataobjectrequired
Show child attributes ›
entityTypestringrequired
entityIdstring<uuid>required
subscribedbooleanrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/subscriptions' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "entityType": "string",
    "entityId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "subscribed": true
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/subscriptions

Follow or unfollow an entity

Set whether the authenticated user follows an entity and receives its notifications. Absolute, not a toggle: `subscribed` is the state you want, so repeating the call is a no-op. Requires the read capability of the entity you are following. Unfollowing mutes the entity permanently for you — participation (commenting, being assigned) will not silently re-subscribe you.

Request body · required
entityType"opportunity" | "task" | "comment" | "customer" | "customer_update" | "customer_document" | "insight" | "vision" | "strategy" | "objective" | "metric" | "team" | "template" | "opportunity_risk" | "file"required
Entity to follow. One of: opportunity, task, comment, customer, customer_update, customer_document, insight, vision, strategy, objective, metric, team, template, opportunity_risk, file
entityIdstring<uuid>required
Entity UUID
subscribedobjectrequired
true follows the entity, false mutes it
Returns · 200 — Follow or unfollow an entity
oktruerequired
dataobjectrequired
Show child attributes ›
entityTypestringrequired
entityIdstring<uuid>required
subscribedbooleanrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/subscriptions' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "entityType": "string",
    "entityId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "subscribed": true
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
Resource

Tag Themes

GET/api/v1/tag-themes

List tag themes

List the themes tags can be grouped under, with the colour each theme lends its tags.

Parameters
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
Returns · 200 — List tag themes
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
namestringrequired
colorstringrequired
createdByUserIdobjectrequired
createdAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/tag-themes' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "name": "string",
      "color": "string",
      "createdByUserId": null,
      "createdAt": "string"
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/tag-themes

Create a tag theme

Create a theme to group tags under (e.g. 'Clients', 'Risk'). Its colour becomes the default colour of every tag in it.

Request body · required
namestringrequired
colorobjectoptional
Returns · 201 — Create a tag theme
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
namestringrequired
colorstringrequired
createdByUserIdobjectrequired
createdAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/tag-themes' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "name": "string",
    "color": "string",
    "createdByUserId": null,
    "createdAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
PATCH/api/v1/tag-themes/{id}

Update a tag theme

Rename a theme or change the colour it lends its tags.

Parameters
idpath · stringrequired
id path parameter
Request body · required
namestringoptional
colorobjectoptional
Returns · 200 — Update a tag theme
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
namestringrequired
colorstringrequired
createdByUserIdobjectrequired
createdAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
PATCH request
curl -X PATCH 'https://www.telos-app.com/api/v1/tag-themes/{id}' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "name": "string",
    "color": "string",
    "createdByUserId": null,
    "createdAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
DELETE/api/v1/tag-themes/{id}

Delete a tag theme

Delete a theme. Its tags survive and fall back to their own colour; nothing is deleted with it.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Delete a tag theme
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
deletedtruerequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
DELETE request
curl -X DELETE 'https://www.telos-app.com/api/v1/tag-themes/{id}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "deleted": true
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
Resource

Tags

GET/api/v1/tags

List tags

List every tag alphabetically with usage counts so you can cluster insights onto existing tags instead of minting duplicates. Follow nextCursor until hasMore is false.

Parameters
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
Returns · 200 — List tags
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
namestringrequired
themeIdobjectrequired
themeNamestringrequired
themeColorstringrequired
colorstringrequired
effectiveColorstringrequired
createdByUserIdobjectrequired
createdAtstringrequired
usageCountintegerrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/tags' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "name": "string",
      "themeId": null,
      "themeName": "string",
      "themeColor": "string",
      "color": "string",
      "effectiveColor": "string",
      "createdByUserId": null,
      "createdAt": "string",
      "usageCount": 0
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/tags

Create a tag

Create a tag for clustering insights. List existing tags first (list_tags) and reuse them rather than minting duplicates.

Request body · required
namestringrequired
themeIdobjectoptional
colorobjectoptional
Returns · 201 — Create a tag
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
namestringrequired
themeIdobjectrequired
themeNamestringrequired
themeColorstringrequired
colorstringrequired
effectiveColorstringrequired
createdByUserIdobjectrequired
createdAtstringrequired
usageCountintegerrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/tags' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "name": "string",
    "themeId": null,
    "themeName": "string",
    "themeColor": "string",
    "color": "string",
    "effectiveColor": "string",
    "createdByUserId": null,
    "createdAt": "string",
    "usageCount": 0
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
PATCH/api/v1/tags/{id}

Update a tag

Rename a tag or change its colour. Renaming keeps every insight, task, and opportunity attached to it.

Parameters
idpath · stringrequired
id path parameter
Request body · required
namestringoptional
colorobjectoptional
Returns · 200 — Update a tag
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
namestringrequired
themeIdobjectrequired
themeNamestringrequired
themeColorstringrequired
colorstringrequired
effectiveColorstringrequired
createdByUserIdobjectrequired
createdAtstringrequired
usageCountintegerrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
PATCH request
curl -X PATCH 'https://www.telos-app.com/api/v1/tags/{id}' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "name": "string",
    "themeId": null,
    "themeName": "string",
    "themeColor": "string",
    "color": "string",
    "effectiveColor": "string",
    "createdByUserId": null,
    "createdAt": "string",
    "usageCount": 0
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
DELETE/api/v1/tags/{id}

Delete a tag

Delete a tag and detach it from everything it labelled. Check usageCount on list first: the rows it tagged keep no record of it.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Delete a tag
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
deletedtruerequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
DELETE request
curl -X DELETE 'https://www.telos-app.com/api/v1/tags/{id}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "deleted": true
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
Resource

Task Statuses

GET/api/v1/task-statuses

List task statuses

List the workspace's concrete task statuses in stable lifecycle and custom position order.

Parameters
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
includeArchivedqueryoptional
Returns · 200 — List task statuses
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
type"backlog" | "todo" | "in_progress" | "completed" | "cancelled" | "duplicate"required
namestringrequired
colorstringrequired
descriptionstringrequired
positionnumberrequired
archivedAtstringrequired
createdAtstringrequired
updatedAtstringrequired
taskCountintegeroptional
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/task-statuses' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "type": "backlog",
      "name": "string",
      "color": "string",
      "description": "string",
      "position": 0,
      "archivedAt": "string",
      "createdAt": "string",
      "updatedAt": "string",
      "taskCount": 0
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/task-statuses

Create a task status

Create a named status inside one stable lifecycle type.

Request body · required
type"backlog" | "todo" | "in_progress" | "completed" | "cancelled" | "duplicate"required
namestringrequired
color"lavender" | "info" | "blue" | "cyan" | "teal" | "green" | "lime" | "amber" | "orange" | "red" | "rose" | "pink" | "purple" | "indigo" | "neutral"required
descriptionobjectoptional
Returns · 200 — Create a task status
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
type"backlog" | "todo" | "in_progress" | "completed" | "cancelled" | "duplicate"required
namestringrequired
colorstringrequired
descriptionstringrequired
positionnumberrequired
archivedAtstringrequired
createdAtstringrequired
updatedAtstringrequired
taskCountintegeroptional
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/task-statuses' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "type": "backlog",
    "name": "string",
    "color": "string",
    "description": "string",
    "position": 0,
    "archivedAt": "string",
    "createdAt": "string",
    "updatedAt": "string",
    "taskCount": 0
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
PATCH/api/v1/task-statuses/{id}

Update a task status

Rename or recolor a task status. Its lifecycle type cannot change.

Parameters
idpath · stringrequired
id path parameter
Request body · required
namestringoptional
color"lavender" | "info" | "blue" | "cyan" | "teal" | "green" | "lime" | "amber" | "orange" | "red" | "rose" | "pink" | "purple" | "indigo" | "neutral"optional
descriptionobjectoptional
Returns · 200 — Update a task status
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
type"backlog" | "todo" | "in_progress" | "completed" | "cancelled" | "duplicate"required
namestringrequired
colorstringrequired
descriptionstringrequired
positionnumberrequired
archivedAtstringrequired
createdAtstringrequired
updatedAtstringrequired
taskCountintegeroptional
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
PATCH request
curl -X PATCH 'https://www.telos-app.com/api/v1/task-statuses/{id}' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "type": "backlog",
    "name": "string",
    "color": "string",
    "description": "string",
    "position": 0,
    "archivedAt": "string",
    "createdAt": "string",
    "updatedAt": "string",
    "taskCount": 0
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/task-statuses/reorder

Reorder a task status

Reorder a status within its lifecycle type.

Request body · required
idstring<uuid>required
afterIdobjectoptional
beforeIdobjectoptional
Returns · 200 — Reorder a task status
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
type"backlog" | "todo" | "in_progress" | "completed" | "cancelled" | "duplicate"required
namestringrequired
colorstringrequired
descriptionstringrequired
positionnumberrequired
archivedAtstringrequired
createdAtstringrequired
updatedAtstringrequired
taskCountintegeroptional
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/task-statuses/reorder' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "type": "backlog",
    "name": "string",
    "color": "string",
    "description": "string",
    "position": 0,
    "archivedAt": "string",
    "createdAt": "string",
    "updatedAt": "string",
    "taskCount": 0
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/task-statuses/{id}/archive

Archive a task status

Move remaining tasks to a same-type replacement, then archive the status atomically.

Parameters
idpath · stringrequired
id path parameter
Request body · required
replacementStatusIdobjectoptional
Returns · 200 — Archive a task status
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
type"backlog" | "todo" | "in_progress" | "completed" | "cancelled" | "duplicate"required
namestringrequired
colorstringrequired
descriptionstringrequired
positionnumberrequired
archivedAtstringrequired
createdAtstringrequired
updatedAtstringrequired
taskCountintegeroptional
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/task-statuses/{id}/archive' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "type": "backlog",
    "name": "string",
    "color": "string",
    "description": "string",
    "position": 0,
    "archivedAt": "string",
    "createdAt": "string",
    "updatedAt": "string",
    "taskCount": 0
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/task-statuses/{id}/restore

Restore a task status

Restore an archived task status.

Parameters
idpath · stringrequired
id path parameter
Request body · required

Empty object.

Returns · 200 — Restore a task status
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
type"backlog" | "todo" | "in_progress" | "completed" | "cancelled" | "duplicate"required
namestringrequired
colorstringrequired
descriptionstringrequired
positionnumberrequired
archivedAtstringrequired
createdAtstringrequired
updatedAtstringrequired
taskCountintegeroptional
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/task-statuses/{id}/restore' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "type": "backlog",
    "name": "string",
    "color": "string",
    "description": "string",
    "position": 0,
    "archivedAt": "string",
    "createdAt": "string",
    "updatedAt": "string",
    "taskCount": 0
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
Resource

Teams

GET/api/v1/teams

List teams

List teams in the organisation, with cursor pagination.

Parameters
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
Returns · 200 — List teams
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
namestringrequired
slugstringrequired
prefixstringrequired
descriptionstringrequired
defaultPrdTemplateIdobjectrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/teams' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "name": "string",
      "slug": "string",
      "prefix": "string",
      "description": "string",
      "defaultPrdTemplateId": null,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/teams

Create a team

Create a team. The 2-4 character prefix becomes the team's task ref prefix (e.g. ENG-42).

Request body · required
namestringrequired
descriptionstringoptional
prefixstringoptional
Returns · 201 — Create a team
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
namestringrequired
slugstringrequired
prefixstringrequired
descriptionstringrequired
defaultPrdTemplateIdobjectrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/teams' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "name": "string",
    "slug": "string",
    "prefix": "string",
    "description": "string",
    "defaultPrdTemplateId": null,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/teams/{id}

Get a team

Get one team: its name, description, ref prefix (the task-ref namespace, e.g. ENG-42) and default PRD template. The roster is a separate read (list_team_members).

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Get a team
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
namestringrequired
slugstringrequired
prefixstringrequired
descriptionstringrequired
defaultPrdTemplateIdobjectrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/teams/{id}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "name": "string",
    "slug": "string",
    "prefix": "string",
    "description": "string",
    "defaultPrdTemplateId": null,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
PATCH/api/v1/teams/{id}

Update a team

Update a team's name, description, ref prefix, or default PRD template.

Parameters
idpath · stringrequired
id path parameter
Request body · required
namestringoptional
descriptionstringoptional
defaultPrdTemplateIdobjectoptional
prefixstringoptional
Returns · 200 — Update a team
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
namestringrequired
slugstringrequired
prefixstringrequired
descriptionstringrequired
defaultPrdTemplateIdobjectrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
PATCH request
curl -X PATCH 'https://www.telos-app.com/api/v1/teams/{id}' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "name": "string",
    "slug": "string",
    "prefix": "string",
    "description": "string",
    "defaultPrdTemplateId": null,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
DELETE/api/v1/teams/{id}

Delete a team

Delete a team. Its opportunities/tasks keep their rows (team unset, refs stable); memberships and team-scoped config are removed. Refuses to delete the org's only team.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Delete a team
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
deletedtruerequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
DELETE request
curl -X DELETE 'https://www.telos-app.com/api/v1/teams/{id}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "deleted": true
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/teams/{id}/members

List team members

The team's roster with cursor pagination: each member's user id, name, email, avatar, membership id, and org role. Salary and weekly-hours fields are included only for a caller holding compensation:read over this team, and are absent otherwise rather than null. Requires team:read.

Parameters
idpath · stringrequired
id path parameter
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
Returns · 200 — List team members
oktruerequired
dataobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/teams/{id}/members' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": null,
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/teams/{id}/members

Add a team member

Add a user to a team's roster.

Parameters
idpath · stringrequired
id path parameter
Request body · required
userIdstring<uuid>required
Returns · 201 — Add a team member
oktruerequired
dataobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/teams/{id}/members' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": null,
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
DELETE/api/v1/teams/{id}/members/{userId}

Remove a team member

Remove a user from a team's roster.

Parameters
idpath · stringrequired
id path parameter
userIdpath · stringrequired
userId path parameter
Returns · 200 — Remove a team member
oktruerequired
dataobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
DELETE request
curl -X DELETE 'https://www.telos-app.com/api/v1/teams/{id}/members/{userId}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": null,
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/teams/ownership-config

List team ownership config

Who owns insight review for each team. One row per team, optionally narrowed to one team; teams with nobody assigned come back with a null reviewer.

Parameters
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
teamIdquery · string<uuid>optional
Only this team's row
Returns · 200 — List team ownership config
oktruerequired
dataobject[]required
Show child attributes ›
teamIdstring<uuid>required
teamNamestringrequired
teamSlugstringrequired
insightReviewerobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/teams/ownership-config' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "teamId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "teamName": "string",
      "teamSlug": "string",
      "insightReviewer": null
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
Resource

Templates

GET/api/v1/templates

List templates

List the org's template templates with cursor pagination. Templates carry no category: categories group tasks and opportunities, not templates.

Parameters
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
Returns · 200 — List templates
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
namestringrequired
descriptionstringrequired
defaultEntityTypeobjectrequired
isDefaultbooleanrequired
isSystembooleanrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/templates' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "name": "string",
      "description": "string",
      "defaultEntityType": null,
      "isDefault": true,
      "isSystem": true,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/templates

Create a template

Create a template template (name, optional description, optional defaultEntityType). Every template closes with system-managed Completed and Cancelled steps; add real steps with create-step.

Request body · required
namestringrequired
descriptionstringoptional
defaultEntityType"task" | "opportunity" | "customer"optional
Returns · 201 — Create a template
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
namestringrequired
descriptionstringrequired
defaultEntityTypeobjectrequired
isDefaultbooleanrequired
isSystembooleanrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/templates' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "name": "string",
    "description": "string",
    "defaultEntityType": null,
    "isDefault": true,
    "isSystem": true,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/templates/{id}

Get a template

Get a template template with its ordered steps. The terminal Completed/Cancelled pair is system-managed and not included.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Get a template
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
namestringrequired
descriptionstringrequired
defaultEntityTypeobjectrequired
isDefaultbooleanrequired
isSystembooleanrequired
createdAtstringrequired
updatedAtstringrequired
stepsobject[]required
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
templateIdstring<uuid>required
positionintegerrequired
titlestringrequired
descriptionstringrequired
defaultDriRoleobjectrequired
defaultDriUserIdobjectrequired
slaTargetHoursobjectrequired
expectedDaysobjectrequired
terminalKindobjectrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/templates/{id}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "name": "string",
    "description": "string",
    "defaultEntityType": null,
    "isDefault": true,
    "isSystem": true,
    "createdAt": "string",
    "updatedAt": "string",
    "steps": [
      {
        "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "templateId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "position": 0,
        "title": "string",
        "description": "string",
        "defaultDriRole": null,
        "defaultDriUserId": null,
        "slaTargetHours": null,
        "expectedDays": null,
        "terminalKind": null,
        "createdAt": "string",
        "updatedAt": "string"
      }
    ]
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
PATCH/api/v1/templates/{id}

Update a template

Update a template's name, description, or default entity type.

Parameters
idpath · stringrequired
id path parameter
Request body · required
namestringoptional
descriptionstringoptional
defaultEntityTypeobjectoptional
Returns · 200 — Update a template
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
namestringrequired
descriptionstringrequired
defaultEntityTypeobjectrequired
isDefaultbooleanrequired
isSystembooleanrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
PATCH request
curl -X PATCH 'https://www.telos-app.com/api/v1/templates/{id}' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "name": "string",
    "description": "string",
    "defaultEntityType": null,
    "isDefault": true,
    "isSystem": true,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
DELETE/api/v1/templates/{id}

Delete a template

Delete a template template. Refused while active tasks or opportunities are using it.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Delete a template
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
deletedtruerequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
DELETE request
curl -X DELETE 'https://www.telos-app.com/api/v1/templates/{id}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "deleted": true
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/templates/{id}/steps

Add a template step

Append a step to a template, ahead of the terminal pair. Owner defaults to the caller when defaultDriUserId is omitted.

Parameters
idpath · stringrequired
id path parameter
Request body · required
titlestringrequired
descriptionstringoptional
defaultDriRole"engineer" | "pm" | "em" | "executive" | "admin" | "sales" | "operations"optional
defaultDriUserIdstring<uuid>optional
slaTargetHoursobjectoptional
Hours the step is expected to take
Returns · 201 — Add a template step
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
templateIdstring<uuid>required
positionintegerrequired
titlestringrequired
descriptionstringrequired
defaultDriRoleobjectrequired
defaultDriUserIdobjectrequired
slaTargetHoursobjectrequired
expectedDaysobjectrequired
terminalKindobjectrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/templates/{id}/steps' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "templateId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "position": 0,
    "title": "string",
    "description": "string",
    "defaultDriRole": null,
    "defaultDriUserId": null,
    "slaTargetHours": null,
    "expectedDays": null,
    "terminalKind": null,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
PATCH/api/v1/templates/steps/{stepId}

Update a template step

Update a step's title, description, position, owner, or SLA. Terminal steps are system-managed and can't be edited.

Parameters
stepIdpath · stringrequired
stepId path parameter
Request body · required
positionobjectoptional
New position among the template's real steps
titlestringoptional
descriptionstringoptional
defaultDriRoleobjectoptional
defaultDriUserIdstring<uuid>optional
slaTargetHoursobjectoptional
Hours the step is expected to take; null clears it
Returns · 200 — Update a template step
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
templateIdstring<uuid>required
positionintegerrequired
titlestringrequired
descriptionstringrequired
defaultDriRoleobjectrequired
defaultDriUserIdobjectrequired
slaTargetHoursobjectrequired
expectedDaysobjectrequired
terminalKindobjectrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
PATCH request
curl -X PATCH 'https://www.telos-app.com/api/v1/templates/steps/{stepId}' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "templateId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "position": 0,
    "title": "string",
    "description": "string",
    "defaultDriRole": null,
    "defaultDriUserId": null,
    "slaTargetHours": null,
    "expectedDays": null,
    "terminalKind": null,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
DELETE/api/v1/templates/steps/{stepId}

Delete a template step

Delete a step and close the position gap. Refused for terminal steps and for steps active work is currently on.

Parameters
stepIdpath · stringrequired
stepId path parameter
Returns · 200 — Delete a template step
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
deletedtruerequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
DELETE request
curl -X DELETE 'https://www.telos-app.com/api/v1/templates/steps/{stepId}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "deleted": true
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/templates/handoff

Write a template handoff

Move an opportunity or customer-onboarding template to a step and post a handoff message for it. Jumps to the target step instance (optionally completing the rest) and records the handoff note on the entity's thread. For a subtask sequence inside a task, use write_task_handoff instead.

Request body · required
targetStepInstanceIdstring<uuid>required
markCompleteobjectoptional
Complete the steps being skipped past
messagestringoptional
mentionsobjectoptional
Show child attributes ›
userIdsstring<uuid>[]optional
teamIdsstring<uuid>[]optional
mentionLinkUrlstringoptional
Returns · 200 — Write a template handoff
oktruerequired
dataobjectrequired
Show child attributes ›
stepInstanceIdstring<uuid>required
commentIdobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/templates/handoff' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "stepInstanceId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "commentId": null
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/templates/{id}/usage

List active work using a template

The tasks and opportunities currently running on this template, with counts. Delete refuses while either count is above zero; reassign-and-delete is the way through.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — List active work using a template
oktruerequired
dataobjectrequired
Show child attributes ›
taskIdsstring<uuid>[]required
opportunityIdsstring<uuid>[]required
taskCountintegerrequired
opportunityCountintegerrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/templates/{id}/usage' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "taskIds": [
      "01J9Z3F4S0Z9KMQ4N6PYZR7C5A"
    ],
    "opportunityIds": [
      "01J9Z3F4S0Z9KMQ4N6PYZR7C5A"
    ],
    "taskCount": 0,
    "opportunityCount": 0
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/templates/default/{entityType}

Get the org's default template for an entity type

The template a new task, opportunity or customer gets when the caller does not choose one: the flagged default, else the oldest matching template. 404 when the org has none for that entity type.

Parameters
entityTypepath · stringrequired
entityType path parameter
Returns · 200 — Get the org's default template for an entity type
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
namestringrequired
descriptionstringrequired
defaultEntityTypeobjectrequired
isDefaultbooleanrequired
isSystembooleanrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/templates/default/{entityType}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "name": "string",
    "description": "string",
    "defaultEntityType": null,
    "isDefault": true,
    "isSystem": true,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/templates/{id}/reassign

Move every entity to another template, then delete this one

Repoint every task and opportunity on this template onto the replacement, re-seed step instances for the active ones, and delete the template. Destructive: step progress on the reassigned work resets, so moving tasks also requires task:update and moving opportunities also requires opportunity:update. Use plain delete when nothing is using it.

Parameters
idpath · stringrequired
id path parameter
Request body · required
replaceWithTemplateIdstring<uuid>required
Template the reassigned work moves onto
Returns · 200 — Move every entity to another template, then delete this one
oktruerequired
dataobjectrequired
Show child attributes ›
deletedobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
namestringrequired
descriptionstringrequired
defaultEntityTypeobjectrequired
isDefaultbooleanrequired
isSystembooleanrequired
createdAtstringrequired
updatedAtstringrequired
replacementobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
namestringrequired
descriptionstringrequired
defaultEntityTypeobjectrequired
isDefaultbooleanrequired
isSystembooleanrequired
createdAtstringrequired
updatedAtstringrequired
reassignedobjectrequired
Show child attributes ›
taskCountintegerrequired
opportunityCountintegerrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/templates/{id}/reassign' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "deleted": {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "name": "string",
      "description": "string",
      "defaultEntityType": null,
      "isDefault": true,
      "isSystem": true,
      "createdAt": "string",
      "updatedAt": "string"
    },
    "replacement": {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "name": "string",
      "description": "string",
      "defaultEntityType": null,
      "isDefault": true,
      "isSystem": true,
      "createdAt": "string",
      "updatedAt": "string"
    },
    "reassigned": {
      "taskCount": 0,
      "opportunityCount": 0
    }
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/templates/instances/{entityType}/{entityId}

Read the template running on an entity

The live process on a task, opportunity or customer: which step is active, how far it has run, and every step instance in order with its owner and status. This is the read an agent needs before advancing a step or writing a handoff. 404 when the entity carries no template.

Parameters
entityTypepath · stringrequired
entityType path parameter
entityIdpath · stringrequired
entityId path parameter
Returns · 200 — Read the template running on an entity
oktruerequired
dataobjectrequired
Show child attributes ›
entityType"task" | "opportunity" | "customer"required
entityIdstring<uuid>required
templateNamestringrequired
totalStepsintegerrequired
completedStepsintegerrequired
skippedStepsintegerrequired
percentageintegerrequired
currentStepTitlestringrequired
currentStepPositionobjectrequired
currentStepTerminalKindobjectrequired
stepsobject[]required
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
entityType"vision" | "objective" | "metric" | "opportunity" | "task" | "team" | "user" | "task_assignment" | "webhook_subscription" | "template" | "template_step" | "template_step_instance" | "template_checklist_instance" | "strategy" | "strategy_version" | "vision_version" | "notification" | "comment" | "customer" | "customer_update" | "customer_document" | "insight" | "opportunity_risk" | "file" | "tag" | "tag_theme" | "prd_template" | "room" | "message" | "comment_thread" | "time_entry" | "org" | "scoring_criterion" | "cycle"required
entityIdstring<uuid>required
stepIdstring<uuid>required
positionintegerrequired
plannedDurationDaysobjectrequired
plannedStartstringrequired
titlestringrequired
descriptionstringrequired
driUserIdobjectrequired
arrUnlockstringrequired
status"pending" | "active" | "complete" | "skipped"required
completedAtstringrequired
cancelledFromStepIdobjectrequired
createdAtstringrequired
updatedAtstringrequired
slaTargetHoursobjectrequired
terminalKindobjectrequired
driobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/templates/instances/{entityType}/{entityId}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "entityType": "task",
    "entityId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "templateName": "string",
    "totalSteps": 0,
    "completedSteps": 0,
    "skippedSteps": 0,
    "percentage": 0,
    "currentStepTitle": "string",
    "currentStepPosition": null,
    "currentStepTerminalKind": null,
    "steps": [
      {
        "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "entityType": "vision",
        "entityId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "stepId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "position": 0,
        "plannedDurationDays": null,
        "plannedStart": "string",
        "title": "string",
        "description": "string",
        "driUserId": null,
        "arrUnlock": "string",
        "status": "pending",
        "completedAt": "string",
        "cancelledFromStepId": null,
        "createdAt": "string",
        "updatedAt": "string",
        "slaTargetHours": null,
        "terminalKind": null,
        "dri": null
      }
    ]
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/templates/instances

Start a template on an entity

Put a task, opportunity or customer on a template for the first time and seed its step instances (opportunities also get one schedulable task per phase). Owners resolve from each step's default user or role. Set activateFirstStep false to seed everything pending. Refused when the entity already runs a template; use swap for that.

Request body · required
entityType"task" | "opportunity" | "customer"required
entityIdstring<uuid>required
templateIdstring<uuid>required
activateFirstStepobjectoptional
false seeds every step pending
Returns · 201 — Start a template on an entity
oktruerequired
dataobjectrequired
Show child attributes ›
entityType"task" | "opportunity" | "customer"required
entityIdstring<uuid>required
templateIdstring<uuid>required
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/templates/instances' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "entityType": "task",
    "entityId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "templateId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/templates/instances/swap

Move an entity onto a different template

Replace the template an entity is already running, in one transaction. Destructive: the old step instances are deleted and progress resets, since template steps rarely line up, so it also requires the target entity's own update permission (task:update, opportunity:update or customer:update). No-op when the entity is already on the target template.

Request body · required
entityType"task" | "opportunity" | "customer"required
entityIdstring<uuid>required
newTemplateIdstring<uuid>required
activateFirstStepobjectoptional
false seeds every step pending
Returns · 200 — Move an entity onto a different template
oktruerequired
dataobjectrequired
Show child attributes ›
entityType"task" | "opportunity" | "customer"required
entityIdstring<uuid>required
templateIdstring<uuid>required
stepsCountintegerrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/templates/instances/swap' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "entityType": "task",
    "entityId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "templateId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "stepsCount": 0
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
PATCH/api/v1/templates/instances/steps/{stepInstanceId}

Advance or reassign a running step

Set a step instance's status and/or its owner. Status moves are checked against the allowed transitions, and completing or skipping a step activates the next pending one. To move the pointer to an arbitrary step and announce it, use write_template_handoff instead. This is the running instance, not the template step update_template_step edits.

Parameters
stepInstanceIdpath · stringrequired
stepInstanceId path parameter
Request body · required
status"pending" | "active" | "complete" | "skipped"optional
driUserIdstring<uuid>optional
Returns · 200 — Advance or reassign a running step
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
entityType"vision" | "objective" | "metric" | "opportunity" | "task" | "team" | "user" | "task_assignment" | "webhook_subscription" | "template" | "template_step" | "template_step_instance" | "template_checklist_instance" | "strategy" | "strategy_version" | "vision_version" | "notification" | "comment" | "customer" | "customer_update" | "customer_document" | "insight" | "opportunity_risk" | "file" | "tag" | "tag_theme" | "prd_template" | "room" | "message" | "comment_thread" | "time_entry" | "org" | "scoring_criterion" | "cycle"required
entityIdstring<uuid>required
stepIdstring<uuid>required
positionintegerrequired
plannedDurationDaysobjectrequired
plannedStartstringrequired
titlestringrequired
descriptionstringrequired
driUserIdobjectrequired
arrUnlockstringrequired
status"pending" | "active" | "complete" | "skipped"required
completedAtstringrequired
cancelledFromStepIdobjectrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
PATCH request
curl -X PATCH 'https://www.telos-app.com/api/v1/templates/instances/steps/{stepInstanceId}' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "entityType": "vision",
    "entityId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "stepId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "position": 0,
    "plannedDurationDays": null,
    "plannedStart": "string",
    "title": "string",
    "description": "string",
    "driUserId": null,
    "arrUnlock": "string",
    "status": "pending",
    "completedAt": "string",
    "cancelledFromStepId": null,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
Resource

Time Entries

GET/api/v1/time-entries

List time entries

List time entries in a date range (from/to, max 366 days), newest first, with cursor pagination. Defaults to the authenticated user's own entries. engineerId reads another engineer's entries and requires the salary read permission (compensation:read); a team-scoped grant admits only engineers on the caller's teams.

Parameters
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
fromquery · stringrequired
Range start (YYYY-MM-DD, inclusive)
toquery · stringrequired
Range end (YYYY-MM-DD, inclusive; max 366 days after from)
engineerIdquery · string<uuid>optional
Another engineer's user UUID; requires compensation:read
Returns · 200 — List time entries
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
engineerIdstring<uuid>required
entryDatestringrequired
opportunityIdobjectrequired
taskIdobjectrequired
miscCategoryIdobjectrequired
hoursstringrequired
hourlyRateSnapshotstringrequired
notestringrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/time-entries' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "engineerId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "entryDate": "string",
      "opportunityId": null,
      "taskId": null,
      "miscCategoryId": null,
      "hours": "string",
      "hourlyRateSnapshot": "string",
      "note": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/time-entries

Log a time entry

Log time for the authenticated user against exactly one target: an opportunity (opportunityId), a task (taskId), or a misc category (miscCategoryId, which requires a note). Hours are 0-24 per entry.

Request body · required
entryDatestringrequired
opportunityIdobjectoptional
taskIdobjectoptional
miscCategoryIdobjectoptional
hoursobjectrequired
Hours worked, 0-24 per entry
noteobjectoptional
Returns · 201 — Log a time entry
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
engineerIdstring<uuid>required
entryDatestringrequired
opportunityIdobjectrequired
taskIdobjectrequired
miscCategoryIdobjectrequired
hoursstringrequired
hourlyRateSnapshotstringrequired
notestringrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/time-entries' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "engineerId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "entryDate": "string",
    "opportunityId": null,
    "taskId": null,
    "miscCategoryId": null,
    "hours": "string",
    "hourlyRateSnapshot": "string",
    "note": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
PATCH/api/v1/time-entries/{id}

Update a time entry

Update one of your own time entries (entryDate, hours, note). Only the engineer who logged an entry may edit it.

Parameters
idpath · stringrequired
id path parameter
Request body · required
entryDatestringoptional
hoursobjectoptional
Hours worked, 0-24 per entry
noteobjectoptional
Returns · 200 — Update a time entry
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
engineerIdstring<uuid>required
entryDatestringrequired
opportunityIdobjectrequired
taskIdobjectrequired
miscCategoryIdobjectrequired
hoursstringrequired
hourlyRateSnapshotstringrequired
notestringrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
PATCH request
curl -X PATCH 'https://www.telos-app.com/api/v1/time-entries/{id}' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "engineerId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "entryDate": "string",
    "opportunityId": null,
    "taskId": null,
    "miscCategoryId": null,
    "hours": "string",
    "hourlyRateSnapshot": "string",
    "note": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
DELETE/api/v1/time-entries/{id}

Delete a time entry

Delete one of your own time entries. Only the engineer who logged an entry may delete it.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Delete a time entry
oktruerequired
dataobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
DELETE request
curl -X DELETE 'https://www.telos-app.com/api/v1/time-entries/{id}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": null,
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/time-entries/aggregate-by-category

Aggregate time by category

Total hours in a date range bucketed by category, across all engineers in the org (optionally filtered to one team's members). Cost reporting: requires an org-wide cost:read grant.

Returns · 200 — Aggregate time by category
oktruerequired
dataobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/time-entries/aggregate-by-category' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": null,
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/time-entries/costs-for-range

Get every engineer's costed time in a date range

Hydrated time entries for every engineer in a date range (hours, derived cost, engineer, category, target), capped at 5000 rows; `truncated` flags the cap. Not a paginated list: it is one capped snapshot of the whole window, so narrow the range rather than paging. Use list_time_entries to walk your own entries with a cursor. Cost reporting: requires an org-wide cost:read grant.

Returns · 200 — Get every engineer's costed time in a date range
oktruerequired
dataobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/time-entries/costs-for-range' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": null,
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/time-entries/actual-cost-for-opportunity/{opportunityId}

Actual labor cost of an opportunity

Sum of hours times each entry's snapshotted hourly rate for every time entry logged against the opportunity. Returns 0 when nothing is logged. Requires an org-wide cost:read grant.

Parameters
opportunityIdpath · stringrequired
opportunityId path parameter
Returns · 200 — Actual labor cost of an opportunity
oktruerequired
dataobjectrequired
Show child attributes ›
actualCostnumberrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/time-entries/actual-cost-for-opportunity/{opportunityId}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "actualCost": 0
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/time-entries/actual-cost-for-task/{taskId}

Actual labor cost of a task

Sum of hours times each entry's snapshotted hourly rate for every time entry logged against the task. Returns 0 when nothing is logged. Requires an org-wide cost:read grant.

Parameters
taskIdpath · stringrequired
taskId path parameter
Returns · 200 — Actual labor cost of a task
oktruerequired
dataobjectrequired
Show child attributes ›
actualCostnumberrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/time-entries/actual-cost-for-task/{taskId}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "actualCost": 0
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/time-entries/upsert-range

Replace a timesheet window

Replace the authenticated user's entries in a date window with exactly these rows: every existing entry inside [from, to] is deleted first, so an empty rows array clears the window. Each row targets exactly one of opportunityId, taskId, or miscCategoryId (misc requires a note) and must fall inside the window. The window is capped at 366 days.

Request body · required
fromstringrequired
Range start (YYYY-MM-DD, inclusive)
tostringrequired
Range end (YYYY-MM-DD, inclusive; max 366 days after from)
rowsobject[]required
The complete set of entries for the window
Show child attributes ›
entryDatestringrequired
opportunityIdobjectoptional
taskIdobjectoptional
miscCategoryIdobjectoptional
hoursobjectrequired
Hours worked, 0-24 per entry
noteobjectoptional
Returns · 200 — Replace a timesheet window
oktruerequired
dataobjectrequired
Show child attributes ›
oktruerequired
countintegerrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/time-entries/upsert-range' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "ok": true,
    "count": 0
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/time-entries/for-opportunity/{opportunityId}

List an opportunity's time entries

Every entry logged against one opportunity, newest first: date, hours, and note. Hours only — the cost of those hours rides cost:read on get_time_entry_cost_for_opportunity. Who logged each entry is individual-grain time, so engineerId/engineerName come back null unless the caller holds compensation:read (which an API key never does): sum the hours, do not attribute them.

Parameters
opportunityIdpath · stringrequired
opportunityId path parameter
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
Returns · 200 — List an opportunity's time entries
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
engineerIdobjectrequired
engineerNamestringrequired
engineerAvatarUrlstringrequired
entryDatestringrequired
hoursstringrequired
notestringrequired
createdAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/time-entries/for-opportunity/{opportunityId}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "engineerId": null,
      "engineerName": "string",
      "engineerAvatarUrl": "string",
      "entryDate": "string",
      "hours": "string",
      "note": "string",
      "createdAt": "string"
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
Resource

Users

GET/api/v1/users

List users

List org members with cursor pagination.

Parameters
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
Returns · 200 — List users
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
kind"human" | "agent" | "system"required
emailstringrequired
namestringrequired
slugstringrequired
avatarUrlobjectrequired
imageobjectrequired
emailVerifiedstringrequired
passwordHashobjectrequired
totpSecretobjectrequired
totpEnabledAtstringrequired
salaryMonthlystringrequired
salaryCurrencyobjectrequired
weeklyHoursintegerrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/users' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "kind": "human",
      "email": "string",
      "name": "string",
      "slug": "string",
      "avatarUrl": null,
      "image": null,
      "emailVerified": "string",
      "passwordHash": null,
      "totpSecret": null,
      "totpEnabledAt": "string",
      "salaryMonthly": "string",
      "salaryCurrency": null,
      "weeklyHours": 0,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
GET/api/v1/users/{id}

Get a user

Get one org member's profile: name, email, avatar, org role and weekly hours. Salary fields are included only for a caller holding compensation:read, and are absent otherwise rather than null. Use whoami for the key's own user.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Get a user
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
kind"human" | "agent" | "system"required
emailstringrequired
namestringrequired
slugstringrequired
avatarUrlobjectrequired
imageobjectrequired
emailVerifiedstringrequired
passwordHashobjectrequired
totpSecretobjectrequired
totpEnabledAtstringrequired
salaryMonthlystringrequired
salaryCurrencyobjectrequired
weeklyHoursintegerrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/users/{id}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "kind": "human",
    "email": "string",
    "name": "string",
    "slug": "string",
    "avatarUrl": null,
    "image": null,
    "emailVerified": "string",
    "passwordHash": null,
    "totpSecret": null,
    "totpEnabledAt": "string",
    "salaryMonthly": "string",
    "salaryCurrency": null,
    "weeklyHours": 0,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
PATCH/api/v1/users/{id}

Update a user

Update an org member's profile (name, weekly hours). Salary fields require a leadership role and travel as a pair; role changes need org:manage, which API keys never carry.

Parameters
idpath · stringrequired
id path parameter
Request body · required
namestringoptional
salaryMonthlyobjectoptional
Monthly salary; travels with salaryCurrency
salaryCurrency"USD" | "EUR" | "GBP" | "CAD" | "AUD" | "CHF" | "SEK" | "NOK" | "DKK" | "JPY"optional
weeklyHoursobjectoptional
Contracted hours per week (1-80)
role"engineer" | "pm" | "em" | "executive" | "admin" | "sales" | "operations"optional
orgRoleIdobjectoptional
Returns · 200 — Update a user
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
kind"human" | "agent" | "system"required
emailstringrequired
namestringrequired
slugstringrequired
avatarUrlobjectrequired
imageobjectrequired
emailVerifiedstringrequired
passwordHashobjectrequired
totpSecretobjectrequired
totpEnabledAtstringrequired
salaryMonthlystringrequired
salaryCurrencyobjectrequired
weeklyHoursintegerrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
PATCH request
curl -X PATCH 'https://www.telos-app.com/api/v1/users/{id}' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "kind": "human",
    "email": "string",
    "name": "string",
    "slug": "string",
    "avatarUrl": null,
    "image": null,
    "emailVerified": "string",
    "passwordHash": null,
    "totpSecret": null,
    "totpEnabledAt": "string",
    "salaryMonthly": "string",
    "salaryCurrency": null,
    "weeklyHours": 0,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
Resource

Viewer

GET/api/v1/viewer

Get the authenticated caller

Who this credential acts as: user id, name, email, org id, role, the teams the caller belongs to, and the permission grants the credential actually carries. Start here to find out what you are allowed to do.

Returns · 200 — Get the authenticated caller
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
userIdstring<uuid>required
orgIdstring<uuid>required
emailstring<email>required
namestringrequired
avatarUrlstringrequired
createdAtstringrequired
updatedAtstringrequired
rolestringrequired
orgRolestringrequired
orgRoleIdobjectrequired
teamsobject[]required
Show child attributes ›
idstring<uuid>required
namestringrequired
teamIdsstring<uuid>[]required
permissionsobject[]required
Show child attributes ›
permissionstringrequired
scope"global" | "team"required
salaryMonthlystringoptional
salaryCurrencystringoptional
weeklyHoursnumberoptional
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/viewer' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "userId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "email": "user@example.com",
    "name": "string",
    "avatarUrl": "string",
    "createdAt": "string",
    "updatedAt": "string",
    "role": "string",
    "orgRole": "string",
    "orgRoleId": null,
    "teams": [
      {
        "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
        "name": "string"
      }
    ],
    "teamIds": [
      "01J9Z3F4S0Z9KMQ4N6PYZR7C5A"
    ],
    "permissions": [
      {
        "permission": "string",
        "scope": "global"
      }
    ],
    "salaryMonthly": "string",
    "salaryCurrency": "string",
    "weeklyHours": 0
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/viewer/avatar

Set the caller's own avatar

Point the caller's avatar at an uploaded file. Upload it first with request-file-upload and confirm-file-upload; this takes the resulting file id. Self-scoped: a credential can only set its own avatar.

Request body · required
avatarFileIdstring<uuid>required
File UUID from confirm-file-upload
Returns · 200 — Set the caller's own avatar
oktruerequired
dataobjectrequired
Show child attributes ›
oktruerequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/viewer/avatar' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "ok": true
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
Resource

Webhook Subscriptions

GET/api/v1/webhook-subscriptions

List webhook subscriptions

List the org's outbound webhook subscriptions. Secrets are write-once and never returned.

Parameters
cursorquery · stringoptional
Opaque pagination cursor from a previous response
limitquery · numberoptional
Number of items per page (default 50, max 200)
Returns · 200 — List webhook subscriptions
oktruerequired
dataobject[]required
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
urlstringrequired
eventTypesstring[]required
activebooleanrequired
descriptionobjectrequired
createdByAppIdobjectrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
GET request
curl -X GET 'https://www.telos-app.com/api/v1/webhook-subscriptions' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": [
    {
      "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
      "url": "string",
      "eventTypes": [
        "string"
      ],
      "active": true,
      "description": null,
      "createdByAppId": null,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/webhook-subscriptions

Create a webhook subscription

Subscribe an HTTPS endpoint to outbound events. Deliveries are signed with the secret (t=/v1= scheme); the secret is encrypted at rest and never returned, so store it now.

Request body · required
urlstring<uri>required
secretstringrequired
eventTypes"opportunity.status_changed" | "task.status_changed" | "metric.value_updated" | "metric.created" | "metric.updated" | "metric.deleted" | "vision.created" | "vision.updated" | "vision.deleted" | "objective.created" | "objective.updated" | "objective.deleted" | "objective.metric_link_updated" | "objective.link_changed" | "team.created" | "team.updated" | "team.deleted" | "team.member_added" | "team.member_removed" | "cycle.configured" | "cycle.updated" | "cycle.deleted" | "team.invite_sent" | "team.invite_revoked" | "team.invite_accepted" | "org.deletion_scheduled" | "org.deletion_canceled" | "org.purged" | "support.access_granted" | "support.access_revoked" | "support.access_expired" | "user.updated" | "task.created" | "task.updated" | "task.owner_changed" | "template.created" | "template.updated" | "template.deleted" | "template.assigned" | "template.step_status_changed" | "template.step_added" | "template.step_updated" | "template.step_removed" | "opportunity.created" | "opportunity.updated" | "opportunity.deleted" | "opportunity.completed" | "opportunity.cancelled" | "opportunity.update_posted" | "opportunity.score_set" | "opportunity.score_cleared" | "scoring_criterion.created" | "scoring_criterion.updated" | "scoring_criterion.deleted" | "task.deleted" | "opportunity.synthesized" | "opportunity.risk_vote_cast" | "opportunity.risk_vote_changed" | "opportunity.tags_changed" | "task.tags_changed" | "opportunity.prototype_added" | "opportunity.prototype_removed" | "opportunity.objective_linked" | "opportunity.objective_unlinked" | "opportunity.objective_link_updated" | "insight.created" | "insight.updated" | "insight.archived" | "insight.deleted" | "insight.pinned" | "insight.unpinned" | "insight.status_changed" | "insight.linked" | "insight.unlinked" | "insight.rejected" | "insight.needs_context" | "insight.review_team_changed" | "tag.created" | "tag.updated" | "tag.deleted" | "tag_theme.created" | "tag_theme.updated" | "tag_theme.deleted" | "prd_template.created" | "prd_template.updated" | "prd_template.deleted" | "time_entry.created" | "time_entry.updated" | "time_entry.deleted" | "time_entry.range_upserted" | "strategy.created" | "strategy.updated" | "strategy.published" | "strategy.archived" | "comment.created" | "comment.updated" | "comment.deleted" | "customer.created" | "customer.updated" | "customer.deleted" | "customer.opportunity_linked" | "customer.opportunity_unlinked" | "customer.update_posted" | "customer.contact_added" | "customer.onboarding_started" | "customer.went_live" | "opportunity.content_updated" | "room.created" | "room.updated" | "room.archived" | "room.member_added" | "room.member_removed" | "room.pinned" | "room.unpinned" | "room.notification_level_changed" | "room.marked_read" | "message.created" | "message.edited" | "message.deleted" | "message.pinned" | "message.unpinned" | "message.reaction_added" | "message.reaction_removed" | "subscription.created" | "subscription.muted" | "good_vibes.posted" | "team_queue.reordered" | "team_queue.chain_added" | "team_queue.chain_removed" | "team_queue.cross_team_chain_added" | "team_queue.window_set" | "webhook_subscription.created" | "webhook_subscription.updated" | "webhook_subscription.deleted" | "external_ref.attached"[]required
descriptionstringoptional
Returns · 201 — Create a webhook subscription
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
urlstringrequired
eventTypesstring[]required
activebooleanrequired
descriptionobjectrequired
createdByAppIdobjectrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/webhook-subscriptions' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "url": "string",
    "eventTypes": [
      "string"
    ],
    "active": true,
    "description": null,
    "createdByAppId": null,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
PATCH/api/v1/webhook-subscriptions/{id}

Update a webhook subscription

Change a subscription's target URL, event types, description, or active flag. The signing secret cannot be changed here — it is write-once, so rotate by deleting the subscription and creating a new one.

Parameters
idpath · stringrequired
id path parameter
Request body · required
urlstring<uri>optional
eventTypes"opportunity.status_changed" | "task.status_changed" | "metric.value_updated" | "metric.created" | "metric.updated" | "metric.deleted" | "vision.created" | "vision.updated" | "vision.deleted" | "objective.created" | "objective.updated" | "objective.deleted" | "objective.metric_link_updated" | "objective.link_changed" | "team.created" | "team.updated" | "team.deleted" | "team.member_added" | "team.member_removed" | "cycle.configured" | "cycle.updated" | "cycle.deleted" | "team.invite_sent" | "team.invite_revoked" | "team.invite_accepted" | "org.deletion_scheduled" | "org.deletion_canceled" | "org.purged" | "support.access_granted" | "support.access_revoked" | "support.access_expired" | "user.updated" | "task.created" | "task.updated" | "task.owner_changed" | "template.created" | "template.updated" | "template.deleted" | "template.assigned" | "template.step_status_changed" | "template.step_added" | "template.step_updated" | "template.step_removed" | "opportunity.created" | "opportunity.updated" | "opportunity.deleted" | "opportunity.completed" | "opportunity.cancelled" | "opportunity.update_posted" | "opportunity.score_set" | "opportunity.score_cleared" | "scoring_criterion.created" | "scoring_criterion.updated" | "scoring_criterion.deleted" | "task.deleted" | "opportunity.synthesized" | "opportunity.risk_vote_cast" | "opportunity.risk_vote_changed" | "opportunity.tags_changed" | "task.tags_changed" | "opportunity.prototype_added" | "opportunity.prototype_removed" | "opportunity.objective_linked" | "opportunity.objective_unlinked" | "opportunity.objective_link_updated" | "insight.created" | "insight.updated" | "insight.archived" | "insight.deleted" | "insight.pinned" | "insight.unpinned" | "insight.status_changed" | "insight.linked" | "insight.unlinked" | "insight.rejected" | "insight.needs_context" | "insight.review_team_changed" | "tag.created" | "tag.updated" | "tag.deleted" | "tag_theme.created" | "tag_theme.updated" | "tag_theme.deleted" | "prd_template.created" | "prd_template.updated" | "prd_template.deleted" | "time_entry.created" | "time_entry.updated" | "time_entry.deleted" | "time_entry.range_upserted" | "strategy.created" | "strategy.updated" | "strategy.published" | "strategy.archived" | "comment.created" | "comment.updated" | "comment.deleted" | "customer.created" | "customer.updated" | "customer.deleted" | "customer.opportunity_linked" | "customer.opportunity_unlinked" | "customer.update_posted" | "customer.contact_added" | "customer.onboarding_started" | "customer.went_live" | "opportunity.content_updated" | "room.created" | "room.updated" | "room.archived" | "room.member_added" | "room.member_removed" | "room.pinned" | "room.unpinned" | "room.notification_level_changed" | "room.marked_read" | "message.created" | "message.edited" | "message.deleted" | "message.pinned" | "message.unpinned" | "message.reaction_added" | "message.reaction_removed" | "subscription.created" | "subscription.muted" | "good_vibes.posted" | "team_queue.reordered" | "team_queue.chain_added" | "team_queue.chain_removed" | "team_queue.cross_team_chain_added" | "team_queue.window_set" | "webhook_subscription.created" | "webhook_subscription.updated" | "webhook_subscription.deleted" | "external_ref.attached"[]optional
descriptionstringoptional
activeobjectoptional
false pauses deliveries, true resumes them
Returns · 200 — Update a webhook subscription
oktruerequired
dataobjectrequired
Show child attributes ›
idstring<uuid>required
orgIdstring<uuid>required
urlstringrequired
eventTypesstring[]required
activebooleanrequired
descriptionobjectrequired
createdByAppIdobjectrequired
createdAtstringrequired
updatedAtstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
PATCH request
curl -X PATCH 'https://www.telos-app.com/api/v1/webhook-subscriptions/{id}' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "id": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "orgId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "url": "string",
    "eventTypes": [
      "string"
    ],
    "active": true,
    "description": null,
    "createdByAppId": null,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
DELETE/api/v1/webhook-subscriptions/{id}

Delete a webhook subscription

Delete a webhook subscription. Deliveries stop immediately.

Parameters
idpath · stringrequired
id path parameter
Returns · 200 — Delete a webhook subscription
oktruerequired
dataobjectrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
DELETE request
curl -X DELETE 'https://www.telos-app.com/api/v1/webhook-subscriptions/{id}' \
  -H 'Authorization: Bearer telos_live_…'
response
{
  "ok": true,
  "data": null,
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}
POST/api/v1/webhook-subscriptions/{id}/test

Send a test event to a webhook subscription

Emit a synthetic event so you can verify the endpoint and its signature check end to end. Returns the emitted event id; the delivery itself lands at your endpoint, signed with the subscription's secret.

Parameters
idpath · stringrequired
id path parameter
Request body · required

Empty object.

Returns · 200 — Send a test event to a webhook subscription
oktruerequired
dataobjectrequired
Show child attributes ›
eventIdstringrequired
metaobjectrequired
Show child attributes ›
requestIdstring<uuid>required
timestampstring<date-time>required
version"v1"required
idempotencyKeystringoptional
paginationobjectoptional
Show child attributes ›
cursorstringrequired
hasMorebooleanrequired
linksobjectrequired
actionsobject[]optional
Show child attributes ›
namestringrequired
method"GET" | "POST" | "PATCH" | "DELETE"required
hrefstringrequired
bodyobjectoptional
POST request
curl -X POST 'https://www.telos-app.com/api/v1/webhook-subscriptions/{id}/test' \
  -H 'Authorization: Bearer telos_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ … }'
response
{
  "ok": true,
  "data": {
    "eventId": "string"
  },
  "meta": {
    "requestId": "01J9Z3F4S0Z9KMQ4N6PYZR7C5A",
    "timestamp": "2026-06-26T14:23:11.842Z",
    "version": "v1",
    "idempotencyKey": "string"
  },
  "pagination": {
    "cursor": "string",
    "hasMore": true
  },
  "links": {},
  "actions": [
    {
      "name": "string",
      "method": "GET",
      "href": "string",
      "body": {}
    }
  ]
}