> ## Documentation Index
> Fetch the complete documentation index at: https://oma-codex-339-workspace-permissions.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Acknowledge Work

> Acknowledge Work through the OMA API.

<Info>Every request requires `?beta=true`.</Info>


## OpenAPI

````yaml /openapi/oma.en.json post /v1/environments/{environment_id}/work/{work_id}/ack
openapi: 3.1.0
info:
  title: OMA API Reference
  version: 1.0.0
  description: Open Managed Agents application API reference.
servers:
  - url: http://localhost:38080
    description: Local OMA server
security:
  - omaApiKey: []
  - omaBearer: []
paths:
  /v1/environments/{environment_id}/work/{work_id}/ack:
    post:
      summary: Acknowledge Work
      description: >-
        Note: these endpoints are called automatically by the pre-built
        environment worker provided in the SDKs and CLI, for orchestrating
        sessions with self-hosted sandbox environments. They are included here
        as a reference; you do not need to invoke them directly.


        Acknowledge receipt of a work item, transitioning it from 'queued' to
        'starting' and removing it from the queue.
      operationId: >-
        beta_acknowledge_work_v1_environments__environment_id__work__work_id__ack_post
      parameters:
        - name: beta
          in: query
          required: true
          description: Selects the beta API contract for this endpoint. Must be `true`.
          schema:
            type: boolean
            enum:
              - true
        - name: environment_id
          in: path
          required: true
          schema:
            type: string
            title: Environment Id
          example: env_011CZkZ9X2dpNyB7HsEFoRfW
        - name: work_id
          in: path
          required: true
          schema:
            type: string
            title: Work Id
        - name: anthropic-beta
          in: header
          required: false
          schema:
            type: string
            items:
              type: string
            description: >-
              Optional header to specify the beta version(s) you want to use.


              To use multiple betas, use a comma separated list like
              `beta1,beta2` or specify the header multiple times for each beta.
            title: Anthropic-Beta
            x-stainless-override-schema:
              x-stainless-param: betas
              x-stainless-extend-default: true
              type: array
              description: Optional header to specify the beta version(s) you want to use.
              items:
                $ref: '#/components/schemas/AnthropicBeta'
            x-default: managed-agents-2026-04-01
          description: >-
            Optional header to specify the beta version(s) you want to use.


            To use multiple betas, use a comma separated list like `beta1,beta2`
            or specify the header multiple times for each beta.
        - name: anthropic-version
          in: header
          required: false
          schema:
            type: string
            description: |-
              The version of the OMA API you want to use.

              Read more about versioning and our version history here.
            title: Anthropic-Version
          description: |-
            The version of the OMA API you want to use.

            Read more about versioning and our version history here.
        - name: authorization
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaSelfHostedWork'
        4XX:
          description: |-
            Error response.

            See our errors documentation for more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
