REST API reference

The non-admin P4A REST API surface — endpoints, scopes, request and response shapes, reachable with a personal access token.

Overview

This is the interactive reference for the P4A REST API — every endpoint an external client or script can call with a personal access token. Each operation below lists its method, path, required scope, request body, and response shape, with an interactive playground for trying calls.

The same endpoints power the dashboard and the hosted MCP server, so the MCP catalog tools are thin wrappers over the policy endpoints documented here.

Policy Ideas are not part of the token-scoped REST surface — read and act on them through the MCP idea tools (list_ideas, get_idea, submit_idea, vote_idea) instead. Idea delivery still shows up here from the policy side: GET /api/policies/{id} returns delivers_ideas (the ideas a policy delivers, with coverage), and POST /api/submissions accepts deliversIdeaIds to declare delivery when submitting.

Authentication

Send your token as a Bearer credential on every request:

curl https://www.p4a.dev/api/policies \
  -H "Authorization: Bearer p4a_xxxxxxxxxxxxxxxxxxxxxxxx"

A token acts as you: requests are attributed to your account and scoped to what you can already access. See Personal access tokens to create and manage tokens.

Scopes

Each endpoint requires one scope, chosen by HTTP method:

api:read — GET requests.
api:write — POST, PATCH, PUT, DELETE requests.

A request whose token lacks the required scope is rejected with 403; a missing, invalid, expired, or revoked token is rejected with 401.

Download the spec

The full OpenAPI 3.1 spec is available for import into Postman, Insomnia, or a code generator:

Policies

GET/api/policies

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Query Parameters

category?string

Filter by policy category.

q?string

Free-text search over name and description (name and summary for source=mulesoft).

source?string

Which catalog to list. community (default) = user-submitted P4A policies. mulesoft = MuleSoft out-of-the-box Omni/Flex Gateway policies (read-only, MuleSoftPolicySummary items).

Default"community"

Value in

"community"
"mulesoft"

direction?string

Filter by enforcement leg — inbound (incoming request, most policies) or outbound (upstream/response leg). Applies to both community and mulesoft sources.

Value in

"inbound"
"outbound"

assetKind?string

source=community only. Filter by asset type — policies that target the specified kind (agent, api, llm, or mcp). Ignored for the MuleSoft catalog.

Value in

"agent"
"api"
"llm"
"mcp"

sort?string

Sort key. alpha (default) orders by policy name; submitted orders by submission date (community catalog only). For source=mulesoft only alpha applies — the batch-synced MuleSoft catalog has no meaningful submission date, so submitted falls back to alpha. Unrecognized values fall back to alpha.

Default"alpha"

Value in

"alpha"
"submitted"

order?string

Sort direction. Defaults to asc for sort=alpha and desc for sort=submitted. Unrecognized values fall back to the per-key default.

Value in

"asc"
"desc"

Response Body

`application/json`

curl -X GET "https://example.com/api/policies"

