Roark Agent Config API

openapi: 3.2.0
info:
  title: Roark Analytics Agent Config API
  description: The Roark Analytics API gives you access to the same API that powers the award winning Roark Analytics platform.
  version: 1.0.0
servers:
- description: Production
  url: https://api.roark.ai
security:
- Bearer: []
tags:
- name: Agent Config
paths:
  /v1/agent-config/{key}/resolve:
    post:
      responses:
        '200':
          description: The resolved config for this session.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ResolveManagedConfigResponse'
                required:
                - data
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Validation error
              example:
                type: validation
                code: invalid_parameter
                message: The request was invalid
                param: email
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Authentication error
              example:
                type: authentication
                code: unauthorized
                message: Authentication required
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Permission error
              example:
                type: forbidden
                code: permission_denied
                message: You do not have permission to access this resource
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Not found error
              example:
                type: not_found
                code: resource_not_found
                message: The requested resource could not be found
          description: Unknown key and no defaults were provided
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Rate limit error
              example:
                type: rate_limit
                code: too_many_requests
                message: Rate limit exceeded
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Server error
              example:
                type: internal
                code: internal_error
                message: Internal server error
          description: Internal Server Error
      operationId: postV1Agent-configByKeyResolve
      tags:
      - Agent Config
      summary: Resolve config for a session
      description: 'The call your agent makes at session start. Returns the config JSON for this session, with per-session simulation recognition built in: when the session was originated by a Roark simulation (matched by caller number against the calls Roark has in flight), the STAGING revision is served for that session only, so Autoimprove candidates are tested on your real deployment. Real traffic always resolves to production; any recognition miss degrades to production too.


        On the first fetch of an unknown key, pass `defaults` (your baked-in config): the key is registered and the defaults become revision 1. That makes integration a single call.


        Cache the response per session; do not fetch per turn.'
      parameters:
      - in: path
        name: key
        schema:
          type: string
          pattern: ^[A-Za-z0-9][A-Za-z0-9_.-]*$
          minLength: 1
          maxLength: 120
        required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResolveManagedConfigRequest'
  /v1/agent-config:
    get:
      responses:
        '200':
          description: The configs.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ManagedAgentConfig'
                required:
                - data
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Authentication error
              example:
                type: authentication
                code: unauthorized
                message: Authentication required
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Permission error
              example:
                type: forbidden
                code: permission_denied
                message: You do not have permission to access this resource
          description: Forbidden
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Rate limit error
              example:
                type: rate_limit
                code: too_many_requests
                message: Rate limit exceeded
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Server error
              example:
                type: internal
                code: internal_error
                message: Internal server error
          description: Internal Server Error
      operationId: getV1Agent-config
      tags:
      - Agent Config
      summary: List managed configs
      description: List the managed agent configs in this project, most recent first.
  /v1/agent-config/{key}:
    get:
      responses:
        '200':
          description: The config with recent revisions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ManagedAgentConfigDetail'
                required:
                - data
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Validation error
              example:
                type: validation
                code: invalid_parameter
                message: The request was invalid
                param: email
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Authentication error
              example:
                type: authentication
                code: unauthorized
                message: Authentication required
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Permission error
              example:
                type: forbidden
                code: permission_denied
                message: You do not have permission to access this resource
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Not found error
              example:
                type: not_found
                code: resource_not_found
                message: The requested resource could not be found
          description: Managed config not found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Rate limit error
              example:
                type: rate_limit
                code: too_many_requests
                message: Rate limit exceeded
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Server error
              example:
                type: internal
                code: internal_error
                message: Internal server error
          description: Internal Server Error
      operationId: getV1Agent-configByKey
      tags:
      - Agent Config
      summary: Get a managed config
      description: Fetch one managed config with its channel pointers and recent revisions, newest first.
      parameters:
      - in: path
        name: key
        schema:
          type: string
          pattern: ^[A-Za-z0-9][A-Za-z0-9_.-]*$
          minLength: 1
          maxLength: 120
        required: true
    put:
      responses:
        '200':
          description: The config with its updated channel pointers.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ManagedAgentConfig'
                required:
                - data
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Validation error
              example:
                type: validation
                code: invalid_parameter
                message: The request was invalid
                param: email
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Authentication error
              example:
                type: authentication
                code: unauthorized
                message: Authentication required
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Permission error
              example:
                type: forbidden
                code: permission_denied
                message: You do not have permission to access this resource
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Not found error
              example:
                type: not_found
                code: resource_not_found
                message: The requested resource could not be found
          description: Staging write on an unknown key
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Rate limit error
              example:
                type: rate_limit
                code: too_many_requests
                message: Rate limit exceeded
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Server error
              example:
                type: internal
                code: internal_error
                message: Internal server error
          description: Internal Server Error
      operationId: putV1Agent-configByKey
      tags:
      - Agent Config
      summary: Write a config revision
      description: Write a new revision onto a channel. Writing production creates the key when it does not exist; writing staging stages a candidate that only Roark-recognized simulation sessions will read. Every write is a new revision; nothing is overwritten.
      parameters:
      - in: path
        name: key
        schema:
          type: string
          pattern: ^[A-Za-z0-9][A-Za-z0-9_.-]*$
          minLength: 1
          maxLength: 120
        required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WriteManagedConfigRequest'
  /v1/agent-config/{key}/promote:
    post:
      responses:
        '200':
          description: The config with production now on the promoted revision.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ManagedAgentConfig'
                required:
                - data
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Validation error
              example:
                type: validation
                code: invalid_parameter
                message: The request was invalid
                param: email
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Authentication error
              example:
                type: authentication
                code: unauthorized
                message: Authentication required
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Permission error
              example:
                type: forbidden
                code: permission_denied
                message: You do not have permission to access this resource
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Not found error
              example:
                type: not_found
                code: resource_not_found
                message: The requested resource could not be found
          description: Managed config not found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Conflict error
              example:
                type: conflict
                code: resource_in_use
                message: The resource is in use and cannot be deleted
          description: No staging revision to promote
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Rate limit error
              example:
                type: rate_limit
                code: too_many_requests
                message: Rate limit exceeded
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Server error
              example:
                type: internal
                code: internal_error
                message: Internal server error
          description: Internal Server Error
      operationId: postV1Agent-configByKeyPromote
      tags:
      - Agent Config
      summary: Promote staging to production
      description: Point the production channel at the staging revision. Real traffic reads it from the next session onward; roll back by writing the prior revision id to production (the chain preserves every state).
      parameters:
      - in: path
        name: key
        schema:
          type: string
          pattern: ^[A-Za-z0-9][A-Za-z0-9_.-]*$
          minLength: 1
          maxLength: 120
        required: true
  /v1/agent-config/{key}/staging:
    delete:
      responses:
        '200':
          description: The config with staging cleared.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ManagedAgentConfig'
                required:
                - data
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Validation error
              example:
                type: validation
                code: invalid_parameter
                message: The request was invalid
                param: email
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Authentication error
              example:
                type: authentication
                code: unauthorized
                message: Authentication required
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Permission error
              example:
                type: forbidden
                code: permission_denied
                message: You do not have permission to access this resource
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Not found error
              example:
                type: not_found
                code: resource_not_found
                message: The requested resource could not be found
          description: Managed config not found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Rate limit error
              example:
                type: rate_limit
                code: too_many_requests
                message: Rate limit exceeded
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Server error
              example:
                type: internal
                code: internal_error
                message: Internal server error
          description: Internal Server Error
      operationId: deleteV1Agent-configByKeyStaging
      tags:
      - Agent Config
      summary: Discard the staging revision
      description: Clear the staging channel. Production is untouched; recognized simulation sessions go back to reading production.
      parameters:
      - in: path
        name: key
        schema:
          type: string
          pattern: ^[A-Za-z0-9][A-Za-z0-9_.-]*$
          minLength: 1
          maxLength: 120
        required: true
