API Response Reference
Response formats, pagination, errors, and version headers
Use this page for shared response rules. The endpoint reference defines each operation's fields and exceptions.
Success representations
The response format depends on the operation. Check its generated reference page.
| Contract kind | Typical response |
|---|---|
| Collection | { "data": [...], "meta": {...}, "links": {...} } or operation-specific pagination fields |
| Resource | { "data": {...} } plus operation-specific fields and headers |
| Representation | Plain text, audio metadata, or an optional redirect as documented |
| Agent stream | text/event-stream in AI SDK UI or OpenAI-compatible chunk format |
| Delete | 204 No Content for the documented destructive operations |
Collection cursors are opaque. Store the returned cursor or watermark. Send it back unchanged. Do not construct cursors from record IDs.
Errors
JSON errors use application/problem+json. Read resolution for the next action:
{
"type": "https://api.y2.dev/problems/unauthorized",
"title": "Unauthorized",
"status": 401,
"detail": "Invalid API key",
"instance": "urn:y2:request:req_...",
"code": "INVALID_API_KEY",
"requestId": "req_...",
"resolution": "Send a valid Y2 API key in the Authorization: Bearer header."
}| Status | Common meaning |
|---|---|
400 | Invalid query, ID, cursor, JSON, or request body |
401 | Missing or invalid bearer authentication |
402 | x402 challenge or rejection. Agent Y2 uses this status for plan or credit exhaustion |
403 | Missing scope, ineligible plan, IP restriction, or tenant authorization failure |
404 | Resource or thread not found in the allowed scope |
409 | Idempotency or resource-state conflict |
412 | If-Match does not match the current representation |
415 / 422 | Unsupported representation or operation-specific semantic failure |
429 | Key, account, endpoint, wallet, or abuse-control limit exceeded |
500 / 503 | Internal failure, unavailable dependency, or unavailable data path |
Keep X-Request-Id and the problem code in logs. Follow Retry-After when the response identifies a temporary limit or availability failure.
Version and diagnostic headers
| Header | Meaning |
|---|---|
X-Y2-API-Version | 1.0 for v1 operations and 2.0 for v2 operations |
X-Y2-Schema-Version | Shared response-schema version, currently 1.2 |
X-Request-Id | Per-request diagnostic identifier |
ETag | Strong validator on operations that support conditional writes |
Location | Canonical URL after resource creation |
Idempotency-Key | Echoed retry key on operations that support idempotent creation |
X-Y2-Next-Cursor, X-Y2-As-Of, X-Y2-Watermark | Collection and change-feed checkpoints where applicable |