Task Integration API
Connect your system with Reten to query task-type activities, submit results, and receive activities.
The Reten task integration API allows tenant developers to query assigned task-type activities, submit results, and receive activities in real time. This section covers exclusively the integration for TASK type activities. There are two integration modes depending on the data flow direction.
This documentation is intended for tenant developers who integrate their systems with Reten using a provider available on the platform (e.g., YOM). If you need to onboard a new provider to the platform, contact the Reten team.
Integration modes
| Mode | Direction | Description | Use case |
|---|---|---|---|
| Pull | Your system → Reten | Your system queries activities and submits results via the REST API | Asynchronous integration, batch processing, systems that prefer to control the polling rate |
| Push (Dispatch) | Reten → Provider | Reten sends activities to the provider's endpoint in real time | Real-time integration, systems that need to receive activities immediately upon creation |
Quick authentication
Integrations authenticate with an API key, sent in the x-api-key header:
x-api-key: YOUR_API_KEYThe API key authenticates your integration, defines the available permissions, and automatically resolves the associated tenant. There is no need to send the x-tenant-id header. Listing tasks and submitting results are project-optional: a project key always works in its own project, while a tenant key covers every project of the tenant and sends x-project-id only to narrow a request to one project or to submit a result without activity_id — see Key scope.
The integration endpoints also accept a user token (JWT), but the API key is the method intended for integrations. See Authentication for details.
Environments
Reten Environments
| Environment | Admin Panel | API Base URL |
|---|---|---|
| Development | app-development.reten.ai | https://api-development.reten.ai |
| Staging | app-staging.reten.ai | https://api-staging.reten.ai |
| Production | app.reten.ai | https://api.reten.ai |
Use the admin panel URL to manage API keys and dispatch configurations. Replace BASE_URL in code examples with the API base URL for your environment.
Getting started
Quickstart: Pull Integration
Set up your first integration in 4 steps with ready-to-run examples.
Receiving Activities (Dispatch)
Learn how Reten dispatches activities to the configured provider endpoint.
Authentication
Details on required headers, permissions, and API keys.
Error Handling
Error format, status codes, and solutions.
Available endpoints
| Method | Path | Description |
|---|---|---|
GET | /api/integration/activities/tasks | List task-type activities visible to your API key |
POST | /api/integration/activity-results/tasks | Submit the result of a task-type activity |
GET | /api/integration/task-result-type-configs | List available result type configurations |
POST | /api/integration/commerces/batch-upsert | Create or update up to 500 commerces in one request — see Batch Upsert |
POST | /api/integration/operators/batch-upsert | Create or update up to 500 operators in one request — see Batch Upsert |
POST | /api/integration/routes/batch-upsert | Create or update up to 500 routes in one request — see Batch Upsert |