Skip to main content

Management API

The API the CLI, AI agents and your scripts use to manage Collector as a person: projects and their setup, issues, logs, speed, members. Sending events is a different API: see the ingestion protocol.

Conventions​

Base URL: Collector's URL plus /api/v1: https://app.clt.chrom.ar/api/v1.

Authentication: an access token, in the header only:

Authorization: Bearer cltp_…

A token acts as its person, with their current role in each organization. If it was created limited to one organization, any other answers 404, as if it didn't exist; if it's read-only, any request that isn't GET answers 403 read_only. Removing someone from an organization or changing their role applies to their tokens at once. Tokens don't expire: they work until revoked.

Format: JSON in and out, snake_case. Times are ISO 8601 in UTC. Ids are 12-character strings. Organizations and projects are named by their slugs, as in the app's URLs. A person carries name and last_name (null when not given). Clients must ignore fields they don't know.

Language: messages and the issue Markdown are in the person's language; Accept-Language: en or es overrides it per request. Field names, error codes and enum values are always English.

Errors:

{"error": {"code": "not_found", "message": "That project doesn't exist."}}
StatuscodeWhen
400invalidA malformed parameter: unknown filter value, bad cursor
401unauthorizedNo token, an unknown one or a revoked one; with WWW-Authenticate: Bearer
403forbiddenThe person's role doesn't allow it
403read_onlyA write with a read-only token
404not_foundMissing, or not visible to this token
422invalidValidation; adds "fields": {"name": ["can't be blank"]}
429rate_limitedOver 600 requests a minute for this token; Retry-After says how many seconds to wait

Pagination: lists answer {"data": […], "next_cursor": "…"}; pass ?cursor= for the next page. next_cursor is null on the last one. ?limit= sets the page size, 1 to 100; the default is 50.

Answers to changes: creating or changing something answers the same object its list shows (plus a one-time secret where noted).

Redirects: an issue merged into another, or an event moved to another issue, answers 308 with Location pointing to where it is now. Follow it.

Versioning: new fields and new endpoints don't change the version. A breaking change would come as /api/v2.

Not here, on purpose: deleting a project, rotating its DSN, creating or deleting an organization. That way a token can never break a running app; those stay in the web app.

Signing in​

collector login's device flow (RFC 8628): the CLI shows a code and the person approves it in a browser, on any device. See Signing in from the CLI.

POST /api/v1/login/device​

No token. Starts a login.

{"client_name": "collector-cli on my-laptop"}
{
"device_code": "…",
"user_code": "WDJB-MJHT",
"verification_uri": "https://app.clt.chrom.ar/login/device",
"verification_uri_complete": "https://app.clt.chrom.ar/login/device?code=WDJBMJHT",
"expires_in": 600,
"interval": 5
}

The client prints user_code and verification_uri, and opens verification_uri_complete when it can. device_code is a secret: never print it. Rate limited per IP to 10 a minute: over it, 429 rate_limited with Retry-After.

POST /api/v1/login/token​

No token. Polls for the result every interval seconds.

{"device_code": "…"}

Approved (once; the code is used up):

{"token": "cltp_…", "user": {"id": "…", "name": "Ana", "last_name": "Smith", "email": "…"}}

Otherwise 400 with RFC 8628's shape (not the usual error shape):

errorMeansThe client
authorization_pendingNot answered yetKeeps polling
slow_downPolled faster than intervalAdds 5 s to the interval
access_deniedThe person denied itStops
expired_tokenOver 10 minutes, already collected, or no such codeStops and starts again

Who's calling​

GET /api/v1/me​

{
"user": {"id": "…", "name": "Ana", "last_name": "Smith", "email": "…", "locale": "en"},
"token": {"name": "laptop", "access": "write", "organization": null},
"organizations": [{"slug": "acme", "name": "Acme", "role": "owner"}]
}

token.organization is the organization the token is limited to, or null. When limited, organizations lists only that one.

DELETE /api/v1/me/token​

Revokes the token making the call: what collector logout does. 204. Read-only tokens may call it too.

Organizations​

GET /api/v1/orgs​

The caller's organizations, with their role in each:

{"data": [{"slug": "acme", "name": "Acme", "role": "owner",
"created_at": "…", "url": "https://app.clt.chrom.ar/o/acme"}],
"next_cursor": null}