components:
  schemas:
    ResolveManagedConfigResponse:
      type: object
      properties:
        key:
          type: string
        channel:
          type: string
          enum:
          - production
          - staging
          description: Which channel this session resolved to.
        revisionId:
          type: string
          format: uuid
        document:
          type: object
          additionalProperties: {}
          description: The config JSON to apply.
        simulationJobId:
          type:
          - string
          - 'null'
          format: uuid
          description: Set when this session is a Roark simulation call. Stamp it (and the revisionId) into your session metadata so analysis attributes the call correctly.
      required:
      - key
      - channel
      - revisionId
      - document
      - simulationJobId
    ResolveManagedConfigRequest:
      type: object
      properties:
        defaults:
          type: object
          additionalProperties: {}
          description: Your baked-in config. On the first fetch of an unknown key this registers the config and becomes revision 1, so integration is a single call. Ignored once the key exists.
          example:
            systemPrompt: You are a helpful receptionist.
            model: gpt-4.1
            temperature: 0.4
        session:
          type: object
          properties:
            sessionId:
              type: string
              maxLength: 255
              description: Your session or room identifier, for correlation.
            callerNumber:
              type: string
              maxLength: 32
              description: The number calling your agent (E.164). Required for simulation recognition.
              example: '+15551230000'
            calledNumber:
              type: string
              maxLength: 32
              description: The number your agent was reached on (E.164).
              example: '+15559870000'
          description: Session context. When the call was originated by a Roark simulation, Roark recognizes it here and serves the staging revision for this session only; real traffic always gets production.
    ErrorResponse:
      type: object
      properties:
        type:
          type: string
          enum:
          - validation
          - authentication
          - forbidden
          - not_found
          - conflict
          - payment_required
          - rate_limit
          - internal
          description: The error type category
          examples:
          - validation
          - authentication
        code:
          type: string
          description: Machine-readable error code identifier
          examples:
          - invalid_parameter
          - missing_required_field
          - unauthorized
        message:
          type: string
          description: Human-readable error message
          examples:
          - The request was invalid
          - Authentication required
        param:
          type: string
          description: The parameter that caused the error (if applicable)
          examples:
          - email
          - user_id
        details:
          description: Additional error context information
      required:
      - type
      - code
      - message
    ManagedAgentConfigDetail:
      allOf:
      - $ref: '#/components/schemas/ManagedAgentConfig'
      properties:
        revisions:
          type: array
          items:
            $ref: '#/components/schemas/ManagedAgentConfigRevision'
          description: Recent revisions, newest first.
      required:
      - revisions
    ManagedAgentConfig:
      type: object
      properties:
        id:
          type: string
          format: uuid
        key:
          type: string
          description: The stable handle your code fetches by.
          example: support-agent
        agentId:
          type:
          - string
          - 'null'
          format: uuid
          description: The linked Roark agent, when one exists.
        productionRevisionId:
          type:
          - string
          - 'null'
          format: uuid
          description: The revision real traffic reads.
        stagingRevisionId:
          type:
          - string
          - 'null'
          format: uuid
          description: The candidate revision Roark test calls read. Null when nothing is staged.
        createdAt:
          type: string
          description: ISO 8601.
        updatedAt:
          type: string
          description: ISO 8601.
      required:
      - id
      - key
      - agentId
      - productionRevisionId
      - stagingRevisionId
      - createdAt
      - updatedAt
      description: 'A managed config for a code-first agent (LiveKit, Pipecat, or any stack using the SDK): your agent fetches its tunable surface from Roark at session start. Two channels: production for real traffic, staging for candidates under test.'
    WriteManagedConfigRequest:
      type: object
      properties:
        channel:
          type: string
          enum:
          - production
          - staging
          description: Which channel to write.
        document:
          type: object
          additionalProperties: {}
          description: The full config JSON for the new revision.
        summary:
          type: string
          maxLength: 500
          description: One-line story of the change.
        agentId:
          type: string
          format: uuid
          description: 'Link this config to a Roark agent (the one your calls report). Required before Autoimprove can run on it: the link is how a fix finds the config channel.'
      required:
      - channel
      - document
    ManagedAgentConfigRevision:
      type: object
      properties:
        id:
          type: string
          format: uuid
        document:
          type: object
          additionalProperties: {}
          description: The config JSON, verbatim.
        parentRevisionId:
          type:
          - string
          - 'null'
          format: uuid
        createdByType:
          type: string
          enum:
          - CUSTOMER
          - AUTOIMPROVE
          description: 'Who wrote it: your own pushes, or the Autoimprove loop staging a candidate.'
        summary:
          type:
          - string
          - 'null'
          description: One-line story of the change.
        createdAt:
          type: string
          description: ISO 8601.
      required:
      - id
      - document
      - parentRevisionId
      - createdByType
      - summary
      - createdAt
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT