{
  "openapi": "3.1.0",
  "info": {
    "title": "oqllm API & POA Gateway",
    "version": "0.2.0",
    "description": "Unified multi-format gateway for Procedure-Oriented Architecture (POA), LLM proxy, multi-tenant API key authentication, quotas, and distributed mesh federation. Routes natural language (PL/EN), voice commands, proc:// URIs, and urn: blocks across dockuri, paxlet, taskand, and subllm with <50ms decision latency.",
    "contact": {
      "name": "Softreck / oqllm",
      "url": "https://oqllm.com"
    }
  },
  "servers": [
    {
      "url": "https://api.oqllm.com",
      "description": "Production API Gateway (TLS/HTTPS)"
    },
    {
      "url": "https://proxy.oqllm.com",
      "description": "Production High-Availability Mesh Proxy"
    },
    {
      "url": "http://127.0.0.1:11437",
      "description": "Local oqllm-proxy Node Loopback"
    }
  ],
  "paths": {
    "/health/": {
      "get": {
        "summary": "Service Healthcheck",
        "description": "Returns real-time health, version, active node domain, and mesh status.",
        "responses": {
          "200": {
            "description": "Healthy service status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/models/": {
      "get": {
        "summary": "Models Catalog",
        "description": "Returns OpenAI-compatible catalog of available routing, proxy, and completion models.",
        "responses": {
          "200": {
            "description": "List of models",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelListResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/poa/": {
      "get": {
        "summary": "Unified POA Registry",
        "description": "Returns the unified catalog of registered addressable POA operations across dockuri, paxlet, taskand, heyasa, and oqlos.",
        "responses": {
          "200": {
            "description": "Full registry object",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PoaRegistryResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Multi-format POA Intent Route or Dispatch",
        "description": "Selects the optimal addressable operation in <50ms based on query format (proc:// URI, urn:, natural language PL/EN, or voice commands). Requires Bearer API key or Session token.",
        "security": [
          {"BearerAuth": []},
          {"SessionTokenAuth": []},
          {"ApiKeyHeaderAuth": []}
        ],
        "parameters": [
          {
            "name": "action",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["route", "dispatch"],
              "default": "route"
            },
            "description": "Set to 'dispatch' to queue or execute the resolved procedure."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PoaRouteRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Routing decision or dispatch receipt",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PoaRouteResponse"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required or invalid key"
          },
          "429": {
            "description": "Rate limit exceeded (e.g. 120 RPM)"
          }
        }
      }
    },
    "/v1/poa/dispatch": {
      "post": {
        "summary": "POA Intent Dispatch Execution",
        "description": "Executes the selected procedure and returns dispatch tracking status.",
        "security": [
          {"BearerAuth": []},
          {"SessionTokenAuth": []},
          {"ApiKeyHeaderAuth": []}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PoaRouteRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Dispatch receipt",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PoaRouteResponse"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          }
        }
      }
    },
    "/v1/auth/request-code": {
      "post": {
        "summary": "Request Passwordless Login Code",
        "description": "Generates a 6-digit magic verification code. Validates against disposable mail and enforces anti-spam rate limiting (max 3/hour per email, max 5/hour per IP).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "example": "developer@softreck.dev"
                  }
                },
                "required": ["email"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verification code generated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {"type": "boolean"},
                    "email": {"type": "string"},
                    "expires_in_seconds": {"type": "integer"},
                    "code_preview": {"type": "string"},
                    "message": {"type": "string"}
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid or disposable email address"
          },
          "429": {
            "description": "Anti-spam rate limit exceeded"
          }
        }
      }
    },
    "/v1/auth/verify": {
      "post": {
        "summary": "Verify Code & Acquire Session",
        "description": "Exchanges 6-digit verification code for a session token.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {"type": "string", "format": "email"},
                  "code": {"type": "string", "example": "123456"}
                },
                "required": ["email", "code"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session established",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {"type": "boolean"},
                    "session_token": {"type": "string"},
                    "user": {"type": "object"}
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or expired verification code"
          }
        }
      }
    },
    "/v1/auth/keys": {
      "get": {
        "summary": "List User API Keys",
        "description": "Lists all active and revoked API keys belonging to the authenticated account.",
        "security": [{"SessionTokenAuth": []}],
        "responses": {
          "200": {
            "description": "List of API keys",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {"type": "boolean"},
                    "email": {"type": "string"},
                    "keys": {
                      "type": "array",
                      "items": {"$ref": "#/components/schemas/ApiKeyRecord"}
                    }
                  }
                }
              }
            }
          },
          "401": {"description": "Session required"}
        }
      },
      "post": {
        "summary": "Generate New API Key",
        "description": "Generates a new API key (`oqllm_live_...`) with configured RPM and daily token limit.",
        "security": [{"SessionTokenAuth": []}],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {"type": "string", "example": "Desktop Worker"},
                  "tier": {"type": "string", "enum": ["developer", "pro", "enterprise"], "default": "developer"},
                  "scopes": {
                    "type": "array",
                    "description": "Authorized channels and permissions (e.g. all, voice, dsl, uri, urn, user:config, mesh:manage)",
                    "items": {"type": "string"},
                    "default": ["all"]
                  },
                  "format_limits": {
                    "type": "object",
                    "description": "Optional custom rate limits (requests per minute) for each data format (nl, uri, urn, voice)",
                    "properties": {
                      "nl": {"type": "integer", "example": 60},
                      "uri": {"type": "integer", "example": 120},
                      "urn": {"type": "integer", "example": 240},
                      "voice": {"type": "integer", "example": 30}
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Key created successfully (shown once in full)",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/CreatedApiKeyResponse"}
              }
            }
          },
          "401": {"description": "Session required"}
        }
      }
    },
    "/v1/auth/keys/{key_id}": {
      "delete": {
        "summary": "Revoke API Key",
        "description": "Revokes an API key belonging to the authenticated account.",
        "security": [{"SessionTokenAuth": []}],
        "parameters": [
          {
            "name": "key_id",
            "in": "path",
            "required": true,
            "schema": {"type": "string"}
          }
        ],
        "responses": {
          "200": {"description": "Key revoked successfully"},
          "404": {"description": "Key not found"}
        }
      }
    },
    "/v1/auth/usage": {
      "get": {
        "summary": "Private Usage & Quotas (SubLLM Service 8788)",
        "description": "Returns private real-time quotas, token allowances, RPM usage, and recent attempts.",
        "security": [
          {"BearerAuth": []},
          {"SessionTokenAuth": []},
          {"ApiKeyHeaderAuth": []}
        ],
        "responses": {
          "200": {
            "description": "Account usage metrics and quota status",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/UserUsageQuotasResponse"}
              }
            }
          },
          "401": {"description": "Authentication required"}
        }
      }
    },
    "/v1/mesh/": {
      "get": {
        "summary": "List User's Mesh Nodes",
        "description": "Returns all local and remote worker instances registered to your account.",
        "security": [
          {"BearerAuth": []},
          {"SessionTokenAuth": []},
          {"ApiKeyHeaderAuth": []}
        ],
        "responses": {
          "200": {
            "description": "List of connected mesh nodes",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/MeshNodeListResponse"}
              }
            }
          },
          "401": {"description": "Authentication required"}
        }
      },
      "post": {
        "summary": "Register Node to Mesh Federation",
        "description": "Registers a new worker instance (e.g. Mini PC or desktop) to your private mesh fleet.",
        "security": [
          {"BearerAuth": []},
          {"SessionTokenAuth": []},
          {"ApiKeyHeaderAuth": []}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {"$ref": "#/components/schemas/RegisterMeshNodeRequest"}
            }
          }
        },
        "responses": {
          "200": {
            "description": "Node registered successfully"
          },
          "401": {"description": "Authentication required"}
        }
      }
    },
    "/v1/mesh/register": {
      "post": {
        "summary": "Register Node to Mesh Federation (Alias)",
        "description": "Registers a node to the authenticated user's private mesh federation.",
        "security": [
          {"BearerAuth": []},
          {"SessionTokenAuth": []},
          {"ApiKeyHeaderAuth": []}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {"$ref": "#/components/schemas/RegisterMeshNodeRequest"}
            }
          }
        },
        "responses": {
          "200": {"description": "Node registered successfully"}
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "oqllm_live_*",
        "description": "Standard Bearer authorization header with API Key"
      },
      "SessionTokenAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Session-Token",
        "description": "Session token from email verification"
      },
      "ApiKeyHeaderAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Alternative direct API key header"
      }
    },
    "schemas": {
      "HealthResponse": {
        "type": "object",
        "properties": {
          "ok": {"type": "boolean"},
          "service": {"type": "string"},
          "status": {"type": "string"},
          "version": {"type": "string"},
          "domain": {"type": "string"},
          "timestamp": {"type": "integer"},
          "mesh_enabled": {"type": "boolean"}
        }
      },
      "ModelListResponse": {
        "type": "object",
        "properties": {
          "object": {"type": "string", "example": "list"},
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {"type": "string"},
                "object": {"type": "string"},
                "created": {"type": "integer"},
                "owned_by": {"type": "string"}
              }
            }
          }
        }
      },
      "PoaRegistryResponse": {
        "type": "object",
        "properties": {
          "version": {"type": "string"},
          "total": {"type": "integer"},
          "systems": {"type": "array", "items": {"type": "string"}},
          "operations": {"type": "array", "items": {"$ref": "#/components/schemas/PoaOperation"}}
        }
      },
      "PoaOperation": {
        "type": "object",
        "properties": {
          "uri": {"type": "string"},
          "system": {"type": "string"},
          "kind": {"type": "string"},
          "desc": {"type": "string"},
          "triggers": {"type": "array", "items": {"type": "string"}},
          "effects": {"type": "array", "items": {"type": "string"}},
          "urn": {"type": "string", "nullable": true},
          "aliases": {"type": "array", "items": {"type": "string"}},
          "parameters": {"type": "object"},
          "canonical": {"type": "boolean"}
        }
      },
      "PoaRouteRequest": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "description": "Query string in any supported format (proc:// URI, urn:, natural language, or voice)."
          },
          "format": {
            "type": "string",
            "enum": ["auto", "uri", "urn", "nl", "voice"],
            "default": "auto"
          }
        },
        "required": ["query"]
      },
      "PoaRouteResponse": {
        "type": "object",
        "properties": {
          "ok": {"type": "boolean"},
          "action": {"type": "string"},
          "query": {"type": "string"},
          "detected_format": {"type": "string"},
          "confidence": {"type": "number"},
          "decision_ms": {"type": "number"},
          "selected_operation": {"type": "string", "nullable": true},
          "operation": {"$ref": "#/components/schemas/PoaOperation"},
          "status": {"type": "string"},
          "dispatch_id": {"type": "string"},
          "user_key": {"type": "string"}
        }
      },
      "ApiKeyRecord": {
        "type": "object",
        "properties": {
          "key_id": {"type": "string"},
          "key_prefix": {"type": "string"},
          "name": {"type": "string"},
          "tier": {"type": "string"},
          "rpm_limit": {"type": "integer"},
          "daily_token_limit": {"type": "integer"},
          "created_at": {"type": "string"},
          "active": {"type": "integer"}
        }
      },
      "CreatedApiKeyResponse": {
        "type": "object",
        "properties": {
          "ok": {"type": "boolean"},
          "key_id": {"type": "string"},
          "name": {"type": "string"},
          "api_key": {"type": "string"},
          "prefix": {"type": "string"},
          "tier": {"type": "string"},
          "rpm_limit": {"type": "integer"},
          "daily_token_limit": {"type": "integer"},
          "scopes": {
            "type": "array",
            "items": {"type": "string"},
            "example": ["all"]
          },
          "format_limits": {
            "type": "object",
            "properties": {
              "nl": {"type": "integer", "description": "Natural language / chat requests per minute", "example": 60},
              "uri": {"type": "integer", "description": "proc:// and app:// procedure calls per minute", "example": 120},
              "urn": {"type": "integer", "description": "urn:... receipts and state checks per minute", "example": 240},
              "voice": {"type": "integer", "description": "Speech transcripts and voice commands per minute", "example": 30}
            }
          },
          "created_at": {"type": "string"}
        }
      },
      "UserUsageQuotasResponse": {
        "type": "object",
        "properties": {
          "ok": {"type": "boolean"},
          "user": {"type": "object"},
          "quotas": {
            "type": "object",
            "properties": {
              "tier": {"type": "string"},
              "rpm_limit": {"type": "integer"},
              "rpm_current": {"type": "integer"},
              "rpm_remaining": {"type": "integer"},
              "daily_token_limit": {"type": "integer"},
              "tokens_used_today": {"type": "integer"},
              "tokens_remaining_today": {"type": "integer"},
              "requests_today": {"type": "integer"},
              "format_limits": {
                "type": "object",
                "description": "Default rate limits by data format for this tier"
              },
              "format_breakdown": {
                "type": "object",
                "description": "Historical request & token usage grouped by format (nl, uri, urn, voice)"
              }
            }
          },
          "summary": {
            "type": "object",
            "properties": {
              "attempts": {"type": "integer"},
              "requests": {"type": "integer"},
              "input_tokens": {"type": "integer"},
              "output_tokens": {"type": "integer"},
              "average_ms": {"type": "number"}
            }
          },
          "recent_attempts": {
            "type": "array",
            "items": {"type": "object"}
          }
        }
      },
      "RegisterMeshNodeRequest": {
        "type": "object",
        "properties": {
          "node_id": {"type": "string", "example": "minipc-amd64"},
          "hostname": {"type": "string", "example": "node-pc.local"},
          "ip": {"type": "string", "example": "192.168.1.100"},
          "port": {"type": "integer", "default": 11437},
          "capabilities": {
            "type": "array",
            "items": {"type": "string"},
            "example": ["poa", "intent", "subllm"]
          },
          "ping_ms": {"type": "number", "default": 0.0}
        },
        "required": ["node_id"]
      },
      "MeshNodeListResponse": {
        "type": "object",
        "properties": {
          "ok": {"type": "boolean"},
          "user": {"type": "string"},
          "count": {"type": "integer"},
          "nodes": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "node_id": {"type": "string"},
                "hostname": {"type": "string"},
                "ip": {"type": "string"},
                "port": {"type": "integer"},
                "capabilities": {"type": "array", "items": {"type": "string"}},
                "online": {"type": "boolean"},
                "ping_ms": {"type": "number"}
              }
            }
          }
        }
      }
    }
  }
}