Agent-readable docs index: /docs/llms.txt. Full docs in one file: /docs/llms-full.txt. Download /docs/docs.zip to grep all markdown files locally.

Deployments and workflows

Use the deployments API when you already have a workflow bundle, and use the workflows API to inspect deployed or AI-generated workflows.
All routes on this page require x-api-key.

Deployments

POST /v1/deployments/create

Upload a base64-encoded gzip tarball and create a hosted deployment.
Request fields:
  • description: optional deployment description
  • source: base64-encoded gzip tarball
  • entry_point: optional entry file, default index.ts
  • auto_repair: optional boolean, default false. When true, failed jobs for this deployment route to the autofix agent instead of the readonly debug agent.
Response fields:
  • deployment_id
  • status: always building
  • created_at

POST /v1/deployments/list

List deployments for the current tenant.
Send an empty request body:
{ "json": {} }
Response fields for each deployment:
  • id
  • description
  • status
  • source_path
  • bundle_path
  • build_error
  • entry_point
  • built_at
  • created_at
  • workflows

POST /v1/deployments/sync

Poll a deployment until the build finishes and workflow discovery lands.
Request fields:
  • id: deployment id
Response fields:
  • id
  • description
  • status
  • source_path
  • bundle_path
  • build_error
  • entry_point
  • built_at
  • created_at
  • workflows

Workflows

POST /v1/workflows/list

List deployed workflows and in-progress workflow builds.
Response fields:
  • deployed_workflows
  • in_progress_builds
Each deployed_workflows entry includes:
  • name
  • deployment_id
  • deployment_status
  • created_at
  • updated_at
Each in_progress_builds entry includes:
  • build_id
  • status
  • workflow_name
  • summary
  • error
  • created_at
  • updated_at

POST /v1/workflows/get

Return the deployment backing a single workflow name, plus the JSON Schemas derived from the workflow's Zod input/output schemas.
Request fields:
  • workflow: workflow name
Response fields:
  • workflow
  • deployment_id
  • deployment_status
  • deployment_created_at
  • deployment_built_at
  • created_at
  • updated_at
  • input_schema: JSON Schema (Draft 2020-12) serialized from the workflow's Zod input schema at build time. null for legacy deployments built before Zod-schema workflows were supported.
  • output_schema: JSON Schema serialized from the workflow's Zod output schema. null for legacy deployments.
Example response for a Zod-schema workflow:
{
  "json": {
    "workflow": "getExampleTitleAndUrl",
    "deployment_id": "062874fc-4714-4bd5-932f-0ae61ed8d0f6",
    "deployment_status": "ready",
    "deployment_created_at": "2026-05-17T01:15:26.670Z",
    "deployment_built_at": "2026-05-17T01:17:08.730Z",
    "created_at": "2026-05-17T01:15:28.167Z",
    "updated_at": "2026-05-17T01:17:31.314Z",
    "input_schema": {
      "type": "object",
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "properties": {
        "url": { "type": "string", "format": "uri" }
      },
      "additionalProperties": false
    },
    "output_schema": {
      "type": "object",
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "required": ["title", "currentUrl"],
      "properties": {
        "title": { "type": "string" },
        "currentUrl": { "type": "string", "format": "uri" }
      },
      "additionalProperties": false
    }
  }
}

POST /v1/workflows/delete

Delete a workflow by name.
Request fields:
  • workflow: workflow name
Response fields:
  • success
  • message

AI workflow build routes

POST /v1/workflows/build

Create an AI-driven workflow build from a natural-language description.
Request fields:
  • descriptions: one or more natural-language descriptions
  • initial_url: URL where the build should start
  • params: optional workflow params schema example
  • network_log: optional captured network log
  • action_log: optional captured action log
  • entry_point: optional entry file, default index.ts
Response fields:
  • build_id
  • status: pending or agent_running

POST /v1/workflows/buildStatus

Poll an AI workflow build.
Request fields:
  • build_id
Response fields:
  • build_id
  • status
  • deployment_id
  • workflow_name
  • summary
  • error
  • details
  • attempted_steps
  • created_at
  • updated_at

Example deploy poll

curl -X POST "https://api.libretto.sh/v1/deployments/sync" \
  -H "x-api-key: $LIBRETTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "json": {
      "id": "<deployment-id>"
    }
  }'
Jobs and Logs
Invoke workflows and inspect job state.
Sessions
Create browser sessions directly.
Libretto Cloud API overview
See the shared request format.
Powered byHolocron