# Hono Documentation - **OpenAPI Version:** `3.1.0` - **API Version:** `0.0.0` Development documentation ## Operations ### GET /v1/usage/summary - **Method:** `GET` - **Path:** `/v1/usage/summary` Get usage summary for a selected time range #### Parameters ##### `range` - **In:** `query` `string`, possible values: `"24h", "7d", "30d"`, default: `"7d"` #### Responses ##### Status: 200 Usage summary ###### Content-Type: application/json - **`actualCostMicrousd` (required)** `number` - **`errors` (required)** `number` - **`requests` (required)** `number` - **`tokens` (required)** `number` **Example:** ```json { "requests": 1, "tokens": 1, "actualCostMicrousd": 1, "errors": 1 } ``` ##### Status: 401 Unauthorized ### GET /v1/usage/breakdown - **Method:** `GET` - **Path:** `/v1/usage/breakdown` Get usage grouped by model for a selected time range #### Parameters ##### `range` - **In:** `query` `string`, possible values: `"24h", "7d", "30d"`, default: `"7d"` #### Responses ##### Status: 200 Usage breakdown by model ###### Content-Type: application/json **Array of:** - **`actualCostMicrousd` (required)** `number` - **`model` (required)** `string` - **`requests` (required)** `number` - **`tokens` (required)** `number` **Example:** ```json [ { "model": "", "requests": 1, "tokens": 1, "actualCostMicrousd": 1 } ] ``` ##### Status: 401 Unauthorized ### GET /v1/usage/app-breakdown - **Method:** `GET` - **Path:** `/v1/usage/app-breakdown` Get usage grouped by app for a selected time range #### Parameters ##### `range` - **In:** `query` `string`, possible values: `"24h", "7d", "30d"`, default: `"7d"` #### Responses ##### Status: 200 Usage breakdown by app ###### Content-Type: application/json **Array of:** - **`actualCostMicrousd` (required)** `number` - **`appId` (required)** `object` - **`requests` (required)** `number` - **`tokens` (required)** `number` **Example:** ```json [ { "appId": "", "requests": 1, "tokens": 1, "actualCostMicrousd": 1 } ] ``` ##### Status: 401 Unauthorized ### GET /v1/usage/time-series - **Method:** `GET` - **Path:** `/v1/usage/time-series` Get usage grouped into hourly or daily buckets for a selected time range #### Parameters ##### `range` - **In:** `query` `string`, possible values: `"24h", "7d", "30d"`, default: `"7d"` #### Responses ##### Status: 200 Usage time series ###### Content-Type: application/json **Array of:** - **`actualCostMicrousd` (required)** `number` - **`errors` (required)** `number` - **`requests` (required)** `number` - **`timeBucket` (required)** `string` - **`tokens` (required)** `number` **Example:** ```json [ { "timeBucket": "", "requests": 1, "tokens": 1, "actualCostMicrousd": 1, "errors": 1 } ] ``` ##### Status: 401 Unauthorized ### GET /v1/usage/model-time-series - **Method:** `GET` - **Path:** `/v1/usage/model-time-series` Get usage grouped into time buckets and model series for a selected time range #### Parameters ##### `range` - **In:** `query` `string`, possible values: `"24h", "7d", "30d"`, default: `"7d"` #### Responses ##### Status: 200 Usage time series by model ###### Content-Type: application/json **Array of:** - **`actualCostMicrousd` (required)** `number` - **`cacheHitRate` (required)** `number` - **`cacheReadTokens` (required)** `number` - **`cacheWriteTokens` (required)** `number` - **`errors` (required)** `number` - **`inputTokens` (required)** `number` - **`model` (required)** `string` - **`outputTokens` (required)** `number` - **`requests` (required)** `number` - **`timeBucket` (required)** `string` - **`tokens` (required)** `number` **Example:** ```json [ { "timeBucket": "", "model": "", "requests": 1, "tokens": 1, "actualCostMicrousd": 1, "errors": 1, "inputTokens": 1, "outputTokens": 1, "cacheReadTokens": 1, "cacheWriteTokens": 1, "cacheHitRate": 1 } ] ``` ##### Status: 401 Unauthorized ### GET /v1/keys - **Method:** `GET` - **Path:** `/v1/keys` List API keys #### Responses ##### Status: 200 List of API keys ###### Content-Type: application/json **Array of:** - **`createdAt` (required)** `string` - **`id` (required)** `string` - **`keyHash`** `string` - **`lastUsedAt`** `object` - **`name`** `object` - **`status`** `string` - **`suffix`** `object` **Example:** ```json [ { "id": "", "name": "", "createdAt": "", "keyHash": "", "status": "", "lastUsedAt": "", "suffix": "" } ] ``` ##### Status: 401 Unauthorized ### POST /v1/keys - **Method:** `POST` - **Path:** `/v1/keys` Create API key #### Request Body ##### Content-Type: application/json - **`name`** `string` **Example:** ```json { "name": "" } ``` #### Responses ##### Status: 201 API key created ###### Content-Type: application/json - **`createdAt` (required)** `string` - **`id` (required)** `string` - **`key` (required)** `string` - **`name`** `object` **Example:** ```json { "id": "", "key": "", "name": "", "createdAt": "" } ``` ##### Status: 401 Unauthorized ### DELETE /v1/keys/{id} - **Method:** `DELETE` - **Path:** `/v1/keys/{id}` Delete API key #### Parameters ##### `id` required - **In:** `path` `string` #### Responses ##### Status: 204 API key deleted ##### Status: 401 Unauthorized ### POST /v1/client-tokens - **Method:** `POST` - **Path:** `/v1/client-tokens` Create a short-lived client token for browser AaaS runtime access #### Request Body ##### Content-Type: application/json - **`appId`** `string` **Example:** ```json { "appId": "" } ``` #### Responses ##### Status: 200 Client token created ###### Content-Type: application/json - **`expiresAt` (required)** `string` - **`token` (required)** `string` **Example:** ```json { "token": "", "expiresAt": "" } ``` ##### Status: 401 Unauthorized ### GET /v1/credits/balance - **Method:** `GET` - **Path:** `/v1/credits/balance` Get current credit balance #### Responses ##### Status: 200 Current credit balance ##### Status: 401 Unauthorized ### POST /v1/credits/checkout - **Method:** `POST` - **Path:** `/v1/credits/checkout` Create a Stripe Checkout session for credit top-up #### Request Body ##### Content-Type: application/json - **`amountUsd` (required)** `integer` **Example:** ```json { "amountUsd": 10 } ``` #### Responses ##### Status: 200 Checkout session URL ###### Content-Type: application/json - **`sessionId` (required)** `string` - **`url` (required)** `string` **Example:** ```json { "url": "", "sessionId": "" } ``` ##### Status: 400 Invalid top-up amount ##### Status: 401 Unauthorized ### GET /v1/credits/transactions - **Method:** `GET` - **Path:** `/v1/credits/transactions` List recent credit ledger transactions #### Parameters ##### `limit` - **In:** `query` `integer`, default: `50` #### Responses ##### Status: 200 Recent credit ledger transactions ###### Content-Type: application/json **Array of:** - **`amountMicrousd` (required)** `number` - **`createdAt` (required)** `number` - **`idempotencyKey` (required)** `string` - **`tokens` (required)** `number` - **`type` (required)** `string` - **`model`** `string` - **`reason`** `string` **Example:** ```json [ { "idempotencyKey": "", "type": "", "amountMicrousd": 1, "reason": "", "model": "", "tokens": 1, "createdAt": 1 } ] ``` ##### Status: 401 Unauthorized ### GET /v1/apps - **Method:** `GET` - **Path:** `/v1/apps` List all applications owned by the logged-in user #### Responses ##### Status: 200 List of applications ###### Content-Type: application/json **Array of:** - **`appId` (required)** `string` - **`createdAt` (required)** `string` - **`name` (required)** `string` - **`updatedAt` (required)** `string` - **`description`** `string` **Example:** ```json [ { "appId": "", "name": "", "description": "", "createdAt": "", "updatedAt": "" } ] ``` ##### Status: 401 Unauthorized ### POST /v1/apps - **Method:** `POST` - **Path:** `/v1/apps` Register a new application #### Request Body ##### Content-Type: application/json - **`appId` (required)** `string` — Globally unique app identifier (lowercase alphanumeric + hyphens) - **`name` (required)** `string` — Display name of the application - **`description`** `string` — Description of the application **Example:** ```json { "appId": "", "name": "", "description": "" } ``` #### Responses ##### Status: 201 Application registered successfully ##### Status: 400 Invalid appId or appId already taken ##### Status: 401 Unauthorized ### GET /v1/apps/{appId} - **Method:** `GET` - **Path:** `/v1/apps/{appId}` Get registry details and manifest of a specific application #### Parameters ##### `appId` required - **In:** `path` `string` #### Responses ##### Status: 200 Application details ##### Status: 401 Unauthorized ##### Status: 403 Forbidden ##### Status: 404 Application not found ### PUT /v1/apps/{appId} - **Method:** `PUT` - **Path:** `/v1/apps/{appId}` Update application registry details and upload manifest #### Parameters ##### `appId` required - **In:** `path` `string` #### Request Body ##### Content-Type: application/json - **`description`** `string` — Updated description - **`manifest`** `object` — Updated application manifest config - **`name`** `string` — Updated display name **Example:** ```json { "name": "", "description": "", "manifest": {} } ``` #### Responses ##### Status: 200 Application updated successfully ##### Status: 401 Unauthorized ##### Status: 403 Forbidden ##### Status: 404 Application not found ### DELETE /v1/apps/{appId} - **Method:** `DELETE` - **Path:** `/v1/apps/{appId}` Delete an application and its registry key #### Parameters ##### `appId` required - **In:** `path` `string` #### Responses ##### Status: 204 Application deleted successfully ##### Status: 401 Unauthorized ##### Status: 403 Forbidden ##### Status: 404 Application not found ### POST /v1/apps/{appId}/deploy - **Method:** `POST` - **Path:** `/v1/apps/{appId}/deploy` Deploy static frontend assets to R2 storage #### Parameters ##### `appId` required - **In:** `path` `string` #### Responses ##### Status: 200 Assets deployed successfully ##### Status: 400 Missing upload assets payload ##### Status: 401 Unauthorized ##### Status: 403 Forbidden ##### Status: 404 Application not found