Create Job

POST /api/messaging/jobs

Create Job

cURL

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": {}
}
'

import requests

url = "https://api.example.com/api/messaging/jobs"

payload = {
    "userId": "<string>",
    "content": "<string>",
    "agentId": "<string>",
    "timeoutMs": 123,
    "metadata": {}
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    userId: '<string>',
    content: '<string>',
    agentId: '<string>',
    timeoutMs: 123,
    metadata: {}
  })
};

fetch('https://api.example.com/api/messaging/jobs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/messaging/jobs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'userId' => '<string>',
    'content' => '<string>',
    'agentId' => '<string>',
    'timeoutMs' => 123,
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/messaging/jobs"

	payload := strings.NewReader("{\n  \"userId\": \"<string>\",\n  \"content\": \"<string>\",\n  \"agentId\": \"<string>\",\n  \"timeoutMs\": 123,\n  \"metadata\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/api/messaging/jobs")
  .header("Content-Type", "application/json")
  .body("{\n  \"userId\": \"<string>\",\n  \"content\": \"<string>\",\n  \"agentId\": \"<string>\",\n  \"timeoutMs\": 123,\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/messaging/jobs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"userId\": \"<string>\",\n  \"content\": \"<string>\",\n  \"agentId\": \"<string>\",\n  \"timeoutMs\": 123,\n  \"metadata\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "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

Status	Description
pending	Job created, waiting for processing
processing	Agent is processing the message
completed	Job finished successfully
failed	Job failed with an error
timeout	Job timed out waiting for response