GET /api/v1/orgs/:org​

One of them, in the same shape.

PATCH /api/v1/orgs/:org​

Owners only.

{"name": "Acme Labs", "slug": "acme-labs"}

Either field or both. 200 with the organization. A new slug changes its URLs (the app's too) and the old one answers 404 from then on. A blank name, a blank slug or a taken one is a 422. Audited.

Projects​

GET /api/v1/orgs/:org/projects​

Anyone in the organization.

{"data": [{"id": "…", "slug": "shop", "name": "Shop",
"platforms": ["elixir", "javascript"], "unresolved_count": 3,
"created_at": "…", "url": "https://app.clt.chrom.ar/o/acme/p/shop"}],
"next_cursor": null}

platforms are the ones that have reported: elixir, node, javascript, other.

POST /api/v1/orgs/:org/projects​

Owners and admins. {"name": "Shop"}. 201 with the project and its dsn.

GET /api/v1/orgs/:org/projects/:project​

Anyone in the organization. The project with its dsn, and muted: whether the caller muted its emails. A project whose key is from before DSNs could be shown again has "dsn": null and a "dsn_hint" saying to rotate it in the web app.

PATCH /api/v1/orgs/:org/projects/:project​

Owners and admins rename it: {"name": "Web shop"}. 200 with the project. The slug never changes, so links and --project keep working. A blank name is a 422. Audited.

PUT /api/v1/orgs/:org/projects/:project/mute, DELETE /api/v1/orgs/:org/projects/:project/mute​

Anyone in the organization turns the project's issue emails off (PUT) or back on (DELETE), for themselves only, with a token that can write. 204 either way, even when nothing changed.

GET /api/v1/orgs/:org/projects/:project/signals​

Anyone in the organization. Which servers and browsers report, one per environment and kind, latest first:

{"data": [{"environment": "production", "source": "server", "status": "active",
"last_seen_at": "…", "sdk_name": "collector", "sdk_version": "0.5.4",
"release": "v57", "server": "web-1", "runtime": {"elixir": "1.19.4"},
"heartbeat_at": null}],
"next_cursor": null}

source: server or browser. status: active (seen lately: 3 hours for servers, a day for browsers), quiet (servers Collector alerted about, or silent past 3 hours in an environment that alerts) or idle (otherwise silent: browsers, and servers in dev or test or that never stayed up). See Signals.

Upload tokens​

For source map uploads from CI. Owners and admins.

GET /api/v1/orgs/:org/projects/:project/upload-tokens​

{"data": [{"id": "…", "name": "GitHub Actions", "hint": "x7Kp",
"last_used_at": "…", "created_by": {"id": "…", "name": "Ana", "last_name": "Smith"},
"created_at": "…"}], "next_cursor": null}

POST /api/v1/orgs/:org/projects/:project/upload-tokens​

{"name": "GitHub Actions"}. 201 with the list's object plus its secret (cltu_…), shown this once.

DELETE /api/v1/orgs/:org/projects/:project/upload-tokens/:id​

Revokes it. 204.

Server keys​

For servers to send logs. Owners and admins, in the same shapes as upload tokens.

GET /api/v1/orgs/:org/projects/:project/server-keys​

The list, like the upload tokens'.

POST /api/v1/orgs/:org/projects/:project/server-keys​

{"name": "API servers"}. 201 with its secret (clts_…), shown this once.

DELETE /api/v1/orgs/:org/projects/:project/server-keys/:id​

Revokes it: logs sent with it are refused at once. 204.

Allowed domains​

Anyone in the organization lists them; owners and admins change them. See Allowed domains.

GET /api/v1/orgs/:org/projects/:project/origins​

{"data": [{"origin": "https://shop.example.com", "status": "pending",
"created_at": "…"}], "next_cursor": null}

PUT /api/v1/orgs/:org/projects/:project/origins​

Allows or blocks one, even one not seen yet, so a domain can be allowed before it's deployed.

{"origin": "https://shop.example.com", "status": "allowed"}

200. Strict: origin must be a scheme and a host, with an optional port; a bare host is a 422, so http and https are never guessed.

DELETE /api/v1/orgs/:org/projects/:project/origins​

?origin=https://shop.example.com. Forgets it: its next event asks again. 204. The origin is a query value because it contains ://.

Issues​

GET /api/v1/orgs/:org/projects/:project/issues​

Anyone in the organization. Last seen first. Filters, as in the app's list:

ParameterValuesDefault
statusunresolved, resolved, ignoredunresolved
rangeday, week, month (seen in it), allweek
releasea release, matched against first_release (what a deploy introduced)all
environmentan environmentall
platformelixir, node, javascript, or other for any without a package of its ownall
qtext in the title, message and culprit, any casenone
{"data": [{
"id": "2C7ZffP787kc", "title": "TypeError", "subtitle": "this._beamMs is not a function",
"culprit": "assets/js/discovery_map.js.updated", "level": "error", "platform": "javascript",
"status": "unresolved", "assignee": null,
"events_count": 1, "users_count": 0, "events_in_range": 1,
"first_seen_at": "…", "last_seen_at": "…", "first_release": "0bd55ed", "last_release": "0bd55ed",
"url": "https://app.clt.chrom.ar/o/acme/p/shop/issues/2C7ZffP787kc"
}], "next_cursor": "…"}

assignee, when set: {"id", "name", "last_name", "email"}. events_in_range counts the range's events; events_count, all of them.

GET /api/v1/issues/:id​

An issue by its id alone, for when that's all you have: 308 to its full path. 404 if the token can't see it.

GET /api/v1/orgs/:org/projects/:project/issues/:id​

The issue, plus latest_event: its newest event that kept its details, in full.

With Accept: text/markdown, the issue as Markdown, written for an AI asked to fix it: the error, the stack trace with the code around each of the app's lines (dependency frames folded per package), whether source maps resolved it, the request (without headers that could carry secrets), the last of what happened before, the tags and how to mark it resolved through this API. Copy as Markdown in the app gives the same text, minus that last part.

GET /api/v1/orgs/:org/projects/:project/issues/:issue_id/events​

Its events, newest first:

{"data": [{"uuid": "…", "occurred_at": "…", "received_at": "…",
"environment": "production", "release": "0bd55ed", "kept": true}],
"next_cursor": null}

kept is false for events stored without details for being over the project's limit.

GET /api/v1/orgs/:org/projects/:project/issues/:issue_id/events/:uuid​

One event in full: the above plus payload, what the app sent as Collector stored it (The event), with sourcemaps ({"release", "status": "resolved" | "missing"}) on browser events and minified on each frame a map resolved. payload is null for events that weren't kept. With Accept: text/markdown, the issue told through this event.

PATCH /api/v1/orgs/:org/projects/:project/issues/:id​

Anyone in the organization. Either field or both:

{"status": "resolved", "assignee": "me"}

status: resolved, ignored or unresolved (reopens it). assignee: a member's email, "me", or null to unassign; someone who isn't a member is a 422. 200 with the issue. Changes go into the audit log as the person's, marked as made through the CLI with the token's name.

Logs​

What the project's servers sent: log lines, requests and sign-ins, in one timeline, newest first. Only where Collector stores logs; elsewhere, 404.

GET /api/v1/orgs/:org/projects/:project/logs​

Paged. Filters, all optional, as the Logs tab's:

ParameterMeaning
env, server, service, request, userExact match on every kind of record (service is OpenTelemetry's service.name)
from, toISO 8601 times
qText in messages, request paths and sign-in accounts
ip, account, status (404, 5xx), pathThe requests and sign-ins that have it, and those requests' lines
levelMinimum: warning, error, … A 5xx counts as error; a 4xx and a failed sign-in as warning
typelog, request, sign_in, comma separated

Each record has kind (log, request or sign_in), id, at, and the fields it has.

{"data": [{"kind": "log", "id": "01J…", "at": "2026-11-11T14:02:07.121000Z",
"level": "error", "message": "** (RuntimeError) boom", "server": "web-1",
"request_id": "F3x…"}],
"next_cursor": "MTc5…"}

With Accept: text/markdown, one line per record, oldest first (a story read from the top), under a heading per day. 503 unavailable when logs can't be read right now.

Following live: collector logs --follow uses a Phoenix channel at wss://app.clt.chrom.ar/api/v1/socket/websocket, with the token in the Sec-WebSocket-Protocol header, never in the URL. The topic is logs:<org>/<project> and takes the same filters, except the time ones. It sends at most 1,000 records a second per channel; what's left out is counted in skipped. The token and membership are checked again every 30 seconds.

Speed​

Only where Collector stores speed (elsewhere 404; 503 unavailable when it can't answer). Anyone in the organization. What the Speed tab shows, with its filters: env (by default, the one with the most page views), period (day, week by default, month, quarter) and device (phone, tablet, desktop). A value that isn't one of those is a 400.

GET /api/v1/orgs/:org/projects/:project/speed​

{"environment": "production", "environments": ["production"],
"period": "week", "device": null, "views": 1520, "dropped": 0, "sample_rates": [1.0],
"vitals": {"lcp": {"p75": 2400, "good": 0.81, "needs_work": 0.12, "poor": 0.07, "samples": 1490},
"inp": {…}, "cls": {…}}}

views are weighted by the sample rate. good, needs_work and poor are shares of the rated page views; samples, how many real page views have that measure. Times in ms.

GET /api/v1/orgs/:org/projects/:project/speed/pages​

The pages, slowest first, paged: route, navigation (hard or soft), views and the p75 lcp, nav and inp.

GET /api/v1/orgs/:org/projects/:project/speed/page​

?route=/checkout. One page: its measures, its devices and its 20 slowest visits.

GET /api/v1/orgs/:org/projects/:project/speed/requests​

The requests pages make, slowest p75 first, paged: method, route, calls, failed (the share with status 0 or 5xx), p75 and start.

GET /api/v1/orgs/:org/projects/:project/speed/request​

?method=GET&route=/api/cart. One request: the pages that make it and its 20 slowest calls.

Audit log​

GET /api/v1/orgs/:org/audits​

Owners and admins. Who did what, newest first, paged:

{"data": [{"id": "…", "action": "project.updated",
"actor": {"id": "…", "name": "Ana", "last_name": "Smith"},
"target_type": "project", "target_id": "…",
"changes": {"name": ["Shop", "Storefront"]},
"via": "CLI: laptop", "ip": "203.0.113.9", "created_at": "…"}],
"next_cursor": "…"}

actor is null for Collector itself. via says how (CLI: <token name> for this API); changes are [before, after] pairs, or values.

Members​

With the app's rules: owners change anyone; admins change admins and members, but never make or change an owner. Nobody changes their own role. Every change is audited and the person gets the same email the app sends.

GET /api/v1/orgs/:org/members​

Anyone in the organization:

{"data": [{"id": "…", "name": "Ana", "last_name": "Smith", "email": "…", "role": "owner"}],
"next_cursor": null}

PATCH /api/v1/orgs/:org/members/:id​

Owners and admins. {"role": "admin"}: member, admin or owner. 200 with the member. The role they already have changes nothing.

DELETE /api/v1/orgs/:org/members/:id​

Owners and admins remove someone. 204.

DELETE /api/v1/orgs/:org/members/me​

The caller leaves the organization. 204. The last owner can't (422): another owner first.

Invitations​

Anyone in the organization lists them; owners and admins invite, resend and revoke. They last seven days, and the email with the link goes out at once.

GET /api/v1/orgs/:org/invitations​

The pending ones, newest first:

{"data": [{"id": "…", "email": "new@example.com", "role": "member",
"invited_by": {"id": "…", "name": "Ana", "last_name": "Smith"},
"created_at": "…", "expires_at": "…"}],
"next_cursor": null}

POST /api/v1/orgs/:org/invitations​

{"email": "new@example.com", "role": "member"}. 201. role defaults to member; admins can't invite owners (403). Inviting an address again replaces its pending invitation. An address that already belongs to a member, or isn't an email, is a 422.

POST /api/v1/orgs/:org/invitations/:id/resend​

Sends it again with a fresh link and seven more days, an expired one too. 200.

DELETE /api/v1/orgs/:org/invitations/:id​

Revokes it: its link stops working. 204.

Uploading maps with an access token​

POST /api/sourcemaps (protocol) accepts, besides an upload token, an access token that can write, from an owner or admin of the project, naming the project in a header:

Authorization: Bearer cltp_…
X-Collector-Project: acme/shop

With an access token, refusals use this API's error shape: 401 unauthorized, 403 read_only, 403 forbidden (not an owner or admin), 400 invalid (no X-Collector-Project, or not org/project) and 404 not_found.