Skip to content

API Tara: organizations ​

Organizations, members, invitations and projects (path-based organization, see above)

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/orgs

Organizations I belong to, with my role in each

Responses ​

CodeDescriptionType
200List of organizations (empty if the user has none yet)application/json · object
401Not signed inapplication/problem+json · object

Example response ​

json
{
  "items": [
    {
      "slug": "acme",
      "name": "Acme Inc.",
      "plan": "free",
      "platform": false,
      "role": "owner"
    }
  ]
}

Call with curl ​

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

Create an organization (the creator becomes its owner; plan Free)

Slug rules: lowercase letters, digits and hyphens, 2 to 39 characters, no leading, trailing or doubled hyphen, not reserved (aiforge, default, api, v1, auth, login, admin, settings, ...; code slug_reserved). Taken slug: 409 slug_taken. At most 5 organizations per user per day (429). From a Portal or CLI session only. Disabled with 403 org_creation_disabled when the installation runs a single organization (TARA_SINGLE_ORG). The new organization becomes the session's current one.

Body (application/json) ​

FieldTypeRequiredDescription
namestringyes
slugstringyes

Responses ​

CodeDescriptionType
201Createdapplication/json · object
400Invalid inputapplication/problem+json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
409Conflict (error code in code, for example seat_limit)application/problem+json · object
429Rate limit exceededapplication/problem+json · object

Example response ​

json
{
  "id": "string",
  "slug": "string",
  "name": "string",
  "plan": "free",
  "platform": false,
  "role": "owner",
  "publishRole": "member",
  "seats": {
    "used": 0,
    "limit": 0
  },
  "createdAt": "2026-11-01T00:00:00Z"
}

Call with curl ​

bash
curl -X POST "https://tara.phillipcli.cloud/v1/orgs" \
  -H "Authorization: Bearer $TARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme Inc.","slug":"acme"}'
GET/v1/orgs/{org}

An organization I belong to (opening it from a session makes it the session's current organization)

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Responses ​

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

Example response ​

json
{
  "id": "string",
  "slug": "string",
  "name": "string",
  "plan": "free",
  "platform": false,
  "role": "owner",
  "publishRole": "member",
  "seats": {
    "used": 0,
    "limit": 0
  },
  "createdAt": "2026-11-01T00:00:00Z"
}

Call with curl ​

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

Update the organization name or its publish policy (owner or admin; the slug cannot change)

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Body (application/json) ​

FieldTypeRequiredDescription
namestring
publishRolemember | adminWho can publish to the organization (recorded in the audit log)

Responses ​

CodeDescriptionType
200Updatedapplication/json · object
400Invalid inputapplication/problem+json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object

Example response ​

json
{
  "id": "string",
  "slug": "string",
  "name": "string",
  "plan": "free",
  "platform": false,
  "role": "owner",
  "publishRole": "member",
  "seats": {
    "used": 0,
    "limit": 0
  },
  "createdAt": "2026-11-01T00:00:00Z"
}

Call with curl ​

bash
curl -X PATCH "https://tara.phillipcli.cloud/v1/orgs/<org>" \
  -H "Authorization: Bearer $TARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"string","publishRole":"member"}'
GET/v1/orgs/{org}/members

Members of the organization (emails are shown to owners and admins only)

Any member of the organization can call this, with a session or their own API token. Each member lists scm: the GitHub or GitLab accounts Tara knows for them (the account they signed in with, or connected). Bandum uses it to offer people for task roles (@login on the repo's host). A member with no entry for a host has not connected that host yet.

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Responses ​

CodeDescriptionType
200Members, highest role firstapplication/json · object
401Not signed inapplication/problem+json · object
404Not foundapplication/problem+json · object

Example response ​

json
{
  "items": [
    {
      "login": "string",
      "name": "string",
      "avatarUrl": "string",
      "email": "string",
      "role": "owner",
      "source": "manual",
      "joinedAt": "2026-11-01T00:00:00Z"
    }
  ]
}

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/orgs/<org>/members" \
  -H "Authorization: Bearer $TARA_TOKEN"
PATCH/v1/orgs/{org}/members/{user}

Change a member's role (owner or admin; only an owner grants or revokes owner; the last owner cannot be demoted)

Moving a viewer to owner, admin or member needs a free seat (409 seat_limit on the Free plan). Demoting the last owner: 409 last_owner.

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)
userpathstringyesLogin of the member

Body (application/json) ​

FieldTypeRequiredDescription
roleowner | admin | member | vieweryesRole in an organization. owner and admin manage the organization and review its private resources; member uses Phillip and submits resources; viewer only reads in the browser (BA, PO, PM) and takes no paid seat.

Responses ​

CodeDescriptionType
200Updatedapplication/json · object
400Invalid inputapplication/problem+json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object
409Conflict (error code in code, for example seat_limit)application/problem+json · object

Example response ​

json
{
  "login": "string",
  "name": "string",
  "avatarUrl": "string",
  "email": "string",
  "role": "owner",
  "source": "manual",
  "joinedAt": "2026-11-01T00:00:00Z"
}

Call with curl ​

bash
curl -X PATCH "https://tara.phillipcli.cloud/v1/orgs/<org>/members/<user>" \
  -H "Authorization: Bearer $TARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role":"owner"}'
DELETE/v1/orgs/{org}/members/{user}

Remove a member (owner or admin), or leave the organization yourself; the last owner cannot be removed or leave

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)
userpathstringyesLogin of the member

Responses ​

CodeDescriptionType
204Removed
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object
409Conflict (error code in code, for example seat_limit)application/problem+json · object

Call with curl ​

bash
curl -X DELETE "https://tara.phillipcli.cloud/v1/orgs/<org>/members/<user>" \
  -H "Authorization: Bearer $TARA_TOKEN"
GET/v1/orgs/{org}/invites

Invitations of the organization that were not revoked (owner or admin)

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Responses ​

CodeDescriptionType
200Invitations, newest firstapplication/json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object

Example response ​

json
{
  "items": [
    {
      "id": "string",
      "email": "string",
      "role": "admin",
      "status": "active",
      "expiresAt": "2026-11-01T00:00:00Z",
      "maxUses": 0,
      "used": 0,
      "invitedBy": "string",
      "createdAt": "2026-11-01T00:00:00Z"
    }
  ]
}

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/orgs/<org>/invites" \
  -H "Authorization: Bearer $TARA_TOKEN"
POST/v1/orgs/{org}/invites

Invite by email or create an invitation link (owner or admin)

With email: a single-use invitation only the holder of that verified email can accept; the accept address is emailed to the recipient (emailSent). If no mail server is configured or sending fails, the invitation is still created and emailSent is false with acceptUrl returned so you can pass the link on yourself. Without email: a link invitation, maxUses configurable (1 to 1000, default 1), and acceptUrl is returned once. expiresAt defaults to 7 days (at most 90). An invitation for a seat role (admin, member) needs a free seat now (409 seat_limit). At most 100 invitations per organization per day (429).

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Body (application/json) ​

FieldTypeRequiredDescription
emailstringOmit for a link invitation
roleadmin | member | vieweryes
expiresAtstring (date-time)Default 7 days from now, at most 90
maxUsesintegerLink invitations only (default 1); an email invitation is single-use

Responses ​

CodeDescriptionType
201Createdapplication/json · object
400Invalid inputapplication/problem+json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object
409Conflict (error code in code, for example seat_limit)application/problem+json · object
429Rate limit exceededapplication/problem+json · object

Example response ​

json
{
  "invite": {
    "id": "string",
    "email": "string",
    "role": "admin",
    "status": "active",
    "expiresAt": "2026-11-01T00:00:00Z",
    "maxUses": 0,
    "used": 0,
    "invitedBy": "string",
    "createdAt": "2026-11-01T00:00:00Z"
  },
  "acceptUrl": "string",
  "emailSent": false
}

Call with curl ​

bash
curl -X POST "https://tara.phillipcli.cloud/v1/orgs/<org>/invites" \
  -H "Authorization: Bearer $TARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"string","role":"admin","expiresAt":"2026-11-01T00:00:00Z","maxUses":1}'
DELETE/v1/orgs/{org}/invites/{id}

Revoke an invitation (owner or admin)

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)
idpathstringyes

Responses ​

CodeDescriptionType
204Revoked
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object

Call with curl ​

bash
curl -X DELETE "https://tara.phillipcli.cloud/v1/orgs/<org>/invites/<id>" \
  -H "Authorization: Bearer $TARA_TOKEN"
GET/v1/orgs/{org}/device-tokens

Device enrollment tokens of the organization (owner or admin)

Tokens that let a machine installed by MDM (ph guardrails install --device-token) read the organization's Guardrails policies before anyone has signed in. Values are never returned here; only the first characters (prefix), who created it, when, and when it was last used.

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Responses ​

CodeDescriptionType
200Active tokens, newest firstapplication/json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object

Example response ​

json
{
  "items": [
    {
      "id": "string",
      "name": "string",
      "prefix": "string",
      "createdBy": "string",
      "createdAt": "2026-11-01T00:00:00Z",
      "expiresAt": "2026-11-01T00:00:00Z"
    }
  ]
}

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/orgs/<org>/device-tokens" \
  -H "Authorization: Bearer $TARA_TOKEN"
POST/v1/orgs/{org}/device-tokens

Create a device enrollment token (owner or admin, from a Portal or CLI session only)

The token carries the guardrails scope and is bound to this organization. It can only read the organization's effective Guardrails policy list (GET /v1/orgs/{org}/guardrails/policies, platform and organization tiers) and download those policy packages with their signatures and the revocation lists; every other route answers 403. The secret is returned once. Creating and revoking are written to the audit log.

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Body (application/json) ​

FieldTypeRequiredDescription
namestringyes
lifetimeDaysinteger

Responses ​

CodeDescriptionType
201New token. The secret value is returned only once.application/json · object
400Invalid inputapplication/problem+json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object
409Too many device tokensapplication/problem+json · object

Example response ​

json
{
  "token": {
    "id": "string",
    "name": "string",
    "prefix": "string",
    "createdBy": "string",
    "createdAt": "2026-11-01T00:00:00Z",
    "expiresAt": "2026-11-01T00:00:00Z"
  },
  "secret": "string",
  "org": "string"
}

Call with curl ​

bash
curl -X POST "https://tara.phillipcli.cloud/v1/orgs/<org>/device-tokens" \
  -H "Authorization: Bearer $TARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme laptops (Jamf)","lifetimeDays":365}'
DELETE/v1/orgs/{org}/device-tokens/{id}

Revoke a device enrollment token (owner or admin)

Machines holding it stop getting policy on their next refresh (they keep the last verified policy until then).

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)
idpathstringyes

Responses ​

CodeDescriptionType
204Revoked
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object

Call with curl ​

bash
curl -X DELETE "https://tara.phillipcli.cloud/v1/orgs/<org>/device-tokens/<id>" \
  -H "Authorization: Bearer $TARA_TOKEN"
GET/v1/orgs/{org}/scim-tokens

SCIM tokens of the organization (owner, from a Portal or CLI session only)

Tokens an identity provider (Okta, Microsoft Entra ID) uses to provision users and groups at baseUrl (/scim/v2/orgs/{org}). Values are never returned here; only the first characters (prefix), who created it, when, and when it was last used.

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Responses ​

CodeDescriptionType
200Active tokens, newest firstapplication/json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object

Example response ​

json
{
  "items": [
    {
      "id": "string",
      "name": "string",
      "prefix": "string",
      "createdBy": "string",
      "createdAt": "2026-11-01T00:00:00Z",
      "expiresAt": "2026-11-01T00:00:00Z"
    }
  ],
  "baseUrl": "string"
}

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/orgs/<org>/scim-tokens" \
  -H "Authorization: Bearer $TARA_TOKEN"
POST/v1/orgs/{org}/scim-tokens

Create a SCIM token (owner, from a Portal or CLI session only)

The token carries the scim scope (prefix tara_scim_) and is bound to this organization. It can only call /scim/v2/orgs/{org}/… of this organization; every other route answers 403. The secret is returned once. Creating and revoking are written to the audit log. Needs the scim feature (Enterprise only; 402 feature_not_in_plan otherwise). Once the plan loses it, every /scim/v2 call of the organization answers 403 with a SCIM error whose detail says so (SCIM clients do not understand 402); revoking tokens stays allowed.

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Body (application/json) ​

FieldTypeRequiredDescription
namestringyes
lifetimeDaysinteger

Responses ​

CodeDescriptionType
201New token. The secret value is returned only once.application/json · object
400Invalid inputapplication/problem+json · object
401Not signed inapplication/problem+json · object
402The plan does not include this feature (feature_not_in_plan, with feature and upgradeUrl)application/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object
409Too many SCIM tokensapplication/problem+json · object

Example response ​

json
{
  "token": {
    "id": "string",
    "name": "string",
    "prefix": "string",
    "createdBy": "string",
    "createdAt": "2026-11-01T00:00:00Z",
    "expiresAt": "2026-11-01T00:00:00Z"
  },
  "secret": "string",
  "org": "string",
  "baseUrl": "string"
}

Call with curl ​

bash
curl -X POST "https://tara.phillipcli.cloud/v1/orgs/<org>/scim-tokens" \
  -H "Authorization: Bearer $TARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Okta","lifetimeDays":365}'
DELETE/v1/orgs/{org}/scim-tokens/{id}

Revoke a SCIM token (owner, from a Portal or CLI session only)

The identity provider holding it gets 401 on its next request.

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)
idpathstringyes

Responses ​

CodeDescriptionType
204Revoked
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object

Call with curl ​

bash
curl -X DELETE "https://tara.phillipcli.cloud/v1/orgs/<org>/scim-tokens/<id>" \
  -H "Authorization: Bearer $TARA_TOKEN"
GET/v1/orgs/{org}/scim-roles

Mapping from SCIM group names to organization roles (owner, from a Portal or CLI session only)

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Responses ​

CodeDescriptionType
200The mapping (scimGroupRoles); empty when none is setapplication/json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object

Example response ​

json
{
  "groupRoles": {
    "Engineering": "member",
    "Platform": "admin",
    "Stakeholders": "viewer"
  }
}

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/orgs/<org>/scim-roles" \
  -H "Authorization: Bearer $TARA_TOKEN"
PUT/v1/orgs/{org}/scim-roles

Set the mapping from SCIM group names to organization roles (owner, from a Portal or CLI session only)

Replaces the whole mapping, then recomputes the role of every provisioned user who has a Tara account. A person in several groups gets the highest role. Roles are admin, member or viewer; SCIM never grants or removes owner (400). Members whose role was set by hand (or by an invitation) keep it. Applying the mapping goes through the plan's seat limit and fails with 409 seat_limit if it would exceed it (nothing is changed).

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Body (application/json) ​

