API Overview

Base URL: https://app.trygradient.ai All API endpoints are served from the same domain as the admin portal. Requests must include valid authentication.

Authentication

Gradient supports two authentication methods:

API Key (recommended)
Session Cookie

Include your API key in the Authorization header:

Authorization: Bearer gai_abc123...

API keys are scoped to your organization. Create and manage them via the API Keys endpoints or the Settings page in the admin portal.A key is shown one time and stored only as a hash. See Managing API keys for how keys are stored, scoped, limited, and revoked.

Pagination

List endpoints accept optional pagination parameters:

integer

default:"20"

Results per page (1-100)

integer

default:"0"

Number of results to skip

Paginated responses include metadata:

{
  "data": [...],
  "total": 42,
  "limit": 20,
  "offset": 0
}

Error Responses

All errors follow a consistent format:

{
  "error": {
    "code": "not_found",
    "message": "Assessment not found"
  }
}

code is stable. Branch on it. message is written for people, carries live values, and can change at any time, so do not match on its text.

HTTP Status	Error Code	Meaning
`400`	`validation`	Invalid request body or missing required fields
`401`	`unauthorized`	Missing or invalid authentication
`403`	`forbidden`	Authenticated but lacking permission
`404`	`not_found`	Resource doesn’t exist or doesn’t belong to your org
`409`	`conflict`	Action conflicts with current resource state
`410`	`gone`	Resource existed but has expired
`429`	`rate_limited`	Too many requests on this API key. See Rate limits
`500`	`internal`	Unexpected server error
`502`	`upstream_error`	A service we depend on failed. Safe to retry
`503`	`unavailable`	Temporarily offline for maintenance. Honour `Retry-After`

A few responses add fields beside error, never inside it. For example a missing deliverable returns expected: true so a viewer can show an empty state instead of an error. Some endpoints return a more specific code than the table gives, when one status covers several different failures. The calibration endpoints are the main case: wrong_channel, no_anchors, no_grades, no_disagreement and llm_error are all 400. Treat an unknown code as its status class.

The ATS partner endpoints under /api/ats/ do not use this format. Greenhouse and Ashby set the request and response shapes for those endpoints, so they follow each vendor’s partner specification. See ATS Integrations.

​API Overview

​Authentication

​Pagination

​Error Responses

API Overview

Authentication

Pagination

Error Responses