job_create
Will work outlive the user request, need retries, or need a status later? job_create queues a durable background job. The platform POSTs the payload to your handler URL and retries on failure (at-least-once, up to 5 attempts with exponential backoff). Handlers are expected to be idempotent.
It suits work that should not block a user request: image processing, report generation, outbound email batches, webhook deliveries. run_at with an ISO-8601 time and explicit time zone schedules a future start. The job reports scheduled while waiting and reserves a slot in the account's job limit; cancel it to free that slot. It starts at or after that time.
Example:
{
"project_id": "my-saas",
"handler": "https://my-saas.somewhere.site/api/jobs/process-upload",
"payload": { "upload_id": "u123", "user_id": "u_alice" },
"timeout_seconds": 600
}
// Returns: { "job_id": "j_abc", "status": "queued" }Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"project_id": "<project_id>",
"handler": "<handler>"
},
"name": "job_create"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| run_at | No | Optional earliest start in ISO-8601 with an explicit time zone, for example 2026-10-05T09:00:00Z. Must be future-dated for a new job. Omitted: starts now. | |
| handler | Yes | Full https:// URL. The platform POSTs the payload here. Usually one of your own /api/... function routes. | |
| payload | No | JSON string or object — becomes the POST body your handler receives. | |
| project_id | Yes | Project ID (UUID), subdomain, or slug — resolved server-side, no UUID lookup needed. 'default' also works when the account has exactly one project; multi-project accounts must name one (the error lists them). | |
| webhook_url | No | Optional https:// URL — platform POSTs {job_id, status, result} here when the job reaches a terminal state. | |
| idempotency_key | No | Stable key for one logical creation. The same key with identical arguments is safe after a lost response; independent work takes a new key. | |
| timeout_seconds | No | How long the platform waits for the handler, in seconds. Default 300, max 1800; a deadline of 271-300 s, or any deadline in a preview run, is waited for at most 270 s. When it passes the job fails with JOB_TIMEOUT and is not sent again; the handler may still have been running. |