API Tara
The API version is 0.1.0. The curl examples call https://tara.phillipcli.cloud.
Tara API: the AI resource store of PhillipCLI. This contract is the source for generating the Go server, the Portal (TypeScript) and the Phillip CLI.
Authentication: every endpoint (except /healthz, /v1/signing-keys, /v1/scm-oauth, /v1/client-config) requires sign-in, in one of two ways:
- Cookie
tara_session: the Portal, after signing in with GitHub (GET /auth/github/login) or an organization's GitLab (GET /auth/gitlab/{id}/login). List of sign-in methods:GET /auth/providers(public). - Header
Authorization: Bearer tara_pat_…: a personal token created on the Portal, for Phillip and CI.
Organizations in the path. Data of an organization lives under /v1/orgs/{org}/... ({org} is the slug). The server checks that the caller is a member (404 if not, so the existence of an organization is not leaked; platform staff get no implicit access to customer organizations) and takes the organization from the path, never from the session. A token is bound to one organization: the path organization must be the token's, otherwise 403. Every existing route below (resources, locks, knowledge, delivery, audit, admin, submissions, versions, reports, drafts) also exists as /v1/orgs/{org}/<same path>; the form without the organization is a deprecated alias that resolves to the organization of the session (the last one opened) or the token, and answers with the header Deprecation: true. Platform-wide routes stay as they are: the official and community catalog reads, /v1/me, /v1/orgs, /v1/invites, /auth/*.
Outside this contract (downloadable files, not a JSON API, public so people without an account can install Phillip): GET /install.sh, GET /install.ps1, GET /phillip/latest.json ({version, sha256, url, vscode?: {version, sha256, url}}), GET /phillip/phillip-<version>.tgz, GET /phillip/phillip-vscode-<version>.vsix (and phillip-vscode-latest.vsix, the newest VS Code extension). Every /phillip/ route requires sign-in when TARA_PHILLIP_DOWNLOAD=login.
Also outside the contract and always requiring sign-in: signed tool binaries (Bandum) GET /tools/<name>/latest.json, GET /tools/<name>/<version>.json, GET /tools/<name>/<version>/<file> (see the README, section on tool distribution).
Endpoint groups
| Group | Description | Endpoints |
|---|---|---|
| system | 1 | |
| billing | Plans and payment through Paddle (the Paddle webhook POST /v1/billing/paddle/webhook is outside this contract because it needs the raw body for the signature) | 5 |
| github | GitHub App connection of an organization (install, auto-join, repositories, read-only tokens) | 7 |
| scm | Source hosts of an organization beyond the GitHub App - GitLab connection, repository check and read tokens for both providers | 15 |
| importing | Import resources (plugins, skills, agents, commands) from GitHub repositories | 8 |
| account | Account and access tokens | 10 |
| publishing | Submit resources, view submissions and versions | 9 |
| authoring | Author resources on the Portal (wizard, new versions) | 3 |
| reviewing | Review resources (platform staff for the official catalog; organization owner or admin for the organization's private store) | 3 |
| browsing | Explore resources and view their details | 5 |
| administration | Role administration (organization owner or admin) | 6 |
| distribution | Package downloads and marketplace for Claude Code | 11 |
| delivery | Projects section on the Portal (delivery metrics read from Ryoma, filtered by organization) | 15 |
| organizations | Organizations, members, invitations and projects (path-based organization, see above) | 61 |
| announcements | Announcements from PhillipCLI (maintenance, incidents, news) shown as banners in the Portal and printed by ph | 2 |
| knowledge | Knowledge base: knowledge spaces, documents, hybrid search (MCP at /mcp/knowledge) | 13 |
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.