POST /api/jobs

Push a one-off HTTP job to a named queue. The queue is created automatically if it does not exist.

Webhook Signing

If you have a signing secret configured, Recuro adds X-Recuro-Signature and X-Recuro-Timestamp headers to every outbound request so your endpoints can verify authenticity. See Webhook Signing for details.

Endpoint

POST /api/jobs

Authentication

Pass your API token as a Bearer token. Generate one from Settings > API.

Authorization: Bearer YOUR_API_TOKEN

Request body

{
  "queue": "emails",
  "url": "https://api.yourapp.com/send",
  "method": "POST",
  "headers": {
    "X-Custom-Header": "value"
  },
  "payload": {
    "to": "[email protected]",
    "subject": "Welcome!"
  },
  "delay": 300
}

Parameters

Field	Type	Required	Description
queue	string	Yes	Queue name. Created automatically if it does not exist. Max 255 characters.
url	string	Yes	The URL to send the HTTP request to. Must be a valid URL. Max 2,048 characters.
method	string	No	HTTP method: GET, POST, PUT, PATCH, DELETE. Defaults to POST.
headers	object	No	Key-value pairs sent as request headers.
payload	object	No	JSON body sent with the request.
callback_url	string	No	URL to receive a POST when the job completes. Must be a valid URL. Max 2,048 characters.
delay	integer	No	Seconds to wait before running the job (0-86,400). Defaults to 0.

Queue-level settings

Queues can have timeout_seconds, retry_delays, success_assertions, and other settings configured via the dashboard. These apply to every job in the queue. See Queues for details.

Response

201 Created

{
  "success": true,
  "queue_id": 12,
  "job_id": 847,
  "scheduled_at": "2026-04-10T14:10:00+00:00",
  "message": "Scheduled successfully"
}

Field	Type	Description
success	boolean	Always true on success
queue_id	integer	ID of the queue the job was added to
job_id	integer	ID of the created job
scheduled_at	string	ISO 8601 timestamp of when the job will run
message	string	Human-readable confirmation

Error responses

401 Unauthorized — missing or invalid token

{ "error": "Missing authorization token" }

422 Unprocessable Entity — validation error

{
  "message": "The queue field is required.",
  "errors": {
    "queue": ["The queue field is required."]
  }
}

Prefer the dashboard?

You can create and manage jobs from the web UI without writing code. See Creating a Job for a full dashboard walkthrough including viewing, filtering, bulk operations, and firing pending jobs.

Code examples

curl

curl -X POST https://app.recurohq.com/api/jobs \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "queue": "emails",
    "url": "https://api.yourapp.com/send",
    "method": "POST",
    "payload": { "to": "[email protected]", "subject": "Welcome!" }
  }'

PHP

$response = Http::withToken('YOUR_API_TOKEN')
    ->post('https://app.recurohq.com/api/jobs', [
        'queue' => 'emails',
        'url' => 'https://api.yourapp.com/send',
        'method' => 'POST',
        'payload' => [
            'to' => '[email protected]',
            'subject' => 'Welcome!',
        ],
    ]);

$job = $response->json();
// $job['job_id'], $job['queue_id'], $job['scheduled_at']

Node.js

const response = await fetch('https://app.recurohq.com/api/jobs', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    queue: 'emails',
    url: 'https://api.yourapp.com/send',
    method: 'POST',
    payload: {
      to: '[email protected]',
      subject: 'Welcome!',
    },
  }),
});

const job = await response.json();
// job.job_id, job.queue_id, job.scheduled_at

Python

import requests

response = requests.post(
    'https://app.recurohq.com/api/jobs',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'},
    json={
        'queue': 'emails',
        'url': 'https://api.yourapp.com/send',
        'method': 'POST',
        'payload': {
            'to': '[email protected]',
            'subject': 'Welcome!',
        },
    },
)

job = response.json()
# job['job_id'], job['queue_id'], job['scheduled_at']

More examples

Delayed job (30 minutes)

curl -X POST https://app.recurohq.com/api/jobs \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "queue": "notifications",
    "url": "https://api.yourapp.com/notify",
    "delay": 1800,
    "payload": { "event": "user_signup" }
  }'

With custom headers

curl -X POST https://app.recurohq.com/api/jobs \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "queue": "webhooks",
    "url": "https://partner.example.com/webhook",
    "method": "POST",
    "headers": { "X-Webhook-Secret": "abc123" },
    "payload": { "event": "order.completed", "order_id": 99 }
  }'

With completion callback

curl -X POST https://app.recurohq.com/api/jobs \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "queue": "webhooks",
    "url": "https://partner.example.com/webhook",
    "method": "POST",
    "payload": { "event": "order.shipped", "order_id": 456 },
    "callback_url": "https://api.yourapp.com/recuro-callback"
  }'

Delayed job with callback (Node.js)

// Schedule a reminder 24 hours from now and get notified when it fires
const response = await fetch('https://app.recurohq.com/api/jobs', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    queue: 'reminders',
    url: 'https://api.yourapp.com/remind',
    method: 'POST',
    payload: { user_id: 42, type: 'trial_expiry' },
    delay: 86400,
    callback_url: 'https://api.yourapp.com/recuro-callback',
  }),
});

Webhook fanout (PHP)

// Distribute an event to multiple partner endpoints
$partners = [
    'https://partner-a.example.com/webhook',
    'https://partner-b.example.com/webhook',
    'https://partner-c.example.com/webhook',
];

foreach ($partners as $url) {
    Http::withToken('YOUR_API_TOKEN')
        ->post('https://app.recurohq.com/api/jobs', [
            'queue' => 'webhook-fanout',
            'url' => $url,
            'method' => 'POST',
            'payload' => [
                'event' => 'order.completed',
                'order_id' => $order->id,
                'timestamp' => now()->toIso8601String(),
            ],
        ]);
}

Batch job creation (Python)

import requests

api_token = 'YOUR_API_TOKEN'
headers = {'Authorization': f'Bearer {api_token}'}

# Schedule cleanup tasks for each expired session
for session_id in expired_session_ids:
    requests.post(
        'https://app.recurohq.com/api/jobs',
        headers=headers,
        json={
            'queue': 'session-cleanup',
            'url': 'https://api.yourapp.com/sessions/cleanup',
            'method': 'POST',
            'payload': {'session_id': session_id},
        },
    )

Next steps

• Create a Cron Job (API) — Schedule recurring HTTP requests
• Jobs — Understand the job lifecycle and retry chain
• Queues — Configure queue-level settings
• Webhook Signing — Verify request authenticity