Skip to main content
POST
/
v1
/
async
/
task
Create async task
curl --request POST \
  --url https://api.cloro.dev/v1/async/task \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "taskType": "CHATGPT",
  "priority": 5,
  "idempotencyKey": "your-custom-identifier-123",
  "webhook": {
    "url": "https://your-app.com/webhook-handler"
  },
  "payload": {
    "prompt": "What is the weather in New York?",
    "country": "US"
  }
}
'
{
  "success": true,
  "task": {
    "id": "b27a21e1-7c39-4aa2-a347-23e828c426f9",
    "taskType": "CHATGPT",
    "status": "QUEUED",
    "priority": 1,
    "createdAt": "2026-04-09T15:00:00.000Z",
    "idempotencyKey": "batch-chatgpt-001"
  },
  "credits": {
    "creditsToCharge": 10,
    "creditsCharged": null
  }
}

​
Overview

Use this endpoint to submit a task for asynchronous processing. You’ll receive a taskId in the response that you can use to: All newly created tasks start with status QUEUED. The scheduler processes tasks by priority first (higher numbers first), then in FIFO order within the same priority level.

​
Priority

You can optionally set a priority from 1 (lowest, default) to 10 (highest). Tasks with higher priority are processed before lower-priority ones. If you don’t specify a priority, it defaults to 1. Monitor your queue’s priority distribution using the async status endpoint.

​
Idempotency

You can optionally include an idempotencyKey to prevent duplicate task creation. If you submit a request with an idempotency key that has already been used, the API returns a 409 Conflict error.

​
Example usage

curl -X POST "https://api.cloro.dev/v1/async/task" \
  -H "Authorization: Bearer sk_live_1234567890abcdef1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "taskType": "CHATGPT",
    "priority": 5,
    "idempotencyKey": "your-custom-identifier-123",
    "webhook": {
      "url": "https://your-app.com/webhook-handler"
    },
    "payload": {
      "prompt": "What is the weather in New York?",
      "country": "US"
    }
  }'

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
taskType
enum<string>
required

The AI provider to use for this task.

Available options:
AIMODE,
GOOGLE,
GOOGLE_NEWS,
GEMINI,
CHATGPT,
COPILOT,
PERPLEXITY,
GROK
Example:

"CHATGPT"

​
payload
object
required

Provider-specific request payload. Must include at least prompt (or query for Google Search).

Example:
{
  "prompt": "What do you know about Acme Corp?",
  "country": "US"
}
​
priority
integer
default:1

Task priority level (1-10). Higher numbers are processed first. Defaults to 1.

Required range: 1 <= x <= 10
Example:

5

​
idempotencyKey
string

Unique string to prevent duplicate task creation. Must be unique across your account.

Example:

"batch-chatgpt-001"

​
webhook
object

Webhook configuration for task completion notification.

Response

Task created successfully. Returns task ID and initial status.

​
success
boolean
required
Example:

true

​
task
object
required

Common task summary fields shared across async task responses.

​
credits
object
required

Credit information for an async task.