Skip to content

API Tara: authoring ​

Author resources on the Portal (wizard, new 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.

POST/v1/drafts/scaffold

Scaffold a starter package for a new resource (wizard on the Portal)

Checks the type, name (including duplicates) and permission on the organization, then returns the starter file set. Nothing is saved.

Body (application/json) ​

FieldTypeRequiredDescription
kindskill | agent | kit | prompt | harnessyes
namestringyes
orgstringyesaiforge or the submitter's organization slug: a reviewed resource. Empty: a personal resource in the community channel (no review, no kit)
displayNamestringyes
descriptionstringyes
rolesstring[]
keywordsstring[]
authorNamestringyes
authorEmailstring
ownersstring[]yesEmails of the people responsible
dependenciesobject[]

Responses ​

CodeDescriptionType
200Starter file setapplication/json · object
400Invalid inputapplication/problem+json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
409Conflictapplication/problem+json · object

Example response ​

json
{
  "files": [
    {
      "path": "agents/ba.md",
      "content": "string",
      "encoding": "utf8",
      "executable": false
    }
  ]
}

Call with curl ​

bash
curl -X POST "https://tara.phillipcli.cloud/v1/drafts/scaffold" \
  -H "Authorization: Bearer $TARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"kind":"skill","name":"agent-java-review","org":"acme","displayName":"string","description":"string","authorName":"string","owners":["string"]}'
POST/v1/drafts/release

Set a new version and CHANGELOG entry in the file set being edited

Only transforms the file set (plugin.json, CHANGELOG.md) and returns it; nothing is saved. Submit it through /v1/submissions like an uploaded package.

Body (application/json) ​

FieldTypeRequiredDescription
filesobject[]yes
versionstringyes
changelogstringyesCHANGELOG entry content (Markdown)

Responses ​

CodeDescriptionType
200File set with the version appliedapplication/json · object
400Invalid inputapplication/problem+json · object
401Not signed inapplication/problem+json · object

Example response ​

json
{
  "files": [
    {
      "path": "agents/ba.md",
      "content": "string",
      "encoding": "utf8",
      "executable": false
    }
  ]
}

Call with curl ​

bash
curl -X POST "https://tara.phillipcli.cloud/v1/drafts/release" \
  -H "Authorization: Bearer $TARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"files":[{"path":"agents/ba.md","content":"string","encoding":"utf8","executable":false}],"version":"1.1.0","changelog":"string"}'
GET/v1/versions/{id}/source

All files of a version, as a starting point for a new version

Parameters ​

NameInTypeRequiredDescription
idpathstringyes

Responses ​

CodeDescriptionType
200File set and suggested version numberapplication/json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object

Example response ​

json
{
  "id": "string",
  "name": "string",
  "kind": "skill",
  "org": "string",
  "version": "string",
  "displayName": "string",
  "state": "submitted",
  "files": [
    {
      "path": "agents/ba.md",
      "content": "string",
      "encoding": "utf8",
      "executable": false
    }
  ],
  "suggestions": {
    "current": "string",
    "patch": "string",
    "minor": "string",
    "major": "string"
  }
}

Call with curl ​

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