{  "policies": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "slug": "string",      "name": "string",      "description": "string",      "category": "string",      "status": "string",      "liked": true,      "github_has_issues": true,      "delivers_ideas": [        {          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",          "title": "string",          "phase": "declared",          "coverage": "full",          "scope_note": "string"        }      ],      "docs_summary": {        "tabCount": 0,        "completeness": {          "filled": 0,          "total": 0,          "ratio": 0        }      },      "asset_kinds": [        "agent"      ],      "a2a_protocol_versions": [        "v0.3.0"      ],      "direction": "inbound"    }  ]}

GET/api/policies/{id}

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Response Body

`application/json`

curl -X GET "https://example.com/api/policies/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "policy": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "slug": "string",    "name": "string",    "description": "string",    "category": "string",    "status": "string",    "liked": true,    "github_has_issues": true,    "delivers_ideas": [      {        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "title": "string",        "phase": "declared",        "coverage": "full",        "scope_note": "string"      }    ],    "docs_summary": {      "tabCount": 0,      "completeness": {        "filled": 0,        "total": 0,        "ratio": 0      }    },    "asset_kinds": [      "agent"    ],    "a2a_protocol_versions": [      "v0.3.0"    ],    "direction": "inbound"  }}

PATCH/api/policies/{id}

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name?string

description?string

category?string

videoTutorialUrl?string

examplesUrl?string

githubUrl?string

GitHub, GitLab, or Bitbucket repo URL of the policy definition.

Formaturi

implementationGithubUrl?string

Split-model only: GitHub, GitLab, or Bitbucket repo URL of the implementation root.

iconUrl?string

iconDisabled?boolean

Response Body

`application/json`

curl -X PATCH "https://example.com/api/policies/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{}'

{  "policy": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "slug": "string",    "name": "string",    "description": "string",    "category": "string",    "status": "string",    "liked": true,    "github_has_issues": true,    "delivers_ideas": [      {        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "title": "string",        "phase": "declared",        "coverage": "full",        "scope_note": "string"      }    ],    "docs_summary": {      "tabCount": 0,      "completeness": {        "filled": 0,        "total": 0,        "ratio": 0      }    },    "asset_kinds": [      "agent"    ],    "a2a_protocol_versions": [      "v0.3.0"    ],    "direction": "inbound"  }}

GET/api/policies/{id}/branches

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Response Body

`application/json`

curl -X GET "https://example.com/api/policies/497f6eca-6276-4993-bfeb-53cbbbba6f08/branches"

{}

POST/api/policies/{id}/download

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Response Body

`application/json`

curl -X POST "https://example.com/api/policies/497f6eca-6276-4993-bfeb-53cbbbba6f08/download"

{  "ok": true}

GET/api/policies/{id}/history

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Query Parameters

limit?integer

before?string

Response Body

`application/json`

curl -X GET "https://example.com/api/policies/497f6eca-6276-4993-bfeb-53cbbbba6f08/history"

{  "entries": [    {}  ],  "nextCursor": "string"}

GET/api/policies/{id}/issues-enabled

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Response Body

`application/json`

curl -X GET "https://example.com/api/policies/497f6eca-6276-4993-bfeb-53cbbbba6f08/issues-enabled"

{  "enabled": true}

GET/api/policies/{id}/like

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Response Body

`application/json`

curl -X GET "https://example.com/api/policies/497f6eca-6276-4993-bfeb-53cbbbba6f08/like"

{  "liked": true}

POST/api/policies/{id}/like

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Response Body

`application/json`

curl -X POST "https://example.com/api/policies/497f6eca-6276-4993-bfeb-53cbbbba6f08/like"

{  "liked": true}

GET/api/policies/{id}/orgs

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Query Parameters

connectionId*string

Formatuuid

Response Body

`application/json`

curl -X GET "https://example.com/api/policies/497f6eca-6276-4993-bfeb-53cbbbba6f08/orgs?connectionId=497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "orgs": [    {      "id": "string",      "name": "string",      "isPrimary": true,      "fullPath": "string"    }  ]}

GET/api/policies/{id}/reviewers/me

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Response Body

`application/json`

curl -X GET "https://example.com/api/policies/497f6eca-6276-4993-bfeb-53cbbbba6f08/reviewers/me"

{  "isReviewer": true}

GET/api/policies/{id}/revisions

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Response Body

`application/json`

curl -X GET "https://example.com/api/policies/497f6eca-6276-4993-bfeb-53cbbbba6f08/revisions"

{  "revisions": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "policy_id": "ee9b03e0-6495-427a-85a5-34444d24ae04",      "field": "description",      "proposed_value": "string",      "previous_value": "string",      "status": "pending",      "feedback": "string",      "submitted_at": "2019-08-24T14:15:22Z",      "reviewed_at": "2019-08-24T14:15:22Z"    }  ]}

POST/api/policies/{id}/revisions

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

field*"description"

Value in

"description"

value*string

New Markdown About text.

Length10 <= length <= 20000

Response Body

`application/json`

curl -X POST "https://example.com/api/policies/497f6eca-6276-4993-bfeb-53cbbbba6f08/revisions" \  -H "Content-Type: application/json" \  -d '{    "field": "description",    "value": "stringstri"  }'

{  "revision": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "policy_id": "ee9b03e0-6495-427a-85a5-34444d24ae04",    "field": "description",    "proposed_value": "string",    "previous_value": "string",    "status": "pending",    "feedback": "string",    "submitted_at": "2019-08-24T14:15:22Z",    "reviewed_at": "2019-08-24T14:15:22Z"  },  "policy_name": "string"}

Submissions

GET/api/submissions

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Response Body

`application/json`

curl -X GET "https://example.com/api/submissions"

