components:
  schemas:
    ChatCompletionRequest:
      additionalProperties: true
      example:
        max_tokens: 128
        messages:
          - content: Write a short haiku about distributed systems.
            role: user
        model: qwen/qwen3-235b-a22b-instruct-2507-fp8
        stream: false
      properties:
        input:
          anyOf:
            - type: string
            - items: {}
              type: array
            - additionalProperties: true
              properties: {}
              type: object
        max_tokens:
          minimum: 1
          type: integer
        messages:
          items: {}
          minItems: 1
          type: array
        model:
          minLength: 1
          type: string
        plugins:
          description: Optional per-request plugin list. Reserved Gonka plugin ids are `response-healing`, `web`, `file-parser` (PDF Inputs), and `privacy-sanitization`.
          items:
            anyOf:
              - additionalProperties: true
                properties:
                  enabled:
                    description: Set to false to disable the response-healing plugin for this request. Defaults to true.
                    type: boolean
                  id:
                    description: Enable response-healing plugin.
                    enum:
                      - response-healing
                    type: string
                required:
                  - id
                type: object
              - additionalProperties: true
                properties:
                  enabled:
                    description: Set to false to disable web search for this request when the plugin object is present.
                    type: boolean
                  engine:
                    description: OpenRouter-compatible web engine hint. In v1, omitted `engine` and explicit `engine:"exa"` are supported. Other values are rejected.
                    minLength: 1
                    type: string
                  exclude_domains:
                    description: Optional denylist of domains applied as shared filters across the logical web-search operation.
                    items:
                      minLength: 1
                      type: string
                    minItems: 1
                    type: array
                  id:
                    description: Enable web-search grounding for this request.
                    enum:
                      - web
                    type: string
                  include_domains:
                    description: Optional allowlist of domains applied as shared filters across the logical web-search operation.
                    items:
                      minLength: 1
                      type: string
                    minItems: 1
                    type: array
                  max_results:
                    description: Maximum number of web results for the logical request-level web-search operation. Internal child-search allocation remains server-managed.
                    minimum: 1
                    type: integer
                  search_prompt:
                    description: Proxy-local planning and grounding hint for web search. It never enables search by itself and is not forwarded verbatim to the Go service or Exa.
                    minLength: 1
                    type: string
                required:
                  - id
                type: object
              - additionalProperties: true
                description: OpenRouter-style PDF Inputs plugin. Use `plugins:[{id:"file-parser"}]` to override gonka-proxy PDF engine selection for this request.
                examples:
                  - id: file-parser
                    pdf:
                      engine: pdf-text
                  - id: file-parser
                    pdf:
                      engine: native
                properties:
                  id:
                    description: Enable the PDF Inputs override for this request. PDF file inputs also work without this plugin; use it only when you need to force a specific PDF engine.
                    enum:
                      - file-parser
                    type: string
                  pdf:
                    additionalProperties: false
                    description: Optional PDF Inputs override. `pdf-text` parses supported PDF URLs or data URLs locally and may append `message.annotations[]` in non-streaming responses. `native` forwards the original PDF file upstream unchanged. Missing `engine` means server-managed auto selection. Unsupported engines return `pdf_engine_not_supported`; explicit `native` may return `pdf_native_unavailable`.
                    examples:
                      - engine: pdf-text
                      - engine: native
                    properties:
                      engine:
                        anyOf:
                          - enum:
                              - pdf-text
                            type: string
                          - enum:
                              - native
                            type: string
                        description: PDF parser engine. Use `pdf-text` for local extraction from supported `http/https` URLs or `data:application/pdf;base64,...`, or `native` to forward the original PDF file upstream unchanged.
                    type: object
                required:
                  - id
                type: object
              - additionalProperties: true
                properties:
                  enabled:
                    type: boolean
                  id:
                    description: Enable privacy-sanitization plugin with the default server-managed privacy profile.
                    enum:
                      - privacy-sanitization
                    type: string
                  mode:
                    anyOf:
                      - enum:
                          - redact
                        type: string
                      - enum:
                          - tokenize
                        type: string
                      - enum:
                          - block
                        type: string
                    description: "Supported privacy modes: redact, tokenize, block."
                required:
                  - id
                  - mode
                type: object
              - additionalProperties: true
                properties:
                  enabled:
                    type: boolean
                  id:
                    minLength: 1
                    pattern: ^(?!(response-healing|file-parser|privacy-sanitization|web)$).+
                    type: string
                required:
                  - id
                type: object
          type: array
        preset:
          minLength: 1
          type: string
        response_format:
          additionalProperties: true
          properties:
            type:
              minLength: 1
              type: string
          required:
            - type
          type: object
        stream:
          type: boolean
        web_search_options:
          additionalProperties: true
          description: OpenRouter-compatible request-level web search options. This object never enables search. `web_search_options.search_context_size` is rejected in v1; other members are unsupported and must not change runtime behavior.
          properties: {}
          type: object
      required:
        - model
      type: object
    ChatCompletionResponse:
      additionalProperties: true
      example:
        choices:
          - finish_reason: stop
            index: 0
            message:
              annotations:
                - type: url_citation
                  url_citation:
                    content: SearXNG is a free internet metasearch engine...
                    end_index: 24
                    start_index: 0
                    title: SearXNG documentation
                    url: https://docs.searxng.org/
              content: |-
                Packets hum in night,
                Consensus finds steady light,
                Systems breathe as one.
              role: assistant
        created: 1761605442
        id: chatcmpl_abc123
        model: qwen/qwen3-235b-a22b-instruct-2507-fp8
        object: chat.completion
        usage:
          base_cost_usd: 8.3e-7
          completion_tokens: 24
          platform_fee_usd: 8e-8
          prompt_tokens: 22
          server_tool_use:
            web_search_requests: 1
          total_cost_usd: 9.1e-7
          total_tokens: 46
      properties: {}
      type: object
    DashboardModelsEnrichedModel:
      properties:
        available:
          description: Whether model is currently available on-chain
          type: boolean
        hfMetadata:
          $ref: "#/components/schemas/DashboardModelsHfMetadata"
          description: HuggingFace model metadata (null if unavailable)
          nullable: true
        id:
          description: Model identifier for API requests
          type: string
        participantCount:
          description: Number of network participants hosting this model
          type: number
      required:
        - id
        - available
        - participantCount
        - hfMetadata
      type: object
    DashboardModelsHfMetadata:
      description: HuggingFace model metadata
      properties:
        contextLength:
          description: Context window size in tokens
          nullable: true
          type: number
        description:
          description: Short description from model README
          nullable: true
          type: string
        downloads:
          description: Total downloads on HuggingFace
          type: number
        id:
          description: Model identifier
          type: string
        lastModified:
          description: Last modification timestamp
          nullable: true
          type: string
        likes:
          description: Number of likes on HuggingFace
          type: number
        pipelineTag:
          description: Model task type (e.g., text-generation)
          nullable: true
          type: string
      required:
        - id
        - contextLength
        - downloads
        - likes
        - pipelineTag
        - lastModified
        - description
      type: object
    DashboardModelsResponse:
      additionalProperties: false
      example:
        data:
          models:
            - available: true
              hfMetadata:
                contextLength: 262144
                description: Qwen3-235B-A22B-Instruct-2507-FP8 Highlights We introduce the updated version...
                downloads: 747562
                id: qwen/qwen3-235b-a22b-instruct-2507-fp8
                lastModified: 2025-09-17T06:53:28.000Z
                likes: 146
                pipelineTag: text-generation
              id: qwen/qwen3-235b-a22b-instruct-2507-fp8
              participantCount: 128
        success: true
      properties:
        data:
          properties:
            models:
              items:
                $ref: "#/components/schemas/DashboardModelsEnrichedModel"
              type: array
          required:
            - models
          type: object
        success:
          enum:
            - true
          type: boolean
      required:
        - success
        - data
      type: object
    Model:
      properties:
        context_length:
          description: Maximum context window in tokens
          nullable: true
          type: number
        created:
          description: Unix timestamp (seconds)
          type: number
        description:
          description: Model description
          nullable: true
          type: string
        id:
          description: Unique model identifier
          type: string
        name:
          description: Human-readable model name
          type: string
        object:
          enum:
            - model
          type: string
        owned_by:
          description: Model owner
          type: string
        pricing:
          $ref: "#/components/schemas/ModelPricing"
      required:
        - id
        - object
        - created
        - owned_by
      type: object
    ModelListResponse:
      example:
        data:
          - context_length: 262144
            created: 0
            description: Qwen3-235B-A22B-Instruct-2507-FP8 Highlights We introduce the updated version...
            id: qwen/qwen3-235b-a22b-instruct-2507-fp8
            name: Qwen3 235B A22B Instruct 2507 FP8
            object: model
            owned_by: gonka
            pricing:
              input: 0.00099
              output: 0.00099
        object: list
      properties:
        data:
          items:
            $ref: "#/components/schemas/Model"
          type: array
        object:
          enum:
            - list
          type: string
      required:
        - object
        - data
      type: object
    ModelPricing:
      properties:
        input:
          description: Cost per 1M input tokens in USD
          type: number
        output:
          description: Cost per 1M output tokens in USD
          type: number
      required:
        - input
        - output
      type: object
    OpenAIErrorResponse:
      additionalProperties: false
      example:
        error:
          code: invalid_api_key
          message: Invalid credentials.
          param: null
          type: authentication_error
      properties:
        error:
          additionalProperties: false
          properties:
            code:
              nullable: true
              type: string
            message:
              type: string
            metadata:
              additionalProperties: true
              properties:
                balance_usd:
                  type: string
                estimated_cost_usd:
                  type: string
                model_slug:
                  type: string
                retry_after_seconds:
                  type: number
              type: object
            param:
              nullable: true
              type: string
            type:
              type: string
          required:
            - message
            - type
          type: object
      required:
        - error
      type: object
    PublicModelsActivityResponse:
      additionalProperties: false
      properties:
        data:
          additionalProperties: false
          properties:
            generatedAt:
              format: date-time
              type: string
            modelId:
              type: string
            series:
              items:
                additionalProperties: false
                properties:
                  completionTokens:
                    type: string
                  promptTokens:
                    type: string
                  reasoningTokens:
                    type: string
                  totalTokens:
                    type: string
                  ts:
                    format: date
                    type: string
                required:
                  - ts
                  - promptTokens
                  - reasoningTokens
                  - completionTokens
                  - totalTokens
                type: object
              type: array
            summary:
              additionalProperties: false
              properties:
                completionTokens:
                  type: string
                promptTokens:
                  type: string
                reasoningTokens:
                  type: string
                totalTokens:
                  type: string
              required:
                - promptTokens
                - reasoningTokens
                - completionTokens
                - totalTokens
              type: object
            window:
              additionalProperties: false
              properties:
                bucket:
                  enum:
                    - day
                  type: string
                from:
                  description: ISO 8601 timestamp in UTC (date or date-time input normalized to date-time).
                  example: 2026-02-18T00:00:00.000Z
                  type: string
                timezone:
                  enum:
                    - UTC
                  type: string
                to:
                  description: ISO 8601 timestamp in UTC (date or date-time input normalized to date-time).
                  example: 2026-02-24T00:00:00.000Z
                  type: string
              required:
                - from
                - to
                - timezone
                - bucket
              type: object
          required:
            - modelId
            - window
            - summary
            - series
            - generatedAt
          type: object
        success:
          enum:
            - true
          type: boolean
      required:
        - success
        - data
      type: object
    PublicModelsPerformanceMetricResponse:
      additionalProperties: false
      properties:
        data:
          additionalProperties: false
          properties:
            modelId:
              type: string
            series:
              items:
                additionalProperties: false
                properties:
                  count:
                    type: number
                  ts:
                    anyOf:
                      - format: date-time
                        type: string
                      - format: date
                        type: string
                  value:
                    nullable: true
                    type: number
                required:
                  - ts
                  - value
                  - count
                type: object
              type: array
            summary:
              additionalProperties: false
              properties:
                avg:
                  nullable: true
                  type: number
                insufficientData:
                  type: boolean
                max:
                  nullable: true
                  type: number
                min:
                  nullable: true
                  type: number
                p50:
                  nullable: true
                  type: number
                sampleCount:
                  type: number
              required:
                - min
                - max
                - avg
                - p50
                - sampleCount
                - insufficientData
              type: object
            window:
              additionalProperties: false
              properties:
                bucket:
                  anyOf:
                    - enum:
                        - hour
                      type: string
                    - enum:
                        - day
                      type: string
                from:
                  description: Window start timestamp in UTC.
                  example: 2026-02-18T00:00:00.000Z
                  format: date-time
                  type: string
                timezone:
                  enum:
                    - UTC
                  type: string
                to:
                  description: Window end timestamp in UTC.
                  example: 2026-02-24T23:59:59.999Z
                  format: date-time
                  type: string
              required:
                - from
                - to
                - timezone
                - bucket
              type: object
          required:
            - modelId
            - window
            - series
            - summary
          type: object
        success:
          enum:
            - true
          type: boolean
      required:
        - success
        - data
      type: object
    PublicModelsPerformanceResponse:
      additionalProperties: false
      properties:
        data:
          additionalProperties: false
          properties:
            metrics:
              additionalProperties: false
              properties:
                e2e:
                  additionalProperties: false
                  properties:
                    series:
                      items:
                        additionalProperties: false
                        properties:
                          count:
                            type: number
                          ts:
                            anyOf:
                              - format: date-time
                                type: string
                              - format: date
                                type: string
                          value:
                            nullable: true
                            type: number
                        required:
                          - ts
                          - value
                          - count
                        type: object
                      type: array
                    summary:
                      additionalProperties: false
                      properties:
                        avg:
                          nullable: true
                          type: number
                        insufficientData:
                          type: boolean
                        sampleCount:
                          type: number
                      required:
                        - avg
                        - sampleCount
                        - insufficientData
                      type: object
                    unit:
                      type: string
                  required:
                    - unit
                    - series
                    - summary
                  type: object
                latency:
                  additionalProperties: false
                  properties:
                    series:
                      items:
                        additionalProperties: false
                        properties:
                          count:
                            type: number
                          ts:
                            anyOf:
                              - format: date-time
                                type: string
                              - format: date
                                type: string
                          value:
                            nullable: true
                            type: number
                        required:
                          - ts
                          - value
                          - count
                        type: object
                      type: array
                    summary:
                      additionalProperties: false
                      properties:
                        avg:
                          nullable: true
                          type: number
                        insufficientData:
                          type: boolean
                        sampleCount:
                          type: number
                      required:
                        - avg
                        - sampleCount
                        - insufficientData
                      type: object
                    unit:
                      type: string
                  required:
                    - unit
                    - series
                    - summary
                  type: object
                throughput:
                  additionalProperties: false
                  properties:
                    series:
                      items:
                        additionalProperties: false
                        properties:
                          count:
                            type: number
                          ts:
                            anyOf:
                              - format: date-time
                                type: string
                              - format: date
                                type: string
                          value:
                            nullable: true
                            type: number
                        required:
                          - ts
                          - value
                          - count
                        type: object
                      type: array
                    summary:
                      additionalProperties: false
                      properties:
                        avg:
                          nullable: true
                          type: number
                        insufficientData:
                          type: boolean
                        sampleCount:
                          type: number
                      required:
                        - avg
                        - sampleCount
                        - insufficientData
                      type: object
                    unit:
                      type: string
                  required:
                    - unit
                    - series
                    - summary
                  type: object
              required:
                - throughput
                - latency
                - e2e
              type: object
            modelId:
              type: string
            window:
              additionalProperties: false
              properties:
                bucket:
                  anyOf:
                    - enum:
                        - hour
                      type: string
                    - enum:
                        - day
                      type: string
                from:
                  description: Window start timestamp in UTC.
                  example: 2026-02-18T00:00:00.000Z
                  format: date-time
                  type: string
                timezone:
                  enum:
                    - UTC
                  type: string
                to:
                  description: Window end timestamp in UTC.
                  example: 2026-02-24T23:59:59.999Z
                  format: date-time
                  type: string
              required:
                - from
                - to
                - timezone
                - bucket
              type: object
          required:
            - modelId
            - window
            - metrics
          type: object
        success:
          enum:
            - true
          type: boolean
      required:
        - success
        - data
      type: object
    PublicModelsUptimeResponse:
      additionalProperties: false
      properties:
        data:
          additionalProperties: false
          properties:
            finishReasons:
              additionalProperties: false
              properties:
                series:
                  items:
                    additionalProperties: false
                    properties:
                      count:
                        type: number
                      ts:
                        anyOf:
                          - format: date-time
                            type: string
                          - format: date
                            type: string
                      values:
                        additionalProperties: false
                        properties:
                          content_filter:
                            nullable: true
                            type: number
                          length:
                            nullable: true
                            type: number
                          other:
                            nullable: true
                            type: number
                          stop:
                            nullable: true
                            type: number
                          tool_calls:
                            nullable: true
                            type: number
                          unknown:
                            nullable: true
                            type: number
                        required:
                          - stop
                          - length
                          - tool_calls
                          - content_filter
                          - other
                          - unknown
                        type: object
                    required:
                      - ts
                      - count
                      - values
                    type: object
                  type: array
                summary:
                  additionalProperties: false
                  properties:
                    counts:
                      additionalProperties: false
                      properties:
                        content_filter:
                          type: number
                        length:
                          type: number
                        other:
                          type: number
                        stop:
                          type: number
                        tool_calls:
                          type: number
                        unknown:
                          type: number
                      required:
                        - stop
                        - length
                        - tool_calls
                        - content_filter
                        - other
                        - unknown
                      type: object
                    insufficientData:
                      type: boolean
                    percent:
                      additionalProperties: false
                      properties:
                        content_filter:
                          type: number
                        length:
                          type: number
                        other:
                          type: number
                        stop:
                          type: number
                        tool_calls:
                          type: number
                        unknown:
                          type: number
                      required:
                        - stop
                        - length
                        - tool_calls
                        - content_filter
                        - other
                        - unknown
                      type: object
                    sampleCount:
                      type: number
                  required:
                    - counts
                    - percent
                    - sampleCount
                    - insufficientData
                  type: object
                unit:
                  enum:
                    - percent
                  type: string
              required:
                - unit
                - series
                - summary
              type: object
            generatedAt:
              format: date-time
              type: string
            modelId:
              type: string
            uptime:
              additionalProperties: false
              properties:
                series:
                  items:
                    additionalProperties: false
                    properties:
                      count:
                        type: number
                      error:
                        type: number
                      interruptedExcluded:
                        type: number
                      success:
                        type: number
                      timeout:
                        type: number
                      ts:
                        anyOf:
                          - format: date-time
                            type: string
                          - format: date
                            type: string
                      value:
                        nullable: true
                        type: number
                    required:
                      - ts
                      - value
                      - count
                      - success
                      - error
                      - timeout
                      - interruptedExcluded
                    type: object
                  type: array
                summary:
                  additionalProperties: false
                  properties:
                    avg:
                      nullable: true
                      type: number
                    insufficientData:
                      type: boolean
                    max:
                      nullable: true
                      type: number
                    min:
                      nullable: true
                      type: number
                    sampleCount:
                      type: number
                  required:
                    - min
                    - max
                    - avg
                    - sampleCount
                    - insufficientData
                  type: object
                unit:
                  enum:
                    - percent
                  type: string
              required:
                - unit
                - series
                - summary
              type: object
            window:
              additionalProperties: false
              properties:
                bucket:
                  anyOf:
                    - enum:
                        - hour
                      type: string
                    - enum:
                        - day
                      type: string
                from:
                  description: Window start timestamp in UTC.
                  example: 2026-02-18T00:00:00.000Z
                  format: date-time
                  type: string
                timezone:
                  enum:
                    - UTC
                  type: string
                to:
                  description: Window end timestamp in UTC.
                  example: 2026-02-24T23:59:59.999Z
                  format: date-time
                  type: string
              required:
                - from
                - to
                - timezone
                - bucket
              type: object
          required:
            - modelId
            - window
            - uptime
            - finishReasons
            - generatedAt
          type: object
        success:
          enum:
            - true
          type: boolean
      required:
        - success
        - data
      type: object
    PublicPricingResponse:
      additionalProperties: false
      example:
        data:
          fees:
            platformFeeRate: 0.1
          models:
            - id: qwen/qwen3-235b-a22b-instruct-2507-fp8
              usdPer1MTokens:
                network: 0.00061
                platformFee: 0.000061
                total: 0.000671
          rate:
            usdPer1MComputeUnits: 0.00061
            usdPerComputeUnit: "0.00000000061"
          updatedAt: 2026-02-24T20:01:32.546Z
        success: true
      properties:
        data:
          additionalProperties: false
          properties:
            fees:
              additionalProperties: false
              properties:
                platformFeeRate:
                  type: number
              required:
                - platformFeeRate
              type: object
            models:
              items:
                additionalProperties: false
                properties:
                  id:
                    type: string
                  usdPer1MTokens:
                    additionalProperties: false
                    properties:
                      network:
                        description: Network-side USD price for 1,000,000 tokens at the current atomic-unit rate
                        type: number
                      platformFee:
                        description: Platform fee USD amount for 1,000,000 tokens
                        type: number
                      total:
                        description: Primary user-facing USD price for 1,000,000 tokens
                        type: number
                    required:
                      - network
                      - platformFee
                      - total
                    type: object
                required:
                  - id
                  - usdPer1MTokens
                type: object
              type: array
            rate:
              additionalProperties: false
              properties:
                usdPer1MComputeUnits:
                  description: USD price for 1,000,000 atomic GNK units (compute units)
                  type: number
                usdPerComputeUnit:
                  description: USD price for one atomic GNK unit (one compute unit / ngonka)
                  type: string
              required:
                - usdPerComputeUnit
                - usdPer1MComputeUnits
              type: object
            updatedAt:
              description: Timestamp of the pricing-service snapshot used to compute this pricing payload
              format: date-time
              type: string
          required:
            - updatedAt
            - rate
            - fees
            - models
          type: object
        success:
          enum:
            - true
          type: boolean
      required:
        - success
        - data
      type: object
    WhoamiResponse:
      additionalProperties: false
      properties:
        data:
          additionalProperties: false
          properties:
            apiKey:
              additionalProperties: false
              properties:
                expiresAt:
                  format: date-time
                  nullable: true
                  type: string
                lastUsed:
                  format: date-time
                  nullable: true
                  type: string
                maskedKey:
                  description: Masked API key (prefix + ... + last4)
                  type: string
                name:
                  type: string
                status:
                  anyOf:
                    - enum:
                        - active
                      type: string
                    - enum:
                        - disabled
                      type: string
                    - enum:
                        - expired
                      type: string
              required:
                - name
                - maskedKey
                - status
                - expiresAt
                - lastUsed
              type: object
            balance:
              additionalProperties: false
              properties:
                status:
                  anyOf:
                    - enum:
                        - active
                      type: string
                    - enum:
                        - low
                      type: string
                    - enum:
                        - suspended
                      type: string
                usd:
                  description: Balance in USD (fixed 2 decimals)
                  type: string
              required:
                - usd
                - status
              type: object
            user:
              additionalProperties: false
              properties:
                emailMasked:
                  description: Masked username part of email (domain omitted)
                  type: string
                emailVerified:
                  type: boolean
              required:
                - emailMasked
                - emailVerified
              type: object
          required:
            - user
            - apiKey
            - balance
          type: object
        success:
          enum:
            - true
          type: boolean
      required:
        - success
        - data
      type: object
    public.shared.ApiError:
      additionalProperties: false
      example:
        error:
          message: Invalid url
          requestId: req_example_123
          statusCode: 400
          timestamp: 2026-02-24T20:02:01.430Z
        success: false
      properties:
        error:
          additionalProperties: false
          properties:
            code:
              minLength: 1
              type: string
            message:
              type: string
            path:
              type: string
            requestId:
              type: string
            statusCode:
              type: integer
            timestamp:
              format: date-time
              type: string
          required:
            - message
            - statusCode
            - requestId
            - timestamp
          type: object
        success:
          enum:
            - false
          type: boolean
      required:
        - success
        - error
      type: object
    whoami.ApiError:
      additionalProperties: false
      example:
        error:
          message: Invalid url
          requestId: req_example_123
          statusCode: 400
          timestamp: 2026-02-24T20:02:01.430Z
        success: false
      properties:
        error:
          additionalProperties: false
          properties:
            code:
              minLength: 1
              type: string
            message:
              type: string
            path:
              type: string
            requestId:
              type: string
            statusCode:
              type: integer
            timestamp:
              format: date-time
              type: string
          required:
            - message
            - statusCode
            - requestId
            - timestamp
          type: object
        success:
          enum:
            - false
          type: boolean
      required:
        - success
        - error
      type: object
  securitySchemes:
    bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http