components:
  schemas:
    BetaSelfHostedWork:
      properties:
        acknowledged_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Acknowledged At
          description: >-
            RFC 3339 timestamp when the work item was acknowledged and assigned
            to a self-hosted sandbox
        created_at:
          type: string
          title: Created At
          description: RFC 3339 timestamp when work was created
        data:
          $ref: '#/components/schemas/BetaSessionWorkData'
          description: The actual work to be performed
        environment_id:
          type: string
          title: Environment Id
          description: Environment identifier this work belongs to (e.g., `env_...`)
        id:
          type: string
          title: Id
          description: Work identifier (e.g., 'work_...')
        latest_heartbeat_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Latest Heartbeat At
          description: RFC 3339 timestamp of the most recent heartbeat
        metadata:
          additionalProperties:
            type: string
          type: object
          title: Metadata
          description: >-
            User-provided metadata key-value pairs associated with this work
            item
        secret:
          anyOf:
            - type: string
            - type: 'null'
          title: Secret
          description: >-
            Credential payload used by the environment worker to execute this
            work item. May be populated when polling for work; null on all other
            retrieval paths.
        started_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Started At
          description: RFC 3339 timestamp when work execution started
        state:
          type: string
          enum:
            - queued
            - starting
            - active
            - stopping
            - stopped
          title: State
          description: Current state of the work item
        stop_requested_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Stop Requested At
          description: RFC 3339 timestamp when stop was requested
        stopped_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Stopped At
          description: RFC 3339 timestamp when work execution stopped
        type:
          type: string
          const: work
          title: Type
          description: The type of object (always 'work')
          default: work
      type: object
      required:
        - acknowledged_at
        - created_at
        - data
        - environment_id
        - id
        - latest_heartbeat_at
        - metadata
        - secret
        - started_at
        - state
        - stop_requested_at
        - stopped_at
        - type
      title: SelfHostedWork
      description: >-
        Work resource representing a unit of work in a self-hosted environment.


        Work items are queued when sessions are created or when long-dormant
        sessions

        receive new messages. The environment worker polls for work to execute
        in a

        self-hosted sandbox.
    BetaErrorResponse:
      properties:
        error:
          discriminator:
            mapping:
              api_error:
                $ref: '#/components/schemas/BetaAPIError'
              authentication_error:
                $ref: '#/components/schemas/BetaAuthenticationError'
              billing_error:
                $ref: '#/components/schemas/BetaBillingError'
              invalid_request_error:
                $ref: '#/components/schemas/BetaInvalidRequestError'
              not_found_error:
                $ref: '#/components/schemas/BetaNotFoundError'
              overloaded_error:
                $ref: '#/components/schemas/BetaOverloadedError'
              permission_error:
                $ref: '#/components/schemas/BetaPermissionError'
              rate_limit_error:
                $ref: '#/components/schemas/BetaRateLimitError'
              timeout_error:
                $ref: '#/components/schemas/BetaGatewayTimeoutError'
            propertyName: type
          oneOf:
            - $ref: '#/components/schemas/BetaInvalidRequestError'
            - $ref: '#/components/schemas/BetaAuthenticationError'
            - $ref: '#/components/schemas/BetaBillingError'
            - $ref: '#/components/schemas/BetaPermissionError'
            - $ref: '#/components/schemas/BetaNotFoundError'
            - $ref: '#/components/schemas/BetaRateLimitError'
            - $ref: '#/components/schemas/BetaGatewayTimeoutError'
            - $ref: '#/components/schemas/BetaAPIError'
            - $ref: '#/components/schemas/BetaOverloadedError'
          title: Error
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Request Id
        type:
          const: error
          default: error
          title: Type
          type: string
      required:
        - error
        - request_id
        - type
      title: ErrorResponse
      type: object
    BetaSessionWorkData:
      properties:
        id:
          type: string
          title: Id
          description: Session identifier (e.g., 'session_...')
        type:
          type: string
          const: session
          title: Type
          description: Type of work data
      type: object
      required:
        - id
        - type
      title: SessionWorkData
      description: >-
        Work data for session work items.


        This resource type is used when work represents a session that needs to
        be executed

        in a self-hosted environment.
    BetaAPIError:
      properties:
        message:
          default: Internal server error
          title: Message
          type: string
        type:
          const: api_error
          default: api_error
          title: Type
          type: string
      required:
        - message
        - type
      title: APIError
      type: object
    BetaAuthenticationError:
      properties:
        message:
          default: Authentication error
          title: Message
          type: string
        type:
          const: authentication_error
          default: authentication_error
          title: Type
          type: string
      required:
        - message
        - type
      title: AuthenticationError
      type: object
    BetaBillingError:
      properties:
        message:
          default: Billing error
          title: Message
          type: string
        type:
          const: billing_error
          default: billing_error
          title: Type
          type: string
      required:
        - message
        - type
      title: BillingError
      type: object
    BetaInvalidRequestError:
      properties:
        message:
          default: Invalid request
          title: Message
          type: string
        type:
          const: invalid_request_error
          default: invalid_request_error
          title: Type
          type: string
      required:
        - message
        - type
      title: InvalidRequestError
      type: object
    BetaNotFoundError:
      properties:
        message:
          default: Not found
          title: Message
          type: string
        type:
          const: not_found_error
          default: not_found_error
          title: Type
          type: string
      required:
        - message
        - type
      title: NotFoundError
      type: object
    BetaOverloadedError:
      properties:
        message:
          default: Overloaded
          title: Message
          type: string
        type:
          const: overloaded_error
          default: overloaded_error
          title: Type
          type: string
      required:
        - message
        - type
      title: OverloadedError
      type: object
    BetaPermissionError:
      properties:
        message:
          default: Permission denied
          title: Message
          type: string
        type:
          const: permission_error
          default: permission_error
          title: Type
          type: string
      required:
        - message
        - type
      title: PermissionError
      type: object
    BetaRateLimitError:
      properties:
        message:
          default: Rate limited
          title: Message
          type: string
        type:
          const: rate_limit_error
          default: rate_limit_error
          title: Type
          type: string
      required:
        - message
        - type
      title: RateLimitError
      type: object
    BetaGatewayTimeoutError:
      properties:
        message:
          default: Request timeout
          title: Message
          type: string
        type:
          const: timeout_error
          default: timeout_error
          title: Type
          type: string
      required:
        - message
        - type
      title: GatewayTimeoutError
      type: object
  securitySchemes:
    omaApiKey:
      type: apiKey
      in: header
      name: X-Api-Key
      description: OMA workspace API key.
      x-default: sk-ant-local-default
    omaBearer:
      type: http
      scheme: bearer
      description: OMA workspace API key sent as a bearer token.

````