Ingest API
HTTP event ingest, auth, payloads, and error codes
Use the REST ingest API when you cannot use an SDK, or for synthetic/test traffic.
Endpoint: POST {baseUrl}/api/v1/events
Auth: Authorization: Bearer sg_ingest_...
Request body
{
"events": [
{
"feature_id": "chat",
"model": "gpt-4o-mini",
"input_tokens": 500,
"output_tokens": 120,
"environment": "prod",
"customer_id": "cus_123",
"latency_ms": 420,
"provider": "openai"
}
]
}
| Field | Required | Notes |
|---|---|---|
feature_id | yes | Product capability label |
model | yes | Used for pricing tables |
input_tokens / output_tokens | yes | Non-negative integers |
environment | no | Defaults to production. Aliases like prod normalize to production on ingest |
customer_id | no | Enables Margin |
latency_ms | no | |
ts | no | ISO timestamp; server time if omitted |
ShipGauge estimates cost_usd from the model price table when not provided.
Example
curl -X POST "https://shipgauge.dev/api/v1/events" \
-H "Authorization: Bearer $SHIPGAUGE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"events":[{"feature_id":"chat","model":"gpt-4o-mini","input_tokens":100,"output_tokens":50}]}'
Related endpoints (CLI)
- Eval run upload — used by
@shipgauge/cli(/api/v1/eval-runs) - Gate check reporting — (
/api/v1/gate-check)
Prefer the CLI over hand-rolling these unless you are building custom CI.
Error responses
| Status | Code / meaning |
|---|---|
401 | Missing/invalid API key |
402 | Plan quota exceeded (events/evals) |
403 | Organization suspended |
429 | Soft ingest rate limit (org throttle) or hard budget block |
503 | Platform ingest temporarily disabled |
Verify
Successful ingest returns 2xx. Check Overview within a minute.