Skip to main content
POST
/
api
/
messaging
/
jobs
Create Job
curl --request POST \
  --url https://api.example.com/api/messaging/jobs \
  --header 'Content-Type: application/json' \
  --data '
{
  "userId": "<string>",
  "content": "<string>",
  "agentId": "<string>",
  "timeoutMs": 123,
  "metadata": {}
}
'
{
  "jobId": "550e8400-e29b-41d4-a716-446655440001",
  "status": "processing",
  "createdAt": 1703001234567,
  "expiresAt": 1703001354567
}
Create a one-off messaging job. Jobs are used for fire-and-forget message processing where the agent processes a prompt and returns a response.
This endpoint requires API key authentication via the X-API-Key header.

​
Request Body

​
userId
string
required
UUID of the user sending the message
​
content
string
required
The message content/prompt to process (max 50KB)
​
agentId
string
UUID of the agent to process the message. If not provided, uses the first available agent.
​
timeoutMs
number
default:"120000"
Job timeout in milliseconds (min: 1000, max: 300000)
​
metadata
object
Additional metadata to attach to the job (max 10KB)

​
Response

​
jobId
string
Unique job identifier for tracking
​
status
string
Initial job status: pending or processing
​
createdAt
number
Unix timestamp of job creation
​
expiresAt
number
Unix timestamp when the job will timeout
{
  "jobId": "550e8400-e29b-41d4-a716-446655440001",
  "status": "processing",
  "createdAt": 1703001234567,
  "expiresAt": 1703001354567
}

​
Example Request

curl -X POST https://api.example.com/api/messaging/jobs \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "content": "Process this asynchronously",
    "agentId": "660e8400-e29b-41d4-a716-446655440001",
    "timeoutMs": 60000,
    "metadata": {
      "source": "api",
      "priority": "high"
    }
  }'

​
Job Status Values

StatusDescription
pendingJob created, waiting for processing
processingAgent is processing the message
completedJob finished successfully
failedJob failed with an error
timeoutJob timed out waiting for response