{"openapi":"3.1.0","info":{"title":"Axoniq Platform API","description":"\nManage an Axoniq Platform workspace over HTTP: its environments, access tokens, users and projects.\n\n## Authentication\n\nSend an access token with the *API access* option on every request as\n`Authorization: Bearer <workspaceId>:<token>`. The workspace id travels in the credential, so no endpoint takes it\nas a parameter. Every operation below states the role it needs.\n\nHow to issue a token, what the scopes and roles allow, and what each error status means are in the\n[REST API guide](https://docs.axoniq.io/axoniq-platform-reference/rest-api/).\n","contact":{"name":"Axoniq","url":"https://www.axoniq.io"},"version":"v1"},"servers":[{"url":"https://platform.axoniq.io/api","description":"This Platform deployment"}],"security":[{"accessToken":[]}],"tags":[{"name":"Environments","description":"A workspace's environments and their Axon Server nodes"},{"name":"Licenses","description":"An environment's Axon Server license"},{"name":"Access Tokens","description":"A workspace's access tokens"},{"name":"Users","description":"A workspace's users"},{"name":"Projects","description":"A workspace's Build projects"}],"paths":{"/v1/environments":{"get":{"tags":["Environments"],"summary":"List a workspace's environments","description":"Requires the `viewer` role on the workspace: an `api:workspace:viewer` (or higher) token. An `api:environment:*` token is refused (401): it only reaches the endpoints of its own environment.","operationId":"environments","responses":{"200":{"description":"The workspace's environments","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentSummaryListDto"}}}},"401":{"description":"Missing, invalid, or insufficiently scoped access token"},"404":{"description":"The workspace was removed after the token was checked"},"502":{"description":"The upstream query failed"},"504":{"description":"The upstream query did not respond in time"}}},"post":{"tags":["Environments"],"summary":"Create an environment","description":"Requires the `admin` role on the workspace: an `api:workspace:admin` (or higher) token. Subject to the workspace's environment limits, in total and per type. Not idempotent: after a 504 or a 502 the environment may still have been created, so list the environments before retrying.","operationId":"create","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEnvironmentRequestDto"}}},"required":true},"responses":{"201":{"description":"The new environment's id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedEnvironmentDto"}}}},"400":{"description":"A blank name, an unknown type, or a workspace limit that is already reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorDto"}}}},"401":{"description":"Missing, invalid, or insufficiently scoped access token"},"502":{"description":"The upstream command failed"},"504":{"description":"The upstream command did not respond in time"}}}},"/v1/access-tokens":{"get":{"tags":["Access Tokens"],"summary":"List a workspace's access tokens","description":"Requires the `viewer` role on the workspace: an `api:workspace:viewer` (or higher) token. Never includes a token's secret value.","operationId":"accessTokens","responses":{"200":{"description":"The workspace's access tokens","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessTokenSummaryListDto"}}}},"401":{"description":"Missing, invalid, or insufficiently scoped access token"},"502":{"description":"The upstream query failed"},"504":{"description":"The upstream query did not respond in time"}}},"post":{"tags":["Access Tokens"],"summary":"Issue a new access token","description":"Requires the `admin` role on the workspace: an `api:workspace:admin` (or higher) token. A token can never be issued with a higher `api:*` role than the caller's own resolved role. The plaintext secret is returned once, in this response, and only stored encrypted thereafter if `revealMode` allows a later reveal.","operationId":"issue","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssueAccessTokenRequestDto"}}},"required":true},"responses":{"201":{"description":"The new token's id and plaintext secret","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssuedAccessTokenDto"}}}},"400":{"description":"An environment that doesn't belong to the workspace, an unrecognized scope, or a scope requesting a higher role than the caller holds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorDto"}}}},"401":{"description":"Missing, invalid, or insufficiently scoped access token"},"502":{"description":"The upstream command failed"},"504":{"description":"The upstream command did not respond in time"}}}},"/v1/access-tokens/{tokenId}/reveal":{"post":{"tags":["Access Tokens"],"summary":"Reveal an access token's secret","description":"Requires the `user` role on the workspace: an `api:workspace:user` (or higher) token. Only succeeds if the target token's own reveal mode allows it for the caller (`ADMIN_REVEALABLE` needs an admin, `USER_REVEALABLE` a user or higher, `NOT_REVEALABLE` is never revealed; see `revealMode` on the list endpoint), the caller holds at least the highest `api:` role the target token grants, and the token has not expired. Recorded in the token's access log under the `API` context, same as any other reveal.","operationId":"reveal","parameters":[{"name":"tokenId","in":"path","description":"The access token's id, as listed by `GET /v1/access-tokens`.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The token's secret","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevealedAccessTokenDto"}}}},"400":{"description":"The token cannot be revealed: not found, expired, not revealable, the caller isn't permitted by its reveal mode, or the target token's own scope grants a higher role than the caller holds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorDto"}}}},"401":{"description":"Missing, invalid, or insufficiently scoped access token"},"502":{"description":"The upstream command failed"},"504":{"description":"The upstream command did not respond in time"}}}},"/v1/access-tokens/{tokenId}":{"delete":{"tags":["Access Tokens"],"summary":"Revoke an access token","description":"Requires the `admin` role on the workspace: an `api:workspace:admin` (or higher) token. Idempotent: revoking an already-revoked or nonexistent token id succeeds without error.","operationId":"revoke","parameters":[{"name":"tokenId","in":"path","description":"The access token's id, as listed by `GET /v1/access-tokens`.","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"The token was revoked"},"401":{"description":"Missing, invalid, or insufficiently scoped access token"},"502":{"description":"The upstream command failed"},"504":{"description":"The upstream command did not respond in time"}}},"patch":{"tags":["Access Tokens"],"summary":"Rename an access token","description":"Requires the `admin` role on the workspace: an `api:workspace:admin` (or higher) token.","operationId":"rename","parameters":[{"name":"tokenId","in":"path","description":"The access token's id, as listed by `GET /v1/access-tokens`.","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenameAccessTokenRequestDto"}}},"required":true},"responses":{"204":{"description":"The token was renamed"},"400":{"description":"No such token in the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorDto"}}}},"401":{"description":"Missing, invalid, or insufficiently scoped access token"},"502":{"description":"The upstream command failed"},"504":{"description":"The upstream command did not respond in time"}}}},"/v1/users":{"get":{"tags":["Users"],"summary":"List a workspace's users","description":"Requires the `viewer` role on the workspace: an `api:workspace:viewer` (or higher) token.","operationId":"users","responses":{"200":{"description":"The workspace's users","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceUserSummaryListDto"}}}},"401":{"description":"Missing, invalid, or insufficiently scoped access token"},"404":{"description":"The workspace was removed after the token was checked"},"502":{"description":"The upstream query failed"},"504":{"description":"The upstream query did not respond in time"}}}},"/v1/projects":{"get":{"tags":["Projects"],"summary":"List a workspace's Build projects","description":"Requires the `viewer` role on the workspace: an `api:workspace:viewer` (or higher) token.","operationId":"projects","responses":{"200":{"description":"The workspace's projects","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectSummaryListDto"}}}},"401":{"description":"Missing, invalid, or insufficiently scoped access token"},"502":{"description":"The upstream query failed"},"504":{"description":"The upstream query did not respond in time"}}}},"/v1/environments/{environmentId}/nodes":{"get":{"tags":["Environments"],"summary":"List the nodes of an environment's Axon Server cluster","description":"Requires the `viewer` role on the environment: an `api:environment:viewer` (or higher) token that includes it, or an `api:workspace:viewer` (or higher) token. The nodes are the cluster's members and anything connected right now; `online` is the rule that decides whether a node can be removed.","operationId":"nodes","parameters":[{"name":"environmentId","in":"path","description":"The environment's identifier, as listed by `GET /v1/environments`.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The cluster's nodes, oldest member first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentNodeListDto"}}}},"401":{"description":"Missing, invalid, or insufficiently scoped access token, or an unknown environment"},"404":{"description":"The environment was removed after the token was checked; an id that never existed, or belongs to another workspace, answers 401"},"502":{"description":"The upstream query failed"},"504":{"description":"The upstream query did not respond in time"}}}},"/v1/environments/{environmentId}/license":{"get":{"tags":["Licenses"],"summary":"Download an environment's license","description":"Requires the `viewer` role on the environment: an `api:environment:viewer` (or higher) token that includes it, or an `api:workspace:viewer` (or higher) token. The license is a secret, so the response carries `Cache-Control: no-store`.","operationId":"license","parameters":[{"name":"environmentId","in":"path","description":"The environment's identifier, as listed by `GET /v1/environments`.","required":true,"schema":{"type":"string"}},{"name":"version","in":"query","description":"The license format, V1 or V2 in either case; omit for V2, falling back to V1.","required":false,"schema":{"type":"string","enum":["V1","V2"]}}],"responses":{"200":{"description":"The license","headers":{"Cache-Control":{"description":"`no-store`: the license is a secret","style":"simple"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LicenseDto"}}}},"400":{"description":"An unknown license version (V1 and V2 are known)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorDto"}}}},"401":{"description":"Missing, invalid, or insufficiently scoped access token, or an unknown environment"},"404":{"description":"The environment has no license in the requested format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorDto"}}}},"502":{"description":"The upstream query failed"},"504":{"description":"The upstream query did not respond in time"}}}},"/v1/environments/{environmentId}":{"delete":{"tags":["Environments"],"summary":"Delete an environment","description":"Requires the `admin` role on the environment: an `api:environment:admin` (or higher) token that includes it, or an `api:workspace:admin` (or higher) token. Refused while the environment has active connections and for the workspace's last environment. The connection check is made just before the delete, so an application that connects in between is not caught. Everything configured on the environment goes with it.","operationId":"delete","parameters":[{"name":"environmentId","in":"path","description":"The environment's identifier, as listed by `GET /v1/environments`.","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"The environment was deleted"},"400":{"description":"The environment cannot be deleted: it has a subscription or an enterprise license","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorDto"}}}},"401":{"description":"Missing, invalid, or insufficiently scoped access token, or an unknown environment"},"404":{"description":"The environment was removed after the token was checked; an id that never existed, or belongs to another workspace, answers 401"},"409":{"description":"The environment has active connections, or is the workspace's last environment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorDto"}}}},"502":{"description":"The upstream query or command failed; nothing is deleted when the connections cannot be checked"},"504":{"description":"The upstream query or command did not respond in time"}}}},"/v1/environments/{environmentId}/nodes/{nodeName}":{"delete":{"tags":["Environments"],"summary":"Remove a node from an environment's Axon Server cluster","description":"Requires the `user` (Developer) role on the environment: an `api:environment:user` (or higher) token that includes it, or an `api:workspace:user` (or higher) token. A node that is still online cannot be removed: stop it first. The check is made just before the removal, so a node that comes online in between is refused with 400. Node names are listed by `GET /v1/environments/{environmentId}/nodes`.","operationId":"removeNode","parameters":[{"name":"environmentId","in":"path","description":"The environment's identifier, as listed by `GET /v1/environments`.","required":true,"schema":{"type":"string"}},{"name":"nodeName","in":"path","description":"The node's name, as the Axon Server cluster knows it.","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"The node is no longer a member of the cluster"},"400":{"description":"The removal was refused, for example because the node came online in the meantime","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorDto"}}}},"401":{"description":"Missing, invalid, or insufficiently scoped access token, or an unknown environment"},"404":{"description":"No such node in the environment; an unknown or foreign environment id answers 401"},"409":{"description":"The node is online","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorDto"}}}},"502":{"description":"The upstream query or command failed; nothing is removed when the connections cannot be checked"},"504":{"description":"The upstream query or command did not respond in time"}}}}},"components":{"schemas":{"CreateEnvironmentRequestDto":{"type":"object","description":"Request body for creating an environment.","properties":{"name":{"type":"string","description":"The environment's display name.","example":"Staging","maxLength":30,"minLength":0},"type":{"type":["string","null"],"description":"The environment's type; omit for DEVELOPMENT.","enum":["DEVELOPMENT","PRE_PRODUCTION","PRODUCTION"],"example":"PRE_PRODUCTION"}},"required":["name"]},"ApiErrorDto":{"type":"object","description":"Why a request was rejected.","properties":{"message":{"type":"string","description":"A message for the caller explaining the rejection.","example":"Unknown scope 'api:team:viewer'."}},"required":["message"]},"CreatedEnvironmentDto":{"type":"object","description":"The newly created environment.","properties":{"identifier":{"type":"string","description":"The new environment's id.","example":"9f3c2a71-2"}},"required":["identifier"]},"IssueAccessTokenRequestDto":{"type":"object","description":"Request body for issuing a new access token.","properties":{"name":{"type":"string","description":"The token's display name.","example":"CI pipeline","minLength":1},"scopes":{"type":"array","description":"The scopes granted to this token, shaped `api:<resource>:<role>`. Cannot exceed the caller's own resolved role.","example":["api:environment:viewer"],"items":{"type":"string"},"minItems":1},"environments":{"type":"array","description":"Environments the token applies to (for environment-applicable scopes); workspace-wide scopes ignore it. Empty means all environments of the workspace.","example":["9f3c2a71-0"],"items":{"type":"string"}},"expiresAt":{"type":["string","null"],"format":"date-time","description":"When the token expires; omit for a token that never expires.","example":"2027-11-01T10:00:00Z"},"revealMode":{"type":"string","description":"Whether/by whom the secret can be revealed later. NOT_REVEALABLE never stores the secret.","enum":["ADMIN_REVEALABLE","USER_REVEALABLE","NOT_REVEALABLE"]}},"required":["environments","name","revealMode","scopes"]},"IssuedAccessTokenDto":{"type":"object","description":"A newly issued token's id and plaintext secret. The secret is returned once, here, and never again unless the token's reveal mode allows a later reveal.","properties":{"tokenId":{"type":"string","description":"The new token's id.","example":"c41d7e08"},"secret":{"type":"string","description":"The new token's plaintext secret.","example":"0f8e1c2a4b6d4e9fa3b7c5d1e2f60817"}},"required":["secret","tokenId"]},"RevealedAccessTokenDto":{"type":"object","description":"A token's decrypted secret, returned on demand by the reveal endpoint.","properties":{"tokenId":{"type":"string","description":"The token's id.","example":"c41d7e08"},"secret":{"type":"string","description":"The token's plaintext secret.","example":"0f8e1c2a4b6d4e9fa3b7c5d1e2f60817"}},"required":["secret","tokenId"]},"RenameAccessTokenRequestDto":{"type":"object","description":"Request body for renaming an access token.","properties":{"name":{"type":"string","description":"The token's new display name.","example":"CI pipeline (renamed)","minLength":1}},"required":["name"]},"WorkspaceUserSummaryDto":{"type":"object","description":"A user of the workspace.","properties":{"email":{"type":"string","description":"The user's email address.","example":"sam@acme.example"},"role":{"type":"string","description":"The user's role in the workspace.","example":"ADMIN"},"blocked":{"type":"boolean","description":"Whether the user is blocked from signing in.","example":false}},"required":["blocked","email","role"]},"WorkspaceUserSummaryListDto":{"type":"object","description":"A workspace's users.","properties":{"users":{"type":"array","description":"The workspace's users.","items":{"$ref":"#/components/schemas/WorkspaceUserSummaryDto"}}},"required":["users"]},"ProjectSummaryDto":{"type":"object","description":"A Build project in the workspace.","properties":{"id":{"type":"string","description":"The project's id.","example":"7c9e6679-7425-40de-944b-e07fc1f90ae7"},"workspaceId":{"type":"string","description":"The workspace the project belongs to.","example":"9f3c2a71"},"name":{"type":"string","description":"The project's name.","example":"Order management"},"description":{"type":["string","null"],"description":"What the project builds; absent when none was given.","example":"Handles orders and invoicing."},"icon":{"type":["string","null"],"description":"The project's icon; absent when none was chosen.","example":"mdi-cart"},"model":{"type":"string","description":"The AI model the project uses, by enum name.","example":"CLAUDE_SONNET_4_6"},"stage":{"type":"string","description":"How far the project has come: requirements through to code.","enum":["JOURNEYS","COMPONENTS","CODE","COMPLETED"],"example":"COMPONENTS"},"createdAt":{"type":"string","format":"date-time","description":"When the project was created.","example":"2026-10-01T09:30:00Z"},"updatedAt":{"type":["string","null"],"format":"date-time","description":"When the project last changed; absent if it never has.","example":"2026-10-12T14:05:00Z"},"visibility":{"type":"string","description":"Who can see the project.","enum":["PUBLIC","PRIVATE"],"example":"PRIVATE"},"starCount":{"type":"integer","format":"int32","description":"How many users starred the project.","example":3},"duplicateCount":{"type":"integer","format":"int32","description":"How many times the project was duplicated.","example":1}},"required":["createdAt","duplicateCount","id","model","name","stage","starCount","visibility","workspaceId"]},"ProjectSummaryListDto":{"type":"object","description":"A workspace's projects.","properties":{"projects":{"type":"array","description":"The workspace's projects.","items":{"$ref":"#/components/schemas/ProjectSummaryDto"}}},"required":["projects"]},"EnvironmentSummaryDto":{"type":"object","description":"An environment of the workspace.","properties":{"identifier":{"type":"string","description":"The environment's id; use it in the environment paths.","example":"9f3c2a71-0"},"name":{"type":"string","description":"The environment's display name.","example":"Production"},"type":{"type":"string","description":"The environment's type.","enum":["DEVELOPMENT","PRE_PRODUCTION","PRODUCTION"],"example":"PRODUCTION"}},"required":["identifier","name","type"]},"EnvironmentSummaryListDto":{"type":"object","description":"A workspace's environments.","properties":{"environments":{"type":"array","description":"The workspace's environments.","items":{"$ref":"#/components/schemas/EnvironmentSummaryDto"}}},"required":["environments"]},"EnvironmentNodeDto":{"type":"object","description":"A node of an environment's Axon Server cluster.","properties":{"name":{"type":"string","description":"The node's name; use it to remove the node.","example":"axonserver-0"},"hostname":{"type":["string","null"],"description":"The host the node registered with; absent for a node that is connected but has not registered.","example":"axonserver-0.axonserver.svc"},"online":{"type":"boolean","description":"Whether the node is connected right now. An online node cannot be removed.","example":true}},"required":["name","online"]},"EnvironmentNodeListDto":{"type":"object","description":"The nodes of an environment's Axon Server cluster.","properties":{"nodes":{"type":"array","description":"The cluster's nodes.","items":{"$ref":"#/components/schemas/EnvironmentNodeDto"}}},"required":["nodes"]},"LicenseDto":{"type":"object","description":"An environment's Axon Server license.","properties":{"active":{"type":"boolean","description":"Whether the license is currently active.","example":true},"content":{"type":"string","description":"The license file's content.","example":"-----BEGIN LICENSE-----..."},"filename":{"type":"string","description":"The file name to save the license under.","example":"axoniq_9f3c2a71-0.license"}},"required":["active","content","filename"]},"AccessTokenSummaryDto":{"type":"object","description":"A workspace access token's public metadata. Never includes the token's secret value.","properties":{"tokenId":{"type":"string","description":"The token's id.","example":"c41d7e08"},"name":{"type":"string","description":"The token's display name.","example":"CI pipeline"},"prefix":{"type":"string","description":"The token's non-secret leading fragment, for identifying it in lists.","example":"0f8e1c2a"},"scopes":{"type":"array","description":"The scopes granted to this token, shaped `api:<resource>:<role>`.","example":["api:environment:viewer"],"items":{"type":"string"}},"environments":{"type":"array","description":"Environments the token applies to; empty means all environments.","example":["9f3c2a71-0"],"items":{"type":"string"}},"issuedAt":{"type":["string","null"],"format":"date-time","description":"When the token was issued.","example":"2026-11-01T10:00:00Z"},"expiresAt":{"type":["string","null"],"format":"date-time","description":"When the token expires; null means it never expires.","example":"2027-11-01T10:00:00Z"},"lastShownAt":{"type":["string","null"],"format":"date-time","description":"When the secret was last revealed/copied; null if never since issue.","example":"2026-11-02T08:15:00Z"},"lastUsedAt":{"type":["string","null"],"format":"date-time","description":"When the token was last used to authenticate; null if never used.","example":"2026-11-05T17:40:00Z"},"lastUsedScope":{"type":["string","null"],"description":"The scope the token was last used for, if known.","example":"api:environment:viewer"},"revealMode":{"type":"string","description":"Whether the secret can be revealed after issue, and by whom.","enum":["ADMIN_REVEALABLE","USER_REVEALABLE","NOT_REVEALABLE"],"example":"ADMIN_REVEALABLE"},"revealableBy":{"type":["string","null"],"description":"The minimum role required to reveal this token's secret; null means never.","enum":["VIEWER","USER","ADMIN","OWNER"]}},"required":["environments","name","prefix","revealMode","scopes","tokenId"]},"AccessTokenSummaryListDto":{"type":"object","description":"A workspace's access tokens.","properties":{"tokens":{"type":"array","description":"The workspace's access tokens.","items":{"$ref":"#/components/schemas/AccessTokenSummaryDto"}}},"required":["tokens"]}},"securitySchemes":{"accessToken":{"type":"http","description":"A workspace access token, sent as `workspaceId:token`, carrying an `api:` scope.","scheme":"bearer"}}}}