{  "submissions": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "name": "string",      "description": "string",      "status": "string",      "githubUrl": "http://example.com"    }  ]}

POST/api/submissions

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

projectType?string

Value in

"unified"
"split"

name*string

Length2 <= length <= 120

description*string

Length10 <= length <= 20000

githubUrl*string

GitHub, GitLab, or Bitbucket repo URL, e.g. https://github.com/owner/repo, https://gitlab.com/owner/repo, or https://bitbucket.org/workspace/repo.

Formaturi

implementationGithubUrl?string

Required when projectType is split. Same GitHub/GitLab/Bitbucket URL shapes.

Formaturi

category?string

videoTutorialUrl?string

examplesUrl?string

iconUrl?string

iconDisabled?boolean

deliversIdeaId?string

Legacy single-idea form (still accepted). Prefer deliversIdeaIds. The id of an approved Policy Idea this submission delivers.

Formatuuid

deliversIdeaIds?array<>

Optional. Approved Policy Ideas this submission declares it delivers, each with a coverage. Every referenced idea must be approved and visible to you, or the request is rejected (422). This records the declared intent while the policy is under review; each idea flips to delivered (and its submitter is notified) only once a policy that fully delivers it — or that an admin marks as completing it — is approved and published. An idea may be delivered by more than one policy, and a policy may deliver more than one idea.

Itemsitems <= 50

assetKinds?array<>

Optional. Asset types this policy targets. Defaults to values inferred from the repository's gcl.yaml metadata or name/description keywords.

a2aProtocolVersions?array<>

Optional. A2A protocol versions this policy supports, only meaningful when 'agent' is present in assetKinds.

docTabs?array<>

Optional. Rich, tabbed documentation staged with the submission and shown on the published policy page. Tabs with the reserved keys overview, configuration, examples, and faq are treated as predefined; any other key is a custom tab. Do not send an overview tab — the overview is seeded from description on review, and an empty overview here would clobber it. Tabs with an empty body are ignored.

Itemsitems <= 50

Response Body

`application/json`

curl -X POST "https://example.com/api/submissions" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "description": "stringstri",    "githubUrl": "http://example.com"  }'

{  "submission": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "name": "string",    "description": "string",    "status": "string",    "githubUrl": "http://example.com"  },  "validation": {}}

GET/api/submissions/{id}

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Response Body

`application/json`

curl -X GET "https://example.com/api/submissions/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "submission": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "name": "string",    "description": "string",    "status": "string",    "githubUrl": "http://example.com"  },  "docTabs": [    {      "key": "string",      "title": "string",      "kind": "predefined",      "bodyMd": "string",      "sortOrder": 0    }  ]}

PATCH/api/submissions/{id}

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

`application/json`

curl -X PATCH "https://example.com/api/submissions/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{}'

{  "submission": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "name": "string",    "description": "string",    "status": "string",    "githubUrl": "http://example.com"  }}

GET/api/submissions/{id}/history

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Response Body

`application/json`

curl -X GET "https://example.com/api/submissions/497f6eca-6276-4993-bfeb-53cbbbba6f08/history"

{  "entries": [    {}  ]}

POST/api/submissions/validate

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

projectType?string

Value in

"unified"
"split"

githubUrl?string

GitHub, GitLab, or Bitbucket repo URL, e.g. https://github.com/owner/repo, https://gitlab.com/owner/repo, or https://bitbucket.org/workspace/repo.

Formaturi

implementationGithubUrl?string

Required when projectType is split. Same GitHub/GitLab/Bitbucket URL shapes.

Formaturi

Response Body

`application/json`

curl -X POST "https://example.com/api/submissions/validate" \  -H "Content-Type: application/json" \  -d '{}'

{  "validation": {}}

Deployments

GET/api/deployments

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Response Body

`application/json`

curl -X GET "https://example.com/api/deployments"

{  "deployments": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "policy_id": "ee9b03e0-6495-427a-85a5-34444d24ae04",      "connection_id": "d3547de1-d1f2-4344-b4c2-17169b7526f9",      "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",      "status": "string",      "anypoint_org_id": "string",      "definition_asset_version": "string",      "implementation_asset_version": "string",      "home_doc_status": "published"    }  ],  "pagination": {}}

POST/api/deployments

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

policyId*string

Formatuuid

connectionId*string

Formatuuid

workspaceId*string

Formatuuid

