cortexweaver/contracts/api/openapi.yaml

CortexWeaver is a command-line interface (CLI) tool that orchestrates a swarm of specialized AI agents, powered by Claude Code and Gemini CLI, to assist in software development. It transforms a high-level project plan (plan.md) into a series of coordinate

openapi: 3.0.3
info:
  title: CortexWeaver Project API
  description: |
    This is a template OpenAPI specification for your CortexWeaver project.
    
    This contract serves as the formal specification for your API, following
    Specification-Driven Development (SDD) principles. AI agents will use this
    contract as their source of truth for implementation and testing.
    
    ## Usage Instructions
    1. Update the info section with your project details
    2. Define your API endpoints in the paths section
    3. Create reusable components in the components section
    4. Use this specification to guide implementation
    
  version: 1.0.0
  contact:
    name: Project Team
    email: team@example.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: http://localhost:3000/api/v1
    description: Development server
  - url: https://staging-api.example.com/v1
    description: Staging server
  - url: https://api.example.com/v1
    description: Production server

paths:
  /health:
    get:
      summary: Health check endpoint
      description: Returns the health status of the API
      operationId: getHealth
      tags:
        - Health
      responses:
        '200':
          description: API is healthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
              example:
                status: "healthy"
                timestamp: "2023-12-07T10:00:00Z"
                version: "1.0.0"

  /auth/register:
    post:
      summary: Register a new user
      description: Creates a new user account
      operationId: registerUser
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserRegistration'
            example:
              email: "user@example.com"
              password: "securePassword123"
              firstName: "John"
              lastName: "Doe"
      responses:
        '201':
          description: User registered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '400':
          description: Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: User already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /auth/login:
    post:
      summary: Authenticate user
      description: Authenticates a user and returns a JWT token
      operationId: loginUser
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserLogin'
            example:
              email: "user@example.com"
              password: "securePassword123"
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
        '401':
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  schemas:
    HealthResponse:
      type: object
      required:
        - status
        - timestamp
        - version
      properties:
        status:
          type: string
          enum: [healthy, degraded, unhealthy]
          description: Current health status
        timestamp:
          type: string
          format: date-time
          description: Timestamp of the health check
        version:
          type: string
          description: API version
        uptime:
          type: number
          description: Uptime in seconds

    UserRegistration:
      type: object
      required:
        - email
        - password
        - firstName
        - lastName
      properties:
        email:
          type: string
          format: email
          description: User's email address
        password:
          type: string
          minLength: 8
          description: User's password (minimum 8 characters)
        firstName:
          type: string
          minLength: 1
          maxLength: 50
          description: User's first name
        lastName:
          type: string
          minLength: 1
          maxLength: 50
          description: User's last name

    UserLogin:
      type: object
      required:
        - email
        - password
      properties:
        email:
          type: string
          format: email
          description: User's email address
        password:
          type: string
          description: User's password

    UserResponse:
      type: object
      required:
        - id
        - email
        - firstName
        - lastName
        - createdAt
      properties:
        id:
          type: string
          format: uuid
          description: Unique user identifier
        email:
          type: string
          format: email
          description: User's email address
        firstName:
          type: string
          description: User's first name
        lastName:
          type: string
          description: User's last name
        createdAt:
          type: string
          format: date-time
          description: Account creation timestamp
        updatedAt:
          type: string
          format: date-time
          description: Last profile update timestamp

    AuthResponse:
      type: object
      required:
        - token
        - user
        - expiresAt
      properties:
        token:
          type: string
          description: JWT authentication token
        user:
          $ref: '#/components/schemas/UserResponse'
        expiresAt:
          type: string
          format: date-time
          description: Token expiration timestamp

    ErrorResponse:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: Error code or type
        message:
          type: string
          description: Human-readable error message
        details:
          type: object
          description: Additional error details
        timestamp:
          type: string
          format: date-time
          description: Error occurrence timestamp

  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token authentication

security:
  - BearerAuth: []

tags:
  - name: Health
    description: Health check endpoints
  - name: Authentication
    description: User authentication and authorization
  - name: Users
    description: User management operations