> ## Documentation Index > Fetch the complete documentation index at: https://docs.runaether.dev/llms.txt > Use this file to discover all available pages before exploring further. # Create a task ## OpenAPI ````yaml api-reference/openapi.v1.json POST /tasks openapi: 3.1.0 info: title: Aether Public API version: 0.1.0 description: >- The versioned, public Aether REST API. Authenticate with an `aether_` platform API key or a session token. servers: - url: https://api.runaether.dev/v1 security: - bearerAuth: [] paths: /tasks: post: tags: - tasks summary: Create a task operationId: createTask requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateTaskRequest' required: true responses: '202': content: application/json: schema: $ref: '#/components/schemas/CreateTaskResponse' description: Accepted '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Bad Request '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Unauthorized '402': content: application/json: schema: $ref: '#/components/schemas/WorkspaceRuntimeAdmissionError' description: Payment Required '403': content: application/json: schema: anyOf: - oneOf: - $ref: '#/components/schemas/ErrorResponse' - $ref: '#/components/schemas/WorkspaceRuntimeAdmissionError' - $ref: '#/components/schemas/OrgAuthorizationErrorResponse' description: Forbidden '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Not Found '408': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Request Timeout '409': content: application/json: schema: anyOf: - $ref: '#/components/schemas/TaskIdempotencyKeyReusedErrorResponse' - $ref: '#/components/schemas/McpServerNotConnectedErrorResponse' description: Conflict '413': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Request Entity Too Large '422': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Unprocessable Entity '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal Server Error components: schemas: CreateTaskRequest: additionalProperties: false properties: agent_type: enum: - codex - claude-code - opencode - cursor type: string auto_fix_ci: description: >- Optional per-task override. Omit to inherit the fresh project default; explicit true or false overrides it. type: boolean auto_fix_pr_comments: description: >- Optional per-task override. Omit to inherit the fresh project default; explicit true or false overrides it. type: boolean auto_rebase: description: >- Optional per-task override. Omit to inherit the fresh project default; explicit true or false overrides it. type: boolean base_branch: minLength: 1 type: string context: $ref: '#/components/schemas/PromptContext' idempotency_key: description: >- Optional client-generated UUID, scoped to the authenticated user in the authenticated org. The first create with a key records it with the task; a retry with the same key and an equivalent request returns that same task (202, same body) without creating, admitting, or dispatching again, even if the task was since archived. Reusing a key for a different request fails with 409 code idempotency_key_reused and creates nothing. format: uuid type: string interaction_mode: enum: - default - plan type: string model: minLength: 1 type: string post_pr_demo_video: description: >- Optional per-task override. Omit to inherit the fresh project default; explicit true or false overrides it. type: boolean post_pr_screenshots: description: >- Optional per-task override. Omit to inherit the fresh project default; explicit true or false overrides it. type: boolean project_id: format: uuid type: string prompt: minLength: 1 type: string reasoning_effort: enum: - ultra - max - xhigh - high - medium - low - ultrathink - ultracode - none type: - string - 'null' vm_size: enum: - small - medium - large type: string required: - project_id - prompt - agent_type - model - interaction_mode type: object CreateTaskResponse: additionalProperties: false properties: id: format: uuid type: string name: minLength: 1 type: string required: - id - name type: object ErrorResponse: additionalProperties: false properties: code: type: string error: minLength: 1 type: string errors: items: $ref: '#/components/schemas/ErrorDetail' type: array required: - error type: object WorkspaceRuntimeAdmissionError: additionalProperties: false properties: code: type: string error: minLength: 1 type: string org_id: format: uuid type: string tier: type: string vm_size: type: string required: - error - code - tier - vm_size - org_id type: object OrgAuthorizationErrorResponse: additionalProperties: false properties: code: enum: - org_membership_required - org_role_insufficient - org_suspended - account_deleting type: string error: minLength: 1 type: string required: - error - code type: object TaskIdempotencyKeyReusedErrorResponse: additionalProperties: false properties: code: enum: - idempotency_key_reused type: string error: minLength: 1 type: string required: - error - code type: object McpServerNotConnectedErrorResponse: additionalProperties: false properties: code: enum: - mcp_server_not_connected type: string error: minLength: 1 type: string servers: items: $ref: '#/components/schemas/McpServerNotConnected' minItems: 1 type: array required: - error - code - servers type: object PromptContext: additionalProperties: false properties: attachments: items: $ref: '#/components/schemas/Attachment' maxItems: 10 type: array files: items: $ref: '#/components/schemas/FileReference' type: array type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object McpServerNotConnected: additionalProperties: false properties: display_name: type: string key: type: string policy: enum: - creator - org type: string reason: enum: - not_connected - needs_reauth type: string repo: $ref: '#/components/schemas/McpServerRepoDeclaration' required: - key - display_name - policy - reason type: object Attachment: additionalProperties: false properties: data: minLength: 1 type: string filename: minLength: 1 type: string mediaType: minLength: 1 type: string required: - filename - mediaType - data type: object FileReference: additionalProperties: false properties: include: type: boolean path: minLength: 1 type: string selection: $ref: '#/components/schemas/FileSelection' required: - path - include type: object McpServerRepoDeclaration: additionalProperties: false properties: cataloged: type: boolean file: enum: - .mcp.json - .codex/config.toml type: string required: - file - cataloged type: object FileSelection: additionalProperties: false properties: endLine: format: int64 minimum: 1 type: integer startLine: format: int64 minimum: 1 type: integer required: - startLine - endLine type: object securitySchemes: bearerAuth: bearerFormat: JWT scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.