openapi.yaml

openapi: 3.1.0
info:
  title: Fulcrum Core API
  description: A comprehensive cloud infrastructure management system designed to orchestrate and monitor distributed cloud resources across multiple providers.
  version: 1.0.0
  contact:
    name: Fulcrum Project
    url: https://fulcrumproject.org
  license:
    name: Apache License 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
  - url: https://api.fulcrum.testudosrl.dev/api/v1
    description: Development server
security:
  - BearerAuth: []
tags:
  - name: Participants
    description: Cloud service participant management
  - name: Agents
    description: Agent and agent type management
  - name: Infrastructure
    description: Infrastructure and infrastructure type management
  - name: Services
    description: Service, service type, service group management and service pools
  - name: Jobs
    description: Job queue and processing
  - name: Keycloak Users
    description: Keycloak user management
  - name: Metrics
    description: Metrics collection and management
  - name: Event
    description: Event logging
  - name: Tokens
    description: Authentication token management
  - name: Vault
    description: Secure secret storage and retrieval
paths:
  /agent-types:
    get:
      operationId: agentTypesList
      summary: List agent types
      tags:
        - Agents
      description: Retrieves a paginated list of agent types
      x-auth-permissions:
        - role: admin
          permission: all agent types
        - role: participant
          permission: all agent types
        - role: agent
          permission: all agent types
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 10
        - name: sort
          in: query
          schema:
            type: string
          description: 'Sort field. Prefix with ''+'' for ascending or ''-'' for descending. Default is ascending. Supported fields: name'
          example: +name
        - name: name
          in: query
          schema:
            type: array
            items:
              type: string
          description: Filter by agent type name (can specify multiple values)
      responses:
        '200':
          description: A paginated list of agent types
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PageRes'
                  - type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/AgentTypeRes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: agentTypesCreate
      summary: Create an agent type
      tags:
        - Agents
      description: Creates a new agent type with optional service types
      x-auth-permissions:
        - role: admin
          permission: all agent types
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentTypeReq'
      responses:
        '201':
          description: Agent type created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentTypeRes'
        '400':
          description: Invalid request body or validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '403':
          description: Administrator access required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '409':
          description: Agent type with same name already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
  /agent-types/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/properties.UUID'
    get:
      operationId: agentTypesGet
      summary: Get an agent type
      tags:
        - Agents
      description: Retrieves a specific agent type by ID
      x-auth-permissions:
        - role: admin
          permission: all agent types
        - role: participant
          permission: all agent types
        - role: agent
          permission: all agent types
      responses:
        '200':
          description: The agent type details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentTypeRes'
        '404':
          description: Agent type not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
    patch:
      operationId: agentTypesUpdate
      summary: Update an agent type
      tags:
        - Agents
      description: Partially updates an agent type (PATCH semantics)
      x-auth-permissions:
        - role: admin
          permission: all agent types
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAgentTypeReq'
      responses:
        '200':
          description: Agent type updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentTypeRes'
        '400':
          description: Invalid request body or validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '403':
          description: Administrator access required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '404':
          description: Agent type not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '409':
          description: Agent type with same name already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
    delete:
      operationId: agentTypesDelete
      summary: Delete an agent type
      tags:
        - Agents
      description: Deletes an agent type if no agents depend on it
      x-auth-permissions:
        - role: admin
          permission: all agent types
      responses:
        '204':
          description: Agent type deleted successfully
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '403':
          description: Administrator access required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '404':
          description: Agent type not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '409':
          description: Cannot delete agent type with dependent agents
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
  /infrastructure-types:
    get:
      operationId: infrastructureTypesList
      summary: List infrastructure types
      tags:
        - Infrastructure
      description: Retrieves a paginated list of infrastructure types
      x-auth-permissions:
        - role: admin
          permission: all infrastructure types
        - role: participant
          permission: all infrastructure types
        - role: agent
          permission: all infrastructure types
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 10
        - name: sort
          in: query
          schema:
            type: string
          description: 'Sort field. Prefix with ''+'' for ascending or ''-'' for descending. Default is ascending. Supported fields: name'
          example: +name
        - name: name
          in: query
          schema:
            type: array
            items:
              type: string
          description: Filter by infrastructure type name (can specify multiple values)
      responses:
        '200':
          description: A paginated list of infrastructure types
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PageRes'
                  - type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/InfrastructureTypeRes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: infrastructureTypesCreate
      summary: Create an infrastructure type
      tags:
        - Infrastructure
      description: Creates a new infrastructure type
      x-auth-permissions:
        - role: admin
          permission: all infrastructure types
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInfrastructureTypeReq'
      responses:
        '201':
          description: Infrastructure type created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InfrastructureTypeRes'
        '400':
          description: Invalid request body or validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '403':
          description: Administrator access required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '409':
          description: Infrastructure type with same name already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
  /infrastructure-types/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/properties.UUID'
    get:
      operationId: infrastructureTypesGet
      summary: Get an infrastructure type
      tags:
        - Infrastructure
      description: Retrieves a specific infrastructure type by ID
      x-auth-permissions:
        - role: admin
          permission: all infrastructure types
        - role: participant
          permission: all infrastructure types
        - role: agent
          permission: all infrastructure types
      responses:
        '200':
          description: The infrastructure type details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InfrastructureTypeRes'
        '404':
          description: Infrastructure type not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
    patch:
      operationId: infrastructureTypesUpdate
      summary: Update an infrastructure type
      tags:
        - Infrastructure
      description: Partially updates an infrastructure type (PATCH semantics)
      x-auth-permissions:
        - role: admin
          permission: all infrastructure types
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateInfrastructureTypeReq'
      responses:
        '200':
          description: Infrastructure type updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InfrastructureTypeRes'
        '400':
          description: Invalid request body or validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '403':
          description: Administrator access required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '404':
          description: Infrastructure type not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '409':
          description: Infrastructure type with same name already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
    delete:
      operationId: infrastructureTypesDelete
      summary: Delete an infrastructure type
      tags:
        - Infrastructure
      description: Deletes an infrastructure type
      x-auth-permissions:
        - role: admin
          permission: all infrastructure types
      responses:
        '204':
          description: Infrastructure type deleted successfully
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '403':
          description: Administrator access required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '404':
          description: Infrastructure type not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
  /infrastructures:
    get:
      operationId: infrastructuresList
      summary: List infrastructures
      tags:
        - Infrastructure
      description: Retrieves a paginated list of infrastructures
      x-auth-permissions:
        - role: admin
          permission: all infrastructures
        - role: participant
          permission: own infrastructures
        - role: agent
          permission: own infrastructure
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 10
        - name: sort
          in: query
          schema:
            type: string
          description: 'Sort field. Prefix with ''+'' for ascending or ''-'' for descending. Default is ascending. Supported fields: name'
          example: +name
        - name: name
          in: query
          schema:
            type: array
            items:
              type: string
          description: Filter by infrastructure name (can specify multiple values)
        - name: providerId
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/properties.UUID'
          description: Filter by provider participant ID
        - name: infrastructureTypeId
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/properties.UUID'
          description: Filter by infrastructure type ID
      responses:
        '200':
          description: A paginated list of infrastructures
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PageRes'
                  - type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/InfrastructureRes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: infrastructuresCreate
      summary: Create an infrastructure
      tags:
        - Infrastructure
      description: Creates a new infrastructure instance under the given provider and infrastructure type. Configuration is validated against the infrastructure type's configurationSchema.
      x-auth-permissions:
        - role: admin
          permission: all infrastructures
        - role: participant
          permission: own infrastructures
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInfrastructureReq'
      responses:
        '201':
          description: Infrastructure created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InfrastructureRes'
        '400':
          description: Invalid request body or configuration validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /infrastructures/me:
    get:
      operationId: infrastructuresGetCurrent
      summary: Get current infrastructure
      tags:
        - Infrastructure
      description: Retrieves the infrastructure referenced by the bootstrap-token identity. Used by the install flow once the install-token issuer for Infrastructure ships (Phase 3).
      security:
        - BearerAuth: []
      responses:
        '200':
          description: The infrastructure details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InfrastructureRes'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '404':
          description: Infrastructure not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
  /infrastructures/install/{token}/config:
    parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
        description: Per-resource install token issued by POST /infrastructures/{id}/install-command.
    get:
      operationId: infrastructuresFetchInstallConfig
      summary: Fetch rendered infrastructure install configuration
      tags:
        - Infrastructure
      description: |
        Returns the rendered configuration for a freshly deployed infrastructure.
        The caller must present BOTH:

        1. A bearer token with `admin`, `participant`, or `agent` role (standard
           API authentication).
        2. A valid install token embedded in the URL (the per-resource secret
           issued by POST `/infrastructures/{id}/install-command`).

        The response body is the rendered configuration — its media type matches
        the infrastructure type's `configContentType` (commonly `text/plain`,
        `application/yaml`, or `application/json`). Install tokens are
        short-lived (≈5 minutes) and single-use per install.

        Auth failures (missing or wrong-role bearer) return `401`/`403` from the
        standard auth middleware. Past that gate, every failure mode (unknown
        token, expired token, wrong-entity-type token, missing template, vault
        resolution failure, render error) collapses into a uniform `404` with
        the standard error envelope — the precise cause is only in the
        server-side log so callers cannot distinguish them.

        Cross-mount isolation: a token issued by the `/agents` mount is not
        accepted here, and vice versa. The two URL surfaces are strictly
        separated.
      x-auth-permissions:
        - role: admin
          permission: authorized with a valid install token
        - role: participant
          permission: authorized with a valid install token
        - role: agent
          permission: authorized with a valid install token
      responses:
        '200':
          description: Rendered infrastructure configuration. Media type is dynamic (matches the infrastructure type's `configContentType`).
          headers:
            Content-Type:
              schema:
                type: string
              description: Matches the infrastructure type's `configContentType`.
            Cache-Control:
              schema:
                type: string
                example: no-store
            X-Content-Type-Options:
              schema:
                type: string
                example: nosniff
          content:
            application/octet-stream:
              schema:
                type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: |
            Install token not found, expired, of the wrong entity type, or the
            infrastructure's configuration could not be rendered. Body is the
            standard error envelope — consult server logs for the real cause.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
  /infrastructures/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/properties.UUID'
    get:
      operationId: infrastructuresGet
      summary: Get an infrastructure
      tags:
        - Infrastructure
      description: Retrieves a specific infrastructure by ID
      x-auth-permissions:
        - role: admin
          permission: all infrastructures
        - role: participant
          permission: own infrastructures
        - role: agent
          permission: own infrastructure
      responses:
        '200':
          description: The infrastructure details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InfrastructureRes'
        '404':
          description: Infrastructure not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
    patch:
      operationId: infrastructuresUpdate
      summary: Update an infrastructure
      tags:
        - Infrastructure
      description: Partially updates an infrastructure (PATCH semantics). Configuration changes are validated against the infrastructure type's configurationSchema.
      x-auth-permissions:
        - role: admin
          permission: all infrastructures
        - role: participant
          permission: own infrastructures
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateInfrastructureReq'
      responses:
        '200':
          description: Infrastructure updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InfrastructureRes'
        '400':
          description: Invalid request body or configuration validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Infrastructure not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
    delete:
      operationId: infrastructuresDelete
      summary: Delete an infrastructure
      tags:
        - Infrastructure
      description: Deletes an infrastructure
      x-auth-permissions:
        - role: admin
          permission: all infrastructures
        - role: participant
          permission: own infrastructures
      responses:
        '204':
          description: Infrastructure deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Infrastructure not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
  /infrastructures/{id}/install-command:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/properties.UUID'
    get:
      operationId: infrastructuresGetInstallCommand
      summary: Get install-command metadata
      tags:
        - Infrastructure
      description: |
        Returns metadata about the current install token for the infrastructure
        (id, expiration, creation time). Never returns the plain token or
        rendered install URL — once the token leaves the Create/Regenerate
        response it cannot be recovered. Metadata is returned even when the
        token has expired so callers can disambiguate "no token yet"
        (404 → POST to create) from "token exists but expired"
        (200 with past `expiresAt` → POST to `/install-command/regenerate`).
      x-auth-permissions:
        - role: admin
          permission: all infrastructures
        - role: participant
          permission: infrastructures provided by its participant
        - role: agent
          permission: not authorized
      responses:
        '200':
          description: Install token metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstallTokenMetaRes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Infrastructure or install token not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
    post:
      operationId: infrastructuresCreateInstallCommand
      summary: Create install command
      tags:
        - Infrastructure
      description: |
        Issues a new install token for the infrastructure and returns the
        one-shot install command plus fetch URL. Install tokens are short-lived
        (≈5 minutes) and the plain token is rendered exactly once — the response
        is the only opportunity to capture it. If lost, use
        `/install-command/regenerate` to rotate.
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: infrastructures provided by its participant
        - role: agent
          permission: not authorized
      responses:
        '201':
          description: Install token created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstallTokenRes'
        '400':
          description: Invalid request (for example, the infrastructure type has no install templates configured)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Infrastructure not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
    delete:
      operationId: infrastructuresRevokeInstallCommand
      summary: Revoke install command
      tags:
        - Infrastructure
      description: Revokes the infrastructure's current install token. Subsequent fetch attempts on that token return 404.
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: infrastructures provided by its participant
        - role: agent
          permission: not authorized
      responses:
        '204':
          description: Install token revoked
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Infrastructure or install token not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
  /infrastructures/{id}/install-command/regenerate:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/properties.UUID'
    post:
      operationId: infrastructuresRegenerateInstallCommand
      summary: Regenerate install command
      tags:
        - Infrastructure
      description: |
        Rotates the infrastructure's install token. Invalidates any previously
        issued install token and returns a fresh install command plus fetch URL.
        As with Create, the plain token is rendered exactly once and cannot be
        recovered later.
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: infrastructures provided by its participant
        - role: agent
          permission: not authorized
      responses:
        '200':
          description: Install token regenerated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstallTokenRes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Infrastructure not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
  /agents:
    get:
      operationId: agentsList
      summary: List agents
      tags:
        - Agents
      description: Retrieves a paginated list of agents
      x-auth-permissions:
        - role: admin
          permission: all agents
        - role: participant
          permission: agents belonging to its participant
        - role: agent
          permission: itself only
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 10
        - name: sort
          in: query
          schema:
            type: string
          description: 'Sort field. Prefix with ''+'' for ascending or ''-'' for descending. Default is ascending. Supported fields: name'
          example: +name
        - name: name
          in: query
          schema:
            type: array
            items:
              type: string
          description: Filter by agent name (can specify multiple values)
        - name: status
          in: query
          schema:
            type: array
            items:
              type: string
              enum:
                - New
                - Connected
                - Disconnected
                - Error
                - Disabled
          description: Filter by agent status (can specify multiple values)
        - name: providerId
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/properties.UUID'
          description: Filter by provider ID (can specify multiple values)
        - name: agentTypeId
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/properties.UUID'
          description: Filter by agent type ID (can specify multiple values)
        - name: serviceTypeId
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/properties.UUID'
          description: Filter by service type ID - returns agents whose agent type provides any of the given service types (can specify multiple values)
      responses:
        '200':
          description: A paginated list of agents
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PageRes'
                  - type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/AgentRes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: agentsCreate
      summary: Create an agent
      tags:
        - Agents
      description: Creates a new agent and returns the agent data with an authentication token
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: for its participant (when acting as provider)
        - role: agent
          permission: not authorized
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentReq'
      responses:
        '201':
          description: Agent created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentCreateRes'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
  /agents/me:
    get:
      operationId: agentsGetCurrent
      summary: Get current agent
      tags:
        - Agents
      description: Retrieves information about the currently authenticated agent
      security:
        - BearerAuth: []
      responses:
        '200':
          description: The agent details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentRes'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
  /agents/me/status:
    put:
      operationId: agentsUpdateStatus
      summary: Update agent status
      tags:
        - Agents
      description: Updates the status of the authenticated agent
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - status
              properties:
                status:
                  $ref: '#/components/schemas/AgentStatus'
      responses:
        '200':
          description: Agent status updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentRes'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
  /agents/install/{token}/config:
    parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
        description: Per-resource install token issued by POST /agents/{id}/install-command.
    get:
      operationId: agentsFetchInstallConfig
      summary: Fetch rendered agent install configuration
      tags:
        - Agents
      description: |
        Returns the rendered agent configuration file for a freshly installed
        agent. The caller must present BOTH:

        1. A bearer token with `admin`, `participant`, or `agent` role (standard
           API authentication).
        2. A valid install token embedded in the URL (the per-resource secret
           issued by POST `/agents/{id}/install-command`).

        The response body is the rendered configuration — its media type matches
        the agent type's `configContentType` (commonly `text/plain`,
        `application/yaml`, or `application/json`). Install tokens are
        short-lived (≈5 minutes) and single-use per install.

        Auth failures (missing or wrong-role bearer) return `401`/`403` from the
        standard auth middleware. Past that gate, every failure mode (unknown
        token, expired token, missing template, vault resolution failure, render
        error) collapses into a uniform `404` with the standard error envelope —
        the precise cause is only in the server-side log so callers cannot
        distinguish them.
      x-auth-permissions:
        - role: admin
          permission: authorized with a valid install token
        - role: participant
          permission: authorized with a valid install token
        - role: agent
          permission: authorized with a valid install token
      responses:
        '200':
          description: Rendered agent configuration. Media type is dynamic (matches the agent type's `configContentType`).
          headers:
            Content-Type:
              schema:
                type: string
              description: Matches the agent type's `configContentType`.
            Cache-Control:
              schema:
                type: string
                example: no-store
            X-Content-Type-Options:
              schema:
                type: string
                example: nosniff
          content:
            application/octet-stream:
              schema:
                type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: |
            Install token not found, expired, or the agent's configuration could
            not be rendered. Body is the standard error envelope — consult server
            logs for the real cause.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
  /agents/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/properties.UUID'
    get:
      operationId: agentsGet
      summary: Get an agent
      tags:
        - Agents
      description: Retrieves a specific agent by ID
      x-auth-permissions:
        - role: admin
          permission: all agents
        - role: participant
          permission: agents belonging to its participant
        - role: agent
          permission: itself only
      responses:
        '200':
          description: The agent details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentRes'
        '404':
          description: Agent not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
    patch:
      operationId: agentsUpdate
      summary: Update an agent
      tags:
        - Agents
      description: Updates an existing agent
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: agents belonging to its participant
        - role: agent
          permission: update its own status only
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAgentReq'
      responses:
        '200':
          description: Agent updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentRes'
        '404':
          description: Agent not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
    delete:
      operationId: agentsDelete
      summary: Delete an agent
      tags:
        - Agents
      description: Deletes an agent by ID
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: agents belonging to its participant
        - role: agent
          permission: not authorized
      responses:
        '204':
          description: Agent deleted successfully
        '404':
          description: Agent not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
  /agents/{id}/install-command:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/properties.UUID'
    get:
      operationId: agentsGetInstallCommand
      summary: Get install-command metadata
      tags:
        - Agents
      description: |
        Returns metadata about the current install token for the agent
        (id, expiration, creation time). Never returns the plain token or
        rendered install URL — once the token leaves the Create/Regenerate
        response it cannot be recovered. Metadata is returned even when the
        token has expired so callers can disambiguate "no token yet"
        (404 → POST to create) from "token exists but expired"
        (200 with past `expiresAt` → POST to `/install-command/regenerate`).
      x-auth-permissions:
        - role: admin
          permission: all agents
        - role: participant
          permission: agents belonging to its participant
        - role: agent
          permission: not authorized
      responses:
        '200':
          description: Install token metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstallTokenMetaRes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Agent or install token not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
    post:
      operationId: agentsCreateInstallCommand
      summary: Create install command
      tags:
        - Agents
      description: |
        Issues a new install token for the agent and returns the one-shot
        install command plus fetch URL. Install tokens are short-lived
        (≈5 minutes) and the plain token is rendered exactly once — the
        response is the only opportunity to capture it. If lost, use
        `/install-command/regenerate` to rotate.
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: agents belonging to its participant
        - role: agent
          permission: not authorized
      responses:
        '201':
          description: Install token created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstallTokenRes'
        '400':
          description: Invalid request (for example, the agent type has no install templates configured)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Agent not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
    delete:
      operationId: agentsRevokeInstallCommand
      summary: Revoke install command
      tags:
        - Agents
      description: Revokes the agent's current install token. Subsequent fetch attempts on that token return 404.
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: agents belonging to its participant
        - role: agent
          permission: not authorized
      responses:
        '204':
          description: Install token revoked
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Agent or install token not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
  /agents/{id}/install-command/regenerate:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/properties.UUID'
    post:
      operationId: agentsRegenerateInstallCommand
      summary: Regenerate install command
      tags:
        - Agents
      description: |
        Rotates the agent's install token. Invalidates any previously issued
        install token and returns a fresh install command plus fetch URL. As
        with Create, the plain token is rendered exactly once and cannot be
        recovered later.
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: agents belonging to its participant
        - role: agent
          permission: not authorized
      responses:
        '200':
          description: Install token regenerated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstallTokenRes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Agent not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
  /config-pools:
    get:
      operationId: configPoolsList
      summary: List config pools
      tags:
        - Agents
      description: Retrieves a paginated list of config pools
      x-auth-permissions:
        - role: admin
          permission: all config pools
        - role: agent
          permission: all config pools (read-only)
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 10
        - name: sort
          in: query
          schema:
            type: string
          description: 'Sort field. Prefix with ''+'' for ascending or ''-'' for descending. Default is ascending. Supported fields: name, type, createdAt'
          example: +name
        - name: name
          in: query
          schema:
            type: array
            items:
              type: string
          description: Filter by name (case-insensitive substring match, can specify multiple values)
        - name: type
          in: query
          schema:
            type: array
            items:
              type: string
          description: Filter by pool type (can specify multiple values)
        - name: generatorType
          in: query
          schema:
            type: array
            items:
              type: string
              enum:
                - list
          description: Filter by generator type (can specify multiple values)
        - name: participantId
          in: query
          schema:
            type: array
            items:
              type: string
              format: uuid
          description: Filter by owning participant ID (can specify multiple values)
      responses:
        '200':
          description: A paginated list of config pools
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PageRes'
                  - type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/ConfigPoolRes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: configPoolsCreate
      summary: Create a config pool
      tags:
        - Agents
      description: Creates a new config pool
      x-auth-permissions:
        - role: admin
          permission: always
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateConfigPoolReq'
      responses:
        '201':
          description: Config pool created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigPoolRes'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
  /config-pools/{id}:
    get:
      operationId: configPoolsGet
      summary: Get an config pool by ID
      tags:
        - Agents
      description: Retrieves details of a specific config pool
      x-auth-permissions:
        - role: admin
          permission: always
        - role: agent
          permission: read-only
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/properties.UUID'
      responses:
        '200':
          description: Config pool retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigPoolRes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Config pool not found
    patch:
      operationId: configPoolsUpdate
      summary: Update an config pool
      tags:
        - Agents
      description: Updates an existing config pool
      x-auth-permissions:
        - role: admin
          permission: always
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/properties.UUID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateConfigPoolReq'
      responses:
        '200':
          description: Config pool updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigPoolRes'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Config pool not found
    delete:
      operationId: configPoolsDelete
      summary: Delete an config pool
      tags:
        - Agents
      description: Deletes an existing config pool
      x-auth-permissions:
        - role: admin
          permission: always
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/properties.UUID'
      responses:
        '204':
          description: Config pool deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Config pool not found
  /config-pool-values:
    get:
      operationId: configPoolValuesList
      summary: List config pool values
      tags:
        - Agents
      description: Retrieves a paginated list of config pool values
      x-auth-permissions:
        - role: admin
          permission: all config pool values
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 10
        - name: sort
          in: query
          schema:
            type: string
          description: 'Sort field. Prefix with ''+'' for ascending or ''-'' for descending. Default is ascending. Supported fields: name, createdAt'
          example: +name
        - name: name
          in: query
          schema:
            type: array
            items:
              type: string
          description: Filter by name (case-insensitive substring match, can specify multiple values)
        - name: configPoolId
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/properties.UUID'
          description: Filter by config pool ID (can specify multiple values)
        - name: agentId
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/properties.UUID'
          description: Filter by agent ID (can specify multiple values)
        - name: infrastructureId
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/properties.UUID'
          description: Filter by infrastructure ID (can specify multiple values)
      responses:
        '200':
          description: A paginated list of config pool values
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PageRes'
                  - type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/ConfigPoolValueRes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: configPoolValuesCreate
      summary: Create an config pool value
      tags:
        - Agents
      description: Creates a new config pool value
      x-auth-permissions:
        - role: admin
          permission: always
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateConfigPoolValueReq'
      responses:
        '201':
          description: Config pool value created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigPoolValueRes'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /config-pool-values/{id}:
    get:
      operationId: configPoolValuesGet
      summary: Get an config pool value by ID
      tags:
        - Agents
      description: Retrieves details of a specific config pool value
      x-auth-permissions:
        - role: admin
          permission: always
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/properties.UUID'
      responses:
        '200':
          description: Config pool value retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigPoolValueRes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Config pool value not found
    delete:
      operationId: configPoolValuesDelete
      summary: Delete an config pool value
      tags:
        - Agents
      description: Deletes an existing config pool value. Cannot delete a value that is currently allocated.
      x-auth-permissions:
        - role: admin
          permission: always
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/properties.UUID'
      responses:
        '204':
          description: Config pool value deleted successfully
        '400':
          description: Cannot delete allocated pool value
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Config pool value not found
  /events:
    get:
      operationId: eventsList
      summary: List events
      tags:
        - Event
      description: Retrieves a paginated list of events
      x-auth-permissions:
        - role: admin
          permission: all events
        - role: participant
          permission: events related to its participant
        - role: agent
          permission: not authorized
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 10
        - name: sort
          in: query
          schema:
            type: string
          description: 'Sort field. Prefix with ''+'' for ascending or ''-'' for descending. Default is ascending. Supported fields: createdAt, sequenceNumber'
          example: +createdAt
        - name: initiatorType
          in: query
          schema:
            type: array
            items:
              type: string
          description: Filter by initiator type (can specify multiple values)
        - name: initiatorId
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/properties.UUID'
          description: Filter by initiator ID (can specify multiple values)
        - name: type
          in: query
          schema:
            type: array
            items:
              type: string
          description: Filter by event type (can specify multiple values)
      responses:
        '200':
          description: A paginated list of events
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PageRes'
                  - type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/EventRes'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /events/ack:
    post:
      operationId: eventsAck
      summary: Acknowledge processed events
      tags:
        - Event
      description: Acknowledge processed events and update progress (Option B - does not renew lease)
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: not authorized
        - role: agent
          permission: not authorized
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventAckReq'
      responses:
        '200':
          description: Events acknowledged successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventAckRes'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: Acknowledgement conflict - lease not held or sequence regression
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /events/lease:
    post:
      operationId: eventsLease
      summary: Acquire event lease and fetch events
      tags:
        - Event
      description: Acquire or renew a lease for event processing and fetch events in chronological order
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: not authorized
        - role: agent
          permission: not authorized
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventLeaseReq'
      responses:
        '200':
          description: Lease acquired successfully with events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventLeaseRes'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: Lease conflict - held by another instance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /jobs:
    get:
      operationId: jobsList
      summary: List jobs
      tags:
        - Jobs
      description: Retrieves a paginated list of jobs (admin route)
      x-auth-permissions:
        - role: admin
          permission: all jobs
        - role: participant
          permission: jobs related to its participant (as provider via agents or as consumer via services)
        - role: agent
          permission: jobs assigned to the agent
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 10
        - name: sort
          in: query
          schema:
            type: string
          description: 'Sort field. Prefix with ''+'' for ascending or ''-'' for descending. Default is ascending. Supported fields: priority, createdAt, claimedAt, completedAt'
          example: +priority
        - name: action
          in: query
          schema:
            type: array
            items:
              type: string
          description: Filter by job action (can specify multiple values)
        - name: status
          in: query
          schema:
            type: array
            items:
              type: string
              enum:
                - Pending
                - Processing
                - Completed
                - Failed
          description: Filter by job status (can specify multiple values)
        - name: agentId
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/properties.UUID'
          description: Filter by agent ID (can specify multiple values)
        - name: serviceId
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/properties.UUID'
          description: Filter by service ID (can specify multiple values)
      responses:
        '200':
          description: A paginated list of jobs
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PageRes'
                  - type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/JobRes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /jobs/pending:
    get:
      operationId: jobsPending
      summary: Get pending jobs
      tags:
        - Jobs
      description: Retrieves a list of pending jobs for the authenticated agent
      security:
        - BearerAuth: []
      x-auth-permissions:
        - role: admin
          permission: not authorized
        - role: participant
          permission: not authorized
        - role: agent
          permission: pending jobs assigned to the agent
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
      responses:
        '200':
          description: List of pending jobs
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/JobRes'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
  /jobs/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/properties.UUID'
    get:
      operationId: jobsGet
      summary: Get a job
      tags:
        - Jobs
      description: Retrieves a specific job by ID (admin route)
      responses:
        '200':
          description: The job details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobRes'
        '404':
          description: Job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
  /jobs/{id}/claim:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/properties.UUID'
    post:
      operationId: jobsClaim
      summary: Claim a job
      tags:
        - Jobs
      description: Claims a job for processing by the authenticated agent
      security:
        - BearerAuth: []
      responses:
        '204':
          description: Job claimed successfully
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '404':
          description: Job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
  /jobs/{id}/complete:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/properties.UUID'
    post:
      operationId: jobsComplete
      summary: Complete a job
      tags:
        - Jobs
      description: Marks a job as completed with results
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompleteJobReq'
      responses:
        '204':
          description: Job completed successfully
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '404':
          description: Job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
  /jobs/{id}/fail:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/properties.UUID'
    post:
      operationId: jobsFail
      summary: Fail a job
      tags:
        - Jobs
      description: Marks a job as failed with an error message
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FailJobReq'
      responses:
        '204':
          description: Job marked as failed successfully
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '404':
          description: Job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
  /keycloak-users:
    get:
      operationId: keycloakUsersList
      summary: List keycloak users
      tags:
        - Keycloak Users
      description: Retrieves a paginated list of keycloak users
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: not authorized
        - role: agent
          permission: not authorized
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 10
        - name: email
          in: query
          schema:
            type: string
          description: Filter by email
        - name: firstName
          in: query
          schema:
            type: string
          description: Filter by first name
        - name: lastName
          in: query
          schema:
            type: string
          description: Filter by last name
      responses:
        '200':
          description: A paginated list of keycloak users
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PageRes'
                  - type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/KeycloakUserListItemRes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: keycloakUsersCreate
      summary: Create a keycloak user
      tags:
        - Keycloak Users
      description: Creates a new keycloak user with role assignment
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: not authorized
        - role: agent
          permission: not authorized
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateKeycloakUserReq'
      responses:
        '201':
          description: Keycloak user created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeycloakUserRes'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
  /keycloak-users/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: Keycloak user ID
    get:
      operationId: keycloakUsersGet
      summary: Get a keycloak user
      tags:
        - Keycloak Users
      description: Retrieves a specific keycloak user by ID
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: not authorized
        - role: agent
          permission: not authorized
      responses:
        '200':
          description: The keycloak user details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeycloakUserRes'
        '404':
          description: Keycloak user not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
    patch:
      operationId: keycloakUsersUpdate
      summary: Update a keycloak user
      tags:
        - Keycloak Users
      description: Updates an existing keycloak user
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: not authorized
        - role: agent
          permission: not authorized
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateKeycloakUserReq'
      responses:
        '200':
          description: Keycloak user updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeycloakUserRes'
        '404':
          description: Keycloak user not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
    delete:
      operationId: keycloakUsersDelete
      summary: Delete a keycloak user
      tags:
        - Keycloak Users
      description: Deletes a keycloak user by ID
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: not authorized
        - role: agent
          permission: not authorized
      responses:
        '204':
          description: Keycloak user deleted successfully
        '404':
          description: Keycloak user not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
  /metric-entries:
    get:
      operationId: metricEntriesList
      summary: List metric entries
      tags:
        - Metrics
      description: Retrieves a paginated list of metric entries
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 10
        - name: sort
          in: query
          schema:
            type: string
          description: 'Sort field. Prefix with ''+'' for ascending or ''-'' for descending. Default is ascending. Supported fields: createdAt, value'
          example: +createdAt
        - name: agentId
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/properties.UUID'
          description: Filter by agent ID (can specify multiple values)
        - name: serviceId
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/properties.UUID'
          description: Filter by service ID (can specify multiple values)
        - name: typeId
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/properties.UUID'
          description: Filter by metric type ID (can specify multiple values)
        - name: resourceId
          in: query
          schema:
            type: array
            items:
              type: string
          description: Filter by resource ID (case-insensitive substring match, can specify multiple values)
      responses:
        '200':
          description: A paginated list of metric entries
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PageRes'
                  - type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/MetricEntryRes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: metricEntriesCreate
      summary: Create a metric entry
      tags:
        - Metrics
      security:
        - BearerAuth: []
      description: Creates a new metric entry
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetricEntryReq'
      responses:
        '201':
          description: Metric entry created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricEntryRes'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
  /metric-entries/resource-ids:
    get:
      operationId: metricEntriesListResourceIDs
      summary: List distinct resource IDs
      tags:
        - Metrics
      description: Returns a paginated list of distinct resource IDs from metric entries, filtered by service, type, and agent
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 10
        - name: serviceId
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/properties.UUID'
          description: Filter by service ID (can specify multiple values)
        - name: typeId
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/properties.UUID'
          description: Filter by metric type ID (can specify multiple values)
        - name: agentId
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/properties.UUID'
          description: Filter by agent ID (can specify multiple values)
        - name: resourceId
          in: query
          schema:
            type: array
            items:
              type: string
          description: Filter by resource ID (case-insensitive substring match, can specify multiple values)
      responses:
        '200':
          description: A paginated list of distinct resource IDs
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PageRes'
                  - type: object
                    properties:
                      items:
                        type: array
                        items:
                          type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /metric-entries/aggregate/{serviceId}/{resourceId}/{typeId}:
    get:
      operationId: metricEntriesAggregate
      summary: Aggregate metric entries
      tags:
        - Metrics
      description: Returns time-bucketed aggregated metric values for a specific service, resource, and metric type
      parameters:
        - name: serviceId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/properties.UUID'
          description: ID of the service
        - name: resourceId
          in: path
          required: true
          schema:
            type: string
          description: Resource identifier
        - name: typeId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/properties.UUID'
          description: ID of the metric type
        - name: aggregateType
          in: query
          schema:
            type: string
            enum:
              - min
              - max
              - sum
              - avg
            default: min
          description: Aggregation function to apply
        - name: bucket
          in: query
          schema:
            type: string
            enum:
              - minute
              - hour
              - day
              - month
            default: hour
          description: Time bucket size for aggregation
        - name: start
          in: query
          schema:
            type: string
            format: date-time
          description: Start of the time range (defaults based on bucket size)
        - name: end
          in: query
          schema:
            type: string
            format: date-time
          description: End of the time range (defaults to now)
      responses:
        '200':
          description: Aggregated metric data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AggregationResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /metric-types:
    get:
      operationId: metricTypesList
      summary: List metric types
      tags:
        - Metrics
      description: Retrieves a paginated list of metric types
      x-auth-permissions:
        - role: admin
          permission: all metric types
        - role: participant
          permission: all metric types
        - role: agent
          permission: all metric types
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 10
        - name: sort
          in: query
          schema:
            type: string
          description: 'Sort field. Prefix with ''+'' for ascending or ''-'' for descending. Default is ascending. Supported fields: name, createdAt'
          example: +name
        - name: name
          in: query
          schema:
            type: array
            items:
              type: string
          description: Filter by name (case-insensitive contains, can specify multiple values)
      responses:
        '200':
          description: A paginated list of metric types
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PageRes'
                  - type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/MetricTypeRes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: metricTypesCreate
      summary: Create a metric type
      tags:
        - Metrics
      description: Creates a new metric type
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: not authorized
        - role: agent
          permission: not authorized
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetricTypeReq'
      responses:
        '201':
          description: Metric type created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricTypeRes'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
  /metric-types/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/properties.UUID'
    get:
      operationId: metricTypesGet
      summary: Get a metric type
      tags:
        - Metrics
      description: Retrieves a specific metric type by ID
      x-auth-permissions:
        - role: admin
          permission: all metric types
        - role: participant
          permission: all metric types
        - role: agent
          permission: all metric types
      responses:
        '200':
          description: The metric type details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricTypeRes'
        '404':
          description: Metric type not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
    patch:
      operationId: metricTypesUpdate
      summary: Update a metric type
      tags:
        - Metrics
      description: Updates an existing metric type
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: not authorized
        - role: agent
          permission: not authorized
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: cpu_usage_updated
      responses:
        '200':
          description: Metric type updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricTypeRes'
        '404':
          description: Metric type not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
    delete:
      operationId: metricTypesDelete
      summary: Delete a metric type
      tags:
        - Metrics
      description: Deletes a metric type by ID
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: not authorized
        - role: agent
          permission: not authorized
      responses:
        '204':
          description: Metric type deleted successfully
        '404':
          description: Metric type not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
  /participants:
    get:
      operationId: participantsList
      summary: List participants
      tags:
        - Participants
      description: Retrieves a paginated list of participants
      x-auth-permissions:
        - role: admin
          permission: all participants
        - role: participant
          permission: only its own participant
        - role: agent
          permission: only its associated participant
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 10
        - name: sort
          in: query
          schema:
            type: string
          description: 'Sort field. Prefix with ''+'' for ascending or ''-'' for descending. Default is ascending. Supported fields: name'
          example: +name
        - name: name
          in: query
          schema:
            type: array
            items:
              type: string
          description: Filter by participant name (can specify multiple values)
        - name: status
          in: query
          schema:
            type: array
            items:
              type: string
              enum:
                - Enabled
                - Disabled
          description: Filter by participant status (can specify multiple values)
      responses:
        '200':
          description: A paginated list of participants
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PageRes'
                  - type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/ParticipantRes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: participantsCreate
      summary: Create a participant
      tags:
        - Participants
      description: Creates a new participant
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: not authorized
        - role: agent
          permission: not authorized
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ParticipantReq'
      responses:
        '201':
          description: Participant created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParticipantRes'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
  /participants/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/properties.UUID'
    get:
      operationId: participantsGet
      summary: Get a participant
      tags:
        - Participants
      description: Retrieves a specific participant by ID
      x-auth-permissions:
        - role: admin
          permission: all participants
        - role: participant
          permission: its own participant
        - role: agent
          permission: its associated participant
      responses:
        '200':
          description: The participant details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParticipantRes'
        '404':
          description: Participant not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
    patch:
      operationId: participantsUpdate
      summary: Update a participant
      tags:
        - Participants
      description: Updates an existing participant
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: its own participant
        - role: agent
          permission: not authorized
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ParticipantReq'
      responses:
        '200':
          description: Participant updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParticipantRes'
        '404':
          description: Participant not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
    delete:
      operationId: participantsDelete
      summary: Delete a participant
      tags:
        - Participants
      description: Deletes a participant by ID
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: not authorized
        - role: agent
          permission: not authorized
      responses:
        '204':
          description: Participant deleted successfully
        '404':
          description: Participant not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
  /service-groups:
    get:
      operationId: serviceGroupsList
      summary: List service groups
      tags:
        - Services
      description: Retrieves a paginated list of service groups
      x-auth-permissions:
        - role: admin
          permission: all service groups
        - role: participant
          permission: service groups belonging to its participant
        - role: agent
          permission: not authorized
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 10
        - name: sort
          in: query
          schema:
            type: string
          description: 'Sort field. Prefix with ''+'' for ascending or ''-'' for descending. Default is ascending. Supported fields: name'
          example: +name
        - name: name
          in: query
          schema:
            type: array
            items:
              type: string
          description: Filter by service group name (can specify multiple values)
        - name: consumerId
          in: query
          schema:
            type: array
            items:
              type: string
              format: uuid
          description: Filter by consumer participant ID (can specify multiple values)
      responses:
        '200':
          description: A paginated list of service groups
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PageRes'
                  - type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/ServiceGroupRes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: serviceGroupsCreate
      summary: Create a service group
      tags:
        - Services
      description: Creates a new service group
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: for its participant
        - role: agent
          permission: not authorized
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateServiceGroupReq'
      responses:
        '201':
          description: Service group created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceGroupRes'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
  /service-groups/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/properties.UUID'
    get:
      operationId: serviceGroupsGet
      summary: Get a service group
      tags:
        - Services
      description: Retrieves a specific service group by ID
      x-auth-permissions:
        - role: admin
          permission: all service groups
        - role: participant
          permission: service groups belonging to its participant
        - role: agent
          permission: not authorized
      responses:
        '200':
          description: The service group details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceGroupRes'
        '404':
          description: Service group not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
    patch:
      operationId: serviceGroupsUpdate
      summary: Update a service group
      tags:
        - Services
      description: Updates an existing service group
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: service groups belonging to its participant
        - role: agent
          permission: not authorized
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateServiceGroupReq'
      responses:
        '200':
          description: Service group updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceGroupRes'
        '404':
          description: Service group not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
    delete:
      operationId: serviceGroupsDelete
      summary: Delete a service group
      tags:
        - Services
      description: Deletes a service group by ID
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: service groups belonging to its participant
        - role: agent
          permission: not authorized
      responses:
        '204':
          description: Service group deleted successfully
        '404':
          description: Service group not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
  /service-option-types:
    get:
      operationId: serviceOptionTypesList
      summary: List service option types
      tags:
        - Service Options
      description: Retrieves a paginated list of service option types
      x-auth-permissions:
        - role: admin
          permission: all service option types
        - role: participant
          permission: all service option types
        - role: agent
          permission: all service option types
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 10
        - name: sort
          in: query
          schema:
            type: string
          description: 'Sort field. Prefix with ''+'' for ascending or ''-'' for descending. Default is ascending. Supported fields: name, type, createdAt'
          example: +name
        - name: name
          in: query
          schema:
            type: array
            items:
              type: string
          description: Filter by name (case-insensitive contains, can specify multiple values)
        - name: type
          in: query
          schema:
            type: array
            items:
              type: string
          description: Filter by type (can specify multiple values)
      responses:
        '200':
          description: A paginated list of service option types
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PageRes'
                  - type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/ServiceOptionTypeRes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: serviceOptionTypesCreate
      summary: Create a service option type
      tags:
        - Service Options
      description: Creates a new service option type
      x-auth-permissions:
        - role: admin
          permission: always
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceOptionTypeReq'
      responses:
        '201':
          description: Service option type created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceOptionTypeRes'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /service-option-types/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/properties.UUID'
    get:
      operationId: serviceOptionTypesGet
      summary: Get a service option type
      tags:
        - Service Options
      description: Retrieves a specific service option type by ID
      x-auth-permissions:
        - role: admin
          permission: all service option types
        - role: participant
          permission: all service option types
        - role: agent
          permission: all service option types
      responses:
        '200':
          description: Service option type details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceOptionTypeRes'
        '404':
          description: Service option type not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
    patch:
      operationId: serviceOptionTypesUpdate
      summary: Update a service option type
      tags:
        - Service Options
      description: Updates an existing service option type
      x-auth-permissions:
        - role: admin
          permission: always
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateServiceOptionTypeReq'
      responses:
        '200':
          description: Service option type updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceOptionTypeRes'
        '404':
          description: Service option type not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
    delete:
      operationId: serviceOptionTypesDelete
      summary: Delete a service option type
      tags:
        - Service Options
      description: Deletes a service option type by ID
      x-auth-permissions:
        - role: admin
          permission: always
      responses:
        '204':
          description: Service option type deleted successfully
        '404':
          description: Service option type not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
  /service-options:
    get:
      operationId: serviceOptionsList
      summary: List service options
      tags:
        - Service Options
      description: Retrieves a paginated list of service options
      x-auth-permissions:
        - role: admin
          permission: all service options
        - role: participant
          permission: service options for its provider
        - role: agent
          permission: service options for its provider
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 10
        - name: sort
          in: query
          schema:
            type: string
          description: 'Sort field. Prefix with ''+'' for ascending or ''-'' for descending. Default is ascending. Supported fields: name, displayOrder'
          example: +name
        - name: name
          in: query
          schema:
            type: array
            items:
              type: string
          description: Filter by name (case-insensitive contains, can specify multiple values)
        - name: providerId
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/properties.UUID'
          description: Filter by provider ID (can specify multiple values)
        - name: serviceOptionTypeId
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/properties.UUID'
          description: Filter by service option type ID (can specify multiple values)
        - name: enabled
          in: query
          schema:
            type: array
            items:
              type: boolean
          description: Filter by enabled status (can specify multiple values)
      responses:
        '200':
          description: A paginated list of service options
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PageRes'
                  - type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/ServiceOptionRes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: serviceOptionsCreate
      summary: Create a service option
      tags:
        - Service Options
      description: Creates a new service option
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: for its participant as provider
        - role: agent
          permission: for its participant as provider
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceOptionReq'
      responses:
        '201':
          description: Service option created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceOptionRes'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /service-options/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/properties.UUID'
    get:
      operationId: serviceOptionsGet
      summary: Get a service option
      tags:
        - Service Options
      description: Retrieves a specific service option by ID
      x-auth-permissions:
        - role: admin
          permission: all service options
        - role: participant
          permission: service options for its provider
        - role: agent
          permission: service options for its provider
      responses:
        '200':
          description: Service option details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceOptionRes'
        '404':
          description: Service option not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
    patch:
      operationId: serviceOptionsUpdate
      summary: Update a service option
      tags:
        - Service Options
      description: Updates an existing service option
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: for its participant as provider
        - role: agent
          permission: for its participant as provider
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceOptionUpdateReq'
      responses:
        '200':
          description: Service option updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceOptionRes'
        '404':
          description: Service option not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
    delete:
      operationId: serviceOptionsDelete
      summary: Delete a service option
      tags:
        - Service Options
      description: Deletes a service option by ID
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: for its participant as provider
        - role: agent
          permission: for its participant as provider
      responses:
        '204':
          description: Service option deleted successfully
        '404':
          description: Service option not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
  /service-pool-sets:
    get:
      operationId: servicePoolSetsList
      summary: List service pool sets
      tags:
        - Services
      description: Retrieves a paginated list of service pool sets
      x-auth-permissions:
        - role: admin
          permission: all service pool sets
        - role: participant
          permission: service pool sets for its provider
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 10
        - name: sort
          in: query
          schema:
            type: string
          description: 'Sort field. Prefix with ''+'' for ascending or ''-'' for descending. Default is ascending. Supported fields: name, createdAt'
          example: +name
        - name: providerId
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/properties.UUID'
          description: Filter by provider ID (can specify multiple values)
        - name: name
          in: query
          schema:
            type: array
            items:
              type: string
          description: Filter by name (can specify multiple values)
      responses:
        '200':
          description: A paginated list of service pool sets
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PageRes'
                  - type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/ServicePoolSetRes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: servicePoolSetsCreate
      summary: Create a service pool set
      tags:
        - Services
      description: Creates a new service pool set
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: for its participant as provider
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateServicePoolSetReq'
      responses:
        '201':
          description: Service pool set created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServicePoolSetRes'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /service-pool-sets/{id}:
    get:
      operationId: servicePoolSetsGet
      summary: Get a service pool set by ID
      tags:
        - Services
      description: Retrieves details of a specific service pool set
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: if owned by participant as provider
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/properties.UUID'
      responses:
        '200':
          description: Service pool set retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServicePoolSetRes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Service pool set not found
    patch:
      operationId: servicePoolSetsUpdate
      summary: Update a service pool set
      tags:
        - Services
      description: Updates an existing service pool set
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: if owned by participant as provider
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/properties.UUID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateServicePoolSetReq'
      responses:
        '200':
          description: Service pool set updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServicePoolSetRes'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Service pool set not found
    delete:
      operationId: servicePoolSetsDelete
      summary: Delete a service pool set
      tags:
        - Services
      description: Deletes an existing service pool set
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: if owned by participant as provider
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/properties.UUID'
      responses:
        '204':
          description: Service pool set deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Service pool set not found
  /service-pools:
    get:
      operationId: servicePoolsList
      summary: List service pools
      tags:
        - Services
      description: Retrieves a paginated list of service pools
      x-auth-permissions:
        - role: admin
          permission: all service pools
        - role: participant
          permission: service pools for its provider
        - role: agent
          permission: service pools for its provider (read-only)
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 10
        - name: sort
          in: query
          schema:
            type: string
          description: 'Sort field. Prefix with ''+'' for ascending or ''-'' for descending. Default is ascending. Supported fields: name, type, createdAt'
          example: +name
        - name: name
          in: query
          schema:
            type: array
            items:
              type: string
          description: Filter by name (case-insensitive substring match, can specify multiple values)
        - name: servicePoolSetId
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/properties.UUID'
          description: Filter by service pool set ID (can specify multiple values)
        - name: type
          in: query
          schema:
            type: array
            items:
              type: string
          description: Filter by pool type (can specify multiple values)
        - name: generatorType
          in: query
          schema:
            type: array
            items:
              type: string
              enum:
                - list
                - subnet
          description: Filter by generator type (can specify multiple values)
      responses:
        '200':
          description: A paginated list of service pools
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PageRes'
                  - type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/ServicePoolRes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: servicePoolsCreate
      summary: Create a service pool
      tags:
        - Services
      description: Creates a new service pool
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: for its participant as provider
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateServicePoolReq'
      responses:
        '201':
          description: Service pool created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServicePoolRes'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
  /service-pools/{id}:
    get:
      operationId: servicePoolsGet
      summary: Get a service pool by ID
      tags:
        - Services
      description: Retrieves details of a specific service pool
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: if owned by participant as provider
        - role: agent
          permission: if owned by participant as provider (read-only)
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/properties.UUID'
      responses:
        '200':
          description: Service pool retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServicePoolRes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Service pool not found
    patch:
      operationId: servicePoolsUpdate
      summary: Update a service pool
      tags:
        - Services
      description: Updates an existing service pool
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: if owned by participant as provider
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/properties.UUID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateServicePoolReq'
      responses:
        '200':
          description: Service pool updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServicePoolRes'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Service pool not found
    delete:
      operationId: servicePoolsDelete
      summary: Delete a service pool
      tags:
        - Services
      description: Deletes an existing service pool
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: if owned by participant as provider
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/properties.UUID'
      responses:
        '204':
          description: Service pool deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Service pool not found
  /service-pool-values:
    get:
      operationId: servicePoolValuesList
      summary: List service pool values
      tags:
        - Services
      description: Retrieves a paginated list of service pool values with allocation status
      x-auth-permissions:
        - role: admin
          permission: all service pool values
        - role: participant
          permission: service pool values for its provider
        - role: agent
          permission: service pool values for its provider (read-only)
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 10
        - name: sort
          in: query
          schema:
            type: string
          description: 'Sort field. Prefix with ''+'' for ascending or ''-'' for descending. Default is ascending. Supported fields: name, createdAt'
          example: +name
        - name: name
          in: query
          schema:
            type: array
            items:
              type: string
          description: Filter by name (case-insensitive substring match, can specify multiple values)
        - name: servicePoolId
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/properties.UUID'
          description: Filter by service pool ID (can specify multiple values)
        - name: serviceId
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/properties.UUID'
          description: Filter by allocated service ID (can specify multiple values)
      responses:
        '200':
          description: A paginated list of service pool values
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PageRes'
                  - type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/ServicePoolValueRes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: servicePoolValuesCreate
      summary: Create a service pool value
      tags:
        - Services
      description: Creates a new service pool value (for list generators only)
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: for its participant as provider
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateServicePoolValueReq'
      responses:
        '201':
          description: Service pool value created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServicePoolValueRes'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /service-pool-values/{id}:
    get:
      operationId: servicePoolValuesGet
      summary: Get a service pool value by ID
      tags:
        - Services
      description: Retrieves details of a specific service pool value including allocation status
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: if owned by participant as provider
        - role: agent
          permission: if owned by participant as provider (read-only)
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/properties.UUID'
      responses:
        '200':
          description: Service pool value retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServicePoolValueRes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Service pool value not found
    delete:
      operationId: servicePoolValuesDelete
      summary: Delete a service pool value
      tags:
        - Services
      description: Deletes an existing service pool value (only if not allocated)
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: if owned by participant as provider
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/properties.UUID'
      responses:
        '204':
          description: Service pool value deleted successfully
        '400':
          description: Cannot delete allocated value
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Service pool value not found
  /service-types:
    get:
      operationId: serviceTypesList
      summary: List service types
      tags:
        - Services
      description: Retrieves a paginated list of service types
      x-auth-permissions:
        - role: admin
          permission: all service types
        - role: participant
          permission: all service types
        - role: agent
          permission: all service types
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 10
        - name: sort
          in: query
          schema:
            type: string
          description: 'Sort field. Prefix with ''+'' for ascending or ''-'' for descending. Default is ascending. Supported fields: name'
          example: +name
        - name: name
          in: query
          schema:
            type: array
            items:
              type: string
          description: Filter by service type name (can specify multiple values)
      responses:
        '200':
          description: A paginated list of service types
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PageRes'
                  - type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/ServiceTypeRes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: serviceTypesCreate
      summary: Create a service type
      tags:
        - Services
      description: Creates a new service type with optional property schema
      x-auth-permissions:
        - role: admin
          permission: all service types
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateServiceTypeReq'
      responses:
        '201':
          description: Service type created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceTypeRes'
        '400':
          description: Invalid request body or validation errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '403':
          description: Insufficient permissions (admin required)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '409':
          description: Service type with this name already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
  /service-types/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/properties.UUID'
    get:
      operationId: serviceTypesGet
      summary: Get a service type
      tags:
        - Services
      description: Retrieves a specific service type by ID
      x-auth-permissions:
        - role: admin
          permission: all service types
        - role: participant
          permission: all service types
        - role: agent
          permission: all service types
      responses:
        '200':
          description: The service type details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceTypeRes'
        '404':
          description: Service type not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
    patch:
      operationId: serviceTypesUpdate
      summary: Update a service type
      tags:
        - Services
      description: Partially updates a service type (PATCH semantics)
      x-auth-permissions:
        - role: admin
          permission: all service types
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateServiceTypeReq'
      responses:
        '200':
          description: Service type updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceTypeRes'
        '400':
          description: Invalid request body or validation errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '403':
          description: Insufficient permissions (admin required)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '404':
          description: Service type not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '409':
          description: Service type name already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
    delete:
      operationId: serviceTypesDelete
      summary: Delete a service type
      tags:
        - Services
      description: Deletes a service type if no services depend on it
      x-auth-permissions:
        - role: admin
          permission: all service types
      responses:
        '204':
          description: Service type deleted successfully
        '403':
          description: Insufficient permissions (admin required)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '404':
          description: Service type not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '409':
          description: Cannot delete service type with dependent services
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
  /services:
    get:
      operationId: servicesList
      summary: List services
      tags:
        - Services
      description: Retrieves a paginated list of services
      x-auth-permissions:
        - role: admin
          permission: all services
        - role: participant
          permission: services associated with its participant (as provider or consumer)
        - role: agent
          permission: services assigned to the agent
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 10
        - name: sort
          in: query
          schema:
            type: string
          description: 'Sort field. Prefix with ''+'' for ascending or ''-'' for descending. Default is ascending. Supported fields: name'
          example: +name
        - name: name
          in: query
          schema:
            type: array
            items:
              type: string
          description: Filter by service name (can specify multiple values)
        - name: currentStatus
          in: query
          schema:
            type: array
            items:
              type: string
          description: Filter by service status (can specify multiple values)
      responses:
        '200':
          description: A paginated list of services
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PageRes'
                  - type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/ServiceRes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: servicesCreate
      summary: Create a service
      tags:
        - Services
      description: Creates a new service
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: when acting as consumer
        - role: agent
          permission: not authorized
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceReq'
      responses:
        '201':
          description: Service created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceRes'
        '400':
          $ref: '#/components/responses/ValidationErrors'
  /services/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/properties.UUID'
    get:
      operationId: servicesGet
      summary: Get a service
      tags:
        - Services
      description: Retrieves a specific service by ID
      x-auth-permissions:
        - role: admin
          permission: all services
        - role: participant
          permission: services associated with its participant (as provider or consumer)
        - role: agent
          permission: services assigned to the agent
      responses:
        '200':
          description: The service details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceRes'
        '404':
          description: Service not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
    patch:
      operationId: servicesUpdate
      summary: Update a service
      tags:
        - Services
      description: |
        Updates an existing service using PATCH semantics. Only provided fields are updated.
        Properties are merged with existing properties for partial updates.
        **Property Merging Behavior:**
        - Only provided properties are updated
        - Existing properties not included in the request remain unchanged
        - Nested objects are deep merged (existing nested properties are preserved)
        - Properties are validated against the complete merged result
        **Examples:**
        - To update only the service name: `{"name": "new-name"}`
        - To update specific database config: `{"properties": {"database": {"port": 3306}}}`
        - To add new API config: `{"properties": {"api": {"version": "v2"}}}`
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: services where it is the consumer participant
        - role: agent
          permission: not authorized
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Service name. Only provided if updating the name.
                  example: web-server-01
                properties:
                  $ref: '#/components/schemas/JSONObject'
                  description: |
                    Service properties. These are merged with existing properties.
                    Only provided properties are updated. Nested objects are deep merged.
      responses:
        '200':
          description: Service updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceRes'
        '400':
          $ref: '#/components/responses/ValidationErrors'
        '404':
          description: Service not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
    delete:
      operationId: servicesDelete
      summary: Delete a service
      tags:
        - Services
      description: Deletes a service by ID
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: services where it is the consumer participant
        - role: agent
          permission: not authorized
      responses:
        '204':
          description: Service deleted successfully
        '404':
          description: Service not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
  /services/{id}/{action}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/properties.UUID'
      - name: action
        in: path
        required: true
        schema:
          type: string
        description: The lifecycle action to perform (e.g., start, stop, restart). Available actions are defined in the service type's lifecycle schema.
        example: start
    post:
      operationId: servicesAction
      summary: Perform a lifecycle action on a service
      tags:
        - Services
      description: |
        Performs a generic lifecycle action on a service. The action name is specified in the URL path
        and must be defined in the service type's lifecycle schema. 
        Common actions include: start, stop, restart, pause, resume, etc.
        Note: Use DELETE /services/{id} for delete actions and PATCH /services/{id} for update actions.
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: services where it is the consumer participant
        - role: agent
          permission: not authorized
      requestBody:
        required: false
        description: Optional properties for actions that require additional parameters (based on lifecycle schema requestSchemaType)
        content:
          application/json:
            schema:
              type: object
              properties:
                properties:
                  type: object
                  additionalProperties: true
                  description: Action-specific properties
      responses:
        '200':
          description: Service action initiated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceRes'
        '400':
          description: Invalid action or service state does not allow this action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '404':
          description: Service not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
  /tokens:
    get:
      operationId: tokensList
      summary: List tokens
      tags:
        - Tokens
      description: Retrieves a paginated list of tokens
      x-auth-permissions:
        - role: admin
          permission: all tokens
        - role: participant
          permission: tokens for its participant and associated agents
        - role: agent
          permission: not authorized
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 10
        - name: sort
          in: query
          schema:
            type: string
          description: 'Sort field. Prefix with ''+'' for ascending or ''-'' for descending. Default is ascending. Supported fields: name, expireAt, createdAt'
          example: +name
        - name: name
          in: query
          schema:
            type: array
            items:
              type: string
          description: Filter by token name (can specify multiple values)
        - name: role
          in: query
          schema:
            type: array
            items:
              type: string
              enum:
                - admin
                - participant
                - agent
          description: Filter by token role (can specify multiple values)
        - name: participantId
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/properties.UUID'
          description: Filter by participant ID (can specify multiple values)
        - name: agentId
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/properties.UUID'
          description: Filter by agent ID (can specify multiple values)
      responses:
        '200':
          description: A paginated list of tokens
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PageRes'
                  - type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/TokenRes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: tokensCreate
      summary: Create a token
      tags:
        - Tokens
      description: Creates a new authentication token. The plain token value is only returned in this response and cannot be retrieved later.
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: for itself and for its agents
        - role: agent
          permission: not authorized
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenReq'
      responses:
        '201':
          description: Token created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenRes'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /tokens/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/properties.UUID'
    get:
      operationId: tokensGet
      summary: Get a token
      tags:
        - Tokens
      description: Retrieves a specific token by ID. Note that the plain token value is not returned in this endpoint.
      x-auth-permissions:
        - role: admin
          permission: all tokens
        - role: participant
          permission: its own tokens and those of its agents
        - role: agent
          permission: not authorized
      responses:
        '200':
          description: The token details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenRes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Token not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
    patch:
      operationId: tokensUpdate
      summary: Update a token
      tags:
        - Tokens
      description: Updates an existing token
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: its own tokens and those of its agents
        - role: agent
          permission: not authorized
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: Updated Token Name
                expireAt:
                  type: string
                  format: date-time
                  example: '2025-12-31T23:59:59Z'
      responses:
        '200':
          description: Token updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenRes'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Token not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
    delete:
      operationId: tokensDelete
      summary: Delete a token
      tags:
        - Tokens
      description: Deletes a token by ID
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: its own tokens and those of its agents
        - role: agent
          permission: not authorized
      responses:
        '204':
          description: Token deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Token not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
  /tokens/{id}/regenerate:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/properties.UUID'
    post:
      operationId: tokensRegenerate
      summary: Regenerate token value
      tags:
        - Tokens
      description: Regenerates the value for an existing token. The new plain token value is returned in the response and cannot be retrieved later.
      x-auth-permissions:
        - role: admin
          permission: always
        - role: participant
          permission: its own tokens and those of its agents
        - role: agent
          permission: not authorized
      responses:
        '200':
          description: Token value regenerated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenRes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Token not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
  /vault/secrets/{reference}:
    get:
      tags:
        - Vault
      summary: Get secret value
      description: |
        Retrieves the actual value of a secret from the vault. This endpoint is only accessible to agents and allows them to resolve `vault://` references in service properties to retrieve the actual sensitive values.

        **Authorization**: Only agents can access this endpoint.

        **Use Case**: When an agent receives a service configuration with properties containing `vault://abc123` references, it calls this endpoint to retrieve the actual secret values needed for provisioning or managing the service.
      operationId: getSecret
      parameters:
        - name: reference
          in: path
          required: true
          description: The vault reference identifier (without the `vault://` prefix)
          schema:
            type: string
            example: abc123def456
      responses:
        '200':
          description: Secret value retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - value
                properties:
                  value:
                    description: The actual secret value (can be any JSON type - string, number, object, array, boolean, null)
                    example: my-secret-password
              examples:
                stringSecret:
                  summary: String secret (API key)
                  value:
                    value: sk_live_abc123xyz789
                objectSecret:
                  summary: Object secret (credentials)
                  value:
                    value:
                      username: admin
                      password: secret123
                numberSecret:
                  summary: Number secret
                  value:
                    value: 12345
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Forbidden - only agents can access vault secrets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
        '404':
          description: Secret not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
              example:
                status: 404
                message: Secret with reference 'abc123' not found
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  securitySchemes:
    BearerAuth:
      type: oauth2
      description: Role-based authentication using bearer tokens
      flows:
        implicit:
          authorizationUrl: https://api.fulcrum.testudosrl.dev/oauth/authorize
          scopes:
            admin: System administrator with unrestricted access
            participant: Participant administrator that can act as both provider and consumer
            agent: Agent role with access to specific operations
  schemas:
    AgentCreateRes:
      allOf:
        - $ref: '#/components/schemas/AgentRes'
        - type: object
          properties:
            token:
              $ref: '#/components/schemas/TokenRes'
              description: The agent authentication token
    AgentRes:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/properties.UUID'
        name:
          type: string
          example: aws-agent-01
        status:
          $ref: '#/components/schemas/AgentStatus'
        providerId:
          $ref: '#/components/schemas/properties.UUID'
        agentTypeId:
          $ref: '#/components/schemas/properties.UUID'
        configuration:
          $ref: '#/components/schemas/JSONObject'
          description: Agent-specific configuration parameters
          example:
            timeout: 30
            retries: 3
            environment: production
        servicePoolSetId:
          $ref: '#/components/schemas/properties.UUID'
          description: Optional service pool set for automatic resource allocation
        infrastructureId:
          $ref: '#/components/schemas/properties.UUID'
          description: Infrastructure this agent runs on (resolved at create time when the agent type requires it)
        participant:
          $ref: '#/components/schemas/ParticipantRes'
        agentType:
          $ref: '#/components/schemas/AgentTypeRes'
        infrastructure:
          $ref: '#/components/schemas/InfrastructureRes'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    AgentStatus:
      type: string
      enum:
        - New
        - Connected
        - Disconnected
        - Error
        - Disabled
    ConfigPoolRes:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/properties.UUID'
        name:
          type: string
          example: Public IP Pool
        type:
          type: string
          example: public_ip
        propertyType:
          type: string
          enum:
            - string
            - integer
            - number
            - boolean
            - json
          example: string
          description: Property type that this pool provides
        generatorType:
          type: string
          enum:
            - list
            - range
            - subnet
          example: list
        generatorConfig:
          type: object
          example:
            cidr: 192.168.1.0/24
        participantId:
          $ref: '#/components/schemas/properties.UUID'
          description: Owning participant (null = global pool managed by admin)
        participant:
          $ref: '#/components/schemas/ParticipantRes'
          description: Owning participant (omitted when this is a global pool)
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ConfigPoolValueRes:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/properties.UUID'
        name:
          type: string
          example: 192.168.1.10
        value:
          description: Any JSON value (string, number, object, array)
          example: 192.168.1.10
        configPoolId:
          $ref: '#/components/schemas/properties.UUID'
        configPool:
          $ref: '#/components/schemas/ConfigPoolRes'
          description: The config pool this value belongs to
        agentId:
          $ref: '#/components/schemas/properties.UUID'
          description: Agent this value is allocated to (set only for agent-owned values)
        agent:
          $ref: '#/components/schemas/AgentRes'
          description: The agent this value is allocated to (only present if allocated to an agent)
        infrastructureId:
          $ref: '#/components/schemas/properties.UUID'
          description: Infrastructure this value is allocated to (set only for infrastructure-owned values)
        infrastructure:
          $ref: '#/components/schemas/InfrastructureRes'
          description: The infrastructure this value is allocated to (only present if allocated to an infrastructure)
        propertyName:
          type: string
          example: ipAddress
          description: Property name this value is allocated to
        allocatedAt:
          type: string
          format: date-time
          description: When this value was allocated
        releasedAt:
          type: string
          format: date-time
          description: When this value was last released back to the pool (omitted while allocated). Combined with the pool's retentionSeconds to gate reuse of range/subnet values.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    AgentTypeRes:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/properties.UUID'
        name:
          type: string
          example: Participant VM Agent
        serviceTypeIds:
          type: array
          items:
            $ref: '#/components/schemas/properties.UUID'
          description: IDs of service types that this agent type can provide
        infrastructureTypeIds:
          type: array
          maxItems: 1
          items:
            $ref: '#/components/schemas/properties.UUID'
          description: IDs of infrastructure types this agent type requires (currently at most one)
        configurationSchema:
          $ref: '#/components/schemas/ConfigurationSchema'
          description: Schema defining the structure and validation rules for agent configuration
        configTemplate:
          type: string
          description: Go text/template rendered at install time to produce the agent config file. Placeholder refs (e.g. {{.host}}) must be keys of configurationSchema.properties.
          example: |-
            host={{.host}}
            port={{.port}}
        cmdTemplate:
          type: string
          description: Go text/template rendered at install time to produce the agent install command. Placeholder refs must be keys of configurationSchema.properties or the special {{.configUrl}}.
          example: agent install --config {{.configUrl}}
        configContentType:
          type: string
          description: Media type (RFC 6838) of the rendered configTemplate output. Defaults to text/plain.
          default: text/plain
          example: application/yaml
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    AuthRole:
      type: string
      enum:
        - admin
        - participant
        - agent
      description: Access role for the token
    CompleteJobReq:
      type: object
      properties:
        agentInstanceId:
          type: string
          description: Agent's native instance identifier for the provisioned resource
          example: i-1234567890abcdef0
        agentInstanceData:
          $ref: '#/components/schemas/JSONObject'
          description: Agent-owned runtime data about the provisioned service
        properties:
          type: object
          additionalProperties: true
          description: Agent-discovered property values to update on the service (only properties with actor authorizer allowing "agent")
          example:
            ipAddress: 192.168.1.100
            port: 8080
    CreateConfigPoolReq:
      type: object
      required:
        - name
        - type
        - propertyType
        - generatorType
      properties:
        name:
          type: string
          example: Public IP Pool
          description: Name of the config pool
        type:
          type: string
          example: public_ip
          description: Type identifier for the pool
        propertyType:
          type: string
          enum:
            - string
            - integer
            - number
            - boolean
            - json
          example: string
          description: Property type that this pool provides
        generatorType:
          type: string
          enum:
            - list
            - range
            - subnet
          example: list
          description: 'Allocation strategy: ''list'' for pre-configured values, ''range'' for an integer range, ''subnet'' for CIDR-derived values'
        generatorConfig:
          type: object
          description: 'Generator-specific configuration. Required for ''range'' (min/max, optional exclude) and ''subnet'' (cidr, optional prefix/hosts/excludeFirst/excludeLast/exclude). For ''range'' and ''subnet'' an optional integer ''retentionSeconds'' sets a reuse cooldown: a released value is re-allocatable only after that many seconds (omitted or 0 = reuse immediately). An optional boolean ''neverReallocate'' (default false): when true a released value is never re-allocated, taking precedence over ''retentionSeconds''.'
          example:
            cidr: 192.168.1.0/24
            excludeFirst: 1
            excludeLast: 1
            neverReallocate: true
        participantId:
          $ref: '#/components/schemas/properties.UUID'
          description: |
            Owner of this pool. Omit (or set null) to create a global pool — admin only.
            When set, the pool is scoped to that participant; participants may only set
            their own ID. Two participants may have pools sharing the same `type`.
    CreateConfigPoolValueReq:
      type: object
      required:
        - configPoolId
        - name
        - value
      properties:
        configPoolId:
          $ref: '#/components/schemas/properties.UUID'
        name:
          type: string
          example: 192.168.1.10
          description: Display name for the value
        value:
          description: Any JSON value (string, number, object, array)
          example: 192.168.1.10
    CreateAgentReq:
      type: object
      required:
        - name
        - providerId
        - agentTypeId
      properties:
        name:
          type: string
          example: aws-agent-01
        providerId:
          $ref: '#/components/schemas/properties.UUID'
          description: The participant ID that owns this agent
        agentTypeId:
          $ref: '#/components/schemas/properties.UUID'
          description: The agent type ID
        configuration:
          $ref: '#/components/schemas/JSONObject'
          description: Agent-specific configuration parameters
          example:
            timeout: 30
            retries: 3
            environment: production
        servicePoolSetId:
          $ref: '#/components/schemas/properties.UUID'
          description: Optional service pool set for automatic resource allocation
        infrastructureId:
          $ref: '#/components/schemas/properties.UUID'
          description: Required when the agent type declares an infrastructure type; must match that type and the agent's provider
    CreateAgentTypeReq:
      type: object
      required:
        - name
        - configurationSchema
      properties:
        name:
          type: string
          description: Name of the agent type
          example: VM Agent
          minLength: 1
        serviceTypeIds:
          type: array
          description: Optional list of service type IDs that this agent type can manage
          items:
            $ref: '#/components/schemas/properties.UUID'
          example:
            - 550e8400-e29b-41d4-a716-446655440000
            - 550e8400-e29b-41d4-a716-446655440001
        infrastructureTypeIds:
          type: array
          maxItems: 1
          description: Optional list of infrastructure type IDs this agent type requires (currently at most one)
          items:
            $ref: '#/components/schemas/properties.UUID'
        configurationSchema:
          $ref: '#/components/schemas/ConfigurationSchema'
          description: Schema defining the structure and validation rules for agent configuration
        configTemplate:
          type: string
          description: Go text/template for the agent config file. Placeholder refs must be keys of configurationSchema.properties.
          example: |-
            host={{.host}}
            port={{.port}}
        cmdTemplate:
          type: string
          description: Go text/template for the agent install command. Placeholder refs must be keys of configurationSchema.properties or {{.configUrl}}.
          example: agent install --config {{.configUrl}}
        configContentType:
          type: string
          description: Media type (RFC 6838) of the rendered configTemplate output. Defaults to text/plain when omitted.
          default: text/plain
          example: application/yaml
    CreateServiceTypeReq:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Name of the service type
          example: VM Instance
          minLength: 1
        propertySchema:
          $ref: '#/components/schemas/PropertySchema'
          description: Optional property schema defining the structure and validation rules for service properties
        lifecycleSchema:
          $ref: '#/components/schemas/LifecycleSchema'
          description: Optional lifecycle schema defining states, actions, and transitions for services of this type
    ErrorRes:
      type: object
      required:
        - status
        - message
      properties:
        status:
          type: integer
          description: HTTP status code
          example: 400
        message:
          type: string
          description: Human-readable error message
          example: provider with ID '123e4567-e89b-12d3-a456-426614174000' does not exist
        template:
          type: string
          description: Message template with {placeholder} tokens, present only when the message was interpolated from structured data (enables client-side localization).
          example: provider with ID {providerId} does not exist
        data:
          type: object
          additionalProperties: true
          description: Interpolation values for the template placeholders
          example:
            providerId: 123e4567-e89b-12d3-a456-426614174000
    EventAckReq:
      type: object
      required:
        - subscriberId
        - instanceId
        - lastEventSequenceProcessed
      properties:
        subscriberId:
          type: string
          description: Unique identifier for the subscriber system
          example: external-system
        instanceId:
          type: string
          description: Unique identifier for the consuming instance
          example: instance-1
        lastEventSequenceProcessed:
          type: integer
          format: int64
          description: Sequence number of the last event successfully processed
          minimum: 1
          example: 150
    EventAckRes:
      type: object
      properties:
        lastEventSequenceProcessed:
          type: integer
          format: int64
          description: Updated last event sequence processed
          example: 150
    EventLeaseReq:
      type: object
      required:
        - subscriberId
        - instanceId
      properties:
        subscriberId:
          type: string
          description: Unique identifier for the subscriber system
          example: external-system
        instanceId:
          type: string
          description: Unique identifier for the consuming instance
          example: instance-1
        leaseDurationSeconds:
          type: integer
          description: Lease duration in seconds (default 300, max 3600, min 30)
          minimum: 30
          maximum: 3600
          default: 300
          example: 300
        limit:
          type: integer
          description: Maximum number of events to fetch (default 100, max 1000, min 1)
          minimum: 1
          maximum: 1000
          default: 100
          example: 100
    EventLeaseRes:
      type: object
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/EventRes'
          description: Array of events fetched in chronological order
        leaseExpiresAt:
          type: string
          format: date-time
          description: When the current lease expires
        lastEventSequenceProcessed:
          type: integer
          format: int64
          description: Last event sequence number processed by this subscriber
          example: 150
    EventRes:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/properties.UUID'
        sequenceNumber:
          type: integer
          format: int64
          description: Sequence number for strict event ordering
        initiatorType:
          type: string
          example: user
        initiatorId:
          type: string
          example: admin
        type:
          type: string
          example: service.created
        properties:
          $ref: '#/components/schemas/JSONObject'
          description: Event payload data
        providerId:
          $ref: '#/components/schemas/properties.UUID'
        provider:
          $ref: '#/components/schemas/ParticipantRes'
        agentId:
          $ref: '#/components/schemas/properties.UUID'
        agent:
          $ref: '#/components/schemas/AgentRes'
        consumerId:
          $ref: '#/components/schemas/properties.UUID'
        consumer:
          $ref: '#/components/schemas/ParticipantRes'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    FailJobReq:
      type: object
      required:
        - errorMessage
      properties:
        errorMessage:
          type: string
          description: |
            Error message describing the failure. This message is matched against
            lifecycle transition regexps to determine the next service state.
          example: 'Failed to create VM: insufficient resources'
    InstallTokenRes:
      type: object
      description: |
        One-shot install token response. Returned by Create and Regenerate.
        `installCommand` and `url` contain the plain token; they cannot be
        recovered later — if lost, the token must be regenerated.
      properties:
        installCommand:
          type: string
          description: Rendered install command (copy-paste onto the target host).
          example: agent install --config https://api.fulcrum.testudosrl.dev/api/v1/agents/install/tkn_9fUw8J3lA2bN5yQrK7zX/config
        url:
          type: string
          format: uri
          description: Install fetch URL containing the plain token.
          example: https://api.fulcrum.testudosrl.dev/api/v1/agents/install/tkn_9fUw8J3lA2bN5yQrK7zX/config
        expiresAt:
          type: string
          format: date-time
          example: '2026-04-24T14:35:00Z'
      required:
        - installCommand
        - url
        - expiresAt
    InstallTokenMetaRes:
      type: object
      description: |
        Metadata-only view of the current install token. Never exposes the
        plain token or rendered URL.
      properties:
        id:
          $ref: '#/components/schemas/properties.UUID'
        expiresAt:
          type: string
          format: date-time
          example: '2026-04-24T14:35:00Z'
        createdAt:
          type: string
          format: date-time
          example: '2026-04-24T14:30:00Z'
      required:
        - id
        - expiresAt
        - createdAt
    InfrastructureRes:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/properties.UUID'
        name:
          type: string
          example: csi-node-01
        providerId:
          $ref: '#/components/schemas/properties.UUID'
        infrastructureTypeId:
          $ref: '#/components/schemas/properties.UUID'
        configuration:
          $ref: '#/components/schemas/JSONObject'
          description: Instance-specific configuration values validated against the referenced InfrastructureType's configurationSchema.
        participant:
          $ref: '#/components/schemas/ParticipantRes'
        infrastructureType:
          $ref: '#/components/schemas/InfrastructureTypeRes'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    CreateInfrastructureReq:
      type: object
      required:
        - name
        - providerId
        - infrastructureTypeId
      properties:
        name:
          type: string
          example: csi-node-01
          minLength: 1
        providerId:
          $ref: '#/components/schemas/properties.UUID'
        infrastructureTypeId:
          $ref: '#/components/schemas/properties.UUID'
        configuration:
          $ref: '#/components/schemas/JSONObject'
          description: Configuration values validated against the InfrastructureType's configurationSchema.
    UpdateInfrastructureReq:
      type: object
      properties:
        name:
          type: string
          minLength: 1
        configuration:
          $ref: '#/components/schemas/JSONObject'
    InfrastructureTypeRes:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/properties.UUID'
        name:
          type: string
          example: fulcrum-csp-node
        configurationSchema:
          $ref: '#/components/schemas/InfrastructureConfigurationSchema'
          description: Schema defining the structure and validation rules for infrastructure configuration
        configTemplate:
          type: string
          description: Go text/template rendered at install time to produce the infrastructure config file. Placeholder refs (e.g. {{.host}}) must be keys of configurationSchema.properties.
          example: |
            endpoint={{.endpoint}}
        cmdTemplate:
          type: string
          description: Go text/template rendered at install time to produce the infrastructure install command. Placeholder refs must be keys of configurationSchema.properties or the special {{.configUrl}} / {{.authToken}}.
          example: 'curl -fsSL {{.configUrl}} -H ''Authorization: Bearer {{.authToken}}'' | sh'
        configContentType:
          type: string
          description: Media type (RFC 6838) of the rendered configTemplate output. Defaults to text/plain.
          default: text/plain
          example: text/yaml
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    CreateInfrastructureTypeReq:
      type: object
      required:
        - name
        - configurationSchema
      properties:
        name:
          type: string
          description: Name of the infrastructure type
          example: fulcrum-csp-node
          minLength: 1
        configurationSchema:
          $ref: '#/components/schemas/InfrastructureConfigurationSchema'
          description: Schema defining the structure and validation rules for infrastructure configuration
        configTemplate:
          type: string
          description: Go text/template for the infrastructure config file. Placeholder refs must be keys of configurationSchema.properties.
          example: |
            endpoint={{.endpoint}}
        cmdTemplate:
          type: string
          description: Go text/template for the infrastructure install command. Placeholder refs must be keys of configurationSchema.properties or {{.configUrl}} / {{.authToken}}.
          example: 'curl -fsSL {{.configUrl}} -H ''Authorization: Bearer {{.authToken}}'' | sh'
        configContentType:
          type: string
          description: Media type (RFC 6838) of the rendered configTemplate output. Defaults to text/plain when omitted.
          default: text/plain
          example: text/yaml
    UpdateInfrastructureTypeReq:
      type: object
      properties:
        name:
          type: string
          description: Updated name of the infrastructure type
          minLength: 1
        configurationSchema:
          $ref: '#/components/schemas/InfrastructureConfigurationSchema'
          description: Updated configuration schema
        configTemplate:
          type: string
          description: Updated Go text/template for the infrastructure config file.
        cmdTemplate:
          type: string
          description: Updated Go text/template for the infrastructure install command.
        configContentType:
          type: string
          description: Updated media type for the rendered configTemplate output. Empty resets to text/plain.
          default: text/plain
    InfrastructureConfigurationSchema:
      type: object
      description: Schema defining validation rules and structure for infrastructure configuration properties
      properties:
        properties:
          type: object
          description: Property definitions keyed by property name
          additionalProperties:
            $ref: '#/components/schemas/PropertyDefinition'
        validators:
          type: array
          description: Schema-level validators (e.g., exactlyOne)
          items:
            $ref: '#/components/schemas/SchemaValidatorConfig'
      example:
        properties:
          endpoint:
            type: string
            label: Endpoint
            required: true
    JSONObject:
      type: object
      additionalProperties: true
      description: A generic properties.JSON object
    CreateKeycloakUserReq:
      type: object
      required:
        - username
        - email
        - firstName
        - lastName
        - password
        - role
      properties:
        username:
          type: string
          example: john.doe
        email:
          type: string
          format: email
          example: john.doe@example.com
        emailVerified:
          type: boolean
          example: false
        firstName:
          type: string
          example: John
        lastName:
          type: string
          example: Doe
        password:
          type: string
          example: securePassword123
        enabled:
          type: boolean
          example: true
        role:
          $ref: '#/components/schemas/AuthRole'
        participantId:
          type: string
          description: Required when role is 'participant'
          example: 123e4567-e89b-12d3-a456-426614174000
        agentId:
          type: string
          description: Required when role is 'agent'
          example: 123e4567-e89b-12d3-a456-426614174000
    UpdateKeycloakUserReq:
      type: object
      properties:
        email:
          type: string
          format: email
          example: john.updated@example.com
        emailVerified:
          type: boolean
        firstName:
          type: string
          example: John
        lastName:
          type: string
          example: Doe
        enabled:
          type: boolean
        password:
          type: string
        role:
          $ref: '#/components/schemas/AuthRole'
        participantId:
          type: string
          description: Required when role is 'participant'
        agentId:
          type: string
          description: Required when role is 'agent'
    KeycloakUserRes:
      type: object
      properties:
        id:
          type: string
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        username:
          type: string
          example: john.doe
        email:
          type: string
          example: john.doe@example.com
        emailVerified:
          type: boolean
        firstName:
          type: string
          example: John
        lastName:
          type: string
          example: Doe
        enabled:
          type: boolean
        roles:
          type: array
          items:
            $ref: '#/components/schemas/AuthRole'
          example:
            - participant
        participantId:
          type: string
          description: Present only for users with participant role
        agentId:
          type: string
          description: Present only for users with agent role
    KeycloakUserListItemRes:
      type: object
      properties:
        id:
          type: string
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        username:
          type: string
          example: john.doe
        email:
          type: string
          example: john.doe@example.com
        firstName:
          type: string
          example: John
        lastName:
          type: string
          example: Doe
    JobRes:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/properties.UUID'
        providerId:
          $ref: '#/components/schemas/properties.UUID'
          description: ID of the participant that provides the service
        consumerId:
          $ref: '#/components/schemas/properties.UUID'
          description: ID of the participant that consumes the service
        agentId:
          $ref: '#/components/schemas/properties.UUID'
        serviceId:
          $ref: '#/components/schemas/properties.UUID'
        action:
          $ref: '#/components/schemas/ServiceAction'
        params:
          $ref: '#/components/schemas/JSONObject'
          description: Parameters for the job action
        status:
          $ref: '#/components/schemas/JobStatus'
        priority:
          type: integer
          example: 1
        errorMessage:
          type: string
          example: 'Failed to create VM: insufficient resources'
        claimedAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
        completedAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        service:
          $ref: '#/components/schemas/ServiceRes'
          description: Associated service details (optional)
        agent:
          $ref: '#/components/schemas/AgentRes'
          description: Associated agent details (optional)
        provider:
          $ref: '#/components/schemas/ParticipantRes'
          description: Provider participant details (optional)
        consumer:
          $ref: '#/components/schemas/ParticipantRes'
          description: Consumer participant details (optional)
    JobStatus:
      type: string
      enum:
        - Pending
        - Processing
        - Completed
        - Failed
      description: |
        Job status transitions:
        - Pending: Job created and waiting for agent to claim
        - Processing: Job claimed by agent and in progress
        - Completed: Job successfully finished
        - Failed: Job encountered an error (error message drives service state transition via regexp)
    LifecycleAction:
      type: object
      required:
        - name
        - transitions
      properties:
        name:
          type: string
          description: Name of the action (e.g., start, stop, restart)
          example: start
        requestSchemaType:
          type: string
          enum:
            - properties
          description: |
            Type of request body expected for this action:
            - properties: Action accepts service properties in request body
            - (none): Action requires no request body
          example: properties
        transitions:
          type: array
          description: State transitions for this action
          items:
            $ref: '#/components/schemas/LifecycleTransition'
    LifecycleSchema:
      type: object
      description: |
        Schema-driven lifecycle definition for service state management. Each ServiceType can define
        its own custom lifecycle with states, actions, and transitions.
      required:
        - states
        - actions
        - initialState
        - terminateState
      properties:
        states:
          type: array
          description: List of possible service states
          items:
            $ref: '#/components/schemas/LifecycleState'
          example:
            - name: New
            - name: Stopped
            - name: Started
            - name: Deleted
        actions:
          type: array
          description: List of available actions that can be performed on services
          items:
            $ref: '#/components/schemas/LifecycleAction'
        initialState:
          type: string
          description: Initial state for new services
          example: New
        terminateState:
          type: string
          description: State CEM moves a service into when its order expires and is not renewed
          example: Deleted
        terminalStates:
          type: array
          description: States where no further actions can be performed
          items:
            type: string
          example:
            - Deleted
        runningStates:
          type: array
          description: States considered "running" for uptime calculation
          items:
            type: string
          example:
            - Started
    LifecycleState:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Unique name for this state
          example: Started
    LifecycleTransition:
      type: object
      required:
        - from
        - to
      properties:
        from:
          type: string
          description: Source state for this transition
          example: Stopped
        to:
          type: string
          description: Destination state for this transition
          example: Started
        onError:
          type: boolean
          description: Whether this transition applies to error cases
          default: false
        onErrorRegexp:
          type: string
          description: |
            Regular expression to match error messages. When a job fails, the error message
            is matched against this regexp to determine which error transition to use.
            If not specified, matches any error.
          example: quota.*exceeded
    MetricEntityType:
      type: string
      enum:
        - Agent
        - Service
        - Resource
    AggregationResult:
      type: object
      properties:
        data:
          type: array
          items:
            type: array
            items: {}
            minItems: 2
            maxItems: 2
            description: Tuple of [timestamp, aggregated_value]
        aggregate:
          type: string
          enum:
            - min
            - max
            - sum
            - avg
        bucket:
          type: string
          enum:
            - minute
            - hour
            - day
            - month
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
    MetricEntryReq:
      type: object
      required:
        - resourceId
        - typeName
        - value
      properties:
        serviceId:
          $ref: '#/components/schemas/properties.UUID'
          description: ID of the service associated with this metric
        agentInstanceId:
          type: string
          description: Agent instance ID of the service associated with this metric
          example: i-12345
        resourceId:
          type: string
          example: cpu-1
        value:
          type: number
          format: float
          example: 78.5
        typeName:
          type: string
          description: Name of the metric type
          example: cpu.usage
    MetricEntryRes:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/properties.UUID'
        providerId:
          $ref: '#/components/schemas/properties.UUID'
        consumerId:
          $ref: '#/components/schemas/properties.UUID'
        agentId:
          $ref: '#/components/schemas/properties.UUID'
        serviceId:
          $ref: '#/components/schemas/properties.UUID'
        resourceId:
          type: string
          example: cpu-1
        value:
          type: number
          format: float
          example: 78.5
        typeId:
          type: string
          description: Metric type ID as string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        agent:
          $ref: '#/components/schemas/AgentRes'
        service:
          $ref: '#/components/schemas/ServiceRes'
        type:
          $ref: '#/components/schemas/MetricTypeRes'
    MetricTypeReq:
      type: object
      required:
        - name
        - entityType
      properties:
        name:
          type: string
          example: cpu_usage
        entityType:
          $ref: '#/components/schemas/MetricEntityType'
    MetricTypeRes:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/properties.UUID'
        entityType:
          $ref: '#/components/schemas/MetricEntityType'
        name:
          type: string
          example: cpu_usage
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    PageRes:
      type: object
      properties:
        items:
          type: array
          items:
            type: object
        totalItems:
          type: integer
          format: int64
          description: Total number of items across all pages
        totalPages:
          type: integer
          description: Total number of pages
        currentPage:
          type: integer
          description: Current page number
        hasNext:
          type: boolean
          description: Whether there is a next page
        hasPrev:
          type: boolean
          description: Whether there is a previous page
    ParticipantReq:
      type: object
      required:
        - name
        - status
      properties:
        name:
          type: string
          example: Test Participant
        status:
          $ref: '#/components/schemas/ParticipantStatus'
    ParticipantRes:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/properties.UUID'
        name:
          type: string
          example: Test Participant
        status:
          $ref: '#/components/schemas/ParticipantStatus'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ParticipantStatus:
      type: string
      enum:
        - Enabled
        - Disabled
    PropertyDefinition:
      type: object
      properties:
        type:
          type: string
          enum:
            - string
            - integer
            - number
            - boolean
            - uuid
            - object
            - array
            - json
          description: The data type of the property
        label:
          type: string
          description: Human-readable label for the property
        required:
          type: boolean
          description: Whether the property is required
          default: false
        default:
          description: Default value for the property
        immutable:
          type: boolean
          description: If true, property cannot be changed after creation
          default: false
        authorizers:
          type: array
          items:
            $ref: '#/components/schemas/AuthorizerDefinition'
          description: Authorization rules controlling who can set/update and when updates are allowed (all must pass - AND logic)
        secret:
          $ref: '#/components/schemas/SecretDefinition'
          description: Configuration for secure vault storage of sensitive values
        generator:
          $ref: '#/components/schemas/GeneratorDefinition'
          description: Configuration for automatic value generation (e.g., pool allocation)
        validators:
          type: array
          items:
            $ref: '#/components/schemas/ValidatorDefinition'
          description: Validation rules for value correctness (pattern, enum, min, max, etc.)
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/PropertyDefinition'
          description: Nested properties for object types
        items:
          $ref: '#/components/schemas/PropertyDefinition'
          description: Schema for array items
    PropertySchema:
      type: object
      description: Schema defining validation rules and structure for service properties
      properties:
        properties:
          type: object
          description: Property definitions keyed by property name
          additionalProperties:
            $ref: '#/components/schemas/PropertyDefinition'
        validators:
          type: array
          description: Schema-level validators (e.g., exactlyOne)
          items:
            $ref: '#/components/schemas/SchemaValidatorConfig'
      example:
        properties:
          cpu:
            type: integer
            label: CPU Cores
            required: true
            validators:
              - type: min
                config:
                  value: 1
              - type: max
                config:
                  value: 32
          memory:
            type: integer
            label: Memory (MB)
            required: true
            validators:
              - type: min
                config:
                  value: 512
          environment:
            type: string
            label: Environment
            default: development
            validators:
              - type: enum
                config:
                  values:
                    - development
                    - staging
                    - production
    ServiceAction:
      type: string
      description: Lifecycle action to perform on the service. Valid values are defined by the service type's lifecycle schema
      example: start
    CreateServiceGroupReq:
      type: object
      required:
        - name
        - consumerId
      properties:
        name:
          type: string
          example: Web Servers
        consumerId:
          $ref: '#/components/schemas/properties.UUID'
          description: ID of the consumer participant that owns this service group
    UpdateServiceGroupReq:
      type: object
      properties:
        name:
          type: string
          example: Web Servers
    ServiceGroupRes:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/properties.UUID'
        name:
          type: string
          example: Web Servers
        consumerId:
          $ref: '#/components/schemas/properties.UUID'
          description: ID of the consumer participant that owns this service group
        consumer:
          $ref: '#/components/schemas/ParticipantRes'
          description: Consumer participant details (populated when available)
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ServiceOptionReq:
      type: object
      required:
        - providerId
        - serviceOptionTypeId
        - name
        - value
      properties:
        providerId:
          $ref: '#/components/schemas/properties.UUID'
        serviceOptionTypeId:
          $ref: '#/components/schemas/properties.UUID'
        name:
          type: string
          example: Ubuntu 22.04 LTS
        value:
          description: Any JSON value (string, number, object, array)
          example: ubuntu-22.04
        enabled:
          type: boolean
          default: true
        displayOrder:
          type: integer
          default: 0
    ServiceOptionRes:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/properties.UUID'
        providerId:
          $ref: '#/components/schemas/properties.UUID'
        serviceOptionTypeId:
          $ref: '#/components/schemas/properties.UUID'
        name:
          type: string
          example: Ubuntu 22.04 LTS
        value:
          description: Any JSON value (string, number, object, array)
          example: ubuntu-22.04
        enabled:
          type: boolean
        displayOrder:
          type: integer
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ServiceOptionTypeReq:
      type: object
      required:
        - name
        - type
      properties:
        name:
          type: string
          example: Operating System
        type:
          type: string
          example: operating_system
          description: Unique identifier (lowercase, underscores)
        description:
          type: string
          example: Available operating systems for VMs
    ServiceOptionTypeRes:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/properties.UUID'
        name:
          type: string
          example: Operating System
        type:
          type: string
          example: operating_system
        description:
          type: string
          example: Available operating systems for VMs
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ServicePoolRes:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/properties.UUID'
        name:
          type: string
          example: Public IP Pool
        type:
          type: string
          example: public_ip
        propertyType:
          type: string
          enum:
            - string
            - integer
            - number
            - boolean
            - json
          example: string
          description: Property type that this pool provides
        generatorType:
          type: string
          enum:
            - list
            - subnet
          example: list
        generatorConfig:
          type: object
          example:
            cidr: 192.168.1.0/24
        servicePoolSetId:
          $ref: '#/components/schemas/properties.UUID'
        servicePoolSetName:
          type: string
          example: My Pool Set
          description: Name of the associated service pool set
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ServicePoolSetRes:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/properties.UUID'
        name:
          type: string
          example: Production Pools
        providerId:
          $ref: '#/components/schemas/properties.UUID'
        provider:
          $ref: '#/components/schemas/ParticipantRes'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ServicePoolValueRes:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/properties.UUID'
        name:
          type: string
          example: 192.168.1.10
        value:
          description: Any JSON value (string, number, object, array)
          example: 192.168.1.10
        servicePoolId:
          $ref: '#/components/schemas/properties.UUID'
        servicePool:
          $ref: '#/components/schemas/ServicePoolRes'
          description: The service pool this value belongs to
        serviceId:
          $ref: '#/components/schemas/properties.UUID'
          description: Service this value is allocated to (null if available)
        service:
          $ref: '#/components/schemas/ServiceRes'
          description: The service this value is allocated to (only present if allocated)
        propertyName:
          type: string
          example: ipAddress
          description: Property name this value is allocated to
        allocatedAt:
          type: string
          format: date-time
          description: When this value was allocated
        releasedAt:
          type: string
          format: date-time
          description: When this value was last released back to the pool (omitted while allocated). Combined with the pool's retentionSeconds to gate reuse of subnet values.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    CreateServicePoolReq:
      type: object
      required:
        - name
        - type
        - propertyType
        - generatorType
        - servicePoolSetId
      properties:
        name:
          type: string
          example: Public IP Pool
          description: Name of the pool
        type:
          type: string
          example: public_ip
          description: Type identifier referenced in servicePoolType property field
        propertyType:
          type: string
          enum:
            - string
            - integer
            - number
            - boolean
            - json
          example: string
          description: Property type that this pool provides (must match property definitions)
        generatorType:
          type: string
          enum:
            - list
            - subnet
          example: list
          description: 'Allocation strategy: ''list'' for pre-configured values, ''subnet'' for IP ranges'
        generatorConfig:
          type: object
          description: 'Generator-specific configuration (required for subnet). For ''subnet'' an optional integer ''retentionSeconds'' sets a reuse cooldown: a released value is re-allocatable only after that many seconds (omitted or 0 = reuse immediately). An optional boolean ''neverReallocate'' (default false): when true a released value is never re-allocated, taking precedence over ''retentionSeconds''.'
          example:
            cidr: 192.168.1.0/24
            excludeFirst: 1
            excludeLast: 1
            neverReallocate: true
        servicePoolSetId:
          $ref: '#/components/schemas/properties.UUID'
    CreateServicePoolSetReq:
      type: object
      required:
        - name
        - providerId
      properties:
        name:
          type: string
          example: Production Pools
          description: Name of the pool set
        providerId:
          $ref: '#/components/schemas/properties.UUID'
    CreateServicePoolValueReq:
      type: object
      required:
        - servicePoolId
        - name
        - value
      properties:
        servicePoolId:
          $ref: '#/components/schemas/properties.UUID'
        name:
          type: string
          example: 192.168.1.10
          description: Display name for the value
        value:
          description: Any JSON value (string, number, object, array)
          example: 192.168.1.10
    UpdateServicePoolReq:
      type: object
      properties:
        name:
          type: string
          example: Public IP Pool - Updated
        generatorConfig:
          type: object
          description: Generator-specific configuration
    UpdateServicePoolSetReq:
      type: object
      properties:
        name:
          type: string
          example: Production Pools - Updated
    ServiceReq:
      type: object
      required:
        - name
        - serviceTypeId
        - groupId
        - agentId
      properties:
        name:
          type: string
          example: web-server-01
        properties:
          $ref: '#/components/schemas/JSONObject'
        agentId:
          $ref: '#/components/schemas/properties.UUID'
          description: ID of the agent that will host the service.
        serviceTypeId:
          $ref: '#/components/schemas/properties.UUID'
        groupId:
          $ref: '#/components/schemas/properties.UUID'
    ServiceRes:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/properties.UUID'
        name:
          type: string
          example: web-server-01
        status:
          type: string
          description: Current lifecycle state. Valid values are defined by the service type's lifecycle schema
          example: Started
        properties:
          $ref: '#/components/schemas/JSONObject'
        agentInstanceData:
          $ref: '#/components/schemas/JSONObject'
        agentInstanceId:
          anyOf:
            - type: string
            - type: 'null'
        providerId:
          $ref: '#/components/schemas/properties.UUID'
        consumerId:
          $ref: '#/components/schemas/properties.UUID'
        agentId:
          $ref: '#/components/schemas/properties.UUID'
        agent:
          $ref: '#/components/schemas/AgentRes'
        serviceTypeId:
          $ref: '#/components/schemas/properties.UUID'
        serviceType:
          $ref: '#/components/schemas/ServiceTypeRes'
        groupId:
          $ref: '#/components/schemas/properties.UUID'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ServiceTypeRes:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/properties.UUID'
        name:
          type: string
          example: VM
        propertySchema:
          $ref: '#/components/schemas/PropertySchema'
        lifecycleSchema:
          $ref: '#/components/schemas/LifecycleSchema'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    TokenReq:
      type: object
      required:
        - name
        - role
      properties:
        name:
          type: string
          example: API Access Token
        role:
          $ref: '#/components/schemas/AuthRole'
        expireAt:
          type: string
          format: date-time
          example: '2025-12-31T23:59:59Z'
          description: Optional expiration date. If not provided, defaults to 24 hours from creation
        scopeId:
          $ref: '#/components/schemas/properties.UUID'
          description: Required for participant and agent roles. For participant role - the participant ID; for agent role - the agent ID
    TokenRes:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/properties.UUID'
        name:
          type: string
          example: API Access Token
        role:
          $ref: '#/components/schemas/AuthRole'
        expireAt:
          type: string
          format: date-time
        participantId:
          $ref: '#/components/schemas/properties.UUID'
          description: For participant role tokens - the participant ID
        participant:
          $ref: '#/components/schemas/ParticipantRes'
          description: For participant role tokens - the full participant object
        agentId:
          $ref: '#/components/schemas/properties.UUID'
          description: For agent role tokens - the agent ID
        agent:
          $ref: '#/components/schemas/AgentRes'
          description: For agent role tokens - the full agent object
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        value:
          type: string
          description: Plain token value. Only returned during token creation or regeneration
          example: eyJhbGciOiJIUzI1NiIsInR5c...
    UpdateConfigPoolReq:
      type: object
      properties:
        name:
          type: string
          example: Public IP Pool - Updated
        generatorConfig:
          type: object
          description: Generator-specific configuration
    UpdateAgentReq:
      type: object
      properties:
        name:
          type: string
          example: aws-agent-01
        status:
          $ref: '#/components/schemas/AgentStatus'
        configuration:
          $ref: '#/components/schemas/JSONObject'
          description: Agent-specific configuration parameters
          example:
            timeout: 60
            retries: 5
            environment: staging
        servicePoolSetId:
          $ref: '#/components/schemas/properties.UUID'
          description: Optional service pool set for automatic resource allocation
    UpdateAgentTypeReq:
      type: object
      properties:
        name:
          type: string
          description: Updated name of the agent type
          example: Updated VM Agent
          minLength: 1
        serviceTypeIds:
          type: array
          description: Updated list of service type IDs that this agent type can manage
          items:
            $ref: '#/components/schemas/properties.UUID'
          example:
            - 550e8400-e29b-41d4-a716-446655440000
            - 550e8400-e29b-41d4-a716-446655440002
        infrastructureTypeIds:
          type: array
          maxItems: 1
          description: Updated list of infrastructure type IDs this agent type requires (currently at most one)
          items:
            $ref: '#/components/schemas/properties.UUID'
        configurationSchema:
          $ref: '#/components/schemas/ConfigurationSchema'
          description: Updated configuration schema
        configTemplate:
          type: string
          description: Updated Go text/template for the agent config file.
        cmdTemplate:
          type: string
          description: Updated Go text/template for the agent install command.
        configContentType:
          type: string
          description: Updated media type for the rendered configTemplate output. Empty resets to text/plain.
          default: text/plain
    UpdateServiceTypeReq:
      type: object
      properties:
        name:
          type: string
          description: Updated name of the service type
          example: Updated VM Instance
          minLength: 1
        propertySchema:
          $ref: '#/components/schemas/PropertySchema'
          description: Updated property schema defining the structure and validation rules for service properties
        lifecycleSchema:
          $ref: '#/components/schemas/LifecycleSchema'
          description: Updated lifecycle schema defining states, actions, and transitions for services of this type
    ValidationError:
      type: object
      properties:
        path:
          type: string
          description: Path to the property that failed validation
          example: cpu
        message:
          type: string
          description: Error message describing the validation failure
          example: 'cpu: value must be one of: [1, 2, 4, 8, 16, 32]'
      examples:
        - path: ipAddress
          message: 'ipAddress: property can only be set by: [agent]'
        - path: region
          message: 'region: property is immutable and cannot be changed'
        - path: diskSize
          message: 'diskSize: property cannot be updated in state ''Started'''
        - path: cpu
          message: 'cpu: value must be one of: [1, 2, 4, 8, 16, 32]'
    ValidatorDefinition:
      type: object
      required:
        - type
        - config
      properties:
        type:
          type: string
          enum:
            - minLength
            - maxLength
            - pattern
            - enum
            - min
            - max
            - minItems
            - maxItems
            - uniqueItems
            - serviceOption
            - serviceReference
          description: Type of validator
        config:
          type: object
          description: Configuration for the validator (structure depends on validator type)
          additionalProperties: true
    SchemaValidatorConfig:
      type: object
      required:
        - type
        - config
      properties:
        type:
          type: string
          enum:
            - exactlyOne
          description: Type of schema-level validator
        config:
          type: object
          description: Configuration for the schema validator
          additionalProperties: true
      example:
        type: exactlyOne
        config:
          properties:
            - option1
            - option2
    properties.UUID:
      type: string
      format: uuid
      example: 123e4567-e89b-12d3-a456-426614174000
    AuthorizerDefinition:
      type: object
      required:
        - type
        - config
      properties:
        type:
          type: string
          enum:
            - actor
            - state
          description: Type of authorizer
        config:
          type: object
          description: Configuration for the authorizer
          additionalProperties: true
      example:
        type: actor
        config:
          actors:
            - agent
    SecretDefinition:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - persistent
            - ephemeral
          description: |
            Secret type:
            - persistent: Cleaned up when service reaches terminal state
            - ephemeral: Cleaned up after each job completion
          example: persistent
    GeneratorDefinition:
      type: object
      required:
        - type
        - config
      properties:
        type:
          type: string
          enum:
            - pool
          description: Type of generator
        config:
          type: object
          description: Configuration for the generator
          additionalProperties: true
      example:
        type: pool
        config:
          poolType: public_ip
    ConfigurationSchema:
      type: object
      description: Schema defining validation rules and structure for agent configuration properties
      properties:
        properties:
          type: object
          description: Property definitions keyed by property name
          additionalProperties:
            $ref: '#/components/schemas/PropertyDefinition'
        validators:
          type: array
          description: Schema-level validators (e.g., exactlyOne)
          items:
            $ref: '#/components/schemas/SchemaValidatorConfig'
      example:
        properties:
          apiEndpoint:
            type: string
            label: API Endpoint
            required: true
            validators:
              - type: pattern
                config:
                  pattern: ^https?://
          maxRetries:
            type: integer
            label: Max Retries
            default: 3
            validators:
              - type: min
                config:
                  value: 0
              - type: max
                config:
                  value: 10
    UpdateServiceOptionTypeReq:
      type: object
      properties:
        name:
          type: string
          example: Operating System
        description:
          type: string
          example: Available operating systems for VMs
    ServiceOptionUpdateReq:
      type: object
      properties:
        name:
          type: string
          example: Ubuntu 22.04 LTS
        value:
          description: Any JSON value (string, number, object, array)
          example: ubuntu-22.04
        enabled:
          type: boolean
        displayOrder:
          type: integer
    ValidationErrorDetail:
      type: object
      required:
        - path
        - message
      properties:
        path:
          type: string
          description: The property path that failed validation
          example: cpu
        message:
          type: string
          description: The validation error message
          example: value not in allowed enum values 1, 2, 4, 8, 16, 32
        template:
          type: string
          description: Message template with {placeholder} tokens, present only when the message was interpolated from structured data.
          example: value not in allowed enum values {values}
        data:
          type: object
          additionalProperties: true
          description: Interpolation values for the template placeholders
          example:
            values:
              - 1
              - 2
              - 4
              - 8
              - 16
              - 32
    ValidationErrRes:
      type: object
      required:
        - status
        - message
        - errors
      properties:
        status:
          type: integer
          description: HTTP status code
          example: 400
        message:
          type: string
          description: Human-readable summary of the failure
          example: validation failed
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ValidationErrorDetail'
          description: Array of validation errors with detailed information about each failure
          minItems: 1
  responses:
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorRes'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorRes'
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorRes'
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorRes'
    Conflict:
      description: Conflict - the request conflicts with the current state of the resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorRes'
    ValidationErrors:
      description: Validation errors - request contains invalid or missing required fields
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationErrRes'
          example:
            status: 400
            message: validation failed
            errors:
              - path: cpu
                message: value not in allowed enum values 1, 2, 4, 8, 16, 32
                template: value not in allowed enum values {values}
                data:
                  values:
                    - 1
                    - 2
                    - 4
                    - 8
                    - 16
                    - 32
              - path: memory
                message: property is required