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: {}