Skip to content

API Tara: publishing ​

Submit resources, view submissions and versions

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.

PUT/v1/resources/{name}/visibilityAdmin

Change a resource's visibility (private or internal to public and back)

Personal resources are private or public (owner only); organization resources are internal or public (organization owner or admin). Making a resource public rescans every installable version with the community rules (no executable components, scanner, model review); errors keep it as it was (409). You cannot close a public resource again once another public resource depends on it, or once it is pinned in a project lock (409). Signatures of installable versions are re-issued because the channel changes.

Parameters ​

NameInTypeRequiredDescription
namepathstringyes
orgquerystringSlug of the owner (full name <owner>/<name>); omitted: the current organization's resource, then your personal one

Body (application/json) ​

FieldTypeRequiredDescription
visibilityprivate | internal | publicyesprivate (personal resources) is visible and installable only by the owner; internal (organization resources) by every member of the organization, viewers included; public by every PhillipCLI user, labeled Community. official resources are always public. A personal resource is private or public, an organization resource internal or public.

Responses ​

CodeDescriptionType
204Visibility changed
400Invalid inputapplication/problem+json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object
409Conflictapplication/problem+json · object

Call with curl ​

bash
curl -X PUT "https://tara.phillipcli.cloud/v1/resources/<name>/visibility" \
  -H "Authorization: Bearer $TARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"visibility":"private"}'
POST/v1/resources/{name}/contribute

Contribute a personal resource to an organization (copy, no review)

Copies the latest released version of one of your personal resources to <org>/<name> (internal), records who contributed it and where it came from, signs it for the organization and releases it immediately. The publish policy of the organization applies (member or admin; viewers never). Contributing again copies a newer version into the same organization resource. 409 if the name is taken by something else.

Parameters ​

NameInTypeRequiredDescription
namepathstringyes
orgquerystringYour own namespace, when {name} is given as part of a full name; optional

Body (application/json) ​

FieldTypeRequiredDescription
orgstringyesSlug of the target organization (you must be a member)

Responses ​

CodeDescriptionType
201Contributedapplication/json · object
400Invalid inputapplication/problem+json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object
409Conflictapplication/problem+json · object

Example response ​

json
{
  "org": "string",
  "name": "string",
  "fullName": "acme/skill-notes",
  "version": "string",
  "contributedBy": "string",
  "sourceName": "an/skill-notes"
}

Call with curl ​

bash
curl -X POST "https://tara.phillipcli.cloud/v1/resources/<name>/contribute" \
  -H "Authorization: Bearer $TARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"org":"string"}'
POST/v1/submissions/preview

Check a package before submitting (nothing is saved)

Body (multipart/form-data) ​

FieldTypeRequiredDescription
packagestring (binary)yesZip file of the resource folder (up to 50 MiB)
ownerstringPublish to this owner (your own handle, an organization slug, or aiforge); overrides metadata.forge.org. Absent: the manifest decides, no org in the manifest means your personal store.
visibilityprivate | internal | publicprivate (personal resources) is visible and installable only by the owner; internal (organization resources) by every member of the organization, viewers included; public by every PhillipCLI user, labeled Community. official resources are always public. A personal resource is private or public, an organization resource internal or public.

Responses ​

CodeDescriptionType
200Check results and package contentsapplication/json · object
400Invalid inputapplication/problem+json · object
401Not signed inapplication/problem+json · object

Example response ​

json
{
  "manifest": {
    "name": "string",
    "displayName": "string",
    "version": "string",
    "description": "string",
    "roles": [
      "string"
    ],
    "keywords": [
      "string"
    ]
  },
  "readme": "string",
  "changelog": "string",
  "files": [
    {
      "path": "string",
      "size": 0,
      "sha256": "string",
      "executable": false
    }
  ],
  "findings": [
    {
      "rule": "string",
      "level": "malware",
      "path": "string",
      "message": "string"
    }
  ],
  "canPublish": false,
  "hasErrors": false
}

Call with curl ​

bash
curl -X POST "https://tara.phillipcli.cloud/v1/submissions/preview" \
  -H "Authorization: Bearer $TARA_TOKEN" \
  -F "package=<package>" \
  -F "owner=<owner>" \
  -F "visibility=<visibility>"
GET/v1/submissions

My submissions

Returns the caller's own submissions. Organizations have no review queue, and the official catalog review is not part of this API.

Parameters ​

NameInTypeRequiredDescription
scopequerymine

Responses ​

CodeDescriptionType
200List of submissionsapplication/json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object

Example response ​

json
{
  "items": [
    {
      "id": "string",
      "name": "string",
      "kind": "skill",
      "org": "string",
      "channel": "official",
      "visibility": "private",
      "version": "string",
      "displayName": "string",
      "state": "submitted",
      "stateReason": "string",
      "submittedBy": "string",
      "submittedAt": "2026-11-01T00:00:00Z",
      "errorCount": 0,
      "warningCount": 0,
      "executableCount": 0
    }
  ]
}

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/submissions" \
  -H "Authorization: Bearer $TARA_TOKEN"
