Skip to main content
Use the jobs API to run workflows and inspect results, and use the logs API to fetch executor logs for recent jobs.
All routes on this page require x-api-key.

​
Jobs

​
POST /v1/jobs/create

Start a workflow job. Request fields:
  • workflow: deployed workflow name
  • params: workflow input object
  • nonce: optional idempotency-style nonce
  • timeout_seconds: optional timeout, default 1800, max 3600
  • callback_url: optional callback URL
  • callback_secret: optional callback secret
  • skip_callbacks: optional boolean
  • residential_proxy: optional residential proxy location object
If you set callback_url, you must also set callback_secret. Use residential_proxy for location-sensitive runs that need traffic to originate from a specific residential proxy country, US state, city, ZIP code, or ASN. See Residential proxy locations for the supported fields and combination rules. Callback delivery order:
  1. If the job has callback_url and callback_secret, Libretto Cloud delivers only to that per-job callback.
  2. Otherwise, Libretto Cloud delivers to every active stored webhook endpoint for the tenant.
  3. If skip_callbacks is true, Libretto Cloud does not deliver callbacks or stored webhooks.
Use callback_url for one-off or environment-specific result delivery. Use stored webhook endpoints for long-lived production destinations. See Webhooks for payload fields and signature headers. Response fields:
  • success
  • job_id
  • status: always running
  • message

​
POST /v1/jobs/list

List jobs for the current tenant. Request fields:
  • status: optional status filter
  • limit: optional page size, default 20, max 100
  • cursor: optional pagination cursor from next_cursor
Response fields:
  • jobs
  • next_cursor
Each job summary includes:
  • job_id
  • deployment_id
  • workflow_id
  • workflow
  • status
  • created_at
  • completed_at

​
POST /v1/jobs/get

Return a single job and its result data. Request fields:
  • id: job id
Response fields:
  • job_id
  • deployment_id
  • deployment_version
  • workflow_id
  • workflow
  • params
  • status
  • created_at
  • started_at
  • completed_at
  • result
  • error
  • mapped_stack
Use Recordings when you need the job’s recording URL.

​
POST /v1/jobs/debugReport

Return the hosted debug or autofix report for a failed job. Request fields:
  • id: job id
Response fields:
  • job_id
  • debug_agent_status
  • debug_agent_mode
  • error
  • tldr
  • handoff_prompt
  • screenshot_url
  • dom_snapshot_url
  • autofix_summary
  • autofix_deployment_id
  • email_sent_at
  • job_error
  • job_mapped_stack
  • job_params
  • job_workflow

​
POST /v1/jobs/cancel

Cancel a queued or running job. Request fields:
  • id: job id
Response fields:
  • success
  • message

​
Logs

​
POST /v1/logs/list

Fetch recent executor logs for one job or for recent jobs in the tenant. Request fields:
  • jobId: optional job id
  • workflow: optional workflow-name filter
  • level: optional info, warn, or error
  • pageToken: optional next-page token
  • limit: optional page size, default 100, max 1000
Response fields:
  • logs
  • nextPageToken
Each log entry includes:
  • jobId
  • workflow
  • level
  • message
  • timestamp

​
Example job run

curl -X POST "https://api.libretto.sh/v1/jobs/create" \
  -H "x-api-key: $LIBRETTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "json": {
      "workflow": "check-eligibility",
      "params": {
        "memberId": "12345"
      },
      "timeout_seconds": 300,
      "callback_url": "https://example.com/libretto/job-callback",
      "callback_secret": "replace-with-your-secret"
    }
  }'

Credentials

Store credentials used by Libretto Cloud workflows.

Deployments and Workflows

Deploy workflows and inspect build state.

Webhooks

Configure tenant-level job result webhooks.

Libretto Cloud API overview

See the shared request format.