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.
Integration for MESSAGE type activities will be available soon in a separate section.
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
All integration API requests require an API key:
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. 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 |