{ "openapi": "3.1.0", "info": { "title": "P4A REST API", "version": "1.0.0", "description": "The P4A REST API lets an external client or script act on your behalf using a\n[personal access token](/docs/api/personal-access-tokens). Every endpoint\ndocumented here is reachable with a token; admin-only endpoints are not part\nof this surface.\n\n## Authentication\n\nSend your token as a Bearer credential on every request:\n\n```\nAuthorization: Bearer p4a_xxxxxxxxxxxxxxxxxxxxxxxx\n```\n\nA token acts as you: requests are attributed to your account and limited to\nwhat you can already access. The same data scoping that applies in the\ndashboard applies to the API.\n\n## Scopes\n\nEach endpoint requires one scope, chosen by HTTP method:\n\n- **`api:read`** — `GET` requests (discover policies, read your own resources).\n- **`api:write`** — `POST`, `PATCH`, `PUT`, `DELETE` requests (submit policies,\n trigger deployments, manage workspaces and connections).\n\nA request whose token is missing the required scope is rejected with `403`.\nA missing, invalid, expired, or revoked token is rejected with `401`.\n" }, "servers": [ { "url": "{origin}", "description": "P4A API origin. Defaults to production; override the `origin` variable in the playground's server dialog to target a non-production environment (e.g. a preview deploy or `http://localhost:3000`).", "variables": { "origin": { "default": "https://www.p4a.ai", "description": "Scheme + host of the P4A instance to call (no trailing slash)." } } } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Policies", "description": "Discover catalog policies and manage policies you own." }, { "name": "Submissions", "description": "Submit policies for review and track their status." }, { "name": "Deployments", "description": "Deploy policies to your Anypoint organizations and manage releases." }, { "name": "Connections", "description": "Manage Anypoint connections and inspect their reach." }, { "name": "Workspaces", "description": "Create workspaces, manage members, and share connections." }, { "name": "Transfers", "description": "Transfer policy ownership between users." }, { "name": "Tokens", "description": "List and revoke your own personal access tokens." }, { "name": "Account", "description": "Read and update your own profile." } ], "paths": { "/api/policies": { "get": { "tags": [ "Policies" ], "summary": "List catalog policies", "description": "Returns the policy catalog. Anonymous and read-token callers see approved\npolicies; an authenticated caller additionally sees their own\nunder-review or private policies.\n\nWith `source=mulesoft`, returns the read-only catalog of MuleSoft\nout-of-the-box (Omni/Flex Gateway) policies synced from\ndocs.mulesoft.com instead. Those entries are summary rows\n(`MuleSoftPolicySummary`, keyed by `slug`, no `body_md`); fetch one\npolicy's full documentation body via\n`GET /api/mulesoft-policies/{slug}`.\n", "operationId": "listPolicies", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "category", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by policy category." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Free-text search over name and description (name and summary for `source=mulesoft`)." }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "community", "mulesoft" ], "default": "community" }, "description": "Which catalog to list. `community` (default) = user-submitted P4A\npolicies. `mulesoft` = MuleSoft out-of-the-box Omni/Flex Gateway\npolicies (read-only, `MuleSoftPolicySummary` items).\n" }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "inbound", "outbound" ] }, "description": "`source=mulesoft` only. Filter by enforcement leg — `inbound`\n(incoming request, most policies) or `outbound` (upstream/response\nleg, e.g. `tls-outbound`). Ignored for the community catalog.\n" } ], "responses": { "200": { "description": "The matching policies.", "content": { "application/json": { "schema": { "type": "object", "properties": { "policies": { "type": "array", "description": "`Policy` items for the community catalog;\n`MuleSoftPolicySummary` items when `source=mulesoft`.\n", "items": { "oneOf": [ { "$ref": "#/components/schemas/Policy" }, { "$ref": "#/components/schemas/MuleSoftPolicySummary" } ] } } } } } } } } } }, "/api/mulesoft-policies/{slug}": { "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The MuleSoft policy slug (from a `source=mulesoft` list entry)." } ], "get": { "tags": [ "Policies" ], "summary": "Get a MuleSoft out-of-the-box policy", "description": "Returns one MuleSoft out-of-the-box (Omni/Flex Gateway) policy including\nits full documentation body (`body_md`, synced from docs.mulesoft.com).\nPublic: the MuleSoft catalog is guest-readable. Slugs that are no longer\npresent in the docs index return 404.\n", "operationId": "getMuleSoftPolicy", "security": [ { "bearerAuth": [] }, {} ], "responses": { "200": { "description": "The MuleSoft policy.", "content": { "application/json": { "schema": { "type": "object", "properties": { "policy": { "$ref": "#/components/schemas/MuleSoftPolicy" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/policies/{id}": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "tags": [ "Policies" ], "summary": "Get a policy", "operationId": "getPolicy", "security": [ { "bearerAuth": [] }, {} ], "responses": { "200": { "description": "The policy.", "content": { "application/json": { "schema": { "type": "object", "properties": { "policy": { "$ref": "#/components/schemas/Policy" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Policies" ], "summary": "Update a policy you own", "description": "Requires `api:write`. Only the policy owner may edit these fields.", "operationId": "updatePolicy", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyPatch" } } } }, "responses": { "200": { "description": "The updated policy.", "content": { "application/json": { "schema": { "type": "object", "properties": { "policy": { "$ref": "#/components/schemas/Policy" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/policies/{id}/branches": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "tags": [ "Policies" ], "summary": "List the policy's repository branches", "operationId": "listPolicyBranches", "responses": { "200": { "description": "Branch information for the policy's source repository.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/policies/{id}/download": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "post": { "tags": [ "Policies" ], "summary": "Record a policy download", "description": "Requires `api:write`. Records that you fetched the install command.", "operationId": "recordPolicyDownload", "responses": { "200": { "$ref": "#/components/responses/Ok" } } } }, "/api/policies/{id}/history": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "tags": [ "Policies" ], "summary": "List a policy's lifecycle history", "operationId": "listPolicyHistory", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "History entries, newest first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object" } }, "nextCursor": { "type": [ "string", "null" ] } } } } } } } } }, "/api/policies/{id}/issues-enabled": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "tags": [ "Policies" ], "summary": "Live re-check of whether the policy repo accepts issues", "description": "Live-verifies (against GitHub, cached ~1h) whether the policy's upstream repository currently accepts issues, for the \"Report an issue\" affordance (#66). Corrects the persisted `github_has_issues` baseline when an author disabled the tracker after publish. Visible to any caller who can read the policy (404 otherwise, same as `GET /api/policies/{id}`).", "operationId": "getPolicyIssuesEnabled", "security": [ { "bearerAuth": [] }, {} ], "responses": { "200": { "description": "The live issue-tracker state. `enabled` is `null` when GitHub couldn't be read (private/gone repo, rate limit, network) — the caller should keep trusting the persisted `github_has_issues`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "nullable": true } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/policies/{id}/like": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "tags": [ "Policies" ], "summary": "Whether you have liked this policy", "operationId": "getPolicyLike", "responses": { "200": { "description": "Your like state.", "content": { "application/json": { "schema": { "type": "object", "properties": { "liked": { "type": "boolean" } } } } } } } }, "post": { "tags": [ "Policies" ], "summary": "Toggle your like on a policy", "description": "Requires `api:write`.", "operationId": "togglePolicyLike", "responses": { "200": { "description": "Your like state after toggling.", "content": { "application/json": { "schema": { "type": "object", "properties": { "liked": { "type": "boolean" } } } } } } } } }, "/api/policies/{id}/comments": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "tags": [ "Policies" ], "summary": "List the discussion comments on a policy", "description": "Public but RLS-scoped: anonymous callers see comments on published policies; a signed-in caller additionally sees comments on their own unpublished policies. Returns a flat, oldest-first list — replies carry a non-null `parentId` (single-level threading) and the client rebuilds the tree. Soft-deleted comments are returned with `deleted: true` and empty `body`/`authorName`/`authorId` so reply chains stay intact.", "operationId": "listPolicyComments", "responses": { "200": { "description": "The policy's comments, oldest-first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "comments": { "type": "array", "items": { "$ref": "#/components/schemas/Comment" } } } } } } } } }, "post": { "tags": [ "Policies" ], "summary": "Post a comment or single-level reply on a policy", "description": "Requires `api:write`. Pass `parentId` to reply to a top-level comment; replies are limited to a single level (you cannot reply to a reply). Per-day quota-checked (HTTP 429 when exceeded).", "operationId": "createPolicyComment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentInput" } } } }, "responses": { "201": { "description": "The created comment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "$ref": "#/components/schemas/Comment" } } } } } }, "404": { "description": "Policy or parent comment not found (or not published).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid body, or reply nesting/parent-policy invariant violated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Daily comment quota exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/comments/{id}": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "patch": { "tags": [ "Policies" ], "summary": "Edit a comment", "description": "Requires `api:write`. Author-only (a platform admin may also edit). A no-op when the body is unchanged.", "operationId": "updateComment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "body" ], "properties": { "body": { "type": "string", "maxLength": 10000 } } } } } }, "responses": { "200": { "description": "The updated comment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "$ref": "#/components/schemas/Comment" } } } } } }, "403": { "description": "You are neither the author nor an admin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Comment not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The comment has been deleted and cannot be edited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Policies" ], "summary": "Delete a comment", "description": "Requires `api:write`. The author soft-deletes (the row is kept so replies don't orphan; the body is blanked and rendered as a placeholder). A platform admin may hard-delete with `?hard=true`.", "operationId": "deleteComment", "parameters": [ { "name": "hard", "in": "query", "required": false, "description": "Admin-only. `true` permanently removes the row and its replies.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "The comment was deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "403": { "description": "You are neither the author nor an admin (or hard-delete requested by a non-admin).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Comment not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/policies/{id}/orgs": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "tags": [ "Policies" ], "summary": "List Anypoint orgs eligible for this policy", "operationId": "listPolicyOrgs", "parameters": [ { "name": "connectionId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The eligible organizations for the given connection.", "content": { "application/json": { "schema": { "type": "object", "properties": { "orgs": { "type": "array", "items": { "$ref": "#/components/schemas/AnypointOrg" } } } } } } } } } }, "/api/policies/{id}/reviewers/me": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "tags": [ "Policies" ], "summary": "Whether you are a reviewer of this policy", "operationId": "getPolicyReviewerSelf", "responses": { "200": { "description": "Your reviewer state.", "content": { "application/json": { "schema": { "type": "object", "properties": { "isReviewer": { "type": "boolean" } } } } } } } } }, "/api/policies/{id}/transfers": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "post": { "tags": [ "Transfers" ], "summary": "Initiate a policy ownership transfer", "description": "Requires `api:write`. Offers ownership of the policy to another user by email.", "operationId": "initiatePolicyTransfer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "recipientEmail" ], "properties": { "recipientEmail": { "type": "string", "format": "email" } } } } } }, "responses": { "201": { "description": "The created transfer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "transfer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "to_user_id": { "type": "string", "format": "uuid" } } } } } } } } } } }, "/api/policies/{id}/revisions": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "tags": [ "Policies" ], "summary": "List your proposed edits for this policy", "description": "Lists the edit revisions you have proposed for this policy's About text or source repository. Scoped to your own revisions.", "operationId": "listPolicyRevisions", "responses": { "200": { "description": "Your revisions for this policy, newest first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "revisions": { "type": "array", "items": { "$ref": "#/components/schemas/PolicyRevision" } } } } } } } } }, "post": { "tags": [ "Policies" ], "summary": "Propose an edit to a published policy", "description": "Requires `api:write`. As the policy's owner, propose a new value for one field — the About text (`description`) or the source repository (`github_url`). The change does not go live immediately: it is stored as a pending revision and an administrator re-reviews it before it replaces the published value. A `github_url` change is re-validated for repository shape before it is accepted. Only one pending edit per field is allowed at a time.", "operationId": "submitPolicyRevision", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "field", "value" ], "properties": { "field": { "type": "string", "enum": [ "description" ] }, "value": { "type": "string", "minLength": 10, "maxLength": 20000, "description": "New Markdown About text." } } }, { "type": "object", "required": [ "field", "value" ], "properties": { "field": { "type": "string", "enum": [ "github_url" ] }, "value": { "type": "string", "format": "uri", "description": "New source repository URL (re-validated for shape)." } } } ] } } } }, "responses": { "201": { "description": "The created pending revision.", "content": { "application/json": { "schema": { "type": "object", "properties": { "revision": { "$ref": "#/components/schemas/PolicyRevision" }, "policy_name": { "type": "string" } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/submissions": { "get": { "tags": [ "Submissions" ], "summary": "List your submissions", "operationId": "listSubmissions", "responses": { "200": { "description": "Your submissions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "submissions": { "type": "array", "items": { "$ref": "#/components/schemas/Submission" } } } } } } } } }, "post": { "tags": [ "Submissions" ], "summary": "Submit a policy for review", "description": "Requires `api:write`. Accepts a unified or split (definition + implementation) project.", "operationId": "createSubmission", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionInput" } } } }, "responses": { "201": { "description": "The created submission and repository validation result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "submission": { "$ref": "#/components/schemas/Submission" }, "validation": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/submissions/{id}": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "patch": { "tags": [ "Submissions" ], "summary": "Update or resubmit a submission", "description": "Requires `api:write`. Resubmit a rejected policy or edit its docs metadata.", "operationId": "updateSubmission", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "The updated submission.", "content": { "application/json": { "schema": { "type": "object", "properties": { "submission": { "$ref": "#/components/schemas/Submission" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/submissions/{id}/history": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "tags": [ "Submissions" ], "summary": "List a submission's review history", "operationId": "listSubmissionHistory", "security": [ { "bearerAuth": [] }, {} ], "responses": { "200": { "description": "Review history entries.", "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object" } } } } } } } } } }, "/api/submissions/validate": { "post": { "tags": [ "Submissions" ], "summary": "Validate a submission's GitHub repositories", "description": "Requires `api:write`. Checks repo shape before you submit.", "operationId": "validateSubmission", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "projectType": { "type": "string", "enum": [ "unified", "split" ] }, "githubUrl": { "type": "string", "format": "uri" }, "implementationGithubUrl": { "type": "string", "format": "uri" } } } } } }, "responses": { "200": { "description": "The validation result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "validation": { "type": "object" } } } } } } } } }, "/api/deployments": { "get": { "tags": [ "Deployments" ], "summary": "List your deployments", "operationId": "listDeployments", "responses": { "200": { "description": "Your deployments, paginated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deployments": { "type": "array", "items": { "$ref": "#/components/schemas/Deployment" } }, "pagination": { "type": "object" } } } } } } } }, "post": { "tags": [ "Deployments" ], "summary": "Enqueue a deployment", "description": "Requires `api:write`. Fans out one deployment per target organization,\noptionally publishing and releasing.\n", "operationId": "createDeployment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentInput" } } } }, "responses": { "201": { "description": "All target organizations were enqueued successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/DeploymentResult" } } } } } } }, "207": { "description": "Partial success — some target organizations were enqueued and others failed. Inspect each entry in `results`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/DeploymentResult" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/deployments/delete-failed": { "post": { "tags": [ "Deployments" ], "summary": "Delete all your failed deployments", "description": "Requires `api:write`. Permanently removes every **failed** deployment\nrow you own (cascading its build jobs and logs), optionally narrowed to\na single policy. Only your own rows are touched.\n", "operationId": "deleteFailedDeployments", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "policyId": { "type": "string", "format": "uuid", "description": "Only delete failed deployments of this policy. Omit to clear all of yours." } } } } } }, "responses": { "200": { "description": "How many failed deployments were deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deletedCount": { "type": "integer" }, "deletedDeploymentIds": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/deployments/{id}": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "delete": { "tags": [ "Deployments" ], "summary": "Delete a failed deployment", "description": "Requires `api:write`. Permanently removes a single **failed**\ndeployment row (cascading its build jobs and logs). Returns `409` if\nthe deployment is in any status other than `failed`.\n", "operationId": "deleteDeployment", "responses": { "200": { "description": "The deleted deployment id.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deletedDeploymentId": { "type": "string" } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/deployments/{id}/cancel": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "post": { "tags": [ "Deployments" ], "summary": "Cancel an in-flight deployment", "description": "Requires `api:write`.", "operationId": "cancelDeployment", "responses": { "200": { "$ref": "#/components/responses/Ok" } } } }, "/api/deployments/{id}/delete-release": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "post": { "tags": [ "Deployments" ], "summary": "Delete a released deployment", "description": "Requires `api:write`. Enqueues removal of a published release.", "operationId": "deleteDeploymentRelease", "responses": { "201": { "description": "The enqueued cleanup job, if one was created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "type": [ "object", "null" ] } } } } } } } } }, "/api/deployments/{id}/dev-version": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "tags": [ "Deployments" ], "summary": "Check whether a deployment's DEV asset still exists", "description": "Requires `api:read`. Probes Anypoint for this Publish-mode\ndeployment's `-dev` asset version. Read-only reconnaissance (no\nstatus change, unlike `sync`) — the portal calls it lazily per row\nto decide whether to offer the \"Delete DEV version\" control.\n\n`dev_version_exists`:\n * `true` — at least one `-dev` peer is still present.\n * `false` — every tracked `-dev` peer is gone.\n * `null` — not a Publish-mode row, nothing to probe, or a\n transient Anypoint lookup failure.\n", "operationId": "getDeploymentDevVersion", "responses": { "200": { "description": "The DEV-version probe result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dev_version_exists": { "type": [ "boolean", "null" ] } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/deployments/{id}/history": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "tags": [ "Deployments" ], "summary": "Get a deployment's job history and logs", "operationId": "getDeploymentHistory", "responses": { "200": { "description": "The deployment's jobs and most-recent logs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "type": "object" } }, "job": { "type": [ "object", "null" ] }, "logs": { "type": "array", "items": { "type": "object" } } } } } } } } } }, "/api/deployments/{id}/logs": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "tags": [ "Deployments" ], "summary": "Stream a deployment's build logs", "description": "Returns a Server-Sent Events stream of log chunks.", "operationId": "streamDeploymentLogs", "responses": { "200": { "description": "A `text/event-stream` of log chunks.", "content": { "text/event-stream": { "schema": { "type": "string" } } } } } } }, "/api/deployments/{id}/sync": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "post": { "tags": [ "Deployments" ], "summary": "Reconcile a deployment's status with Anypoint", "description": "Requires `api:write`.", "operationId": "syncDeployment", "responses": { "200": { "description": "The reconciliation result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "result": { "type": "string", "enum": [ "in_sync", "deleted", "unknown" ] }, "status": { "type": "string" } } } } } } } } }, "/api/deployments/{id}/unpublish": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "post": { "tags": [ "Deployments" ], "summary": "Unpublish a deployment", "description": "Requires `api:write`. Enqueues removal of the published asset.", "operationId": "unpublishDeployment", "responses": { "201": { "description": "The enqueued unpublish job, if one was created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "type": [ "object", "null" ] } } } } } } } } }, "/api/connections": { "get": { "tags": [ "Connections" ], "summary": "List your Anypoint connections", "operationId": "listConnections", "responses": { "200": { "description": "Your connections.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connections": { "type": "array", "items": { "$ref": "#/components/schemas/Connection" } } } } } } } } }, "post": { "tags": [ "Connections" ], "summary": "Create an Anypoint connection", "description": "Requires `api:write`. The client secret is encrypted at rest and never returned.", "operationId": "createConnection", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionInput" } } } }, "responses": { "200": { "description": "The created connection and credential validation result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connection": { "$ref": "#/components/schemas/Connection" }, "validation": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/connections/{id}": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "tags": [ "Connections" ], "summary": "Get a connection", "operationId": "getConnection", "responses": { "200": { "description": "The connection.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connection": { "$ref": "#/components/schemas/Connection" }, "is_owner": { "type": "boolean" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Connections" ], "summary": "Update a connection", "description": "Requires `api:write`. Credential fields are all-or-none.", "operationId": "updateConnection", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionPatch" } } } }, "responses": { "200": { "description": "The updated connection.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connection": { "$ref": "#/components/schemas/Connection" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "delete": { "tags": [ "Connections" ], "summary": "Delete a connection", "description": "Requires `api:write`.", "operationId": "deleteConnection", "responses": { "200": { "$ref": "#/components/responses/Ok" } } } }, "/api/connections/{id}/sync": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "post": { "tags": [ "Connections" ], "summary": "Re-validate a connection's credentials", "description": "Requires `api:write`.", "operationId": "syncConnection", "responses": { "200": { "description": "The connection and validation result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connection": { "$ref": "#/components/schemas/Connection" }, "validation": { "type": "object" } } } } } } } } }, "/api/connections/{id}/orgs": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "tags": [ "Connections" ], "summary": "List the connection's Anypoint organizations", "operationId": "listConnectionOrgs", "responses": { "200": { "description": "The organizations visible through the connection.", "content": { "application/json": { "schema": { "type": "object", "properties": { "orgs": { "type": "array", "items": { "$ref": "#/components/schemas/AnypointOrg" } } } } } } } } } }, "/api/connections/{id}/workspaces": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "tags": [ "Connections" ], "summary": "List workspaces the connection is shared with", "operationId": "listConnectionWorkspaces", "responses": { "200": { "description": "The workspace shares for this connection.", "content": { "application/json": { "schema": { "type": "object", "properties": { "shared": { "type": "array", "items": { "type": "object" } } } } } } } } } }, "/api/connections/{id}/impact": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "tags": [ "Connections" ], "summary": "Summarize what depends on a connection", "operationId": "getConnectionImpact", "responses": { "200": { "description": "Counts of dependents, for confirmation before deletion.", "content": { "application/json": { "schema": { "type": "object", "properties": { "active_deployments": { "type": "integer" }, "historical_deployments": { "type": "integer" }, "workspace_links": { "type": "integer" }, "has_credential": { "type": "boolean" } } } } } } } } }, "/api/connections/validate": { "post": { "tags": [ "Connections" ], "summary": "Validate Anypoint credentials without saving", "description": "Requires `api:write`.", "operationId": "validateConnection", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionCredentials" } } } }, "responses": { "200": { "description": "Whether the credentials authenticate.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string" } } } } } } } } }, "/api/workspaces": { "get": { "tags": [ "Workspaces" ], "summary": "List your workspace memberships", "operationId": "listWorkspaces", "responses": { "200": { "description": "The workspaces you belong to.", "content": { "application/json": { "schema": { "type": "object", "properties": { "memberships": { "type": "array", "items": { "type": "object" } } } } } } } } }, "post": { "tags": [ "Workspaces" ], "summary": "Create a workspace", "description": "Requires `api:write`.", "operationId": "createWorkspace", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 80 }, "slug": { "type": "string", "minLength": 2, "maxLength": 48 } } } } } }, "responses": { "201": { "description": "The created workspace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace": { "$ref": "#/components/schemas/Workspace" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/workspaces/{id}": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "tags": [ "Workspaces" ], "summary": "Get a workspace with members and shares", "operationId": "getWorkspace", "responses": { "200": { "description": "The workspace and its related data.", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Workspaces" ], "summary": "Rename a workspace", "description": "Requires `api:write`.", "operationId": "updateWorkspace", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 80 } } } } } }, "responses": { "200": { "description": "The updated workspace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace": { "$ref": "#/components/schemas/Workspace" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/workspaces/{id}/archive": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "post": { "tags": [ "Workspaces" ], "summary": "Archive a workspace", "description": "Requires `api:write`.", "operationId": "archiveWorkspace", "responses": { "200": { "description": "The new archive timestamp.", "content": { "application/json": { "schema": { "type": "object", "properties": { "archived_at": { "type": [ "string", "null" ] } } } } } } } }, "delete": { "tags": [ "Workspaces" ], "summary": "Unarchive a workspace", "description": "Requires `api:write`.", "operationId": "unarchiveWorkspace", "responses": { "200": { "description": "The cleared archive timestamp.", "content": { "application/json": { "schema": { "type": "object", "properties": { "archived_at": { "type": [ "string", "null" ] } } } } } } } } }, "/api/workspaces/{id}/members": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "get": { "tags": [ "Workspaces" ], "summary": "List workspace members", "operationId": "listWorkspaceMembers", "responses": { "200": { "description": "The members of the workspace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "members": { "type": "array", "items": { "type": "object" } } } } } } } } }, "post": { "tags": [ "Workspaces" ], "summary": "Invite a member to a workspace", "description": "Requires `api:write`.", "operationId": "inviteWorkspaceMember", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": [ "admin", "member" ] } } } } } }, "responses": { "201": { "$ref": "#/components/responses/Ok" } } } }, "/api/workspaces/{id}/members/{userId}": { "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "patch": { "tags": [ "Workspaces" ], "summary": "Change a member's role or re-enable them", "description": "Requires `api:write`.", "operationId": "updateWorkspaceMember", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "admin", "member" ] }, "disabled": { "type": "boolean", "enum": [ false ] } } } } } }, "responses": { "200": { "$ref": "#/components/responses/Ok" } } }, "delete": { "tags": [ "Workspaces" ], "summary": "Remove a member from a workspace", "description": "Requires `api:write`.", "operationId": "removeWorkspaceMember", "responses": { "200": { "$ref": "#/components/responses/Ok" } } } }, "/api/workspaces/{id}/members/{userId}/impact": { "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Workspaces" ], "summary": "Summarize what depends on a member", "operationId": "getWorkspaceMemberImpact", "responses": { "200": { "description": "Counts of resources owned or authored by the member.", "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "disabled_at": { "type": [ "string", "null" ] }, "owned_shared_connections": { "type": "integer" }, "deployments_authored": { "type": "integer" } } } } } } } } }, "/api/workspaces/{id}/connections": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "post": { "tags": [ "Workspaces" ], "summary": "Share a connection into a workspace", "description": "Requires `api:write`.", "operationId": "shareWorkspaceConnection", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "connection_id" ], "properties": { "connection_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "201": { "$ref": "#/components/responses/Ok" } } }, "patch": { "tags": [ "Workspaces" ], "summary": "Re-enable a shared connection", "description": "Requires `api:write`.", "operationId": "updateWorkspaceConnection", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "connection_id" ], "properties": { "connection_id": { "type": "string", "format": "uuid" }, "disabled": { "type": "boolean", "enum": [ false ] } } } } } }, "responses": { "200": { "$ref": "#/components/responses/Ok" } } }, "delete": { "tags": [ "Workspaces" ], "summary": "Unshare a connection from a workspace", "description": "Requires `api:write`.", "operationId": "unshareWorkspaceConnection", "parameters": [ { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" } } } }, "/api/workspaces/{id}/connections/{connectionId}/impact": { "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Workspaces" ], "summary": "Summarize a shared connection's reach in a workspace", "operationId": "getWorkspaceConnectionImpact", "responses": { "200": { "description": "Counts describing the shared connection's visibility and use.", "content": { "application/json": { "schema": { "type": "object", "properties": { "is_disabled": { "type": "boolean" }, "disabled_reason": { "type": [ "string", "null" ] }, "members_visible": { "type": "integer" }, "deployments_authored": { "type": "integer" } } } } } } } } }, "/api/transfers/{id}/accept": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "post": { "tags": [ "Transfers" ], "summary": "Accept a policy transfer offered to you", "description": "Requires `api:write`.", "operationId": "acceptTransfer", "responses": { "200": { "description": "The accepted transfer and the policy now owned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "transfer": { "type": "object" }, "policyId": { "type": "string" } } } } } } } } }, "/api/transfers/{id}/cancel": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "post": { "tags": [ "Transfers" ], "summary": "Cancel a transfer you initiated", "description": "Requires `api:write`.", "operationId": "cancelTransfer", "responses": { "200": { "description": "The cancelled transfer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "transfer": { "type": "object" } } } } } } } } }, "/api/transfers/{id}/reject": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "post": { "tags": [ "Transfers" ], "summary": "Reject a policy transfer offered to you", "description": "Requires `api:write`.", "operationId": "rejectTransfer", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "feedback": { "type": "string", "maxLength": 4000 } } } } } }, "responses": { "200": { "description": "The rejected transfer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "transfer": { "type": "object" } } } } } } } } }, "/api/tokens": { "get": { "tags": [ "Tokens" ], "summary": "List your personal access tokens", "operationId": "listTokens", "responses": { "200": { "description": "Your tokens (secrets are never returned).", "content": { "application/json": { "schema": { "type": "object", "properties": { "tokens": { "type": "array", "items": { "$ref": "#/components/schemas/Token" } } } } } } } } }, "post": { "tags": [ "Tokens" ], "summary": "Create a personal access token", "description": "Requires a signed-in **browser session** — a token cannot mint another\ntoken, so this endpoint rejects personal-access-token (bearer)\nauthentication with `403`. The full secret is returned exactly once in\nthe response. This is the one operation in this API that is **not**\nPAT-eligible; create tokens from the dashboard Settings page, not the\ninteractive playground.\n", "operationId": "createToken", "security": [ { "cookieAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "scopes" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "scopes": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "api:read", "api:write" ] } }, "expiresInDays": { "type": [ "integer", "null" ], "enum": [ 30, 90, 365, null ] } } } } } }, "responses": { "201": { "description": "The new token's secret (shown once) and its record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "record": { "$ref": "#/components/schemas/Token" } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/tokens/{id}": { "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "delete": { "tags": [ "Tokens" ], "summary": "Revoke a personal access token", "description": "Requires `api:write`. Revocation is immediate and cannot be undone.", "operationId": "revokeToken", "responses": { "200": { "description": "The revoked token's record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "record": { "$ref": "#/components/schemas/Token" } } } } } } } } }, "/api/me": { "get": { "tags": [ "Account" ], "summary": "Get your profile", "operationId": "getMe", "responses": { "200": { "description": "Your profile.", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" } } } } } } } }, "patch": { "tags": [ "Account" ], "summary": "Update your profile", "description": "Requires `api:write`.", "operationId": "updateMe", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "company": { "type": "string", "minLength": 1, "maxLength": 120 } } } } } }, "responses": { "200": { "description": "Your updated profile.", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/me/transfers": { "get": { "tags": [ "Account" ], "summary": "List transfers involving you", "operationId": "listMyTransfers", "parameters": [ { "name": "role", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "recipient", "initiator" ] } } ], "responses": { "200": { "description": "Transfers where you are the recipient or initiator.", "content": { "application/json": { "schema": { "type": "object", "properties": { "transfers": { "type": "array", "items": { "type": "object" } } } } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "p4a_", "description": "A personal access token, sent as `Authorization: Bearer p4a_…`." }, "cookieAuth": { "type": "apiKey", "in": "cookie", "name": "sb-access-token", "description": "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." } }, "parameters": { "PathId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The resource's UUID." } }, "responses": { "Ok": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } } } } } }, "BadRequest": { "description": "The request body failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "The token is missing the required scope, or the action is not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "The resource does not exist or is not visible to you.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Conflict": { "description": "The resource is in a state that does not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" } }, "example": { "error": "Not authenticated" } }, "Policy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "status": { "type": "string" }, "liked": { "type": "boolean", "description": "Whether the current viewer has liked this policy. Present on `GET /api/policies/{id}` and reflects the authenticated caller (false for anonymous callers). Folded into the policy payload so the catalog detail page need not make a separate like-state round-trip (#666)." }, "github_has_issues": { "type": "boolean", "nullable": true, "description": "Whether the policy's upstream GitHub repository currently accepts issues, captured at submission/validation time. Drives the \"Report an issue\" affordance on the detail page (#66): a prefilled `/issues/new` handoff is offered unless this is explicitly `false`. `null` means unknown (pre-#66 rows or a repo that couldn't be re-read) and fails open. The live re-check that can correct a tracker disabled after publish is exposed at `GET /api/policies/{id}/issues-enabled`." } }, "example": { "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 } }, "MuleSoftPolicySummary": { "type": "object", "description": "A MuleSoft out-of-the-box (Omni/Flex Gateway) policy as returned by `GET /api/policies?source=mulesoft`. Summary shape — no documentation body; fetch that via `GET /api/mulesoft-policies/{slug}`.", "properties": { "slug": { "type": "string", "description": "Stable identifier from the docs URL." }, "name": { "type": "string" }, "summary": { "type": "string" }, "category": { "type": "string" }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ], "description": "Enforcement leg derived from the policy slug: `outbound` for slugs ending in `-outbound`/`-response`, else `inbound`." }, "first_version": { "type": "string", "nullable": true, "description": "First Omni/Flex Gateway version the policy was available in, if known." }, "doc_url": { "type": "string", "format": "uri", "description": "Canonical docs.mulesoft.com page for the policy." }, "synced_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the row was last synced from docs.mulesoft.com." } }, "example": { "slug": "rate-limiting", "name": "Rate Limiting", "summary": "Monitors access to an API.", "category": "Quality of Service", "direction": "inbound", "first_version": "v1.2.0", "doc_url": "https://docs.mulesoft.com/gateway/latest/policies-included-rate-limiting", "synced_at": "2026-07-08T15:00:00Z" } }, "MuleSoftPolicy": { "allOf": [ { "$ref": "#/components/schemas/MuleSoftPolicySummary" }, { "type": "object", "description": "Full MuleSoft policy including the documentation body rendered on the in-portal detail page.", "properties": { "body_md": { "type": "string", "description": "The policy documentation synced from docs.mulesoft.com — markdown with embedded (sanitizable) HTML tables. Relative doc links are rewritten to absolute docs.mulesoft.com URLs." } } } ] }, "PolicyPatch": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "videoTutorialUrl": { "type": "string" }, "examplesUrl": { "type": "string" }, "githubUrl": { "type": "string", "format": "uri" }, "implementationGithubUrl": { "type": "string" }, "iconUrl": { "type": "string" }, "iconDisabled": { "type": "boolean" } } }, "PolicyRevision": { "type": "object", "description": "An owner-proposed edit to a single published-policy field, pending an administrator's re-review before it goes live.", "properties": { "id": { "type": "string", "format": "uuid" }, "policy_id": { "type": "string", "format": "uuid" }, "field": { "type": "string", "enum": [ "description", "github_url" ] }, "proposed_value": { "type": "string" }, "previous_value": { "type": "string", "nullable": true, "description": "The live value at the time the edit was proposed." }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected" ] }, "feedback": { "type": "string", "nullable": true, "description": "Reviewer note left on approval or rejection." }, "submitted_at": { "type": "string", "format": "date-time" }, "reviewed_at": { "type": "string", "format": "date-time", "nullable": true } } }, "Comment": { "type": "object", "description": "A discussion comment on a policy. Top-level comments have a null `parentId`; single-level replies point at a top-level comment. A soft-deleted comment has `deleted: true` with empty `body` and null `authorId`/`authorName` so its live replies stay intact.", "properties": { "id": { "type": "string", "format": "uuid" }, "policyId": { "type": "string", "format": "uuid" }, "parentId": { "type": "string", "format": "uuid", "nullable": true, "description": "The top-level comment this replies to, or null for a top-level comment." }, "authorId": { "type": "string", "format": "uuid", "nullable": true, "description": "Null on a soft-deleted comment." }, "authorName": { "type": "string", "nullable": true, "description": "The author's display name; null on a soft-deleted comment." }, "body": { "type": "string", "description": "Markdown source. Empty string on a soft-deleted comment." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deleted": { "type": "boolean", "description": "True when the comment has been (soft-)deleted." } }, "example": { "id": "c1d2e3f4-a5b6-7089-90ab-cdef01234567", "policyId": "3f1c2b4a-1e2d-4c3b-9a8f-0d1e2f3a4b5c", "parentId": null, "authorId": "a1b2c3d4-5e6f-7081-92a3-b4c5d6e7f809", "authorName": "Jane Doe", "body": "How do I configure the token bucket size?", "createdAt": "2026-07-02T10:15:00Z", "updatedAt": "2026-07-02T10:15:00Z", "deleted": false } }, "CommentInput": { "type": "object", "required": [ "body" ], "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 10000, "description": "Markdown source of the comment." }, "parentId": { "type": "string", "format": "uuid", "description": "Optional. The id of the top-level comment to reply to. Omit for a top-level comment. Replies are limited to a single level." } } }, "Submission": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string" }, "githubUrl": { "type": "string", "format": "uri" } }, "example": { "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" } }, "SubmissionInput": { "type": "object", "required": [ "name", "description", "githubUrl" ], "properties": { "projectType": { "type": "string", "enum": [ "unified", "split" ] }, "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "description": { "type": "string", "minLength": 10, "maxLength": 20000 }, "githubUrl": { "type": "string", "format": "uri" }, "implementationGithubUrl": { "type": "string", "format": "uri", "description": "Required when `projectType` is `split`." }, "category": { "type": "string" }, "videoTutorialUrl": { "type": "string" }, "examplesUrl": { "type": "string" }, "iconUrl": { "type": "string" }, "iconDisabled": { "type": "boolean" }, "deliversIdeaId": { "type": "string", "format": "uuid", "description": "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." } }, "example": { "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" } }, "Deployment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "policy_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "anypoint_org_id": { "type": "string" }, "definition_asset_version": { "type": [ "string", "null" ], "description": "Version the definition asset was published at. Distinct from the implementation peer only for split-model policies." }, "implementation_asset_version": { "type": [ "string", "null" ], "description": "Version the implementation asset was published at." }, "home_doc_status": { "type": [ "string", "null" ], "enum": [ "published", "skipped", "failed", null ], "description": "Outcome of the best-effort documentation page published to the\nExchange asset after a successful deploy. `failed` means the deploy\nsucceeded but the Exchange listing carries no docs page. `null` =\nnot attempted (legacy or simulated deploys).\n" } } }, "DeploymentResult": { "type": "object", "description": "One per-target outcome from a fan-out enqueue. On a timed-out request\nthe deployment may still have been queued — poll `GET /api/deployments`\nwith the returned `deployment.id` before retrying. A retry of the same\ntarget within ~5 minutes is de-duplicated: it returns the original\ndeployment (with `deployment.deduped: true`) instead of queuing a\nduplicate.\n", "properties": { "ok": { "type": "boolean" }, "organizationId": { "type": "string" }, "organizationName": { "type": [ "string", "null" ] }, "error": { "type": "string", "description": "Set when this target failed to enqueue." }, "deployment": { "type": "object", "description": "The queued (or de-duplicated) deployment row; absent on a failed target.", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "deduped": { "type": "boolean", "description": "True when an in-window retry matched an existing deployment instead of creating a new one." } } } } }, "DeploymentInput": { "type": "object", "required": [ "policyId", "connectionId", "workspaceId", "targetOrganizationIds" ], "properties": { "policyId": { "type": "string", "format": "uuid" }, "connectionId": { "type": "string", "format": "uuid" }, "workspaceId": { "type": "string", "format": "uuid" }, "targetOrganizationIds": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string" } }, "doPublish": { "type": "boolean" }, "doRelease": { "type": "boolean" }, "cleanupDev": { "type": "boolean" }, "ref": { "type": "string" }, "implementationRef": { "type": "string" } }, "example": { "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 } }, "Connection": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "host": { "type": "string", "enum": [ "us", "eu", "custom" ] }, "client_id": { "type": "string", "description": "Masked; the secret is never returned." }, "organization_id": { "type": "string" } }, "example": { "id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d", "name": "Acme production", "host": "us", "client_id": "abcd…", "organization_id": "a0000000-0000-0000-0000-000000000001" } }, "ConnectionCredentials": { "type": "object", "required": [ "host", "clientId", "clientSecret", "organizationId" ], "properties": { "host": { "type": "string", "enum": [ "us", "eu", "custom" ] }, "customDomain": { "type": [ "string", "null" ], "format": "uri" }, "clientId": { "type": "string", "minLength": 4 }, "clientSecret": { "type": "string", "minLength": 4 }, "organizationId": { "type": "string", "minLength": 4 } } }, "ConnectionInput": { "allOf": [ { "$ref": "#/components/schemas/ConnectionCredentials" }, { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 80 } } } ], "example": { "name": "Acme production", "host": "us", "clientId": "1234abcd", "clientSecret": "s3cr3t-value", "organizationId": "a0000000-0000-0000-0000-000000000001" } }, "ConnectionPatch": { "type": "object", "description": "Credential fields (clientId, clientSecret, organizationId) are all-or-none.", "properties": { "name": { "type": "string" }, "host": { "type": "string", "enum": [ "us", "eu", "custom" ] }, "customDomain": { "type": [ "string", "null" ], "format": "uri" }, "clientId": { "type": "string", "minLength": 4 }, "clientSecret": { "type": "string", "minLength": 4 }, "organizationId": { "type": "string", "minLength": 4 } } }, "AnypointOrg": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "isPrimary": { "type": "boolean" }, "fullPath": { "type": "string" } } }, "Workspace": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "example": { "id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210", "name": "Platform team", "slug": "platform-team" } }, "Token": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "token_prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "api:read", "api:write" ] } }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "example": { "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" } }, "User": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "company": { "type": [ "string", "null" ] }, "is_admin": { "type": "boolean" } }, "example": { "id": "deadbeef-0000-1111-2222-333344445555", "email": "you@example.com", "company": "Acme", "is_admin": false } } } } }