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."}}
| Status | code | When |
|---|---|---|
| 400 | invalid | A malformed parameter: unknown filter value, bad cursor |
| 401 | unauthorized | No token, an unknown one or a revoked one; with WWW-Authenticate: Bearer |
| 403 | forbidden | The person's role doesn't allow it |
| 403 | read_only | A write with a read-only token |
| 404 | not_found | Missing, or not visible to this token |
| 422 | invalid | Validation; adds "fields": {"name": ["can't be blank"]} |
| 429 | rate_limited | Over 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):
error | Means | The client |
|---|---|---|
authorization_pending | Not answered yet | Keeps polling |
slow_down | Polled faster than interval | Adds 5 s to the interval |
access_denied | The person denied it | Stops |
expired_token | Over 10 minutes, already collected, or no such code | Stops 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:
| Parameter | Values | Default |
|---|---|---|
status | unresolved, resolved, ignored | unresolved |
range | day, week, month (seen in it), all | week |
release | a release, matched against first_release (what a deploy introduced) | all |
environment | an environment | all |
platform | elixir, node, javascript, or other for any without a package of its own | all |
q | text in the title, message and culprit, any case | none |
{"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:
| Parameter | Meaning |
|---|---|
env, server, service, request, user | Exact match on every kind of record (service is OpenTelemetry's service.name) |
from, to | ISO 8601 times |
q | Text in messages, request paths and sign-in accounts |
ip, account, status (404, 5xx), path | The requests and sign-ins that have it, and those requests' lines |
level | Minimum: warning, error, … A 5xx counts as error; a 4xx and a failed sign-in as warning |
type | log, 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.