Skip to content

API Ryoma ​

The API version is 0.1.0. The curl examples call https://ryoma.phillipcli.cloud.

Ryoma API: token metering, AI cost and quotas for PhillipCLI. This contract is the source for generating the Go server and the Phillip CLI.

Authentication: every endpoint (except /healthz) needs the header Authorization: Bearer tara_pat_…. Ryoma does not manage users: tokens are checked with Tara (GET /v1/me).

Organizations. All data belongs to one organization (the customer). A Tara token (API token or CLI session) is bound to exactly one organization, and every request reads and writes only that organization: the organization is taken from the authenticated token, never from the request body or query. Data of an organization lives under /v1/orgs/{org}/... ({org} is the slug), with the same paths and bodies as the /v1/... routes below (/v1/orgs/acme/projects, /v1/orgs/acme/usage). The server checks the path organization against the token: a user who is not a member of {org} gets 404 (so the existence of an organization is not leaked); a member whose token is bound to another organization gets 403. Platform staff get no implicit access to customer organizations. The form without the organization (/v1/usage) is a deprecated alias that resolves to the organization of the token and answers with the header Deprecation: true; it goes away once Phillip uses the new routes. /healthz, /openapi.json and /v1/me have no organization form.

Roles (Tara): owner, admin, member, viewer. Every role sees every project of the organization that is not private, and the project-level metrics (health, flow, AI, estimate, cost per project). Writing configuration (projects, quotas) and reading per-person data (usage by user, adoption, Guardrails audit, telemetry gaps) is for owner and admin. The Guardrails report (counts by rule and project, no names) and the Insights endpoints (/v1/flow, /v1/ai, /v1/insights/overview, /v1/delivery/health, /v1/guardrails) are readable by every role: they feed the dashboards in the Tara Portal. Private projects. A project can be private in Tara (only organization owners, admins and the project's members see it). For every request that touches project data, Ryoma asks Tara which projects the caller can see (cached for 60 seconds) and answers 404 for a private project the caller cannot see, never 403. Lists and organization-level figures leave those projects out. When Tara cannot be reached the answer is 503 with Retry-After: Ryoma never falls back to showing everything. Owners, admins and the service accounts of Tara (scope scm or admin) skip the check. A token delegated by Tara (tara_dlg_…) is checked as the person it was issued for. Per-project admins have no extra rights in Ryoma.

Cost is the converted cost at API prices (estimated USD computed by Claude Code), used as the unit for quotas; it is not the amount the company pays for a subscription plan.

Claude Code OTLP/HTTP telemetry goes to /otlp/v1/logs and /otlp/v1/metrics (not described here).

Endpoint groups ​

GroupDescriptionEndpoints
system1
accountThe current user and their own metrics3
reportingUsage reports of the organization (org owner and admin; members and viewers only by project)10
projectsProjects and their repos8
quotasConverted-cost quotas and threshold breaches5
adminService-to-service endpoints for Tara (scope admin, never for users)3

These pages are generated

Endpoint descriptions come from the service's openapi.yaml each time you run npm run gen. Endpoints labeled Admin can be called only by admin roles. A few internal endpoints are left out of the public edition.