FieldTypeRequiredDescription
groupRolesobjectyesSCIM group name (displayName, case-insensitive) to organization role

Responses ​

CodeDescriptionType
200The mapping after the changeapplication/json · object
400Invalid mappingapplication/problem+json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object
409Seat limit reachedapplication/problem+json · object

Example response ​

json
{
  "groupRoles": {
    "Engineering": "member",
    "Platform": "admin",
    "Stakeholders": "viewer"
  }
}

Call with curl ​

bash
curl -X PUT "https://tara.phillipcli.cloud/v1/orgs/<org>/scim-roles" \
  -H "Authorization: Bearer $TARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"groupRoles":{"Engineering":"member","Platform":"admin","Stakeholders":"viewer"}}'
GET/v1/orgs/{org}/domains

Email domains of the organization, verified or waiting for the DNS record (owner or admin)

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Responses ​

CodeDescriptionType
200Domains, oldest firstapplication/json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object

Example response ​

json
{
  "items": [
    {
      "domain": "string",
      "status": "pending",
      "txtName": "string",
      "txtValue": "string",
      "createdAt": "2026-11-01T00:00:00Z"
    }
  ]
}

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/orgs/<org>/domains" \
  -H "Authorization: Bearer $TARA_TOKEN"
POST/v1/orgs/{org}/domains

Add an email domain to verify (owner or admin)

Returns the DNS TXT record to create: name _aiforge-verify.<domain>, value aiforge-verify=<token>. Public email domains (gmail.com, outlook.com, …) and their subdomains are rejected (400). Adding the same domain again returns it unchanged (idempotent). Several organizations may add the same domain, but only the first to verify it keeps it (409 domain_taken on verify).

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Body (application/json) ​

FieldTypeRequiredDescription
domainstringyesDomain name, for example acme.com (case-insensitive)

Responses ​

CodeDescriptionType
201Added (or already added)application/json · object
400Invalid domain or a public email domainapplication/problem+json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object
429Rate limit exceededapplication/problem+json · object

Example response ​

json
{
  "domain": "string",
  "status": "pending",
  "txtName": "string",
  "txtValue": "string",
  "createdAt": "2026-11-01T00:00:00Z"
}

Call with curl ​

bash
curl -X POST "https://tara.phillipcli.cloud/v1/orgs/<org>/domains" \
  -H "Authorization: Bearer $TARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain":"string"}'
PATCH/v1/orgs/{org}/domains/{domain}

Set the role people with a verified email at this domain get when they sign in (owner or admin)

autoJoinRole null turns auto-join off. Only a verified domain can auto-join (409 domain_not_verified). Owner and admin cannot be granted this way.

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)
domainpathstringyesDomain name, for example acme.com

Body (application/json) ​

FieldTypeRequiredDescription
autoJoinRolemember | vieweryes

Responses ​

CodeDescriptionType
200Updatedapplication/json · object
400Invalid inputapplication/problem+json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object
409Conflict (error code in code, for example domain_not_verified)application/problem+json · object

Example response ​

json
{
  "domain": "string",
  "status": "pending",
  "txtName": "string",
  "txtValue": "string",
  "createdAt": "2026-11-01T00:00:00Z"
}

Call with curl ​

bash
curl -X PATCH "https://tara.phillipcli.cloud/v1/orgs/<org>/domains/<domain>" \
  -H "Authorization: Bearer $TARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"autoJoinRole":"member"}'
DELETE/v1/orgs/{org}/domains/{domain}

Remove a domain (owner or admin); people who already joined through it stay members

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)
domainpathstringyesDomain name, for example acme.com

Responses ​

CodeDescriptionType
204Removed
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object

Call with curl ​

bash
curl -X DELETE "https://tara.phillipcli.cloud/v1/orgs/<org>/domains/<domain>" \
  -H "Authorization: Bearer $TARA_TOKEN"
POST/v1/orgs/{org}/domains/{domain}/verify

Look up the DNS TXT record and mark the domain verified (owner or admin)

Resolves the TXT records of _aiforge-verify.<domain>. 200 with status: verified when aiforge-verify=<token> is among them (or the domain was already verified by this organization). 409 dns_record_not_found while the record is missing (DNS can take a while to spread; try again). 409 domain_taken when another organization verified the domain first.

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)
domainpathstringyesDomain name, for example acme.com

Responses ​

CodeDescriptionType
200Verifiedapplication/json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object
409Record not found or domain taken (error code in code)application/problem+json · object
429Rate limit exceededapplication/problem+json · object

Example response ​

json
{
  "domain": "string",
  "status": "pending",
  "txtName": "string",
  "txtValue": "string",
  "createdAt": "2026-11-01T00:00:00Z"
}

Call with curl ​

bash
curl -X POST "https://tara.phillipcli.cloud/v1/orgs/<org>/domains/<domain>/verify" \
  -H "Authorization: Bearer $TARA_TOKEN"
GET/v1/orgs/{org}/sso

Single sign-on (OIDC) of the organization (owner or admin)

Always 200: configured: false when the organization has not set it up. The client secret is never returned, only hasSecret. callbackUrl is the redirect URI to register in the identity provider. available is false when the server has no key to encrypt secrets (TARA_SECRET_KEY), in which case SSO cannot be configured. domains are the verified email domains "require SSO" applies to. Session only (Portal or ph login); a token gets 403.

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Responses ​

CodeDescriptionType
200Statusapplication/json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object

Example response ​

json
{
  "configured": false,
  "available": false,
  "callbackUrl": "string",
  "domains": [
    "string"
  ]
}

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/orgs/<org>/sso" \
  -H "Authorization: Bearer $TARA_TOKEN"
PUT/v1/orgs/{org}/sso

Create or change the single sign-on configuration (owner or admin)

The first call needs issuer, clientId and clientSecret; later calls send only what changes. Tara fetches <issuer>/.well-known/openid-configuration and the signing keys first and saves nothing if the provider cannot be reached or does not match (400 sso_discovery_failed). In production the issuer must be https and a public address (400 sso_issuer_blocked for private, loopback and link-local addresses). Changing issuer, client id or secret clears the last successful test and turns "require SSO" off. enforce: true needs a successful test (409 sso_not_tested) and a verified domain (409 sso_no_domain). jitRole is the role of people who sign in through the provider and are not members yet: viewer, member or none (never admin or owner). 400 sso_secret_required; 409 sso_unavailable when the server cannot encrypt secrets. Every change is written to the audit log.

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Body (application/json) ​

FieldTypeRequiredDescription
issuerstringOIDC issuer, for example https://login.microsoftonline.com/<tenant>/v2.0
clientIdstring
clientSecretstringOnly when it changes; stored encrypted and never returned
scopesstring[]Default openid profile email
claimLoginstringClaim holding the login (default preferred_username, then the email name)
claimEmailstringClaim holding the email (default email)
claimNamestringClaim holding the display name (default name)
jitRoleviewer | member | none
enabledboolean
enforceboolean

Responses ​

CodeDescriptionType
200Savedapplication/json · object
400Invalid input or the identity provider cannot be reached (error code in code)application/problem+json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object
409Conflict (error code in code, for example sso_not_tested)application/problem+json · object

Example response ​

json
{
  "configured": false,
  "available": false,
  "callbackUrl": "string",
  "domains": [
    "string"
  ]
}

Call with curl ​

bash
curl -X PUT "https://tara.phillipcli.cloud/v1/orgs/<org>/sso" \
  -H "Authorization: Bearer $TARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"issuer":"string","clientId":"string","clientSecret":"string","scopes":["string"]}'
DELETE/v1/orgs/{org}/sso

Remove the single sign-on configuration (owner or admin)

Deletes the configuration and the sign-in identities linked to it. Members keep their membership and can use their other sign-in methods.

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Responses ​

CodeDescriptionType
204Removed
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object

Call with curl ​

bash
curl -X DELETE "https://tara.phillipcli.cloud/v1/orgs/<org>/sso" \
  -H "Authorization: Bearer $TARA_TOKEN"
POST/v1/orgs/{org}/sso/test

Check the saved single sign-on configuration against the identity provider (owner or admin)

Fetches the discovery document and the signing keys again. Always 200; ok tells the result and error the reason. A successful test is required before "require SSO" can be turned on.

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Responses ​

CodeDescriptionType
200Test resultapplication/json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object

Example response ​

json
{
  "ok": false,
  "error": "string"
}

Call with curl ​

bash
curl -X POST "https://tara.phillipcli.cloud/v1/orgs/<org>/sso/test" \
  -H "Authorization: Bearer $TARA_TOKEN"
GET/v1/invites/{code}

Public preview of an invitation (organization name, role, inviter, validity)

Public (no sign-in; the code is a 256-bit secret). Expired, revoked or used-up invitations are shown with their status so the page can explain.

No sign-in required.

Parameters ​

NameInTypeRequiredDescription
codepathstringyes

Responses ​

CodeDescriptionType
200The invitationapplication/json · object
404Not foundapplication/problem+json · object

Example response ​

json
{
  "org": {
    "slug": "string",
    "name": "string"
  },
  "role": "admin",
  "invitedBy": "string",
  "emailHint": "string",
  "status": "active",
  "expiresAt": "2026-11-01T00:00:00Z"
}

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/invites/<code>"
POST/v1/invites/{code}/accept

Accept an invitation (signed in)

Idempotent: someone who is already a member gets 200 with alreadyMember: true and nothing changes. An invitation by email needs the signed-in user's verified email to match (case-insensitive; 403 invite_email_mismatch or email_not_verified). Expired, revoked or used-up: 409 invite_expired, invite_revoked, invite_used_up. No free seat: 409 seat_limit. The joined organization becomes the session's current one.

Parameters ​

NameInTypeRequiredDescription
codepathstringyes

Responses ​

CodeDescriptionType
200Joined (or already a member)application/json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object
409Conflict (error code in code, for example seat_limit)application/problem+json · object

Example response ​

json
{
  "org": {
    "slug": "acme",
    "name": "Acme Inc.",
    "plan": "free",
    "platform": false,
    "role": "owner"
  },
  "alreadyMember": false
}

Call with curl ​

bash
curl -X POST "https://tara.phillipcli.cloud/v1/invites/<code>/accept" \
  -H "Authorization: Bearer $TARA_TOKEN"
POST/v1/me/invites/{id}/accept

Accept one of my pending invitations by email (the ones listed in `pendingInvites` of /v1/me)

Parameters ​

NameInTypeRequiredDescription
idpathstringyes

Responses ​

CodeDescriptionType
200Joined (or already a member)application/json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object
409Conflict (error code in code, for example seat_limit)application/problem+json · object

Example response ​

json
{
  "org": {
    "slug": "acme",
    "name": "Acme Inc.",
    "plan": "free",
    "platform": false,
    "role": "owner"
  },
  "alreadyMember": false
}

Call with curl ​

bash
curl -X POST "https://tara.phillipcli.cloud/v1/me/invites/<id>/accept" \
  -H "Authorization: Bearer $TARA_TOKEN"
GET/v1/orgs/{org}/projects

Projects of the organization

Projects the caller can see. A private project (visibility: private) is listed only for owners, admins and the project's members. A service account with scope scm (Ryoma, Bandum) sees every project and may add visibleTo=<login> to get exactly the projects that organization member can see (an unknown login gives an empty list); any other caller using visibleTo gets 403.

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)
visibleToquerystringService accounts only: the login whose view of the projects is wanted

Responses ​

CodeDescriptionType
200Projectsapplication/json · object
401Not signed inapplication/problem+json · object
403visibleTo used by a caller that is not a service accountapplication/problem+json · object
404Not foundapplication/problem+json · object

Example response ​

json
{
  "items": [
    {
      "visibility": "org",
      "key": "shop-web",
      "name": "string",
      "repos": [],
      "releaseApprovers": [],
      "createdBy": "string",
      "createdAt": "2026-11-01T00:00:00Z"
    }
  ]
}

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/orgs/<org>/projects" \
  -H "Authorization: Bearer $TARA_TOKEN"
POST/v1/orgs/{org}/projects

Create a project (any seat role; the creator becomes its project admin)

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Body (application/json) ​

FieldTypeRequiredDescription
keystringyes
namestringyes
reposstring[]

Responses ​

CodeDescriptionType
201Createdapplication/json · object
400Invalid inputapplication/problem+json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object
409Conflict (error code in code, for example seat_limit)application/problem+json · object

Example response ​

json
{
  "visibility": "org",
  "key": "shop-web",
  "name": "string",
  "repos": [
    "acme/shop-web"
  ],
  "releaseApprovers": [
    "string"
  ],
  "createdBy": "string",
  "createdAt": "2026-11-01T00:00:00Z"
}

Call with curl ​

bash
curl -X POST "https://tara.phillipcli.cloud/v1/orgs/<org>/projects" \
  -H "Authorization: Bearer $TARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key":"shop-web","name":"string","repos":["string"]}'
POST/v1/orgs/{org}/projects/import

Create several projects at once from connected repositories (same permission as creating one project)

Each row goes through the same rules as POST …/projects and is independent of the others: an error in one row does not stop the next. The results come back in request order. created: the project is new and the caller is its project admin. exists: the key already exists and every repository of the row is already in that project (running the same import again changes nothing). error: bad key or name, a repository that is not part of the connected GitHub installation or GitLab group, a repository already in another project, or a key used by a project with other repositories (error says which). A private row needs an owner or admin, and a plan with private projects (402 for the whole request otherwise). At most 100 rows.

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Body (application/json) ​

FieldTypeRequiredDescription
projectsobject[]yes

Responses ​

CodeDescriptionType
200One result per rowapplication/json · object
400Invalid input (no rowsapplication/problem+json · object
401Not signed inapplication/problem+json · object
402A row asks for a private project and the plan does not include themapplication/problem+json · object
403Forbidden (viewers cannot create projects)application/problem+json · object
404Not foundapplication/problem+json · object

Example response ​

json
{
  "results": [
    {
      "key": "string",
      "status": "created",
      "error": "string"
    }
  ]
}

Call with curl ​

bash
curl -X POST "https://tara.phillipcli.cloud/v1/orgs/<org>/projects/import" \
  -H "Authorization: Bearer $TARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"projects":[{"key":"shop-web","name":"string","repos":[],"visibility":"org"}]}'
GET/v1/orgs/{org}/projects/{key}

A project

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)
keypathstringyes

Responses ​

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

Example response ​

