API de administración
La API con la que la CLI, los agentes de IA y tus scripts manejan Collector como una persona: proyectos y su configuración, problemas, registros, velocidad, miembros. Mandar eventos es otra API: ver el protocolo de envío.
Convenciones
URL base: la de Collector más /api/v1: https://app.clt.chrom.ar/api/v1.
Autenticación: una credencial de acceso, solo en el encabezado:
Authorization: Bearer cltp_…
Una credencial actúa como su persona, con su rol actual en cada organización. Si se creó limitada a una organización, cualquier otra contesta 404, como si no existiera; si es de solo lectura, todo pedido que no sea GET contesta 403 read_only. Quitar a alguien de una organización o cambiar su rol se aplica a sus credenciales al instante. Las credenciales no vencen: funcionan hasta que se revocan.
Formato: JSON de ida y vuelta, en snake_case. Las horas son ISO 8601 en UTC. Los identificadores son textos de 12 caracteres. Organizaciones y proyectos se nombran por su dirección (slug), como en las URL de la aplicación. Una persona trae name y last_name (null si no lo dio). Los clientes deben ignorar los campos que no conocen.
Idioma: los mensajes y el Markdown de los problemas salen en el idioma de la persona; Accept-Language: en o es lo cambia por pedido. Los nombres de campos, los códigos de error y los valores de enumeraciones siempre están en inglés.
Errores:
{"error": {"code": "not_found", "message": "That project doesn't exist."}}
| Estado | code | Cuándo |
|---|---|---|
| 400 | invalid | Un parámetro mal formado: un filtro desconocido, un cursor roto |
| 401 | unauthorized | Sin credencial, una desconocida o una revocada; con WWW-Authenticate: Bearer |
| 403 | forbidden | El rol de la persona no lo permite |
| 403 | read_only | Un cambio con una credencial de solo lectura |
| 404 | not_found | No existe, o esta credencial no lo ve |
| 422 | invalid | Validación; agrega "fields": {"name": ["can't be blank"]} |
| 429 | rate_limited | Más de 600 pedidos por minuto con esta credencial; Retry-After dice cuántos segundos esperar |
Paginación: las listas contestan {"data": […], "next_cursor": "…"}; pasa ?cursor= para la página siguiente. next_cursor es null en la última. ?limit= fija el tamaño de página, de 1 a 100; por defecto, 50.
Respuestas a cambios: crear o cambiar algo contesta el mismo objeto que muestra su lista (más un secret de una sola vez donde se indica).
Redirecciones: un problema que se unió a otro, o un evento que pasó a otro problema, contesta 308 con Location apuntando a donde está ahora. Síguela.
Versiones: los campos y endpoints nuevos no cambian la versión. Un cambio incompatible llegaría como /api/v2.
Lo que no está, a propósito: eliminar un proyecto, rotar su DSN, crear o eliminar una organización. Así una credencial nunca puede romper una aplicación en marcha; esas acciones quedan en la aplicación web.
Iniciar sesión
El flujo de dispositivo de collector login (RFC 8628): la CLI muestra un código y la persona lo aprueba en un navegador, en cualquier dispositivo. Ver Iniciar sesión desde la CLI.
POST /api/v1/login/device
Sin credencial. Empieza un inicio de sesión.
{"client_name": "collector-cli on mi-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
}
El cliente muestra user_code y verification_uri, y abre verification_uri_complete cuando puede. device_code es secreto: nunca lo muestres. Limitado por IP a 10 por minuto: pasado eso, 429 rate_limited con Retry-After.
POST /api/v1/login/token
Sin credencial. Consulta el resultado cada interval segundos.
{"device_code": "…"}
Aprobado (una sola vez; el código queda usado):
{"token": "cltp_…", "user": {"id": "…", "name": "Ana", "last_name": "Pérez", "email": "…"}}
Si no, 400 con la forma de RFC 8628 (no la forma de error de siempre):
error | Significa | El cliente |
|---|---|---|
authorization_pending | Todavía no contestaron | Sigue consultando |
slow_down | Consultó más rápido que interval | Suma 5 s al intervalo |
access_denied | La persona lo denegó | Para |
expired_token | Pasaron 10 minutos, ya se recogió, o el código no existe | Para y vuelve a empezar |
Quién llama
GET /api/v1/me
{
"user": {"id": "…", "name": "Ana", "last_name": "Pérez", "email": "…", "locale": "es"},
"token": {"name": "laptop", "access": "write", "organization": null},
"organizations": [{"slug": "acme", "name": "Acme", "role": "owner"}]
}
token.organization es la organización a la que está limitada la credencial, o null. Si está limitada, organizations lista solo esa.
DELETE /api/v1/me/token
Revoca la credencial que hace el pedido: lo que hace collector logout. 204. Las credenciales de solo lectura también pueden.
Organizaciones
GET /api/v1/orgs
Las organizaciones de quien llama, con su rol en cada una:
{"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
Una de ellas, con la misma forma.
PATCH /api/v1/orgs/:org
Solo propietarios.
{"name": "Acme Labs", "slug": "acme-labs"}
Uno de los dos campos o ambos. 200 con la organización. Una dirección nueva cambia sus URL (también las de la aplicación) y la anterior contesta 404 desde entonces. Un nombre o una dirección vacíos, o una dirección tomada, son un 422. Queda en el registro de auditoría.
Proyectos
GET /api/v1/orgs/:org/projects
Cualquiera de la organización.
{"data": [{"id": "…", "slug": "tienda", "name": "Tienda",
"platforms": ["elixir", "javascript"], "unresolved_count": 3,
"created_at": "…", "url": "https://app.clt.chrom.ar/o/acme/p/tienda"}],
"next_cursor": null}
platforms son las que reportaron: elixir, node, javascript, other.
POST /api/v1/orgs/:org/projects
Propietarios y administradores. {"name": "Tienda"}. 201 con el proyecto y su dsn.
GET /api/v1/orgs/:org/projects/:project
Cualquiera de la organización. El proyecto con su dsn, y muted: si quien llama silenció sus correos. Un proyecto cuya clave es de antes de que el DSN se pudiera volver a mostrar trae "dsn": null y un "dsn_hint" que dice que hay que rotarla en la aplicación web.
PATCH /api/v1/orgs/:org/projects/:project
Propietarios y administradores lo renombran: {"name": "Tienda web"}. 200 con el proyecto. La dirección nunca cambia, así que los enlaces y --project siguen funcionando. Un nombre vacío es un 422. Queda en el registro de auditoría.
PUT /api/v1/orgs/:org/projects/:project/mute, DELETE /api/v1/orgs/:org/projects/:project/mute
Cualquiera de la organización apaga (PUT) o vuelve a encender (DELETE) los correos de problemas del proyecto, solo para sí, con una credencial que puede escribir. 204 siempre, aunque nada cambie.
GET /api/v1/orgs/:org/projects/:project/signals
Cualquiera de la organización. Qué servidores y navegadores reportan, uno por entorno y tipo, el más reciente primero:
{"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 o browser. status: active (visto hace poco: 3 horas para servidores, un día para navegadores), quiet (servidores por los que Collector avisó, o callados por más de 3 horas en un entorno que avisa) o idle (callados por lo demás: navegadores, y servidores de desarrollo o pruebas o que nunca estuvieron arriba). Ver Señales.
Credenciales de subida
Para subir mapas de código fuente desde la integración continua. Propietarios y administradores.
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": "Pérez"},
"created_at": "…"}], "next_cursor": null}
POST /api/v1/orgs/:org/projects/:project/upload-tokens
{"name": "GitHub Actions"}. 201 con el objeto de la lista más su secret (cltu_…), que solo se muestra esta vez.
DELETE /api/v1/orgs/:org/projects/:project/upload-tokens/:id
La revoca. 204.
Claves de servidor
Para que los servidores manden registros. Propietarios y administradores, con la misma forma que las credenciales de subida.
GET /api/v1/orgs/:org/projects/:project/server-keys
La lista, como la de credenciales de subida.
POST /api/v1/orgs/:org/projects/:project/server-keys
{"name": "Servidores de la API"}. 201 con su secret (clts_…), que solo se muestra esta vez.
DELETE /api/v1/orgs/:org/projects/:project/server-keys/:id
La revoca: los registros mandados con ella se rechazan al instante. 204.
Dominios permitidos
Cualquiera de la organización los lista; propietarios y administradores los cambian. Ver Dominios permitidos.
GET /api/v1/orgs/:org/projects/:project/origins
{"data": [{"origin": "https://tienda.ejemplo.com", "status": "pending",
"created_at": "…"}], "next_cursor": null}
PUT /api/v1/orgs/:org/projects/:project/origins
Permite o bloquea uno, aunque todavía no se haya visto, así un dominio se puede permitir antes de desplegar.
{"origin": "https://tienda.ejemplo.com", "status": "allowed"}
200. Estricto: origin tiene que ser un esquema y un host, con puerto opcional; un host solo es un 422, para no adivinar nunca entre http y https.
DELETE /api/v1/orgs/:org/projects/:project/origins
?origin=https://tienda.ejemplo.com. Lo olvida: su próximo evento vuelve a preguntar. 204. El origen va como parámetro de query porque contiene ://.
Problemas
GET /api/v1/orgs/:org/projects/:project/issues
Cualquiera de la organización. El visto más recientemente primero. Filtros, como en la lista de la aplicación:
| Parámetro | Valores | Por defecto |
|---|---|---|
status | unresolved, resolved, ignored | unresolved |
range | day, week, month (vistos en ese período), all | week |
release | una versión, comparada con first_release (lo que introdujo un despliegue) | todas |
environment | un entorno | todos |
platform | elixir, node, javascript, u other para cualquiera sin paquete propio | todas |
q | texto en el título, el mensaje y la función, sin distinguir mayúsculas | ninguno |
{"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/tienda/issues/2C7ZffP787kc"
}], "next_cursor": "…"}
assignee, si hay: {"id", "name", "last_name", "email"}. events_in_range cuenta los eventos del período; events_count, todos.
GET /api/v1/issues/:id
Un problema por su identificador solo, para cuando no tienes más: 308 a su ruta completa. 404 si la credencial no lo ve.
GET /api/v1/orgs/:org/projects/:project/issues/:id
El problema, más latest_event: su evento más nuevo que guardó detalles, completo.
Con Accept: text/markdown, el problema en Markdown, escrito para una IA a la que se le pide arreglarlo: el error, la pila de llamadas con el código alrededor de cada línea de la aplicación (los marcos de dependencias plegados por paquete), si los mapas de código fuente lo resolvieron, la solicitud (sin los encabezados que pueden llevar secretos), lo último que pasó antes, las etiquetas y cómo marcarlo resuelto por esta API. Copiar como Markdown en la aplicación da el mismo texto, menos esa última parte.
GET /api/v1/orgs/:org/projects/:project/issues/:issue_id/events
Sus eventos, el más nuevo primero:
{"data": [{"uuid": "…", "occurred_at": "…", "received_at": "…",
"environment": "production", "release": "0bd55ed", "kept": true}],
"next_cursor": null}
kept es false para los eventos guardados sin detalles por pasar el límite del proyecto.
GET /api/v1/orgs/:org/projects/:project/issues/:issue_id/events/:uuid
Un evento completo: lo anterior más payload, lo que mandó la aplicación tal como Collector lo guardó (El evento), con sourcemaps ({"release", "status": "resolved" | "missing"}) en los eventos de navegador y minified en cada marco que un mapa tradujo. payload es null para los eventos no guardados. Con Accept: text/markdown, el problema contado a través de este evento.
PATCH /api/v1/orgs/:org/projects/:project/issues/:id
Cualquiera de la organización. Uno de los dos campos o ambos:
{"status": "resolved", "assignee": "me"}
status: resolved, ignored o unresolved (lo reabre). assignee: el correo de un miembro, "me", o null para quitarlo; alguien que no es miembro es un 422. 200 con el problema. Los cambios quedan en el registro de auditoría a nombre de la persona, marcados como hechos desde la CLI con el nombre de la credencial.
Registros
Lo que mandaron los servidores del proyecto: líneas de log, solicitudes e inicios de sesión, en una línea de tiempo, lo más nuevo primero. Solo donde Collector guarda registros; en otro caso, 404.
GET /api/v1/orgs/:org/projects/:project/logs
Paginada. Filtros, todos opcionales, como los de la pestaña Registros:
| Parámetro | Significa |
|---|---|
env, server, service, request, user | Coincidencia exacta en todo tipo de registro (service es el service.name de OpenTelemetry) |
from, to | Horas ISO 8601 |
q | Texto en los mensajes, las rutas de las solicitudes y las cuentas de los inicios de sesión |
ip, account, status (404, 5xx), path | Las solicitudes e inicios de sesión que lo tienen, y las líneas de esas solicitudes |
level | Mínimo: warning, error, … Un 5xx cuenta como error; un 4xx y un inicio de sesión fallido, como advertencia |
type | log, request, sign_in, separados por comas |
Cada registro tiene kind (log, request o sign_in), id, at y los campos que tenga.
{"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…"}
Con Accept: text/markdown, una línea por registro, lo más viejo primero (una historia que se lee de arriba), bajo un encabezado por día. 503 unavailable cuando los registros no se pueden leer en ese momento.
Seguir en vivo: collector logs --follow usa un canal de Phoenix en wss://app.clt.chrom.ar/api/v1/socket/websocket, con la credencial en el encabezado Sec-WebSocket-Protocol, nunca en la URL. El tema es logs:<org>/<proyecto> y acepta los mismos filtros, salvo los de tiempo. Manda hasta 1.000 registros por segundo por canal; lo que queda afuera se cuenta en skipped. La credencial y la membresía se vuelven a comprobar cada 30 segundos.
Velocidad
Solo donde Collector guarda velocidad (si no, 404; 503 unavailable cuando no puede contestar). Cualquiera de la organización. Lo que muestra la pestaña Velocidad, con sus filtros: env (por defecto, el que tiene más visitas), period (day, week por defecto, month, quarter) y device (phone, tablet, desktop). Un valor que no es ninguno de esos es un 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 está ponderado por el muestreo. good, needs_work y poor son partes de las visitas calificadas; samples, cuántas visitas reales tienen esa medida. Tiempos en ms.
GET /api/v1/orgs/:org/projects/:project/speed/pages
Las páginas, la más lenta primero, paginadas: route, navigation (hard o soft), views y los p75 de lcp, nav e inp.
GET /api/v1/orgs/:org/projects/:project/speed/page
?route=/checkout. Una página: sus medidas, sus dispositivos y sus 20 visitas más lentas.
GET /api/v1/orgs/:org/projects/:project/speed/requests
Los pedidos que hacen las páginas, el p75 más lento primero, paginados: method, route, calls, failed (la parte con estado 0 o 5xx), p75 y start.
GET /api/v1/orgs/:org/projects/:project/speed/request
?method=GET&route=/api/cart. Un pedido: las páginas que lo hacen y sus 20 llamadas más lentas.
Registro de auditoría
GET /api/v1/orgs/:org/audits
Propietarios y administradores. Quién hizo qué, lo más nuevo primero, paginado:
{"data": [{"id": "…", "action": "project.updated",
"actor": {"id": "…", "name": "Ana", "last_name": "Pérez"},
"target_type": "project", "target_id": "…",
"changes": {"name": ["Shop", "Storefront"]},
"via": "CLI: laptop", "ip": "203.0.113.9", "created_at": "…"}],
"next_cursor": "…"}
actor es null para Collector mismo. via dice cómo (CLI: <nombre de la credencial> por esta API); changes son pares [antes, después], o valores.
Miembros
Con las reglas de la aplicación: los propietarios cambian a cualquiera; los administradores cambian administradores y miembros, pero nunca nombran ni cambian a un propietario. Nadie cambia su propio rol. Cada cambio queda auditado y la persona recibe el mismo correo que manda la aplicación.
GET /api/v1/orgs/:org/members
Cualquiera de la organización:
{"data": [{"id": "…", "name": "Ana", "last_name": "Pérez", "email": "…", "role": "owner"}],
"next_cursor": null}
PATCH /api/v1/orgs/:org/members/:id
Propietarios y administradores. {"role": "admin"}: member, admin u owner. 200 con el miembro. El rol que ya tiene no cambia nada.
DELETE /api/v1/orgs/:org/members/:id
Propietarios y administradores quitan a alguien. 204.
DELETE /api/v1/orgs/:org/members/me
Quien llama sale de la organización. 204. El último propietario no puede (422): primero otro propietario.
Invitaciones
Cualquiera de la organización las lista; propietarios y administradores invitan, reenvían y revocan. Duran siete días, y el correo con el enlace sale al instante.
GET /api/v1/orgs/:org/invitations
Las pendientes, la más nueva primero:
{"data": [{"id": "…", "email": "nueva@ejemplo.com", "role": "member",
"invited_by": {"id": "…", "name": "Ana", "last_name": "Pérez"},
"created_at": "…", "expires_at": "…"}],
"next_cursor": null}
POST /api/v1/orgs/:org/invitations
{"email": "nueva@ejemplo.com", "role": "member"}. 201. role es member por defecto; los administradores no pueden invitar propietarios (403). Invitar de nuevo una dirección reemplaza su invitación pendiente. Una dirección que ya es de un miembro, o que no es un correo, es un 422.
POST /api/v1/orgs/:org/invitations/:id/resend
La manda de nuevo con un enlace nuevo y siete días más, aunque haya vencido. 200.
DELETE /api/v1/orgs/:org/invitations/:id
La revoca: su enlace deja de funcionar. 204.
Subir mapas con una credencial de acceso
POST /api/sourcemaps (protocolo) acepta, además de una credencial de subida, una credencial de acceso que puede escribir, de un propietario o administrador del proyecto, nombrando el proyecto en un encabezado:
Authorization: Bearer cltp_…
X-Collector-Project: acme/tienda
Con una credencial de acceso, los rechazos usan la forma de error de esta API: 401 unauthorized, 403 read_only, 403 forbidden (no es propietario ni administrador), 400 invalid (falta X-Collector-Project o no es org/proyecto) y 404 not_found.