{
  "openapi": "3.1.0",
  "info": {
    "title": "Hapti API",
    "version": "2026-11-22",
    "description": "Hapti does tasks on websites that have no API: an agent operates a real browser by sight, like a person, and returns the result with proof. You pay only when a task succeeds.",
    "contact": {
      "url": "https://hapti.dev/docs"
    },
    "termsOfService": "https://hapti.dev/legal/terms"
  },
  "servers": [
    {
      "url": "https://api.hapti.dev"
    }
  ],
  "security": [
    {
      "bearer": []
    }
  ],
  "externalDocs": {
    "url": "https://hapti.dev/docs",
    "description": "Guides"
  },
  "tags": [
    {
      "name": "Tasks"
    },
    {
      "name": "Catalogue"
    },
    {
      "name": "Batches"
    },
    {
      "name": "Schedules"
    },
    {
      "name": "Users"
    },
    {
      "name": "Webhooks"
    },
    {
      "name": "Events"
    },
    {
      "name": "Recipes"
    },
    {
      "name": "Account"
    }
  ],
  "paths": {
    "/v1/tasks": {
      "post": {
        "tags": [
          "Tasks"
        ],
        "operationId": "createTask",
        "summary": "Create a task",
        "description": "Starts an agent that does the goal on the website, by sight, in a real browser. Returns at once; follow the task with GET, the live stream or webhooks.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Any unique string of 1 to 255 visible characters. The same key with the same request within 24 hours returns the first answer again instead of acting twice.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TaskInput"
              },
              "example": {
                "url": "https://portal.example.com/claims",
                "goal": "Declare the water damage claim and give me the claim number.",
                "data": {
                  "contract": "AX-4471",
                  "date": "2026-11-20"
                },
                "user": "customer_42"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The task was created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Task"
                },
                "example": {
                  "id": "tsk_9a96d9052acef545",
                  "object": "task",
                  "batch": null,
                  "schedule": null,
                  "mode": "test",
                  "status": "queued",
                  "paused": null,
                  "level": "standard",
                  "price_cents": 0,
                  "starting_price_cents": 10,
                  "billed": false,
                  "user": "customer_42",
                  "url": "https://portal.example.com/claims",
                  "goal": "Declare the water damage claim and give me the claim number.",
                  "input": {
                    "data": {
                      "contract": "AX-4471",
                      "date": "2026-11-20"
                    },
                    "files": []
                  },
                  "pending": null,
                  "learn": true,
                  "used_recipe": null,
                  "template": null,
                  "created_by": {
                    "type": "key",
                    "id": "key_d160ed300d0cf627",
                    "hint": "hp_test_7eF…ZD9D",
                    "name": "default test key",
                    "owner_email": null
                  },
                  "recipe_chosen": null,
                  "recipe": null,
                  "dispute": null,
                  "result": null,
                  "files": [],
                  "usage": null,
                  "created_at": "2026-11-22T18:40:56.170Z",
                  "finished_at": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/InsufficientCredit"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "get": {
        "tags": [
          "Tasks"
        ],
        "operationId": "listTasks",
        "summary": "List tasks",
        "description": "Tasks of the key mode, newest first, paged with a cursor.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1 to 100, 25 by default",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "next_cursor of the previous page",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "One status or several separated by commas",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "user",
            "in": "query",
            "required": false,
            "description": "Only the tasks of this person",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Search the goal, the site, the person or the id",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "since",
            "in": "query",
            "required": false,
            "description": "ISO date",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "until",
            "in": "query",
            "required": false,
            "description": "ISO date",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "template",
            "in": "query",
            "required": false,
            "description": "Catalogue template id",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "batch",
            "in": "query",
            "required": false,
            "description": "Batch id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of tasks",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Task"
                      }
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                },
                "example": {
                  "object": "list",
                  "data": [
                    {
                      "id": "tsk_9a96d9052acef545",
                      "object": "task",
                      "batch": null,
                      "schedule": null,
                      "mode": "test",
                      "status": "succeeded",
                      "paused": null,
                      "level": "standard",
                      "price_cents": 0,
                      "starting_price_cents": 10,
                      "billed": false,
                      "user": "customer_42",
                      "url": "https://portal.example.com/claims",
                      "goal": "Declare the water damage claim and give me the claim number.",
                      "input": {
                        "data": {
                          "contract": "AX-4471",
                          "date": "2026-11-20"
                        },
                        "files": []
                      },
                      "pending": null,
                      "learn": true,
                      "used_recipe": null,
                      "template": null,
                      "created_by": {
                        "type": "key",
                        "id": "key_d160ed300d0cf627",
                        "hint": "hp_test_7eF…ZD9D",
                        "name": "default test key",
                        "owner_email": null
                      },
                      "recipe_chosen": null,
                      "recipe": null,
                      "dispute": null,
                      "result": {
                        "answer": "The claim is declared. Claim number SIN-2026-118.",
                        "data": {
                          "claim_number": "SIN-2026-118"
                        }
                      },
                      "files": [],
                      "usage": {
                        "steps": 14
                      },
                      "created_at": "2026-11-22T18:40:56.170Z",
                      "finished_at": "2026-11-22T18:40:56.190Z"
                    }
                  ],
                  "has_more": false,
                  "next_cursor": null,
                  "total": 1
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/tasks/estimate": {
      "post": {
        "tags": [
          "Tasks"
        ],
        "operationId": "estimateTask",
        "summary": "Estimate a task",
        "description": "Gives the likely price of a task before you create it, from your earlier successes of the same task and its recipe.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TaskInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "An estimate",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "object": "estimate",
                  "level": "standard",
                  "currency": "usd",
                  "recipe": null,
                  "based_on": "nothing yet: this task has never succeeded here",
                  "typical_actions": null,
                  "likely_cents": 10,
                  "at_most_cents": null,
                  "minimum_cents": 10,
                  "charged": "never: test mode is free"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/tasks/{id}": {
      "get": {
        "tags": [
          "Tasks"
        ],
        "operationId": "getTask",
        "summary": "Get a task",
        "description": "The current state of a task, with its result once it is over.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Task id, like tsk_9f2c41a07b3d5e18",
            "schema": {
              "type": "string",
              "pattern": "^tsk_[0-9a-f]+$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The task",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Task"
                },
                "example": {
                  "id": "tsk_9a96d9052acef545",
                  "object": "task",
                  "batch": null,
                  "schedule": null,
                  "mode": "test",
                  "status": "succeeded",
                  "paused": null,
                  "level": "standard",
                  "price_cents": 0,
                  "starting_price_cents": 10,
                  "billed": false,
                  "user": "customer_42",
                  "url": "https://portal.example.com/claims",
                  "goal": "Declare the water damage claim and give me the claim number.",
                  "input": {
                    "data": {
                      "contract": "AX-4471",
                      "date": "2026-11-20"
                    },
                    "files": []
                  },
                  "pending": null,
                  "learn": true,
                  "used_recipe": null,
                  "template": null,
                  "created_by": {
                    "type": "key",
                    "id": "key_d160ed300d0cf627",
                    "hint": "hp_test_7eF…ZD9D",
                    "name": "default test key",
                    "owner_email": null
                  },
                  "recipe_chosen": null,
                  "recipe": null,
                  "dispute": null,
                  "result": {
                    "answer": "The claim is declared. Claim number SIN-2026-118.",
                    "data": {
                      "claim_number": "SIN-2026-118"
                    }
                  },
                  "files": [],
                  "usage": {
                    "steps": 14
                  },
                  "created_at": "2026-11-22T18:40:56.170Z",
                  "finished_at": "2026-11-22T18:40:56.190Z"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/tasks/{id}/answer": {
      "post": {
        "tags": [
          "Tasks"
        ],
        "operationId": "answerTask",
        "summary": "Answer a question",
        "description": "Gives the agent the value it asked for when the task is waiting with a pending question.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Task id, like tsk_9f2c41a07b3d5e18",
            "schema": {
              "type": "string",
              "pattern": "^tsk_[0-9a-f]+$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "value"
                ],
                "properties": {
                  "key": {
                    "type": "string",
                    "description": "The pending.key of the question"
                  },
                  "value": {
                    "type": "string"
                  }
                }
              },
              "example": {
                "key": "policy_holder_phone",
                "value": "+351 912 345 678"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Task"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/tasks/{id}/approve": {
      "post": {
        "tags": [
          "Tasks"
        ],
        "operationId": "approveTask",
        "summary": "Approve or refuse a step",
        "description": "Answers a pending approval: the agent goes on with approve true, and stops that step with approve false.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Task id, like tsk_9f2c41a07b3d5e18",
            "schema": {
              "type": "string",
              "pattern": "^tsk_[0-9a-f]+$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "approve"
                ],
                "properties": {
                  "approve": {
                    "type": "boolean"
                  },
                  "by": {
                    "type": "string",
                    "description": "Who decided, kept with the proof"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Task"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/tasks/{id}/cancel": {
      "post": {
        "tags": [
          "Tasks"
        ],
        "operationId": "cancelTask",
        "summary": "Cancel a task",
        "description": "Stops a task that is queued, running, waiting or paused. A cancelled task is never billed.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Task id, like tsk_9f2c41a07b3d5e18",
            "schema": {
              "type": "string",
              "pattern": "^tsk_[0-9a-f]+$"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Any unique string of 1 to 255 visible characters. The same key with the same request within 24 hours returns the first answer again instead of acting twice.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Task"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/tasks/{id}/retry": {
      "post": {
        "tags": [
          "Tasks"
        ],
        "operationId": "retryTask",
        "summary": "Run a task again",
        "description": "Creates a new task with the same input as a finished one.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Task id, like tsk_9f2c41a07b3d5e18",
            "schema": {
              "type": "string",
              "pattern": "^tsk_[0-9a-f]+$"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Any unique string of 1 to 255 visible characters. The same key with the same request within 24 hours returns the first answer again instead of acting twice.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          }
        ],
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Task"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/tasks/{id}/stream": {
      "get": {
        "tags": [
          "Tasks"
        ],
        "operationId": "streamTask",
        "summary": "Follow a task live",
        "description": "Server-Sent Events: task when its state changes, step for each action of the agent, screenshot for each image, done at the end. Send Last-Event-ID to resume after the last step.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Task id, like tsk_9f2c41a07b3d5e18",
            "schema": {
              "type": "string",
              "pattern": "^tsk_[0-9a-f]+$"
            }
          },
          {
            "name": "Last-Event-ID",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "An event stream",
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/tasks/{id}/proof": {
      "get": {
        "tags": [
          "Tasks"
        ],
        "operationId": "getProof",
        "summary": "Get the proof",
        "description": "Every step of the agent and the screenshots it saw, kept 90 days.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Task id, like tsk_9f2c41a07b3d5e18",
            "schema": {
              "type": "string",
              "pattern": "^tsk_[0-9a-f]+$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "task": {
                      "$ref": "#/components/schemas/Task"
                    },
                    "events": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "screenshots": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "tags": [
          "Tasks"
        ],
        "operationId": "deleteProof",
        "summary": "Delete the proof",
        "description": "Erases the steps and screenshots of a finished task now.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Task id, like tsk_9f2c41a07b3d5e18",
            "schema": {
              "type": "string",
              "pattern": "^tsk_[0-9a-f]+$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/tasks/{id}/files/{name}": {
      "get": {
        "tags": [
          "Tasks"
        ],
        "operationId": "getTaskFile",
        "summary": "Download a file",
        "description": "A file the site gave during the task, listed in task.files.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Task id, like tsk_9f2c41a07b3d5e18",
            "schema": {
              "type": "string",
              "pattern": "^tsk_[0-9a-f]+$"
            }
          },
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The file",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/tasks/{id}/dispute": {
      "post": {
        "tags": [
          "Tasks"
        ],
        "operationId": "disputeTask",
        "summary": "Dispute a billed task",
        "description": "Asks for a check of a billed task whose result is wrong. The proof is reviewed and the price refunded when the claim is right.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Task id, like tsk_9f2c41a07b3d5e18",
            "schema": {
              "type": "string",
              "pattern": "^tsk_[0-9a-f]+$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "reason"
                ],
                "properties": {
                  "reason": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/catalogue": {
      "get": {
        "tags": [
          "Catalogue"
        ],
        "operationId": "listTemplates",
        "summary": "List templates",
        "description": "Ready-made tasks: give a template id and its params instead of a url and a goal.",
        "parameters": [
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "en or fr",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The templates",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                },
                "example": {
                  "object": "list",
                  "data": [
                    {
                      "id": "prendre_rdv",
                      "group": "demarches",
                      "name": "Book an appointment",
                      "description": "On a booking site (prefecture, town hall, doctor…), books the first slot that fits.",
                      "params": {
                        "site": "address of the booking page",
                        "reason": "reason for the appointment",
                        "window": "preferred dates and times (optional)"
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/batches": {
      "post": {
        "tags": [
          "Batches"
        ],
        "operationId": "createBatch",
        "summary": "Create a batch",
        "description": "Many tasks at once, from a list of tasks or from one template and a list of items.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Any unique string of 1 to 255 visible characters. The same key with the same request within 24 hours returns the first answer again instead of acting twice.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "webhook": {
                    "type": "string",
                    "format": "uri"
                  },
                  "tasks": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/TaskInput"
                    }
                  },
                  "template": {
                    "$ref": "#/components/schemas/TaskInput"
                  },
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The batch",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Batch"
                },
                "example": {
                  "id": "bat_344f0b5bbdb6853e",
                  "object": "batch",
                  "mode": "test",
                  "name": "November invoices",
                  "total": 2,
                  "done": 0,
                  "counts": {
                    "queued": 2,
                    "paused": 0,
                    "running": 0,
                    "waiting": 0,
                    "succeeded": 0,
                    "failed": 0,
                    "blocked": 0,
                    "incomplete": 0,
                    "needs_person": 0,
                    "cancelled": 0
                  },
                  "billed_cents": 0,
                  "created_at": "2026-11-22T18:40:56.210Z",
                  "finished_at": null,
                  "cancelled": false
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "get": {
        "tags": [
          "Batches"
        ],
        "operationId": "listBatches",
        "summary": "List batches",
        "description": "Batches, newest first.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Up to 100",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Batch"
                      }
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/batches/{id}": {
      "get": {
        "tags": [
          "Batches"
        ],
        "operationId": "getBatch",
        "summary": "Get a batch",
        "description": "Counts per status and what was billed.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Batch id",
            "schema": {
              "type": "string",
              "pattern": "^bat_[0-9a-f]{16}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Batch"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/batches/{id}/tasks": {
      "get": {
        "tags": [
          "Batches"
        ],
        "operationId": "listBatchTasks",
        "summary": "List the tasks of a batch",
        "description": "Paged with after and next.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Batch id",
            "schema": {
              "type": "string",
              "pattern": "^bat_[0-9a-f]{16}$"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Filter by status",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "after",
            "in": "query",
            "required": false,
            "description": "next of the previous page",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Up to 200",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/batches/{id}/cancel": {
      "post": {
        "tags": [
          "Batches"
        ],
        "operationId": "cancelBatch",
        "summary": "Cancel a batch",
        "description": "Cancels every task of the batch that is not over.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Batch id",
            "schema": {
              "type": "string",
              "pattern": "^bat_[0-9a-f]{16}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/schedules": {
      "post": {
        "tags": [
          "Schedules"
        ],
        "operationId": "createSchedule",
        "summary": "Create a schedule",
        "description": "Runs the same task on a cron or every interval, in a time zone.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Any unique string of 1 to 255 visible characters. The same key with the same request within 24 hours returns the first answer again instead of acting twice.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "task"
                ],
                "properties": {
                  "task": {
                    "$ref": "#/components/schemas/TaskInput"
                  },
                  "cron": {
                    "type": "string",
                    "example": "0 8 * * 1"
                  },
                  "every": {
                    "type": "string",
                    "example": "1d"
                  },
                  "timezone": {
                    "type": "string",
                    "example": "Europe/Lisbon"
                  },
                  "name": {
                    "type": "string"
                  },
                  "start_at": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "until": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "run_now": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The schedule",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Schedule"
                },
                "example": {
                  "id": "sch_f23abc98afc7afcc",
                  "object": "schedule",
                  "mode": "test",
                  "name": "Monday report",
                  "every": null,
                  "cron": "0 8 * * 1",
                  "timezone": "Europe/Lisbon",
                  "paused": false,
                  "next_run_at": "2026-11-23T08:00:00.000Z",
                  "until": null,
                  "runs": 0,
                  "last_task": null,
                  "last_run_at": null,
                  "last_error": null,
                  "task": {
                    "url": "https://portal.example.com/reports",
                    "goal": "Download the weekly report."
                  },
                  "created_at": "2026-11-22T18:40:56.222Z"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "get": {
        "tags": [
          "Schedules"
        ],
        "operationId": "listSchedules",
        "summary": "List schedules",
        "description": "Every schedule of the mode.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Schedule"
                      }
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/schedules/{id}": {
      "get": {
        "tags": [
          "Schedules"
        ],
        "operationId": "getSchedule",
        "summary": "Get a schedule",
        "description": "",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Schedule id",
            "schema": {
              "type": "string",
              "pattern": "^sch_[0-9a-f]{16}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Schedule"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "tags": [
          "Schedules"
        ],
        "operationId": "updateSchedule",
        "summary": "Pause or resume a schedule",
        "description": "Send paused true or false.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Schedule id",
            "schema": {
              "type": "string",
              "pattern": "^sch_[0-9a-f]{16}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "paused": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Schedule"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "tags": [
          "Schedules"
        ],
        "operationId": "deleteSchedule",
        "summary": "Delete a schedule",
        "description": "",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Schedule id",
            "schema": {
              "type": "string",
              "pattern": "^sch_[0-9a-f]{16}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/schedules/{id}/tasks": {
      "get": {
        "tags": [
          "Schedules"
        ],
        "operationId": "listScheduleTasks",
        "summary": "List the tasks of a schedule",
        "description": "",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Schedule id",
            "schema": {
              "type": "string",
              "pattern": "^sch_[0-9a-f]{16}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/users": {
      "post": {
        "tags": [
          "Users"
        ],
        "operationId": "createUser",
        "summary": "Create a person",
        "description": "Registers a person you act for, with their country, language and time zone. Tasks with the same user share one device, one session and one memory.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "id"
                ],
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "country": {
                    "type": "string"
                  },
                  "locale": {
                    "type": "string"
                  },
                  "timezone": {
                    "type": "string"
                  },
                  "mandate": {
                    "$ref": "#/components/schemas/Mandate"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The person",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                },
                "example": {
                  "object": "user",
                  "id": "customer_42",
                  "name": "Ana Silva",
                  "created_at": "2026-11-22T18:40:56.163Z",
                  "mandate": null,
                  "session": null,
                  "device": {
                    "locale": "pt-PT",
                    "timezone": "Europe/Lisbon",
                    "country": "pt",
                    "country_set": true,
                    "since": "2026-11-22T18:40:56.165Z"
                  },
                  "limits": null,
                  "accounts": []
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "get": {
        "tags": [
          "Users"
        ],
        "operationId": "listUsers",
        "summary": "List people",
        "description": "",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Up to 100",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Search",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "next_cursor of the previous page",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/User"
                      }
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/users/{user}": {
      "get": {
        "tags": [
          "Users"
        ],
        "operationId": "getUser",
        "summary": "Get a person",
        "description": "",
        "parameters": [
          {
            "name": "user",
            "in": "path",
            "required": true,
            "description": "Your own id for the person, like customer_42",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9._@-]{1,64}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "tags": [
          "Users"
        ],
        "operationId": "updateUser",
        "summary": "Update a person",
        "description": "Name, country, language, time zone and limits.",
        "parameters": [
          {
            "name": "user",
            "in": "path",
            "required": true,
            "description": "Your own id for the person, like customer_42",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9._@-]{1,64}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "country": {
                    "type": "string"
                  },
                  "locale": {
                    "type": "string"
                  },
                  "timezone": {
                    "type": "string"
                  },
                  "limits": {
                    "type": "object",
                    "properties": {
                      "tasks_per_day": {
                        "type": "integer"
                      },
                      "cents_per_month": {
                        "type": "integer"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "tags": [
          "Users"
        ],
        "operationId": "forgetUser",
        "summary": "Forget a person",
        "description": "Erases the person: session, memory, stored accounts, mandate, inbox and received messages.",
        "parameters": [
          {
            "name": "user",
            "in": "path",
            "required": true,
            "description": "Your own id for the person, like customer_42",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9._@-]{1,64}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/users/{user}/mandate": {
      "post": {
        "tags": [
          "Users"
        ],
        "operationId": "giveMandate",
        "summary": "Give a mandate",
        "description": "Records what the agent may do for the person without asking each time, and who agreed to it.",
        "parameters": [
          {
            "name": "user",
            "in": "path",
            "required": true,
            "description": "Your own id for the person, like customer_42",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9._@-]{1,64}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Mandate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The mandate",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "mandate": {
                    "scope": "Declare insurance claims and download invoices",
                    "sites": [],
                    "given_by": "Ana Silva, in the app on 2026-11-20",
                    "until": null,
                    "given_at": "2026-11-22T18:40:56.233Z"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "tags": [
          "Users"
        ],
        "operationId": "revokeMandate",
        "summary": "Revoke the mandate",
        "description": "",
        "parameters": [
          {
            "name": "user",
            "in": "path",
            "required": true,
            "description": "Your own id for the person, like customer_42",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9._@-]{1,64}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/users/{user}/accounts": {
      "get": {
        "tags": [
          "Users"
        ],
        "operationId": "listAccounts",
        "summary": "List stored accounts",
        "description": "Accounts the agent may sign in with for this person. Secrets are never returned.",
        "parameters": [
          {
            "name": "user",
            "in": "path",
            "required": true,
            "description": "Your own id for the person, like customer_42",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9._@-]{1,64}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/users/{user}/accounts/{account}": {
      "put": {
        "tags": [
          "Users"
        ],
        "operationId": "putAccount",
        "summary": "Store an account",
        "description": "Saves sign-in details in the vault, sealed. The agent types them in the browser; the model never sees them.",
        "parameters": [
          {
            "name": "user",
            "in": "path",
            "required": true,
            "description": "Your own id for the person, like customer_42",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9._@-]{1,64}$"
            }
          },
          {
            "name": "account",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{1,40}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "origin",
                  "password"
                ],
                "properties": {
                  "origin": {
                    "type": "string",
                    "format": "uri"
                  },
                  "username": {
                    "type": "string"
                  },
                  "password": {
                    "type": "string"
                  },
                  "totp_secret": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The account, without its secret",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "account": "insurer",
                  "label": "insurer",
                  "origin": "https://portal.example.com",
                  "has_username": true,
                  "has_totp": false,
                  "entered_by": "developer",
                  "updated_at": "2026-11-22T18:40:56.235Z"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "tags": [
          "Users"
        ],
        "operationId": "deleteAccount",
        "summary": "Delete an account",
        "description": "",
        "parameters": [
          {
            "name": "user",
            "in": "path",
            "required": true,
            "description": "Your own id for the person, like customer_42",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9._@-]{1,64}$"
            }
          },
          {
            "name": "account",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/users/{user}/connect": {
      "post": {
        "tags": [
          "Users"
        ],
        "operationId": "createConnectLink",
        "summary": "Create a connect link",
        "description": "A page where the person enters their own sign-in details. You never see them.",
        "parameters": [
          {
            "name": "user",
            "in": "path",
            "required": true,
            "description": "Your own id for the person, like customer_42",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9._@-]{1,64}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "accounts": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "account": {
                          "type": "string"
                        },
                        "origin": {
                          "type": "string",
                          "format": "uri"
                        }
                      }
                    }
                  },
                  "brand": {
                    "type": "string"
                  },
                  "return_url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "expires_in": {
                    "type": "integer"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "tags": [
          "Users"
        ],
        "operationId": "revokeConnectLinks",
        "summary": "Revoke connect links",
        "description": "",
        "parameters": [
          {
            "name": "user",
            "in": "path",
            "required": true,
            "description": "Your own id for the person, like customer_42",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9._@-]{1,64}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/users/{user}/memory": {
      "get": {
        "tags": [
          "Users"
        ],
        "operationId": "getMemory",
        "summary": "Read the memory",
        "description": "Lasting facts the agent kept about the person, never secrets.",
        "parameters": [
          {
            "name": "user",
            "in": "path",
            "required": true,
            "description": "Your own id for the person, like customer_42",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9._@-]{1,64}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "tags": [
          "Users"
        ],
        "operationId": "addMemory",
        "summary": "Add a fact",
        "description": "",
        "parameters": [
          {
            "name": "user",
            "in": "path",
            "required": true,
            "description": "Your own id for the person, like customer_42",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9._@-]{1,64}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "fact"
                ],
                "properties": {
                  "fact": {
                    "type": "string",
                    "minLength": 3,
                    "maxLength": 300
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "tags": [
          "Users"
        ],
        "operationId": "forgetMemory",
        "summary": "Erase the memory",
        "description": "",
        "parameters": [
          {
            "name": "user",
            "in": "path",
            "required": true,
            "description": "Your own id for the person, like customer_42",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9._@-]{1,64}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/users/{user}/inbox": {
      "post": {
        "tags": [
          "Users"
        ],
        "operationId": "createInbox",
        "summary": "Open an email inbox",
        "description": "An address that receives the emails sites send to the person, such as confirmation codes, which the agent reads by itself.",
        "parameters": [
          {
            "name": "user",
            "in": "path",
            "required": true,
            "description": "Your own id for the person, like customer_42",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9._@-]{1,64}$"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "username": {
                    "type": "string"
                  },
                  "domain": {
                    "type": "string"
                  },
                  "client_id": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "get": {
        "tags": [
          "Users"
        ],
        "operationId": "listInboxes",
        "summary": "List inboxes",
        "description": "",
        "parameters": [
          {
            "name": "user",
            "in": "path",
            "required": true,
            "description": "Your own id for the person, like customer_42",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9._@-]{1,64}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/users/{user}/emails": {
      "get": {
        "tags": [
          "Users"
        ],
        "operationId": "listEmails",
        "summary": "List received emails",
        "description": "",
        "parameters": [
          {
            "name": "user",
            "in": "path",
            "required": true,
            "description": "Your own id for the person, like customer_42",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9._@-]{1,64}$"
            }
          },
          {
            "name": "since",
            "in": "query",
            "required": false,
            "description": "ISO date",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Up to 100",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/users/{user}/phone": {
      "post": {
        "tags": [
          "Users"
        ],
        "operationId": "givePhone",
        "summary": "Give a phone number",
        "description": "A real number that receives the texts sites send. Live keys only, paid monthly from the credit.",
        "parameters": [
          {
            "name": "user",
            "in": "path",
            "required": true,
            "description": "Your own id for the person, like customer_42",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9._@-]{1,64}$"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "country": {
                    "type": "string",
                    "example": "us"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "get": {
        "tags": [
          "Users"
        ],
        "operationId": "getPhone",
        "summary": "Get the phone number",
        "description": "",
        "parameters": [
          {
            "name": "user",
            "in": "path",
            "required": true,
            "description": "Your own id for the person, like customer_42",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9._@-]{1,64}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "tags": [
          "Users"
        ],
        "operationId": "releasePhone",
        "summary": "Release the phone number",
        "description": "",
        "parameters": [
          {
            "name": "user",
            "in": "path",
            "required": true,
            "description": "Your own id for the person, like customer_42",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9._@-]{1,64}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/users/{user}/sms": {
      "get": {
        "tags": [
          "Users"
        ],
        "operationId": "listSms",
        "summary": "List received texts",
        "description": "",
        "parameters": [
          {
            "name": "user",
            "in": "path",
            "required": true,
            "description": "Your own id for the person, like customer_42",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9._@-]{1,64}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/users/{user}/usage": {
      "get": {
        "tags": [
          "Users"
        ],
        "operationId": "getUserUsage",
        "summary": "Usage of a person",
        "description": "Tasks and amounts billed for this person.",
        "parameters": [
          {
            "name": "user",
            "in": "path",
            "required": true,
            "description": "Your own id for the person, like customer_42",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9._@-]{1,64}$"
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "YYYY-MM-DD",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "YYYY-MM-DD",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/webhooks/endpoints": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "createWebhookEndpoint",
        "summary": "Create an endpoint",
        "description": "An https address that receives the events you choose, signed with its own secret. The secret is returned once here.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Any unique string of 1 to 255 visible characters. The same key with the same request within 24 hours returns the first answer again instead of acting twice.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookEndpointInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The endpoint",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpoint"
                },
                "example": {
                  "id": "we_0e47caf33717b1a8",
                  "object": "webhook_endpoint",
                  "url": "https://api.example.com/hooks/hapti",
                  "events": [
                    "task.succeeded",
                    "task.failed",
                    "task.waiting"
                  ],
                  "description": "Production",
                  "enabled": true,
                  "disabled_reason": null,
                  "disabled_at": null,
                  "failing_since": null,
                  "last_success_at": null,
                  "headers": {},
                  "mode": "test",
                  "secret": "whsec_0f9c3a…",
                  "previous_secret_expires_at": null,
                  "created_at": "2026-11-22T18:40:56.225Z"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "get": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "listWebhookEndpoints",
        "summary": "List endpoints",
        "description": "With their deliveries and failures of the last 7 days.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/WebhookEndpoint"
                      }
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/webhooks/endpoints/{id}": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "getWebhookEndpoint",
        "summary": "Get an endpoint",
        "description": "",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Webhook endpoint id",
            "schema": {
              "type": "string",
              "pattern": "^we_[0-9a-f]{16}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpoint"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "updateWebhookEndpoint",
        "summary": "Update an endpoint",
        "description": "Address, events, description, headers, or enabled to pause and resume.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Webhook endpoint id",
            "schema": {
              "type": "string",
              "pattern": "^we_[0-9a-f]{16}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookEndpointInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpoint"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "deleteWebhookEndpoint",
        "summary": "Delete an endpoint",
        "description": "",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Webhook endpoint id",
            "schema": {
              "type": "string",
              "pattern": "^we_[0-9a-f]{16}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/webhooks/endpoints/{id}/secret": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "getWebhookSecret",
        "summary": "Reveal the secret",
        "description": "",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Webhook endpoint id",
            "schema": {
              "type": "string",
              "pattern": "^we_[0-9a-f]{16}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "secret": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/webhooks/endpoints/{id}/roll-secret": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "rollWebhookSecret",
        "summary": "Roll the secret",
        "description": "A new secret; the previous one stays valid for expires_in_hours (24 by default, 0 to 168) and each delivery carries both signatures meanwhile.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Webhook endpoint id",
            "schema": {
              "type": "string",
              "pattern": "^we_[0-9a-f]{16}$"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "expires_in_hours": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 168
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpoint"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/webhooks/endpoints/{id}/test": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "testWebhookEndpoint",
        "summary": "Send a test event",
        "description": "Sends a signed ping event now and returns the delivery with the answer of your server.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Webhook endpoint id",
            "schema": {
              "type": "string",
              "pattern": "^we_[0-9a-f]{16}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookDelivery"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/webhooks/endpoints/{id}/recover": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "recoverWebhookEndpoint",
        "summary": "Send missed events again",
        "description": "Sends once every event of the period that never reached this endpoint.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Webhook endpoint id",
            "schema": {
              "type": "string",
              "pattern": "^we_[0-9a-f]{16}$"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "since": {
                    "type": "string",
                    "format": "date-time",
                    "description": "3 days ago by default, at most 30"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "resent": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/webhook/secret": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "getOrganisationWebhookSecret",
        "summary": "Reveal the organisation secret",
        "description": "The secret that signs the deliveries of webhooks given on a task or a batch with the webhook field.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "secret": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/webhooks/events": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "listEventTypes",
        "summary": "List event types",
        "description": "",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/webhooks/deliveries": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "listWebhookDeliveries",
        "summary": "List deliveries",
        "description": "",
        "parameters": [
          {
            "name": "endpoint",
            "in": "query",
            "required": false,
            "description": "Endpoint id",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "event",
            "in": "query",
            "required": false,
            "description": "Event type",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "description": "pending, delivered or failed",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Up to 100",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "next_cursor of the previous page",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/WebhookDelivery"
                      }
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/webhooks/deliveries/{id}": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "getWebhookDelivery",
        "summary": "Get a delivery",
        "description": "With every attempt, the answer of your server and the body sent.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Delivery id",
            "schema": {
              "type": "string",
              "pattern": "^whd_\\d+$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookDelivery"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/webhooks/deliveries/{id}/resend": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "resendWebhookDelivery",
        "summary": "Send a delivery again",
        "description": "",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Delivery id",
            "schema": {
              "type": "string",
              "pattern": "^whd_\\d+$"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookDelivery"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/events": {
      "get": {
        "tags": [
          "Events"
        ],
        "operationId": "listEvents",
        "summary": "List events",
        "description": "Every event of the last 30 days, the same objects webhooks send.",
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "An event type, or a family like task.*",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "object",
            "in": "query",
            "required": false,
            "description": "Only the events of this task or object id",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "since",
            "in": "query",
            "required": false,
            "description": "ISO date",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Up to 100",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "next_cursor of the previous page",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of events",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Event"
                      }
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                },
                "example": {
                  "object": "list",
                  "data": [
                    {
                      "id": "evt_c3b9a22cc8666f754e930055",
                      "object": "event",
                      "type": "task.succeeded",
                      "api_version": "2026-11-22",
                      "created_at": "2026-11-22T18:40:56.191Z",
                      "mode": "test",
                      "data": {
                        "id": "tsk_9a96d9052acef545",
                        "object": "task",
                        "batch": null,
                        "schedule": null,
                        "mode": "test",
                        "status": "succeeded",
                        "paused": null,
                        "level": "standard",
                        "price_cents": 0,
                        "starting_price_cents": 10,
                        "billed": false,
                        "user": "customer_42",
                        "url": "https://portal.example.com/claims",
                        "goal": "Declare the water damage claim and give me the claim number.",
                        "input": {
                          "data": {
                            "contract": "AX-4471",
                            "date": "2026-11-20"
                          },
                          "files": []
                        },
                        "pending": null,
                        "learn": true,
                        "used_recipe": null,
                        "template": null,
                        "created_by": {
                          "type": "key",
                          "id": "key_d160ed300d0cf627",
                          "hint": "hp_test_7eF…ZD9D",
                          "name": "default test key",
                          "owner_email": null
                        },
                        "recipe_chosen": null,
                        "recipe": null,
                        "dispute": null,
                        "result": {
                          "answer": "The claim is declared. Claim number SIN-2026-118.",
                          "data": {
                            "claim_number": "SIN-2026-118"
                          }
                        },
                        "files": [],
                        "usage": {
                          "steps": 14
                        },
                        "created_at": "2026-11-22T18:40:56.170Z",
                        "finished_at": "2026-11-22T18:40:56.190Z"
                      }
                    }
                  ],
                  "has_more": false,
                  "next_cursor": null,
                  "total": 1
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/events/{id}": {
      "get": {
        "tags": [
          "Events"
        ],
        "operationId": "getEvent",
        "summary": "Get an event",
        "description": "",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Event id",
            "schema": {
              "type": "string",
              "pattern": "^evt_[0-9a-f]+$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Event"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/stream": {
      "get": {
        "tags": [
          "Events"
        ],
        "operationId": "streamEvents",
        "summary": "Follow every task live",
        "description": "Server-Sent Events: a task event each time a task of the mode changes state.",
        "responses": {
          "200": {
            "description": "An event stream",
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/me": {
      "get": {
        "tags": [
          "Account"
        ],
        "operationId": "getMe",
        "summary": "Who am I",
        "description": "The organisation and mode of the key.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/billing": {
      "get": {
        "tags": [
          "Account"
        ],
        "operationId": "getBalance",
        "summary": "Credit and prices",
        "description": "The credit left and the prices.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/usage": {
      "get": {
        "tags": [
          "Account"
        ],
        "operationId": "getUsage",
        "summary": "Usage by day",
        "description": "",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "YYYY-MM-DD",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "YYYY-MM-DD",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/usage/users": {
      "get": {
        "tags": [
          "Account"
        ],
        "operationId": "getUsageByUser",
        "summary": "Usage by person",
        "description": "",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "YYYY-MM-DD",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "YYYY-MM-DD",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/versions": {
      "get": {
        "tags": [
          "Account"
        ],
        "operationId": "listVersions",
        "summary": "API versions",
        "description": "Every version and what it changed, with the one your organisation is pinned to.",
        "responses": {
          "200": {
            "description": "The versions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "object": "list",
                  "latest": "2026-11-22",
                  "pinned": "2026-11-22",
                  "current": "2026-11-22",
                  "data": [
                    {
                      "id": "2026-11-22",
                      "changes": [
                        "A live task without enough credit is created paused and starts by itself once credit is added (on_insufficient_credit: refuse keeps the 402).",
                        "Lists are paged with has_more, next_cursor and total.",
                        "price_cents is what was billed, 0 until a live task succeeds; starting_price_cents gives the starting price."
                      ]
                    },
                    {
                      "id": "2026-11-01",
                      "changes": [
                        "A live task without enough credit is refused with 402 insufficient_credit."
                      ]
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/recipes": {
      "get": {
        "tags": [
          "Recipes"
        ],
        "operationId": "listRecipes",
        "summary": "List recipes",
        "description": "Tasks learnt from successes and replayed faster and cheaper.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/recipes/{id}": {
      "get": {
        "tags": [
          "Recipes"
        ],
        "operationId": "getRecipe",
        "summary": "Get a recipe",
        "description": "",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Recipe id",
            "schema": {
              "type": "string",
              "pattern": "^rcp_"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "tags": [
          "Recipes"
        ],
        "operationId": "renameRecipe",
        "summary": "Rename a recipe",
        "description": "",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Recipe id",
            "schema": {
              "type": "string",
              "pattern": "^rcp_"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "tags": [
          "Recipes"
        ],
        "operationId": "deleteRecipe",
        "summary": "Delete a recipe",
        "description": "",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Recipe id",
            "schema": {
              "type": "string",
              "pattern": "^rcp_"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/logs": {
      "get": {
        "tags": [
          "Account"
        ],
        "operationId": "listLogs",
        "summary": "List API requests",
        "description": "Every request made with a key of the mode in the last 30 days, secrets masked.",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "ok or error",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Path or Request-Id",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Up to 100",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "next_cursor of the previous page",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "An API key: hp_test_ for free tests, hp_live_ for real tasks."
      }
    },
    "schemas": {
      "TaskInput": {
        "type": "object",
        "description": "Give url and goal, or a catalogue template and its params.",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "The page to start on."
          },
          "goal": {
            "type": "string",
            "maxLength": 4000,
            "description": "What to achieve and what to report back, in plain words, in any language."
          },
          "data": {
            "type": "object",
            "description": "The facts the agent may use. It never invents a missing value: it asks."
          },
          "template": {
            "type": "string",
            "description": "A catalogue template id, instead of url and goal."
          },
          "params": {
            "type": "object",
            "description": "The params of the template."
          },
          "user": {
            "type": "string",
            "description": "The person the task acts for. Gives the task their device, session, memory, inbox and stored accounts."
          },
          "accounts": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Stored accounts of the person the agent may sign in with."
          },
          "output": {
            "type": "object",
            "description": "A JSON Schema for result.data. A task whose answer cannot follow it is not billed."
          },
          "files": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "base64": {
                  "type": "string"
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                }
              }
            },
            "description": "Files the agent may upload on the site: up to 20, 50 MB each, 100 MB in all."
          },
          "webhook": {
            "type": "string",
            "format": "uri",
            "description": "An https address that receives the events of this task only."
          },
          "approval": {
            "type": "string",
            "enum": [
              "mandate",
              "required"
            ],
            "description": "required: the agent waits for your approval before any step that commits the person."
          },
          "max_price_cents": {
            "type": "integer",
            "description": "The agent stops before the price would go over it."
          },
          "max_steps": {
            "type": "integer",
            "minimum": 1,
            "maximum": 500
          },
          "answer_language": {
            "type": "string",
            "description": "Language of the answer and questions, like fr, pt-BR or wo. By default, the language of the goal."
          },
          "locale": {
            "type": "string",
            "description": "Language of the browser, like pt-PT."
          },
          "country": {
            "type": "string",
            "description": "Two letters: the country the sites see the person in."
          },
          "proxy": {
            "type": "boolean",
            "description": "Go out through a residential address in that country, billed per GB when the task succeeds."
          },
          "memory": {
            "type": "boolean",
            "description": "true by default with a user."
          },
          "keep_session": {
            "type": "boolean",
            "description": "true by default with a user."
          },
          "learn": {
            "type": "boolean",
            "description": "true by default: a success becomes a recipe."
          },
          "recipe": {
            "type": "string",
            "description": "A recipe id to replay."
          },
          "on_insufficient_credit": {
            "type": "string",
            "enum": [
              "pause",
              "refuse"
            ],
            "description": "pause by default: a live task without enough credit waits and starts once credit is added."
          }
        }
      },
      "Task": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "object": {
            "const": "task"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "running",
              "waiting",
              "paused",
              "succeeded",
              "failed",
              "blocked",
              "incomplete",
              "needs_person",
              "cancelled"
            ]
          },
          "mode": {
            "type": "string",
            "enum": [
              "test",
              "live"
            ]
          },
          "url": {
            "type": "string"
          },
          "goal": {
            "type": "string"
          },
          "user": {
            "type": [
              "string",
              "null"
            ]
          },
          "input": {
            "type": "object"
          },
          "pending": {
            "type": [
              "object",
              "null"
            ],
            "description": "What the agent waits for: a question or an approval, with an action_url the person can use without an account.",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "question",
                  "approval"
                ]
              },
              "key": {
                "type": "string"
              },
              "text": {
                "type": "string"
              },
              "action_url": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "result": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "answer": {
                "type": "string"
              },
              "data": {
                "type": "object"
              },
              "error": {
                "type": "string"
              }
            }
          },
          "files": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                }
              }
            }
          },
          "price_cents": {
            "type": "integer",
            "description": "What was billed: 0 until a live task succeeds."
          },
          "starting_price_cents": {
            "type": "integer"
          },
          "billed": {
            "type": "boolean"
          },
          "usage": {
            "type": [
              "object",
              "null"
            ]
          },
          "paused": {
            "type": [
              "object",
              "null"
            ]
          },
          "batch": {
            "type": [
              "string",
              "null"
            ]
          },
          "schedule": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "finished_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "Batch": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "object": {
            "const": "batch"
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "total": {
            "type": "integer"
          },
          "done": {
            "type": "integer"
          },
          "counts": {
            "type": "object"
          },
          "billed_cents": {
            "type": "integer"
          }
        }
      },
      "Schedule": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "object": {
            "const": "schedule"
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "cron": {
            "type": [
              "string",
              "null"
            ]
          },
          "every": {
            "type": [
              "string",
              "null"
            ]
          },
          "timezone": {
            "type": "string"
          },
          "paused": {
            "type": "boolean"
          },
          "next_run_at": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "User": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "object": {
            "type": "string"
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "Mandate": {
        "type": "object",
        "required": [
          "scope",
          "given_by"
        ],
        "properties": {
          "scope": {
            "type": "string",
            "description": "What the agent may do for the person."
          },
          "given_by": {
            "type": "string",
            "description": "Who gave it, or how the person agreed."
          },
          "sites": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uri"
            }
          },
          "until": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "WebhookEndpointInput": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri"
          },
          "events": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Event types, a family like user.*, or [\"*\"] for every event, including future ones."
          },
          "description": {
            "type": "string"
          },
          "headers": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Up to 10 headers sent with each delivery."
          },
          "enabled": {
            "type": "boolean"
          }
        }
      },
      "WebhookEndpoint": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "object": {
            "const": "webhook_endpoint"
          },
          "url": {
            "type": "string"
          },
          "events": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "enabled": {
            "type": "boolean"
          },
          "disabled_reason": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "manual",
              "failing",
              null
            ]
          },
          "failing_since": {
            "type": [
              "string",
              "null"
            ]
          },
          "secret": {
            "type": "string",
            "description": "Only when created, rolled or revealed."
          },
          "secret_hint": {
            "type": "string"
          }
        }
      },
      "WebhookDelivery": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "event": {
            "type": "string"
          },
          "event_id": {
            "type": "string"
          },
          "endpoint": {
            "type": [
              "string",
              "null"
            ]
          },
          "url": {
            "type": "string"
          },
          "state": {
            "type": "string",
            "enum": [
              "pending",
              "retrying",
              "delivered",
              "failed"
            ]
          },
          "status": {
            "type": [
              "integer",
              "null"
            ]
          },
          "attempts": {
            "type": "integer"
          },
          "attempts_log": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      },
      "Event": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "object": {
            "const": "event"
          },
          "type": {
            "type": "string",
            "enum": [
              "task.created",
              "task.paused",
              "task.waiting",
              "task.succeeded",
              "task.failed",
              "task.cancelled",
              "batch.finished",
              "email.received",
              "sms.received",
              "user.account_connected",
              "user.account_removed",
              "user.forward_started",
              "user.forward_stopped",
              "user.memory_forgotten",
              "ping"
            ]
          },
          "api_version": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "mode": {
            "type": "string"
          },
          "data": {
            "type": "object"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string"
              },
              "code": {
                "type": "integer"
              },
              "message": {
                "type": "string"
              },
              "reason": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "The request is not valid",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "type": "invalid_request_error",
                "code": 400,
                "message": "url: an http or https address is required"
              }
            }
          }
        }
      },
      "Unauthorized": {
        "description": "The key is missing or not valid",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "type": "authentication_error",
                "code": 401,
                "message": "a valid key is required: Authorization: Bearer hp_live_… or hp_test_…"
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "No such object",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Conflict": {
        "description": "The object is not in a state that allows this",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Too many requests: wait for Retry-After seconds",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "InsufficientCredit": {
        "description": "Not enough credit, with on_insufficient_credit set to refuse",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  }
}