json
{
  "visibility": "org",
  "key": "shop-web",
  "name": "string",
  "repos": [
    "acme/shop-web"
  ],
  "releaseApprovers": [
    "string"
  ],
  "createdBy": "string",
  "createdAt": "2026-11-01T00:00:00Z"
}

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/orgs/<org>/projects/<key>" \
  -H "Authorization: Bearer $TARA_TOKEN"
PATCH/v1/orgs/{org}/projects/{key}

Edit a project (project admin, or organization owner or admin)

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)
keypathstringyes

Body (application/json) ​

FieldTypeRequiredDescription
namestring
reposstring[]

Responses ​

CodeDescriptionType
200Updatedapplication/json · object
400Invalid inputapplication/problem+json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object

Example response ​

json
{
  "visibility": "org",
  "key": "shop-web",
  "name": "string",
  "repos": [
    "acme/shop-web"
  ],
  "releaseApprovers": [
    "string"
  ],
  "createdBy": "string",
  "createdAt": "2026-11-01T00:00:00Z"
}

Call with curl ​

bash
curl -X PATCH "https://tara.phillipcli.cloud/v1/orgs/<org>/projects/<key>" \
  -H "Authorization: Bearer $TARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"string","repos":["string"]}'
DELETE/v1/orgs/{org}/projects/{key}

Delete a project (project admin, or organization owner or admin)

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)
keypathstringyes

Responses ​

CodeDescriptionType
204Deleted
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object

Call with curl ​

bash
curl -X DELETE "https://tara.phillipcli.cloud/v1/orgs/<org>/projects/<key>" \
  -H "Authorization: Bearer $TARA_TOKEN"
GET/v1/orgs/{org}/projects/{key}/release-approvers

Who can approve releases of a project (besides organization owners)

Tara logins that may approve releases of this project in Bandum. Any member of the organization can read it. An empty list means no list: only organization owners and admins can approve. With a list, only the people in it and organization owners can (an admin who is not in the list is refused). This stands in for a project role until project roles exist (the list will then become the role release_approver).

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)
keypathstringyes

Responses ​

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

Example response ​

json
{
  "approvers": [
    "maya.chen"
  ]
}

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/orgs/<org>/projects/<key>/release-approvers" \
  -H "Authorization: Bearer $TARA_TOKEN"
PUT/v1/orgs/{org}/projects/{key}/release-approvers

Set who can approve releases of a project (organization owner or admin)

Replaces the whole list; an empty list clears it. Only an owner or admin of the organization, from the Portal or the CLI (a token cannot). Every login must be a member of the organization (400 approver_not_member otherwise, naming the logins). Duplicates are dropped and logins are written as the member's own spelling. The change is written to the audit log (project.release_approvers, with before and after).

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)
keypathstringyes

Body (application/json) ​

FieldTypeRequiredDescription
approversstring[]yes

Responses ​

CodeDescriptionType
200The list as storedapplication/json · object
400Invalid input (approver_not_member)application/problem+json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object

Example response ​

json
{
  "approvers": [
    "maya.chen"
  ]
}

Call with curl ​

bash
curl -X PUT "https://tara.phillipcli.cloud/v1/orgs/<org>/projects/<key>/release-approvers" \
  -H "Authorization: Bearer $TARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"approvers":["maya.chen"]}'
PUT/v1/orgs/{org}/projects/{key}/visibilityAdmin

Make a project private or visible to the whole organization (organization owner or admin)

private: only owners, admins of the organization and the project's members see the project, its delivery numbers, tracker settings and release approvers; everyone else gets 404 (never 403). org: every member sees it. Only from the Portal or the CLI (a token cannot). The change is written to the audit log (project.visibility, with before and after). Setting private needs the private-projects feature (Team and Enterprise; 402 feature_not_in_plan on Free). Setting org works on every plan, and a project that is already private stays private when the organization moves down to Free: nobody loses privacy because a payment stopped.

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)
keypathstringyes

Body (application/json) ​

FieldTypeRequiredDescription
visibilityorg | privateyes

Responses ​

CodeDescriptionType
200The projectapplication/json · object
400Invalid inputapplication/problem+json · object
401Not signed inapplication/problem+json · object
402The plan does not include this feature (feature_not_in_plan, with feature and upgradeUrl)application/problem+json · object
403Forbiddenapplication/problem+json · object
404Not found (also when the caller cannot see the project)application/problem+json · object

Example response ​

json
{
  "visibility": "org",
  "key": "shop-web",
  "name": "string",
  "repos": [
    "acme/shop-web"
  ],
  "releaseApprovers": [
    "string"
  ],
  "createdBy": "string",
  "createdAt": "2026-11-01T00:00:00Z"
}

Call with curl ​

bash
curl -X PUT "https://tara.phillipcli.cloud/v1/orgs/<org>/projects/<key>/visibility" \
  -H "Authorization: Bearer $TARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"visibility":"org"}'
GET/v1/orgs/{org}/projects/{key}/members

Members of a project

Logins on the project's member list. Anyone who can see the project can read it. A member keeps their organization role; there is no project-only role.

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)
keypathstringyes

Responses ​

CodeDescriptionType
200The listapplication/json · object
401Not signed inapplication/problem+json · object
404Not found (also when the caller cannot see the project)application/problem+json · object

Example response ​

json
{
  "logins": [
    "maya.chen"
  ]
}

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/orgs/<org>/projects/<key>/members" \
  -H "Authorization: Bearer $TARA_TOKEN"
PUT/v1/orgs/{org}/projects/{key}/members

Set the members of a project (organization owner or admin)

Replaces the list of regular members; an empty list removes them all. Every login must be a member of the organization (400 member_not_in_org, naming the logins). Only from the Portal or the CLI. The change is written to the audit log (project.members, with before and after). Members added here can see the project but are not project admins. The list manages only these regular members: project admins (the creator, and anyone granted project admin) are always members, are never removed by this call and always appear in the response, even when missing from the request. Needs the private-projects feature (Team and Enterprise): on Free it answers 402 feature_not_in_plan; reading the list stays open on every plan.

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)
keypathstringyes

Body (application/json) ​

FieldTypeRequiredDescription
loginsstring[]yes

Responses ​

CodeDescriptionType
200The list as storedapplication/json · object
400Invalid input (member_not_in_org)application/problem+json · object
401Not signed inapplication/problem+json · object
402The plan does not include this feature (feature_not_in_plan, with feature and upgradeUrl)application/problem+json · object
403Forbiddenapplication/problem+json · object
404Not found (also when the caller cannot see the project)application/problem+json · object

Example response ​

json
{
  "logins": [
    "maya.chen"
  ]
}

Call with curl ​

bash
curl -X PUT "https://tara.phillipcli.cloud/v1/orgs/<org>/projects/<key>/members" \
  -H "Authorization: Bearer $TARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"logins":["maya.chen"]}'
GET/v1/orgs/{org}/projects/{key}/tracker

Task source of a project (any member; never has the token)

taskSource is scm (default: tasks are GitHub or GitLab issues) or tracker (tasks come from a tracker kit such as kit-tracker-jira). settings are the kit settings (baseUrl, project, email...). tokenSet says whether a token is stored; the token is never returned.

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)
keypathstringyes

Responses ​

CodeDescriptionType
200The task sourceapplication/json · object
401Not signed inapplication/problem+json · object
404Not foundapplication/problem+json · object

Example response ​

json
{
  "taskSource": "scm",
  "kit": "kit-tracker-jira",
  "version": "1.1.0",
  "settings": {
    "baseUrl": "https://acme.atlassian.net",
    "project": "PAY"
  },
  "tokenSet": false
}

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/orgs/<org>/projects/<key>/tracker" \
  -H "Authorization: Bearer $TARA_TOKEN"