targetOrganizationIds*array<string>

Items1 <= items <= 50

doPublish?boolean

doRelease?boolean

cleanupDev?boolean

ref?string

implementationRef?string

Response Body

`application/json`

curl -X POST "https://example.com/api/deployments" \  -H "Content-Type: application/json" \  -d '{    "policyId": "2f5573e6-5ba4-48f2-a75d-df99c936463b",    "connectionId": "84b500d7-71c8-4b1f-adf4-f1eb0000973d",    "workspaceId": "ef0efa32-d1c1-43d4-a5e2-fe7b4f00403c",    "targetOrganizationIds": [      "string"    ]  }'

{  "results": [    {      "ok": true,      "organizationId": "string",      "organizationName": "string",      "error": "string",      "deployment": {        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "status": "string",        "deduped": true      }    }  ]}

POST/api/deployments/delete-failed

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

policyId?string

Only delete failed deployments of this policy. Omit to clear all of yours.

Formatuuid

Response Body

`application/json`

curl -X POST "https://example.com/api/deployments/delete-failed" \  -H "Content-Type: application/json" \  -d '{}'

{  "deletedCount": 0,  "deletedDeploymentIds": [    "string"  ]}

DELETE/api/deployments/{id}

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Response Body

`application/json`

curl -X DELETE "https://example.com/api/deployments/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "deletedDeploymentId": "string"}

POST/api/deployments/{id}/cancel

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Response Body

`application/json`

curl -X POST "https://example.com/api/deployments/497f6eca-6276-4993-bfeb-53cbbbba6f08/cancel"

{  "ok": true}

POST/api/deployments/{id}/delete-release

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Response Body

`application/json`

curl -X POST "https://example.com/api/deployments/497f6eca-6276-4993-bfeb-53cbbbba6f08/delete-release"

{  "job": {}}

GET/api/deployments/{id}/dev-version

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Response Body

`application/json`

curl -X GET "https://example.com/api/deployments/497f6eca-6276-4993-bfeb-53cbbbba6f08/dev-version"

{  "dev_version_exists": true}

GET/api/deployments/{id}/history

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Response Body

`application/json`

curl -X GET "https://example.com/api/deployments/497f6eca-6276-4993-bfeb-53cbbbba6f08/history"

{  "jobs": [    {}  ],  "job": {},  "logs": [    {}  ]}

GET/api/deployments/{id}/logs

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Response Body

`text/event-stream`

curl -X GET "https://example.com/api/deployments/497f6eca-6276-4993-bfeb-53cbbbba6f08/logs"

"string"

POST/api/deployments/{id}/sync

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Response Body

`application/json`

curl -X POST "https://example.com/api/deployments/497f6eca-6276-4993-bfeb-53cbbbba6f08/sync"

{  "ok": true,  "result": "in_sync",  "status": "string"}

POST/api/deployments/{id}/unpublish

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Response Body

`application/json`

curl -X POST "https://example.com/api/deployments/497f6eca-6276-4993-bfeb-53cbbbba6f08/unpublish"

{  "job": {}}

Connections

GET/api/connections

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Response Body

`application/json`

curl -X GET "https://example.com/api/connections"

{  "connections": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "name": "string",      "host": "us",      "client_id": "string",      "organization_id": "string"    }  ]}

POST/api/connections

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

host*string

Value in

"us"
"eu"
"custom"

customDomain?|

Formaturi

clientId*string

Length4 <= length

clientSecret*string

Length4 <= length

organizationId*string

Length4 <= length

name*string

Length2 <= length <= 80

Response Body

`application/json`

curl -X POST "https://example.com/api/connections" \  -H "Content-Type: application/json" \  -d '{    "host": "us",    "clientId": "string",    "clientSecret": "string",    "organizationId": "string",    "name": "string"  }'

{  "connection": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "name": "string",    "host": "us",    "client_id": "string",    "organization_id": "string"  },  "validation": {}}

GET/api/connections/{id}

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Response Body

`application/json`

curl -X GET "https://example.com/api/connections/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "connection": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "name": "string",    "host": "us",    "client_id": "string",    "organization_id": "string"  },  "is_owner": true}

PATCH/api/connections/{id}

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Credential fields (clientId, clientSecret, organizationId) are all-or-none.

name?string

host?string

Value in

"us"
"eu"
"custom"

customDomain?|

Formaturi

