API HTTP

Gli SDK sono una comodità: sotto, ognuno fa le richieste HTTP di questa pagina. Usa l'API direttamente da un linguaggio senza SDK, da uno script o dalla CI.

Prima di cominciare

Ti servono tre cose, tutte dalle impostazioni del progetto in CloseYourIt:

• l'indirizzo della tua installazione, per esempio https://bugs.example.com;
• l'id del progetto;
• un token di ingest (cyi_…).

Il token è segreto e resta sul server. ingest permette di mandare dati; le letture private richiedono lo scope separato read. I client browser e mobile usano una chiave pubblica per i segnali supportati, senza accesso in lettura né di amministrazione. I segnali disponibili dipendono dall'SDK e dalla versione; vedi SDK JavaScript.

Ogni richiesta porta il token e manda JSON, con i nomi dei campi in snake_case:

Authorization: Bearer cyi_...
Content-Type: application/json

Dove mandare

L'<id> nell'indirizzo deve essere il progetto a cui appartiene il token.

202 vuol dire accettato, non salvato: i dati li scrive un attimo dopo un lavoro in background. accepted conta gli elementi che hanno passato i primi controlli.

Mandare un errore

Il corpo è un evento nel formato di Sentry.

curl -X POST https://bugs.example.com/api/v1/projects/$PROJECT_ID/events \
  -H "Authorization: Bearer $CYI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "fc6d8c0c43fc4630ad850ee518f1b9d0",
    "timestamp": "2026-10-03T10:15:30Z",
    "level": "error",
    "platform": "ruby",
    "environment": "production",
    "release": "v1.4.2",
    "exception": { "values": [ {
      "type": "RuntimeError",
      "value": "boom",
      "stacktrace": { "frames": [
        { "filename": "app/models/order.rb", "function": "charge", "lineno": 42, "in_app": true }
      ] }
    } ] }
  }'

Gli errori si raggruppano per tipo di eccezione e punto del codice, non per il testo del messaggio.

Mandare log

curl -X POST https://bugs.example.com/api/v1/projects/$PROJECT_ID/logs \
  -H "Authorization: Bearer $CYI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    { "timestamp": "2026-10-03T10:15:30Z", "level": "info", "message": "order charged",
      "logger": "billing", "attributes": { "order_id": 7 } }
  ]'

Mandare campioni di prestazioni

curl -X POST https://bugs.example.com/api/v1/projects/$PROJECT_ID/metrics \
  -H "Authorization: Bearer $CYI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    { "kind": "slow_query", "duration_ms": 812.4,
      "sql": "SELECT * FROM orders WHERE id = 7", "environment": "production" },
    { "kind": "slow_method", "duration_ms": 240.0, "label": "Invoice#render" }
  ]'

Mandare visite

curl -X POST https://bugs.example.com/api/v1/projects/$PROJECT_ID/pageviews \
  -H "Authorization: Bearer $CYI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "hostname": "www.example.com", "path": "/pricing",
        "referrer": "https://www.google.com/", "utm_source": "newsletter" }'

Non si usano cookie. Il visitatore si conta da un hash che cambia ogni giorno e non si può riportare a una persona. Una richiesta che sembra di un bot riceve 202 con accepted: 0.

Le visite richiedono il token segreto, quindi questo indirizzo si chiama dal tuo server, non dal browser. Per un sito web usa l'SDK JavaScript.

Limiti

Oltre un limite di dimensione la risposta è 413 e non si salva niente. Oltre un limite di frequenza la risposta è 429 con l'intestazione Retry-After, in secondi.

Con il gateway di ingest acceso, una richiesta può essere al massimo di 5 MB.

Quando qualcosa va storto

Una risposta di errore è così:

{ "error": { "code": "R422-LOG-004", "message": "…" } }

Per ritentare senza doppioni tieni lo stesso event_id o sample_id: CloseYourIt ignora la copia se il primo tentativo era arrivato. Fanno eccezione i pezzi di registrazione: un pezzo rimandato può essere salvato due volte.

Rileggere i dati

Lo stesso token legge i dati del progetto. Ogni indirizzo restituisce gli ultimi 25 elementi.

curl -H "Authorization: Bearer $CYI_TOKEN" \
  "https://bugs.example.com/api/v1/error_groups?status=unresolved"

Per segnare un errore come risolto: PUT /api/v1/error_groups/<id>/resolution. Per riaprirlo: DELETE sullo stesso indirizzo.

Se vieni da Sentry

Le applicazioni che usano già un SDK di Sentry non hanno bisogno di questa pagina: tengono il loro SDK e cambiano un'impostazione. Vedi SDK Sentry.