{
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "description": "API key (lk_live_..., lk_test_..., or lk_pub_...)",
        "scheme": "bearer",
        "type": "http"
      }
    }
  },
  "info": {
    "description": "Central hub for LOCURA ecosystem - clients, files (R2), API keys, webhooks, usage tracking",
    "title": "LOCURA Hub API",
    "version": "1.0.0"
  },
  "openapi": "3.1.0",
  "paths": {
    "/api/v1/changelog": {
      "get": {
        "responses": {
          "200": {
            "description": "Success"
          },
          "401": {
            "description": "Unauthorized - missing or invalid API key"
          },
          "403": {
            "description": "Forbidden - missing required scope"
          },
          "429": {
            "description": "Rate limit exceeded"
          },
          "500": {
            "description": "Internal server error"
          }
        },
        "security": [],
        "summary": "API changelog",
        "tags": [
          "Meta"
        ]
      }
    },
    "/api/v1/clients": {
      "get": {
        "description": "List all clients with pagination and optional search by name",
        "responses": {
          "200": {
            "description": "Success"
          },
          "401": {
            "description": "Unauthorized - missing or invalid API key"
          },
          "403": {
            "description": "Forbidden - missing required scope"
          },
          "429": {
            "description": "Rate limit exceeded"
          },
          "500": {
            "description": "Internal server error"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "List clients",
        "tags": [
          "Clients"
        ],
        "x-required-scope": "hub:clients:read"
      }
    },
    "/api/v1/clients/{id}": {
      "get": {
        "description": "Get detailed information about a specific client",
        "responses": {
          "200": {
            "description": "Success"
          },
          "401": {
            "description": "Unauthorized - missing or invalid API key"
          },
          "403": {
            "description": "Forbidden - missing required scope"
          },
          "429": {
            "description": "Rate limit exceeded"
          },
          "500": {
            "description": "Internal server error"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Get client details",
        "tags": [
          "Clients"
        ],
        "x-required-scope": "hub:clients:read"
      }
    },
    "/api/v1/clients/{id}/files": {
      "get": {
        "description": "List files stored in R2 for a client. Use ?folder=all for all folders or specify a folder name.",
        "responses": {
          "200": {
            "description": "Success"
          },
          "401": {
            "description": "Unauthorized - missing or invalid API key"
          },
          "403": {
            "description": "Forbidden - missing required scope"
          },
          "429": {
            "description": "Rate limit exceeded"
          },
          "500": {
            "description": "Internal server error"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "List client files from R2",
        "tags": [
          "Files"
        ],
        "x-required-scope": "hub:files:read"
      },
      "put": {
        "description": "Upload a file to R2 storage. Send base64-encoded data with path and contentType.",
        "responses": {
          "200": {
            "description": "Success"
          },
          "401": {
            "description": "Unauthorized - missing or invalid API key"
          },
          "403": {
            "description": "Forbidden - missing required scope"
          },
          "429": {
            "description": "Rate limit exceeded"
          },
          "500": {
            "description": "Internal server error"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Upload file to R2",
        "tags": [
          "Files"
        ],
        "x-required-scope": "hub:files:write"
      }
    },
    "/api/v1/clients/{id}/files/{key}": {
      "get": {
        "description": "Download a specific file from R2 by its key path",
        "responses": {
          "200": {
            "description": "Success"
          },
          "401": {
            "description": "Unauthorized - missing or invalid API key"
          },
          "403": {
            "description": "Forbidden - missing required scope"
          },
          "429": {
            "description": "Rate limit exceeded"
          },
          "500": {
            "description": "Internal server error"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Download file",
        "tags": [
          "Files"
        ],
        "x-required-scope": "hub:files:read"
      }
    },
    "/api/v1/data-erasure": {
      "post": {
        "responses": {
          "200": {
            "description": "Success"
          },
          "401": {
            "description": "Unauthorized - missing or invalid API key"
          },
          "403": {
            "description": "Forbidden - missing required scope"
          },
          "429": {
            "description": "Rate limit exceeded"
          },
          "500": {
            "description": "Internal server error"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Request data erasure (GDPR)",
        "tags": [
          "GDPR"
        ],
        "x-required-scope": "hub:gdpr:manage"
      }
    },
    "/api/v1/data-export": {
      "post": {
        "responses": {
          "200": {
            "description": "Success"
          },
          "401": {
            "description": "Unauthorized - missing or invalid API key"
          },
          "403": {
            "description": "Forbidden - missing required scope"
          },
          "429": {
            "description": "Rate limit exceeded"
          },
          "500": {
            "description": "Internal server error"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Request data export (GDPR)",
        "tags": [
          "GDPR"
        ],
        "x-required-scope": "hub:gdpr:manage"
      }
    },
    "/api/v1/health": {
      "get": {
        "responses": {
          "200": {
            "description": "Success"
          },
          "401": {
            "description": "Unauthorized - missing or invalid API key"
          },
          "403": {
            "description": "Forbidden - missing required scope"
          },
          "429": {
            "description": "Rate limit exceeded"
          },
          "500": {
            "description": "Internal server error"
          }
        },
        "security": [],
        "summary": "Health check",
        "tags": [
          "Meta"
        ]
      }
    },
    "/api/v1/sandbox/reset": {
      "post": {
        "responses": {
          "200": {
            "description": "Success"
          },
          "401": {
            "description": "Unauthorized - missing or invalid API key"
          },
          "403": {
            "description": "Forbidden - missing required scope"
          },
          "429": {
            "description": "Rate limit exceeded"
          },
          "500": {
            "description": "Internal server error"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Reset sandbox data",
        "tags": [
          "Sandbox"
        ],
        "x-required-scope": "hub:keys:manage"
      }
    },
    "/api/v1/usage": {
      "get": {
        "description": "Get usage statistics aggregated by day with optional date range filtering",
        "responses": {
          "200": {
            "description": "Success"
          },
          "401": {
            "description": "Unauthorized - missing or invalid API key"
          },
          "403": {
            "description": "Forbidden - missing required scope"
          },
          "429": {
            "description": "Rate limit exceeded"
          },
          "500": {
            "description": "Internal server error"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "API usage stats",
        "tags": [
          "Usage"
        ],
        "x-required-scope": "hub:usage:read"
      }
    },
    "/api/v1/usage/audit-log": {
      "get": {
        "description": "View API audit trail with pagination",
        "responses": {
          "200": {
            "description": "Success"
          },
          "401": {
            "description": "Unauthorized - missing or invalid API key"
          },
          "403": {
            "description": "Forbidden - missing required scope"
          },
          "429": {
            "description": "Rate limit exceeded"
          },
          "500": {
            "description": "Internal server error"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Audit log",
        "tags": [
          "Usage"
        ],
        "x-required-scope": "hub:audit:read"
      }
    }
  },
  "servers": [
    {
      "url": "https://hub.locura.tech"
    }
  ]
}