Getting Started

Learn the basics of the Reten API — base URL, common headers, pagination, and error handling.

What is the Reten API?

The Reten API is a REST API for the Reten multi-tenant SaaS platform. It allows you to manage field activities assigned to commerces (businesses and stores), track results, and configure dispatch providers.

Key capabilities:

Activity Management — Create, dispatch, and track tasks for commerces
Result Tracking — Submit and query task execution outcomes
Commerce & Operator Management — CRUD operations on commerces, operators, and routes
Multi-Tenant Isolation — Each tenant operates in a fully isolated environment

Base URL

The Reten API is available in multiple environments. Use the appropriate base URL depending on your stage of integration:

Environment	Base URL
Production	`https://api.reten.ai/api`
Staging	`https://api-staging.reten.ai/api`
Development	`https://api-development.reten.ai/api`
Local	`http://localhost:3000/api`

All code examples in this documentation use the production URL. Replace https://api.reten.ai/api with the corresponding environment URL when working in staging or development.

Common Headers

Header	Required	Description
`Authorization`	Yes (JWT auth)	`Bearer <access_token>`
`x-api-key`	Yes (API key auth)	`rtn_sk_<key>` — alternative to Bearer token
`x-tenant-id`	Yes (JWT auth, tenant-scoped routes)	UUID of the active tenant. Not needed with API key auth
`x-project-id`	Yes (project-scoped routes); optional (project-optional routes)	UUID of the active project. Not needed with a project API key — see Authentication → Project Context
`Content-Type`	Yes (for request bodies)	`application/json`

Pagination

List endpoints support pagination via query parameters:

Parameter	Type	Default	Description
`page`	number	1	Page number (1-indexed)
`per_page`	number	25	Items per page (max `100`)

Response includes pagination metadata:

{
  "data": [],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 150,
    "total_pages": 6,
    "has_next": true,
    "has_previous": false
  }
}

Error Responses

Errors follow a consistent format:

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

Field	Type	Description
`statusCode`	number	HTTP status code
`message`	string \| string[]	Description of the problem
`error`	string	HTTP error name
`code`	string	Present only on errors a client has to branch on. It is a stable `UPPER_SNAKE` value: branch on `code`, never on the text of `message`, which may change. Today the only one is `DEFAULT_ROOT_CONFIRMATION_REQUIRED` (see Publish Config)

Common Status Codes

Code	Description
`200`	Success
`201`	Created
`204`	No Content (deactivate, delete operations)
`400`	Bad Request (validation errors)
`401`	Unauthorized (missing or invalid token)
`403`	Forbidden (insufficient permissions or wrong tenant)
`404`	Not Found
`409`	Conflict (duplicate idempotency key, unique constraint violation)

Next Steps

Authentication — Learn how to authenticate with API keys or JWT
Roles & Permissions — Understand role hierarchy and permission gating
Task Integration — Start integrating with the task activities module