codai Tasks API

Outcome-billing task lifecycle. A task opens at the first task-start request of a session (or of an `x-codai-task-id`) and closes with an exec verdict, your explicit confirmation, or the 30-minute idle timeout. Only `pass` with machine evidence or `confirmed` with your confirmation is billed as one success. Every query is scoped to the user behind the key; there is no cross-user access.

GitHub OpenAPI

Operations 5

GET /v1/tasks List your tasks #
GET /v1/tasks/pending Tasks awaiting your confirmation #
GET /v1/tasks/stats Task counts since a timestamp #
GET /v1/tasks/{id} Get one task #
POST /v1/tasks/{id}/confirm Confirm or reject a task's outcome #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/codai-ro:codai-ro-tasks-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

codai-ro-tasks-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Codai Ro Tasks API
  version: '1'
  description: 'Operations tagged Tasks across 2 of this provider''s published API definitions: codai-ro-gateway-openapi.json, codai-ro-gateway-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://ai.codai.ro
  description: Production
security:
- bearerAuth: []
tags:
- name: Tasks
  description: 'Outcome-billing task lifecycle. A task opens at the first task-start request of a session (or of an

    `x-codai-task-id`) and closes with an exec verdict, your explicit confirmation, or the 30-minute idle timeout.

    Only `pass` with machine evidence or `confirmed` with your confirmation is billed as one success. Every query is

    scoped to the user behind the key; there is no cross-user access.'
paths:
  /v1/tasks:
    get:
      operationId: listTasks
      tags:
      - Tasks
      summary: List your tasks
      description: 'Returns the calling user''s tasks newest first (`opened_at` descending, then `id`). Filter by `outcome`, page

        with `limit` (default 50, max 200) and `cursor` — the `opened_at` of the last row of the previous page,

        exclusive; `next_cursor` is `null` on the last page. Requires a user-scoped key (401 otherwise) and counts

        against the per-key request limiter (`X-RateLimit-*` headers are set). Money fields are integer micros and

        are never converted.'
      parameters:
      - $ref: '#/components/parameters/RequestId'
      - name: outcome
        in: query
        required: false
        description: Only tasks with this outcome.
        schema:
          $ref: '#/components/schemas/TaskOutcome'
      - name: limit
        in: query
        required: false
        description: Page size.
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
      - name: cursor
        in: query
        required: false
        description: ISO 8601 timestamp with offset — the `next_cursor` of the previous page.
        schema:
          type: string
          format: date-time
          examples:
          - '2026-09-22T14:03:11.512Z'
      responses:
        '200':
          description: One page of tasks.
          content:
            application/json:
              schema:
                type: object
                required:
                - tasks
                - next_cursor
                properties:
                  tasks:
                    type: array
                    items:
                      $ref: '#/components/schemas/Task'
                  next_cursor:
                    type:
                    - string
                    - 'null'
                    format: date-time
                    description: Pass as `cursor` to fetch the next page; `null` when there is none.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
    servers:
    - url: https://ai.codai.ro
      description: Production
  /v1/tasks/pending:
    get:
      operationId: listPendingTasks
      tags:
      - Tasks
      summary: Tasks awaiting your confirmation
      description: 'Returns up to 100 tasks that need a "Did codai solve it?" answer, most recent activity first: tasks closed as

        `unconfirmed` whose confirmation window (24 h) is still open, plus `open` tasks on the `proxy`, `cli` and

        `mobile` surfaces with no activity for 30 minutes (they are about to be idle-closed). Confirm each one with

        `POST /v1/tasks/{id}/confirm`.'
      parameters:
      - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: Tasks pending confirmation.
          content:
            application/json:
              schema:
                type: object
                required:
                - tasks
                properties:
                  tasks:
                    type: array
                    maxItems: 100
                    items:
                      $ref: '#/components/schemas/Task'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
    servers:
    - url: https://ai.codai.ro
      description: Production
  /v1/tasks/stats:
    get:
      operationId: getTaskStats
      tags:
      - Tasks
      summary: Task counts since a timestamp
      description: 'Counts the calling user''s tasks opened at or after `since` (default: 30 days ago). `since` accepts anything

        `Date` can parse and is echoed back normalised to ISO 8601 UTC; an unparsable value is a 400. `billed` counts

        tasks whose `billed_success` flag is set, independent of outcome.'
      parameters:
      - $ref: '#/components/parameters/RequestId'
      - name: since
        in: query
        required: false
        description: Lower bound on `opened_at` (inclusive). Defaults to now minus 30 days.
        schema:
          type: string
          format: date-time
          examples:
          - '2026-09-01T00:00:00Z'
      responses:
        '200':
          description: Counts for the window.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskStats'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
    servers:
    - url: https://ai.codai.ro
      description: Production
  /v1/tasks/{id}:
    get:
      operationId: getTask
      tags:
      - Tasks
      summary: Get one task
      description: 'Returns a single task. A malformed id, an unknown id and a task belonging to another user are all reported

        as 404 — never 403 — so ids cannot be probed.'
      parameters:
      - $ref: '#/components/parameters/RequestId'
      - name: id
        in: path
        required: true
        description: Task UUID.
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The task.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
    servers:
    - url: https://ai.codai.ro
      description: Production
  /v1/tasks/{id}/confirm:
    post:
      operationId: confirmTask
      tags:
      - Tasks
      summary: Confirm or reject a task's outcome
      description: 'Answers "Did codai solve it?" for one of YOUR tasks. Ownership is checked against the user behind the calling

        key — there is no delegation or act-as header; another user''s task is a 403. The task must be `open`, or

        `unconfirmed` within its 24-hour confirmation window (`confirm_deadline_at`, falling back to `closed_at` /

        `last_activity_at` + 24 h); anything else is 409 `task_not_confirmable`. `outcome: confirmed` closes the task

        as `confirmed` / `user_confirmed` (billable) and runs settlement: `billed` says whether a `task_succeeded`

        meter event was emitted and `refundedMicroEur` how much token cost was returned to the prepaid wallet when it

        converted to a flat success charge. `outcome: fail` closes as `fail` / `user_confirmed` and is never billed.

        The request''s `x-request-id`, if any, is stored as `evidence_ref`. The response uses camelCase keys.'
      parameters:
      - $ref: '#/components/parameters/RequestId'
      - name: id
        in: path
        required: true
        description: Task UUID.
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskConfirmRequest'
      responses:
        '200':
          description: The task is closed with the chosen outcome.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskConfirmResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: The task is already closed with a final outcome, or its confirmation window has passed; `error.code` is `task_not_confirmable`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskNotConfirmableError'
        '429':
          $ref: '#/components/responses/RateLimited'
    servers:
    - url: https://ai.codai.ro
      description: Production
