Skip to content

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 ​

GroupDescriptionEndpoints
system1
billingPlans 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
githubGitHub App connection of an organization (install, auto-join, repositories, read-only tokens)7
scmSource hosts of an organization beyond the GitHub App - GitLab connection, repository check and read tokens for both providers15
importingImport resources (plugins, skills, agents, commands) from GitHub repositories8
accountAccount and access tokens10
publishingSubmit resources, view submissions and versions9
authoringAuthor resources on the Portal (wizard, new versions)3
reviewingReview resources (platform staff for the official catalog; organization owner or admin for the organization's private store)3
browsingExplore resources and view their details5
administrationRole administration (organization owner or admin)6
distributionPackage downloads and marketplace for Claude Code11
deliveryProjects section on the Portal (delivery metrics read from Ryoma, filtered by organization)15
organizationsOrganizations, members, invitations and projects (path-based organization, see above)61
announcementsAnnouncements from PhillipCLI (maintenance, incidents, news) shown as banners in the Portal and printed by ph2
knowledgeKnowledge 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.