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 and messages 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
`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)
`limit`	number	20	Items per page

Response includes pagination metadata:

{
  "data": [],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

Error Responses

Errors follow a consistent format:

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

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