components:
  schemas:
    TaskConfirmRequest:
      type: object
      title: Confirm request
      description: Body of `POST /v1/tasks/{id}/confirm`.
      required:
      - outcome
      properties:
        outcome:
          type: string
          enum:
          - confirmed
          - fail
          description: '`confirmed` = codai solved it (billable); `fail` = it did not (never billed).'
        note:
          type: string
          maxLength: 500
          description: Optional free-text note (trimmed), stored on the task.
    TaskStats:
      type: object
      title: Task statistics
      description: Counts over tasks opened at or after `since`.
      required:
      - since
      - opened
      - confirmed
      - pass
      - unconfirmed
      - billed
      properties:
        since:
          type: string
          format: date-time
          description: The effective lower bound, normalised to ISO 8601 UTC.
        opened:
          type: integer
          minimum: 0
        confirmed:
          type: integer
          minimum: 0
        pass:
          type: integer
          minimum: 0
        unconfirmed:
          type: integer
          minimum: 0
        billed:
          type: integer
          minimum: 0
          description: Tasks with `billed_success` set.
    TaskOutcome:
      type: string
      description: 'Task outcome. `open` while running; `pass`/`fail`/`error` from an exec verdict; `unconfirmed` after the idle

        close; `confirmed` after your confirmation; `cancelled` when withdrawn.

        '
      enum:
      - pass
      - fail
      - error
      - unconfirmed
      - confirmed
      - cancelled
      - open
    TaskEvidenceKind:
      type: string
      description: What closed the task — a machine verdict, a re-execution, your confirmation, or nothing yet.
      enum:
      - exec_verdict
      - reexec
      - user_confirmed
      - none
    TaskSurface:
      type: string
      description: Client surface that opened the task.
      enum:
      - proxy
      - desktop
      - cli
      - resolve
      - sandbox
      - mobile
      - hub
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - message
          - type
          - code
          properties:
            message:
              type: string
              description: Human-readable, provider names redacted.
            type:
              type: string
              enum:
              - invalid_request_error
              - subscription_required
              - rate_limit_error
              - upstream_error
              - server_error
            code:
              type: string
              enum:
              - bad_request
              - invalid_api_key
              - subscription_inactive
              - forbidden
              - not_found
              - payload_too_large
              - rate_limit_exceeded
              - quota_exceeded
              - upstream_error
              - internal_error
              - not_a_member
              - lease_held
              - seq_conflict
              - host_offline
              - host_timeout
              - rules_refused
              - search_unavailable
              - task_not_confirmable
              - slug_taken
              - project_has_environments
              - already_has_env
              - not_enrollable
              - not_byo
              - invalid_transition
              - already_member
              - vm_per_dev_single_member
              - last_owner
              - insufficient_balance
              - key_scope_forbidden
              - assets_unavailable
              - asset_not_found
              - too_many_renders
              - renders_unavailable
              - timeline_too_long
              - not_a_timeline
              - invalid_cursor
              - templates_unavailable
              - url_blocked
              - invalid_tokens
              - unsupported_media
              - kind_mismatch
              - node_not_found
              - invalid_pick
              - duplicate_key
              - unknown_var
              - invalid_var_value
              - unsupported_kind
              - too_long
              - stale
              - not_supported_for_kind
              - unsupported_format
              - too_large
              - not_implemented
              - version_conflict
              - settings_unavailable
              - ai_label_required
              - sandbox_concurrency_limit
              - sandbox_busy
              - sandbox_daily_limit
              - invalid_ttl
              - workspace_too_large
              - sandbox_paused_limit
              - sandbox_capacity
            details:
              description: Present on `bad_request` (flattened Zod field errors), `invalid_tokens` (`issues`) and `rules_refused` (`tool`, `rule_id`, `decision`). Other codes never forward details over HTTP.
              type: object
              additionalProperties: true
      examples:
      - error:
          message: Invalid or missing API key.
          type: invalid_request_error
          code: invalid_api_key
    Task:
      type: object
      title: Task
      description: Wire view of a task. Money is integer micros (USD for cost, EUR for charges); dates are ISO 8601.
      required:
      - id
      - surface
      - session_key
      - client_task_id
      - title
      - outcome
      - evidence_kind
      - evidence_ref
      - requests
      - cost_micro_usd
      - charged_micro_eur
      - billed_success
      - billable_at
      - confirm_deadline_at
      - opened_at
      - last_activity_at
      - closed_at
      - note
      properties:
        id:
          type: string
          format: uuid
        surface:
          $ref: '#/components/schemas/TaskSurface'
        session_key:
          type:
          - string
          - 'null'
          description: Derived session key or the client `x-codai-task-id` that groups the task's requests.
        client_task_id:
          type:
          - string
          - 'null'
          description: Your `x-codai-task-id`, verbatim, when one was sent.
        title:
          type:
          - string
          - 'null'
          description: First user message, ≤ 200 chars.
        outcome:
          $ref: '#/components/schemas/TaskOutcome'
        evidence_kind:
          $ref: '#/components/schemas/TaskEvidenceKind'
        evidence_ref:
          type:
          - string
          - 'null'
          description: Verdict request id, resolve job id, usage event id, or the `x-request-id` of the confirm call.
        requests:
          type: integer
          minimum: 0
          description: Number of requests attributed to the task.
        cost_micro_usd:
          type: integer
          minimum: 0
          description: Real upstream cost in USD micros.
        charged_micro_eur:
          type: integer
          minimum: 0
          description: Token cost debited from the prepaid wallet so far, in EUR micros.
        billed_success:
          type: boolean
          description: True once the task was billed as one success (`task_succeeded` meter event).
        billable_at:
          type:
          - string
          - 'null'
          format: date-time
          description: When outcome and evidence first agreed on a billable success.
        confirm_deadline_at:
          type:
          - string
          - 'null'
          format: date-time
          description: Until when `POST /v1/tasks/{id}/confirm` still converts an `unconfirmed` task.
        opened_at:
          type: string
          format: date-time
        last_activity_at:
          type: string
          format: date-time
        closed_at:
          type:
          - string
          - 'null'
          format: date-time
        note:
          type:
          - string
          - 'null'
          description: Your note from the confirm call, when given.
    TaskNotConfirmableError:
      type: object
      title: Task not confirmable
      description: The task cannot be confirmed any more (HTTP 409).
      required:
      - error
      properties:
        error:
          type: object
          required:
          - message
          - type
          - code
          properties:
            message:
              type: string
              examples:
              - The confirmation window for this task has closed.
              - Task is already closed as "pass".
            type:
              type: string
              enum:
              - invalid_request_error
            code:
              type: string
              enum:
              - task_not_confirmable
    TaskConfirmResponse:
      type: object
      title: Confirm response
      description: Outcome of the confirmation. Keys are camelCase, unlike the `Task` object.
      required:
      - taskId
      - outcome
      - billed
      - refundedMicroEur
      properties:
        taskId:
          type: string
          format: uuid
        outcome:
          type: string
          enum:
          - confirmed
          - fail
          description: The outcome you sent.
        billed:
          type: boolean
          description: True when this confirmation emitted a `task_succeeded` meter event.
        refundedMicroEur:
          type: integer
          minimum: 0
          description: Token cost returned to the prepaid wallet on conversion to a flat success charge, in EUR micros.
  responses:
    Unauthorized:
      description: Missing, malformed, revoked or paused API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: The key is valid but not allowed to perform this action (model allow-list, role, ownership).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    PaymentRequired:
      description: The subscription behind this key is inactive.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: No such resource, or it belongs to another account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Per-key RPM/RPH, token-per-minute budget, spend cap (`rate_limit_exceeded`) or task quota (`quota_exceeded`). Read `Retry-After`.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
            minimum: 1
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Malformed body or query; `details` holds the flattened field errors.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    RequestId:
      name: x-request-id
      in: header
      required: false
      description: Client correlation id; echoed back as `x-codai-trace-id` and persisted on the usage row.
      schema:
        type: string
        maxLength: 128
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: codai_…
      description: A codai API key (`codai_` prefix). Ephemeral tokens from `POST /v1/tokens` are accepted only by the media surfaces matching their scope (`/v1/realtime`, `/v1/audio/*`, `/v1/embeddings`).
x-refined-from:
- codai-ro-gateway-openapi.json
- codai-ro-gateway-openapi.yml