openapi: 3.1.0
info:
  title: ActLoom API v1
  version: "1.0.0"
  description: >
    Machine-to-machine API for selected ActLoom resources using scoped API keys.
servers:
  - url: http://localhost:3000
    description: Local development
security:
  - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: actloom_api_key
  schemas:
    AISystem:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        type: { type: string }
        description: { type: string }
        riskCategory: { type: string }
        deploymentStatus: { type: string }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
    Incident:
      type: object
      properties:
        id: { type: string }
        aiSystemId: { type: string }
        title: { type: string }
        description: { type: string }
        severity: { type: string, enum: [serious, near_miss] }
        status: { type: string }
        occurredAt: { type: string, format: date-time }
        createdAt: { type: string, format: date-time }
    Report:
      type: object
      properties:
        id: { type: string }
        type: { type: string }
        status: { type: string }
        aiSystemId: { type: string, nullable: true }
        createdAt: { type: string, format: date-time }
        generatedAt: { type: string, format: date-time, nullable: true }
paths:
  /api/v1/ai-systems:
    get:
      summary: List AI systems
      description: Requires scope `read:systems`.
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  systems:
                    type: array
                    items:
                      $ref: "#/components/schemas/AISystem"
    post:
      summary: Create AI system
      description: Requires scope `write:systems`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, type, description]
              properties:
                name: { type: string }
                type: { type: string }
                description: { type: string }
                intendedPurpose: { type: string }
                roles:
                  type: array
                  items: { type: string }
      responses:
        "201":
          description: Created
  /api/v1/incidents:
    get:
      summary: List incidents
      description: Requires scope `read:incidents`.
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  incidents:
                    type: array
                    items:
                      $ref: "#/components/schemas/Incident"
    post:
      summary: Create incident
      description: Requires scope `write:incidents`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [aiSystemId, title, description, severity]
              properties:
                aiSystemId: { type: string }
                title: { type: string }
                description: { type: string }
                severity: { type: string, enum: [serious, near_miss] }
                occurredAt: { type: string, format: date-time }
                notifiedAuthority: { type: boolean }
      responses:
        "201":
          description: Created
  /api/v1/reports:
    get:
      summary: List reports
      description: Requires scope `read:reports`.
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  reports:
                    type: array
                    items:
                      $ref: "#/components/schemas/Report"
  /api/v1/reports/generate:
    post:
      summary: Queue report generation
      description: Requires scope `write:reports`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [type]
              properties:
                type: { type: string }
                aiSystemId: { type: string }
      responses:
        "201":
          description: Queued