Introduction

Pi is an enterprise-grade, OpenAI-compatible agentic intelligence platform. This page covers the fundamentals you need before making your first request.

Pi is an enterprise-grade Agentic Infrastructure Intelligence Platform: a multi-modal orchestration API with a predictable, OpenAI-style developer experience. It covers brand intelligence, visual ads, voice agents, health decision support, neuro/BCI decoding, video surveillance, and robotics — all sharing the same auth, job lifecycle, and envelope patterns.

Base URL

All routes are versioned under /api/v1/:

https://api.example.com/api/v1/

Replace https://api.example.com with your deployed host.

Authentication

Send a Bearer token on every request:

Authorization: Bearer <your_api_key>

Keys are issued and verified via Unkey, which handles rate limits and metering. Never embed API keys in client-side code or public repositories.

See Authentication for key formats, error codes, and idempotency details.

Response envelope

Every Pi response wraps its payload in a consistent envelope:

Field	Type	Description
id	string	Unique request or resource id (e.g. pi_req_…)
object	string	Resource type (e.g. job, image.generation)
status	string	Current state of the resource
created_at	number	Unix timestamp in seconds
data	object	Primary payload
error	object	Structured error with code and message; absent on success

Rate-limit headers

Pi includes Stripe-style operational headers on every authenticated response:

Header	Description
X-Request-Id	Unique trace id (req_pi_<uuid>). Include this when contacting support.
X-RateLimit-Limit	Maximum requests allowed in the current window
X-RateLimit-Remaining	Requests remaining in the current window
X-RateLimit-Reset	Unix timestamp (seconds) when the current window resets

Expansion convention

Use the expand= query parameter to include a related object inline on supported endpoints. Expansions are additive — the base resource fields remain unchanged — and never bypass tenant isolation.

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. Use expansion to reduce follow-up requests; skip it for lightweight polling where payload size matters.

Error envelope

Errors follow a Stripe-style format:

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

See Response format for a full table of error codes and HTTP status codes.

Idempotency

Add an Idempotency-Key header to POST requests to avoid duplicate side effects and duplicate billing:

Idempotency-Key: <unique-client-generated-key>

If you retry with the same key, Pi may replay the original response. Reusing the same key with a different request body returns 409 idempotency_key_mismatch. Support varies by endpoint — consult individual endpoint docs.

Async jobs

Heavy operations return 202 Accepted with a job_id. Jobs progress through:

queued → processing → completed | failed

Poll GET /api/v1/jobs/:id (or use wait_for_completion=true for long-polling) until the job reaches a terminal state. See Async jobs for the full lifecycle and error-handling patterns.

Next steps

Quick Start

Copy-paste curl, TypeScript, and Python examples for the full extract → poll → project flow.