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.

Pagination

List endpoints accept optional pagination parameters:

limit

integer

default:"20"

Results per page (1-100)

offset

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"
  }
}

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
`500`	`internal`	Unexpected server error

Documentation Index

​API Overview

​Authentication

​Pagination

​Error Responses

API Overview

Authentication

Pagination

Error Responses