POST/v1/submissions

Publish a resource version (checks run, then it is released)

The owner is owner (form field) or metadata.forge.org: aiforge is the official catalog (platform staff submit, reviewed by platform staff); an organization slug publishes into that organization (allowed by its publish policy: members, or admins only; viewers never), internal by default; absent (or your own handle) is your personal store, private by default. There is no review for personal and organization stores: a version that passes the automatic scanner is released immediately and signed. Executable components are allowed except for public resources. visibility applies to a new resource (public needs the owner, or an organization owner or admin) and must match an existing one. The legacy metadata.forge.center is still read (rnd is aiforge, another value is the current organization) with a deprecation warning. Full resource name: <owner>/<name>.

Body (multipart/form-data) ​

FieldTypeRequiredDescription
packagestring (binary)yesZip file of the resource folder (up to 50 MiB)
ownerstringPublish to this owner (your own handle, an organization slug, or aiforge); overrides metadata.forge.org. Absent: the manifest decides, no org in the manifest means your personal store.
visibilityprivate | internal | publicprivate (personal resources) is visible and installable only by the owner; internal (organization resources) by every member of the organization, viewers included; public by every PhillipCLI user, labeled Community. official resources are always public. A personal resource is private or public, an organization resource internal or public.

Responses ​

CodeDescriptionType
201Submission received; automatic checks run in the backgroundapplication/json · object
400Invalid inputapplication/problem+json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
409Conflictapplication/problem+json · object

Example response ​

json
{
  "id": "string",
  "name": "string",
  "kind": "skill",
  "org": "string",
  "channel": "official",
  "visibility": "private",
  "version": "string",
  "displayName": "string",
  "state": "submitted",
  "stateReason": "string",
  "submittedBy": "string",
  "submittedAt": "2026-11-01T00:00:00Z",
  "errorCount": 0,
  "warningCount": 0,
  "executableCount": 0
}

Call with curl ​

bash
curl -X POST "https://tara.phillipcli.cloud/v1/submissions" \
  -H "Authorization: Bearer $TARA_TOKEN" \
  -F "package=<package>" \
  -F "owner=<owner>" \
  -F "visibility=<visibility>"
GET/v1/versions/{id}

Details of a version (a submission or a released version)

Parameters ​

NameInTypeRequiredDescription
idpathstringyes

Responses ​

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

Example response ​

json
{
  "id": "string",
  "name": "string",
  "kind": "skill",
  "org": "string",
  "channel": "official",
  "visibility": "private",
  "version": "string",
  "displayName": "string",
  "state": "submitted",
  "stateReason": "string",
  "submittedBy": "string",
  "submittedAt": "2026-11-01T00:00:00Z",
  "errorCount": 0,
  "warningCount": 0,
  "executableCount": 0,
  "description": "string",
  "readme": "string",
  "changelog": "string",
  "files": [
    {
      "path": "string",
      "size": 0,
      "sha256": "string",
      "executable": false
    }
  ],
  "findings": [
    {
      "rule": "string",
      "level": "malware",
      "path": "string",
      "message": "string"
    }
  ],
  "sha256": "string",
  "size": 0,
  "canReview": false,
  "canManage": false
}

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/versions/<id>" \
  -H "Authorization: Bearer $TARA_TOKEN"
GET/v1/versions/{id}/file

Content of a file in the package

Parameters ​

NameInTypeRequiredDescription
idpathstringyes
pathquerystringyes

Responses ​

CodeDescriptionType
200File content (text); binary or oversized files only have binary=trueapplication/json · object
401Not signed inapplication/problem+json · object
404Not foundapplication/problem+json · object

Example response ​

json
{
  "path": "string",
  "binary": false,
  "content": "string"
}

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/versions/<id>/file?path=string" \
  -H "Authorization: Bearer $TARA_TOKEN"
GET/v1/versions/{id}/documents/{seq}

Content of a document attached to a version (same view permission as the version details)

Parameters ​

NameInTypeRequiredDescription
idpathstringyes
seqpathintegeryes

Responses ​

CodeDescriptionType
200Document (media type follows the format, for example text/markdown, application/pdf)application/octet-stream · string (binary)
401Not signed inapplication/problem+json · object
404Not foundapplication/problem+json · object

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/versions/<id>/documents/<seq>" \
  -H "Authorization: Bearer $TARA_TOKEN"
GET/v1/document-policy

Policy for attached documents (type, format, required by resource type)

Responses ​

CodeDescriptionType
200Policyapplication/json · object
401Not signed inapplication/problem+json · object

Example response ​

json
{
  "types": [
    {
      "code": "string",
      "name": "string"
    }
  ],
  "formats": [
    {
      "ext": "string",
      "mediaType": "string",
      "maxBytes": 0
    }
  ],
  "required": {},
  "recommended": {}
}

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/document-policy" \
  -H "Authorization: Bearer $TARA_TOKEN"