clientId?string

Length4 <= length

clientSecret?string

Length4 <= length

organizationId?string

Length4 <= length

Response Body

`application/json`

curl -X PATCH "https://example.com/api/connections/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{}'

{  "connection": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "name": "string",    "host": "us",    "client_id": "string",    "organization_id": "string"  }}

DELETE/api/connections/{id}

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Response Body

`application/json`

curl -X DELETE "https://example.com/api/connections/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "ok": true}

POST/api/connections/{id}/sync

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Response Body

`application/json`

curl -X POST "https://example.com/api/connections/497f6eca-6276-4993-bfeb-53cbbbba6f08/sync"

{  "connection": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "name": "string",    "host": "us",    "client_id": "string",    "organization_id": "string"  },  "validation": {},  "reconciliation": {    "in_sync": 0,    "unknown": 0,    "gone": [      {        "deployment_id": "6ef0ac85-9892-4664-a2a5-58bf2af5a8a6",        "policy_name": "string",        "version": "string",        "status": "published",        "mode": "publish"      }    ]  }}

GET/api/connections/{id}/orgs

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Response Body

`application/json`

curl -X GET "https://example.com/api/connections/497f6eca-6276-4993-bfeb-53cbbbba6f08/orgs"

{  "orgs": [    {      "id": "string",      "name": "string",      "isPrimary": true,      "fullPath": "string"    }  ]}

GET/api/connections/{id}/workspaces

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Response Body

`application/json`

curl -X GET "https://example.com/api/connections/497f6eca-6276-4993-bfeb-53cbbbba6f08/workspaces"

{  "shared": [    {}  ]}

GET/api/connections/{id}/impact

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Response Body

`application/json`

curl -X GET "https://example.com/api/connections/497f6eca-6276-4993-bfeb-53cbbbba6f08/impact"

{  "active_deployments": 0,  "historical_deployments": 0,  "workspace_links": 0,  "has_credential": true}

POST/api/connections/validate

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

host*string

Value in

"us"
"eu"
"custom"

customDomain?|

Formaturi

clientId*string

Length4 <= length

clientSecret*string

Length4 <= length

organizationId*string

Length4 <= length

Response Body

`application/json`

curl -X POST "https://example.com/api/connections/validate" \  -H "Content-Type: application/json" \  -d '{    "host": "us",    "clientId": "string",    "clientSecret": "string",    "organizationId": "string"  }'

{  "ok": true,  "error": "string"}

Workspaces

GET/api/workspaces

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Response Body

`application/json`

curl -X GET "https://example.com/api/workspaces"

{  "memberships": [    {}  ]}

POST/api/workspaces

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

Length2 <= length <= 80

slug?string

Length2 <= length <= 48

Response Body

`application/json`

curl -X POST "https://example.com/api/workspaces" \  -H "Content-Type: application/json" \  -d '{    "name": "string"  }'

{  "workspace": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "name": "string",    "slug": "string"  }}

GET/api/workspaces/{id}

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Response Body

`application/json`

curl -X GET "https://example.com/api/workspaces/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{}

PATCH/api/workspaces/{id}

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

Length2 <= length <= 80

Response Body

`application/json`

curl -X PATCH "https://example.com/api/workspaces/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{    "name": "string"  }'

{  "workspace": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "name": "string",    "slug": "string"  }}

POST/api/workspaces/{id}/archive

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Response Body

`application/json`

curl -X POST "https://example.com/api/workspaces/497f6eca-6276-4993-bfeb-53cbbbba6f08/archive"

{  "archived_at": "string"}

DELETE/api/workspaces/{id}/archive

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Response Body

`application/json`

curl -X DELETE "https://example.com/api/workspaces/497f6eca-6276-4993-bfeb-53cbbbba6f08/archive"

{  "archived_at": "string"}

GET/api/workspaces/{id}/members

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Response Body

`application/json`

curl -X GET "https://example.com/api/workspaces/497f6eca-6276-4993-bfeb-53cbbbba6f08/members"

{  "members": [    {}  ]}

POST/api/workspaces/{id}/members

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

email*string

Formatemail

role?string

Value in

"admin"
"member"

Response Body

`application/json`

curl -X POST "https://example.com/api/workspaces/497f6eca-6276-4993-bfeb-53cbbbba6f08/members" \  -H "Content-Type: application/json" \  -d '{    "email": "user@example.com"  }'

