> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryardent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Operations API

> Poll long-running Ardent work to completion

Some Ardent work takes longer than a single request: connector discovery, connector setup, resets, and environment operations. Those endpoints return an operation ID that you can poll.

Add `?wait=10` to long-poll: the server holds the request up to that many seconds (max 10) and answers early if the operation finishes. This cuts most polling loops to a single line.

Add `?wait=10` to long-poll: the server holds the request up to that many seconds (max 10) and answers early if the operation finishes. This cuts most polling loops to a single line.

Representative response:

```json theme={null}
{
  "id": "op_123",
  "org_id": "org_123",
  "type": "connector_engine_setup",
  "resource_id": "conn_123",
  "status": "running",
  "stage": "initializing",
  "stage_label": "Initializing",
  "progress": 35,
  "result": null,
  "error": null,
  "created_at": "2026-06-01T12:00:00Z",
  "updated_at": "2026-06-01T12:02:00Z"
}
```

`stage` is a machine token; `stage_label` is the human-readable version for progress displays.

## Status values

| Status      | Meaning                         |
| ----------- | ------------------------------- |
| `pending`   | The operation is queued         |
| `running`   | Work is in progress             |
| `completed` | Work finished successfully      |
| `failed`    | Work reached a terminal failure |

## Results

When an operation completes, `result` holds the outcome. For `branch_create` operations, `result` contains the full branch details, including `branch_url` — that's where automation picks up the connection string. See [Branches](/api/branches) for the shape.

## Polling loop

```bash theme={null}
while true; do
  json="$(curl -s -H "Authorization: Bearer $ARDENT_TOKEN"     "https://api.tryardent.com/v1/operations/$OPERATION_ID?wait=10")"
  status="$(node -e 'console.log(JSON.parse(process.argv[1]).status)' "$json")"

  case "$status" in
    completed) echo "$json"; break ;;
    failed) echo "$json" >&2; exit 1 ;;
    pending|running) : ;; # no sleep needed: ?wait=10 makes the server hold each poll
    *) echo "Unknown operation status: $status" >&2; exit 1 ;;
  esac
done
```

Poll with a bounded timeout in production automation. If an operation fails, read `error`, fix the cause, and start a new supported action rather than assuming the old operation will recover.


## OpenAPI

````yaml openapi.public.json GET /v1/operations/{operation_id}
openapi: 3.1.0
info:
  description: >-
    Public Ardent API. Generated by scripts/export_public_openapi.py — do not
    edit by hand.
  title: Ardent API
  version: v1
servers:
  - url: https://api.tryardent.com
security: []
paths:
  /v1/operations/{operation_id}:
    get:
      tags:
        - v1-operations
      summary: Get Operation Endpoint
      operationId: get_operation_endpoint_v1_operations__operation_id__get
      parameters:
        - in: path
          name: operation_id
          required: true
          schema:
            title: Operation Id
            type: string
        - description: >-
            Optionally wait up to this many seconds for a terminal operation
            state. Omit for the existing immediate poll response.
          in: query
          name: wait
          required: false
          schema:
            anyOf:
              - maximum: 10
                minimum: 0
                type: number
              - type: 'null'
            description: >-
              Optionally wait up to this many seconds for a terminal operation
              state. Omit for the existing immediate poll response.
            title: Wait
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncOperationResponse'
          description: >-
            Current operation state. On `completed`, `result` holds the outcome
            — for `branch_create`, the full branch details.
        '404':
          description: Operation not found (or not visible to the caller).
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
        - bearerAuth: []
components:
  schemas:
    AsyncOperationResponse:
      properties:
        completed_at:
          anyOf:
            - type: string
            - type: 'null'
          description: When the operation finished. Null until then.
          title: Completed At
        created_at:
          description: When the operation was created.
          title: Created At
          type: string
        error:
          anyOf:
            - type: string
            - type: 'null'
          description: Error message when the operation failed.
          title: Error
        id:
          description: Operation ID.
          title: Id
          type: string
        org_id:
          description: Organization the operation belongs to.
          title: Org Id
          type: string
        progress:
          anyOf:
            - maximum: 100
              minimum: 0
              type: integer
            - type: 'null'
          description: >-
            Best-effort completion percentage. Null when no estimate is
            available.
          title: Progress
        resource_id:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            ID of the resource the operation acts on (the branch ID for branch
            create).
          title: Resource Id
        result:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: >-
            Result payload on completion; for branch create, includes
            `branch_url`.
          title: Result
        setup_status:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: >-
            Connector setup progress detail. Present only for connector engine
            setup.
          title: Setup Status
        stage:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Raw progress token, kept for released CLIs. Read `stage_label`
            instead.
          title: Stage
        stage_label:
          anyOf:
            - type: string
            - type: 'null'
          description: Human-readable stage; null means the operation has not started yet.
          title: Stage Label
        started_at:
          anyOf:
            - type: string
            - type: 'null'
          description: When work started. Null until then.
          title: Started At
        status:
          $ref: '#/components/schemas/OperationStatus'
          description: Current status. `completed` and `failed` are terminal.
        type:
          $ref: '#/components/schemas/OperationType'
          description: The kind of work this operation tracks, for example `branch_create`.
        updated_at:
          description: When the operation was last updated.
          title: Updated At
          type: string
      required:
        - id
        - org_id
        - type
        - resource_id
        - status
        - created_at
        - updated_at
      title: AsyncOperationResponse
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    OperationStatus:
      enum:
        - pending
        - running
        - completed
        - failed
      title: OperationStatus
      type: string
    OperationType:
      enum:
        - connector_engine_setup
        - connector_reset
        - connector_deep_reset
        - connector_discovery
        - connector_delete
        - connector_secret_purge
        - connector_rollout
        - connector_replication_rollback
        - connector_debezium_cutover
        - connector_debezium_shadow_cleanup
        - environment_deploy
        - environment_destroy
        - branch_create
        - branch_delete
      title: OperationType
      type: string
    ValidationError:
      properties:
        ctx:
          title: Context
          type: object
        input:
          title: Input
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationError
      type: object
  securitySchemes:
    bearerAuth:
      description: >-
        Ardent API key (sk-ard_live_… / sk-ard_test_…) or a dashboard session
        token.
      scheme: bearer
      type: http

````