Skip to content

local-http-api.md

Latest commit

 

History

History
95 lines (67 loc) · 2.61 KB

local-http-api.md

File metadata and controls

95 lines (67 loc) · 2.61 KB

Local HTTP API

OpenUsage exposes a read-only HTTP API on the loopback interface so other local apps can consume the same usage data shown in the menu bar.

Base URL: http://127.0.0.1:6736

The server starts automatically with the app. If the port is already in use, the feature is silently disabled for that session.

Routes

GET /v1/usage

Returns an array of cached usage snapshots for all enabled providers, ordered by your plugin settings.

  • 200 OK — JSON array (may be empty [] if no cached data exists yet).

GET /v1/usage/:providerId

Returns a single cached usage snapshot for the given provider.

  • 200 OK — JSON object with cached snapshot.
  • 204 No Content — Provider is known but has no cached snapshot yet.
  • 404 Not Found — Provider ID is unknown.

Unsupported methods

Any method other than GET or OPTIONS on the above routes returns 405 Method Not Allowed.

Unknown routes return 404 Not Found.

Response Shape

{
  "providerId": "claude",
  "displayName": "Claude",
  "plan": "Team 5x",
  "lines": [
    {
      "type": "progress",
      "label": "Session",
      "used": 42.0,
      "limit": 100.0,
      "format": { "kind": "percent" },
      "resetsAt": "2026-03-26T13:00:00.161Z",
      "periodDurationMs": 18000000,
      "color": null
    },
    {
      "type": "text",
      "label": "Today",
      "value": "$5.17 \u00b7 9.2M tokens",
      "color": null,
      "subtitle": null
    }
  ],
  "fetchedAt": "2026-03-26T11:16:29Z"
}

The lines array uses the same metric line types as the internal plugin output: progress, text, and badge.

fetchedAt is an ISO 8601 timestamp indicating when the snapshot was last successfully fetched.

iconUrl is intentionally omitted from the API response to keep payloads small.

Filtering and Caching Behavior

  • The collection endpoint (/v1/usage) returns enabled providers only, in the order defined by your plugin settings.
  • Only successful probe results are cached. A failed probe never overwrites a previous successful snapshot.
  • The single-provider endpoint (/v1/usage/:providerId) works for any known provider, including disabled ones.

CORS

All responses include permissive CORS headers:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, OPTIONS
Access-Control-Allow-Headers: Content-Type

OPTIONS requests return 204 No Content with these headers for preflight support.

Error Responses

Error responses use this shape:

{
  "error": "provider_not_found"
}

Possible error codes: provider_not_found, not_found, method_not_allowed.