{  "ok": true}

PATCH/api/workspaces/{id}/members/{userId}

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

userId*string

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

role?string

Value in

"admin"
"member"

disabled?false

Value in

false

Response Body

`application/json`

curl -X PATCH "https://example.com/api/workspaces/497f6eca-6276-4993-bfeb-53cbbbba6f08/members/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{}'

{  "ok": true}

DELETE/api/workspaces/{id}/members/{userId}

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

userId*string

Formatuuid

Response Body

`application/json`

curl -X DELETE "https://example.com/api/workspaces/497f6eca-6276-4993-bfeb-53cbbbba6f08/members/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "ok": true}

GET/api/workspaces/{id}/members/{userId}/impact

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

userId*string

Formatuuid

Response Body

`application/json`

curl -X GET "https://example.com/api/workspaces/497f6eca-6276-4993-bfeb-53cbbbba6f08/members/497f6eca-6276-4993-bfeb-53cbbbba6f08/impact"

{  "role": "owner",  "disabled_at": "string",  "owned_shared_connections": 0,  "deployments_authored": 0}

POST/api/workspaces/{id}/connections

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

connection_id*string

Formatuuid

Response Body

`application/json`

curl -X POST "https://example.com/api/workspaces/497f6eca-6276-4993-bfeb-53cbbbba6f08/connections" \  -H "Content-Type: application/json" \  -d '{    "connection_id": "d3547de1-d1f2-4344-b4c2-17169b7526f9"  }'

{  "ok": true}

PATCH/api/workspaces/{id}/connections

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

connection_id*string

Formatuuid

disabled?false

Value in

false

Response Body

`application/json`

curl -X PATCH "https://example.com/api/workspaces/497f6eca-6276-4993-bfeb-53cbbbba6f08/connections" \  -H "Content-Type: application/json" \  -d '{    "connection_id": "d3547de1-d1f2-4344-b4c2-17169b7526f9"  }'

{  "ok": true}

DELETE/api/workspaces/{id}/connections

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Query Parameters

connection_id*string

Formatuuid

Response Body

`application/json`

curl -X DELETE "https://example.com/api/workspaces/497f6eca-6276-4993-bfeb-53cbbbba6f08/connections?connection_id=497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "ok": true}

GET/api/workspaces/{id}/connections/{connectionId}/impact

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

connectionId*string

Formatuuid

Response Body

`application/json`

curl -X GET "https://example.com/api/workspaces/497f6eca-6276-4993-bfeb-53cbbbba6f08/connections/497f6eca-6276-4993-bfeb-53cbbbba6f08/impact"

{  "is_disabled": true,  "disabled_reason": "string",  "members_visible": 0,  "deployments_authored": 0}

Transfers

POST/api/policies/{id}/transfers

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

recipientEmail*string

Formatemail

Response Body

`application/json`

curl -X POST "https://example.com/api/policies/497f6eca-6276-4993-bfeb-53cbbbba6f08/transfers" \  -H "Content-Type: application/json" \  -d '{    "recipientEmail": "user@example.com"  }'

{  "transfer": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "to_user_id": "bdcaa974-8e23-4fc9-823d-e060850bbef1"  }}

POST/api/transfers/{id}/accept

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Response Body

`application/json`

curl -X POST "https://example.com/api/transfers/497f6eca-6276-4993-bfeb-53cbbbba6f08/accept"

{  "transfer": {},  "policyId": "string"}

POST/api/transfers/{id}/cancel

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Response Body

`application/json`

curl -X POST "https://example.com/api/transfers/497f6eca-6276-4993-bfeb-53cbbbba6f08/cancel"

{  "transfer": {}}

POST/api/transfers/{id}/reject

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

feedback?string

Lengthlength <= 4000

Response Body

`application/json`

curl -X POST "https://example.com/api/transfers/497f6eca-6276-4993-bfeb-53cbbbba6f08/reject" \  -H "Content-Type: application/json" \  -d '{}'

{  "transfer": {}}

Tokens

GET/api/tokens

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Response Body

`application/json`

curl -X GET "https://example.com/api/tokens"

{  "tokens": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "name": "string",      "token_prefix": "string",      "scopes": [        "api:read"      ],      "expires_at": "2019-08-24T14:15:22Z",      "last_used_at": "2019-08-24T14:15:22Z",      "revoked_at": "2019-08-24T14:15:22Z",      "created_at": "2019-08-24T14:15:22Z"    }  ]}

