Skip to content
Prism API

Quickstart

The API lives at https://prism-apis.vercel.app. GraphQL is served at /graphql and REST under /v1. Examples run against your own workspace or the public sample workspace. Choose Try sandbox above, or sign in, create a project, and create a key in the dashboard.

List your projects first. For individual and nested examples, replace YOUR_PROJECT_ID, YOUR_USER_ID, or YOUR_DEPLOYMENT_ID in the editable request path with an ID from your workspace. Sandbox mode fills these IDs automatically.

GET/v1/projects?first=3&include=owner
curl "https://prism-apis.vercel.app/v1/projects?first=3&include=owner" \  -H "Authorization: Bearer <API_KEY>"
No key yet? or paste one above.

Authentication

Send your key in the Authorization header as a bearer token, or in X-API-Key. Keys are checked by the application gateway before resource queries run, and only a SHA-256 hash of each key is stored, so a key is shown once when you create it. Requests without a valid key get a 401.

GET/v1/projects
curl "https://prism-apis.vercel.app/v1/projects"
Runs without a key

Rate limits

Each key has a token bucket. A request takes one token and tokens refill continuously, so short bursts are fine and sustained traffic is smoothed. When the bucket is empty you get a 429 with a Retry-After header in seconds.

HeaderMeaning
X-RateLimit-LimitBucket size for your plan
X-RateLimit-RemainingTokens left after this request
X-RateLimit-ResetSeconds until the bucket is full
Retry-AfterSeconds to wait, only on 429

Sandbox keys hold 10 tokens and refill 1 per second. Standard keys hold 100 and refill 10 per second. A burst uses the selected key’s limit:

GET/v1/users/YOUR_USER_ID
curl "https://prism-apis.vercel.app/v1/users/YOUR_USER_ID" \  -H "Authorization: Bearer <API_KEY>"
No key yet? or paste one above.

Pagination

Lists use cursors. Pass first (1–100, default 20) and, for later pages, after set to the previous pageInfo.endCursor. Cursors are opaque and stay valid when new rows arrive. Run this, then use Next page.

GET/v1/projects/YOUR_PROJECT_ID/deployments?first=3
curl "https://prism-apis.vercel.app/v1/projects/YOUR_PROJECT_ID/deployments?first=3" \  -H "Authorization: Bearer <API_KEY>"
No key yet? or paste one above.

GraphQL

POST { query, variables } to /graphql. Nested fields are batched with DataLoader per request, so asking for 20 projects and their owners costs two database round trips, not 21. The X-Prism-DB-Queries header shows the count. Queries deeper than 8 levels are rejected. The full schema is at /api/schema.

POST/graphql
curl -X POST "https://prism-apis.vercel.app/graphql" \  -H "Authorization: Bearer <API_KEY>" \  -H "Content-Type: application/json" \  -d '{"query":"query { projects(first: 5) { edges { node { name owner { name } } } pageInfo { hasNextPage endCursor } } }"}'
No key yet? or paste one above.

REST reference

These routes are generated from the GraphQL schema when the server starts. Each one compiles to a GraphQL query and runs through the same resolvers. Related objects come back as { id }; expand them with include.

GET /v1/deployments/:id

Fetch a deployment by id. Returns a Deployment.

  • include String. Expand: project
GET/v1/deployments/YOUR_DEPLOYMENT_ID?include=project
curl "https://prism-apis.vercel.app/v1/deployments/YOUR_DEPLOYMENT_ID?include=project" \  -H "Authorization: Bearer <API_KEY>"
No key yet? or paste one above.

GET /v1/projects

List projects, newest first. Returns a page of Project.

  • first Int. Page size, 1–100. Default 20.
  • after String. Cursor from pageInfo.endCursor.
  • include String. Expand: owner
GET/v1/projects?first=3
curl "https://prism-apis.vercel.app/v1/projects?first=3" \  -H "Authorization: Bearer <API_KEY>"
No key yet? or paste one above.

GET /v1/projects/:id

Fetch a project by id. Returns a Project.

  • include String. Expand: owner
GET/v1/projects/YOUR_PROJECT_ID?include=owner
curl "https://prism-apis.vercel.app/v1/projects/YOUR_PROJECT_ID?include=owner" \  -H "Authorization: Bearer <API_KEY>"
No key yet? or paste one above.

GET /v1/projects/:id/deployments

Deployments for this project, newest first. Returns a page of Deployment.

  • first Int. Page size, 1–100. Default 20.
  • after String. Cursor from pageInfo.endCursor.
  • include String. Expand: project
GET/v1/projects/YOUR_PROJECT_ID/deployments?first=3
curl "https://prism-apis.vercel.app/v1/projects/YOUR_PROJECT_ID/deployments?first=3" \  -H "Authorization: Bearer <API_KEY>"
No key yet? or paste one above.

GET /v1/users/:id

Fetch a user by id. Returns a User.

GET/v1/users/YOUR_USER_ID
curl "https://prism-apis.vercel.app/v1/users/YOUR_USER_ID" \  -H "Authorization: Bearer <API_KEY>"
No key yet? or paste one above.

TypeScript SDK

The SDK is generated from the same schema and routes. Download prism.ts into your project. It has no dependencies, types every resource, and retries 429s using Retry-After.

Usage
import { Prism, PrismError } from "./prism"; const prism = new Prism({ key: process.env.PRISM_KEY! }); const project = await prism.projects.get("YOUR_PROJECT_ID", { include: ["owner"] });const page = await prism.projects.deployments(project.id, { first: 10 }); try {  await prism.users.get("usr_missing");} catch (e) {  if (e instanceof PrismError) console.log(e.status, e.code);}

Errors

REST and gateway errors share one shape. GraphQL errors follow the GraphQL spec, with a code in extensions.code.

{  "error": {    "code": "rate_limited",    "message": "Rate limit exceeded for this key. Retry in 1s.",    "docs": "/docs#errors"  }}
400invalid_parameter, invalid_bodyFix the request and retry
401missing_key, invalid_key, revoked_keyCheck the key you are sending
404not_found, unknown_routeThe id or route does not exist
405method_not_allowedREST is read-only; use GET
429rate_limitedWait Retry-After seconds
500internalRetry; include x-request-id if you contact us

Breaking changes

Every operation the API receives is recorded by its normalized document. In CI, npm run schema:check compares the schema with a trusted base revision. When a live operation source is configured, it validates operations seen in the last 30 days against the new schema. Without traffic history, all structural breaking changes block. If a change would break any of them, the build fails. Unused fields can be removed; used ones can’t, until clients stop sending them.