PUT/v1/orgs/{org}/projects/{key}/tracker

Set the task source to a tracker kit (organization owner or admin)

Only an owner or admin of the organization, from the Portal or the CLI (a token cannot). Tara checks the kit exists, provides: tracker, and that settings has every key the kit marks required. token is optional: left out, the stored token is kept. The token is encrypted with the server secret key (503 tracker_unavailable when the server has none) and never appears in a response, log or audit entry. The audit entry project.tracker.set has the kit, the version and the settings keys (not the values).

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)
keypathstringyes

Body (application/json) ​

FieldTypeRequiredDescription
kitstringyes
versionstringyes
settingsobjectyes
tokenstringOptional; left out keeps the stored token

Responses ​

CodeDescriptionType
200The task source as storedapplication/json · object
400Invalid input (kit_not_found, kit_not_tracker, tracker_settings_required, tracker_settings_invalid)application/problem+json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object
503The server has no secret key to store a token (tracker_unavailable)application/problem+json · object

Example response ​

json
{
  "taskSource": "scm",
  "kit": "kit-tracker-jira",
  "version": "1.1.0",
  "settings": {
    "baseUrl": "https://acme.atlassian.net",
    "project": "PAY"
  },
  "tokenSet": false
}

Call with curl ​

bash
curl -X PUT "https://tara.phillipcli.cloud/v1/orgs/<org>/projects/<key>/tracker" \
  -H "Authorization: Bearer $TARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"kit":"kit-tracker-jira","version":"1.1.0","settings":{},"token":"string"}'
DELETE/v1/orgs/{org}/projects/{key}/tracker

Back to scm and delete the token (organization owner or admin)

Writes the audit entry project.tracker.clear. Clearing a project that is already on scm is fine.

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)
keypathstringyes

Responses ​

CodeDescriptionType
204Cleared
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object

Call with curl ​

bash
curl -X DELETE "https://tara.phillipcli.cloud/v1/orgs/<org>/projects/<key>/tracker" \
  -H "Authorization: Bearer $TARA_TOKEN"
GET/v1/orgs/{org}/projects/{key}/tracker/credential

Kit, settings and token of a project's tracker (service account with scope scm only)

For Ryoma (ryoma-svc). Returns the same body as GET .../tracker plus the decrypted token and the sha256 of the kit package, so the caller can download and verify that exact version. Members, delegation tokens and service accounts without scope scm get 403. Every read writes one log line (no token in it). 404 tracker_not_set when the project uses scm.

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)
keypathstringyes

Responses ​

CodeDescriptionType
200The credentialapplication/json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object

Example response ​

json
{
  "taskSource": "tracker",
  "kit": "string",
  "version": "string",
  "sha256": "string",
  "settings": {},
  "tokenSet": false,
  "token": "string"
}

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/orgs/<org>/projects/<key>/tracker/credential" \
  -H "Authorization: Bearer $TARA_TOKEN"
GET/v1/orgs/{org}/tracker-identities

Tracker identities of the organization's members for one tracker (members and service accounts with scope scm)

Only members of this organization appear. identity is the tracker's own id of the person (for Jira Cloud the accountId).

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)
baseUrlquerystringyesTracker base URL (compared after normalizing)

Responses ​

CodeDescriptionType
200Members and their identitiesapplication/json · object[]
400Invalid inputapplication/problem+json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object

Example response ​

json
[
  {
    "login": "maya.chen",
    "identity": "string"
  }
]

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/orgs/<org>/tracker-identities?baseUrl=string" \
  -H "Authorization: Bearer $TARA_TOKEN"
GET/v1/orgs/{org}/setup

Setup guide progress of the organization (any member)

