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.

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).

direction?string

source=mulesoft only. Filter by enforcement leg — inbound (incoming request, most policies) or outbound (upstream/response leg, e.g. tls-outbound). Ignored for the community catalog.

Response Body

`application/json`

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

{
  "policies": [
    {
      "id": "3f1c2b4a-1e2d-4c3b-9a8f-0d1e2f3a4b5c",
      "name": "Rate limit",
      "description": "Throttle requests per agent.",
      "category": "Traffic management",
      "status": "approved",
      "liked": false,
      "github_has_issues": true
    }
  ]
}

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.

Response Body

`application/json`

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

{
  "policy": {
    "id": "3f1c2b4a-1e2d-4c3b-9a8f-0d1e2f3a4b5c",
    "name": "Rate limit",
    "description": "Throttle requests per agent.",
    "category": "Traffic management",
    "status": "approved",
    "liked": false,
    "github_has_issues": true
  }
}

{
  "error": "Not authenticated"
}

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.

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

implementationGithubUrl?string

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": "3f1c2b4a-1e2d-4c3b-9a8f-0d1e2f3a4b5c",
    "name": "Rate limit",
    "description": "Throttle requests per agent.",
    "category": "Traffic management",
    "status": "approved",
    "liked": false,
    "github_has_issues": true
  }
}

{
  "error": "Not authenticated"
}

{
  "error": "Not authenticated"
}

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.

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.

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.

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.

Response Body

`application/json`

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

{
  "enabled": true
}

{
  "error": "Not authenticated"
}

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.

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.

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.

Query Parameters

connectionId*string

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.

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.

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.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

field*string

value*string

New Markdown About text.

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"
}

{
  "error": "Not authenticated"
}

{
  "error": "Not authenticated"
}

{
  "error": "Not authenticated"
}

{
  "error": "Not authenticated"
}

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": "a1b2c3d4-5e6f-7081-92a3-b4c5d6e7f809",
      "name": "Rate limit",
      "description": "Throttle requests per agent based on a token bucket.",
      "status": "pending",
      "githubUrl": "https://github.com/acme/rate-limit-policy"
    }
  ]
}

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

name*string

description*string

githubUrl*string

implementationGithubUrl?string

Required when projectType is split.

category?string

videoTutorialUrl?string

examplesUrl?string

iconUrl?string

iconDisabled?boolean

deliversIdeaId?string

Optional. The id of an approved Policy Idea this submission delivers. Must reference an idea that is approved and visible to you, otherwise the request is rejected. This records the declared intent to deliver the idea while the policy is under review; the idea flips to delivered (and its original submitter is notified) only once the policy is approved and published.

Response Body

`application/json`

curl -X POST "https://example.com/api/submissions" \  -H "Content-Type: application/json" \  -d '{    "projectType": "unified",    "name": "Rate limit",    "description": "Throttle requests per agent based on a token bucket algorithm.",    "githubUrl": "https://github.com/acme/rate-limit-policy",    "category": "Traffic management"  }'

{
  "submission": {
    "id": "a1b2c3d4-5e6f-7081-92a3-b4c5d6e7f809",
    "name": "Rate limit",
    "description": "Throttle requests per agent based on a token bucket.",
    "status": "pending",
    "githubUrl": "https://github.com/acme/rate-limit-policy"
  },
  "validation": {}
}

{
  "error": "Not authenticated"
}

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.

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": "a1b2c3d4-5e6f-7081-92a3-b4c5d6e7f809",
    "name": "Rate limit",
    "description": "Throttle requests per agent based on a token bucket.",
    "status": "pending",
    "githubUrl": "https://github.com/acme/rate-limit-policy"
  }
}

{
  "error": "Not authenticated"
}

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.

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

githubUrl?string

implementationGithubUrl?string

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

connectionId*string

workspaceId*string

targetOrganizationIds*array<string>

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": "3f1c2b4a-1e2d-4c3b-9a8f-0d1e2f3a4b5c",    "connectionId": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",    "workspaceId": "9f8e7d6c-5b4a-3210-fedc-ba9876543210",    "targetOrganizationIds": [      "a0000000-0000-0000-0000-000000000001"    ],    "doPublish": true,    "doRelease": false  }'

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

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

{
  "error": "Not authenticated"
}

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.

Response Body

`application/json`

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

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

{
  "error": "Not authenticated"
}

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.

Response Body

`application/json`

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

{
  "deletedDeploymentId": "string"
}

{
  "error": "Not authenticated"
}

{
  "error": "Not authenticated"
}

{
  "error": "Not authenticated"
}

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.

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.

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.

Response Body

`application/json`

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

{
  "dev_version_exists": true
}

