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

# Promote or demote agents between lifecycle phases

> Set the listed agents' lifecycle phase: `production` to promote, `sandbox` to demote. Production unlocks the capabilities, secrets and API capabilities marked production-only plus the reserved credits; demotion pauses that access but keeps the agent's configuration. Agents already in the requested phase are reported as unchanged. Returns 400 when lifecycle phases are not enabled for the workspace. Batch write: each id gets its own result and per-id failures still return HTTP 200 — check `results[].success` and `summary`.



## OpenAPI

````yaml /api-reference/workspace-api.json post /workspaceapi/agents/phase
openapi: 3.1.0
info:
  title: Abundly Workspace API
  description: >-
    Workspace-level and per-agent data and administration. GET endpoints need a
    workspace API key (wk_) with the Workspace read API scope; POST endpoints
    need the Workspace write API scope. The write endpoints are batch operations
    mirroring the Workspace Manager capability: ids travel in the JSON body,
    each id gets its own result, and per-id failures still return HTTP 200.


    Private agents are listed by /workspaceapi/agents but return 403 on every
    per-agent GET, so enumerate from /workspaceapi/agents?includeOverview=true
    rather than iterating agent ids. Write endpoints can target private agents.
  version: 1.0.0
servers:
  - url: https://service.abundly.ai
    description: Shared platform
  - url: https://{tenant}.service.abundly.ai
    description: Dedicated deployment
    variables:
      tenant:
        default: your-tenant
security:
  - workspaceApiKey: []
paths:
  /workspaceapi/agents/phase:
    post:
      summary: Promote or demote agents between lifecycle phases
      description: >-
        Set the listed agents' lifecycle phase: `production` to promote,
        `sandbox` to demote. Production unlocks the capabilities, secrets and
        API capabilities marked production-only plus the reserved credits;
        demotion pauses that access but keeps the agent's configuration. Agents
        already in the requested phase are reported as unchanged. Returns 400
        when lifecycle phases are not enabled for the workspace. Batch write:
        each id gets its own result and per-id failures still return HTTP 200 —
        check `results[].success` and `summary`.
      operationId: post-agents-phase
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ids:
                  description: Agent IDs to update.
                  minItems: 1
                  type: array
                  items:
                    type: string
                phase:
                  description: '"production" to promote, "sandbox" to demote.'
                  type: string
                  enum:
                    - sandbox
                    - production
              required:
                - ids
                - phase
      responses:
        '200':
          description: Success. Empty result sets are also 200.
          content:
            application/json:
              schema:
                description: >-
                  Batch outcome. The request is 200 as long as it was
                  well-formed; check per-id `success` for failures.
                type: object
                properties:
                  results:
                    type: array
                    items:
                      description: Outcome for one id in the batch.
                      type: object
                      properties:
                        id:
                          description: The target entity id from the request.
                          type: string
                        name:
                          description: The target's name, when it could be resolved.
                          type: string
                        success:
                          type: boolean
                        unchanged:
                          description: >-
                            True when the write would not have changed anything
                            (or dryRun).
                          type: boolean
                        applied:
                          description: The stored values after the write.
                          type: object
                          propertyNames:
                            type: string
                          additionalProperties: {}
                        tags:
                          description: 'Tag endpoints: the final tag list.'
                          type: array
                          items:
                            type: string
                        impact:
                          description: >-
                            Team moves: who gains/loses access and which
                            capabilities flip.
                        error:
                          description: >-
                            Why this id failed. Per-id failures still return
                            HTTP 200.
                          type: string
                      required:
                        - id
                        - success
                      additionalProperties: {}
                  summary:
                    type: object
                    properties:
                      total:
                        type: number
                      succeeded:
                        type: number
                      failed:
                        type: number
                      unchanged:
                        type: number
                    required:
                      - total
                      - succeeded
                      - failed
                      - unchanged
                    additionalProperties: false
                required:
                  - results
                  - summary
                additionalProperties: false
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '403':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
components:
  responses:
    Error:
      description: >-
        Error. Every failure on this API returns JSON with a single `error`
        field.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                description: >-
                  Human-readable message. Every error on this API uses this
                  shape.
                type: string
            required:
              - error
            additionalProperties: false
  securitySchemes:
    workspaceApiKey:
      type: http
      scheme: bearer
      description: >-
        Workspace API key (wk_). GET endpoints require the Workspace read API
        scope, POST endpoints the Workspace write API scope.

````