Task integration shapes

{
  "name": "Hello task",
  "steps": [
    {
      "type": "code",
      "name": "Prepare result",
      "fields": {
        "code": "return { message: \"Hello\" };",
        "output": "result",
        "format": "json"
      }
    }
  ]
}

{
  "name": "Hello AI",
  "steps": [
    {
      "type": "ai_agent",
      "name": "Say hello",
      "fields": {
        "prompts": [
          {
            "prompt": "Say hello in one short sentence.",
            "output": "greeting",
            "model": "gpt-5.5",
            "response": "string"
          }
        ]
      }
    }
  ]
}

Discover models and Run as users

GET /api/v1/tasks/authoring-options uses your project API key and takes no query parameters.

Filter models client-side by type: 1 for language prompts, 2 for media workflows, 3 for transcription. Use model verbatim. run_as contains eligible project-member emails: your identity, or other eligible members if you are an organization-admin. Values and timezone in this example are illustrative; use your server response.

{
  "models": [
    {
      "model": "gpt-5.5",
      "type": 1
    },
    {
      "model": "whisper-1",
      "type": 3
    }
  ],
  "model_types": {
    "1": "language",
    "2": "media",
    "3": "speech_to_text"
  },
  "run_as": [
    "user@example.com"
  ],
  "api_server_timezone": "Europe/London",
  "schedule_timezone": "Scheduler host local timezone; the scheduler and API hosts must use the same timezone.",
  "notes": [
    "Models are organization-approved and enabled for this project; credentials and provider availability are checked at execution."
  ]
}

For a paginated model list with optional type filtering, use GET /api/v1/models. Example: /api/v1/models?type=1 lists language models available to your project.

AI response types

Create and update schemas

task_schema is the create/update oneOf contract. schedule_schema is authoritative; schedule_types is a readable index of the same variants. Calendar validity and interval stop_time > start_time are checked by POST /api/v1/tasks/validate; schema alone cannot compare these values.

Creates require name and at least one step, with no task id or revision. Updates require id and at least one editable field; omitted fields remain unchanged. An inactive task may be updated with an empty steps list.

Successful responses

Create: 201

{
  "created": true,
  "task": {
    "id": "0123456789abcdef01234567",
    "revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "name": "Hello task",
    "steps": [
      {
        "id": "0123456789abcdef01234568",
        "type": "code",
        "name": "Prepare result",
        "fields": {
          "code": "return { message: \"Hello\" };",
          "output": "result",
          "format": "json"
        },
        "description": ""
      }
    ],
    "active": false,
    "schedule": {
      "type": "manual"
    },
    "run_as": "user@example.com",
    "notification": "errors",
    "notification_emails": [],
    "log_reference": ""
  }
}

Update: 200

{
  "created": false,
  "task": {
    "id": "0123456789abcdef01234567",
    "revision": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
    "name": "Hello task updated",
    "steps": [
      {
        "id": "0123456789abcdef01234568",
        "type": "code",
        "name": "Prepare result",
        "fields": {
          "code": "return { message: \"Hello\" };",
          "output": "result",
          "format": "json"
        },
        "description": ""
      }
    ],
    "active": false,
    "schedule": {
      "type": "manual"
    },
    "run_as": "user@example.com",
    "notification": "errors",
    "notification_emails": [],
    "log_reference": ""
  }
}

Validate: 200

{
  "valid": true,
  "issues": [],
  "warnings": [
    "Validation does not execute steps or verify external services."
  ]
}

Common mistakes

• Use unique step names.
• Keep newly authored parent/branch subtrees contiguous.
• Supplying steps replaces the entire list; omit it for settings-only updates.
• Queued or running tasks cannot be edited.
• Use an exact model from authoring-options; credentials must also be configured.
• Output names do not include {{braces}}.
• Retain IDs on renames, and update child parent names.
• Do not delete unsupported steps to silence validation errors. Return them unchanged with their IDs.

Choosing an AI type

Use ai_agent for new agent tasks. ai_answer defaults to direct answer context. These are not interchangeable aliases despite sharing the same fields.

Editing existing tasks

Returned IDs preserve private settings across renames. Unchanged unsupported steps can be returned with their IDs. Existing branch layouts are preserved for content edits; changing the layout applies the rules below. Include the returned revision to detect stale edits (409). Do not drop unsupported steps to make a request pass validation.

Use this guide to create task steps through POST /api/v1/tasks/createOrUpdateTask. The integration type is supplied in type; every step has a fields object. The examples cover all 11 types currently supported by this API. Other UI integrations are not yet supported.

AI agents can read the same reference as JSON, including field schemas and examples. These pages contain no project data and need no login. Actual task requests require authentication.

Authenticate and save

x-api-key: <project API key>. The key supplies project context; no project header is needed.

Supply id to update an existing task; omit it to create. New tasks require a name and at least one step and default to inactive. Saving does not run a task. run_as is a project member’s email address; omit it to use your own identity on creation. Assigning another user requires organization-admin permission. Replace example emails and model/instruction references with your own values.

On update, omitted fields are preserved. For existing step content, prefer step_updates: [{id, fields: {code: "..."}}] with the task ID and latest revision. Supply only changed fields or description; fields merge by top-level name, while nested objects and arrays replace their entire field. The server validates the merged draft. Step updates cannot rename, add, remove, reorder or change types or branches, and cannot accompany steps. Supplying steps replaces the complete list; supplying schedule replaces the schedule. Unknown fields are rejected. Use GET /api/v1/tasks/{id} to read a task first. Queued or running tasks cannot be edited.

Common step fields

AI steps put their prompt list in fields.prompts. Every prompt contains prompt, output, model and response.