{
  "error": "Not authenticated"
}

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.

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.

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.

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.

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": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
      "name": "Acme production",
      "host": "us",
      "client_id": "abcd…",
      "organization_id": "a0000000-0000-0000-0000-000000000001"
    }
  ]
}

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

customDomain?|

clientId*string

clientSecret*string

organizationId*string

name*string

Response Body

`application/json`

curl -X POST "https://example.com/api/connections" \  -H "Content-Type: application/json" \  -d '{    "name": "Acme production",    "host": "us",    "clientId": "1234abcd",    "clientSecret": "s3cr3t-value",    "organizationId": "a0000000-0000-0000-0000-000000000001"  }'

{
  "connection": {
    "id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
    "name": "Acme production",
    "host": "us",
    "client_id": "abcd…",
    "organization_id": "a0000000-0000-0000-0000-000000000001"
  },
  "validation": {}
}

{
  "error": "Not authenticated"
}

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.

Response Body

`application/json`

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

{
  "connection": {
    "id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
    "name": "Acme production",
    "host": "us",
    "client_id": "abcd…",
    "organization_id": "a0000000-0000-0000-0000-000000000001"
  },
  "is_owner": true
}

{
  "error": "Not authenticated"
}

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.

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

customDomain?|

clientId?string

clientSecret?string

organizationId?string

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": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
    "name": "Acme production",
    "host": "us",
    "client_id": "abcd…",
    "organization_id": "a0000000-0000-0000-0000-000000000001"
  }
}

{
  "error": "Not authenticated"
}

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.

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.

Response Body

`application/json`

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

{
  "connection": {
    "id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
    "name": "Acme production",
    "host": "us",
    "client_id": "abcd…",
    "organization_id": "a0000000-0000-0000-0000-000000000001"
  },
  "validation": {}
}

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.

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.

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.

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

customDomain?|

clientId*string

clientSecret*string

organizationId*string

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

slug?string

Response Body

`application/json`

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

{
  "workspace": {
    "id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210",
    "name": "Platform team",
    "slug": "platform-team"
  }
}

{
  "error": "Not authenticated"
}

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.

Response Body

`application/json`

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

{}

{
  "error": "Not authenticated"
}

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.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

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": "9f8e7d6c-5b4a-3210-fedc-ba9876543210",
    "name": "Platform team",
    "slug": "platform-team"
  }
}

{
  "error": "Not authenticated"
}

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.

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.

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.

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.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

email*string

role?string

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.

userId*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

role?string

disabled?boolean

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.

userId*string

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.

userId*string

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.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

connection_id*string

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.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

connection_id*string

disabled?boolean

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.

Query Parameters

connection_id*string

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.

connectionId*string

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.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

recipientEmail*string

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.

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.

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.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

feedback?string

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": "11112222-3333-4444-5555-666677778888",
      "name": "My laptop's CLI",
      "token_prefix": "p4a_abcd",
      "scopes": [
        "api:read"
      ],
      "expires_at": "2026-09-22T00:00:00.000Z",
      "last_used_at": null,
      "revoked_at": null,
      "created_at": "2026-06-24T12:00:00.000Z"
    }
  ]
}

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

scopes*array<>

expiresInDays?|

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": "11112222-3333-4444-5555-666677778888",
    "name": "My laptop's CLI",
    "token_prefix": "p4a_abcd",
    "scopes": [
      "api:read"
    ],
    "expires_at": "2026-09-22T00:00:00.000Z",
    "last_used_at": null,
    "revoked_at": null,
    "created_at": "2026-06-24T12:00:00.000Z"
  }
}

{
  "error": "Not authenticated"
}

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.

Response Body

`application/json`

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

{
  "ok": true,
  "record": {
    "id": "11112222-3333-4444-5555-666677778888",
    "name": "My laptop's CLI",
    "token_prefix": "p4a_abcd",
    "scopes": [
      "api:read"
    ],
    "expires_at": "2026-09-22T00:00:00.000Z",
    "last_used_at": null,
    "revoked_at": null,
    "created_at": "2026-06-24T12:00:00.000Z"
  }
}

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": "deadbeef-0000-1111-2222-333344445555",
    "email": "you@example.com",
    "company": "Acme",
    "is_admin": false
  }
}

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

Response Body

`application/json`

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

{
  "user": {
    "id": "deadbeef-0000-1111-2222-333344445555",
    "email": "you@example.com",
    "company": "Acme",
    "is_admin": false
  }
}

{
  "error": "Not authenticated"
}

GET/api/me/transfers

Authorization

bearerAuth

AuthorizationBearer <token>

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

In: header

Query Parameters

role?string

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

400application/json

200application/json

200application/json

200application/json

201application/json

207application/json

400application/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

200application/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`

`application/json`