info:
  description: OpenAI-compatible proxy API for Gonka GPU network
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  title: Gonka Proxy API
  version: 1.0.0
openapi: 3.0.3
paths:
  /api/v1/dashboard/models:
    get:
      description: Get list of available Gonka network models with HuggingFace metadata (downloads, likes, context length).
      operationId: dashboard.models.list
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DashboardModelsResponse"
          description: Default Response
      tags:
        - Dashboard
      x-lifecycle: beta
  /api/v1/public/models/{modelId}/activity:
    get:
      description: Get daily activity for a model (tokens only)
      operationId: public.models.activity.get
      parameters:
        - description: Window start in ISO 8601 date or datetime format.
          example: 2026-02-18
          in: query
          name: from
          required: false
          schema:
            type: string
        - description: Window end in ISO 8601 date or datetime format.
          example: 2026-02-24
          in: query
          name: to
          required: false
          schema:
            type: string
        - description: Model identifier. URL-encode `/` in path segment (for example `qwen%2Fqwen3-235b-a22b-instruct-2507-fp8`).
          example: qwen%2Fqwen3-235b-a22b-instruct-2507-fp8
          in: path
          name: modelId
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicModelsActivityResponse"
          description: Default Response
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/public.shared.ApiError"
          description: Default Response
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/public.shared.ApiError"
          description: Default Response
        "500":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/public.shared.ApiError"
          description: Default Response
      tags:
        - Public
      x-lifecycle: beta
  /api/v1/public/models/{modelId}/performance:
    get:
      description: Get model performance metrics
      operationId: public.models.performance.get
      parameters:
        - description: Window start in ISO 8601 date or datetime format.
          example: 2026-02-18T00:00:00Z
          in: query
          name: from
          required: false
          schema:
            type: string
        - description: Window end in ISO 8601 date or datetime format.
          example: 2026-02-24T23:59:59Z
          in: query
          name: to
          required: false
          schema:
            type: string
        - description: Optional aggregation bucket. Supported values are `hour` and `day`.
          example: day
          in: query
          name: bucket
          required: false
          schema:
            type: string
        - description: Model identifier. URL-encode `/` in path segment (for example `qwen%2Fqwen3-235b-a22b-instruct-2507-fp8`).
          example: qwen%2Fqwen3-235b-a22b-instruct-2507-fp8
          in: path
          name: modelId
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicModelsPerformanceResponse"
          description: Default Response
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/public.shared.ApiError"
          description: Default Response
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/public.shared.ApiError"
          description: Default Response
        "500":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/public.shared.ApiError"
          description: Default Response
      tags:
        - Public
      x-lifecycle: beta
  /api/v1/public/models/{modelId}/performance/{metric}:
    get:
      description: Get model performance details for a metric
      operationId: public.models.performance.metric.get
      parameters:
        - description: Window start in ISO 8601 date or datetime format.
          example: 2026-02-18T00:00:00Z
          in: query
          name: from
          required: false
          schema:
            type: string
        - description: Window end in ISO 8601 date or datetime format.
          example: 2026-02-24T23:59:59Z
          in: query
          name: to
          required: false
          schema:
            type: string
        - description: Optional aggregation bucket. Supported values are `hour` and `day`.
          example: day
          in: query
          name: bucket
          required: false
          schema:
            type: string
        - description: Model identifier. URL-encode `/` in path segment (for example `qwen%2Fqwen3-235b-a22b-instruct-2507-fp8`).
          example: qwen%2Fqwen3-235b-a22b-instruct-2507-fp8
          in: path
          name: modelId
          required: true
          schema:
            type: string
        - in: path
          name: metric
          required: true
          schema:
            anyOf:
              - enum:
                  - throughput
                type: string
              - enum:
                  - latency
                type: string
              - enum:
                  - e2e
                type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicModelsPerformanceMetricResponse"
          description: Default Response
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/public.shared.ApiError"
          description: Default Response
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/public.shared.ApiError"
          description: Default Response
        "500":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/public.shared.ApiError"
          description: Default Response
      tags:
        - Public
      x-lifecycle: beta
  /api/v1/public/models/{modelId}/uptime:
    get:
      description: Get model reliability metrics (uptime + finish reasons)
      operationId: public.models.uptime.get
      parameters:
        - description: Window start in ISO 8601 date or datetime format.
          example: 2026-02-18T00:00:00Z
          in: query
          name: from
          required: false
          schema:
            type: string
        - description: Window end in ISO 8601 date or datetime format.
          example: 2026-02-24T23:59:59Z
          in: query
          name: to
          required: false
          schema:
            type: string
        - description: Optional aggregation bucket. Supported values are `hour` and `day`.
          example: day
          in: query
          name: bucket
          required: false
          schema:
            type: string
        - description: Model identifier. URL-encode `/` in path segment (for example `qwen%2Fqwen3-235b-a22b-instruct-2507-fp8`).
          example: qwen%2Fqwen3-235b-a22b-instruct-2507-fp8
          in: path
          name: modelId
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicModelsUptimeResponse"
          description: Default Response
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/public.shared.ApiError"
          description: Default Response
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/public.shared.ApiError"
          description: Default Response
        "500":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/public.shared.ApiError"
          description: Default Response
      tags:
        - Public
      x-lifecycle: beta
  /api/v1/public/pricing:
    get:
      description: Get computed per-model pricing in USD ($/1M tokens)
      operationId: public.pricing.get
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicPricingResponse"
          description: Default Response
        "500":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/public.shared.ApiError"
          description: Default Response
        "503":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/public.shared.ApiError"
          description: Default Response
      tags:
        - Public
      x-lifecycle: stable
  /api/v1/whoami:
    get:
      description: "Returns safe account information for the provided API key. Read-only: does not update lastUsed or enforce balance/limits."
      operationId: whoami.get
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WhoamiResponse"
          description: Default Response
        "401":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/whoami.ApiError"
          description: Default Response
        "500":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/whoami.ApiError"
          description: Default Response
      security:
        - bearerAuth: []
      summary: API key WhoAmI (diagnostic)
      tags:
        - Auth
      x-lifecycle: beta
  /v1/chat/completions:
    post:
      description: 'Create a chat completion (OpenAI-compatible). `stream=false` returns JSON, `stream=true` returns `text/event-stream` (SSE). Explicit web search is supported for authenticated requests via `plugins:[{id:"web"}]` or `model:"...:online"`. Streaming web-search requests reject `X-Idempotency-Key` with `400 invalid_request_error`; use idempotency keys only for non-streaming safe retries. In v1, omitted `plugins[].engine` and explicit `engine:"exa"` are both supported; other web engines are rejected with `400 invalid_request_error`. When both `:online` and an explicit `web` plugin are present, the explicit plugin owns search options. `include_domains` and `exclude_domains` are supported on the `web` plugin as shared domain filters. `max_results` is the logical maximum number of web results for the full request; internal child-search allocation remains server-managed. `search_prompt` is a proxy-local planning and grounding hint and is not forwarded verbatim to the Go service or Exa. `web_search_options` never enables search; `web_search_options.search_context_size` is rejected, and other members are unsupported in v1. Non-streaming web-search responses may include `message.annotations[]`; streaming web-search responses remain ordinary chat SSE chunks without custom citation events. PDF file inputs work without plugins; `file-parser` is an optional PDF Inputs override for `pdf.engine` (`native` | `pdf-text`). `pdf-text` parses supported `http/https` URLs or `data:application/pdf;base64,...` locally and may append `message.annotations[]` in non-streaming responses. `native` forwards the original PDF file upstream unchanged and may return `400 invalid_request_error` with code `pdf_native_unavailable` when native PDF processing is unavailable for the selected model. Also supports `response-healing` and `privacy-sanitization` (`mode`: `redact` | `tokenize` | `block`).'
      operationId: createChatCompletion
      parameters:
        - description: Optional idempotency key for safe non-streaming retries. Streaming web-search requests reject this header with 400 invalid_request_error.
          example: idem_01J0ABCD2EFGH3IJK4LMN5PQRS
          in: header
          name: x-idempotency-key
          required: false
          schema:
            maxLength: 64
            minLength: 1
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ChatCompletionRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChatCompletionResponse"
            text/event-stream:
              examples:
                chunk:
                  summary: Streaming chunk frame
                  value: |+
                    data: {"id":"chatcmpl_stream_123","object":"chat.completion.chunk","created":1761605442,"model":"qwen/qwen3-235b-a22b-instruct-2507-fp8","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

                done:
                  summary: Stream completion frame
                  value: |+
                    data: [DONE]

              schema:
                description: "Server-Sent Events stream. Each `data:` frame contains a chat completion chunk JSON object; stream ends with `data: [DONE]`."
                type: string
          description: Non-streaming JSON response (`stream=false`) or SSE stream (`text/event-stream`) when `stream=true`.
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OpenAIErrorResponse"
          description: Default Response
        "401":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OpenAIErrorResponse"
          description: Default Response
        "403":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OpenAIErrorResponse"
          description: Default Response
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OpenAIErrorResponse"
          description: Default Response
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OpenAIErrorResponse"
          description: Default Response
        "413":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OpenAIErrorResponse"
          description: Default Response
        "429":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OpenAIErrorResponse"
          description: Default Response
        "500":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OpenAIErrorResponse"
          description: Default Response
        "502":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OpenAIErrorResponse"
          description: Default Response
        "503":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OpenAIErrorResponse"
          description: Default Response
        "504":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OpenAIErrorResponse"
          description: Default Response
      security:
        - bearerAuth: []
      summary: Create chat completion
      tags:
        - Chat
      x-lifecycle: stable
  /v1/models:
    get:
      description: Returns a list of available models with metadata including pricing. Requires API key authentication.
      operationId: listModels
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModelListResponse"
          description: Default Response
        "401":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OpenAIErrorResponse"
          description: Default Response
        "503":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OpenAIErrorResponse"
          description: Default Response
      security:
        - bearerAuth: []
      summary: List available models
      tags:
        - Models
      x-lifecycle: stable
servers:
  - url: https://api.gonkagate.com
tags:
  - description: Authentication endpoints
    name: Auth
  - description: Public API endpoints
    name: Public
  - description: Dashboard API endpoints
    name: Dashboard
  - description: OpenAI-compatible chat endpoints
    name: Chat
  - description: OpenAI-compatible model endpoints
    name: Models