Status of each guided-setup step, computed on the server from real data. Six steps, in this order, when the server has a way to connect a source host: connect_github (the organization has a GitHub App installation or a GitLab group), create_project (a project has a repository), standard_labels ("Map your labels": every GitHub repo of the organization's projects that is in the installation has the standard labels, OR an owner or admin confirmed the label map, see /v1/orgs/{org}/label-map; shown when the server has a GitHub App or a usable GitLab connection; the GitHub check is cached about 2 minutes), invite_team (more than one member, a pending invitation, or auto-join from GitHub or GitLab is on), first_telemetry (Ryoma recorded AI cost in the last 90 days), first_review (a task has gone through Review: waiting for testing, tested, approved or sent back). Ryoma-based steps are todo while Ryoma is unreachable. Steps an owner or admin skipped are skipped. ph org setup prints the same checklist.

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Responses ​

CodeDescriptionType
200Setup progressapplication/json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object

Example response ​

json
{
  "steps": [
    {
      "id": "connect_github",
      "status": "done"
    }
  ],
  "dismissed": false,
  "completed": false
}

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/orgs/<org>/setup" \
  -H "Authorization: Bearer $TARA_TOKEN"
GET/v1/orgs/{org}/label-map

The organization's label map (members, and service accounts with scope scm)

Maps the customer's own labels onto the standard ones (status: …, type: …, level: …) without writing anything to their repositories. Kits apply it when they read issues. An organization without a map gets an empty one (map has three empty groups, confirmedAt is null). A token with scope scm that is not bound to an organization may read the map of any organization (Ryoma does this before each sync).

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Responses ​

CodeDescriptionType
200The mapapplication/json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object

Example response ​

json
{
  "map": {
    "status": {
      "in progress": "in progress",
      "needs review": "review",
      "qa passed": "approved",
      "qa failed": "rejected"
    },
    "type": {
      "bug": "bug",
      "enhancement": "feature",
      "tech debt": "debt",
      "security": "risk",
      "issue-type:Bug": "bug"
    },
    "level": {
      "size: small": "S",
      "size: medium": "M",
      "size: large": "L"
    }
  },
  "confirmedAt": "2026-11-01T00:00:00Z",
  "updatedAt": "2026-11-01T00:00:00Z"
}

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/orgs/<org>/label-map" \
  -H "Authorization: Bearer $TARA_TOKEN"
PUT/v1/orgs/{org}/label-map

Replace the label map (owner or admin, session only)

Replaces the whole map. confirm: true also sets confirmedAt, which completes the standard_labels step of the setup guide; without it the previous confirmedAt stays. Keys are the customer's label names (compared case-insensitively, surrounding spaces ignored); a key starting with issue-type: is a native GitHub Issue Type or GitLab work item type. Values: status in {in progress, review, approved, rejected}, type in {feature, bug, debt, risk}, level in {S, M, L}. A label may appear in one group only, standard labels (status:, type:, level:) cannot be mapped, and the map holds at most 200 keys. Invalid input is answered with 422 invalid_label_map and an error per key.

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Body (application/json) ​

FieldTypeRequiredDescription
mapobjectyes
confirmbooleantrue also sets confirmedAt; false or absent keeps the previous confirmedAt

Responses ​

CodeDescriptionType
200Savedapplication/json · object
400Invalid inputapplication/problem+json · object
401Not signed inapplication/problem+json · object
403Not an owner or adminapplication/problem+json · object
404Not foundapplication/problem+json · object
422The map is invalid (code invalid_label_map); errors has one message per label name, _ for errors about the whole mapapplication/problem+json · object

Example response ​

json
{
  "map": {
    "status": {
      "in progress": "in progress",
      "needs review": "review",
      "qa passed": "approved",
      "qa failed": "rejected"
    },
    "type": {
      "bug": "bug",
      "enhancement": "feature",
      "tech debt": "debt",
      "security": "risk",
      "issue-type:Bug": "bug"
    },
    "level": {
      "size: small": "S",
      "size: medium": "M",
      "size: large": "L"
    }
  },
  "confirmedAt": "2026-11-01T00:00:00Z",
  "updatedAt": "2026-11-01T00:00:00Z"
}

Call with curl ​

bash
curl -X PUT "https://tara.phillipcli.cloud/v1/orgs/<org>/label-map" \
  -H "Authorization: Bearer $TARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"map":{"status":{"in progress":"in progress","needs review":"review","qa passed":"approved","qa failed":"rejected"},"type":{"bug":"bug","enhancement":"feature","tech debt":"debt","security":"risk","issue-type:Bug":"bug"},"level":{"size: small":"S","size: medium":"M","size: large":"L"}},"confirm":false}'
GET/v1/orgs/{org}/label-map/suggest

Scan the labels of the organization's repositories and suggest a map (owner or admin)

Reads the labels of every repository of the organization's projects through the GitHub App installation or the GitLab connection, and for a GitHub organization its native Issue Types (skipped quietly when the organization has none). labels lists each distinct label (standard labels left out) with the number of repositories that have it, most common first. suggested comes from a fixed dictionary (no model): for example bug, defect map to type bug, enhancement, feat to feature, wip, doing to status in progress, size: small to level S. Repositories that cannot be read are skipped; the call fails only when none of them can be read.

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Responses ​

CodeDescriptionType
200The scanapplication/json · object
401Not signed inapplication/problem+json · object
403Not an owner or adminapplication/problem+json · object
404Not foundapplication/problem+json · object
502GitHub or GitLab did not answerapplication/problem+json · object
503GitHub or GitLab is not available on this serverapplication/problem+json · object

Example response ​

json
{
  "labels": [
    {
      "name": "string",
      "repos": 0
    }
  ],
  "issueTypes": [
    "string"
  ],
  "suggested": {
    "status": {
      "in progress": "in progress",
      "needs review": "review",
      "qa passed": "approved",
      "qa failed": "rejected"
    },
    "type": {
      "bug": "bug",
      "enhancement": "feature",
      "tech debt": "debt",
      "security": "risk",
      "issue-type:Bug": "bug"
    },
    "level": {
      "size: small": "S",
      "size: medium": "M",
      "size: large": "L"
    }
  },
  "standard": [
    "string"
  ]
}

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/orgs/<org>/label-map/suggest" \
  -H "Authorization: Bearer $TARA_TOKEN"
POST/v1/orgs/{org}/label-map/preview

Preview what a label map would understand on real issues (owner or admin)

Applies map (not saved) to a sample of the organization's issues and tells how many closed issues get a work type. The sample is the 100 most recently updated issues of each of at most 10 repositories of the organization's projects (pull requests left out), read through the GitHub App installation or the GitLab connection. closedRecent counts sampled issues closed in the last 56 days; typedNow how many of those already carry a standard type: … label, typedWithMap how many have a work type once the map is applied (standard labels win, keys are case-insensitive, issue-type:<name> is the native Issue Type). examples are up to 3 real issues with what the map understands, preferring issues that have a type (one per type first). status is done for a closed issue, otherwise the status understood, or todo; type and level are null when not understood. The fetched issues are cached for 5 minutes per organization (the result for a map is not). An invalid map is answered with 422 invalid_label_map, as in PUT. When no repository can be read the call fails with 502.

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Body (application/json) ​

FieldTypeRequiredDescription
mapobjectyes

Responses ​

CodeDescriptionType
200The previewapplication/json · object
400Invalid inputapplication/problem+json · object
401Not signed inapplication/problem+json · object
403Not an owner or adminapplication/problem+json · object
404Not foundapplication/problem+json · object
422The map is invalid (code invalid_label_map); errors has one message per label nameapplication/problem+json · object
502GitHub or GitLab did not answerapplication/problem+json · object
503GitHub or GitLab is not available on this serverapplication/problem+json · object

Example response ​

json
{
  "sampled": 0,
  "closedRecent": 0,
  "typedNow": 0,
  "typedWithMap": 0,
  "examples": [
    {
      "repo": "acme/shop-web",
      "number": 0,
      "title": "string",
      "url": "string",
      "status": "string",
      "type": "string",
      "level": "string"
    }
  ]
}

Call with curl ​

bash
curl -X POST "https://tara.phillipcli.cloud/v1/orgs/<org>/label-map/preview" \
  -H "Authorization: Bearer $TARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"map":{"status":{"in progress":"in progress","needs review":"review","qa passed":"approved","qa failed":"rejected"},"type":{"bug":"bug","enhancement":"feature","tech debt":"debt","security":"risk","issue-type:Bug":"bug"},"level":{"size: small":"S","size: medium":"M","size: large":"L"}}}'
POST/v1/orgs/{org}/label-map/labels

Create a missing label definition on the repositories (owner or admin, session only)

Creates the label definition (no issue gets it) on each repository: GitHub through the App installation token (needs Issues: write), GitLab through the organization's connection (needs the api scope, which the OAuth sign-in does not ask for). repos defaults to every repository of the organization's projects. color is a hex color without #; for a standard name (status: approved, …) the standard color and description are the defaults, otherwise ededed. A label with the same name (case-insensitive) already on a repository counts as existed. Each repository is independent: a failure (for example the installation lacks Issues: write, error then says how to grant it) is listed in failed and does not stop the others. After at least one repository has the label, name → value is added to the label map as a draft (confirmedAt is unchanged) and mapped is true; a standard name is not added (standard labels always count and cannot be mapped), so mapped stays false. A name already mapped to another group or value is refused with 409 label_already_mapped, before anything is created. An audit entry is written.

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Body (application/json) ​

FieldTypeRequiredDescription
namestringyesLabel name, at most 50 characters
colorstringHex color without #; default the standard color, else ededed
descriptionstringAt most 100 characters; default the standard description
dimensionstatus | type | levelyes
valuestringyesstatus: in progress, review, approved, rejected; type: feature, bug, debt, risk; level: S, M, L
reposstring[]Default: every repository of the organization's projects

Responses ​

CodeDescriptionType
200Result per repositoryapplication/json · object
400Invalid inputapplication/problem+json · object
401Not signed inapplication/problem+json · object
403Not an owner or adminapplication/problem+json · object
404Not foundapplication/problem+json · object
409The name is already mapped elsewhere (label_already_mapped)application/problem+json · object
422The resulting map would be invalid (code invalid_label_map, for example more than 200 keys)application/problem+json · object

Example response ​

json
{
  "created": [
    "string"
  ],
  "existed": [
    "string"
  ],
  "failed": [
    {
      "repo": "string",
      "error": "string"
    }
  ],
  "mapped": false
}

Call with curl ​

bash
curl -X POST "https://tara.phillipcli.cloud/v1/orgs/<org>/label-map/labels" \
  -H "Authorization: Bearer $TARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"status: approved","color":"2a78d6","description":"string","dimension":"status","value":"approved"}'
POST/v1/orgs/{org}/setup/skip/{step}

Skip a setup step (owner or admin, session only)

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)
steppathconnect_github | create_project | standard_labels | invite_team | first_telemetry | first_reviewyes

