Response Format

Pi’s consistent response envelope, expansion convention, error structure, and HTTP status codes.

Response envelope

Every Pi response wraps its payload in a consistent top-level envelope, regardless of endpoint:

id · string

Unique request or resource id (e.g. pi_req_…).

object · string

Resource type string (e.g. job, image.generation).

status · string

Current state of the resource (e.g. queued, completed, failed).

created_at · number

Unix timestamp in seconds when the resource was created.

data · object

Primary payload. Shape varies by endpoint.

error · object

Structured error object. Present only when the request failed. See Error envelope below.

Example success response

{
  "id": "pi_req_3f2a1b",
  "object": "job",
  "status": "queued",
  "created_at": 1760000000,
  "data": {
    "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Expansion convention

Use the expand= query parameter to include a related object inline on supported endpoints:

GET /api/v1/jobs/:id?expand=brand

This returns the normal job payload plus data.expanded.brand when result_url resolves to a brand in the same organization.

Rules:

• Expansions are additive — base resource fields remain unchanged.
• If expansion is missing or unsupported, the endpoint returns the base payload only.
• Expansion never bypasses tenant isolation.

Use expansion to reduce follow-up requests. Skip it for lightweight polling where minimal payload size matters.

Error envelope

Pi uses a Stripe-style error envelope. When a request fails, the response body contains a top-level error object:

error.type · string

Broad category of the error (e.g. invalid_request_error, api_error).

error.code · string

Machine-readable error code. Use this for programmatic error handling.

error.message · string

Human-readable description of what went wrong.

error.request_id · string

Unique trace id for this request. Include it when contacting support.

Example error response

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_authorization_header",
    "message": "Missing Authorization header. Use Bearer <api_key>.",
    "request_id": "req_pi_9a8b7c6d"
  }
}

HTTP status codes

Status	Meaning
200 OK	Request succeeded. Response body contains the resource.
202 Accepted	Job created and queued. Response body contains data.job_id.
400 Bad Request	Malformed request syntax or missing required fields.
401 Unauthorized	Missing or invalid API key.
409 Conflict	Idempotency key reused with a different request body.
422 Unprocessable Entity	Request was well-formed but semantically invalid (e.g. failed Zod validation).
500 Internal Server Error	Unexpected server-side error. Retry with exponential backoff.

Common error codes

Code	HTTP status	Description
missing_authorization_header	401	No Authorization header was sent
invalid_api_key	401	The API key is malformed or revoked
rate_limit_exceeded	429	Too many requests in the current window
idempotency_key_mismatch	409	Same idempotency key used with a different request body
invalid_request_error	400 / 422	Request body failed validation
api_error	500	Unexpected internal server error

Log error.request_id in your application whenever you catch a Pi error. Include it in support tickets to help the Pi team trace the exact request.