P4A DocumentationREST 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.ai/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—GETrequests.api:write—POST,PATCH,PUT,DELETErequests.
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
/api/policiesbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
category?stringFilter by policy category.
q?stringFree-text search over name and description (name and summary for source=mulesoft).
source?stringWhich catalog to list. community (default) = user-submitted P4A
policies. mulesoft = MuleSoft out-of-the-box Omni/Flex Gateway
policies (read-only, MuleSoftPolicySummary items).
"community""community""mulesoft"direction?stringFilter by enforcement leg — inbound (incoming request, most policies)
or outbound (upstream/response leg). Applies to both community and
mulesoft sources.
"inbound""outbound"assetKind?stringsource=community only. Filter by asset type — policies that target
the specified kind (agent, api, llm, or mcp). Ignored for the MuleSoft
catalog.
"agent""api""llm""mcp"sort?stringSort 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.
"alpha""alpha""submitted"order?stringSort direction. Defaults to asc for sort=alpha and desc
for sort=submitted. Unrecognized values fall back to the
per-key default.
"asc""desc"The matching policies.
application/json- response
policies?array<|>Policy items for the community catalog;
MuleSoftPolicySummary items when source=mulesoft.
curl -X GET 'https://www.p4a.ai/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", "completes_idea": true } ], "contributors": [ { "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5", "username": "string", "name": "string" } ], "owner_avatar_url": "string", "owner_avatar_email_hash": "string", "docs_summary": { "tabCount": 0, "completeness": { "filled": 0, "total": 0, "ratio": 0 } }, "asset_kinds": [ "agent" ], "a2a_protocol_versions": [ "v0.3.0" ], "direction": "inbound", "source_ref": "string", "implementation_source_ref": "string" } ]}/api/policies/{id}bearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidThe policy.
application/json- response
policy?curl -X GET 'https://www.p4a.ai/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", "completes_idea": true } ], "contributors": [ { "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5", "username": "string", "name": "string" } ], "owner_avatar_url": "string", "owner_avatar_email_hash": "string", "docs_summary": { "tabCount": 0, "completeness": { "filled": 0, "total": 0, "ratio": 0 } }, "asset_kinds": [ "agent" ], "a2a_protocol_versions": [ "v0.3.0" ], "direction": "inbound", "source_ref": "string", "implementation_source_ref": "string" }}/api/policies/{id}bearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidapplication/json- body
name?stringdescription?stringcategory?stringvideoTutorialUrl?stringexamplesUrl?stringgithubUrl?stringGitHub, GitLab, or Bitbucket repo URL of the policy definition.
uriimplementationGithubUrl?stringSplit-model only: GitHub, GitLab, or Bitbucket repo URL of the implementation root.
sourceRef?stringDefault git branch/tag/commit used when this policy is deployed (#1033). Send an empty string to clear it back to the repository's default branch. Admin-only.
implementationSourceRef?stringSplit-model only: default git ref for the implementation root (#1033). Empty string clears it. Admin-only.
iconUrl?stringiconDisabled?booleanThe updated policy.
application/json- response
policy?curl -X PATCH 'https://www.p4a.ai/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", "completes_idea": true } ], "contributors": [ { "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5", "username": "string", "name": "string" } ], "owner_avatar_url": "string", "owner_avatar_email_hash": "string", "docs_summary": { "tabCount": 0, "completeness": { "filled": 0, "total": 0, "ratio": 0 } }, "asset_kinds": [ "agent" ], "a2a_protocol_versions": [ "v0.3.0" ], "direction": "inbound", "source_ref": "string", "implementation_source_ref": "string" }}/api/policies/{id}/branchesbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidBranch information for the policy's source repository.
application/json- response
curl -X GET 'https://www.p4a.ai/api/policies/497f6eca-6276-4993-bfeb-53cbbbba6f08/branches'{}/api/policies/{id}/downloadbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidSuccess.
application/json- response
ok?booleancurl -X POST 'https://www.p4a.ai/api/policies/497f6eca-6276-4993-bfeb-53cbbbba6f08/download'{ "ok": true}/api/policies/{id}/historybearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidlimit?integerbefore?stringHistory entries, newest first.
application/json- response
entries?array<>nextCursor?string|nullcurl -X GET 'https://www.p4a.ai/api/policies/497f6eca-6276-4993-bfeb-53cbbbba6f08/history'{ "entries": [ {} ], "nextCursor": "string"}/api/policies/{id}/issues-enabledbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidThe live issue-tracker state. enabled is null when the provider couldn't be read (private/gone repo, rate limit, network) — the caller should keep trusting the persisted github_has_issues.
application/json- response
enabled?booleancurl -X GET 'https://www.p4a.ai/api/policies/497f6eca-6276-4993-bfeb-53cbbbba6f08/issues-enabled'{ "enabled": true}/api/policies/{id}/likebearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidYour like state.
application/json- response
liked?booleancurl -X GET 'https://www.p4a.ai/api/policies/497f6eca-6276-4993-bfeb-53cbbbba6f08/like'{ "liked": true}/api/policies/{id}/likebearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidYour like state after toggling.
application/json- response
liked?booleancurl -X POST 'https://www.p4a.ai/api/policies/497f6eca-6276-4993-bfeb-53cbbbba6f08/like'{ "liked": true}/api/policies/{id}/orgsbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidconnectionId*stringuuidThe eligible organizations for the given connection.
application/json- response
orgs?array<>curl -X GET 'https://www.p4a.ai/api/policies/497f6eca-6276-4993-bfeb-53cbbbba6f08/orgs?connectionId=497f6eca-6276-4993-bfeb-53cbbbba6f08'{ "orgs": [ { "id": "string", "name": "string", "isPrimary": true, "fullPath": "string" } ]}/api/policies/{id}/reviewers/mebearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidYour reviewer state.
application/json- response
isReviewer?booleancurl -X GET 'https://www.p4a.ai/api/policies/497f6eca-6276-4993-bfeb-53cbbbba6f08/reviewers/me'{ "isReviewer": true}/api/policies/{id}/revisionsbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidYour revisions for this policy, newest first.
application/json- response
revisions?array<>curl -X GET 'https://www.p4a.ai/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" } ]}/api/policies/{id}/revisionsbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidapplication/json- body
field*"description""description"value*stringNew Markdown About text.
10 <= length <= 20000The created pending revision.
application/json- response
revision?An owner-proposed edit to a single published-policy field, pending an administrator's re-review before it goes live.
policy_name?stringcurl -X POST 'https://www.p4a.ai/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
/api/submissionsbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
Your submissions.
application/json- response
submissions?array<>curl -X GET 'https://www.p4a.ai/api/submissions'{ "submissions": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "description": "string", "status": "string", "githubUrl": "http://example.com", "feedback": "string" } ]}/api/submissionsbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
application/json- body
projectType?string"unified""split"name*string2 <= length <= 120description*string10 <= length <= 20000githubUrl*stringGitHub, GitLab, or Bitbucket repo URL, e.g. https://github.com/owner/repo, https://gitlab.com/owner/repo, or https://bitbucket.org/workspace/repo.
uriimplementationGithubUrl?stringRequired when projectType is split. Same GitHub/GitLab/Bitbucket URL shapes.
urisourceRef?stringOptional default git branch, tag, or commit (#1033), used as the default source ref when this policy is deployed. Omit to use the repository's default branch. Deployers can still choose another ref.
1 <= length <= 255implementationSourceRef?stringSplit-model only: optional default git ref for the implementation root (#1033). Omit to use the repository's default branch.
1 <= length <= 255category?stringvideoTutorialUrl?stringexamplesUrl?stringiconUrl?stringiconDisabled?booleandeliversIdeaId?stringLegacy single-idea form (still accepted). Prefer deliversIdeaIds. The id of an approved Policy Idea this submission delivers.
uuiddeliversIdeaIds?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.
items <= 50assetKinds?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.
items <= 50The created submission and repository validation result.
application/json- response
submission?validation?curl -X POST 'https://www.p4a.ai/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", "feedback": "string" }, "validation": {}}/api/submissions/{id}bearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidThe submission and its staged documentation tabs.
application/json- response
submission?docTabs?array<>curl -X GET 'https://www.p4a.ai/api/submissions/497f6eca-6276-4993-bfeb-53cbbbba6f08'{ "submission": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "description": "string", "status": "string", "githubUrl": "http://example.com", "feedback": "string" }, "docTabs": [ { "key": "string", "title": "string", "kind": "predefined", "bodyMd": "string", "sortOrder": 0 } ]}/api/submissions/{id}bearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidapplication/json- body
The updated submission.
application/json- response
submission?curl -X PATCH 'https://www.p4a.ai/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", "feedback": "string" }}/api/submissions/{id}/historybearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidReview history entries.
application/json- response
entries?array<>curl -X GET 'https://www.p4a.ai/api/submissions/497f6eca-6276-4993-bfeb-53cbbbba6f08/history'{ "entries": [ {} ]}/api/submissions/validatebearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
application/json- body
projectType?string"unified""split"githubUrl?stringGitHub, GitLab, or Bitbucket repo URL, e.g. https://github.com/owner/repo, https://gitlab.com/owner/repo, or https://bitbucket.org/workspace/repo.
uriimplementationGithubUrl?stringRequired when projectType is split. Same GitHub/GitLab/Bitbucket URL shapes.
uriThe validation result.
application/json- response
validation?curl -X POST 'https://www.p4a.ai/api/submissions/validate' \ -H 'Content-Type: application/json' \ -d '{}'{ "validation": {}}Rulesets
Community governance rulesets: browse the catalog, submit a ruleset repository for review, and track your submissions.
/api/rulesetsbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
source?stringWhich catalog to list. community (default) = user-submitted
rulesets (RulesetSummary items). mulesoft = MuleSoft
out-of-the-box rulesets (read-only, MulesoftRulesetSummary items).
"community""community""mulesoft"q?stringFree-text search over name and description (also for source=mulesoft).
length <= 200category?stringFilter by category: one of the RulesetCategory values, or All Categories for no filter. For source=mulesoft it matches one of the ruleset's Exchange categories exactly (most MuleSoft rulesets have none).
length <= 120scope?stringOnly rulesets that target this API type. agent-network is a deprecated alias for agent.
"rest-api""async-api""http-api""grpc-api""agent""mcp""agent-network"sort?stringSort key. alpha sorts by name; submitted by submission time; likes and views by engagement. Unrecognized values fall back to alpha. For source=mulesoft only alpha applies, because the batch-synced catalog has no submission date or engagement counters; the other keys fall back to alpha.
"alpha""alpha""submitted""likes""views"order?stringSort direction. Defaults to asc for alpha and desc for the others.
"asc""desc"limit?integer1 <= value <= 200100offset?integer0 <= value0One page of rulesets.
application/json- response
rulesets?array<|>RulesetSummary items for the community catalog;
MulesoftRulesetSummary items when source=mulesoft.
Tell them apart by source.
hasMore?booleancurl -X GET 'https://www.p4a.ai/api/rulesets'{ "rulesets": [ { "source": "community", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "description": "string", "category": "Security", "profile_name": "string", "rule_counts": { "violation": 0, "warning": 0, "info": 0 }, "target_scopes": [ "rest-api" ], "tags": [ "string" ], "icon_url": "http://example.com", "exchange_asset_id": "string", "lifecycle_status": "under_review", "published_at": "2019-08-24T14:15:22Z", "likes": 0, "views": 0, "deploys": 0, "comment_count": 0, "submitted_by": "6703ac2f-9eb5-40e9-9fde-511b2dbf4be5", "owner_name": "string", "owner_username": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ], "hasMore": true}/api/rulesets/{id}bearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidThe ruleset.
application/json- response
ruleset?curl -X GET 'https://www.p4a.ai/api/rulesets/497f6eca-6276-4993-bfeb-53cbbbba6f08'{ "ruleset": { "source": "community", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "description": "string", "category": "Security", "profile_name": "string", "rule_counts": { "violation": 0, "warning": 0, "info": 0 }, "target_scopes": [ "rest-api" ], "tags": [ "string" ], "icon_url": "http://example.com", "exchange_asset_id": "string", "lifecycle_status": "under_review", "published_at": "2019-08-24T14:15:22Z", "likes": 0, "views": 0, "deploys": 0, "comment_count": 0, "submitted_by": "6703ac2f-9eb5-40e9-9fde-511b2dbf4be5", "owner_name": "string", "owner_username": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "submission_id": "945dfedc-ad7f-4af7-b20c-06082ffa3cb3", "source_url": "http://example.com", "source_ref": "string", "ruleset_path": "string", "rule_names": [ "string" ], "video_tutorial_url": "http://example.com", "examples_url": "http://example.com", "review_feedback": "string", "reviewed_at": "2019-08-24T14:15:22Z", "contributors": [ { "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5", "username": "string", "name": "string" } ], "delivers_ideas": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "slug": "string", "title": "string", "phase": "declared", "coverage": "full", "scope_note": "string", "completes_idea": true } ] }}/api/rulesets/{id}bearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidapplication/json- body
As the owner you can set these two links. Send an empty string to clear one.
1 <= propertiesvideoTutorialUrl?stringexamplesUrl?stringThe updated ruleset.
application/json- response
ruleset?curl -X PATCH 'https://www.p4a.ai/api/rulesets/497f6eca-6276-4993-bfeb-53cbbbba6f08' \ -H 'Content-Type: application/json' \ -d '{}'{ "ruleset": { "source": "community", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "description": "string", "category": "Security", "profile_name": "string", "rule_counts": { "violation": 0, "warning": 0, "info": 0 }, "target_scopes": [ "rest-api" ], "tags": [ "string" ], "icon_url": "http://example.com", "exchange_asset_id": "string", "lifecycle_status": "under_review", "published_at": "2019-08-24T14:15:22Z", "likes": 0, "views": 0, "deploys": 0, "comment_count": 0, "submitted_by": "6703ac2f-9eb5-40e9-9fde-511b2dbf4be5", "owner_name": "string", "owner_username": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "submission_id": "945dfedc-ad7f-4af7-b20c-06082ffa3cb3", "source_url": "http://example.com", "source_ref": "string", "ruleset_path": "string", "rule_names": [ "string" ], "video_tutorial_url": "http://example.com", "examples_url": "http://example.com", "review_feedback": "string", "reviewed_at": "2019-08-24T14:15:22Z", "contributors": [ { "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5", "username": "string", "name": "string" } ], "delivers_ideas": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "slug": "string", "title": "string", "phase": "declared", "coverage": "full", "scope_note": "string", "completes_idea": true } ] }}/api/rulesets/{id}/reviewers/mebearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidYour reviewer state.
application/json- response
isReviewer*booleanrole*|"viewer""commenter""editor"nullcurl -X GET 'https://www.p4a.ai/api/rulesets/497f6eca-6276-4993-bfeb-53cbbbba6f08/reviewers/me'{ "isReviewer": true, "role": "viewer"}/api/rulesets/{id}/docsbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidThe documentation tabs and completeness.
application/json- response
A ruleset's documentation tabs as the caller sees them (#1163).
tabs?array<>Tabs ordered by sortOrder. Callers who can't edit get only the overview and the tabs with content.
completeness?How many of the predefined documentation tabs carry non-empty content. A soft signal for badges / progress UI, not a gate. Only the four predefined tabs (overview/configuration/examples/faq) count.
canEdit?booleanWhether the caller may edit these tabs.
curl -X GET 'https://www.p4a.ai/api/rulesets/497f6eca-6276-4993-bfeb-53cbbbba6f08/docs'{ "tabs": [ { "key": "string", "title": "string", "kind": "predefined", "bodyMd": "string", "sortOrder": 0 } ], "completeness": { "filled": 0, "total": 0, "ratio": 0 }, "canEdit": true}/api/rulesets/{id}/docsbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidapplication/json- body
The complete new tab set for a ruleset. Must include an overview tab (the one mandatory tab). Keys overview/rules/examples/faq become predefined tabs; others (including configuration) are custom.
tabs*array<>1 <= items <= 50The new documentation tab set and completeness.
application/json- response
A ruleset's documentation tabs as the caller sees them (#1163).
tabs?array<>Tabs ordered by sortOrder. Callers who can't edit get only the overview and the tabs with content.
completeness?How many of the predefined documentation tabs carry non-empty content. A soft signal for badges / progress UI, not a gate. Only the four predefined tabs (overview/configuration/examples/faq) count.
canEdit?booleanWhether the caller may edit these tabs.
curl -X POST 'https://www.p4a.ai/api/rulesets/497f6eca-6276-4993-bfeb-53cbbbba6f08/docs' \ -H 'Content-Type: application/json' \ -d '{ "tabs": [ { "key": "string", "title": "string" } ]}'{ "tabs": [ { "key": "string", "title": "string", "kind": "predefined", "bodyMd": "string", "sortOrder": 0 } ], "completeness": { "filled": 0, "total": 0, "ratio": 0 }, "canEdit": true}/api/rulesets/{id}/docs/{key}bearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidkey*stringTab key. overview/rules/examples/faq are predefined tabs; any other key (including configuration) is a custom tab.
^[a-z0-9][a-z0-9_-]{0,63}$application/json- body
title*stringbodyMd?stringsortOrder?integerThe tab as stored.
application/json- response
tab?One per-policy documentation tab (#817).
curl -X PUT 'https://www.p4a.ai/api/rulesets/497f6eca-6276-4993-bfeb-53cbbbba6f08/docs/string' \ -H 'Content-Type: application/json' \ -d '{ "title": "string"}'{ "tab": { "key": "string", "title": "string", "kind": "predefined", "bodyMd": "string", "sortOrder": 0 }}/api/rulesets/{id}/docs/{key}bearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidkey*stringTab key. overview/rules/examples/faq are predefined tabs; any other key (including configuration) is a custom tab.
^[a-z0-9][a-z0-9_-]{0,63}$Success.
application/json- response
ok?booleancurl -X DELETE 'https://www.p4a.ai/api/rulesets/497f6eca-6276-4993-bfeb-53cbbbba6f08/docs/string'{ "ok": true}/api/ruleset-submissionsbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
Your ruleset submissions.
application/json- response
submissions?array<>curl -X GET 'https://www.p4a.ai/api/ruleset-submissions'{ "submissions": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "status": "submitted", "submitted_by": "6703ac2f-9eb5-40e9-9fde-511b2dbf4be5", "name": "string", "description": "string", "category": "Security", "source_url": "http://example.com", "source_ref": "string", "ruleset_path": "string", "profile_name": "string", "rule_counts": { "violation": 0, "warning": 0, "info": 0 }, "rule_names": [ "string" ], "target_scopes": [ "rest-api" ], "exchange_asset_id": "string", "icon_url": "http://example.com", "tags": [ "string" ], "video_tutorial_url": "http://example.com", "examples_url": "http://example.com", "review_feedback": "string", "reviewed_by": "92ab4dbc-1b27-40ce-b24b-7dde8f4709be", "reviewed_at": "2019-08-24T14:15:22Z", "ruleset_id": "ca688a19-2766-4b2c-aefa-28d16a464773", "previous_snapshot": { "name": "string", "description": "string", "category": "Security", "source_url": "http://example.com", "source_ref": "string", "ruleset_path": "string", "profile_name": "string", "rule_names": [ "string" ], "target_scopes": [ "rest-api" ], "exchange_asset_id": "string", "tags": [ "string" ], "video_tutorial_url": "http://example.com", "examples_url": "http://example.com", "snapshotted_at": "2019-08-24T14:15:22Z" }, "revision_count": 0, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ]}/api/ruleset-submissionsbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
application/json- body
name*string2 <= length <= 120description*string10 <= length <= 20000repoUrl*stringPublic GitHub, GitLab, or Bitbucket repo URL. A /tree/<ref>/<path> URL scopes the ruleset root to that folder.
uricategory?RulesetCategoryCatalog category of a community ruleset. Defaults to Other.
"Security""API Design""Documentation""Compliance""MCP""A2A""LLM""Operations""Other"sourceRef?stringDefault branch, tag, or commit. Omit (or send an empty string) for the default branch.
length <= 255rulesetPath?stringProfile file path relative to the ruleset root. Omit to auto-discover it.
length <= 1024targetScopes?array<>Asset kinds the ruleset applies to. Defaults to what the profile targets.
exchangeAssetId?string^[A-Za-z0-9][A-Za-z0-9._-]*$length <= 255iconUrl?stringCatalog icon. Omit to use icon.png or icon.svg from the ruleset root, if present.
uriiconDisabled?booleanShow the default icon, ignoring iconUrl and any icon in the repository.
tags?array<>items <= 20videoTutorialUrl?stringuriexamplesUrl?stringuridocTabs?array<>Optional documentation tabs (#1163), staged with the submission and copied to the ruleset when it moves to review. Keys must be unique. The reserved keys overview, rules, examples and faq are predefined tabs; any other key is a custom tab. Missing predefined tabs are added empty, and a blank overview keeps the description as the overview.
items <= 50deliversIdeaIds?array<>Optional. Approved ideas this submission declares it delivers, each with a coverage. Every idea must be approved and visible to you, and may appear once, or the request is rejected (422). This is declared intent: an idea flips to delivered (and its submitter is notified) only once a ruleset that fully delivers it, or that an admin marks as completing it, is approved.
items <= 50The created submission and any validation warnings.
application/json- response
submission?warnings?array<string>curl -X POST 'https://www.p4a.ai/api/ruleset-submissions' \ -H 'Content-Type: application/json' \ -d '{ "name": "string", "description": "stringstri", "repoUrl": "http://example.com"}'{ "submission": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "status": "submitted", "submitted_by": "6703ac2f-9eb5-40e9-9fde-511b2dbf4be5", "name": "string", "description": "string", "category": "Security", "source_url": "http://example.com", "source_ref": "string", "ruleset_path": "string", "profile_name": "string", "rule_counts": { "violation": 0, "warning": 0, "info": 0 }, "rule_names": [ "string" ], "target_scopes": [ "rest-api" ], "exchange_asset_id": "string", "icon_url": "http://example.com", "tags": [ "string" ], "video_tutorial_url": "http://example.com", "examples_url": "http://example.com", "review_feedback": "string", "reviewed_by": "92ab4dbc-1b27-40ce-b24b-7dde8f4709be", "reviewed_at": "2019-08-24T14:15:22Z", "ruleset_id": "ca688a19-2766-4b2c-aefa-28d16a464773", "previous_snapshot": { "name": "string", "description": "string", "category": "Security", "source_url": "http://example.com", "source_ref": "string", "ruleset_path": "string", "profile_name": "string", "rule_names": [ "string" ], "target_scopes": [ "rest-api" ], "exchange_asset_id": "string", "tags": [ "string" ], "video_tutorial_url": "http://example.com", "examples_url": "http://example.com", "snapshotted_at": "2019-08-24T14:15:22Z" }, "revision_count": 0, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" }, "warnings": [ "string" ]}/api/ruleset-submissions/{id}bearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidThe submission.
application/json- response
submission?docTabs?array<>The documentation tabs staged on the submission (#1163), copied to the ruleset when it moves to review.
curl -X GET 'https://www.p4a.ai/api/ruleset-submissions/497f6eca-6276-4993-bfeb-53cbbbba6f08'{ "submission": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "status": "submitted", "submitted_by": "6703ac2f-9eb5-40e9-9fde-511b2dbf4be5", "name": "string", "description": "string", "category": "Security", "source_url": "http://example.com", "source_ref": "string", "ruleset_path": "string", "profile_name": "string", "rule_counts": { "violation": 0, "warning": 0, "info": 0 }, "rule_names": [ "string" ], "target_scopes": [ "rest-api" ], "exchange_asset_id": "string", "icon_url": "http://example.com", "tags": [ "string" ], "video_tutorial_url": "http://example.com", "examples_url": "http://example.com", "review_feedback": "string", "reviewed_by": "92ab4dbc-1b27-40ce-b24b-7dde8f4709be", "reviewed_at": "2019-08-24T14:15:22Z", "ruleset_id": "ca688a19-2766-4b2c-aefa-28d16a464773", "previous_snapshot": { "name": "string", "description": "string", "category": "Security", "source_url": "http://example.com", "source_ref": "string", "ruleset_path": "string", "profile_name": "string", "rule_names": [ "string" ], "target_scopes": [ "rest-api" ], "exchange_asset_id": "string", "tags": [ "string" ], "video_tutorial_url": "http://example.com", "examples_url": "http://example.com", "snapshotted_at": "2019-08-24T14:15:22Z" }, "revision_count": 0, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" }, "docTabs": [ { "key": "string", "title": "string", "kind": "predefined", "bodyMd": "string", "sortOrder": 0 } ]}/api/ruleset-submissions/{id}bearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidapplication/json- body
Any subset of the RulesetSubmissionInput fields. An empty string clears an optional field.
1 <= propertiesname?string2 <= length <= 120description?string10 <= length <= 20000repoUrl?stringuricategory?RulesetCategoryCatalog category of a community ruleset. Defaults to Other.
"Security""API Design""Documentation""Compliance""MCP""A2A""LLM""Operations""Other"sourceRef?stringlength <= 255rulesetPath?stringlength <= 1024targetScopes?array<>exchangeAssetId?stringlength <= 255iconUrl?stringiconDisabled?booleanClear the icon and show the default. Wins over iconUrl.
tags?array<string>videoTutorialUrl?stringexamplesUrl?stringresubmit?booleanSend a needs_improvement submission back for review.
docTabs?array<>Optional documentation tabs (#1163), staged with the submission and copied to the ruleset when it moves to review. Keys must be unique. The reserved keys overview, rules, examples and faq are predefined tabs; any other key is a custom tab. Missing predefined tabs are added empty, and a blank overview keeps the description as the overview. On a patch the array replaces the staged set; omit it to keep the staged tabs.
items <= 50deliversIdeaIds?array<>Replaces the ideas this submission declares it delivers. Omit it to keep them; send [] to clear them. Every idea you add must be approved and visible to you (422); ideas already declared stay valid even if they have since been delivered. You can change them while the submission is submitted or needs_improvement; sending only this field does not resubmit. Once the ruleset is under review only an admin can change them (403). When the same request also edits fields or resubmits, the edit is applied first, and if it is rejected (409/403) the declared ideas are left unchanged.
items <= 50The updated submission.
application/json- response
submission?curl -X PATCH 'https://www.p4a.ai/api/ruleset-submissions/497f6eca-6276-4993-bfeb-53cbbbba6f08' \ -H 'Content-Type: application/json' \ -d '{}'{ "submission": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "status": "submitted", "submitted_by": "6703ac2f-9eb5-40e9-9fde-511b2dbf4be5", "name": "string", "description": "string", "category": "Security", "source_url": "http://example.com", "source_ref": "string", "ruleset_path": "string", "profile_name": "string", "rule_counts": { "violation": 0, "warning": 0, "info": 0 }, "rule_names": [ "string" ], "target_scopes": [ "rest-api" ], "exchange_asset_id": "string", "icon_url": "http://example.com", "tags": [ "string" ], "video_tutorial_url": "http://example.com", "examples_url": "http://example.com", "review_feedback": "string", "reviewed_by": "92ab4dbc-1b27-40ce-b24b-7dde8f4709be", "reviewed_at": "2019-08-24T14:15:22Z", "ruleset_id": "ca688a19-2766-4b2c-aefa-28d16a464773", "previous_snapshot": { "name": "string", "description": "string", "category": "Security", "source_url": "http://example.com", "source_ref": "string", "ruleset_path": "string", "profile_name": "string", "rule_names": [ "string" ], "target_scopes": [ "rest-api" ], "exchange_asset_id": "string", "tags": [ "string" ], "video_tutorial_url": "http://example.com", "examples_url": "http://example.com", "snapshotted_at": "2019-08-24T14:15:22Z" }, "revision_count": 0, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" }}/api/ruleset-submissions/{id}bearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidSuccess.
application/json- response
ok?booleancurl -X DELETE 'https://www.p4a.ai/api/ruleset-submissions/497f6eca-6276-4993-bfeb-53cbbbba6f08'{ "ok": true}/api/ruleset-submissions/{id}/historybearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidReview history entries.
application/json- response
entries?array<>curl -X GET 'https://www.p4a.ai/api/ruleset-submissions/497f6eca-6276-4993-bfeb-53cbbbba6f08/history'{ "entries": [ {} ]}/api/ruleset-submissions/validatebearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
application/json- body
repoUrl*stringGitHub, GitLab, or Bitbucket repo URL. A /tree/<ref>/<path> URL scopes the ruleset root to that folder.
uriref?stringBranch, tag, or commit to inspect. Defaults to the URL ref, then the default branch.
rulesetPath?stringProfile file path relative to the ruleset root; skips auto-discovery.
includeBranches?booleanAlso return the repository's branch list for a ref picker.
The validation result. validation.ok is false (with errors) when the repository or profile is not acceptable.
application/json- response
validation?branchInfo?Present when includeBranches is true and validation passed.
curl -X POST 'https://www.p4a.ai/api/ruleset-submissions/validate' \ -H 'Content-Type: application/json' \ -d '{ "repoUrl": "http://example.com"}'{ "validation": { "ok": true, "errors": [ "string" ], "warnings": [ "string" ], "ref": "string", "subPath": "string", "rulesetPath": "string", "rulesetPathSource": "explicit", "profile": { "profileName": "string", "description": "string", "ruleNames": [ "string" ], "ruleCounts": { "violation": 0, "warning": 0, "info": 0 }, "targetClasses": [ "string" ], "dialectVersion": "1.0" }, "exchange": { "assetId": "string", "name": "string", "description": "string", "main": "string" }, "targetScopes": [ "rest-api" ], "iconUrl": "http://example.com" }, "branchInfo": {}}Deployments
/api/deploymentsbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
rulesetId?stringOnly ruleset deployments for this ruleset.
uuidassetType?stringFilter by deployed asset type. Omit to return both.
"policy""ruleset"Your deployments, paginated.
application/json- response
deployments?array<>pagination?curl -X GET 'https://www.p4a.ai/api/deployments'{ "deployments": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "asset_type": "policy", "policy_id": "ee9b03e0-6495-427a-85a5-34444d24ae04", "ruleset_id": "ca688a19-2766-4b2c-aefa-28d16a464773", "governance_profile": {}, "governance_profile_result": {}, "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": {}}/api/deploymentsbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
application/json- body
policyId*stringuuidconnectionId*stringuuidworkspaceId*stringuuidtargetOrganizationIds*array<string>1 <= items <= 50doPublish?booleandoRelease?booleancleanupDev?booleanref?stringimplementationRef?stringversion?stringOptional override for the published Exchange asset version. Semver core only (MAJOR.MINOR.PATCH, e.g. 1.2.3 — no v prefix, no pre-release/build suffix). Omit to derive the version from the policy repo. A Publish still appends a -dev.<timestamp> suffix.
^\d+\.\d+\.\d+$All target organizations were enqueued successfully.
application/json- response
results?array<>curl -X POST 'https://www.p4a.ai/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 } } ]}/api/deployments/delete-failedbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
application/json- body
policyId?stringOnly delete failed deployments of this policy. Omit to clear all of yours.
uuidHow many failed deployments were deleted.
application/json- response
deletedCount?integerdeletedDeploymentIds?array<string>curl -X POST 'https://www.p4a.ai/api/deployments/delete-failed' \ -H 'Content-Type: application/json' \ -d '{}'{ "deletedCount": 0, "deletedDeploymentIds": [ "string" ]}/api/deployments/{id}bearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidThe deleted deployment id.
application/json- response
deletedDeploymentId?stringcurl -X DELETE 'https://www.p4a.ai/api/deployments/497f6eca-6276-4993-bfeb-53cbbbba6f08'{ "deletedDeploymentId": "string"}/api/deployments/{id}/cancelbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidSuccess.
application/json- response
ok?booleancurl -X POST 'https://www.p4a.ai/api/deployments/497f6eca-6276-4993-bfeb-53cbbbba6f08/cancel'{ "ok": true}/api/deployments/{id}/delete-releasebearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidThe enqueued cleanup job, if one was created.
application/json- response
job?|nullcurl -X POST 'https://www.p4a.ai/api/deployments/497f6eca-6276-4993-bfeb-53cbbbba6f08/delete-release'{ "job": {}}/api/deployments/{id}/dev-versionbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidThe DEV-version probe result.
application/json- response
dev_version_exists?boolean|nullcurl -X GET 'https://www.p4a.ai/api/deployments/497f6eca-6276-4993-bfeb-53cbbbba6f08/dev-version'{ "dev_version_exists": true}/api/deployments/{id}/historybearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidThe deployment's jobs and most-recent logs.
application/json- response
jobs?array<>job?|nulllogs?array<>curl -X GET 'https://www.p4a.ai/api/deployments/497f6eca-6276-4993-bfeb-53cbbbba6f08/history'{ "jobs": [ {} ], "job": {}, "logs": [ {} ]}/api/deployments/{id}/logsbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidA text/event-stream of log chunks.
response?stringtext/event-streamcurl -X GET 'https://www.p4a.ai/api/deployments/497f6eca-6276-4993-bfeb-53cbbbba6f08/logs'"string"/api/deployments/{id}/syncbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidThe reconciliation result.
application/json- response
ok?booleanresult?string"in_sync""deleted""unknown"status?stringcurl -X POST 'https://www.p4a.ai/api/deployments/497f6eca-6276-4993-bfeb-53cbbbba6f08/sync'{ "ok": true, "result": "in_sync", "status": "string"}/api/deployments/{id}/unpublishbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidThe enqueued unpublish job, if one was created.
application/json- response
job?|nullcurl -X POST 'https://www.p4a.ai/api/deployments/497f6eca-6276-4993-bfeb-53cbbbba6f08/unpublish'{ "job": {}}Connections
/api/connectionsbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
Your connections.
application/json- response
connections?array<>curl -X GET 'https://www.p4a.ai/api/connections'{ "connections": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "host": "us", "client_id": "string", "organization_id": "string" } ]}/api/connectionsbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
application/json- body
host*string"us""eu""custom"customDomain?|uriclientId*string4 <= lengthclientSecret*string4 <= lengthorganizationId*string4 <= lengthname*string2 <= length <= 80The created connection and credential validation result.
application/json- response
connection?validation?curl -X POST 'https://www.p4a.ai/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": {}}/api/connections/{id}bearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidThe connection.
application/json- response
connection?is_owner?booleancurl -X GET 'https://www.p4a.ai/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}/api/connections/{id}bearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidapplication/json- body
Credential fields (clientId, clientSecret, organizationId) are all-or-none.
name?stringhost?string"us""eu""custom"customDomain?|uriclientId?string4 <= lengthclientSecret?string4 <= lengthorganizationId?string4 <= lengthThe updated connection.
application/json- response
connection?curl -X PATCH 'https://www.p4a.ai/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" }}/api/connections/{id}bearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidSuccess.
application/json- response
ok?booleancurl -X DELETE 'https://www.p4a.ai/api/connections/497f6eca-6276-4993-bfeb-53cbbbba6f08'{ "ok": true}/api/connections/{id}/syncbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidThe connection, validation result, and deployment reconciliation summary.
application/json- response
connection?validation?reconciliation?Deployment reconciliation summary. null when credentials failed to validate or the probe sweep could not complete.
curl -X POST 'https://www.p4a.ai/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" } ] }}/api/connections/{id}/orgsbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidThe organizations visible through the connection.
application/json- response
orgs?array<>curl -X GET 'https://www.p4a.ai/api/connections/497f6eca-6276-4993-bfeb-53cbbbba6f08/orgs'{ "orgs": [ { "id": "string", "name": "string", "isPrimary": true, "fullPath": "string" } ]}/api/connections/{id}/workspacesbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidThe workspace shares for this connection.
application/json- response
shared?array<>curl -X GET 'https://www.p4a.ai/api/connections/497f6eca-6276-4993-bfeb-53cbbbba6f08/workspaces'{ "shared": [ {} ]}/api/connections/{id}/impactbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidCounts of dependents, for confirmation before deletion.
application/json- response
active_deployments?integerhistorical_deployments?integerworkspace_links?integerhas_credential?booleancurl -X GET 'https://www.p4a.ai/api/connections/497f6eca-6276-4993-bfeb-53cbbbba6f08/impact'{ "active_deployments": 0, "historical_deployments": 0, "workspace_links": 0, "has_credential": true}/api/connections/validatebearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
application/json- body
host*string"us""eu""custom"customDomain?|uriclientId*string4 <= lengthclientSecret*string4 <= lengthorganizationId*string4 <= lengthWhether the credentials authenticate.
application/json- response
ok?booleanerror?stringcurl -X POST 'https://www.p4a.ai/api/connections/validate' \ -H 'Content-Type: application/json' \ -d '{ "host": "us", "clientId": "string", "clientSecret": "string", "organizationId": "string"}'{ "ok": true, "error": "string"}Workspaces
/api/workspacesbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
The workspaces you belong to.
application/json- response
memberships?array<>curl -X GET 'https://www.p4a.ai/api/workspaces'{ "memberships": [ {} ]}/api/workspacesbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
application/json- body
name*string2 <= length <= 80slug?string2 <= length <= 48The created workspace.
application/json- response
workspace?curl -X POST 'https://www.p4a.ai/api/workspaces' \ -H 'Content-Type: application/json' \ -d '{ "name": "string"}'{ "workspace": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "slug": "string" }}/api/workspaces/{id}bearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidThe workspace and its related data.
application/json- response
workspace?role?stringThe caller's role. Null for a platform admin who is not a member.
"owner""admin""member"is_admin?booleancaller_id?stringuuidconnections?array<>connectionStats?Live counters keyed by connection id.
installedPolicies?array<>Unique policies live through the workspace's connections, newest deployment first.
installedRulesets?array<>Unique rulesets live through the workspace's connections, newest deployment first.
members?array<>Empty for a personal workspace.
curl -X GET 'https://www.p4a.ai/api/workspaces/497f6eca-6276-4993-bfeb-53cbbbba6f08'{ "workspace": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "slug": "string" }, "role": "owner", "is_admin": true, "caller_id": "bc12a995-fda4-4e32-ba32-5851a0f06a0a", "connections": [ {} ], "connectionStats": { "property1": { "deployments": 0, "target_orgs": 0, "live_policies": 0, "ruleset_deployments": 0, "ruleset_target_orgs": 0, "live_rulesets": 0 }, "property2": { "deployments": 0, "target_orgs": 0, "live_policies": 0, "ruleset_deployments": 0, "ruleset_target_orgs": 0, "live_rulesets": 0 } }, "installedPolicies": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "category": "string", "description": "string", "pdk_version": "string", "owner_name": "string", "company": "string", "submitted_by": "6703ac2f-9eb5-40e9-9fde-511b2dbf4be5", "icon_url": "string", "deploys_in_workspace": 0, "latest_deployment_at": "2019-08-24T14:15:22Z" } ], "installedRulesets": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "category": "string", "description": "string", "target_scopes": [ "string" ], "owner_name": "string", "company": "string", "submitted_by": "6703ac2f-9eb5-40e9-9fde-511b2dbf4be5", "icon_url": "string", "deploys_in_workspace": 0, "latest_deployment_at": "2019-08-24T14:15:22Z" } ], "members": [ {} ]}/api/workspaces/{id}bearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidapplication/json- body
name*string2 <= length <= 80The updated workspace.
application/json- response
workspace?curl -X PATCH 'https://www.p4a.ai/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" }}/api/workspaces/{id}/archivebearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidThe new archive timestamp.
application/json- response
archived_at?string|nullcurl -X POST 'https://www.p4a.ai/api/workspaces/497f6eca-6276-4993-bfeb-53cbbbba6f08/archive'{ "archived_at": "string"}/api/workspaces/{id}/archivebearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidThe cleared archive timestamp.
application/json- response
archived_at?string|nullcurl -X DELETE 'https://www.p4a.ai/api/workspaces/497f6eca-6276-4993-bfeb-53cbbbba6f08/archive'{ "archived_at": "string"}/api/workspaces/{id}/membersbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidThe members of the workspace.
application/json- response
members?array<>curl -X GET 'https://www.p4a.ai/api/workspaces/497f6eca-6276-4993-bfeb-53cbbbba6f08/members'{ "members": [ {} ]}/api/workspaces/{id}/membersbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidapplication/json- body
2 <= propertiesusername?stringThe invitee's @username (with or without a leading @).
email?stringemailrole*string"admin""member"Success.
application/json- response
ok?booleancurl -X POST 'https://www.p4a.ai/api/workspaces/497f6eca-6276-4993-bfeb-53cbbbba6f08/members' \ -H 'Content-Type: application/json' \ -d '{ "role": "admin"}'{ "ok": true}/api/workspaces/{id}/members/{userId}bearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuiduserId*stringuuidapplication/json- body
role?string"admin""member"disabled?falsefalseSuccess.
application/json- response
ok?booleancurl -X PATCH 'https://www.p4a.ai/api/workspaces/497f6eca-6276-4993-bfeb-53cbbbba6f08/members/497f6eca-6276-4993-bfeb-53cbbbba6f08' \ -H 'Content-Type: application/json' \ -d '{}'{ "ok": true}/api/workspaces/{id}/members/{userId}bearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuiduserId*stringuuidSuccess.
application/json- response
ok?booleancurl -X DELETE 'https://www.p4a.ai/api/workspaces/497f6eca-6276-4993-bfeb-53cbbbba6f08/members/497f6eca-6276-4993-bfeb-53cbbbba6f08'{ "ok": true}/api/workspaces/{id}/members/{userId}/impactbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuiduserId*stringuuidCounts of resources owned or authored by the member.
application/json- response
role?string"owner""admin""member"disabled_at?string|nullowned_shared_connections?integerdeployments_authored?integercurl -X GET 'https://www.p4a.ai/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}/api/workspaces/{id}/connectionsbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidapplication/json- body
connection_id*stringuuidSuccess.
application/json- response
ok?booleancurl -X POST 'https://www.p4a.ai/api/workspaces/497f6eca-6276-4993-bfeb-53cbbbba6f08/connections' \ -H 'Content-Type: application/json' \ -d '{ "connection_id": "d3547de1-d1f2-4344-b4c2-17169b7526f9"}'{ "ok": true}/api/workspaces/{id}/connectionsbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidapplication/json- body
connection_id*stringuuiddisabled?falsefalseSuccess.
application/json- response
ok?booleancurl -X PATCH 'https://www.p4a.ai/api/workspaces/497f6eca-6276-4993-bfeb-53cbbbba6f08/connections' \ -H 'Content-Type: application/json' \ -d '{ "connection_id": "d3547de1-d1f2-4344-b4c2-17169b7526f9"}'{ "ok": true}/api/workspaces/{id}/connectionsbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidconnection_id*stringuuidSuccess.
application/json- response
ok?booleancurl -X DELETE 'https://www.p4a.ai/api/workspaces/497f6eca-6276-4993-bfeb-53cbbbba6f08/connections?connection_id=497f6eca-6276-4993-bfeb-53cbbbba6f08'{ "ok": true}/api/workspaces/{id}/connections/{connectionId}/impactbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidconnectionId*stringuuidCounts describing the shared connection's visibility and use.
application/json- response
is_disabled?booleandisabled_reason?string|nullmembers_visible?integerdeployments_authored?integercurl -X GET 'https://www.p4a.ai/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
/api/policies/{id}/transfersbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidapplication/json- body
1 <= propertiesrecipientUsername?stringThe recipient's @username (with or without a leading @).
recipientEmail?stringemailThe created transfer.
application/json- response
transfer?curl -X POST 'https://www.p4a.ai/api/policies/497f6eca-6276-4993-bfeb-53cbbbba6f08/transfers' \ -H 'Content-Type: application/json' \ -d '{}'{ "transfer": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "to_user_id": "bdcaa974-8e23-4fc9-823d-e060850bbef1" }}/api/transfers/{id}/acceptbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidThe accepted transfer and the resource now owned.
application/json- response
transfer?resourceType?string"policy""idea""ruleset"resourceId?stringuuidcurl -X POST 'https://www.p4a.ai/api/transfers/497f6eca-6276-4993-bfeb-53cbbbba6f08/accept'{ "transfer": {}, "resourceType": "policy", "resourceId": "026d60bb-63a8-407e-bf67-01dcfc6022e6"}/api/transfers/{id}/cancelbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidThe cancelled transfer.
application/json- response
transfer?curl -X POST 'https://www.p4a.ai/api/transfers/497f6eca-6276-4993-bfeb-53cbbbba6f08/cancel'{ "transfer": {}}/api/transfers/{id}/rejectbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidapplication/json- body
feedback?stringlength <= 4000The rejected transfer.
application/json- response
transfer?curl -X POST 'https://www.p4a.ai/api/transfers/497f6eca-6276-4993-bfeb-53cbbbba6f08/reject' \ -H 'Content-Type: application/json' \ -d '{}'{ "transfer": {}}Tokens
/api/tokensbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
Your tokens (secrets are never returned).
application/json- response
tokens?array<>curl -X GET 'https://www.p4a.ai/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" } ]}cookieAuthsb-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.
application/json- body
name*string1 <= length <= 100scopes*array<>1 <= itemsexpiresInDays?|3090365nullThe new token's secret (shown once) and its record.
application/json- response
token?stringrecord?curl -X POST 'https://www.p4a.ai/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" }}/api/tokens/{id}bearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
id*stringThe resource's UUID.
uuidThe revoked token's record.
application/json- response
ok?booleanrecord?curl -X DELETE 'https://www.p4a.ai/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
/api/mebearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
Your profile.
application/json- response
user?curl -X GET 'https://www.p4a.ai/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 }}/api/mebearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
application/json- body
company?string1 <= length <= 120username?stringYour unique @-mention handle: 3–30 chars, lowercased, [a-z0-9] with internal _/- (no leading/trailing separator). Must be unique across all users.
^[a-z0-9][a-z0-9_-]{1,28}[a-z0-9]$3 <= length <= 30bio?|Optional short public bio (1–1000 chars). Send null (or an empty string) to clear it. Only visible to others when profileIsPublic is true.
length <= 1000linkedinUrl?|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?booleanOpt-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.
Your updated profile.
application/json- response
user?curl -X PATCH 'https://www.p4a.ai/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 }}/api/me/transfersbearerAuthAuthorizationBearer <token>A personal access token, sent as Authorization: Bearer p4a_….
role?string"recipient""initiator"Transfers where you are the recipient or initiator.
application/json- response
transfers?array<>curl -X GET 'https://www.p4a.ai/api/me/transfers'{ "transfers": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "resource_type": "policy", "resource_id": "4d5215ed-38bb-48ed-879a-fdb9ca58522f", "resource_name": "string", "policy_id": "ee9b03e0-6495-427a-85a5-34444d24ae04", "policy_name": "string", "status": "string", "feedback": "string", "created_at": "2019-08-24T14:15:22Z", "decided_at": "2019-08-24T14:15:22Z", "expires_at": "2019-08-24T14:15:22Z", "counterparty_name": "string", "counterparty_email": "string", "role": "recipient" } ]}