Responses ​

CodeDescriptionType
204Skipped
400Unknown stepapplication/problem+json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object

Call with curl ​

bash
curl -X POST "https://tara.phillipcli.cloud/v1/orgs/<org>/setup/skip/<step>" \
  -H "Authorization: Bearer $TARA_TOKEN"
POST/v1/orgs/{org}/setup/dismiss

Dismiss the setup guide for the whole organization (owner or admin, session only)

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Responses ​

CodeDescriptionType
204Dismissed
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object

Call with curl ​

bash
curl -X POST "https://tara.phillipcli.cloud/v1/orgs/<org>/setup/dismiss" \
  -H "Authorization: Bearer $TARA_TOKEN"
POST/v1/orgs/{org}/notify/events

Send an event to the organization's notification channels (service accounts with scope scm only)

Lets Bandum and Ryoma notify through the channels the organization configured in Settings, Notifications, instead of configuring their own. Only a service account with scope scm may call it; any other caller (session, personal token, even an owner) gets 403. kind must be one of the external kinds (bandum.*, ryoma.*). key (1 to 300 characters) makes the call idempotent: the same key for the same organization within 30 days answers 202 with duplicate: true and queues nothing. to (at most 50) is narrowed to members of the organization (case-insensitive); other addresses are dropped silently. subject is at most 200 characters on one line, text at most 4000, link an http(s) URL of at most 1000. queued is the number of channels that will receive it; it is 0 when no channel takes this kind or the server has no notify plugin pinned.

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug

Body (application/json) ​

FieldTypeRequiredDescription
kindbandum.awaiting_test | bandum.rejected | bandum.test_overdue | bandum.ready_for_release | bandum.release_succeeded | bandum.release_failed | ryoma.quota | ryoma.telemetry_gap | ryoma.task_risks | ryoma.digest | ryoma.guardrailsyes
keystringyesIdempotency key; the same key for the same organization within 30 days is not sent again
subjectstringyesOne line
textstring
linkstringhttp or https URL
tostring[]Email addresses; only members of the organization are kept

Responses ​

CodeDescriptionType
202Acceptedapplication/json · object
400Invalid inputapplication/problem+json · object
401Not signed inapplication/problem+json · object
403Not a service account with scope scmapplication/problem+json · object
404Not foundapplication/problem+json · object

Example response ​

json
{
  "queued": 0,
  "duplicate": false
}

Call with curl ​

bash
curl -X POST "https://tara.phillipcli.cloud/v1/orgs/<org>/notify/events" \
  -H "Authorization: Bearer $TARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"kind":"bandum.awaiting_test","key":"string","subject":"string","text":"string"}'
GET/v1/orgs/{org}/exports

Data exports of the organization, newest first (owner, from a Portal or CLI session)

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Responses ​

CodeDescriptionType
200The latest exports and their stateapplication/json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object

Example response ​

json
{
  "items": [
    {
      "id": "string",
      "status": "pending",
      "requestedBy": "string",
      "createdAt": "2026-11-01T00:00:00Z"
    }
  ]
}

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/orgs/<org>/exports" \
  -H "Authorization: Bearer $TARA_TOKEN"
POST/v1/orgs/{org}/exports

Ask for an export of all the organization's data (owner, from a Portal or CLI session; at most once every 24 hours)

A background job builds one ZIP: a JSON file per kind of data (organization, members, invites, projects, tracker settings without tokens, resources and version metadata without package content, Guardrails policy declarations, audit log, billing summary, device token metadata without token values) and, from Ryoma, ryoma/ (projects, task copy, weekly Flow and AI cost, sessions without prompt content), plus manifest.json with the SHA-256 of every file. The file is kept 7 days under exports/ in the package store. When it is ready the requester gets an email with a link to the Portal (not to the file). Recorded in the audit log as org.export.request and org.export.download.

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Responses ​

CodeDescriptionType
202The export was queuedapplication/json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object
409An export was already requested in the last 24 hours (code export_rate_limited)application/problem+json · object

Example response ​

json
{
  "id": "string",
  "status": "pending",
  "requestedBy": "string",
  "createdAt": "2026-11-01T00:00:00Z"
}

Call with curl ​

bash
curl -X POST "https://tara.phillipcli.cloud/v1/orgs/<org>/exports" \
  -H "Authorization: Bearer $TARA_TOKEN"
GET/v1/orgs/{org}/exports/{id}/download

Download an export (owner, from a Portal or CLI session)

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)
idpathstringyes

Responses ​

CodeDescriptionType
200The ZIP fileapplication/zip · string (binary)
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object
409The export is not ready yet (code export_not_ready)application/problem+json · object
410The export has expired (kept 7 days)application/problem+json · object

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/orgs/<org>/exports/<id>/download" \
  -H "Authorization: Bearer $TARA_TOKEN"
GET/v1/orgs/{org}/deletion

State of the organization deletion (owner, from a Portal or CLI session)

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Responses ​

CodeDescriptionType
200state is none or pending_deletion (with the date of the real deletion)application/json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object

Example response ​

json
{
  "state": "none",
  "requestedAt": "2026-11-01T00:00:00Z",
  "purgeAfter": "2026-11-01T00:00:00Z",
  "requestedBy": "string"
}

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/orgs/<org>/deletion" \
  -H "Authorization: Bearer $TARA_TOKEN"
POST/v1/orgs/{org}/deletion

Ask to delete the organization (owner, from a Portal or CLI session)

Send {"confirm": "<organization slug>"}. The organization becomes pending_deletion and is purged after the grace period (TARA_ORG_DELETION_GRACE, default 720h). The Paddle subscription is cancelled at the end of the paid period. While pending, every organization API answers 423 org_pending_deletion except GET and DELETE of this path and the data export (owner). Device and SCIM tokens stop working. The owner can restore the organization with DELETE until the real deletion. Recorded as org.deletion.request.

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Body (application/json) ​

FieldTypeRequiredDescription
confirmstringyesThe organization slug

Responses ​

CodeDescriptionType
202The organization is pending deletionapplication/json · object
400The confirmation does not match the slugapplication/problem+json · object
401Not signed inapplication/problem+json · object
403Not an ownerapplication/problem+json · object
404Not foundapplication/problem+json · object
409The organization is already pending deletionapplication/problem+json · object

Example response ​

json
{
  "state": "none",
  "requestedAt": "2026-11-01T00:00:00Z",
  "purgeAfter": "2026-11-01T00:00:00Z",
  "requestedBy": "string"
}

Call with curl ​

bash
curl -X POST "https://tara.phillipcli.cloud/v1/orgs/<org>/deletion" \
  -H "Authorization: Bearer $TARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"confirm":"string"}'
DELETE/v1/orgs/{org}/deletion

Restore the organization during the grace period (owner, from a Portal or CLI session)

Clears the pending deletion and undoes the scheduled Paddle cancellation. Recorded as org.deletion.cancel.

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Responses ​

CodeDescriptionType
200The organization is active again (state none)application/json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object
409The organization is not pending deletionapplication/problem+json · object

Example response ​

json
{
  "state": "none",
  "requestedAt": "2026-11-01T00:00:00Z",
  "purgeAfter": "2026-11-01T00:00:00Z",
  "requestedBy": "string"
}

Call with curl ​

bash
curl -X DELETE "https://tara.phillipcli.cloud/v1/orgs/<org>/deletion" \
  -H "Authorization: Bearer $TARA_TOKEN"