openapi.yaml

openapi: 3.1.0
info:
  title: Koine Gateway API
  version: 1.0.0
  description: HTTP gateway service for Claude Code CLI. Provides REST endpoints for text generation, structured object generation, and streaming responses.
  license:
    name: AGPL-3.0-only OR LicenseRef-Commercial
    url: https://github.com/pattern-zones-co/koine/blob/main/LICENSE
  contact:
    name: Pattern Zones Co
    url: https://github.com/pattern-zones-co/koine
servers:
  - url: http://localhost:3100
    description: Local development server
tags:
  - name: Health
    description: Health check endpoints
  - name: Documentation
    description: API documentation and OpenAPI specification
  - name: Generation
    description: Text and object generation endpoints
  - name: Streaming
    description: Server-Sent Events streaming endpoints
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: "API key for authentication. Generate with: openssl rand -hex 32"
  schemas:
    GenerateTextRequest:
      type: object
      properties:
        system:
          type: string
        prompt:
          type: string
        sessionId:
          type: string
        model:
          type: string
        allowedTools:
          type: array
          items:
            type: string
        maxTokens:
          type: integer
          exclusiveMinimum: 0
      required:
        - prompt
    GenerateObjectRequest:
      type: object
      properties:
        system:
          type: string
        prompt:
          type: string
        sessionId:
          type: string
        model:
          type: string
        allowedTools:
          type: array
          items:
            type: string
        schema:
          type: object
          properties:
            type:
              type: string
              enum: &a1
                - object
                - array
                - string
                - number
                - integer
                - boolean
                - "null"
            properties:
              type: object
              additionalProperties: {}
            items: {}
            $ref:
              type: string
            allOf:
              type: array
              items: {}
            anyOf:
              type: array
              items: {}
            oneOf:
              type: array
              items: {}
            enum:
              type: array
              items: {}
            const: {}
        maxTokens:
          type: integer
          exclusiveMinimum: 0
      required:
        - prompt
        - schema
    StreamRequest:
      type: object
      properties:
        system:
          type: string
        prompt:
          type: string
        sessionId:
          type: string
        model:
          type: string
        allowedTools:
          type: array
          items:
            type: string
      required:
        - prompt
    StreamObjectRequest:
      type: object
      properties:
        system:
          type: string
        prompt:
          type: string
        sessionId:
          type: string
        model:
          type: string
        allowedTools:
          type: array
          items:
            type: string
        schema:
          type: object
          properties:
            type:
              type: string
              enum: *a1
            properties:
              type: object
              additionalProperties: {}
            items: {}
            $ref:
              type: string
            allOf:
              type: array
              items: {}
            anyOf:
              type: array
              items: {}
            oneOf:
              type: array
              items: {}
            enum:
              type: array
              items: {}
            const: {}
      required:
        - prompt
        - schema
    UsageInfo:
      type: object
      properties:
        inputTokens:
          type: integer
          minimum: 0
        outputTokens:
          type: integer
          minimum: 0
        totalTokens:
          type: integer
          minimum: 0
      required:
        - inputTokens
        - outputTokens
        - totalTokens
    GenerateTextResponse:
      type: object
      properties:
        text:
          type: string
        usage:
          type: object
          properties:
            inputTokens:
              type: integer
              minimum: 0
            outputTokens:
              type: integer
              minimum: 0
            totalTokens:
              type: integer
              minimum: 0
          required:
            - inputTokens
            - outputTokens
            - totalTokens
        sessionId:
          type: string
      required:
        - text
        - usage
        - sessionId
    GenerateObjectResponse:
      type: object
      properties:
        object: {}
        rawText:
          type: string
        usage:
          type: object
          properties:
            inputTokens:
              type: integer
              minimum: 0
            outputTokens:
              type: integer
              minimum: 0
            totalTokens:
              type: integer
              minimum: 0
          required:
            - inputTokens
            - outputTokens
            - totalTokens
        sessionId:
          type: string
      required:
        - rawText
        - usage
        - sessionId
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
          enum: &a4
            - VALIDATION_ERROR
            - INTERNAL_ERROR
            - UNKNOWN_ERROR
            - TIMEOUT_ERROR
            - CLI_EXIT_ERROR
            - SPAWN_ERROR
            - PARSE_ERROR
            - CONCURRENCY_LIMIT_ERROR
            - NO_TOOLS_AVAILABLE
        rawText:
          type: string
      required:
        - error
        - code
    HealthResponse:
      type: object
      properties:
        status:
          type: string
          enum: &a2
            - healthy
            - unhealthy
        claudeCli:
          type: string
          enum: &a3
            - available
            - unavailable
        timestamp:
          type: string
        error:
          type: string
        concurrency:
          type: object
          properties:
            streaming:
              type: object
              properties:
                active:
                  type: integer
                  minimum: 0
                limit:
                  type: integer
                  minimum: 0
              required:
                - active
                - limit
            nonStreaming:
              type: object
              properties:
                active:
                  type: integer
                  minimum: 0
                limit:
                  type: integer
                  minimum: 0
              required:
                - active
                - limit
          required:
            - streaming
            - nonStreaming
      required:
        - status
        - claudeCli
        - timestamp
  parameters: {}
