API Tara: distribution
Package downloads and marketplace for Claude Code
This page is generated from
openapi.yamlbynpm run gen, so do not edit it by hand. Authentication is described on the overview page.
/v1/artifacts/{name}/{file}Download the immutable package of a version (counts a download)
file has the form <version>.zip, for example /v1/artifacts/agent-ba/1.0.0.zip. Only installable versions (published, deprecated, yanked) can be downloaded. A yanked version is still downloadable so existing locks do not break; the X-Tara-State header reports the state so Phillip can warn.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | yes | |
file | path | string | yes | |
org | query | string | Slug of the owning organization (full name <org>/<name>). Omitted: {name} means aiforge/<name>, then the caller's own organization, never another organization (a public community resource of another organization is reachable only by its full name; a miss that matches one answers 404 with code not_found_hint listing up to 5 full names) |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Zip package | application/zip · string (binary) |
| 400 | Invalid file name | application/problem+json · object |
| 401 | Not signed in | application/problem+json · object |
| 404 | Not found | application/problem+json · object |
Call with curl
curl "https://tara.phillipcli.cloud/v1/artifacts/<name>/<file>" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/signatures/{name}/{version}Signature of a version (Ed25519, signed on approval)
statement is exactly the signed bytes (JSON, type tara.package/v2: name (without namespace), version, kind, org, channel (official for org aiforge, org for the private store of another organization, community), sha256, reviewedBy, publishedAt). Older statements (tara.package/v1, with center instead of org and channel) remain valid: center: rnd is org aiforge, another center is that organization, channel: community is community. Verifiers (Phillip, Bandum, Ryoma) check signature with the public key configured in advance for keyId, then compare name, version, sha256 with the downloaded package. Do not use a key fetched from Tara at verification time.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | yes | |
version | path | string | yes | |
org | query | string | Slug of the owning organization (full name <org>/<name>). Omitted: {name} means aiforge/<name>, then the caller's own organization, never another organization (a public community resource of another organization is reachable only by its full name; a miss that matches one answers 404 with code not_found_hint listing up to 5 full names) |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Signature | application/json · object |
| 400 | Invalid version | application/problem+json · object |
| 401 | Not signed in | application/problem+json · object |
| 404 | Version not found or not signed | application/problem+json · object |
Example response
{
"keyId": "string",
"statement": "string",
"signature": "string"
}Call with curl
curl "https://tara.phillipcli.cloud/v1/signatures/<name>/<version>" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/revocationsSigned revocation list (latest)
statement is exactly the signed bytes (JSON, type tara.revocations/v1: serial, issuedAt, entries with org, name, version, sha256, reason for every yanked version of the official catalog and of public community resources; an entry without org is from before namespaces and applies to every organization). Yanks of an organization's private store are on GET /v1/orgs/{org}/revocations. Tara re-signs on every yank. Verifiers check the signature like a package signature, keep the highest serial they have seen (never roll back to an older one) and refuse to load a package that is on the list.
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Revocation list | application/json · object |
| 401 | Not signed in | application/problem+json · object |
| 404 | Tara has not published a list (signing is not enabled) | application/problem+json · object |
Example response
{
"keyId": "string",
"statement": "string",
"signature": "string"
}Call with curl
curl "https://tara.phillipcli.cloud/v1/revocations" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/orgs/{org}/revocationsSigned revocation list of an organization's private store
Same format as /v1/revocations (type tara.revocations/v1) with a top-level org, listing the yanked or removed versions of the organization's private store (channel org). Members of the organization only. The serial is the issue time in milliseconds, so it increases on every call; verifiers keep the highest serial they have seen like for the global list and check this list in addition to the global one for packages of channel org.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
org | path | string | yes |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Revocation list | application/json · object |
| 401 | Not signed in | application/problem+json · object |
| 403 | The token belongs to a different organization | application/problem+json · object |
| 404 | Not a member of the organization (or no such organization) | application/problem+json · object |
Example response
{
"keyId": "string",
"statement": "string",
"signature": "string"
}Call with curl
curl "https://tara.phillipcli.cloud/v1/orgs/<org>/revocations" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/signing-keysPublic key Tara uses to sign packages
Public (no sign-in needed): the Phillip install script (/install.sh) fetches the key here over Tara's HTTPS to write into the user configuration. Verifiers should still compare keyId with the value the admin publishes through a trusted channel.
No sign-in required.
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Key | application/json · object |
Example response
{
"keys": [
{
"keyId": "string",
"publicKey": "string"
}
]
}Call with curl
curl "https://tara.phillipcli.cloud/v1/signing-keys"/v1/scm-oauthGitHub/GitLab OAuth apps for Phillip to connect
Public (no sign-in needed): ph connect reads it before the user has a token. Only public information (Client ID; the app is public so it has no secret). Admins declare them in TARA_SCM_OAUTH_CLIENTS; if none are declared, clients is empty.
No sign-in required.
Responses
| Code | Description | Type |
|---|---|---|
| 200 | List of apps | application/json · object |
Example response
{
"clients": [
{
"host": "gitlab.example.com",
"scheme": "http",
"kind": "github",
"clientId": "string",
"deviceFlow": false,
"scopes": []
}
]
}Call with curl
curl "https://tara.phillipcli.cloud/v1/scm-oauth"/v1/client-configAddresses a client (Phillip) needs besides Tara itself
Public (no sign-in needed): /install.sh, ph tara login and ph setup read it to learn where to send telemetry. ryomaUrl is TARA_RYOMA_PUBLIC_URL (or TARA_RYOMA_URL when unset); null when Ryoma is not configured. More client URLs may be added later.
No sign-in required.
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Client configuration | application/json · object |
Example response
{
"ryomaUrl": "https://ryoma.example.com"
}Call with curl
curl "https://tara.phillipcli.cloud/v1/client-config"/v1/locksResolve dependencies and lock versions for a project
Picks, for each resource, the highest version that satisfies every constraint (from the project and from dependencies), never picking a yanked version. lockId is the sha256 of the resolved version set: the same result gives the same lockId, and calling again does not create a new lock. Phillip writes the result into the project's phillip.lock.
Body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
resources | object[] | yes |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Resolved lock | application/json · object |
| 400 | Invalid input or resource does not exist | application/problem+json · object |
| 401 | Not signed in | application/problem+json · object |
| 409 | No version set satisfies every constraint | application/problem+json · object |
Example response
{
"lockId": "string",
"marketplace": "string",
"requirements": [
{
"name": "acme/harness-sdlc",
"version": "^1.0.0",
"org": "string",
"pluginId": "string"
}
],
"entries": [
{
"name": "string",
"org": "string",
"pluginId": "string",
"version": "string",
"kind": "skill",
"sha256": "string",
"state": "submitted",
"requiredBy": []
}
]
}Call with curl
curl -X POST "https://tara.phillipcli.cloud/v1/locks" \
-H "Authorization: Bearer $TARA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"resources":[{"name":"acme/harness-sdlc","version":"^1.0.0","org":"string","pluginId":"string"}]}'/v1/locks/{lockId}Lock and current state of each version (to warn about versions yanked after locking)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
lockId | path | string | yes |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Lock | application/json · object |
| 401 | Not signed in | application/problem+json · object |
| 404 | Not found | application/problem+json · object |
Example response
{
"lockId": "string",
"marketplace": "string",
"requirements": [
{
"name": "acme/harness-sdlc",
"version": "^1.0.0",
"org": "string",
"pluginId": "string"
}
],
"entries": [
{
"name": "string",
"org": "string",
"pluginId": "string",
"version": "string",
"kind": "skill",
"sha256": "string",
"state": "submitted",
"requiredBy": []
}
]
}Call with curl
curl "https://tara.phillipcli.cloud/v1/locks/<lockId>" \
-H "Authorization: Bearer $TARA_TOKEN"/claude/locks/{lockId}/marketplace.jsonClaude Code marketplace for a lock
Exactly the versions in the lock (including versions yanked after locking, so the project does not break). The marketplace name is ai-forge-<first 8 characters of lockId>: Claude Code stores the marketplace name in the user's shared registry, so every lock needs its own name so two projects with different locks do not overwrite each other.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
lockId | path | string | yes |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | marketplace.json | application/json · object |
| 401 | Not signed in | application/problem+json · object |
| 404 | Not found | application/problem+json · object |
Example response
{
"name": "ai-forge",
"description": "string",
"owner": {
"name": "string"
},
"plugins": [
{
"name": "string",
"displayName": "string",
"description": "string",
"source": {},
"metadata": {}
}
]
}Call with curl
curl "https://tara.phillipcli.cloud/claude/locks/<lockId>/marketplace.json" \
-H "Authorization: Bearer $TARA_TOKEN"/claude/marketplace.jsonClaude Code marketplace, "newest" channel
The newest published version of every active resource; each plugin is an archive source pinned by sha256. Register in Claude Code: a marketplace with a url source pointing at this address, plus a headersHelper that prints the header Authorization: Bearer <token>. Claude Code only downloads packages over https, not from localhost.
Responses
| Code | Description | Type |
|---|---|---|
| 200 | marketplace.json | application/json · object |
| 401 | Not signed in | application/problem+json · object |
Example response
{
"name": "ai-forge",
"description": "string",
"owner": {
"name": "string"
},
"plugins": [
{
"name": "string",
"displayName": "string",
"description": "string",
"source": {},
"metadata": {}
}
]
}Call with curl
curl "https://tara.phillipcli.cloud/claude/marketplace.json" \
-H "Authorization: Bearer $TARA_TOKEN"