> ## Documentation Index > Fetch the complete documentation index at: https://docs.tela.com/llms.txt > Use this file to discover all available pages before exploring further. # Create tasks > Creates one or more tasks. The body may be a single task object, an array of up to 100 task objects (all must share the same `promptApplicationId`), or an agent batch object (`sourceType: "agent"`). ## OpenAPI ````yaml POST /task openapi: 3.0.1 info: title: Tela API license: name: MIT version: 1.0.0 servers: - url: https://api.tela.com security: [] paths: /task: post: tags: - Task summary: Create tasks description: > Creates one or more tasks. The body may be a single task object, an array of up to 100 task objects (all must share the same `promptApplicationId`), or an agent batch object (`sourceType: "agent"`). **Workstation/App tasks** (single object or array): - Each task is executed asynchronously against the app's current Canvas version. The response is returned immediately with the task in `running` status; poll `GET /task/{id}` or pass `rawInput.webhook_url` to be notified. - If `outputContent` is supplied, no execution happens: the task is stored directly in `validating` status with the given output (useful for importing already-extracted data). - Variables in `rawInput.variables` are validated against the app's required variables and, for multimodal variables, against the allowed file MIME types (400 `INVALID_SCHEMA` on failure). Files are passed inside variables as objects with `file_url` (see `TaskVariableValue`). - The server sets `rawInput.application_id` to `promptApplicationId` for you. - Tags from the request are merged with the Canvas version's custom tags. - Request headers prefixed with `x-tela-forward-` (max 20 headers / 8 KB) are forwarded to your webhook when the task finishes. **Agent tasks** (`sourceType: "agent"`): each task is created in `created` status and its execution is triggered on the given agent. The request is rejected with 402 when the workspace has reached its monthly usage limit. Additional internal fields accepted by the validator (`cronOccurrenceId`, `useTempFunction`, and other raw table columns) are not part of the public contract; `cronOccurrenceId` in particular returns 400 unless the request comes from the internal scheduler. requestBody: required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/TaskCreateRequest' - type: array title: Batch of tasks description: >- Up to 100 tasks. All items must have the same `promptApplicationId`. maxItems: 100 items: $ref: '#/components/schemas/TaskCreateRequest' - $ref: '#/components/schemas/TaskCreateAgentRequest' examples: Single task with a file: value: promptApplicationId: 95cec438-6080-44fe-8275-28b16bd40178 name: Invoice-2025-001.pdf rawInput: variables: document: file_url: https://example.com/invoice.pdf file_name: Invoice-2025-001.pdf mime_type: application/pdf webhook_url: https://example.com/webhook tags: - priority Batch: value: - promptApplicationId: 95cec438-6080-44fe-8275-28b16bd40178 name: Contract A rawInput: variables: document: file_url: https://example.com/a.pdf - promptApplicationId: 95cec438-6080-44fe-8275-28b16bd40178 name: Contract B rawInput: variables: document: file_url: https://example.com/b.pdf Pre-filled output (no execution): value: promptApplicationId: 95cec438-6080-44fe-8275-28b16bd40178 name: Imported row 12 rawInput: variables: customer: Acme Corporation outputContent: content: cliente: Acme Corporation valor: 150000 Agent batch: value: sourceType: agent agentId: 2f1c7c1e-6b7a-4e0e-9d5a-1b2c3d4e5f60 tasks: - name: Research Acme rawInput: variables: company: Acme Corporation tags: - research responses: '201': description: The created tasks (always an array, even for a single-object body) content: application/json: schema: type: array items: $ref: '#/components/schemas/Task' example: - id: 8b6d2c9a-1f4e-4c1b-9a1e-3c2d5e6f7a80 reference: 43 name: Invoice-2025-001.pdf status: running rawInput: application_id: 95cec438-6080-44fe-8275-28b16bd40178 variables: document: files: - file_url: https://example.com/invoice.pdf file_name: Invoice-2025-001.pdf mime_type: application/pdf webhook_url: https://example.com/webhook inputContent: null outputContent: null originalOutputContent: null createdBy: api@company.com approvedBy: null approvedAt: null completionRunId: b83b1558-de5b-4e45-b517-7bececbdd154 workflowRunId: null sourceType: prompt agentId: null agentRef: null agentSessionId: null promptVersionId: 76065caa-c519-441a-8fe2-cc43e29664ab promptApplicationId: 95cec438-6080-44fe-8275-28b16bd40178 workspaceId: 3f55cfd9-4427-4887-a181-d9ad39967802 metadata: null tags: - priority createdAt: '2025-01-15T10:30:00.000Z' updatedAt: '2025-01-15T10:30:00.000Z' deletedAt: null '400': description: >- Invalid payload (batch larger than 100, mixed `promptApplicationId` values, missing `promptApplicationId`, missing required variables, disallowed file MIME type) content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/Error' '402': description: Monthly usage limit reached (`QUOTA_EXCEEDED`) content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: App or agent not found / not accessible content: application/json: schema: $ref: '#/components/schemas/Error' security: - bearerAuth: [] components: schemas: TaskCreateRequest: type: object title: Workstation/App task properties: promptApplicationId: type: string format: uuid description: >- The Workstation/App to create the task in. Required by the server (400 when missing); all tasks in a batch must use the same value. name: type: string description: Display name of the task (typically the document file name). rawInput: $ref: '#/components/schemas/TaskRawInput' outputContent: type: object nullable: true description: >- Pre-filled output. When present the task is stored in `validating` status without executing the Canvas. properties: content: description: The extracted fields. required: - content inputContent: $ref: '#/components/schemas/TaskInputContent' metadata: $ref: '#/components/schemas/TaskMetadata' tags: type: array items: type: string required: - promptApplicationId - name TaskCreateAgentRequest: type: object title: Agent tasks properties: sourceType: type: string enum: - agent agentId: type: string format: uuid tasks: type: array maxItems: 100 items: type: object properties: name: type: string rawInput: type: object properties: variables: type: object additionalProperties: true required: - variables tags: type: array items: type: string required: - name required: - sourceType - agentId - tasks Task: type: object title: Task properties: id: type: string format: uuid reference: type: integer nullable: true description: >- Sequential number of the task within its app/agent. Assigned shortly after creation. name: type: string status: $ref: '#/components/schemas/TaskStatus' rawInput: $ref: '#/components/schemas/TaskRawInput' inputContent: $ref: '#/components/schemas/TaskInputContent' outputContent: type: object nullable: true additionalProperties: true description: >- Current output. For Canvas tasks this is the assistant message (`role`, `content`, …) where `content` holds the extracted fields; for workflow tasks it wraps `{ response, stepOutputs, error? }`. Reflects reviewer edits. originalOutputContent: type: object nullable: true additionalProperties: true description: >- Output as originally produced by the execution, before any reviewer edits. createdBy: type: string description: Email of the identity that created the task. approvedBy: type: string nullable: true approvedAt: type: string format: date-time nullable: true completionRunId: type: string format: uuid nullable: true workflowRunId: type: string format: uuid nullable: true sourceType: $ref: '#/components/schemas/TaskSourceType' agentId: type: string format: uuid nullable: true agentRef: type: string nullable: true description: Published agent identifier (agent tasks only). agentSessionId: type: string nullable: true promptVersionId: type: string format: uuid nullable: true description: >- Canvas version the task was executed with (Workstation/App tasks only). promptApplicationId: type: string format: uuid nullable: true workspaceId: type: string format: uuid metadata: $ref: '#/components/schemas/TaskMetadata' tags: type: array items: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time deletedAt: type: string format: date-time nullable: true inputFiles: type: array description: >- Only present on `GET /task` when `excludeInputOutputColumns=true` (and `excludeInputFiles` is not set). Summary of `inputContent.files` without parser payloads. items: type: object properties: name: type: string filename: type: string type: type: string url: type: string mimeType: type: string jobId: type: string pages: type: number usedAt: type: string enum: - variables - messages required: - id - name - status - createdBy - sourceType - workspaceId - tags - createdAt - updatedAt Error: {} TaskRawInput: type: object nullable: true title: Raw input description: >- The completion request the task is executed with. Same shape as the `/v2/chat/completions` body; `application_id` is set by the server from `promptApplicationId`. properties: application_id: type: string format: uuid description: >- Set by the server; any value you send is overwritten with `promptApplicationId`. canvas_id: type: string format: uuid version_id: type: string format: uuid environment_name: type: string variables: type: object description: >- Variables keyed by the app's variable names. Files are passed here (see `TaskVariableValue`). additionalProperties: $ref: '#/components/schemas/TaskVariableValue' messages: type: array items: $ref: '#/components/schemas/TaskMessage' input: type: string webhook_url: type: string description: URL that receives a POST when the execution finishes. override: $ref: '#/components/schemas/Override' stream: type: boolean async: type: boolean long_response: type: boolean label: type: string tags: type: array items: type: string TaskInputContent: type: object nullable: true title: Input content description: >- Normalized input of the execution. `null` until the run has been prepared. properties: variables: type: object additionalProperties: $ref: '#/components/schemas/TaskInternalVariableContent' messages: type: array items: $ref: '#/components/schemas/TaskMessage' files: type: array items: $ref: '#/components/schemas/TaskInputFile' TaskMetadata: type: object nullable: true title: Task metadata properties: resourceContext: $ref: '#/components/schemas/TaskResourceContext' editedFields: type: array description: >- Paths inside `outputContent.content` edited by reviewers via `PATCH /task/{id}`. items: type: object properties: path: type: string author: type: string editedAt: type: string format: date-time previousValue: {} required: - path - author - editedAt approvalRevokedBy: type: string approvalRevokedAt: type: string format: date-time sourceFile: type: object description: Provenance of tasks created from a spreadsheet/CSV import. properties: filename: type: string mimeType: type: string fileSize: type: number totalRows: type: number rowIndex: type: number uploadedAt: type: string format: date-time uploadedBy: type: string required: - filename TaskStatus: type: string description: >- Task lifecycle status. `created` (agent tasks awaiting execution) → `running` → `validating` (output ready, awaiting review) → `completed` (approved). `failed` and `cancelled` are terminal. enum: - created - running - validating - completed - failed - cancelled TaskSourceType: type: string description: >- Whether the task belongs to a Workstation/App (`prompt`) or to an agent (`agent`). enum: - prompt - agent TaskVariableValue: description: >- Value of a variable when creating a task. A string for text variables; a file object for a single file; `{ files: [...] }` for several files; `{ text, files }` for mixed content. oneOf: - type: string title: Text - $ref: '#/components/schemas/TaskVariableFile' - type: object title: Files properties: files: type: array items: $ref: '#/components/schemas/TaskVariableFile' required: - files - type: object title: Mixed properties: text: oneOf: - type: string - type: object additionalProperties: type: string files: type: array items: $ref: '#/components/schemas/TaskVariableFile' required: - text - files TaskMessage: type: object properties: role: type: string content: description: A string, a single content part, or an array of content parts. oneOf: - type: string - $ref: '#/components/schemas/TaskMessageContentPart' - type: array items: $ref: '#/components/schemas/TaskMessageContentPart' function_call: type: object properties: name: type: string arguments: type: string required: - name - arguments required: - role - content Override: type: object description: >- Override default settings specified in the canvas. This allows for fine-tuning the completion behavior for this specific request. properties: model: type: string description: >- The specific model to use for this completion. If not specified, the default model set in the canvas will be used. temperature: type: number description: >- Controls randomness in the output. Values between 0 and 1. Lower values make the output more focused and deterministic. type: type: string enum: - chat - completion description: Specifies whether to use a chat or completion model. functions: type: array items: type: object properties: id: type: string name: type: string description: type: string parameters: type: object properties: type: type: string enum: - object properties: type: object additionalProperties: true required: type: array items: type: string description: >- An array of functions that the model can call. This allows for more structured and interactive completions. structured_output: type: object properties: enabled: type: boolean description: Whether to enable structured output for this completion. schema: type: object properties: properties: type: object additionalProperties: true description: Defines the properties of the structured output type: type: string enum: - object description: >- The type of the schema, always "object" for structured output title: type: string description: The title of the schema description: type: string description: A description of the schema required: type: array items: type: string description: An array of required property names description: >- The schema defining the structure of the output. This is used when structured output is enabled. description: Configuration for generating structured output. required: - type TaskInternalVariableContent: description: >- Normalized variable value as stored on the task. A string, `{ files: [...] }`, or `{ text, files }` (a single file object is normalized into `files`). oneOf: - type: string - type: object properties: files: type: array items: $ref: '#/components/schemas/TaskVariableFile' required: - files - type: object properties: text: oneOf: - type: string - type: object additionalProperties: type: string files: type: array items: $ref: '#/components/schemas/TaskVariableFile' required: - text - files TaskInputFile: type: object description: >- A file that took part in the execution, either from a variable (`usedAt: variables`) or from a message (`usedAt: messages`). properties: name: type: string description: Variable name, or `message-{index}` for files found in messages. type: type: string usedAt: type: string enum: - variables - messages url: type: string mimeType: type: string jobId: type: string description: Parser job identifier, when the file was parsed. filename: type: string pages: type: number parserData: type: object additionalProperties: true description: Parser result payload (structure not documented here). filePagesAsImage: type: array items: type: string TaskResourceContext: type: object description: >- Set by the server on tasks that run against a resource shared from another workspace (federated). Client-supplied values are discarded. properties: isFederated: type: boolean entitlementId: type: string nullable: true executionWorkspaceId: type: string billingWorkspaceId: type: string resourceWorkspaceId: type: string credentialWorkspaceId: type: string projectId: type: string nullable: true TaskVariableFile: type: object title: File properties: file_url: type: string description: Publicly reachable URL or a `vault://` reference of the file. file_name: type: string mime_type: type: string vault_reference: type: string options: type: object properties: range: type: array description: Page range to process (e.g. for PDFs). items: type: number required: - file_url TaskMessageContentPart: oneOf: - type: object title: Text part properties: type: type: string enum: - text text: type: string required: - type - text - type: object title: Image part properties: type: type: string enum: - image_url image_url: type: object properties: url: type: string detail: type: string enum: - auto - high - low required: - url required: - type - image_url securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT or UUID ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.