Skip to content

API Tara: distribution ​

Package downloads and marketplace for Claude Code

This page is generated from openapi.yaml by npm run gen, so do not edit it by hand. Authentication is described on the overview page.

GET/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 ​

NameInTypeRequiredDescription
namepathstringyes
filepathstringyes
orgquerystringSlug 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 ​

CodeDescriptionType
200Zip packageapplication/zip · string (binary)
400Invalid file nameapplication/problem+json · object
401Not signed inapplication/problem+json · object
404Not foundapplication/problem+json · object

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/artifacts/<name>/<file>" \
  -H "Authorization: Bearer $TARA_TOKEN"
GET/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 ​

NameInTypeRequiredDescription
namepathstringyes
versionpathstringyes
orgquerystringSlug 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 ​

CodeDescriptionType
200Signatureapplication/json · object
400Invalid versionapplication/problem+json · object
401Not signed inapplication/problem+json · object
404Version not found or not signedapplication/problem+json · object

Example response ​

json
{
  "keyId": "string",
  "statement": "string",
  "signature": "string"
}

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/signatures/<name>/<version>" \
  -H "Authorization: Bearer $TARA_TOKEN"
GET/v1/revocations

Signed 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 ​

CodeDescriptionType
200Revocation listapplication/json · object
401Not signed inapplication/problem+json · object
404Tara has not published a list (signing is not enabled)application/problem+json · object

Example response ​

json
{
  "keyId": "string",
  "statement": "string",
  "signature": "string"
}

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/revocations" \
  -H "Authorization: Bearer $TARA_TOKEN"
GET/v1/orgs/{org}/revocations

Signed 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 ​

NameInTypeRequiredDescription
orgpathstringyes

Responses ​

CodeDescriptionType
200Revocation listapplication/json · object
401Not signed inapplication/problem+json · object
403The token belongs to a different organizationapplication/problem+json · object
404Not a member of the organization (or no such organization)application/problem+json · object

Example response ​

json
{
  "keyId": "string",
  "statement": "string",
  "signature": "string"
}

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/orgs/<org>/revocations" \
  -H "Authorization: Bearer $TARA_TOKEN"
GET/v1/signing-keys

Public 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 ​

CodeDescriptionType
200Keyapplication/json · object

Example response ​

json
{
  "keys": [
    {
      "keyId": "string",
      "publicKey": "string"
    }
  ]
}

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/signing-keys"
GET/v1/scm-oauth

GitHub/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 ​

CodeDescriptionType
200List of appsapplication/json · object

Example response ​

json
{
  "clients": [
    {
      "host": "gitlab.example.com",
      "scheme": "http",
      "kind": "github",
      "clientId": "string",
      "deviceFlow": false,
      "scopes": []
    }
  ]
}

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/scm-oauth"
GET/v1/client-config

Addresses 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 ​

CodeDescriptionType
200Client configurationapplication/json · object

Example response ​

json
{
  "ryomaUrl": "https://ryoma.example.com"
}

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/client-config"
POST/v1/locks

Resolve 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) ​

FieldTypeRequiredDescription
resourcesobject[]yes

Responses ​

CodeDescriptionType
200Resolved lockapplication/json · object
400Invalid input or resource does not existapplication/problem+json · object
401Not signed inapplication/problem+json · object
409No version set satisfies every constraintapplication/problem+json · object

Example response ​

json
{
  "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 ​

bash
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"}]}'
GET/v1/locks/{lockId}

Lock and current state of each version (to warn about versions yanked after locking)

Parameters ​

NameInTypeRequiredDescription
lockIdpathstringyes

Responses ​

CodeDescriptionType
200Lockapplication/json · object
401Not signed inapplication/problem+json · object
404Not foundapplication/problem+json · object

Example response ​

json
{
  "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 ​

bash
curl "https://tara.phillipcli.cloud/v1/locks/<lockId>" \
  -H "Authorization: Bearer $TARA_TOKEN"
GET/claude/locks/{lockId}/marketplace.json

Claude 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 ​

NameInTypeRequiredDescription
lockIdpathstringyes

Responses ​

CodeDescriptionType
200marketplace.jsonapplication/json · object
401Not signed inapplication/problem+json · object
404Not foundapplication/problem+json · object

Example response ​

json
{
  "name": "ai-forge",
  "description": "string",
  "owner": {
    "name": "string"
  },
  "plugins": [
    {
      "name": "string",
      "displayName": "string",
      "description": "string",
      "source": {},
      "metadata": {}
    }
  ]
}

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/claude/locks/<lockId>/marketplace.json" \
  -H "Authorization: Bearer $TARA_TOKEN"
GET/claude/marketplace.json

Claude 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 ​

CodeDescriptionType
200marketplace.jsonapplication/json · object
401Not signed inapplication/problem+json · object

Example response ​

json
{
  "name": "ai-forge",
  "description": "string",
  "owner": {
    "name": "string"
  },
  "plugins": [
    {
      "name": "string",
      "displayName": "string",
      "description": "string",
      "source": {},
      "metadata": {}
    }
  ]
}

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/claude/marketplace.json" \
  -H "Authorization: Bearer $TARA_TOKEN"