paths:
  /health:
    get:
      summary: Health check endpoint
      description: Verifies the service is running and Claude CLI is accessible. No authentication required.
      tags:
        - Health
      responses:
        "200":
          description: Service is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum: *a2
                  claudeCli:
                    type: string
                    enum: *a3
                  timestamp:
                    type: string
                  error:
                    type: string
                  concurrency:
                    type: object
                    properties:
                      streaming:
                        type: object
                        properties:
                          active:
                            type: integer
                            minimum: 0
                          limit:
                            type: integer
                            minimum: 0
                        required:
                          - active
                          - limit
                      nonStreaming:
                        type: object
                        properties:
                          active:
                            type: integer
                            minimum: 0
                          limit:
                            type: integer
                            minimum: 0
                        required:
                          - active
                          - limit
                    required:
                      - streaming
                      - nonStreaming
                required:
                  - status
                  - claudeCli
                  - timestamp
        "503":
          description: Service is unhealthy (Claude CLI unavailable)
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum: *a2
                  claudeCli:
                    type: string
                    enum: *a3
                  timestamp:
                    type: string
                  error:
                    type: string
                  concurrency:
                    type: object
                    properties:
                      streaming:
                        type: object
                        properties:
                          active:
                            type: integer
                            minimum: 0
                          limit:
                            type: integer
                            minimum: 0
                        required:
                          - active
                          - limit
                      nonStreaming:
                        type: object
                        properties:
                          active:
                            type: integer
                            minimum: 0
                          limit:
                            type: integer
                            minimum: 0
                        required:
                          - active
                          - limit
                    required:
                      - streaming
                      - nonStreaming
                required:
                  - status
                  - claudeCli
                  - timestamp
  /docs:
    get:
      summary: API documentation
      description: Interactive API documentation powered by Scalar. No authentication required.
      tags:
        - Documentation
      responses:
        "200":
          description: HTML page with interactive API documentation
          content:
            text/html:
              schema:
                type: string
  /openapi.yaml:
    get:
      summary: OpenAPI specification
      description: Raw OpenAPI 3.1 specification in YAML format. No authentication required.
      tags:
        - Documentation
      responses:
        "200":
          description: OpenAPI specification in YAML format
          content:
            text/yaml:
              schema:
                type: string
  /generate-text:
    post:
      summary: Generate text response
      description: Generates plain text response from Claude CLI.
      tags:
        - Generation
      security:
        - BearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                system:
                  type: string
                prompt:
                  type: string
                sessionId:
                  type: string
                model:
                  type: string
                allowedTools:
                  type: array
                  items:
                    type: string
                maxTokens:
                  type: integer
                  exclusiveMinimum: 0
              required:
                - prompt
      responses:
        "200":
          description: Successful text generation
          content:
            application/json:
              schema:
                type: object
                properties:
                  text:
                    type: string
                  usage:
                    type: object
                    properties:
                      inputTokens:
                        type: integer
                        minimum: 0
                      outputTokens:
                        type: integer
                        minimum: 0
                      totalTokens:
                        type: integer
                        minimum: 0
                    required:
                      - inputTokens
                      - outputTokens
                      - totalTokens
                  sessionId:
                    type: string
                required:
                  - text
                  - usage
                  - sessionId
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
                    enum: *a4
                  rawText:
                    type: string
                required:
                  - error
                  - code
        "401":
          description: Missing authorization header
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
        "403":
          description: Invalid API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
        "500":
          description: Internal server error or CLI error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
                    enum: *a4
                  rawText:
                    type: string
                required:
                  - error
                  - code
  /generate-object:
    post:
      summary: Generate structured JSON response
      description: Generates structured JSON response from Claude CLI. The schema is passed in the request to instruct Claude to output valid JSON.
      tags:
        - Generation
      security:
        - BearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                system:
                  type: string
                prompt:
                  type: string
                sessionId:
                  type: string
                model:
                  type: string
                allowedTools:
                  type: array
                  items:
                    type: string
                schema:
                  type: object
                  properties:
                    type:
                      type: string
                      enum: *a1
                    properties:
                      type: object
                      additionalProperties: {}
                    items: {}
                    $ref:
                      type: string
                    allOf:
                      type: array
                      items: {}
                    anyOf:
                      type: array
                      items: {}
                    oneOf:
                      type: array
                      items: {}
                    enum:
                      type: array
                      items: {}
                    const: {}
                maxTokens:
                  type: integer
                  exclusiveMinimum: 0
              required:
                - prompt
                - schema
      responses:
        "200":
          description: Successful object generation
          content:
            application/json:
              schema:
                type: object
                properties:
                  object: {}
                  rawText:
                    type: string
                  usage:
                    type: object
                    properties:
                      inputTokens:
                        type: integer
                        minimum: 0
                      outputTokens:
                        type: integer
                        minimum: 0
                      totalTokens:
                        type: integer
                        minimum: 0
                    required:
                      - inputTokens
                      - outputTokens
                      - totalTokens
                  sessionId:
                    type: string
                required:
                  - rawText
                  - usage
                  - sessionId
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
                    enum: *a4
                  rawText:
                    type: string
                required:
                  - error
                  - code
        "401":
          description: Missing authorization header
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
        "403":
          description: Invalid API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
        "500":
          description: Internal server error or CLI error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
                    enum: *a4
                  rawText:
                    type: string
                required:
                  - error
                  - code
  /stream:
    post:
      summary: Stream text response via SSE
      description: "Streams Claude CLI output using Server-Sent Events (SSE). Provides real-time streaming of Claude's response with session management and usage tracking. Event types: session (session ID), text (streaming content), result (final usage stats), error (errors), done (stream complete)."
      tags:
        - Streaming
      security:
        - BearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                system:
                  type: string
                prompt:
                  type: string
                sessionId:
                  type: string
                model:
                  type: string
                allowedTools:
                  type: array
                  items:
                    type: string
              required:
                - prompt
      responses:
        "200":
          description: SSE stream with real-time Claude CLI output
          content:
            text/event-stream:
              schema:
                type: string
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
                    enum: *a4
                  rawText:
                    type: string
                required:
                  - error
                  - code
        "401":
          description: Missing authorization header
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
        "403":
          description: Invalid API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
  /stream-object:
    post:
      summary: Stream structured JSON objects via SSE
      description: "Streams partial JSON objects as they're generated using Server-Sent Events (SSE). Provides real-time streaming of structured data with partial object parsing. Event types: session (session ID), partial-object (partial JSON with parsed object), object (final validated object), result (final usage stats), error (errors), done (stream complete)."
      tags:
        - Streaming
      security:
        - BearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                system:
                  type: string
                prompt:
                  type: string
                sessionId:
                  type: string
                model:
                  type: string
                allowedTools:
                  type: array
                  items:
                    type: string
                schema:
                  type: object
                  properties:
                    type:
                      type: string
                      enum: *a1
                    properties:
                      type: object
                      additionalProperties: {}
                    items: {}
                    $ref:
                      type: string
                    allOf:
                      type: array
                      items: {}
                    anyOf:
                      type: array
                      items: {}
                    oneOf:
                      type: array
                      items: {}
                    enum:
                      type: array
                      items: {}
                    const: {}
              required:
                - prompt
                - schema
      responses:
        "200":
          description: SSE stream with real-time partial JSON objects
          content:
            text/event-stream:
              schema:
                type: string
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
                    enum: *a4
                  rawText:
                    type: string
                required:
                  - error
                  - code
        "401":
          description: Missing authorization header
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
        "403":
          description: Invalid API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
webhooks: {}