POST /api/jobs

Push a one-off HTTP job to a named queue. The queue is created automatically if it doesn’t exist.

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 doesn’t exist
url	string	Yes	The URL to send the HTTP request to
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
delay	integer	No	Seconds to wait before running the job (0–86400). Defaults to 0

Response

201 Created

{
  "success": true,
  "queue_id": 12,
  "job_id": 847,
  "scheduled_at": "2026-02-27T14: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."]
  }
}

Examples

Basic job

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",
    "payload": { "to": "[email protected]" }
  }'

Delayed job

Run the job 30 minutes from now:

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 }
  }'