Integration types

{
  "type": "http_request",
  "name": "Fetch orders",
  "description": "",
  "fields": {
    "method": "GET",
    "url": "https://example.com/orders",
    "headers": {
      "Accept": "application/json"
    },
    "output": "orders"
  }
}

{
  "type": "code",
  "name": "Prepare orders",
  "description": "",
  "fields": {
    "code": "return [{ number: \"PO1001\" }];",
    "output": "orders",
    "format": "json"
  }
}

{
  "type": "for_each",
  "name": "Each order",
  "description": "",
  "fields": {
    "list": "orders",
    "item": "order",
    "index": "orderIndex",
    "max_iterations": 1000,
    "continue_on_error": false,
    "output": "orderResults"
  }
}

{
  "type": "if_statement",
  "name": "Has orders",
  "description": "",
  "fields": {
    "code": "return {{orders}}.length > 0;",
    "output": "hasOrders"
  }
}

{
  "type": "log_response",
  "name": "Record result",
  "description": "",
  "fields": {
    "subject": "Order results",
    "body": "{{matchedProducts}}"
  }
}

{
  "type": "send_email",
  "name": "Email result",
  "description": "",
  "fields": {
    "to": "ops@example.com",
    "subject": "Order results",
    "body": "{{matchedProducts}}",
    "include_email_attachments": false
  }
}

{
  "type": "fetch_email",
  "name": "Read orders",
  "description": "",
  "fields": {
    "folder": "Inbox",
    "processed_folder": "Processed",
    "failed_folder": "Failed",
    "keyword": "Order",
    "single_file": false
  }
}

{
  "type": "ai_answer",
  "name": "Match to product codes",
  "description": "",
  "fields": {
    "prompts": [
      {
        "prompt": "Match the order lines to product codes in {{priceList}}. Return JSON.",
        "output": "matchedProducts",
        "model": "gpt-5.5",
        "response": "json"
      }
    ]
  }
}

{
  "type": "ai_agent",
  "name": "Match to product codes",
  "description": "",
  "fields": {
    "prompts": [
      {
        "prompt": "Match the order lines to product codes in {{priceList}}. Return JSON.",
        "output": "matchedProducts",
        "model": "gpt-5.5",
        "response": "json"
      }
    ]
  }
}

{
  "type": "transcribe_audio",
  "name": "Transcribe voicemail",
  "description": "",
  "fields": {
    "transcriptions": [
      {
        "model": "whisper-1",
        "output": "audioTranscription"
      }
    ]
  }
}

{
  "type": "end",
  "name": "Finish",
  "description": "",
  "fields": {}
}

{
  "name": "Process order list",
  "active": false,
  "schedule": {
    "type": "manual"
  },
  "run_as": "user@example.com",
  "notification": "errors",
  "notification_emails": [
    "ops@example.com"
  ],
  "log_reference": "Order processing",
  "steps": [
    {
      "type": "code",
      "name": "Prepare orders",
      "fields": {
        "code": "return [{ number: \"PO1001\" }];",
        "output": "orders",
        "format": "json"
      }
    },
    {
      "type": "if_statement",
      "name": "Has orders",
      "fields": {
        "code": "return {{orders}}.length > 0;",
        "output": "hasOrders"
      }
    },
    {
      "type": "for_each",
      "name": "Each order",
      "parent": "Has orders",
      "branch": "true",
      "fields": {
        "list": "orders",
        "item": "order",
        "index": "orderIndex",
        "max_iterations": 1000,
        "continue_on_error": false,
        "output": "orderResults"
      }
    },
    {
      "type": "log_response",
      "name": "Record order",
      "parent": "Each order",
      "fields": {
        "body": "{{order.number}}"
      }
    },
    {
      "type": "log_response",
      "name": "No orders",
      "parent": "Has orders",
      "branch": "false",
      "fields": {
        "body": "No orders to process."
      }
    }
  ]
}

Required schedule fields

Inputs and outputs

{
  "syntax": "{{outputName}} or {{outputName.property}}; loop list uses outputName without braces.",
  "fetch_email": {
    "emailAttachments": "array of stored attachment paths",
    "emailBody": "email HTML/text",
    "emailSender": "sender email",
    "emailSubject": "subject",
    "emailSendDate": "message date"
  },
  "transcribe_audio": "Reads emailAttachments; writes each configured output as text and outputQuality as an object. audioTranscription remains an alias for the first result.",
  "code_and_http": "Writes the return value under fields.output. Its structure depends on your code or endpoint.",
  "ai": "Prompts run in list order; later prompts may use earlier outputs. response json requests parsed JSON; specify the required properties in prompt text.",
  "loops": "fields.item and fields.index are available to loop children.",
  "scope": "Branch outputs are available only if that branch ran. Project API/environment tags require project configuration and are not implied by text references."
}

Validation and errors

Checks schema, saved references, project permissions, model catalog and edit constraints. Does not execute steps or contact external providers. Independent schema errors are returned together; resolve these before semantic checks.

Validation success returns {"valid":true,"issues":[],"warnings":[...]}. Errors use HTTP status codes below and JSON Pointer field paths. Validation does not save or run a task.

{
  "error": "Task validation failed",
  "code": "invalid_request",
  "issues": [
    {
      "path": "/steps/0/fields/output",
      "code": "required",
      "message": "output is required",
      "step": "Prepare orders"
    }
  ]
}

{
  "200": "Read, update or successful validation",
  "201": "Created",
  "400": "Invalid request; inspect issues",
  "401": "Authentication required",
  "403": "Permission denied",
  "404": "Task not found in project",
  "409": "Stale revision, queued/running task or conflicting saved configuration"
}