API Reference

On this page

Authentication

Dispatched uses API keys for authentication. Include your API key as a Bearer token in the Authorization header of each request.

Example:

Authorization: Bearer YOUR-API-KEY

You can have multiple API keys for different environments or projects. To create a new API key, visit the Dashboard > API Keys section in your account.

Queue a Job

To queue a job, send a POST request to the /api/jobs/dispatch endpoint. The request body must be in JSON format and include the payload field, along with an optional scheduleFor field.

Example request:

{
  "payload": { "key": "value" },
  "scheduleFor": "2024-12-17T12:00:00Z",
  "maxRetries": 3
}
  • payload: A required field containing job-specific JSON data. Must be a JSON object.
  • scheduleFor: An optional ISO UTC timestamp to schedule the job for a specific time.
  • maxRetries: An optional integer value to specify the number of retries if the job fails. The value will be capped at the Team's limits based on the subscription plan. If not specified, the default value will be the max value of the Team's limits.

NOTES:

  • The maximum size of the payload is 10KB.

The response will include a unique jobId and the status of the job:

{
  "jobId": "job_1234567890abcdef",
  "status": "QUEUED"
}
  • jobId: A unique identifier for the job.
  • status: Indicates that the job is queued.

Get Job Status

To check the status of a job, send a GET request to the /api/jobs/:jobId endpoint, where :jobId is the unique identifier of the job.

Example request:

GET /api/jobs/job_1234567890abcdef

The response will include the current status of the job:

{
  "jobId": "job_1234567890abcdef",
  "scheduledFor": "2024-12-17T12:00:00Z",
  "status": "QUEUED"
}
  • jobId: The unique identifier of the job.
  • scheduledFor: The scheduled time for the job (if applicable).
  • status: The current status of the job.

The possible job statuses are:

  • QUEUED: The job is waiting to be processed.
  • DISPATCHED: The job has been dispatched to the workers of Dispatched, but has not yet been processed.
  • STARTED: The job has been sent to the webhook URL and processing has begun.
  • COMPLETED: The job has been successfully processed.
  • FAILED: The job has failed after all retries.
  • CANCELLED: The job has been manually canceled.

Webhook Callbacks

Once a job is processed, Dispatched will send a POST request to the webhook URL you configured. The request body will include:

{
  "jobId": "1234567890abcdef",
  "attempt": "transaction_id",
  "attemptNumber": 1,
  "payload": { "key": "value" }
}
  • jobId: The unique ID of the job being processed.
  • attempt: A unique transaction identifier for the current attempt.
  • attemptNumber: The number of the current attempt (1-4). 1 indicates the first attempt. 2-4 indicate retries.
  • payload: The original payload sent when the job was dispatched.

Your webhook endpoint must verify the request using the Webhook Secret and respond with a 200 or 201 status code. If it fails to do so, Dispatched will retry the request up to 3 times using an exponential backoff strategy.

Cancel a Job

Only jobs in the QUEUED status can be canceled. To cancel a job, send a DELETE request to the /api/jobs/:jobId endpoint.

Example request:

DELETE /api/jobs/job_1234567890abcdef

The response will indicate whether the job was successfully canceled:

{
  "jobId": "job_1234567890abcdef",
  "status": "CANCELLED"
}

NOTES:

  • Jobs that are already being processed cannot be canceled.
  • Once a job is canceled, it cannot be restarted.
  • Cancelled jobs will not be retried.
  • Cancelled jobs will still count towards your usage limits.
  • Cancelled jobs can be viewed in the Dashboard.

Error Handling

If there is an issue with your request, Dispatched will respond with an appropriate HTTP status code and error message.

Example error response for an invalid API key:

{
    "error": "UNAUTHORIZED",
    "data": {
        "message": "Unauthorized"
    }
}

Common error scenarios include:

  • Invalid API keys
  • Missing or invalid payload
  • Exceeding rate limits

Rate Limits

API requests are subject to rate limits based on your subscription plan. If you exceed the rate limit, Dispatched will return a 429 Too Many Requests status code.

To monitor your current usage and rate limits, visit the Dashboard.