POST/api/tokens

Authorization

cookieAuth

sb-access-token<token>

A signed-in browser session cookie. Used only by POST /api/tokens, which mints new tokens and therefore rejects personal access tokens — a token cannot mint another token. This operation cannot be exercised from the interactive playground; create tokens from the dashboard Settings page.

In: cookie

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

Length1 <= length <= 100

scopes*array<>

Items1 <= items

expiresInDays?|

Value in

30
90
365
null

Response Body

`application/json`

curl -X POST "https://example.com/api/tokens" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "scopes": [      "api:read"    ]  }'

{  "token": "string",  "record": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "name": "string",    "token_prefix": "string",    "scopes": [      "api:read"    ],    "expires_at": "2019-08-24T14:15:22Z",    "last_used_at": "2019-08-24T14:15:22Z",    "revoked_at": "2019-08-24T14:15:22Z",    "created_at": "2019-08-24T14:15:22Z"  }}

DELETE/api/tokens/{id}

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Path Parameters

id*string

The resource's UUID.

Formatuuid

Response Body

`application/json`

curl -X DELETE "https://example.com/api/tokens/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "ok": true,  "record": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "name": "string",    "token_prefix": "string",    "scopes": [      "api:read"    ],    "expires_at": "2019-08-24T14:15:22Z",    "last_used_at": "2019-08-24T14:15:22Z",    "revoked_at": "2019-08-24T14:15:22Z",    "created_at": "2019-08-24T14:15:22Z"  }}

Account

GET/api/me

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Response Body

`application/json`

curl -X GET "https://example.com/api/me"

{  "user": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "email": "user@example.com",    "company": "string",    "username": "string",    "bio": "string",    "linkedinUrl": "string",    "xUrl": "string",    "profileIsPublic": true,    "is_admin": true  }}

PATCH/api/me

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

company?string

Length1 <= length <= 120

username?string

Your unique @-mention handle: 3–30 chars, lowercased, [a-z0-9] with internal _/- (no leading/trailing separator). Must be unique across all users.

Match^[a-z0-9][a-z0-9_-]{1,28}[a-z0-9]$

Length3 <= length <= 30

bio?|

Optional short public bio (1–1000 chars). Send null (or an empty string) to clear it. Only visible to others when profileIsPublic is true.

Lengthlength <= 1000

linkedinUrl?|

Optional LinkedIn profile URL. Must be an https:// link to linkedin.com (any country subdomain). Send null to clear. Only visible to others when profileIsPublic is true.

xUrl?|

Optional X / Twitter profile URL. Must be an https:// link to x.com or twitter.com. Send null to clear. Only visible to others when profileIsPublic is true.

profileIsPublic?boolean

Opt-in gate: when true, your bio and social links are exposed on your public profile (GET /api/users/{username}). Default false (private). Your name, company, and username are always public regardless.

Response Body

`application/json`

curl -X PATCH "https://example.com/api/me" \  -H "Content-Type: application/json" \  -d '{}'

{  "user": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "email": "user@example.com",    "company": "string",    "username": "string",    "bio": "string",    "linkedinUrl": "string",    "xUrl": "string",    "profileIsPublic": true,    "is_admin": true  }}

GET/api/me/transfers

Authorization

bearerAuth

AuthorizationBearer <token>

A personal access token, sent as Authorization: Bearer p4a_….

In: header

Query Parameters

role?string

Value in

"recipient"
"initiator"

Response Body

`application/json`

curl -X GET "https://example.com/api/me/transfers"

{  "transfers": [    {}  ]}

200application/json

200application/json

404application/json

200application/json

400application/json

403application/json

200application/json

200application/json

200application/json

200application/json

404application/json

200application/json

200application/json

200application/json

200application/json

200application/json

201application/json

403application/json

404application/json

409application/json

422application/json

200application/json

201application/json

400application/json

200application/json

404application/json

200application/json

400application/json

200application/json

200application/json

200application/json

201application/json

207application/json

400application/json

503application/json

200application/json

400application/json

200application/json

403application/json

404application/json

409application/json

200application/json

201application/json

200application/json

404application/json

200application/json

200text/event-stream

200application/json

201application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`text/event-stream`

`application/json`

`application/json`