OpenAPI 3.1 Specification for OSSA Registry API

Objective

Define the OpenAPI 3.1 specification for the OSSA Agent Registry API that enables agent discovery, registration, and lifecycle management.

Scope

Create a comprehensive OpenAPI spec that defines:

• Agent registration and deregistration endpoints
• Agent discovery and search capabilities
• Version management and compatibility checking
• Health check and status endpoints
• Authentication and authorization patterns

Technical Approach

# openapi/ossa-registry.openapi.yml
openapi: 3.1.0
info:
  title: OSSA Agent Registry API
  version: 1.0.0
  description: API for managing OSSA-compliant agent registration and discovery

paths:
  /agents:
    get:
      summary: List registered agents
      operationId: listAgents
      parameters:
        - name: role
          in: query
          schema:
            type: string
            enum: [compliance, chat, orchestration, audit, workflow]
        - name: capability
          in: query
          schema:
            type: string
      responses:
        '200':
          description: List of agents
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AgentManifest'
    
    post:
      summary: Register new agent
      operationId: registerAgent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentManifest'
      responses:
        '201':
          description: Agent registered successfully
        '409':
          description: Agent already exists

  /agents/{agentId}:
    get:
      summary: Get agent details
      operationId: getAgent
    put:
      summary: Update agent registration
      operationId: updateAgent
    delete:
      summary: Deregister agent
      operationId: deregisterAgent

  /agents/{agentId}/health:
    get:
      summary: Check agent health
      operationId: checkAgentHealth

components:
  schemas:
    AgentManifest:
      $ref: '../spec/ossa-1.0.schema.json'
  
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

Acceptance Criteria

• OpenAPI 3.1 spec passes validation (redocly lint)
• All CRUD operations for agent lifecycle management
• Search/filter capabilities by role, capability, version
• Health check endpoints for monitoring
• Authentication/authorization patterns defined
• Request/response schemas reference OSSA 1.0 schema
• Error responses follow RFC 7807 Problem Details
• Rate limiting and pagination specified
• Webhook definitions for agent status changes
• Generated HTML documentation looks professional

Files to Create

• openapi/ossa-registry.openapi.yml - Main API specification
• spec/examples/registry-responses.yml - Example API responses

Related Standards

• OpenAPI 3.1 specification
• RFC 7807 - Problem Details for HTTP APIs
• JSON:API for collection responses