> ## 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.

# List instruction versions

> The agent's instruction history, newest first, with who made each change, when, and the length of each version's text; the first entry is the live instructions. Pass `since` for the version in effect at that time plus every later one — enough to diff what changed after a given date, such as a promotion approval. Text is included with `includeContent=true`, or for a single version with `version`. Only the latest 100 superseded versions are kept. Returns 403 for a private agent.



## OpenAPI

````yaml /api-reference/workspace-api.json get /workspaceapi/agents/{agentId}/instruction-versions
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/{agentId}/instruction-versions:
    get:
      summary: List instruction versions
      description: >-
        The agent's instruction history, newest first, with who made each
        change, when, and the length of each version's text; the first entry is
        the live instructions. Pass `since` for the version in effect at that
        time plus every later one — enough to diff what changed after a given
        date, such as a promotion approval. Text is included with
        `includeContent=true`, or for a single version with `version`. Only the
        latest 100 superseded versions are kept. Returns 403 for a private
        agent.
      operationId: agents-agentId-instruction-versions
      parameters:
        - name: agentId
          in: path
          required: true
          description: The agent id.
          schema:
            type: string
        - name: since
          in: query
          required: false
          description: >-
            ISO date. Returns the version in effect at that time and every later
            one.
          schema:
            type: string
        - name: version
          in: query
          required: false
          description: Return only this version, with its text.
          schema:
            type: integer
            minimum: 1
        - name: includeContent
          in: query
          required: false
          description: Include each version's full text. Defaults to false.
          schema:
            type: boolean
      responses:
        '200':
          description: Success. Empty result sets are also 200.
          content:
            application/json:
              schema:
                description: >-
                  Newest first. Narrowed by `since` to the version in effect
                  then plus every later one.
                type: object
                properties:
                  agentId:
                    type: string
                  versions:
                    type: array
                    items:
                      type: object
                      properties:
                        version:
                          description: Increases by one per change.
                          type: number
                        isCurrent:
                          description: >-
                            True for the live instructions, always the first
                            entry.
                          type: boolean
                        changedAt:
                          description: >-
                            When this text was set. Absent on the oldest legacy
                            versions.
                          type: string
                        changedBy:
                          description: >-
                            Who made the change. Absent on versions older than
                            change tracking.
                          type: object
                          properties:
                            userId:
                              type: string
                            agentId:
                              description: >-
                                Set when an agent edited the instructions
                                itself.
                              type: string
                            name:
                              type: string
                          additionalProperties: {}
                        contentLength:
                          description: >-
                            Characters in this version's text, present even
                            without the content.
                          type: number
                        content:
                          description: Only with `includeContent=true` or `version`.
                          type: string
                      required:
                        - version
                        - isCurrent
                        - contentLength
                      additionalProperties: false
                required:
                  - agentId
                  - versions
                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.

````