{ "openapi": "3.0.3", "info": { "title": "GoRules BRMS", "version": "local" }, "servers": [ { "url": "https://acme.us1.gorules.io", "description": "Your organisation URL" } ], "components": { "securitySchemes": { "projectAccessToken": { "type": "apiKey", "in": "header", "name": "X-Access-Token", "description": "Project access token is obtained within project settings" }, "personalAccessToken": { "type": "http", "scheme": "bearer", "description": "Personal access token is obtained through your profile" }, "internalAuth": { "type": "http", "scheme": "internal", "description": "Cannot be used directly" } } }, "paths": { "/api/invitations": { "get": { "operationId": "listInvitations", "summary": "List invitations", "tags": [ "Invitation" ], "description": "Retrieve a paginated list of invitations for the organisation with optional filtering by search term and status.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "search", "description": "Search term to filter invitations by email" }, { "schema": { "type": "string", "enum": [ "pending", "accepted" ] }, "in": "query", "name": "status", "description": "Filter invitations by status" }, { "schema": { "type": "number", "default": 1 }, "in": "query", "name": "page", "description": "Current page" }, { "schema": { "type": "number", "default": 10 }, "in": "query", "name": "perPage", "description": "Number of items per page" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Paginated list of invitations", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the invitation" }, "email": { "type": "string", "format": "email", "description": "Email address the invitation was sent to" }, "expiresAt": { "type": "string", "nullable": true, "description": "Expiration date of the invitation" }, "createdAt": { "type": "string", "description": "Timestamp when the invitation was created" }, "acceptedAt": { "type": "string", "nullable": true, "description": "Timestamp when the invitation was accepted" }, "status": { "type": "string", "enum": [ "pending", "accepted" ], "description": "Current status of the invitation" }, "createdBy": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the user" }, "email": { "type": "string", "format": "email", "description": "Email address of the user" }, "firstName": { "type": "string", "nullable": true, "description": "First name of the user" }, "lastName": { "type": "string", "nullable": true, "description": "Last name of the user" }, "type": { "type": "string", "enum": [ "invited", "member", "author", "admin", "owner" ], "description": "Type of user (e.g., admin, member)" }, "status": { "type": "string", "enum": [ "active", "disabled", "locked" ], "description": "Current status of the user" } }, "required": [ "id", "email", "firstName", "lastName", "type", "status" ], "description": "User who created the invitation" }, "user": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the user" }, "email": { "type": "string", "format": "email", "description": "Email address of the user" }, "firstName": { "type": "string", "nullable": true, "description": "First name of the user" }, "lastName": { "type": "string", "nullable": true, "description": "Last name of the user" }, "type": { "type": "string", "enum": [ "invited", "member", "author", "admin", "owner" ], "description": "Type of user (e.g., admin, member)" }, "status": { "type": "string", "enum": [ "active", "disabled", "locked" ], "description": "Current status of the user" } }, "required": [ "id", "email", "firstName", "lastName", "type", "status" ], "description": "User the invitation is for" }, "organisation": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the organisation" }, "name": { "type": "string", "description": "Name of the organisation" } }, "required": [ "id", "name" ], "description": "Organisation the invitation belongs to" } }, "required": [ "id", "email", "expiresAt", "createdAt", "acceptedAt", "status" ] }, "description": "List of invitations" }, "paginate": { "type": "object", "properties": { "current": { "type": "number", "description": "Current page number" }, "from": { "type": "number", "description": "Starting record number on the current page" }, "to": { "type": "number", "description": "Ending record number on the current page" }, "total": { "type": "number", "description": "Total number of records" }, "pageSize": { "type": "number", "description": "Number of records per page" } }, "required": [ "current", "from", "to", "total", "pageSize" ], "description": "Pagination metadata" } }, "required": [ "results", "paginate" ], "description": "Paginated list of invitations" } } } } } } }, "/api/organisations": { "put": { "operationId": "updateOrganisation", "summary": "Update the organisation", "tags": [ "Organisation" ], "description": "Updates the organisation name, display name, and preferences.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "URL-safe name of the organisation" }, "displayName": { "type": "string", "description": "Display name of the organisation" }, "preferences": { "type": "object", "properties": { "themeLogo": { "type": "string", "description": "URL or path to the organisation logo" }, "themePrimaryColor": { "type": "string", "description": "Primary theme color for the organisation" }, "emailSignupDomains": { "type": "string", "description": "Comma separated list", "example": "@gorules.io, @gorules.dev" } }, "default": {}, "description": "Organisation preferences to update" } } } } } }, "security": [ { "internalAuth": [] } ], "responses": { "200": { "description": "The updated organisation", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the organisation" }, "name": { "type": "string", "description": "URL-safe name of the organisation" }, "displayName": { "type": "string", "description": "Display name of the organisation" }, "onboarded": { "type": "boolean", "description": "Whether the organisation has completed onboarding" }, "license": { "type": "string", "description": "License key" }, "licenseData": { "type": "object", "properties": { "kind": { "type": "string", "nullable": true, "enum": [ "online", "offline", null ], "description": "License kind (online or offline)" }, "createdAt": { "type": "string", "nullable": true, "description": "Date the license was created" }, "expiresAt": { "type": "string", "nullable": true, "description": "Date the license expires" }, "environmentState": { "type": "string", "enum": [ "initial", "connected", "disabled" ], "description": "Current environment state" }, "organisationStatus": { "type": "string", "enum": [ "active", "disabled", "invalid", "grace", "expired" ], "description": "Current organisation license status" }, "environmentLimits": { "type": "object", "properties": { "users": { "type": "number", "description": "Maximum number of users allowed" }, "projects": { "type": "number", "description": "Maximum number of projects allowed" }, "documents": { "type": "number", "description": "Maximum number of documents allowed" }, "deployments": { "type": "number", "description": "Maximum number of deployments allowed" }, "enableDeploymentsWorkflows": { "type": "boolean", "description": "Whether deployment workflows are enabled" }, "enableSSO": { "type": "boolean", "description": "Whether SSO is enabled" }, "enableAuditLogs": { "type": "boolean", "description": "Whether audit logs are enabled" }, "enableBranding": { "type": "boolean", "description": "Whether custom branding is enabled" }, "evaluateByRelease": { "type": "boolean", "description": "Whether evaluate by release is enabled" }, "diffModel": { "type": "boolean", "description": "Whether model diffing is enabled" }, "diffRelease": { "type": "boolean", "description": "Whether release diffing is enabled" }, "activeSimulation": { "type": "boolean", "description": "Whether active simulation is enabled" }, "testEventsShared": { "type": "boolean", "description": "Whether test events sharing is enabled" }, "enableLLM": { "type": "boolean", "description": "Whether LLM features are enabled" }, "enableRoles": { "type": "boolean", "description": "Whether roles are enabled" } }, "description": "Environment feature limits and flags" } }, "required": [ "environmentState", "organisationStatus" ], "description": "Decoded license data" }, "url": { "type": "string", "description": "URL of the organisation" }, "themeLogo": { "type": "string", "description": "Theme logo URL" }, "themePrimaryColor": { "type": "string", "description": "Theme primary color" }, "preferences": { "type": "object", "properties": { "emailSignupDomains": { "type": "string", "description": "Comma-separated list of email signup domains" }, "themePrimaryColor": { "type": "string", "description": "Primary theme color for the organisation" }, "themeLogo": { "type": "string", "description": "URL or path to the organisation logo" } }, "description": "Organisation preferences" }, "createdAt": { "type": "string", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "description": "Last update timestamp" }, "deletedAt": { "type": "string", "description": "Deletion timestamp if soft-deleted" } }, "required": [ "id", "name", "displayName", "onboarded", "themeLogo", "themePrimaryColor", "preferences", "createdAt", "updatedAt" ], "description": "The updated organisation" } } } } } } }, "/api/users": { "get": { "operationId": "listUsers", "summary": "List users", "tags": [ "User" ], "description": "Retrieves a paginated list of users in the organisation with optional filtering by service account type and search term.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "isService", "description": "Filter by service account status (true/false)" }, { "schema": { "type": "string" }, "in": "query", "name": "search", "description": "Search term to filter users by email, first name, or last name" }, { "schema": { "type": "number", "default": 1 }, "in": "query", "name": "page", "description": "Current page" }, { "schema": { "type": "number", "default": 10 }, "in": "query", "name": "perPage", "description": "Number of items per page" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Paginated list of users", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the user" }, "email": { "type": "string", "format": "email", "description": "Email address of the user" }, "firstName": { "type": "string", "nullable": true, "description": "First name of the user" }, "lastName": { "type": "string", "nullable": true, "description": "Last name of the user" }, "type": { "type": "string", "enum": [ "invited", "member", "author", "admin", "owner" ], "description": "User type/role within the organisation" }, "status": { "type": "string", "enum": [ "active", "disabled", "locked" ], "description": "Current status of the user account" }, "isService": { "type": "boolean", "description": "Whether this is a service account" }, "roles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the role" }, "name": { "type": "string", "description": "Name of the role" }, "description": { "type": "string", "nullable": true, "description": "Description of the role" } }, "required": [ "id", "name" ] }, "description": "Roles assigned to the user" }, "createdAt": { "type": "string", "description": "Timestamp when the user was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the user was last updated" } }, "required": [ "id", "email", "type", "status", "createdAt", "updatedAt" ] }, "description": "List of users" }, "paginate": { "type": "object", "properties": { "current": { "type": "number", "description": "Current page number" }, "from": { "type": "number", "description": "Starting record number" }, "to": { "type": "number", "description": "Ending record number" }, "total": { "type": "number", "description": "Total number of records" }, "pageSize": { "type": "number", "description": "Number of records per page" } }, "required": [ "current", "from", "to", "total", "pageSize" ], "description": "Pagination metadata" } }, "required": [ "results", "paginate" ], "description": "Paginated list of users" } } } } } }, "post": { "operationId": "inviteUsers", "summary": "Invite users", "tags": [ "User" ], "description": "Sends invitation emails to the specified email addresses to join the organisation.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "emails": { "type": "array", "items": { "type": "string", "format": "email", "description": "Email address to invite" }, "description": "List of email addresses to invite (max 10)" } }, "required": [ "emails" ] } } }, "required": true }, "security": [ { "internalAuth": [] } ], "responses": { "200": { "description": "List of created invitations", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the invitation" }, "email": { "type": "string", "format": "email", "description": "Email address the invitation was sent to" }, "status": { "type": "string", "enum": [ "pending", "accepted" ], "description": "Current status of the invitation" }, "userId": { "type": "string", "format": "uuid", "description": "ID of the user associated with this invitation" }, "createdAt": { "type": "string", "description": "Timestamp when the invitation was created" }, "expiresAt": { "type": "string", "nullable": true, "description": "Timestamp when the invitation expires" } }, "required": [ "id", "email", "status", "userId", "createdAt" ] }, "description": "List of created invitations" } } } } } } }, "/api/users/service": { "post": { "operationId": "createServiceAccount", "summary": "Create service account", "tags": [ "User" ], "description": "Creates a new service account user with the specified email and user type.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address for the service account" }, "type": { "type": "string", "enum": [ "admin", "member" ], "default": "member", "description": "User type for the service account" } }, "required": [ "email" ] } } }, "required": true }, "security": [ { "internalAuth": [] } ], "responses": { "200": { "description": "The created service account user", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the user" }, "email": { "type": "string", "format": "email", "description": "Email address of the user" }, "firstName": { "type": "string", "nullable": true, "description": "First name of the user" }, "lastName": { "type": "string", "nullable": true, "description": "Last name of the user" }, "type": { "type": "string", "enum": [ "invited", "member", "author", "admin", "owner" ], "description": "User type/role within the organisation" }, "status": { "type": "string", "enum": [ "active", "disabled", "locked" ], "description": "Current status of the user account" }, "isService": { "type": "boolean", "description": "Whether this is a service account" }, "roles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the role" }, "name": { "type": "string", "description": "Name of the role" }, "description": { "type": "string", "nullable": true, "description": "Description of the role" } }, "required": [ "id", "name" ] }, "description": "Roles assigned to the user" }, "createdAt": { "type": "string", "description": "Timestamp when the user was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the user was last updated" } }, "required": [ "id", "email", "type", "status", "createdAt", "updatedAt" ], "description": "The created service account user" } } } } } } }, "/api/users/{userId}": { "put": { "operationId": "updateUser", "summary": "Update a user", "tags": [ "User" ], "description": "Updates user properties including name, status, type, and assigned roles.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "firstName": { "type": "string", "description": "Updated first name" }, "lastName": { "type": "string", "description": "Updated last name" }, "status": { "type": "string", "enum": [ "active", "disabled", "locked" ], "description": "Updated user status" }, "type": { "type": "string", "enum": [ "invited", "member", "author", "admin", "owner" ], "description": "Updated user type" }, "roles": { "type": "array", "items": { "type": "string", "format": "uuid", "description": "Role ID" }, "description": "List of role IDs to assign to the user" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "userId", "required": true, "description": "Unique identifier of the user to update" } ], "security": [ { "internalAuth": [] } ], "responses": { "200": { "description": "The updated user", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the user" }, "email": { "type": "string", "format": "email", "description": "Email address of the user" }, "firstName": { "type": "string", "nullable": true, "description": "First name of the user" }, "lastName": { "type": "string", "nullable": true, "description": "Last name of the user" }, "type": { "type": "string", "enum": [ "invited", "member", "author", "admin", "owner" ], "description": "User type/role within the organisation" }, "status": { "type": "string", "enum": [ "active", "disabled", "locked" ], "description": "Current status of the user account" }, "isService": { "type": "boolean", "description": "Whether this is a service account" }, "roles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the role" }, "name": { "type": "string", "description": "Name of the role" }, "description": { "type": "string", "nullable": true, "description": "Description of the role" } }, "required": [ "id", "name" ] }, "description": "Roles assigned to the user" }, "createdAt": { "type": "string", "description": "Timestamp when the user was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the user was last updated" } }, "required": [ "id", "email", "type", "status", "createdAt", "updatedAt" ], "description": "The updated user" } } } } } }, "delete": { "operationId": "removeUser", "summary": "Remove a user", "tags": [ "User" ], "description": "Removes a user from the organisation, deleting their memberships, invitations, and sessions.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "userId", "required": true, "description": "Unique identifier of the user to remove" } ], "security": [ { "internalAuth": [] } ], "responses": { "200": { "description": "Confirmation that the user was removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ], "description": "Operation status" } }, "required": [ "status" ], "description": "Confirmation that the user was removed" } } } } } } }, "/api/users/{userId}/transfer-ownership": { "post": { "operationId": "transferOwnership", "summary": "Transfer ownership", "tags": [ "User" ], "description": "Transfers the ownership of organisation to given user.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "userId", "required": true, "description": "Unique identifier of the user to transfer ownership to" } ], "security": [ { "internalAuth": [] } ], "responses": { "200": { "description": "The previous owner user (now demoted to admin)", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the user" }, "email": { "type": "string", "format": "email", "description": "Email address of the user" }, "firstName": { "type": "string", "nullable": true, "description": "First name of the user" }, "lastName": { "type": "string", "nullable": true, "description": "Last name of the user" }, "type": { "type": "string", "enum": [ "invited", "member", "author", "admin", "owner" ], "description": "User type/role within the organisation" }, "status": { "type": "string", "enum": [ "active", "disabled", "locked" ], "description": "Current status of the user account" }, "isService": { "type": "boolean", "description": "Whether this is a service account" }, "roles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the role" }, "name": { "type": "string", "description": "Name of the role" }, "description": { "type": "string", "nullable": true, "description": "Description of the role" } }, "required": [ "id", "name" ] }, "description": "Roles assigned to the user" }, "createdAt": { "type": "string", "description": "Timestamp when the user was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the user was last updated" } }, "required": [ "id", "email", "type", "status", "createdAt", "updatedAt" ], "description": "The previous owner user (now demoted to admin)" } } } } } } }, "/api/users/{userId}/invitation": { "post": { "operationId": "sendUserInvitation", "summary": "Send a user invitation", "tags": [ "User" ], "description": "Sends or resends an invitation email to a user who has been invited but not yet accepted.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "userId", "required": true, "description": "Unique identifier of the invited user" } ], "security": [ { "internalAuth": [] } ], "responses": { "200": { "description": "The created invitation", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the invitation" }, "email": { "type": "string", "format": "email", "description": "Email address the invitation was sent to" }, "status": { "type": "string", "enum": [ "pending", "accepted" ], "description": "Current status of the invitation" }, "userId": { "type": "string", "format": "uuid", "description": "ID of the user associated with this invitation" }, "createdAt": { "type": "string", "description": "Timestamp when the invitation was created" }, "expiresAt": { "type": "string", "nullable": true, "description": "Timestamp when the invitation expires" } }, "required": [ "id", "email", "status", "userId", "createdAt" ], "description": "The created invitation" } } } } } }, "delete": { "operationId": "revokeUserInvitation", "summary": "Revoke a user invitation", "tags": [ "User" ], "description": "Revokes a pending invitation for a user, preventing them from joining the organisation.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "userId", "required": true, "description": "Unique identifier of the invited user whose invitation should be revoked" } ], "security": [ { "internalAuth": [] } ], "responses": { "200": { "description": "Confirmation that the invitation was revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ], "description": "Operation status" } }, "required": [ "status" ], "description": "Confirmation that the invitation was revoked" } } } } } } }, "/api/profile": { "put": { "operationId": "updateProfile", "summary": "Update user profile", "tags": [ "Profile" ], "description": "Update current user profile.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "firstName": { "type": "string", "maxLength": 100, "description": "First name of the user", "example": "John" }, "lastName": { "type": "string", "maxLength": 100, "description": "Last name of the user", "example": "Doe" } }, "required": [ "firstName", "lastName" ] } } }, "required": true }, "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Successfully updated user profile", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the user" }, "email": { "type": "string", "format": "email", "description": "Email address of the user" }, "firstName": { "type": "string", "description": "First name of the user" }, "lastName": { "type": "string", "description": "Last name of the user" }, "type": { "type": "string", "enum": [ "invited", "member", "author", "admin", "owner" ], "description": "User role type within the organisation" }, "status": { "type": "string", "enum": [ "active", "disabled", "locked" ], "description": "Current status of the user account" }, "organisationId": { "type": "string", "format": "uuid", "description": "Organisation ID the user belongs to" }, "lastProjectId": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of the last visited project" }, "owner": { "type": "boolean", "description": "Whether the user is the organisation owner" }, "isService": { "type": "boolean", "description": "Whether the user is a service account" }, "createdAt": { "type": "string", "description": "Timestamp when the user was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the user was last updated" } }, "required": [ "id", "email", "type", "status", "organisationId", "lastProjectId", "createdAt", "updatedAt" ], "description": "Updated user profile information" } }, "required": [ "user" ], "description": "Successfully updated user profile" } } } } } }, "delete": { "operationId": "deleteProfile", "summary": "Delete user profile", "tags": [ "Profile" ], "description": "Deletes current user profile. This action is not reversible.", "security": [ { "internalAuth": [] } ], "responses": { "202": { "description": "Profile deletion accepted and processed" } } } }, "/api/profile/visit-project": { "post": { "operationId": "visitProject", "summary": "Visit project", "tags": [ "Profile" ], "description": "Used for caching last visited project.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "projectId": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of the project being visited, or null to clear" } }, "required": [ "projectId" ] } } }, "required": true }, "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "202": { "description": "Project visit recorded successfully" } } } }, "/api/projects/{projectId}/releases": { "get": { "operationId": "listReleases", "summary": "List releases", "tags": [ "Release" ], "description": "Retrieve a paginated list of releases for a project, with optional filtering by status and search.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "search", "description": "Search query to filter releases by version or name" }, { "schema": { "type": "string", "nullable": true, "enum": [ "draft", "published", "completed", null ] }, "in": "query", "name": "status", "description": "Filter releases by status" }, { "schema": { "type": "number", "default": 1 }, "in": "query", "name": "page", "description": "Current page" }, { "schema": { "type": "number", "default": 10 }, "in": "query", "name": "perPage", "description": "Number of items per page" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project unique identifier" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Paginated list of releases", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Release unique identifier" }, "createdAt": { "type": "string", "description": "Release creation timestamp" }, "deletedAt": { "type": "string", "nullable": true, "description": "Release deletion timestamp" }, "name": { "type": "string", "nullable": true, "description": "Release name" }, "description": { "type": "string", "nullable": true, "description": "Release description" }, "version": { "type": "number", "nullable": true, "description": "Legacy numeric version" }, "semanticVersion": { "type": "string", "nullable": true, "description": "Semantic version (e.g., 1.0.0)" }, "status": { "type": "string", "enum": [ "draft", "published", "completed" ], "description": "Release status" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID the release belongs to" }, "createdById": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of the user who created the release" }, "commitId": { "type": "string", "nullable": true, "format": "uuid", "description": "Associated commit ID" }, "meta": { "type": "object", "nullable": true, "properties": { "bucket": { "type": "string", "description": "Storage bucket name" }, "key": { "type": "string", "description": "Storage object key" } }, "description": "Release storage metadata" }, "changeRequests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Change request unique identifier" }, "status": { "type": "string", "description": "Change request status" }, "environment": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Environment unique identifier" }, "name": { "type": "string", "description": "Environment name" } }, "required": [ "id", "name" ], "description": "Environment details" } }, "required": [ "id", "status" ], "description": "Pending change request for the release" }, "description": "Pending change requests" } }, "required": [ "id", "createdAt", "projectId" ], "description": "Release list item" }, "description": "List of releases" }, "paginate": { "type": "object", "properties": { "current": { "type": "number", "description": "Current page number" }, "from": { "type": "number", "description": "Starting record number" }, "to": { "type": "number", "description": "Ending record number" }, "total": { "type": "number", "description": "Total number of records" }, "pageSize": { "type": "number", "description": "Number of records per page" } }, "required": [ "current", "from", "to", "total", "pageSize" ], "description": "Pagination metadata" } }, "required": [ "results", "paginate" ], "description": "Paginated list of releases" } } } } } }, "post": { "operationId": "createRelease", "summary": "Create a release", "tags": [ "Release" ], "description": "Create a new release from the current project state or a specific commit.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "nullable": true, "description": "Release name" }, "description": { "type": "string", "nullable": true, "description": "Release description" }, "commitId": { "type": "string", "nullable": true, "description": "Commit ID to create the release from (v2 projects only)" }, "status": { "type": "string", "enum": [ "draft", "published", "completed" ], "default": "draft", "description": "Initial release status" }, "versionType": { "type": "string", "enum": [ "major", "minor", "patch" ], "default": "patch", "description": "Version increment type for semantic versioning" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project unique identifier" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Created release information", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Release unique identifier" }, "createdAt": { "type": "string", "description": "Release creation timestamp" }, "deletedAt": { "type": "string", "nullable": true, "description": "Release deletion timestamp" }, "name": { "type": "string", "nullable": true, "description": "Release name" }, "description": { "type": "string", "nullable": true, "description": "Release description" }, "version": { "type": "number", "nullable": true, "description": "Legacy numeric version" }, "semanticVersion": { "type": "string", "nullable": true, "description": "Semantic version (e.g., 1.0.0)" }, "status": { "type": "string", "enum": [ "draft", "published", "completed" ], "description": "Release status" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID the release belongs to" }, "createdById": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of the user who created the release" }, "commitId": { "type": "string", "nullable": true, "format": "uuid", "description": "Associated commit ID" }, "meta": { "type": "object", "nullable": true, "properties": { "bucket": { "type": "string", "description": "Storage bucket name" }, "key": { "type": "string", "description": "Storage object key" } }, "description": "Release storage metadata" } }, "required": [ "id", "createdAt", "projectId" ], "description": "Created release information" } } } } } } }, "/api/projects/{projectId}/releases/{releaseId}": { "get": { "operationId": "getRelease", "summary": "Get a release", "tags": [ "Release" ], "description": "Retrieve a single release by ID, optionally including diff information compared to a previous release.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "previousReleaseId", "description": "Previous release ID for computing file diffs" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project unique identifier" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "releaseId", "required": true, "description": "Release unique identifier" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Release details with files", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Release unique identifier" }, "createdAt": { "type": "string", "description": "Release creation timestamp" }, "deletedAt": { "type": "string", "nullable": true, "description": "Release deletion timestamp" }, "name": { "type": "string", "nullable": true, "description": "Release name" }, "description": { "type": "string", "nullable": true, "description": "Release description" }, "version": { "type": "number", "nullable": true, "description": "Legacy numeric version" }, "semanticVersion": { "type": "string", "nullable": true, "description": "Semantic version (e.g., 1.0.0)" }, "status": { "type": "string", "enum": [ "draft", "published", "completed" ], "description": "Release status" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID the release belongs to" }, "createdById": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of the user who created the release" }, "commitId": { "type": "string", "nullable": true, "format": "uuid", "description": "Associated commit ID" }, "meta": { "type": "object", "nullable": true, "properties": { "bucket": { "type": "string", "description": "Storage bucket name" }, "key": { "type": "string", "description": "Storage object key" } }, "description": "Release storage metadata" }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "File unique identifier" }, "name": { "type": "string", "nullable": true, "description": "File name" }, "path": { "type": "string", "description": "File path within the release" }, "contentType": { "type": "string", "nullable": true, "description": "MIME type of the file" }, "contentHash": { "type": "string", "nullable": true, "description": "MD5 hash of the file content" }, "releaseId": { "type": "string", "format": "uuid", "description": "ID of the release this file belongs to" }, "versionId": { "type": "string", "nullable": true, "format": "uuid", "description": "Document version ID" }, "createdAt": { "type": "string", "nullable": true, "description": "File creation timestamp" }, "diffStatus": { "type": "string", "enum": [ "added", "modified", "removed", "unchanged" ], "description": "Diff status when comparing releases" }, "previousReleaseId": { "type": "string", "format": "uuid", "description": "Previous release ID for modified files" }, "previousId": { "type": "string", "format": "uuid", "description": "Previous file ID for modified files" } }, "required": [ "id", "path", "releaseId" ], "description": "Release file information" }, "description": "List of files in the release" }, "createdBy": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" }, "type": { "type": "string", "nullable": true, "description": "User type" }, "status": { "type": "string", "nullable": true, "description": "User status" } }, "required": [ "id", "email", "firstName", "lastName", "type", "status" ], "description": "User who created the release" }, "changeRequests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Change request unique identifier" }, "status": { "type": "string", "description": "Change request status" }, "environment": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Environment unique identifier" }, "name": { "type": "string", "description": "Environment name" } }, "required": [ "id", "name" ], "description": "Environment details" } }, "required": [ "id", "status" ], "description": "Pending change request for the release" }, "description": "Pending change requests" } }, "required": [ "id", "createdAt", "projectId" ], "description": "Release details with files" } } } } } }, "put": { "operationId": "updateRelease", "summary": "Update release", "tags": [ "Release" ], "description": "Update the name, description, or tags of an existing release.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "nullable": true, "description": "Updated release name" }, "description": { "type": "string", "nullable": true, "description": "Updated release description" }, "tags": { "type": "array", "nullable": true, "items": { "type": "string" }, "default": [], "description": "Release tags" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project unique identifier" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "releaseId", "required": true, "description": "Release unique identifier" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Updated release information", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Release unique identifier" }, "createdAt": { "type": "string", "description": "Release creation timestamp" }, "deletedAt": { "type": "string", "nullable": true, "description": "Release deletion timestamp" }, "name": { "type": "string", "nullable": true, "description": "Release name" }, "description": { "type": "string", "nullable": true, "description": "Release description" }, "version": { "type": "number", "nullable": true, "description": "Legacy numeric version" }, "semanticVersion": { "type": "string", "nullable": true, "description": "Semantic version (e.g., 1.0.0)" }, "status": { "type": "string", "enum": [ "draft", "published", "completed" ], "description": "Release status" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID the release belongs to" }, "createdById": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of the user who created the release" }, "commitId": { "type": "string", "nullable": true, "format": "uuid", "description": "Associated commit ID" }, "meta": { "type": "object", "nullable": true, "properties": { "bucket": { "type": "string", "description": "Storage bucket name" }, "key": { "type": "string", "description": "Storage object key" } }, "description": "Release storage metadata" } }, "required": [ "id", "createdAt", "projectId" ], "description": "Updated release information" } } } } } }, "delete": { "operationId": "deleteRelease", "summary": "Delete a release", "tags": [ "Release" ], "description": "Soft delete a release from the project.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project unique identifier" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "releaseId", "required": true, "description": "Release unique identifier" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Release deleted successfully" } } } }, "/api/projects/{projectId}/releases/latest-published": { "get": { "operationId": "getLatestPublishedRelease", "summary": "Get latest published release", "tags": [ "Release" ], "description": "Retrieve the most recently published release for a project based on semantic version.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project unique identifier" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Latest published release or null if none exists", "content": { "application/json": { "schema": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Release unique identifier" }, "createdAt": { "type": "string", "description": "Release creation timestamp" }, "deletedAt": { "type": "string", "nullable": true, "description": "Release deletion timestamp" }, "name": { "type": "string", "nullable": true, "description": "Release name" }, "description": { "type": "string", "nullable": true, "description": "Release description" }, "version": { "type": "number", "nullable": true, "description": "Legacy numeric version" }, "semanticVersion": { "type": "string", "nullable": true, "description": "Semantic version (e.g., 1.0.0)" }, "status": { "type": "string", "enum": [ "draft", "published", "completed" ], "description": "Release status" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID the release belongs to" }, "createdById": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of the user who created the release" }, "commitId": { "type": "string", "nullable": true, "format": "uuid", "description": "Associated commit ID" }, "meta": { "type": "object", "nullable": true, "properties": { "bucket": { "type": "string", "description": "Storage bucket name" }, "key": { "type": "string", "description": "Storage object key" } }, "description": "Release storage metadata" } }, "required": [ "id", "createdAt", "projectId" ], "description": "Latest published release or null if none exists" } } } } } } }, "/api/projects/{projectId}/releases/{releaseId}/publish": { "post": { "operationId": "publishRelease", "summary": "Publish release", "tags": [ "Release" ], "description": "Publish a draft release, assigning it a semantic version.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "nullable": true, "description": "Updated release name" }, "description": { "type": "string", "nullable": true, "description": "Updated release description" }, "versionType": { "type": "string", "enum": [ "major", "minor", "patch" ], "default": "patch", "description": "Version increment type for semantic versioning" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project unique identifier" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "releaseId", "required": true, "description": "Release unique identifier" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Published release information", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Release unique identifier" }, "createdAt": { "type": "string", "description": "Release creation timestamp" }, "deletedAt": { "type": "string", "nullable": true, "description": "Release deletion timestamp" }, "name": { "type": "string", "nullable": true, "description": "Release name" }, "description": { "type": "string", "nullable": true, "description": "Release description" }, "version": { "type": "number", "nullable": true, "description": "Legacy numeric version" }, "semanticVersion": { "type": "string", "nullable": true, "description": "Semantic version (e.g., 1.0.0)" }, "status": { "type": "string", "enum": [ "draft", "published", "completed" ], "description": "Release status" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID the release belongs to" }, "createdById": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of the user who created the release" }, "commitId": { "type": "string", "nullable": true, "format": "uuid", "description": "Associated commit ID" }, "meta": { "type": "object", "nullable": true, "properties": { "bucket": { "type": "string", "description": "Storage bucket name" }, "key": { "type": "string", "description": "Storage object key" } }, "description": "Release storage metadata" } }, "required": [ "id", "createdAt", "projectId" ], "description": "Published release information" } } } } } } }, "/api/projects/{projectId}/releases/multipart": { "post": { "operationId": "uploadRelease", "summary": "Upload a release", "tags": [ "Release" ], "description": "Upload a release package as a ZIP file containing decision documents.", "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "nullable": true, "properties": { "files": { "type": "array", "items": { "format": "binary", "description": "ZIP file containing release documents" }, "description": "List of ZIP files to be uploaded" } }, "required": [ "files" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project unique identifier" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Created release information", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Release unique identifier" }, "createdAt": { "type": "string", "description": "Release creation timestamp" }, "deletedAt": { "type": "string", "nullable": true, "description": "Release deletion timestamp" }, "name": { "type": "string", "nullable": true, "description": "Release name" }, "description": { "type": "string", "nullable": true, "description": "Release description" }, "version": { "type": "number", "nullable": true, "description": "Legacy numeric version" }, "semanticVersion": { "type": "string", "nullable": true, "description": "Semantic version (e.g., 1.0.0)" }, "status": { "type": "string", "enum": [ "draft", "published", "completed" ], "description": "Release status" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID the release belongs to" }, "createdById": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of the user who created the release" }, "commitId": { "type": "string", "nullable": true, "format": "uuid", "description": "Associated commit ID" }, "meta": { "type": "object", "nullable": true, "properties": { "bucket": { "type": "string", "description": "Storage bucket name" }, "key": { "type": "string", "description": "Storage object key" } }, "description": "Release storage metadata" } }, "required": [ "id", "createdAt", "projectId" ], "description": "Created release information" } } } } } } }, "/api/projects/{projectId}/releases/{releaseId}/download": { "get": { "operationId": "downloadRelease", "summary": "Download a release", "tags": [ "Release" ], "description": "Download all files in a release as a ZIP archive.", "parameters": [ { "schema": { "type": "string", "enum": [ "buffered", "streamed" ], "default": "streamed" }, "in": "query", "name": "transferMode", "description": "Transfer mode for the download (buffered returns complete file, streamed uses chunked transfer)" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project unique identifier" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "releaseId", "required": true, "description": "Release unique identifier" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/projects/{projectId}/releases/apply": { "post": { "operationId": "applyRelease", "summary": "Apply a release", "tags": [ "Release" ], "description": "Apply a release to the project, creating or updating documents from the release files (v1 projects only).", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "releaseId": { "type": "string", "format": "uuid", "description": "Release ID to apply" }, "publish": { "type": "boolean", "default": false, "description": "Whether to publish the applied documents immediately" } }, "required": [ "releaseId" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project unique identifier" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Release applied successfully" } } } }, "/api/projects/{projectId}/releases/deploy": { "post": { "operationId": "deployRelease", "summary": "Deploy a release", "tags": [ "Release" ], "description": "Deploy a release to a specific environment, optionally creating a change request if approvals are required.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "releaseId": { "type": "string", "format": "uuid", "description": "Release ID to deploy" }, "environmentId": { "type": "string", "format": "uuid", "description": "Target environment ID" }, "comment": { "type": "string", "nullable": true, "description": "Deployment comment or description" } }, "required": [ "releaseId", "environmentId" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project unique identifier" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Deployment initiated successfully" } } } }, "/api/projects/{projectId}/releases/{releaseId}/files/{fileId}": { "get": { "operationId": "getReleaseFile", "summary": "Get a release file", "tags": [ "Release" ], "description": "Retrieve a single file from a release including its content.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project unique identifier" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "releaseId", "required": true, "description": "Release unique identifier" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "fileId", "required": true, "description": "File unique identifier" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Release file with content", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "File unique identifier" }, "name": { "type": "string", "nullable": true, "description": "File name" }, "path": { "type": "string", "description": "File path within the release" }, "contentType": { "type": "string", "nullable": true, "description": "MIME type of the file" }, "contentHash": { "type": "string", "nullable": true, "description": "MD5 hash of the file content" }, "releaseId": { "type": "string", "format": "uuid", "description": "ID of the release this file belongs to" }, "versionId": { "type": "string", "nullable": true, "format": "uuid", "description": "Document version ID" }, "createdAt": { "type": "string", "nullable": true, "description": "File creation timestamp" }, "diffStatus": { "type": "string", "enum": [ "added", "modified", "removed", "unchanged" ], "description": "Diff status when comparing releases" }, "previousReleaseId": { "type": "string", "format": "uuid", "description": "Previous release ID for modified files" }, "previousId": { "type": "string", "format": "uuid", "description": "Previous file ID for modified files" }, "content": { "nullable": true, "description": "File content (decision graph data)" }, "documentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Associated document ID" } }, "required": [ "id", "path", "releaseId" ], "description": "Release file with content" } } } } } } }, "/api/projects/{projectId}/releases/{releaseId}/files": { "get": { "operationId": "getReleaseFiles", "summary": "Get release files", "tags": [ "Release" ], "description": "Retrieve all files contained in a release with their content.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project unique identifier" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "releaseId", "required": true, "description": "Release unique identifier" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "List of release files with content", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "File unique identifier" }, "name": { "type": "string", "nullable": true, "description": "File name" }, "path": { "type": "string", "description": "File path within the release" }, "contentType": { "type": "string", "nullable": true, "description": "MIME type of the file" }, "contentHash": { "type": "string", "nullable": true, "description": "MD5 hash of the file content" }, "releaseId": { "type": "string", "format": "uuid", "description": "ID of the release this file belongs to" }, "versionId": { "type": "string", "nullable": true, "format": "uuid", "description": "Document version ID" }, "createdAt": { "type": "string", "nullable": true, "description": "File creation timestamp" }, "diffStatus": { "type": "string", "enum": [ "added", "modified", "removed", "unchanged" ], "description": "Diff status when comparing releases" }, "previousReleaseId": { "type": "string", "format": "uuid", "description": "Previous release ID for modified files" }, "previousId": { "type": "string", "format": "uuid", "description": "Previous file ID for modified files" }, "content": { "nullable": true, "description": "File content (decision graph data)" }, "documentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Associated document ID" } }, "required": [ "id", "path", "releaseId" ], "description": "Release file with content" }, "description": "List of release files with content" } } } } } } }, "/api/ai/chat": { "post": { "operationId": "createAiChat", "summary": "Chat with an AI", "tags": [ "AI" ], "description": "Send messages to an AI assistant and receive a streaming response for interactive conversations.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "string" }, "description": "Array of messages to send to the AI assistant" } }, "required": [ "messages" ] } } }, "required": true }, "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/projects/{projectId}/members": { "get": { "operationId": "listMembers", "summary": "List members", "tags": [ "Member" ], "description": "Retrieve a paginated list of all members in a project, including their user details and group assignments.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "search", "description": "Search term to filter members by email or name" }, { "schema": { "type": "number", "default": 1 }, "in": "query", "name": "page", "description": "Current page" }, { "schema": { "type": "number", "default": 10 }, "in": "query", "name": "perPage", "description": "Number of items per page" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Unique identifier of the project" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Paginated list of project members", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the member" }, "owner": { "type": "boolean", "description": "Whether the member is an owner of the project" }, "userId": { "type": "string", "format": "uuid", "description": "User ID of the member" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID the member belongs to" }, "user": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the user" }, "email": { "type": "string", "format": "email", "description": "Email address of the user" }, "firstName": { "type": "string", "nullable": true, "description": "First name of the user" }, "lastName": { "type": "string", "nullable": true, "description": "Last name of the user" }, "type": { "type": "string", "description": "Type of user (e.g., OWNER, ADMIN, MEMBER)" }, "status": { "type": "string", "description": "Status of the user (e.g., ACTIVE, INACTIVE)" }, "organisationId": { "type": "string", "format": "uuid", "description": "Organisation the user belongs to" }, "isService": { "type": "boolean", "description": "Whether this is a service account" }, "createdAt": { "type": "string", "description": "Timestamp when the user was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the user was last updated" } }, "required": [ "id", "email", "firstName", "lastName", "type", "status", "organisationId", "createdAt", "updatedAt" ], "description": "User details of the member" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the group" }, "name": { "type": "string", "description": "Name of the group" }, "description": { "type": "string", "nullable": true, "description": "Description of the group" }, "projectId": { "type": "string", "format": "uuid", "description": "Project the group belongs to" }, "permissions": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "List of permissions assigned to the group" }, "roleId": { "type": "string", "nullable": true, "format": "uuid", "description": "Role ID associated with the group" } }, "required": [ "id", "name", "projectId", "permissions" ] }, "description": "Groups the member belongs to" }, "createdAt": { "type": "string", "description": "Timestamp when the member was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the member was last updated" } }, "required": [ "id", "createdAt", "updatedAt" ] }, "description": "List of project members" }, "paginate": { "type": "object", "properties": { "current": { "type": "number", "description": "Current page number" }, "from": { "type": "number", "description": "Starting record number on the current page" }, "to": { "type": "number", "description": "Ending record number on the current page" }, "total": { "type": "number", "description": "Total number of records" }, "pageSize": { "type": "number", "description": "Number of records per page" } }, "required": [ "current", "from", "to", "total", "pageSize" ], "description": "Pagination metadata" } }, "required": [ "results", "paginate" ], "description": "Paginated list of project members" } } } } } }, "post": { "operationId": "inviteMembers", "summary": "Invite members", "tags": [ "Member" ], "description": "Invite one or more users to become members of a project, optionally assigning them to groups and setting owner status.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "userIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "List of user IDs to invite to the project" }, "groupIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "List of group IDs to assign to the new members" }, "owner": { "type": "boolean", "default": false, "description": "Whether the invited members should be project owners" } }, "required": [ "userIds" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Unique identifier of the project" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "List of newly created membership records", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the member" }, "owner": { "type": "boolean", "description": "Whether the member is an owner of the project" }, "userId": { "type": "string", "format": "uuid", "description": "User ID of the member" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID the member belongs to" }, "user": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the user" }, "email": { "type": "string", "format": "email", "description": "Email address of the user" }, "firstName": { "type": "string", "nullable": true, "description": "First name of the user" }, "lastName": { "type": "string", "nullable": true, "description": "Last name of the user" }, "type": { "type": "string", "description": "Type of user (e.g., OWNER, ADMIN, MEMBER)" }, "status": { "type": "string", "description": "Status of the user (e.g., ACTIVE, INACTIVE)" }, "organisationId": { "type": "string", "format": "uuid", "description": "Organisation the user belongs to" }, "isService": { "type": "boolean", "description": "Whether this is a service account" }, "createdAt": { "type": "string", "description": "Timestamp when the user was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the user was last updated" } }, "required": [ "id", "email", "firstName", "lastName", "type", "status", "organisationId", "createdAt", "updatedAt" ], "description": "User details of the member" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the group" }, "name": { "type": "string", "description": "Name of the group" }, "description": { "type": "string", "nullable": true, "description": "Description of the group" }, "projectId": { "type": "string", "format": "uuid", "description": "Project the group belongs to" }, "permissions": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "List of permissions assigned to the group" }, "roleId": { "type": "string", "nullable": true, "format": "uuid", "description": "Role ID associated with the group" } }, "required": [ "id", "name", "projectId", "permissions" ] }, "description": "Groups the member belongs to" }, "createdAt": { "type": "string", "description": "Timestamp when the member was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the member was last updated" } }, "required": [ "id", "createdAt", "updatedAt" ] }, "description": "List of newly created membership records" } } } } } } }, "/api/projects/{projectId}/members/users": { "get": { "operationId": "listMemberUsers", "summary": "List member users", "tags": [ "Member" ], "description": "Retrieve a paginated list of organisation users who are not yet members of the project and can be invited.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "search", "description": "Search term to filter users by email, first name, or last name" }, { "schema": { "type": "number", "default": 1 }, "in": "query", "name": "page", "description": "Current page" }, { "schema": { "type": "number", "default": 10 }, "in": "query", "name": "perPage", "description": "Number of items per page" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Unique identifier of the project" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Paginated list of users available for invitation", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the user" }, "email": { "type": "string", "format": "email", "description": "Email address of the user" }, "firstName": { "type": "string", "nullable": true, "description": "First name of the user" }, "lastName": { "type": "string", "nullable": true, "description": "Last name of the user" }, "type": { "type": "string", "description": "Type of user (e.g., OWNER, ADMIN, MEMBER)" }, "status": { "type": "string", "description": "Status of the user (e.g., ACTIVE, INACTIVE)" }, "organisationId": { "type": "string", "format": "uuid", "description": "Organisation the user belongs to" }, "isService": { "type": "boolean", "description": "Whether this is a service account" }, "createdAt": { "type": "string", "description": "Timestamp when the user was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the user was last updated" } }, "required": [ "id", "email", "firstName", "lastName", "type", "status", "organisationId", "createdAt", "updatedAt" ] }, "description": "List of users available to invite" }, "paginate": { "type": "object", "properties": { "current": { "type": "number", "description": "Current page number" }, "from": { "type": "number", "description": "Starting record number on the current page" }, "to": { "type": "number", "description": "Ending record number on the current page" }, "total": { "type": "number", "description": "Total number of records" }, "pageSize": { "type": "number", "description": "Number of records per page" } }, "required": [ "current", "from", "to", "total", "pageSize" ], "description": "Pagination metadata" } }, "required": [ "results", "paginate" ], "description": "Paginated list of users available for invitation" } } } } } } }, "/api/projects/{projectId}/members/join": { "post": { "operationId": "joinProject", "summary": "Join project", "tags": [ "Member" ], "description": "Join the project for current user", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Unique identifier of the project to join" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "The newly created membership record", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the member" }, "owner": { "type": "boolean", "description": "Whether the member is an owner of the project" }, "userId": { "type": "string", "format": "uuid", "description": "User ID of the member" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID the member belongs to" }, "user": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the user" }, "email": { "type": "string", "format": "email", "description": "Email address of the user" }, "firstName": { "type": "string", "nullable": true, "description": "First name of the user" }, "lastName": { "type": "string", "nullable": true, "description": "Last name of the user" }, "type": { "type": "string", "description": "Type of user (e.g., OWNER, ADMIN, MEMBER)" }, "status": { "type": "string", "description": "Status of the user (e.g., ACTIVE, INACTIVE)" }, "organisationId": { "type": "string", "format": "uuid", "description": "Organisation the user belongs to" }, "isService": { "type": "boolean", "description": "Whether this is a service account" }, "createdAt": { "type": "string", "description": "Timestamp when the user was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the user was last updated" } }, "required": [ "id", "email", "firstName", "lastName", "type", "status", "organisationId", "createdAt", "updatedAt" ], "description": "User details of the member" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the group" }, "name": { "type": "string", "description": "Name of the group" }, "description": { "type": "string", "nullable": true, "description": "Description of the group" }, "projectId": { "type": "string", "format": "uuid", "description": "Project the group belongs to" }, "permissions": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "List of permissions assigned to the group" }, "roleId": { "type": "string", "nullable": true, "format": "uuid", "description": "Role ID associated with the group" } }, "required": [ "id", "name", "projectId", "permissions" ] }, "description": "Groups the member belongs to" }, "createdAt": { "type": "string", "description": "Timestamp when the member was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the member was last updated" } }, "required": [ "id", "createdAt", "updatedAt" ], "description": "The newly created membership record" } } } } } } }, "/api/projects/{projectId}/members/{memberId}": { "put": { "operationId": "updateMember", "summary": "Update a member", "tags": [ "Member" ], "description": "Update an existing project member, including their group assignments and owner status.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "groupIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "List of group IDs to assign to the member" }, "owner": { "type": "boolean", "default": false, "description": "Whether the member should be a project owner" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "memberId", "required": true, "description": "Unique identifier of the member to update" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Unique identifier of the project" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "The updated membership record", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the member" }, "owner": { "type": "boolean", "description": "Whether the member is an owner of the project" }, "userId": { "type": "string", "format": "uuid", "description": "User ID of the member" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID the member belongs to" }, "user": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the user" }, "email": { "type": "string", "format": "email", "description": "Email address of the user" }, "firstName": { "type": "string", "nullable": true, "description": "First name of the user" }, "lastName": { "type": "string", "nullable": true, "description": "Last name of the user" }, "type": { "type": "string", "description": "Type of user (e.g., OWNER, ADMIN, MEMBER)" }, "status": { "type": "string", "description": "Status of the user (e.g., ACTIVE, INACTIVE)" }, "organisationId": { "type": "string", "format": "uuid", "description": "Organisation the user belongs to" }, "isService": { "type": "boolean", "description": "Whether this is a service account" }, "createdAt": { "type": "string", "description": "Timestamp when the user was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the user was last updated" } }, "required": [ "id", "email", "firstName", "lastName", "type", "status", "organisationId", "createdAt", "updatedAt" ], "description": "User details of the member" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the group" }, "name": { "type": "string", "description": "Name of the group" }, "description": { "type": "string", "nullable": true, "description": "Description of the group" }, "projectId": { "type": "string", "format": "uuid", "description": "Project the group belongs to" }, "permissions": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "List of permissions assigned to the group" }, "roleId": { "type": "string", "nullable": true, "format": "uuid", "description": "Role ID associated with the group" } }, "required": [ "id", "name", "projectId", "permissions" ] }, "description": "Groups the member belongs to" }, "createdAt": { "type": "string", "description": "Timestamp when the member was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the member was last updated" } }, "required": [ "id", "createdAt", "updatedAt" ], "description": "The updated membership record" } } } } } }, "delete": { "operationId": "deleteMember", "summary": "Delete a member", "tags": [ "Member" ], "description": "Remove a member from a project. The current user cannot remove themselves using this endpoint.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "memberId", "required": true, "description": "Unique identifier of the member to remove" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Unique identifier of the project" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Confirmation that the member has been removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ], "description": "Operation status" } }, "required": [ "status" ], "description": "Confirmation that the member has been removed" } } } } } } }, "/api/projects/{projectId}/members/leave": { "delete": { "operationId": "leaveProject", "summary": "Leave a project", "tags": [ "Member" ], "description": "Leaves a project for current user", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Unique identifier of the project to leave" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Confirmation that the user has left the project", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ], "description": "Operation status" } }, "required": [ "status" ], "description": "Confirmation that the user has left the project" } } } } } } }, "/api/projects/{projectId}/groups": { "get": { "operationId": "listGroups", "summary": "List groups", "tags": [ "Group" ], "description": "Retrieve a paginated list of groups for a project, with optional search filtering.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "search", "description": "Search term to filter groups by name" }, { "schema": { "type": "number", "default": 1 }, "in": "query", "name": "page", "description": "Current page" }, { "schema": { "type": "number", "default": 10 }, "in": "query", "name": "perPage", "description": "Number of items per page" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "ID of the project to list groups for" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Paginated list of groups", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the group" }, "name": { "type": "string", "description": "Name of the group" }, "description": { "type": "string", "description": "Description of the group" }, "projectId": { "type": "string", "format": "uuid", "description": "ID of the project this group belongs to" }, "permissions": { "type": "array", "nullable": true, "items": { "type": "string", "enum": [ "owner", "documents", "releases", "releases:manage", "releases:deploy", "releases:delete", "integrations:manage", "documents:full", "documents:view-content", "documents:edit-content", "documents:edit-view", "branches", "branches:create", "branches:merge", "branches:delete", "project:manage", "environments", "environments:manage", "environments:delete" ] }, "description": "List of permissions granted to this group" }, "filePermissions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "description": "Unique identifier of the file permission" }, "effect": { "type": "string", "enum": [ "allow", "deny" ], "description": "Whether this permission allows or denies the actions" }, "actions": { "type": "array", "nullable": true, "items": { "type": "string", "enum": [ "visible", "modify", "write", "delete" ] }, "default": [], "description": "List of actions this permission applies to" }, "patterns": { "type": "string", "nullable": true, "description": "Glob pattern to match file paths" } }, "required": [ "effect", "actions" ] }, "description": "File-level permissions for this group" }, "roleId": { "type": "string", "format": "uuid", "description": "ID of the access profile managing this group" }, "role": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the role" }, "name": { "type": "string", "description": "Name of the role" }, "description": { "type": "string", "description": "Description of the role" } }, "required": [ "id", "name" ], "description": "Access profile that manages this group" } }, "required": [ "id", "name", "projectId", "permissions" ] }, "description": "List of groups" }, "paginate": { "type": "object", "properties": { "current": { "type": "number", "description": "Current page number" }, "from": { "type": "number", "description": "Starting record number on the current page" }, "to": { "type": "number", "description": "Ending record number on the current page" }, "total": { "type": "number", "description": "Total number of records" }, "pageSize": { "type": "number", "description": "Number of records per page" } }, "required": [ "current", "from", "to", "total", "pageSize" ], "description": "Pagination metadata" } }, "required": [ "results", "paginate" ], "description": "Paginated list of groups" } } } } } }, "post": { "operationId": "createGroup", "summary": "Create group", "tags": [ "Group" ], "description": "Create a new group within a project with specified permissions.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the group" }, "description": { "type": "string", "description": "Description of the group" }, "permissions": { "type": "array", "items": { "type": "string", "enum": [ "owner", "documents", "releases", "releases:manage", "releases:deploy", "releases:delete", "integrations:manage", "documents:full", "documents:view-content", "documents:edit-content", "documents:edit-view", "branches", "branches:create", "branches:merge", "branches:delete", "project:manage", "environments", "environments:manage", "environments:delete" ] }, "description": "List of permissions to grant to the group" }, "filePermissions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "effect": { "type": "string", "enum": [ "allow", "deny" ] }, "actions": { "type": "array", "nullable": true, "items": { "type": "string", "enum": [ "visible", "modify", "write", "delete" ] }, "default": [] }, "patterns": { "type": "string", "nullable": true } }, "required": [ "effect" ] }, "default": [], "description": "File-level permissions for the group" } }, "required": [ "name" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "ID of the project to create the group in" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "The created group", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the group" }, "name": { "type": "string", "description": "Name of the group" }, "description": { "type": "string", "description": "Description of the group" }, "projectId": { "type": "string", "format": "uuid", "description": "ID of the project this group belongs to" }, "permissions": { "type": "array", "nullable": true, "items": { "type": "string", "enum": [ "owner", "documents", "releases", "releases:manage", "releases:deploy", "releases:delete", "integrations:manage", "documents:full", "documents:view-content", "documents:edit-content", "documents:edit-view", "branches", "branches:create", "branches:merge", "branches:delete", "project:manage", "environments", "environments:manage", "environments:delete" ] }, "description": "List of permissions granted to this group" }, "filePermissions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "description": "Unique identifier of the file permission" }, "effect": { "type": "string", "enum": [ "allow", "deny" ], "description": "Whether this permission allows or denies the actions" }, "actions": { "type": "array", "nullable": true, "items": { "type": "string", "enum": [ "visible", "modify", "write", "delete" ] }, "default": [], "description": "List of actions this permission applies to" }, "patterns": { "type": "string", "nullable": true, "description": "Glob pattern to match file paths" } }, "required": [ "effect", "actions" ] }, "description": "File-level permissions for this group" }, "roleId": { "type": "string", "format": "uuid", "description": "ID of the access profile managing this group" }, "role": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the role" }, "name": { "type": "string", "description": "Name of the role" }, "description": { "type": "string", "description": "Description of the role" } }, "required": [ "id", "name" ], "description": "Access profile that manages this group" } }, "required": [ "id", "name", "projectId", "permissions" ], "description": "The created group" } } } } } } }, "/api/projects/{projectId}/groups/{groupId}": { "put": { "operationId": "updateGroup", "summary": "Update group", "tags": [ "Group" ], "description": "Update an existing group with new name, description, or permissions.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "New name for the group" }, "description": { "type": "string", "description": "New description for the group" }, "permissions": { "type": "array", "items": { "type": "string", "enum": [ "owner", "documents", "releases", "releases:manage", "releases:deploy", "releases:delete", "integrations:manage", "documents:full", "documents:view-content", "documents:edit-content", "documents:edit-view", "branches", "branches:create", "branches:merge", "branches:delete", "project:manage", "environments", "environments:manage", "environments:delete" ] }, "description": "Updated list of permissions for the group" }, "filePermissions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "effect": { "type": "string", "enum": [ "allow", "deny" ] }, "actions": { "type": "array", "nullable": true, "items": { "type": "string", "enum": [ "visible", "modify", "write", "delete" ] }, "default": [] }, "patterns": { "type": "string", "nullable": true } }, "required": [ "effect" ] }, "default": [], "description": "Updated file-level permissions for the group" } }, "required": [ "name" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "groupId", "required": true, "description": "ID of the group to update" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "ID of the project the group belongs to" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "The updated group", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the group" }, "name": { "type": "string", "description": "Name of the group" }, "description": { "type": "string", "description": "Description of the group" }, "projectId": { "type": "string", "format": "uuid", "description": "ID of the project this group belongs to" }, "permissions": { "type": "array", "nullable": true, "items": { "type": "string", "enum": [ "owner", "documents", "releases", "releases:manage", "releases:deploy", "releases:delete", "integrations:manage", "documents:full", "documents:view-content", "documents:edit-content", "documents:edit-view", "branches", "branches:create", "branches:merge", "branches:delete", "project:manage", "environments", "environments:manage", "environments:delete" ] }, "description": "List of permissions granted to this group" }, "filePermissions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "description": "Unique identifier of the file permission" }, "effect": { "type": "string", "enum": [ "allow", "deny" ], "description": "Whether this permission allows or denies the actions" }, "actions": { "type": "array", "nullable": true, "items": { "type": "string", "enum": [ "visible", "modify", "write", "delete" ] }, "default": [], "description": "List of actions this permission applies to" }, "patterns": { "type": "string", "nullable": true, "description": "Glob pattern to match file paths" } }, "required": [ "effect", "actions" ] }, "description": "File-level permissions for this group" }, "roleId": { "type": "string", "format": "uuid", "description": "ID of the access profile managing this group" }, "role": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the role" }, "name": { "type": "string", "description": "Name of the role" }, "description": { "type": "string", "description": "Description of the role" } }, "required": [ "id", "name" ], "description": "Access profile that manages this group" } }, "required": [ "id", "name", "projectId", "permissions" ], "description": "The updated group" } } } } } }, "delete": { "operationId": "deleteGroup", "summary": "Delete group", "tags": [ "Group" ], "description": "Delete a group from a project. Groups managed by access profiles cannot be deleted directly.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "groupId", "required": true, "description": "ID of the group to delete" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "ID of the project the group belongs to" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Confirmation of successful deletion", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ], "description": "Indicates successful deletion" } }, "required": [ "status" ], "description": "Confirmation of successful deletion" } } } } } } }, "/api/projects/{projectId}/environments": { "get": { "operationId": "listEnvironments", "summary": "List environments", "tags": [ "Environment" ], "description": "Retrieves all environments for a project, including their deployment status and pending change requests.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "ID of the project to list environments for" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "List of environments for the project", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the environment" }, "name": { "type": "string", "description": "Name of the environment" }, "accessToken": { "type": "string", "nullable": true, "description": "Access token for the environment" }, "type": { "type": "string", "enum": [ "brms", "deployment" ], "description": "Type of environment (brms or deployment)" }, "key": { "type": "string", "nullable": true, "description": "Unique key for BRMS type environments" }, "release": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the release" }, "name": { "type": "string", "description": "Name of the release" }, "version": { "type": "number", "description": "Version number of the release (legacy)" }, "semanticVersion": { "type": "string", "description": "Semantic version string of the release" }, "status": { "type": "string", "description": "Status of the release" }, "createdAt": { "type": "string", "description": "Timestamp when the release was created" } }, "required": [ "id", "name", "status", "createdAt" ], "description": "Currently deployed release information" }, "releaseId": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of the currently deployed release" }, "deploymentId": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of the associated deployment" }, "deployment": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the deployment" }, "name": { "type": "string", "description": "Name of the deployment" }, "description": { "type": "string", "nullable": true, "description": "Description of the deployment" }, "provider": { "type": "string", "description": "Cloud provider for the deployment" }, "configuration": { "type": "object", "additionalProperties": {}, "description": "Provider-specific configuration" }, "organisationId": { "type": "string", "format": "uuid", "description": "ID of the organisation" }, "createdAt": { "type": "string", "description": "Timestamp when the deployment was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the deployment was last updated" }, "deletedAt": { "type": "string", "nullable": true, "description": "Timestamp when the deployment was deleted" } }, "required": [ "id", "name", "provider", "organisationId", "createdAt", "updatedAt" ], "description": "Deployment configuration for the environment" }, "projectId": { "type": "string", "format": "uuid", "description": "ID of the project" }, "project": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the project" }, "name": { "type": "string", "description": "Name of the project" }, "key": { "type": "string", "description": "Unique key of the project" } }, "required": [ "id", "name" ], "description": "Project the environment belongs to" }, "reviewers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the member" } }, "required": [ "id" ], "description": "Member assigned as reviewer" }, "description": "List of members assigned as reviewers" }, "requiredReviewers": { "type": "boolean", "description": "Whether reviewers are required" }, "addToWorkflow": { "type": "boolean", "description": "Whether the environment is part of the deployment workflow" }, "workflowOrder": { "type": "number", "nullable": true, "description": "Order position in the deployment workflow" }, "approvalGroups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the group" }, "name": { "type": "string", "description": "Name of the group" }, "description": { "type": "string", "description": "Description of the group" }, "projectId": { "type": "string", "format": "uuid", "description": "ID of the project the group belongs to" }, "roleId": { "type": "string", "format": "uuid", "description": "ID of the role assigned to the group" } }, "required": [ "id", "name", "projectId" ] }, "description": "Groups that can approve deployments" }, "approvalMode": { "type": "string", "enum": [ "require_one_per_team", "none_create_request", "require_any", "none" ], "description": "Approval mode for deployments to this environment" }, "changeRequests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the change request" }, "type": { "type": "string", "description": "Type of change request" }, "status": { "type": "string", "description": "Status of the change request" }, "createdAt": { "type": "string", "description": "Timestamp when the change request was created" } }, "required": [ "id", "type", "status", "createdAt" ], "description": "Change request associated with the environment" }, "description": "Pending change requests for this environment" }, "createdAt": { "type": "string", "description": "Timestamp when the environment was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the environment was last updated" }, "deletedAt": { "type": "string", "nullable": true, "description": "Timestamp when the environment was deleted" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional metadata from the deployment provider" } }, "required": [ "id", "name", "type", "projectId", "requiredReviewers", "addToWorkflow", "approvalGroups", "approvalMode", "createdAt", "updatedAt" ] }, "description": "List of environments for the project" } } } } } }, "post": { "operationId": "createEnvironment", "summary": "Create environment", "tags": [ "Environment" ], "description": "Creates a new environment within a project for deploying releases.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the environment" }, "key": { "type": "string", "nullable": true, "description": "Unique key for BRMS type environments (required when type is brms)" }, "type": { "type": "string", "enum": [ "brms", "deployment" ], "description": "Type of environment (brms or deployment)" }, "deploymentId": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of the deployment configuration (required when type is deployment)" }, "approvalMode": { "type": "string", "nullable": true, "enum": [ "require_one_per_team", "none_create_request", "require_any", "none", null ], "default": "none", "description": "Approval mode for deployments to this environment" }, "approvalGroups": { "type": "array", "items": { "type": "string", "format": "uuid", "description": "Group ID" }, "default": [], "description": "List of group IDs that can approve deployments" } }, "required": [ "name", "type" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "ID of the project to create the environment in" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "The created environment", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the environment" }, "name": { "type": "string", "description": "Name of the environment" }, "accessToken": { "type": "string", "nullable": true, "description": "Access token for the environment" }, "type": { "type": "string", "enum": [ "brms", "deployment" ], "description": "Type of environment (brms or deployment)" }, "key": { "type": "string", "nullable": true, "description": "Unique key for BRMS type environments" }, "release": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the release" }, "name": { "type": "string", "description": "Name of the release" }, "version": { "type": "number", "description": "Version number of the release (legacy)" }, "semanticVersion": { "type": "string", "description": "Semantic version string of the release" }, "status": { "type": "string", "description": "Status of the release" }, "createdAt": { "type": "string", "description": "Timestamp when the release was created" } }, "required": [ "id", "name", "status", "createdAt" ], "description": "Currently deployed release information" }, "releaseId": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of the currently deployed release" }, "deploymentId": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of the associated deployment" }, "deployment": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the deployment" }, "name": { "type": "string", "description": "Name of the deployment" }, "description": { "type": "string", "nullable": true, "description": "Description of the deployment" }, "provider": { "type": "string", "description": "Cloud provider for the deployment" }, "configuration": { "type": "object", "additionalProperties": {}, "description": "Provider-specific configuration" }, "organisationId": { "type": "string", "format": "uuid", "description": "ID of the organisation" }, "createdAt": { "type": "string", "description": "Timestamp when the deployment was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the deployment was last updated" }, "deletedAt": { "type": "string", "nullable": true, "description": "Timestamp when the deployment was deleted" } }, "required": [ "id", "name", "provider", "organisationId", "createdAt", "updatedAt" ], "description": "Deployment configuration for the environment" }, "projectId": { "type": "string", "format": "uuid", "description": "ID of the project" }, "project": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the project" }, "name": { "type": "string", "description": "Name of the project" }, "key": { "type": "string", "description": "Unique key of the project" } }, "required": [ "id", "name" ], "description": "Project the environment belongs to" }, "reviewers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the member" } }, "required": [ "id" ], "description": "Member assigned as reviewer" }, "description": "List of members assigned as reviewers" }, "requiredReviewers": { "type": "boolean", "description": "Whether reviewers are required" }, "addToWorkflow": { "type": "boolean", "description": "Whether the environment is part of the deployment workflow" }, "workflowOrder": { "type": "number", "nullable": true, "description": "Order position in the deployment workflow" }, "approvalGroups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the group" }, "name": { "type": "string", "description": "Name of the group" }, "description": { "type": "string", "description": "Description of the group" }, "projectId": { "type": "string", "format": "uuid", "description": "ID of the project the group belongs to" }, "roleId": { "type": "string", "format": "uuid", "description": "ID of the role assigned to the group" } }, "required": [ "id", "name", "projectId" ] }, "description": "Groups that can approve deployments" }, "approvalMode": { "type": "string", "enum": [ "require_one_per_team", "none_create_request", "require_any", "none" ], "description": "Approval mode for deployments to this environment" }, "changeRequests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the change request" }, "type": { "type": "string", "description": "Type of change request" }, "status": { "type": "string", "description": "Status of the change request" }, "createdAt": { "type": "string", "description": "Timestamp when the change request was created" } }, "required": [ "id", "type", "status", "createdAt" ], "description": "Change request associated with the environment" }, "description": "Pending change requests for this environment" }, "createdAt": { "type": "string", "description": "Timestamp when the environment was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the environment was last updated" }, "deletedAt": { "type": "string", "nullable": true, "description": "Timestamp when the environment was deleted" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional metadata from the deployment provider" } }, "required": [ "id", "name", "type", "projectId", "requiredReviewers", "addToWorkflow", "approvalGroups", "approvalMode", "createdAt", "updatedAt" ], "description": "The created environment" } } } } } } }, "/api/projects/{projectId}/environments/{environmentId}/regenerate-token": { "post": { "operationId": "regenerateEnvironmentToken", "summary": "Token regenerate", "tags": [ "Environment" ], "description": "Generates a new access token for the environment, invalidating the previous token.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "environmentId", "required": true, "description": "ID of the environment to regenerate the token for" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "ID of the project containing the environment" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "The environment with the new access token", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the environment" }, "name": { "type": "string", "description": "Name of the environment" }, "accessToken": { "type": "string", "description": "Newly generated access token" }, "type": { "type": "string", "enum": [ "brms", "deployment" ], "description": "Type of environment" }, "key": { "type": "string", "nullable": true, "description": "Unique key for BRMS type environments" }, "releaseId": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of the currently deployed release" }, "deploymentId": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of the associated deployment" }, "projectId": { "type": "string", "format": "uuid", "description": "ID of the project" }, "addToWorkflow": { "type": "boolean", "description": "Whether the environment is part of the deployment workflow" }, "workflowOrder": { "type": "number", "nullable": true, "description": "Order position in the deployment workflow" }, "requiredReviewers": { "type": "boolean", "description": "Whether reviewers are required" }, "approvalMode": { "type": "string", "nullable": true, "enum": [ "require_one_per_team", "none_create_request", "require_any", "none", null ], "description": "Approval mode for deployments" }, "createdAt": { "type": "string", "description": "Timestamp when the environment was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the environment was last updated" }, "deletedAt": { "type": "string", "nullable": true, "description": "Timestamp when the environment was deleted" } }, "required": [ "id", "name", "accessToken", "type", "projectId", "addToWorkflow", "requiredReviewers", "createdAt", "updatedAt" ], "description": "The environment with the new access token" } } } } } } }, "/api/projects/{projectId}/environments/{environmentId}/undeploy": { "post": { "operationId": "undeployEnvironment", "summary": "Undeploy environment", "tags": [ "Environment" ], "description": "Removes the currently deployed release from an environment, optionally creating a change request if approval is required.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "environmentId", "required": true, "description": "ID of the environment to undeploy" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "ID of the project containing the environment" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Environment successfully undeployed or change request created" } } } }, "/api/projects/{projectId}/environments/{environmentId}": { "put": { "operationId": "updateEnvironment", "summary": "Update environment", "tags": [ "Environment" ], "description": "Updates an existing environment configuration including name, key, and approval settings.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "New name for the environment" }, "key": { "type": "string", "nullable": true, "description": "New key for BRMS type environments" }, "approvalMode": { "type": "string", "nullable": true, "enum": [ "require_one_per_team", "none_create_request", "require_any", "none", null ], "default": "none", "description": "Approval mode for deployments to this environment" }, "approvalGroups": { "type": "array", "items": { "type": "string", "format": "uuid", "description": "Group ID" }, "default": [], "description": "List of group IDs that can approve deployments" } }, "required": [ "name" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "environmentId", "required": true, "description": "ID of the environment to update" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "ID of the project containing the environment" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "The updated environment", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the environment" }, "name": { "type": "string", "description": "Name of the environment" }, "accessToken": { "type": "string", "nullable": true, "description": "Access token for the environment" }, "type": { "type": "string", "enum": [ "brms", "deployment" ], "description": "Type of environment (brms or deployment)" }, "key": { "type": "string", "nullable": true, "description": "Unique key for BRMS type environments" }, "release": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the release" }, "name": { "type": "string", "description": "Name of the release" }, "version": { "type": "number", "description": "Version number of the release (legacy)" }, "semanticVersion": { "type": "string", "description": "Semantic version string of the release" }, "status": { "type": "string", "description": "Status of the release" }, "createdAt": { "type": "string", "description": "Timestamp when the release was created" } }, "required": [ "id", "name", "status", "createdAt" ], "description": "Currently deployed release information" }, "releaseId": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of the currently deployed release" }, "deploymentId": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of the associated deployment" }, "deployment": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the deployment" }, "name": { "type": "string", "description": "Name of the deployment" }, "description": { "type": "string", "nullable": true, "description": "Description of the deployment" }, "provider": { "type": "string", "description": "Cloud provider for the deployment" }, "configuration": { "type": "object", "additionalProperties": {}, "description": "Provider-specific configuration" }, "organisationId": { "type": "string", "format": "uuid", "description": "ID of the organisation" }, "createdAt": { "type": "string", "description": "Timestamp when the deployment was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the deployment was last updated" }, "deletedAt": { "type": "string", "nullable": true, "description": "Timestamp when the deployment was deleted" } }, "required": [ "id", "name", "provider", "organisationId", "createdAt", "updatedAt" ], "description": "Deployment configuration for the environment" }, "projectId": { "type": "string", "format": "uuid", "description": "ID of the project" }, "project": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the project" }, "name": { "type": "string", "description": "Name of the project" }, "key": { "type": "string", "description": "Unique key of the project" } }, "required": [ "id", "name" ], "description": "Project the environment belongs to" }, "reviewers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the member" } }, "required": [ "id" ], "description": "Member assigned as reviewer" }, "description": "List of members assigned as reviewers" }, "requiredReviewers": { "type": "boolean", "description": "Whether reviewers are required" }, "addToWorkflow": { "type": "boolean", "description": "Whether the environment is part of the deployment workflow" }, "workflowOrder": { "type": "number", "nullable": true, "description": "Order position in the deployment workflow" }, "approvalGroups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the group" }, "name": { "type": "string", "description": "Name of the group" }, "description": { "type": "string", "description": "Description of the group" }, "projectId": { "type": "string", "format": "uuid", "description": "ID of the project the group belongs to" }, "roleId": { "type": "string", "format": "uuid", "description": "ID of the role assigned to the group" } }, "required": [ "id", "name", "projectId" ] }, "description": "Groups that can approve deployments" }, "approvalMode": { "type": "string", "enum": [ "require_one_per_team", "none_create_request", "require_any", "none" ], "description": "Approval mode for deployments to this environment" }, "changeRequests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the change request" }, "type": { "type": "string", "description": "Type of change request" }, "status": { "type": "string", "description": "Status of the change request" }, "createdAt": { "type": "string", "description": "Timestamp when the change request was created" } }, "required": [ "id", "type", "status", "createdAt" ], "description": "Change request associated with the environment" }, "description": "Pending change requests for this environment" }, "createdAt": { "type": "string", "description": "Timestamp when the environment was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the environment was last updated" }, "deletedAt": { "type": "string", "nullable": true, "description": "Timestamp when the environment was deleted" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional metadata from the deployment provider" } }, "required": [ "id", "name", "type", "projectId", "requiredReviewers", "addToWorkflow", "approvalGroups", "approvalMode", "createdAt", "updatedAt" ], "description": "The updated environment" } } } } } }, "delete": { "operationId": "deleteEnvironment", "summary": "Delete environment", "tags": [ "Environment" ], "description": "Soft deletes an environment from the project.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "environmentId", "required": true, "description": "ID of the environment to delete" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "ID of the project containing the environment" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "The ID of the deleted environment", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID of the deleted environment" } }, "required": [ "id" ], "description": "The ID of the deleted environment" } } } } } } }, "/api/projects/{projectId}/documents": { "get": { "operationId": "listDocuments", "summary": "List documents", "tags": [ "Document" ], "description": "Retrieve a paginated list of documents for a project with optional filtering.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "parentId", "description": "Filter by parent document ID" }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "true", "false", "True", "False", "TRUE", "FALSE" ] }, { "type": "boolean" } ] }, "in": "query", "name": "deleted", "description": "Include only deleted documents" }, { "schema": { "type": "string" }, "in": "query", "name": "search", "description": "Search documents by name" }, { "schema": { "type": "string" }, "in": "query", "name": "key", "description": "Get a single document by exact key" }, { "schema": { "type": "string" }, "in": "query", "name": "keys", "description": "Comma separated list of document keys to retrieve" }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "true", "false", "True", "False", "TRUE", "FALSE" ] }, { "type": "boolean" } ] }, "in": "query", "name": "ancestors", "description": "Include ancestor documents" }, { "schema": { "type": "string" }, "in": "query", "name": "contentType", "description": "Filter by content type (comma separated)" }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "true", "false", "True", "False", "TRUE", "FALSE" ] }, { "type": "boolean" } ] }, "in": "query", "name": "directoriesOnly", "description": "Return only directory documents" }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "true", "false", "True", "False", "TRUE", "FALSE" ] }, { "type": "boolean" } ] }, "in": "query", "name": "directChildren", "description": "Return only direct children" }, { "schema": { "type": "number", "default": 1 }, "in": "query", "name": "page", "description": "Current page" }, { "schema": { "type": "number", "default": 10 }, "in": "query", "name": "perPage", "description": "Number of items per page" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project unique identifier" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Paginated list of documents", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Document unique identifier" }, "key": { "type": "string", "description": "Materialized lowercase path based on the name" }, "path": { "type": "string", "description": "Materialized path based on the name" }, "name": { "type": "string", "description": "Document name" }, "type": { "type": "string", "enum": [ "f", "d", "e" ], "description": "Document type (file, directory, or external file)" }, "meta": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Document metadata" }, "contentType": { "type": "string", "description": "Content MIME type" }, "size": { "type": "number", "description": "Document size in bytes" }, "parentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Parent document ID" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID" }, "publishedId": { "type": "string", "nullable": true, "format": "uuid", "description": "Currently published version ID" }, "publishedAt": { "type": "string", "nullable": true, "description": "Publication timestamp" }, "publishedBy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id" ], "description": "User who published the document" }, "published": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Version unique identifier" }, "name": { "type": "string", "nullable": true, "description": "Version name" }, "parentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Parent version ID for sub-versions" }, "status": { "type": "string", "description": "Version status (draft or completed)" }, "content": { "description": "Version content data" }, "documentId": { "type": "string", "format": "uuid", "description": "Associated document ID" }, "createdBy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id" ], "description": "User who created the version" }, "createdAt": { "type": "string", "description": "Version creation timestamp" }, "versions": { "type": "array", "items": {}, "description": "Sub-versions (recursive structure)" }, "releases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Release ID" }, "version": { "type": "string", "description": "Release version string" } }, "required": [ "id" ] }, "description": "Associated releases" } }, "required": [ "id" ], "description": "Published version details" }, "versions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Version unique identifier" }, "name": { "type": "string", "nullable": true, "description": "Version name" }, "parentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Parent version ID for sub-versions" }, "status": { "type": "string", "description": "Version status (draft or completed)" }, "content": { "description": "Version content data" }, "documentId": { "type": "string", "format": "uuid", "description": "Associated document ID" }, "createdBy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id" ], "description": "User who created the version" }, "createdAt": { "type": "string", "description": "Version creation timestamp" }, "versions": { "type": "array", "items": {}, "description": "Sub-versions (recursive structure)" }, "releases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Release ID" }, "version": { "type": "string", "description": "Release version string" } }, "required": [ "id" ] }, "description": "Associated releases" } }, "required": [ "id" ], "description": "Document version information" }, "description": "Document versions" }, "changeRequests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Change request unique identifier" }, "type": { "type": "string", "description": "Type of change request" }, "status": { "type": "string", "description": "Change request status" }, "createdAt": { "type": "string", "description": "Creation timestamp" } }, "required": [ "id", "type", "status" ], "description": "Change request information" }, "description": "Pending change requests" }, "view": { "type": "object", "nullable": true, "properties": { "description": { "type": "string", "nullable": true, "description": "View description" }, "permissions": { "type": "object", "nullable": true, "additionalProperties": { "type": "string", "enum": [ "edit:full", "edit:rules", "edit:values" ] }, "description": "View permissions mapping" } }, "description": "Document view configuration" }, "updatedAt": { "type": "string", "description": "Last update timestamp" }, "deletedAt": { "type": "string", "nullable": true, "description": "Deletion timestamp if soft deleted" } }, "required": [ "id", "key", "path", "name", "type", "projectId" ], "description": "Document entity" }, "description": "List of documents" }, "paginate": { "type": "object", "properties": { "current": { "type": "number", "description": "Current page number" }, "from": { "type": "number", "description": "Starting record number" }, "to": { "type": "number", "description": "Ending record number" }, "total": { "type": "number", "description": "Total number of records" }, "pageSize": { "type": "number", "description": "Number of records per page" } }, "required": [ "current", "from", "to", "total", "pageSize" ], "description": "Pagination metadata" } }, "required": [ "results", "paginate" ], "description": "Paginated list of documents" } } } } } }, "post": { "operationId": "createDocument", "summary": "Create a document", "tags": [ "Document" ], "description": "Create a new document or directory within a project.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "example": "Sample document", "description": "Document name" }, "type": { "type": "string", "enum": [ "f", "d", "e" ], "default": "f", "description": "Document type (file or directory)" }, "contentType": { "type": "string", "description": "Content MIME type for files" }, "content": { "nullable": true, "description": "Initial document content" }, "testEvent": { "type": "string", "nullable": true, "description": "Default test event context" }, "parent": { "type": "string", "description": "Parent directory key path" }, "duplicate": { "type": "boolean", "default": false, "description": "Allow duplicate names" }, "meta": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Document metadata" }, "source": { "type": "string", "description": "Source document key to copy content from" } }, "required": [ "name" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project unique identifier" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Newly created document", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Document unique identifier" }, "key": { "type": "string", "description": "Materialized lowercase path based on the name" }, "path": { "type": "string", "description": "Materialized path based on the name" }, "name": { "type": "string", "description": "Document name" }, "type": { "type": "string", "enum": [ "f", "d", "e" ], "description": "Document type (file, directory, or external file)" }, "meta": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Document metadata" }, "contentType": { "type": "string", "description": "Content MIME type" }, "size": { "type": "number", "description": "Document size in bytes" }, "parentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Parent document ID" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID" }, "publishedId": { "type": "string", "nullable": true, "format": "uuid", "description": "Currently published version ID" }, "publishedAt": { "type": "string", "nullable": true, "description": "Publication timestamp" }, "publishedBy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id" ], "description": "User who published the document" }, "published": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Version unique identifier" }, "name": { "type": "string", "nullable": true, "description": "Version name" }, "parentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Parent version ID for sub-versions" }, "status": { "type": "string", "description": "Version status (draft or completed)" }, "content": { "description": "Version content data" }, "documentId": { "type": "string", "format": "uuid", "description": "Associated document ID" }, "createdBy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id" ], "description": "User who created the version" }, "createdAt": { "type": "string", "description": "Version creation timestamp" }, "versions": { "type": "array", "items": {}, "description": "Sub-versions (recursive structure)" }, "releases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Release ID" }, "version": { "type": "string", "description": "Release version string" } }, "required": [ "id" ] }, "description": "Associated releases" } }, "required": [ "id" ], "description": "Published version details" }, "versions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Version unique identifier" }, "name": { "type": "string", "nullable": true, "description": "Version name" }, "parentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Parent version ID for sub-versions" }, "status": { "type": "string", "description": "Version status (draft or completed)" }, "content": { "description": "Version content data" }, "documentId": { "type": "string", "format": "uuid", "description": "Associated document ID" }, "createdBy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id" ], "description": "User who created the version" }, "createdAt": { "type": "string", "description": "Version creation timestamp" }, "versions": { "type": "array", "items": {}, "description": "Sub-versions (recursive structure)" }, "releases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Release ID" }, "version": { "type": "string", "description": "Release version string" } }, "required": [ "id" ] }, "description": "Associated releases" } }, "required": [ "id" ], "description": "Document version information" }, "description": "Document versions" }, "changeRequests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Change request unique identifier" }, "type": { "type": "string", "description": "Type of change request" }, "status": { "type": "string", "description": "Change request status" }, "createdAt": { "type": "string", "description": "Creation timestamp" } }, "required": [ "id", "type", "status" ], "description": "Change request information" }, "description": "Pending change requests" }, "view": { "type": "object", "nullable": true, "properties": { "description": { "type": "string", "nullable": true, "description": "View description" }, "permissions": { "type": "object", "nullable": true, "additionalProperties": { "type": "string", "enum": [ "edit:full", "edit:rules", "edit:values" ] }, "description": "View permissions mapping" } }, "description": "Document view configuration" }, "updatedAt": { "type": "string", "description": "Last update timestamp" }, "deletedAt": { "type": "string", "nullable": true, "description": "Deletion timestamp if soft deleted" } }, "required": [ "id", "key", "path", "name", "type", "projectId" ], "description": "Newly created document" } } } } } }, "delete": { "operationId": "deleteDocuments", "summary": "Delete documents", "tags": [ "Document" ], "description": "Soft delete one or more documents by moving them to trash.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "List of document IDs to delete" } }, "required": [ "ids" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project unique identifier" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "List of deleted document IDs", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "List of deleted document IDs" } } } } } } }, "/api/projects/{projectId}/documents/path": { "get": { "operationId": "getDocumentByPath", "summary": "Get documents by path", "tags": [ "Document" ], "description": "Retrieve a document by its file system path.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "path", "required": true, "description": "Document path to search for" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project unique identifier" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Document matching the specified path", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Document unique identifier" }, "key": { "type": "string", "description": "Materialized lowercase path based on the name" }, "path": { "type": "string", "description": "Materialized path based on the name" }, "name": { "type": "string", "description": "Document name" }, "type": { "type": "string", "enum": [ "f", "d", "e" ], "description": "Document type (file, directory, or external file)" }, "meta": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Document metadata" }, "contentType": { "type": "string", "description": "Content MIME type" }, "size": { "type": "number", "description": "Document size in bytes" }, "parentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Parent document ID" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID" }, "publishedId": { "type": "string", "nullable": true, "format": "uuid", "description": "Currently published version ID" }, "publishedAt": { "type": "string", "nullable": true, "description": "Publication timestamp" }, "publishedBy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id" ], "description": "User who published the document" }, "published": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Version unique identifier" }, "name": { "type": "string", "nullable": true, "description": "Version name" }, "parentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Parent version ID for sub-versions" }, "status": { "type": "string", "description": "Version status (draft or completed)" }, "content": { "description": "Version content data" }, "documentId": { "type": "string", "format": "uuid", "description": "Associated document ID" }, "createdBy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id" ], "description": "User who created the version" }, "createdAt": { "type": "string", "description": "Version creation timestamp" }, "versions": { "type": "array", "items": {}, "description": "Sub-versions (recursive structure)" }, "releases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Release ID" }, "version": { "type": "string", "description": "Release version string" } }, "required": [ "id" ] }, "description": "Associated releases" } }, "required": [ "id" ], "description": "Published version details" }, "versions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Version unique identifier" }, "name": { "type": "string", "nullable": true, "description": "Version name" }, "parentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Parent version ID for sub-versions" }, "status": { "type": "string", "description": "Version status (draft or completed)" }, "content": { "description": "Version content data" }, "documentId": { "type": "string", "format": "uuid", "description": "Associated document ID" }, "createdBy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id" ], "description": "User who created the version" }, "createdAt": { "type": "string", "description": "Version creation timestamp" }, "versions": { "type": "array", "items": {}, "description": "Sub-versions (recursive structure)" }, "releases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Release ID" }, "version": { "type": "string", "description": "Release version string" } }, "required": [ "id" ] }, "description": "Associated releases" } }, "required": [ "id" ], "description": "Document version information" }, "description": "Document versions" }, "changeRequests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Change request unique identifier" }, "type": { "type": "string", "description": "Type of change request" }, "status": { "type": "string", "description": "Change request status" }, "createdAt": { "type": "string", "description": "Creation timestamp" } }, "required": [ "id", "type", "status" ], "description": "Change request information" }, "description": "Pending change requests" }, "view": { "type": "object", "nullable": true, "properties": { "description": { "type": "string", "nullable": true, "description": "View description" }, "permissions": { "type": "object", "nullable": true, "additionalProperties": { "type": "string", "enum": [ "edit:full", "edit:rules", "edit:values" ] }, "description": "View permissions mapping" } }, "description": "Document view configuration" }, "updatedAt": { "type": "string", "description": "Last update timestamp" }, "deletedAt": { "type": "string", "nullable": true, "description": "Deletion timestamp if soft deleted" } }, "required": [ "id", "key", "path", "name", "type", "projectId" ], "description": "Document matching the specified path" } } } } } } }, "/api/projects/{projectId}/documents/list-paths": { "get": { "operationId": "listDocumentPaths", "summary": "List document paths", "tags": [ "Document" ], "description": "Retrieve a list of all published document paths in a project.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project unique identifier" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "List of document paths", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Document unique identifier" }, "path": { "type": "string", "description": "Document path" } }, "required": [ "id", "path" ], "description": "Document path information" }, "description": "List of document paths" } } } } } } }, "/api/projects/{projectId}/documents/move": { "post": { "operationId": "moveDocuments", "summary": "Move documents", "tags": [ "Document" ], "description": "Move one or more documents to a new parent directory.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "List of document IDs to move" }, "target": { "type": "string", "default": "/", "description": "Target directory path" } }, "required": [ "ids" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project unique identifier" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "List of moved documents", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Document unique identifier" }, "key": { "type": "string", "description": "Materialized lowercase path based on the name" }, "path": { "type": "string", "description": "Materialized path based on the name" }, "name": { "type": "string", "description": "Document name" }, "type": { "type": "string", "enum": [ "f", "d", "e" ], "description": "Document type (file, directory, or external file)" }, "meta": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Document metadata" }, "contentType": { "type": "string", "description": "Content MIME type" }, "size": { "type": "number", "description": "Document size in bytes" }, "parentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Parent document ID" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID" }, "publishedId": { "type": "string", "nullable": true, "format": "uuid", "description": "Currently published version ID" }, "publishedAt": { "type": "string", "nullable": true, "description": "Publication timestamp" }, "publishedBy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id" ], "description": "User who published the document" }, "published": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Version unique identifier" }, "name": { "type": "string", "nullable": true, "description": "Version name" }, "parentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Parent version ID for sub-versions" }, "status": { "type": "string", "description": "Version status (draft or completed)" }, "content": { "description": "Version content data" }, "documentId": { "type": "string", "format": "uuid", "description": "Associated document ID" }, "createdBy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id" ], "description": "User who created the version" }, "createdAt": { "type": "string", "description": "Version creation timestamp" }, "versions": { "type": "array", "items": {}, "description": "Sub-versions (recursive structure)" }, "releases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Release ID" }, "version": { "type": "string", "description": "Release version string" } }, "required": [ "id" ] }, "description": "Associated releases" } }, "required": [ "id" ], "description": "Published version details" }, "versions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Version unique identifier" }, "name": { "type": "string", "nullable": true, "description": "Version name" }, "parentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Parent version ID for sub-versions" }, "status": { "type": "string", "description": "Version status (draft or completed)" }, "content": { "description": "Version content data" }, "documentId": { "type": "string", "format": "uuid", "description": "Associated document ID" }, "createdBy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id" ], "description": "User who created the version" }, "createdAt": { "type": "string", "description": "Version creation timestamp" }, "versions": { "type": "array", "items": {}, "description": "Sub-versions (recursive structure)" }, "releases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Release ID" }, "version": { "type": "string", "description": "Release version string" } }, "required": [ "id" ] }, "description": "Associated releases" } }, "required": [ "id" ], "description": "Document version information" }, "description": "Document versions" }, "changeRequests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Change request unique identifier" }, "type": { "type": "string", "description": "Type of change request" }, "status": { "type": "string", "description": "Change request status" }, "createdAt": { "type": "string", "description": "Creation timestamp" } }, "required": [ "id", "type", "status" ], "description": "Change request information" }, "description": "Pending change requests" }, "view": { "type": "object", "nullable": true, "properties": { "description": { "type": "string", "nullable": true, "description": "View description" }, "permissions": { "type": "object", "nullable": true, "additionalProperties": { "type": "string", "enum": [ "edit:full", "edit:rules", "edit:values" ] }, "description": "View permissions mapping" } }, "description": "Document view configuration" }, "updatedAt": { "type": "string", "description": "Last update timestamp" }, "deletedAt": { "type": "string", "nullable": true, "description": "Deletion timestamp if soft deleted" } }, "required": [ "id", "key", "path", "name", "type", "projectId" ], "description": "Document entity" }, "description": "List of moved documents" } } } } } } }, "/api/projects/{projectId}/documents/{documentId}": { "get": { "operationId": "getDocument", "summary": "Get a document", "tags": [ "Document" ], "description": "Retrieve a single document by ID with its latest version and content.", "parameters": [ { "schema": { "anyOf": [ { "type": "string", "enum": [ "true", "false", "True", "False", "TRUE", "FALSE" ] }, { "type": "boolean" } ], "default": false }, "in": "query", "name": "deleted", "description": "Include deleted documents" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "documentId", "required": true, "description": "Document unique identifier" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project unique identifier" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Document with full details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Document unique identifier" }, "key": { "type": "string", "description": "Materialized lowercase path based on the name" }, "path": { "type": "string", "description": "Materialized path based on the name" }, "name": { "type": "string", "description": "Document name" }, "type": { "type": "string", "enum": [ "f", "d", "e" ], "description": "Document type (file, directory, or external file)" }, "meta": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Document metadata" }, "contentType": { "type": "string", "description": "Content MIME type" }, "size": { "type": "number", "description": "Document size in bytes" }, "parentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Parent document ID" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID" }, "publishedId": { "type": "string", "nullable": true, "format": "uuid", "description": "Currently published version ID" }, "publishedAt": { "type": "string", "nullable": true, "description": "Publication timestamp" }, "publishedBy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id" ], "description": "User who published the document" }, "published": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Version unique identifier" }, "name": { "type": "string", "nullable": true, "description": "Version name" }, "parentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Parent version ID for sub-versions" }, "status": { "type": "string", "description": "Version status (draft or completed)" }, "content": { "description": "Version content data" }, "documentId": { "type": "string", "format": "uuid", "description": "Associated document ID" }, "createdBy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id" ], "description": "User who created the version" }, "createdAt": { "type": "string", "description": "Version creation timestamp" }, "versions": { "type": "array", "items": {}, "description": "Sub-versions (recursive structure)" }, "releases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Release ID" }, "version": { "type": "string", "description": "Release version string" } }, "required": [ "id" ] }, "description": "Associated releases" } }, "required": [ "id" ], "description": "Published version details" }, "versions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Version unique identifier" }, "name": { "type": "string", "nullable": true, "description": "Version name" }, "parentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Parent version ID for sub-versions" }, "status": { "type": "string", "description": "Version status (draft or completed)" }, "content": { "description": "Version content data" }, "documentId": { "type": "string", "format": "uuid", "description": "Associated document ID" }, "createdBy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id" ], "description": "User who created the version" }, "createdAt": { "type": "string", "description": "Version creation timestamp" }, "versions": { "type": "array", "items": {}, "description": "Sub-versions (recursive structure)" }, "releases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Release ID" }, "version": { "type": "string", "description": "Release version string" } }, "required": [ "id" ] }, "description": "Associated releases" } }, "required": [ "id" ], "description": "Document version information" }, "description": "Document versions" }, "changeRequests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Change request unique identifier" }, "type": { "type": "string", "description": "Type of change request" }, "status": { "type": "string", "description": "Change request status" }, "createdAt": { "type": "string", "description": "Creation timestamp" } }, "required": [ "id", "type", "status" ], "description": "Change request information" }, "description": "Pending change requests" }, "view": { "type": "object", "nullable": true, "properties": { "description": { "type": "string", "nullable": true, "description": "View description" }, "permissions": { "type": "object", "nullable": true, "additionalProperties": { "type": "string", "enum": [ "edit:full", "edit:rules", "edit:values" ] }, "description": "View permissions mapping" } }, "description": "Document view configuration" }, "updatedAt": { "type": "string", "description": "Last update timestamp" }, "deletedAt": { "type": "string", "nullable": true, "description": "Deletion timestamp if soft deleted" } }, "required": [ "id", "key", "path", "name", "type", "projectId" ], "description": "Document with full details" } } } } } }, "put": { "operationId": "updateDocument", "summary": "Update a document", "tags": [ "Document" ], "description": "Update document properties such as name or metadata.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "example": "Sample document", "description": "New document name" }, "content": { "type": "object", "additionalProperties": true, "example": null, "description": "Document content to update" }, "meta": { "type": "object", "additionalProperties": { "type": "string" }, "example": null, "description": "Document metadata to merge" }, "publish": { "type": "boolean", "default": false, "description": "Whether to publish after updating" }, "deleted": { "type": "boolean", "default": false, "description": "Whether to include deleted documents" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "documentId", "required": true, "description": "Document unique identifier" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project unique identifier" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Updated document", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Document unique identifier" }, "key": { "type": "string", "description": "Materialized lowercase path based on the name" }, "path": { "type": "string", "description": "Materialized path based on the name" }, "name": { "type": "string", "description": "Document name" }, "type": { "type": "string", "enum": [ "f", "d", "e" ], "description": "Document type (file, directory, or external file)" }, "meta": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Document metadata" }, "contentType": { "type": "string", "description": "Content MIME type" }, "size": { "type": "number", "description": "Document size in bytes" }, "parentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Parent document ID" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID" }, "publishedId": { "type": "string", "nullable": true, "format": "uuid", "description": "Currently published version ID" }, "publishedAt": { "type": "string", "nullable": true, "description": "Publication timestamp" }, "publishedBy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id" ], "description": "User who published the document" }, "published": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Version unique identifier" }, "name": { "type": "string", "nullable": true, "description": "Version name" }, "parentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Parent version ID for sub-versions" }, "status": { "type": "string", "description": "Version status (draft or completed)" }, "content": { "description": "Version content data" }, "documentId": { "type": "string", "format": "uuid", "description": "Associated document ID" }, "createdBy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id" ], "description": "User who created the version" }, "createdAt": { "type": "string", "description": "Version creation timestamp" }, "versions": { "type": "array", "items": {}, "description": "Sub-versions (recursive structure)" }, "releases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Release ID" }, "version": { "type": "string", "description": "Release version string" } }, "required": [ "id" ] }, "description": "Associated releases" } }, "required": [ "id" ], "description": "Published version details" }, "versions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Version unique identifier" }, "name": { "type": "string", "nullable": true, "description": "Version name" }, "parentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Parent version ID for sub-versions" }, "status": { "type": "string", "description": "Version status (draft or completed)" }, "content": { "description": "Version content data" }, "documentId": { "type": "string", "format": "uuid", "description": "Associated document ID" }, "createdBy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id" ], "description": "User who created the version" }, "createdAt": { "type": "string", "description": "Version creation timestamp" }, "versions": { "type": "array", "items": {}, "description": "Sub-versions (recursive structure)" }, "releases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Release ID" }, "version": { "type": "string", "description": "Release version string" } }, "required": [ "id" ] }, "description": "Associated releases" } }, "required": [ "id" ], "description": "Document version information" }, "description": "Document versions" }, "changeRequests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Change request unique identifier" }, "type": { "type": "string", "description": "Type of change request" }, "status": { "type": "string", "description": "Change request status" }, "createdAt": { "type": "string", "description": "Creation timestamp" } }, "required": [ "id", "type", "status" ], "description": "Change request information" }, "description": "Pending change requests" }, "view": { "type": "object", "nullable": true, "properties": { "description": { "type": "string", "nullable": true, "description": "View description" }, "permissions": { "type": "object", "nullable": true, "additionalProperties": { "type": "string", "enum": [ "edit:full", "edit:rules", "edit:values" ] }, "description": "View permissions mapping" } }, "description": "Document view configuration" }, "updatedAt": { "type": "string", "description": "Last update timestamp" }, "deletedAt": { "type": "string", "nullable": true, "description": "Deletion timestamp if soft deleted" } }, "required": [ "id", "key", "path", "name", "type", "projectId" ], "description": "Updated document" } } } } } } }, "/api/projects/{projectId}/documents/{documentId}/ancestors": { "get": { "operationId": "listDocumentAncestors", "summary": "List document ancestors", "tags": [ "Document" ], "description": "Retrieve the ancestor hierarchy of a document from root to the specified document.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "documentId", "required": true, "description": "Document unique identifier" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project unique identifier" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "List of ancestor documents from root to current", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Document unique identifier" }, "key": { "type": "string", "description": "Document key path" }, "name": { "type": "string", "description": "Document name" }, "parentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Parent document ID" }, "originalPath": { "type": "string", "nullable": true, "description": "Original path before deletion" } }, "required": [ "id", "key", "name" ], "description": "Document ancestor information" }, "description": "List of ancestor documents from root to current" } } } } } } }, "/api/projects/{projectId}/documents/{documentId}/download": { "get": { "operationId": "downloadDocument", "summary": "Download a document", "tags": [ "Document" ], "description": "Download the document content as a JSON file.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "documentId", "required": true, "description": "Document unique identifier" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project unique identifier" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Document content as JSON file download", "content": { "application/json": { "schema": { "type": "string", "description": "Document content as JSON file download" } } } } } } }, "/api/projects/{projectId}/documents/{documentId}/publish": { "put": { "operationId": "publishDocument", "summary": "Publish a document", "tags": [ "Document" ], "description": "Publish or unpublish a document version, optionally creating a change request for approval.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "publish", "unpublish" ], "default": "publish", "description": "Action type: publish or unpublish" }, "versionId": { "type": "string", "format": "uuid", "description": "Version ID to publish (required for publish)" }, "comment": { "type": "string", "nullable": true, "description": "Comment for the change request" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "documentId", "required": true, "description": "Document unique identifier" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project unique identifier" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Document with updated publication status", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Document unique identifier" }, "key": { "type": "string", "description": "Materialized lowercase path based on the name" }, "path": { "type": "string", "description": "Materialized path based on the name" }, "name": { "type": "string", "description": "Document name" }, "type": { "type": "string", "enum": [ "f", "d", "e" ], "description": "Document type (file, directory, or external file)" }, "meta": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Document metadata" }, "contentType": { "type": "string", "description": "Content MIME type" }, "size": { "type": "number", "description": "Document size in bytes" }, "parentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Parent document ID" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID" }, "publishedId": { "type": "string", "nullable": true, "format": "uuid", "description": "Currently published version ID" }, "publishedAt": { "type": "string", "nullable": true, "description": "Publication timestamp" }, "publishedBy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id" ], "description": "User who published the document" }, "published": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Version unique identifier" }, "name": { "type": "string", "nullable": true, "description": "Version name" }, "parentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Parent version ID for sub-versions" }, "status": { "type": "string", "description": "Version status (draft or completed)" }, "content": { "description": "Version content data" }, "documentId": { "type": "string", "format": "uuid", "description": "Associated document ID" }, "createdBy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id" ], "description": "User who created the version" }, "createdAt": { "type": "string", "description": "Version creation timestamp" }, "versions": { "type": "array", "items": {}, "description": "Sub-versions (recursive structure)" }, "releases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Release ID" }, "version": { "type": "string", "description": "Release version string" } }, "required": [ "id" ] }, "description": "Associated releases" } }, "required": [ "id" ], "description": "Published version details" }, "versions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Version unique identifier" }, "name": { "type": "string", "nullable": true, "description": "Version name" }, "parentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Parent version ID for sub-versions" }, "status": { "type": "string", "description": "Version status (draft or completed)" }, "content": { "description": "Version content data" }, "documentId": { "type": "string", "format": "uuid", "description": "Associated document ID" }, "createdBy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id" ], "description": "User who created the version" }, "createdAt": { "type": "string", "description": "Version creation timestamp" }, "versions": { "type": "array", "items": {}, "description": "Sub-versions (recursive structure)" }, "releases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Release ID" }, "version": { "type": "string", "description": "Release version string" } }, "required": [ "id" ] }, "description": "Associated releases" } }, "required": [ "id" ], "description": "Document version information" }, "description": "Document versions" }, "changeRequests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Change request unique identifier" }, "type": { "type": "string", "description": "Type of change request" }, "status": { "type": "string", "description": "Change request status" }, "createdAt": { "type": "string", "description": "Creation timestamp" } }, "required": [ "id", "type", "status" ], "description": "Change request information" }, "description": "Pending change requests" }, "view": { "type": "object", "nullable": true, "properties": { "description": { "type": "string", "nullable": true, "description": "View description" }, "permissions": { "type": "object", "nullable": true, "additionalProperties": { "type": "string", "enum": [ "edit:full", "edit:rules", "edit:values" ] }, "description": "View permissions mapping" } }, "description": "Document view configuration" }, "updatedAt": { "type": "string", "description": "Last update timestamp" }, "deletedAt": { "type": "string", "nullable": true, "description": "Deletion timestamp if soft deleted" } }, "required": [ "id", "key", "path", "name", "type", "projectId" ], "description": "Document with updated publication status" } } } } } } }, "/api/projects/{projectId}/documents/permanently": { "delete": { "operationId": "permanentlyDeleteDocuments", "summary": "Permanently delete documents", "tags": [ "Document" ], "description": "Permanently remove soft-deleted documents from the system.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "List of document IDs to permanently delete" } }, "required": [ "ids" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project unique identifier" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "List of permanently deleted document IDs", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "List of permanently deleted document IDs" } } } } } } }, "/api/projects/{projectId}/documents/restore": { "post": { "operationId": "restoreDocuments", "summary": "Restore documents", "tags": [ "Document" ], "description": "Restore soft-deleted documents from trash to a specified location.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "List of document IDs to restore" }, "path": { "type": "string", "default": "/", "description": "Target path where to place restored documents" } }, "required": [ "ids" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project unique identifier" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Documents restored successfully" } } } }, "/api/projects/{projectId}/documents/{documentId}/versions": { "get": { "operationId": "listDocumentVersions", "summary": "List document versions", "tags": [ "Document" ], "description": "Retrieve a paginated list of versions for a specific document.", "parameters": [ { "schema": { "type": "number", "default": 1 }, "in": "query", "name": "page", "description": "Current page" }, { "schema": { "type": "number", "default": 10 }, "in": "query", "name": "perPage", "description": "Number of items per page" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "documentId", "required": true, "description": "Document unique identifier" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project unique identifier" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Paginated list of document versions", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Version unique identifier" }, "name": { "type": "string", "nullable": true, "description": "Version name" }, "parentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Parent version ID for sub-versions" }, "status": { "type": "string", "description": "Version status (draft or completed)" }, "content": { "description": "Version content data" }, "documentId": { "type": "string", "format": "uuid", "description": "Associated document ID" }, "createdBy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id" ], "description": "User who created the version" }, "createdAt": { "type": "string", "description": "Version creation timestamp" }, "versions": { "type": "array", "items": {}, "description": "Sub-versions (recursive structure)" }, "releases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Release ID" }, "version": { "type": "string", "description": "Release version string" } }, "required": [ "id" ] }, "description": "Associated releases" } }, "required": [ "id" ], "description": "Document version information" }, "description": "List of document versions" }, "paginate": { "type": "object", "properties": { "current": { "type": "number", "description": "Current page number" }, "from": { "type": "number", "description": "Starting record number" }, "to": { "type": "number", "description": "Ending record number" }, "total": { "type": "number", "description": "Total number of records" }, "pageSize": { "type": "number", "description": "Number of records per page" } }, "required": [ "current", "from", "to", "total", "pageSize" ], "description": "Pagination metadata" } }, "required": [ "results", "paginate" ], "description": "Paginated list of document versions" } } } } } }, "post": { "operationId": "createDocumentVersion", "summary": "Create a version", "tags": [ "Document" ], "description": "Create a new version of a document with updated content.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "nullable": true, "description": "Version name" }, "versionId": { "type": "string", "nullable": true, "format": "uuid", "description": "Optional version ID to use" }, "content": { "type": "object", "nullable": true, "additionalProperties": true, "example": null, "description": "Version content" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "documentId", "required": true, "description": "Document unique identifier" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project unique identifier" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Document with the new version", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Document unique identifier" }, "key": { "type": "string", "description": "Materialized lowercase path based on the name" }, "path": { "type": "string", "description": "Materialized path based on the name" }, "name": { "type": "string", "description": "Document name" }, "type": { "type": "string", "enum": [ "f", "d", "e" ], "description": "Document type (file, directory, or external file)" }, "meta": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Document metadata" }, "contentType": { "type": "string", "description": "Content MIME type" }, "size": { "type": "number", "description": "Document size in bytes" }, "parentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Parent document ID" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID" }, "publishedId": { "type": "string", "nullable": true, "format": "uuid", "description": "Currently published version ID" }, "publishedAt": { "type": "string", "nullable": true, "description": "Publication timestamp" }, "publishedBy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id" ], "description": "User who published the document" }, "published": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Version unique identifier" }, "name": { "type": "string", "nullable": true, "description": "Version name" }, "parentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Parent version ID for sub-versions" }, "status": { "type": "string", "description": "Version status (draft or completed)" }, "content": { "description": "Version content data" }, "documentId": { "type": "string", "format": "uuid", "description": "Associated document ID" }, "createdBy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id" ], "description": "User who created the version" }, "createdAt": { "type": "string", "description": "Version creation timestamp" }, "versions": { "type": "array", "items": {}, "description": "Sub-versions (recursive structure)" }, "releases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Release ID" }, "version": { "type": "string", "description": "Release version string" } }, "required": [ "id" ] }, "description": "Associated releases" } }, "required": [ "id" ], "description": "Published version details" }, "versions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Version unique identifier" }, "name": { "type": "string", "nullable": true, "description": "Version name" }, "parentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Parent version ID for sub-versions" }, "status": { "type": "string", "description": "Version status (draft or completed)" }, "content": { "description": "Version content data" }, "documentId": { "type": "string", "format": "uuid", "description": "Associated document ID" }, "createdBy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id" ], "description": "User who created the version" }, "createdAt": { "type": "string", "description": "Version creation timestamp" }, "versions": { "type": "array", "items": {}, "description": "Sub-versions (recursive structure)" }, "releases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Release ID" }, "version": { "type": "string", "description": "Release version string" } }, "required": [ "id" ] }, "description": "Associated releases" } }, "required": [ "id" ], "description": "Document version information" }, "description": "Document versions" }, "changeRequests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Change request unique identifier" }, "type": { "type": "string", "description": "Type of change request" }, "status": { "type": "string", "description": "Change request status" }, "createdAt": { "type": "string", "description": "Creation timestamp" } }, "required": [ "id", "type", "status" ], "description": "Change request information" }, "description": "Pending change requests" }, "view": { "type": "object", "nullable": true, "properties": { "description": { "type": "string", "nullable": true, "description": "View description" }, "permissions": { "type": "object", "nullable": true, "additionalProperties": { "type": "string", "enum": [ "edit:full", "edit:rules", "edit:values" ] }, "description": "View permissions mapping" } }, "description": "Document view configuration" }, "updatedAt": { "type": "string", "description": "Last update timestamp" }, "deletedAt": { "type": "string", "nullable": true, "description": "Deletion timestamp if soft deleted" } }, "required": [ "id", "key", "path", "name", "type", "projectId" ], "description": "Document with the new version" } } } } } } }, "/api/projects/{projectId}/documents/{documentId}/versions/{versionId}/rename": { "put": { "operationId": "renameDocumentVersion", "summary": "Rename a version", "tags": [ "Document" ], "description": "Update the name of a document version.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "nullable": true, "description": "New version name (null to clear)" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "documentId", "required": true, "description": "Document unique identifier" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project unique identifier" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "versionId", "required": true, "description": "Version unique identifier" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Updated document version", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Version unique identifier" }, "name": { "type": "string", "nullable": true, "description": "Version name" }, "parentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Parent version ID for sub-versions" }, "status": { "type": "string", "description": "Version status (draft or completed)" }, "content": { "description": "Version content data" }, "documentId": { "type": "string", "format": "uuid", "description": "Associated document ID" }, "createdBy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id" ], "description": "User who created the version" }, "createdAt": { "type": "string", "description": "Version creation timestamp" }, "versions": { "type": "array", "items": {}, "description": "Sub-versions (recursive structure)" }, "releases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Release ID" }, "version": { "type": "string", "description": "Release version string" } }, "required": [ "id" ] }, "description": "Associated releases" } }, "required": [ "id" ], "description": "Updated document version" } } } } } } }, "/api/projects/{projectId}/documents/{documentId}/versions/restore": { "post": { "operationId": "restoreDocumentVersion", "summary": "Restore document version", "tags": [ "Document" ], "description": "Restore a document to a previous version by creating a new version with the old content.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "versionId": { "type": "string", "format": "uuid", "description": "Version ID to restore from" } }, "required": [ "versionId" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "documentId", "required": true, "description": "Document unique identifier" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project unique identifier" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Document with restored version", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Document unique identifier" }, "key": { "type": "string", "description": "Materialized lowercase path based on the name" }, "path": { "type": "string", "description": "Materialized path based on the name" }, "name": { "type": "string", "description": "Document name" }, "type": { "type": "string", "enum": [ "f", "d", "e" ], "description": "Document type (file, directory, or external file)" }, "meta": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Document metadata" }, "contentType": { "type": "string", "description": "Content MIME type" }, "size": { "type": "number", "description": "Document size in bytes" }, "parentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Parent document ID" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID" }, "publishedId": { "type": "string", "nullable": true, "format": "uuid", "description": "Currently published version ID" }, "publishedAt": { "type": "string", "nullable": true, "description": "Publication timestamp" }, "publishedBy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id" ], "description": "User who published the document" }, "published": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Version unique identifier" }, "name": { "type": "string", "nullable": true, "description": "Version name" }, "parentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Parent version ID for sub-versions" }, "status": { "type": "string", "description": "Version status (draft or completed)" }, "content": { "description": "Version content data" }, "documentId": { "type": "string", "format": "uuid", "description": "Associated document ID" }, "createdBy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id" ], "description": "User who created the version" }, "createdAt": { "type": "string", "description": "Version creation timestamp" }, "versions": { "type": "array", "items": {}, "description": "Sub-versions (recursive structure)" }, "releases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Release ID" }, "version": { "type": "string", "description": "Release version string" } }, "required": [ "id" ] }, "description": "Associated releases" } }, "required": [ "id" ], "description": "Published version details" }, "versions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Version unique identifier" }, "name": { "type": "string", "nullable": true, "description": "Version name" }, "parentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Parent version ID for sub-versions" }, "status": { "type": "string", "description": "Version status (draft or completed)" }, "content": { "description": "Version content data" }, "documentId": { "type": "string", "format": "uuid", "description": "Associated document ID" }, "createdBy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id" ], "description": "User who created the version" }, "createdAt": { "type": "string", "description": "Version creation timestamp" }, "versions": { "type": "array", "items": {}, "description": "Sub-versions (recursive structure)" }, "releases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Release ID" }, "version": { "type": "string", "description": "Release version string" } }, "required": [ "id" ] }, "description": "Associated releases" } }, "required": [ "id" ], "description": "Document version information" }, "description": "Document versions" }, "changeRequests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Change request unique identifier" }, "type": { "type": "string", "description": "Type of change request" }, "status": { "type": "string", "description": "Change request status" }, "createdAt": { "type": "string", "description": "Creation timestamp" } }, "required": [ "id", "type", "status" ], "description": "Change request information" }, "description": "Pending change requests" }, "view": { "type": "object", "nullable": true, "properties": { "description": { "type": "string", "nullable": true, "description": "View description" }, "permissions": { "type": "object", "nullable": true, "additionalProperties": { "type": "string", "enum": [ "edit:full", "edit:rules", "edit:values" ] }, "description": "View permissions mapping" } }, "description": "Document view configuration" }, "updatedAt": { "type": "string", "description": "Last update timestamp" }, "deletedAt": { "type": "string", "nullable": true, "description": "Deletion timestamp if soft deleted" } }, "required": [ "id", "key", "path", "name", "type", "projectId" ], "description": "Document with restored version" } } } } } } }, "/api/projects/{projectId}/documents/{documentId}/versions/{versionId}": { "get": { "operationId": "getDocumentVersion", "summary": "Get a document version", "tags": [ "Document" ], "description": "Retrieve a specific version of a document including its content.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "documentId", "required": true, "description": "Document unique identifier" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project unique identifier" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "versionId", "required": true, "description": "Version unique identifier" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Document version with content", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Version unique identifier" }, "name": { "type": "string", "nullable": true, "description": "Version name" }, "parentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Parent version ID for sub-versions" }, "status": { "type": "string", "description": "Version status (draft or completed)" }, "content": { "description": "Version content data" }, "documentId": { "type": "string", "format": "uuid", "description": "Associated document ID" }, "createdBy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id" ], "description": "User who created the version" }, "createdAt": { "type": "string", "description": "Version creation timestamp" }, "versions": { "type": "array", "items": {}, "description": "Sub-versions (recursive structure)" }, "releases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Release ID" }, "version": { "type": "string", "description": "Release version string" } }, "required": [ "id" ] }, "description": "Associated releases" } }, "required": [ "id" ], "description": "Document version with content" } } } } } } }, "/api/projects/{projectId}/documents/{documentId}/view": { "put": { "operationId": "updateDocumentView", "summary": "Update a document view", "tags": [ "Document" ], "description": "Update the view configuration and permissions for a document.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "view": { "type": "object", "nullable": true, "properties": { "description": { "type": "string", "nullable": true, "description": "View description text" }, "permissions": { "type": "object", "nullable": true, "additionalProperties": { "type": "string", "enum": [ "edit:full", "edit:rules", "edit:values" ] }, "default": null, "description": "Permission mapping by group ID" } }, "default": null, "description": "View configuration (null to remove)" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "documentId", "required": true, "description": "Document unique identifier" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project unique identifier" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Document with updated view configuration", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Document unique identifier" }, "key": { "type": "string", "description": "Materialized lowercase path based on the name" }, "path": { "type": "string", "description": "Materialized path based on the name" }, "name": { "type": "string", "description": "Document name" }, "type": { "type": "string", "enum": [ "f", "d", "e" ], "description": "Document type (file, directory, or external file)" }, "meta": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Document metadata" }, "contentType": { "type": "string", "description": "Content MIME type" }, "size": { "type": "number", "description": "Document size in bytes" }, "parentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Parent document ID" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID" }, "publishedId": { "type": "string", "nullable": true, "format": "uuid", "description": "Currently published version ID" }, "publishedAt": { "type": "string", "nullable": true, "description": "Publication timestamp" }, "publishedBy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id" ], "description": "User who published the document" }, "published": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Version unique identifier" }, "name": { "type": "string", "nullable": true, "description": "Version name" }, "parentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Parent version ID for sub-versions" }, "status": { "type": "string", "description": "Version status (draft or completed)" }, "content": { "description": "Version content data" }, "documentId": { "type": "string", "format": "uuid", "description": "Associated document ID" }, "createdBy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id" ], "description": "User who created the version" }, "createdAt": { "type": "string", "description": "Version creation timestamp" }, "versions": { "type": "array", "items": {}, "description": "Sub-versions (recursive structure)" }, "releases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Release ID" }, "version": { "type": "string", "description": "Release version string" } }, "required": [ "id" ] }, "description": "Associated releases" } }, "required": [ "id" ], "description": "Published version details" }, "versions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Version unique identifier" }, "name": { "type": "string", "nullable": true, "description": "Version name" }, "parentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Parent version ID for sub-versions" }, "status": { "type": "string", "description": "Version status (draft or completed)" }, "content": { "description": "Version content data" }, "documentId": { "type": "string", "format": "uuid", "description": "Associated document ID" }, "createdBy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id" ], "description": "User who created the version" }, "createdAt": { "type": "string", "description": "Version creation timestamp" }, "versions": { "type": "array", "items": {}, "description": "Sub-versions (recursive structure)" }, "releases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Release ID" }, "version": { "type": "string", "description": "Release version string" } }, "required": [ "id" ] }, "description": "Associated releases" } }, "required": [ "id" ], "description": "Document version information" }, "description": "Document versions" }, "changeRequests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Change request unique identifier" }, "type": { "type": "string", "description": "Type of change request" }, "status": { "type": "string", "description": "Change request status" }, "createdAt": { "type": "string", "description": "Creation timestamp" } }, "required": [ "id", "type", "status" ], "description": "Change request information" }, "description": "Pending change requests" }, "view": { "type": "object", "nullable": true, "properties": { "description": { "type": "string", "nullable": true, "description": "View description" }, "permissions": { "type": "object", "nullable": true, "additionalProperties": { "type": "string", "enum": [ "edit:full", "edit:rules", "edit:values" ] }, "description": "View permissions mapping" } }, "description": "Document view configuration" }, "updatedAt": { "type": "string", "description": "Last update timestamp" }, "deletedAt": { "type": "string", "nullable": true, "description": "Deletion timestamp if soft deleted" } }, "required": [ "id", "key", "path", "name", "type", "projectId" ], "description": "Document with updated view configuration" } } } } } } }, "/api/projects/{projectId}/change-requests": { "get": { "operationId": "listChangeRequests", "summary": "List change requests", "tags": [ "Change requests" ], "description": "Retrieve a paginated list of change requests for a project. Supports filtering by document, release, type, and status.", "parameters": [ { "schema": { "type": "number", "default": 1 }, "in": "query", "name": "page", "description": "Current page" }, { "schema": { "type": "number", "default": 10 }, "in": "query", "name": "perPage", "description": "Number of items per page" }, { "schema": { "type": "string", "nullable": true, "format": "uuid" }, "in": "query", "name": "documentId", "description": "Filter by document ID" }, { "schema": { "type": "string", "nullable": true, "format": "uuid" }, "in": "query", "name": "releaseId", "description": "Filter by release ID" }, { "schema": { "nullable": true, "anyOf": [ { "type": "array", "items": { "type": "string", "enum": [ "decisions", "deployments", "publish_document", "unpublish_document", "deploy_environment", "undeploy_environment" ] } }, { "type": "string", "enum": [ "decisions", "deployments", "publish_document", "unpublish_document", "deploy_environment", "undeploy_environment" ] } ] }, "in": "query", "name": "type", "description": "Filter by change request type(s)" }, { "schema": { "type": "string", "nullable": true, "enum": [ "pending", "closed", null ] }, "in": "query", "name": "status", "description": "Filter by status (pending or closed)" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project unique identifier" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Paginated list of change requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Change request unique identifier" }, "type": { "type": "string", "enum": [ "publish_document", "unpublish_document", "deploy_environment", "undeploy_environment", "merge_branch" ], "description": "Type of change request" }, "status": { "type": "string", "enum": [ "pending", "rejected", "cancelled", "completed" ], "description": "Current status of the change request" }, "description": { "type": "string", "nullable": true, "description": "Change request description" }, "projectId": { "type": "string", "format": "uuid", "description": "Project unique identifier" }, "document": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Document unique identifier" }, "name": { "type": "string", "description": "Document name" }, "key": { "type": "string", "nullable": true, "description": "Document key" } }, "required": [ "id", "name" ], "description": "Document information" }, "documentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Document unique identifier" }, "environment": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Environment unique identifier" }, "name": { "type": "string", "description": "Environment name" } }, "required": [ "id", "name" ], "description": "Environment information" }, "environmentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Environment unique identifier" }, "release": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Release unique identifier" }, "name": { "type": "string", "description": "Release name" }, "version": { "type": "string", "nullable": true, "description": "Release version" } }, "required": [ "id", "name" ], "description": "Release information" }, "releaseId": { "type": "string", "nullable": true, "format": "uuid", "description": "Release unique identifier" }, "branch": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Branch unique identifier" }, "name": { "type": "string", "description": "Branch name" } }, "required": [ "id", "name" ], "description": "Branch information" }, "branchId": { "type": "string", "nullable": true, "format": "uuid", "description": "Branch unique identifier" }, "commit": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Commit unique identifier" }, "message": { "type": "string", "nullable": true, "description": "Commit message" } }, "required": [ "id" ], "description": "Commit information" }, "createdAt": { "type": "string", "description": "Change request creation timestamp" }, "createdBy": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id", "email", "firstName", "lastName" ], "description": "User information" }, "updatedAt": { "type": "string", "description": "Change request last update timestamp" } }, "required": [ "id", "type", "status", "projectId", "createdAt", "updatedAt" ], "description": "Change request" }, "description": "List of change requests" }, "paginate": { "type": "object", "properties": { "current": { "type": "number", "description": "Current page number" }, "from": { "type": "number", "description": "Starting record number" }, "to": { "type": "number", "description": "Ending record number" }, "total": { "type": "number", "description": "Total number of records" }, "pageSize": { "type": "number", "description": "Number of records per page" } }, "required": [ "current", "from", "to", "total", "pageSize" ], "description": "Pagination metadata" } }, "required": [ "results", "paginate" ], "description": "Paginated list of change requests" } } } } } } }, "/api/projects/{projectId}/change-requests/{changeRequestId}": { "get": { "operationId": "getChangeRequest", "summary": "Get a change request", "tags": [ "Change requests" ], "description": "Retrieve a single change request by ID, including activities, snapshot, and related entities.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project unique identifier" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "changeRequestId", "required": true, "description": "Change request unique identifier" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Change request with full details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Change request unique identifier" }, "type": { "type": "string", "enum": [ "publish_document", "unpublish_document", "deploy_environment", "undeploy_environment", "merge_branch" ], "description": "Type of change request" }, "status": { "type": "string", "enum": [ "pending", "rejected", "cancelled", "completed" ], "description": "Current status of the change request" }, "description": { "type": "string", "nullable": true, "description": "Change request description" }, "projectId": { "type": "string", "format": "uuid", "description": "Project unique identifier" }, "document": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Document unique identifier" }, "name": { "type": "string", "description": "Document name" }, "key": { "type": "string", "nullable": true, "description": "Document key" } }, "required": [ "id", "name" ], "description": "Document information" }, "documentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Document unique identifier" }, "environment": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Environment unique identifier" }, "name": { "type": "string", "description": "Environment name" } }, "required": [ "id", "name" ], "description": "Environment information" }, "environmentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Environment unique identifier" }, "release": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Release unique identifier" }, "name": { "type": "string", "description": "Release name" }, "version": { "type": "string", "nullable": true, "description": "Release version" } }, "required": [ "id", "name" ], "description": "Release information" }, "releaseId": { "type": "string", "nullable": true, "format": "uuid", "description": "Release unique identifier" }, "branch": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Branch unique identifier" }, "name": { "type": "string", "description": "Branch name" } }, "required": [ "id", "name" ], "description": "Branch information" }, "branchId": { "type": "string", "nullable": true, "format": "uuid", "description": "Branch unique identifier" }, "commit": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Commit unique identifier" }, "message": { "type": "string", "nullable": true, "description": "Commit message" } }, "required": [ "id" ], "description": "Commit information" }, "createdAt": { "type": "string", "description": "Change request creation timestamp" }, "createdBy": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id", "email", "firstName", "lastName" ], "description": "User information" }, "updatedAt": { "type": "string", "description": "Change request last update timestamp" }, "activities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Activity unique identifier" }, "type": { "type": "string", "enum": [ "create", "comment", "approve", "unapprove", "reject", "cancel", "complete" ], "description": "Activity type" }, "comment": { "type": "string", "nullable": true, "description": "Activity comment" }, "createdAt": { "type": "string", "description": "Activity creation timestamp" }, "createdBy": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id", "email", "firstName", "lastName" ], "description": "User information" }, "updatedAt": { "type": "string", "description": "Activity last update timestamp" } }, "required": [ "id", "type", "createdAt", "updatedAt" ], "description": "Change request activity" }, "description": "List of activities" }, "snapshot": { "type": "object", "properties": { "approvalMode": { "type": "string", "nullable": true, "description": "Approval mode" }, "approvalGroups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Approval group unique identifier" }, "name": { "type": "string", "description": "Approval group name" }, "description": { "type": "string", "nullable": true, "description": "Approval group description" }, "status": { "type": "string", "enum": [ "pending", "approved" ], "description": "Approval group status" }, "approvals": { "type": "array", "items": {}, "description": "List of approvals for this group" } }, "required": [ "id", "name", "status", "approvals" ], "description": "Approval group information" }, "description": "List of approval groups" }, "approvals": { "type": "array", "items": {}, "description": "List of approvals" }, "canComplete": { "type": "boolean", "description": "Whether the change request can be completed" } }, "description": "Change request snapshot containing approval state" }, "documentVersion": { "nullable": true, "description": "Document version being published" }, "previousDocumentVersion": { "nullable": true, "description": "Previous document version" }, "previousRelease": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Release unique identifier" }, "name": { "type": "string", "description": "Release name" }, "version": { "type": "string", "nullable": true, "description": "Release version" } }, "required": [ "id", "name" ], "description": "Release information" }, "previousReleaseId": { "type": "string", "nullable": true, "format": "uuid", "description": "Previous release unique identifier" } }, "required": [ "id", "type", "status", "projectId", "createdAt", "updatedAt" ], "description": "Change request with full details" } } } } } } }, "/api/projects/{projectId}/change-requests/{changeRequestId}/activities": { "post": { "operationId": "createChangeRequestActivity", "summary": "Create activity", "tags": [ "Change requests" ], "description": "Create a new activity on a change request. Activities include approval, rejection, comments, and completion actions.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "create", "comment", "approve", "unapprove", "reject", "cancel", "complete" ], "description": "Activity type to perform" }, "comment": { "type": "string", "nullable": true, "description": "Optional comment for the activity" }, "requestChange": { "type": "boolean", "default": false, "description": "Whether to request changes" } }, "required": [ "type" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project unique identifier" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "changeRequestId", "required": true, "description": "Change request unique identifier" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Updated change request with the new activity", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Change request unique identifier" }, "type": { "type": "string", "enum": [ "publish_document", "unpublish_document", "deploy_environment", "undeploy_environment", "merge_branch" ], "description": "Type of change request" }, "status": { "type": "string", "enum": [ "pending", "rejected", "cancelled", "completed" ], "description": "Current status of the change request" }, "description": { "type": "string", "nullable": true, "description": "Change request description" }, "projectId": { "type": "string", "format": "uuid", "description": "Project unique identifier" }, "document": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Document unique identifier" }, "name": { "type": "string", "description": "Document name" }, "key": { "type": "string", "nullable": true, "description": "Document key" } }, "required": [ "id", "name" ], "description": "Document information" }, "documentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Document unique identifier" }, "environment": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Environment unique identifier" }, "name": { "type": "string", "description": "Environment name" } }, "required": [ "id", "name" ], "description": "Environment information" }, "environmentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Environment unique identifier" }, "release": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Release unique identifier" }, "name": { "type": "string", "description": "Release name" }, "version": { "type": "string", "nullable": true, "description": "Release version" } }, "required": [ "id", "name" ], "description": "Release information" }, "releaseId": { "type": "string", "nullable": true, "format": "uuid", "description": "Release unique identifier" }, "branch": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Branch unique identifier" }, "name": { "type": "string", "description": "Branch name" } }, "required": [ "id", "name" ], "description": "Branch information" }, "branchId": { "type": "string", "nullable": true, "format": "uuid", "description": "Branch unique identifier" }, "commit": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Commit unique identifier" }, "message": { "type": "string", "nullable": true, "description": "Commit message" } }, "required": [ "id" ], "description": "Commit information" }, "createdAt": { "type": "string", "description": "Change request creation timestamp" }, "createdBy": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id", "email", "firstName", "lastName" ], "description": "User information" }, "updatedAt": { "type": "string", "description": "Change request last update timestamp" }, "activities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Activity unique identifier" }, "type": { "type": "string", "enum": [ "create", "comment", "approve", "unapprove", "reject", "cancel", "complete" ], "description": "Activity type" }, "comment": { "type": "string", "nullable": true, "description": "Activity comment" }, "createdAt": { "type": "string", "description": "Activity creation timestamp" }, "createdBy": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id", "email", "firstName", "lastName" ], "description": "User information" }, "updatedAt": { "type": "string", "description": "Activity last update timestamp" } }, "required": [ "id", "type", "createdAt", "updatedAt" ], "description": "Change request activity" }, "description": "List of activities" }, "snapshot": { "type": "object", "properties": { "approvalMode": { "type": "string", "nullable": true, "description": "Approval mode" }, "approvalGroups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Approval group unique identifier" }, "name": { "type": "string", "description": "Approval group name" }, "description": { "type": "string", "nullable": true, "description": "Approval group description" }, "status": { "type": "string", "enum": [ "pending", "approved" ], "description": "Approval group status" }, "approvals": { "type": "array", "items": {}, "description": "List of approvals for this group" } }, "required": [ "id", "name", "status", "approvals" ], "description": "Approval group information" }, "description": "List of approval groups" }, "approvals": { "type": "array", "items": {}, "description": "List of approvals" }, "canComplete": { "type": "boolean", "description": "Whether the change request can be completed" } }, "description": "Change request snapshot containing approval state" }, "documentVersion": { "nullable": true, "description": "Document version being published" }, "previousDocumentVersion": { "nullable": true, "description": "Previous document version" }, "previousRelease": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Release unique identifier" }, "name": { "type": "string", "description": "Release name" }, "version": { "type": "string", "nullable": true, "description": "Release version" } }, "required": [ "id", "name" ], "description": "Release information" }, "previousReleaseId": { "type": "string", "nullable": true, "format": "uuid", "description": "Previous release unique identifier" } }, "required": [ "id", "type", "status", "projectId", "createdAt", "updatedAt" ], "description": "Updated change request with the new activity" } } } } } } }, "/api/projects/{projectId}/change-requests/{changeRequestId}/activities/{activityId}": { "put": { "operationId": "updateChangeRequestActivity", "summary": "Update activity", "tags": [ "Change requests" ], "description": "Update an existing activity on a change request. Allows modifying the comment or resolving the activity.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "type": "string", "nullable": true, "description": "Updated comment for the activity" }, "resolve": { "type": "boolean", "nullable": true, "default": false, "description": "Whether to mark the activity as resolved" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project unique identifier" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "changeRequestId", "required": true, "description": "Change request unique identifier" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "activityId", "required": true, "description": "Activity unique identifier" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Updated change request with the modified activity", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Change request unique identifier" }, "type": { "type": "string", "enum": [ "publish_document", "unpublish_document", "deploy_environment", "undeploy_environment", "merge_branch" ], "description": "Type of change request" }, "status": { "type": "string", "enum": [ "pending", "rejected", "cancelled", "completed" ], "description": "Current status of the change request" }, "description": { "type": "string", "nullable": true, "description": "Change request description" }, "projectId": { "type": "string", "format": "uuid", "description": "Project unique identifier" }, "document": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Document unique identifier" }, "name": { "type": "string", "description": "Document name" }, "key": { "type": "string", "nullable": true, "description": "Document key" } }, "required": [ "id", "name" ], "description": "Document information" }, "documentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Document unique identifier" }, "environment": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Environment unique identifier" }, "name": { "type": "string", "description": "Environment name" } }, "required": [ "id", "name" ], "description": "Environment information" }, "environmentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Environment unique identifier" }, "release": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Release unique identifier" }, "name": { "type": "string", "description": "Release name" }, "version": { "type": "string", "nullable": true, "description": "Release version" } }, "required": [ "id", "name" ], "description": "Release information" }, "releaseId": { "type": "string", "nullable": true, "format": "uuid", "description": "Release unique identifier" }, "branch": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Branch unique identifier" }, "name": { "type": "string", "description": "Branch name" } }, "required": [ "id", "name" ], "description": "Branch information" }, "branchId": { "type": "string", "nullable": true, "format": "uuid", "description": "Branch unique identifier" }, "commit": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Commit unique identifier" }, "message": { "type": "string", "nullable": true, "description": "Commit message" } }, "required": [ "id" ], "description": "Commit information" }, "createdAt": { "type": "string", "description": "Change request creation timestamp" }, "createdBy": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id", "email", "firstName", "lastName" ], "description": "User information" }, "updatedAt": { "type": "string", "description": "Change request last update timestamp" }, "activities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Activity unique identifier" }, "type": { "type": "string", "enum": [ "create", "comment", "approve", "unapprove", "reject", "cancel", "complete" ], "description": "Activity type" }, "comment": { "type": "string", "nullable": true, "description": "Activity comment" }, "createdAt": { "type": "string", "description": "Activity creation timestamp" }, "createdBy": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id", "email", "firstName", "lastName" ], "description": "User information" }, "updatedAt": { "type": "string", "description": "Activity last update timestamp" } }, "required": [ "id", "type", "createdAt", "updatedAt" ], "description": "Change request activity" }, "description": "List of activities" }, "snapshot": { "type": "object", "properties": { "approvalMode": { "type": "string", "nullable": true, "description": "Approval mode" }, "approvalGroups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Approval group unique identifier" }, "name": { "type": "string", "description": "Approval group name" }, "description": { "type": "string", "nullable": true, "description": "Approval group description" }, "status": { "type": "string", "enum": [ "pending", "approved" ], "description": "Approval group status" }, "approvals": { "type": "array", "items": {}, "description": "List of approvals for this group" } }, "required": [ "id", "name", "status", "approvals" ], "description": "Approval group information" }, "description": "List of approval groups" }, "approvals": { "type": "array", "items": {}, "description": "List of approvals" }, "canComplete": { "type": "boolean", "description": "Whether the change request can be completed" } }, "description": "Change request snapshot containing approval state" }, "documentVersion": { "nullable": true, "description": "Document version being published" }, "previousDocumentVersion": { "nullable": true, "description": "Previous document version" }, "previousRelease": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Release unique identifier" }, "name": { "type": "string", "description": "Release name" }, "version": { "type": "string", "nullable": true, "description": "Release version" } }, "required": [ "id", "name" ], "description": "Release information" }, "previousReleaseId": { "type": "string", "nullable": true, "format": "uuid", "description": "Previous release unique identifier" } }, "required": [ "id", "type", "status", "projectId", "createdAt", "updatedAt" ], "description": "Updated change request with the modified activity" } } } } } } }, "/api/projects/{projectId}/decisions/simulate": { "post": { "operationId": "simulateDecision", "summary": "Simulate decision", "tags": [ "Decision" ], "description": "Simulates a decision graph evaluation without persisting changes, useful for testing decision logic.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "published": { "type": "boolean", "default": true, "description": "Indicates if simulation should use published decisions or draft" }, "releaseId": { "type": "string", "nullable": true, "description": "Optional release ID to use for loading dependent decisions" }, "context": { "type": "object", "nullable": true, "additionalProperties": true, "default": {}, "description": "Evaluation context", "example": { "cart": { "total": 1500 }, "customer": { "country": "US", "tier": "gold" } } }, "graph": { "description": "Decision graph", "example": { "edges": [ { "id": "1dfbc57d-ad1f-4cf8-978a-e43241856fc8", "type": "edge", "sourceId": "be0a5c2d-538d-4e50-9843-91b274e1b9d8", "targetId": "7c07550a-07bc-4ee4-80d6-9ad900e3d6c9" }, { "id": "5e2dc187-3b82-4f21-94f5-9c3fd16e12d4", "type": "edge", "sourceId": "7c07550a-07bc-4ee4-80d6-9ad900e3d6c9", "targetId": "72d52cfc-e866-4c11-bf79-6be9f750e4d7" } ], "nodes": [ { "id": "be0a5c2d-538d-4e50-9843-91b274e1b9d8", "name": "Request", "type": "inputNode", "position": { "x": 180, "y": 280 } }, { "id": "7c07550a-07bc-4ee4-80d6-9ad900e3d6c9", "name": "Fees", "type": "decisionTableNode", "content": { "rules": [ { "_id": "vCqrZGdWjA", "DA3Ybo-shA": "\"US\"", "FD4qBBPv2G": "> 1000", "JuUcECFGe1": "2", "jrsT5Wg9F8": "\"gold\"", "qA7iYc3Wle": "" }, { "_id": "CpXx-s78FH", "DA3Ybo-shA": "\"US\"", "FD4qBBPv2G": "> 1000", "JuUcECFGe1": "3", "jrsT5Wg9F8": "", "qA7iYc3Wle": "" }, { "_id": "zH-PuRB2aQ", "DA3Ybo-shA": "\"US\"", "FD4qBBPv2G": "", "JuUcECFGe1": "", "jrsT5Wg9F8": "", "qA7iYc3Wle": "25" }, { "_id": "HjEp-eQhAP", "DA3Ybo-shA": "\"CA\",\"MX\"", "FD4qBBPv2G": "> 1000", "JuUcECFGe1": "5", "jrsT5Wg9F8": "", "qA7iYc3Wle": "" }, { "_id": "nq40hJ1nXy", "DA3Ybo-shA": "\"CA\",\"MX\"", "FD4qBBPv2G": "", "JuUcECFGe1": "", "jrsT5Wg9F8": "", "qA7iYc3Wle": "50" }, { "_id": "G64ltgrVgV", "DA3Ybo-shA": "\"IE\",\"UK\",\"FR\",\"DE\"", "FD4qBBPv2G": "> 1000", "JuUcECFGe1": "10", "jrsT5Wg9F8": "", "qA7iYc3Wle": "" }, { "_id": "PD3oYgtiDa", "DA3Ybo-shA": "\"IE\",\"UK\",\"FR\",\"DE\"", "FD4qBBPv2G": "", "JuUcECFGe1": "", "jrsT5Wg9F8": "", "qA7iYc3Wle": "100" }, { "_id": "1BY7iMFoDw", "DA3Ybo-shA": "", "FD4qBBPv2G": "> 1000", "JuUcECFGe1": "15", "jrsT5Wg9F8": "", "qA7iYc3Wle": "" }, { "_id": "dlwJlbW7ZH", "DA3Ybo-shA": "", "FD4qBBPv2G": "", "JuUcECFGe1": "", "jrsT5Wg9F8": "", "qA7iYc3Wle": "150" } ], "inputs": [ { "id": "FD4qBBPv2G", "name": "Cart Total", "type": "expression", "field": "cart.total" }, { "id": "DA3Ybo-shA", "name": "Customer Country", "type": "expression", "field": "customer.country" }, { "id": "jrsT5Wg9F8", "name": "Customer Tier", "type": "expression", "field": "customer.tier" } ], "outputs": [ { "id": "qA7iYc3Wle", "name": "Fees Flat ($)", "type": "expression", "field": "fees.flat" }, { "id": "JuUcECFGe1", "name": "Fees Percent", "type": "expression", "field": "fees.percent" } ], "hitPolicy": "first" }, "position": { "x": 420, "y": 280 } }, { "id": "72d52cfc-e866-4c11-bf79-6be9f750e4d7", "name": "Response", "type": "outputNode", "position": { "x": 670, "y": 280 } } ] } } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Unique identifier of the project" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Successful simulation result with trace data", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "description": "The computed result from the decision evaluation" }, "performance": { "type": "string", "description": "Total execution time of the decision" }, "trace": { "type": "object", "additionalProperties": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the trace node" }, "name": { "type": "string", "description": "Name of the decision node" }, "input": { "description": "Input data passed to this node" }, "output": { "description": "Output data produced by this node" }, "traceData": { "description": "Additional trace metadata for the node" }, "performance": { "type": "string", "description": "Execution time for this node" } }, "required": [ "id", "name" ] }, "description": "Detailed trace of each node execution when trace is enabled" } }, "additionalProperties": true, "description": "Successful simulation result with trace data" } } } }, "400": { "description": "Simulation failed due to invalid input or decision logic error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing the simulation failure" }, "data": { "description": "Additional error details from the decision engine" } }, "description": "Simulation failed due to invalid input or decision logic error" } } } } } } }, "/api/projects/{projectId}/evaluate/{*}": { "post": { "operationId": "evaluateDecision", "summary": "Evaluate decision", "tags": [ "Decision" ], "description": "By default, decision should be published before it is evaluated.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "context": { "type": "object", "nullable": true, "additionalProperties": true, "default": {}, "description": "Evaluation context", "example": { "cart": { "total": 1500 }, "customer": { "country": "US", "tier": "gold" } } }, "trace": { "type": "boolean", "default": false, "description": "Include decision trace in response" } } } } } }, "parameters": [ { "schema": { "type": "string", "nullable": true, "format": "uuid" }, "in": "query", "name": "versionId", "description": "Optional version ID to evaluate a specific decision version instead of the published one" }, { "schema": { "type": "string" }, "in": "path", "name": "projectId", "required": true, "description": "ProjectId or projectKey" }, { "schema": { "type": "string" }, "in": "path", "name": "*", "required": true, "description": "Decision document key" } ], "security": [ { "projectAccessToken": [] } ], "responses": { "200": { "description": "Successful decision evaluation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "description": "The computed result from the decision evaluation" }, "performance": { "type": "string", "description": "Total execution time of the decision" }, "trace": { "type": "object", "additionalProperties": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the trace node" }, "name": { "type": "string", "description": "Name of the decision node" }, "input": { "description": "Input data passed to this node" }, "output": { "description": "Output data produced by this node" }, "traceData": { "description": "Additional trace metadata for the node" }, "performance": { "type": "string", "description": "Execution time for this node" } }, "required": [ "id", "name" ] }, "description": "Detailed trace of each node execution when trace is enabled" } }, "additionalProperties": true, "description": "Successful decision evaluation result" } } } }, "400": { "description": "Evaluation failed due to invalid input or missing published version", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing the simulation failure" }, "data": { "description": "Additional error details from the decision engine" } }, "description": "Evaluation failed due to invalid input or missing published version" } } } } } } }, "/api/projects/{projectId}/environments/{environmentId}/evaluate/{*}": { "post": { "operationId": "evaluateEnvironmentDecision", "summary": "Evaluate environment decision", "tags": [ "Decision" ], "description": "Evaluates a decision using the release deployed to a specific environment.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "context": { "type": "object", "nullable": true, "additionalProperties": true, "default": {}, "description": "Evaluation context", "example": { "cart": { "total": 1500 }, "customer": { "country": "US", "tier": "gold" } } }, "trace": { "type": "boolean", "default": false, "description": "Include decision trace in response" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "projectId", "required": true, "description": "ProjectId or projectKey" }, { "schema": { "type": "string" }, "in": "path", "name": "environmentId", "required": true, "description": "EnvironmentId or environmentKey" }, { "schema": { "type": "string" }, "in": "path", "name": "*", "required": true, "description": "Decision document key" } ], "security": [ { "projectAccessToken": [] } ], "responses": { "200": { "description": "Successful environment decision evaluation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "description": "The computed result from the decision evaluation" }, "performance": { "type": "string", "description": "Total execution time of the decision" }, "trace": { "type": "object", "additionalProperties": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the trace node" }, "name": { "type": "string", "description": "Name of the decision node" }, "input": { "description": "Input data passed to this node" }, "output": { "description": "Output data produced by this node" }, "traceData": { "description": "Additional trace metadata for the node" }, "performance": { "type": "string", "description": "Execution time for this node" } }, "required": [ "id", "name" ] }, "description": "Detailed trace of each node execution when trace is enabled" } }, "additionalProperties": true, "description": "Successful environment decision evaluation result" } } } }, "400": { "description": "Evaluation failed due to invalid environment or missing release", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing the simulation failure" }, "data": { "description": "Additional error details from the decision engine" } }, "description": "Evaluation failed due to invalid environment or missing release" } } } } } } }, "/api/projects/{projectId}/releases/{releaseId}/evaluate/{*}": { "post": { "operationId": "evaluateReleaseDecision", "summary": "Evaluate release decisions", "tags": [ "Decision" ], "description": "Evaluates a decision from a specific release version.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "context": { "type": "object", "nullable": true, "additionalProperties": true, "default": {}, "description": "Evaluation context", "example": { "cart": { "total": 1500 }, "customer": { "country": "US", "tier": "gold" } } }, "trace": { "type": "boolean", "default": false, "description": "Include decision trace in response" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "projectId", "required": true, "description": "ProjectId or projectKey" }, { "schema": { "type": "string" }, "in": "path", "name": "releaseId", "required": true, "description": "ReleaseId or releaseVersion" }, { "schema": { "type": "string" }, "in": "path", "name": "*", "required": true, "description": "Decision document key" } ], "security": [ { "projectAccessToken": [] } ], "responses": { "200": { "description": "Successful release decision evaluation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "description": "The computed result from the decision evaluation" }, "performance": { "type": "string", "description": "Total execution time of the decision" }, "trace": { "type": "object", "additionalProperties": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the trace node" }, "name": { "type": "string", "description": "Name of the decision node" }, "input": { "description": "Input data passed to this node" }, "output": { "description": "Output data produced by this node" }, "traceData": { "description": "Additional trace metadata for the node" }, "performance": { "type": "string", "description": "Execution time for this node" } }, "required": [ "id", "name" ] }, "description": "Detailed trace of each node execution when trace is enabled" } }, "additionalProperties": true, "description": "Successful release decision evaluation result" } } } }, "400": { "description": "Evaluation failed due to invalid release or missing document", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing the simulation failure" }, "data": { "description": "Additional error details from the decision engine" } }, "description": "Evaluation failed due to invalid release or missing document" } } } } } } }, "/api/projects/{projectId}/http-proxy": { "post": { "operationId": "proxyHttpRequest", "summary": "HTTP Proxy", "tags": [ "Decision" ], "description": "Proxies an HTTP request through the decision engine for testing integrations.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Target URL for the proxied request" }, "method": { "type": "string", "enum": [ "HEAD", "PATCH", "POST", "GET", "DELETE" ], "description": "HTTP method to use for the proxied request" }, "body": { "description": "Request body to send with the proxied request" }, "headers": { "description": "HTTP headers to include in the proxied request" }, "params": { "description": "Query parameters to include in the proxied request" }, "auth": { "description": "Authentication configuration for the proxied request" } }, "required": [ "url", "method" ] } } }, "required": true }, "security": [ { "internalAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "200": { "description": "Response received from the proxied HTTP request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Response received from the proxied HTTP request" } } } } } } }, "/api/projects/{projectId}/branches": { "get": { "operationId": "listBranches", "summary": "List branches", "tags": [ "Branches" ], "description": "Retrieves a paginated list of branches for a project.", "parameters": [ { "schema": { "type": "number", "default": 1 }, "in": "query", "name": "page", "description": "Current page" }, { "schema": { "type": "number", "default": 10 }, "in": "query", "name": "perPage", "description": "Number of items per page" }, { "schema": { "type": "string" }, "in": "query", "name": "search", "description": "Search term to filter branches by name" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project ID" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Paginated list of branches", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Branch ID" }, "name": { "type": "string", "description": "Branch name" }, "default": { "type": "boolean", "description": "Whether this is the default (main) branch" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID" }, "baseCommitId": { "type": "string", "nullable": true, "format": "uuid", "description": "Base commit ID" }, "createdById": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of user who created the branch" }, "createdBy": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "User ID" }, "email": { "type": "string", "description": "User email" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id", "email", "firstName", "lastName" ], "description": "User who created the branch" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "changeRequests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Change request ID" }, "status": { "type": "string", "description": "Change request status" }, "type": { "type": "string", "description": "Change request type" }, "branchId": { "type": "string", "nullable": true, "format": "uuid", "description": "Associated branch ID" }, "projectId": { "type": "string", "format": "uuid", "description": "Associated project ID" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" } }, "required": [ "id", "status", "type", "branchId", "projectId", "createdAt" ], "description": "Change request associated with the branch" }, "description": "Pending change requests" } }, "required": [ "id", "name", "default", "projectId", "baseCommitId", "createdById", "createdAt", "updatedAt" ], "description": "Branch entity" }, "description": "List of branches" }, "pagination": { "type": "object", "properties": { "current": { "type": "number", "description": "Current page number" }, "from": { "type": "number", "description": "Starting record number" }, "to": { "type": "number", "description": "Ending record number" }, "total": { "type": "number", "description": "Total number of records" }, "pageSize": { "type": "number", "description": "Number of records per page" } }, "required": [ "current", "from", "to", "total", "pageSize" ], "description": "Pagination information" } }, "required": [ "data", "pagination" ], "description": "Paginated list of branches" } } } } } }, "post": { "operationId": "createBranch", "summary": "Create branch", "tags": [ "Branches" ], "description": "Creates a new branch in the project.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name for the new branch" }, "baseCommitId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "string", "enum": [ "base", "latest" ] } ], "description": "Base commit ID to branch from, or \"base\"/\"latest\" keywords" } }, "required": [ "name" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project ID" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "The newly created branch", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Branch ID" }, "name": { "type": "string", "description": "Branch name" }, "default": { "type": "boolean", "description": "Whether this is the default (main) branch" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID" }, "baseCommitId": { "type": "string", "nullable": true, "format": "uuid", "description": "Base commit ID" }, "createdById": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of user who created the branch" }, "createdBy": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "User ID" }, "email": { "type": "string", "description": "User email" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id", "email", "firstName", "lastName" ], "description": "User who created the branch" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "changeRequests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Change request ID" }, "status": { "type": "string", "description": "Change request status" }, "type": { "type": "string", "description": "Change request type" }, "branchId": { "type": "string", "nullable": true, "format": "uuid", "description": "Associated branch ID" }, "projectId": { "type": "string", "format": "uuid", "description": "Associated project ID" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" } }, "required": [ "id", "status", "type", "branchId", "projectId", "createdAt" ], "description": "Change request associated with the branch" }, "description": "Pending change requests" } }, "required": [ "id", "name", "default", "projectId", "baseCommitId", "createdById", "createdAt", "updatedAt" ], "description": "The newly created branch" } } } } } } }, "/api/projects/{projectId}/branches/{branchId}": { "get": { "operationId": "getBranch", "summary": "Get branch", "tags": [ "Branches" ], "description": "Retrieves details of a specific branch including its latest commit and change requests.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project ID" }, { "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "string", "enum": [ "main" ] } ] }, "in": "path", "name": "branchId", "required": true, "description": "Branch ID or \"main\" for the default branch" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Branch details with latest commit and change requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Branch ID" }, "name": { "type": "string", "description": "Branch name" }, "default": { "type": "boolean", "description": "Whether this is the default (main) branch" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID" }, "baseCommitId": { "type": "string", "nullable": true, "format": "uuid", "description": "Base commit ID" }, "createdById": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of user who created the branch" }, "createdBy": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "User ID" }, "email": { "type": "string", "description": "User email" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id", "email", "firstName", "lastName" ], "description": "User who created the branch" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "changeRequests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Change request ID" }, "status": { "type": "string", "description": "Change request status" }, "type": { "type": "string", "description": "Change request type" }, "branchId": { "type": "string", "nullable": true, "format": "uuid", "description": "Associated branch ID" }, "projectId": { "type": "string", "format": "uuid", "description": "Associated project ID" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" } }, "required": [ "id", "status", "type", "branchId", "projectId", "createdAt" ], "description": "Change request associated with the branch" }, "description": "Pending change requests" }, "latestCommit": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Commit ID" }, "message": { "type": "string", "nullable": true, "description": "Commit message" }, "branchId": { "type": "string", "format": "uuid", "description": "Branch ID" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID" }, "createdById": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of user who created the commit" }, "createdBy": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "User ID" }, "email": { "type": "string", "description": "User email" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id", "email", "firstName", "lastName" ], "description": "User who created the commit" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "files": { "type": "array", "items": {}, "description": "Commit files" } }, "required": [ "id", "message", "branchId", "projectId", "createdById", "createdAt" ], "description": "Latest commit on the branch" }, "totalCommits": { "type": "number", "description": "Total number of commits on the branch" } }, "required": [ "id", "name", "default", "projectId", "baseCommitId", "createdById", "createdAt", "updatedAt", "changeRequests", "latestCommit", "totalCommits" ], "description": "Branch details with latest commit and change requests" } } } } } }, "delete": { "operationId": "deleteBranch", "summary": "Remove branch", "tags": [ "Branches" ], "description": "Deletes a branch from the project.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project ID" }, { "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "string", "enum": [ "main" ] } ] }, "in": "path", "name": "branchId", "required": true, "description": "Branch ID or \"main\" for the default branch" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "202": { "description": "Branch successfully deleted" } } } }, "/api/projects/{projectId}/branches/{branchId}/commits": { "get": { "operationId": "listBranchCommits", "summary": "List commits", "tags": [ "Branches" ], "description": "Retrieves a paginated list of commits for a branch.", "parameters": [ { "schema": { "type": "number", "default": 1 }, "in": "query", "name": "page", "description": "Current page" }, { "schema": { "type": "number", "default": 10 }, "in": "query", "name": "perPage", "description": "Number of items per page" }, { "schema": { "type": "string" }, "in": "query", "name": "search", "description": "Search term to filter commits by message" }, { "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "string", "enum": [ "main" ] } ] }, "in": "path", "name": "branchId", "required": true, "description": "Branch ID or \"main\" for the default branch" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project ID" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Paginated list of commits", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Commit ID" }, "message": { "type": "string", "nullable": true, "description": "Commit message" }, "branchId": { "type": "string", "format": "uuid", "description": "Branch ID" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID" }, "createdById": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of user who created the commit" }, "createdBy": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "User ID" }, "email": { "type": "string", "description": "User email" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id", "email", "firstName", "lastName" ], "description": "User who created the commit" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "files": { "type": "array", "items": {}, "description": "Commit files" } }, "required": [ "id", "message", "branchId", "projectId", "createdById", "createdAt" ], "description": "Commit entity" }, "description": "List of commits" }, "pagination": { "type": "object", "properties": { "current": { "type": "number", "description": "Current page number" }, "from": { "type": "number", "description": "Starting record number" }, "to": { "type": "number", "description": "Ending record number" }, "total": { "type": "number", "description": "Total number of records" }, "pageSize": { "type": "number", "description": "Number of records per page" } }, "required": [ "current", "from", "to", "total", "pageSize" ], "description": "Pagination information" } }, "required": [ "data", "pagination" ], "description": "Paginated list of commits" } } } } } } }, "/api/projects/{projectId}/commits/{commitId}": { "get": { "operationId": "getCommit", "summary": "Get commit", "tags": [ "Branches" ], "description": "Retrieves a specific commit by ID.", "parameters": [ { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "content", "description": "Whether to include file content in the response" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project ID" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "commitId", "required": true, "description": "Commit ID" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "The requested commit", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Commit ID" }, "message": { "type": "string", "nullable": true, "description": "Commit message" }, "branchId": { "type": "string", "format": "uuid", "description": "Branch ID" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID" }, "createdById": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of user who created the commit" }, "createdBy": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "User ID" }, "email": { "type": "string", "description": "User email" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id", "email", "firstName", "lastName" ], "description": "User who created the commit" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "files": { "type": "array", "items": {}, "description": "Commit files" } }, "required": [ "id", "message", "branchId", "projectId", "createdById", "createdAt" ], "description": "The requested commit" } } } } } } }, "/api/projects/{projectId}/commits/{commitId}/diff": { "get": { "operationId": "getCommitDiff", "summary": "Get commit diff", "tags": [ "Branches" ], "description": "Retrieves the diff (file changes) for a specific commit compared to its previous commit.", "parameters": [ { "schema": { "anyOf": [ { "type": "string", "enum": [ "true", "false", "True", "False", "TRUE", "FALSE" ] }, { "type": "boolean" } ], "default": true }, "in": "query", "name": "content", "description": "Whether to include file content in the response" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project ID" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "commitId", "required": true, "description": "Commit ID" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Commit diff with file changes and statistics", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Commit ID" }, "message": { "type": "string", "nullable": true, "description": "Commit message" }, "branchId": { "type": "string", "format": "uuid", "description": "Branch ID" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID" }, "createdById": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of user who created the commit" }, "createdBy": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "User ID" }, "email": { "type": "string", "description": "User email" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id", "email", "firstName", "lastName" ], "description": "User who created the commit" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "files": { "type": "array", "items": {}, "description": "Commit files" }, "branch": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Branch ID" }, "name": { "type": "string", "description": "Branch name" }, "default": { "type": "boolean", "description": "Whether this is the default (main) branch" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID" }, "baseCommitId": { "type": "string", "nullable": true, "format": "uuid", "description": "Base commit ID" }, "createdById": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of user who created the branch" }, "createdBy": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "User ID" }, "email": { "type": "string", "description": "User email" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id", "email", "firstName", "lastName" ], "description": "User who created the branch" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "changeRequests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Change request ID" }, "status": { "type": "string", "description": "Change request status" }, "type": { "type": "string", "description": "Change request type" }, "branchId": { "type": "string", "nullable": true, "format": "uuid", "description": "Associated branch ID" }, "projectId": { "type": "string", "format": "uuid", "description": "Associated project ID" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" } }, "required": [ "id", "status", "type", "branchId", "projectId", "createdAt" ], "description": "Change request associated with the branch" }, "description": "Pending change requests" } }, "required": [ "id", "name", "default", "projectId", "baseCommitId", "createdById", "createdAt", "updatedAt" ], "description": "Branch the commit belongs to" }, "previousCommit": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Commit ID" }, "message": { "type": "string", "nullable": true, "description": "Commit message" }, "branchId": { "type": "string", "format": "uuid", "description": "Branch ID" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID" }, "createdById": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of user who created the commit" }, "createdBy": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "User ID" }, "email": { "type": "string", "description": "User email" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id", "email", "firstName", "lastName" ], "description": "User who created the commit" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "files": { "type": "array", "items": {}, "description": "Commit files" } }, "required": [ "id", "message", "branchId", "projectId", "createdById", "createdAt" ], "description": "Previous commit" }, "changes": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "added", "deleted", "modified", "renamed" ], "description": "Type of change" }, "file": { "description": "File for added/deleted changes" }, "from": { "description": "Original file for modified/renamed changes" }, "to": { "description": "New file for modified/renamed changes" } }, "required": [ "type" ], "description": "File system change" }, "description": "List of file changes" }, "stats": { "type": "object", "properties": { "filesAdded": { "type": "number", "description": "Number of files added" }, "filesDeleted": { "type": "number", "description": "Number of files deleted" }, "filesModified": { "type": "number", "description": "Number of files modified" }, "filesRenamed": { "type": "number", "description": "Number of files renamed" }, "totalChanges": { "type": "number", "description": "Total number of changes" } }, "required": [ "filesAdded", "filesDeleted", "filesModified", "totalChanges" ], "description": "Change statistics" } }, "required": [ "id", "message", "branchId", "projectId", "createdById", "createdAt", "branch", "changes", "stats" ], "description": "Commit diff with file changes and statistics" } } } } } } }, "/api/projects/{projectId}/branches/{branchId}/commits/{commitId}": { "get": { "operationId": "getBranchCommit", "summary": "Get branch commit", "tags": [ "Branches" ], "description": "Retrieves a specific commit on a branch by commit ID or keywords.", "parameters": [ { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "content", "description": "Whether to include file content in the response" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project ID" }, { "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "string", "enum": [ "main" ] } ] }, "in": "path", "name": "branchId", "required": true, "description": "Branch ID or \"main\" for the default branch" }, { "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "string", "enum": [ "base", "latest" ] } ] }, "in": "path", "name": "commitId", "required": true, "description": "Commit ID or \"base\"/\"latest\" keywords" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "The requested commit", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Commit ID" }, "message": { "type": "string", "nullable": true, "description": "Commit message" }, "branchId": { "type": "string", "format": "uuid", "description": "Branch ID" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID" }, "createdById": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of user who created the commit" }, "createdBy": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "User ID" }, "email": { "type": "string", "description": "User email" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id", "email", "firstName", "lastName" ], "description": "User who created the commit" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "files": { "type": "array", "items": {}, "description": "Commit files" } }, "required": [ "id", "message", "branchId", "projectId", "createdById", "createdAt" ], "description": "The requested commit" } } } } } } }, "/api/projects/{projectId}/branches/{branchId}/commit": { "post": { "operationId": "createBranchCommit", "summary": "Branch commit", "tags": [ "Branches" ], "description": "Creates a new commit on a branch with the specified changes.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "baseCommitId": { "type": "string", "format": "uuid" }, "message": { "type": "string", "minLength": 1 }, "changes": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "added" ] }, "path": { "type": "string" }, "content": {} }, "required": [ "type", "path" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "removed" ] }, "path": { "type": "string" } }, "required": [ "type", "path" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "modified" ] }, "path": { "type": "string" }, "content": {} }, "required": [ "type", "path" ] } ] }, "default": [] }, "resolutions": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "resolution": { "type": "string", "enum": [ "useLeft", "useRight", "manual" ] }, "content": {}, "hash": { "type": "string" } }, "required": [ "path", "resolution" ] } } }, "required": [ "message" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project ID" }, { "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "string", "enum": [ "main" ] } ] }, "in": "path", "name": "branchId", "required": true, "description": "Branch ID or \"main\" for the default branch" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Commit result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the commit was successful" }, "commitId": { "type": "string", "format": "uuid", "description": "ID of the newly created commit" }, "stats": { "type": "object", "properties": { "totalFiles": { "type": "number", "description": "Total number of files in the commit" }, "reusedContent": { "type": "number", "description": "Number of reused file contents" }, "newContent": { "type": "number", "description": "Number of new file contents" } }, "required": [ "totalFiles", "reusedContent", "newContent" ], "description": "Commit statistics" } }, "required": [ "success", "commitId", "stats" ], "description": "Commit result" } } } } } } }, "/api/projects/{projectId}/branches/{branchId}/merge-preview": { "get": { "operationId": "getMergePreview", "summary": "Get merge preview", "tags": [ "Branches" ], "description": "Previews the result of merging a branch into main, including any conflicts.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project ID" }, { "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "string", "enum": [ "main" ] } ] }, "in": "path", "name": "branchId", "required": true, "description": "Branch ID or \"main\" for the default branch" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Merge preview result", "content": { "application/json": { "schema": { "type": "object", "properties": { "canMerge": { "type": "boolean", "description": "Whether the branch can be merged without conflicts" }, "isUpToDate": { "type": "boolean", "description": "Whether the branch is up to date with main" }, "needsRebase": { "type": "boolean", "description": "Whether the branch needs to be rebased" }, "changes": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "added", "deleted", "modified", "renamed" ], "description": "Type of change" }, "file": { "description": "File for added/deleted changes" }, "from": { "description": "Original file for modified/renamed changes" }, "to": { "description": "New file for modified/renamed changes" } }, "required": [ "type" ], "description": "File system change" }, "description": "List of file changes that would result from merge" }, "conflicts": { "type": "array", "items": { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "modify/modify", "delete/modify", "add/add", "directory/file" ], "description": "Reason for the conflict" }, "path": { "type": "string", "description": "File path where conflict occurred" }, "base": { "description": "Base version of the file" }, "ours": { "description": "Our version of the file" }, "theirs": { "description": "Their version of the file" }, "deleted": { "type": "string", "enum": [ "ours", "theirs" ], "description": "Which side deleted the file" }, "modified": { "description": "Modified version of the file" } }, "required": [ "reason", "path" ], "description": "Merge conflict" }, "description": "List of merge conflicts" }, "stats": { "type": "object", "properties": { "filesAdded": { "type": "number", "description": "Number of files added" }, "filesDeleted": { "type": "number", "description": "Number of files deleted" }, "filesModified": { "type": "number", "description": "Number of files modified" }, "filesRenamed": { "type": "number", "description": "Number of files renamed" }, "totalChanges": { "type": "number", "description": "Total number of changes" } }, "required": [ "filesAdded", "filesDeleted", "filesModified", "totalChanges" ], "description": "Change statistics" }, "message": { "type": "string", "description": "Human-readable merge status message" } }, "required": [ "canMerge", "isUpToDate", "needsRebase", "changes", "conflicts", "stats", "message" ], "description": "Merge preview result" } } } } } } }, "/api/projects/{projectId}/branches/{branchId}/merge": { "post": { "operationId": "mergeBranch", "summary": "Merge branch", "tags": [ "Branches" ], "description": "Merges a branch into main, or creates a change request if approval is required.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "nullable": true, "properties": { "message": { "type": "string", "minLength": 1, "description": "Merge commit message" }, "resolutions": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "resolution": { "type": "string", "enum": [ "useLeft", "useRight", "manual" ] }, "content": {}, "hash": { "type": "string" } }, "required": [ "path", "resolution" ] }, "default": [], "description": "Conflict resolutions" } }, "required": [ "message" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project ID" }, { "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "string", "enum": [ "main" ] } ] }, "in": "path", "name": "branchId", "required": true, "description": "Branch ID or \"main\" for the default branch" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Merge result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the operation was successful" }, "requiresApproval": { "type": "boolean", "description": "Whether approval is required for the merge" }, "changeRequestId": { "type": "string", "format": "uuid", "description": "ID of created change request" }, "mergeCommitId": { "type": "string", "format": "uuid", "description": "ID of the merge commit" }, "message": { "type": "string", "description": "Human-readable result message" }, "changes": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "added", "deleted", "modified", "renamed" ], "description": "Type of change" }, "file": { "description": "File for added/deleted changes" }, "from": { "description": "Original file for modified/renamed changes" }, "to": { "description": "New file for modified/renamed changes" } }, "required": [ "type" ], "description": "File system change" }, "description": "List of merged changes" }, "stats": { "type": "object", "properties": { "filesAdded": { "type": "number", "description": "Number of files added" }, "filesDeleted": { "type": "number", "description": "Number of files deleted" }, "filesModified": { "type": "number", "description": "Number of files modified" }, "filesRenamed": { "type": "number", "description": "Number of files renamed" }, "totalChanges": { "type": "number", "description": "Total number of changes" } }, "required": [ "filesAdded", "filesDeleted", "filesModified", "totalChanges" ], "description": "Change statistics" } }, "required": [ "success", "requiresApproval", "message" ], "description": "Merge result" } } } } } } }, "/api/projects/{projectId}/branches/{branchId}/rebase": { "post": { "operationId": "rebaseBranch", "summary": "Rebase branch", "tags": [ "Branches" ], "description": "Rebases a branch onto the latest main branch commit.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "resolutions": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "resolution": { "type": "string", "enum": [ "useLeft", "useRight", "manual" ] }, "content": {}, "hash": { "type": "string" } }, "required": [ "path", "resolution" ] }, "description": "Conflict resolutions for rebasing" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project ID" }, { "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "string", "enum": [ "main" ] } ] }, "in": "path", "name": "branchId", "required": true, "description": "Branch ID or \"main\" for the default branch" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Rebase result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the rebase was successful" }, "newBaseCommitId": { "type": "string", "format": "uuid", "description": "ID of the new base commit" }, "newCommitId": { "type": "string", "format": "uuid", "description": "ID of the new commit created by rebase" }, "message": { "type": "string", "description": "Human-readable result message" }, "stats": { "type": "object", "properties": { "filesChanged": { "type": "number", "description": "Number of files changed" }, "conflictsResolved": { "type": "number", "description": "Number of conflicts resolved" } }, "required": [ "filesChanged", "conflictsResolved" ], "description": "Rebase statistics" } }, "required": [ "success", "newBaseCommitId", "message" ], "description": "Rebase result" } } } } } } }, "/api/projects/{projectId}/branches/{branchId}/revert": { "post": { "operationId": "revertCommit", "summary": "Revert commit", "tags": [ "Branches" ], "description": "Creates a new branch that reverts the project state to a specific commit.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "branchName": { "type": "string", "description": "Name for the new revert branch" }, "commitId": { "type": "string", "format": "uuid", "description": "ID of the commit to revert to" }, "message": { "type": "string", "minLength": 1, "description": "Commit message for the revert" } }, "required": [ "branchName", "commitId", "message" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project ID" }, { "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "string", "enum": [ "main" ] } ] }, "in": "path", "name": "branchId", "required": true, "description": "Branch ID or \"main\" for the default branch" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "The newly created revert branch", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Branch ID" }, "name": { "type": "string", "description": "Branch name" }, "default": { "type": "boolean", "description": "Whether this is the default (main) branch" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID" }, "baseCommitId": { "type": "string", "nullable": true, "format": "uuid", "description": "Base commit ID" }, "createdById": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of user who created the branch" }, "createdBy": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "User ID" }, "email": { "type": "string", "description": "User email" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id", "email", "firstName", "lastName" ], "description": "User who created the branch" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "changeRequests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Change request ID" }, "status": { "type": "string", "description": "Change request status" }, "type": { "type": "string", "description": "Change request type" }, "branchId": { "type": "string", "nullable": true, "format": "uuid", "description": "Associated branch ID" }, "projectId": { "type": "string", "format": "uuid", "description": "Associated project ID" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" } }, "required": [ "id", "status", "type", "branchId", "projectId", "createdAt" ], "description": "Change request associated with the branch" }, "description": "Pending change requests" } }, "required": [ "id", "name", "default", "projectId", "baseCommitId", "createdById", "createdAt", "updatedAt" ], "description": "The newly created revert branch" } } } } } } }, "/api/projects/{projectId}/security/tokens": { "post": { "operationId": "generateProjectAccessToken", "summary": "Generate a token", "tags": [ "Security" ], "description": "Generates a new access token for the specified project.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name to identify the access token" } }, "required": [ "name" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Unique identifier of the project" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "The newly created project access token", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the project access token" }, "name": { "type": "string", "description": "Name of the access token" }, "token": { "type": "string", "description": "The access token value" }, "projectId": { "type": "string", "format": "uuid", "description": "ID of the project this token belongs to" }, "createdBy": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the user" }, "email": { "type": "string", "format": "email", "description": "Email address of the user" }, "firstName": { "type": "string", "nullable": true, "description": "First name of the user" }, "lastName": { "type": "string", "nullable": true, "description": "Last name of the user" } }, "required": [ "id", "email", "firstName", "lastName" ], "description": "User who created the token" }, "createdAt": { "type": "string", "description": "Timestamp when the token was created" } }, "required": [ "id", "name", "token", "projectId", "createdAt" ], "description": "The newly created project access token" } } } } } }, "get": { "operationId": "listProjectAccessTokens", "summary": "List project tokens", "tags": [ "Security" ], "description": "Retrieves all access tokens for the specified project.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Unique identifier of the project" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "List of project access tokens", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the project access token" }, "name": { "type": "string", "description": "Name of the access token" }, "token": { "type": "string", "description": "The access token value" }, "projectId": { "type": "string", "format": "uuid", "description": "ID of the project this token belongs to" }, "createdBy": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the user" }, "email": { "type": "string", "format": "email", "description": "Email address of the user" }, "firstName": { "type": "string", "nullable": true, "description": "First name of the user" }, "lastName": { "type": "string", "nullable": true, "description": "Last name of the user" } }, "required": [ "id", "email", "firstName", "lastName" ], "description": "User who created the token" }, "createdAt": { "type": "string", "description": "Timestamp when the token was created" } }, "required": [ "id", "name", "token", "projectId", "createdAt" ], "description": "Project access token details" }, "description": "List of project access tokens" } } } } } } }, "/api/projects/{projectId}/security/tokens/{tokenId}": { "delete": { "operationId": "revokeProjectAccessToken", "summary": "Revoke a token", "tags": [ "Security" ], "description": "Revokes and permanently deletes the specified access token from the project.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Unique identifier of the project" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "tokenId", "required": true, "description": "Unique identifier of the token to revoke" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Token successfully revoked" } } } }, "/api/projects": { "get": { "operationId": "listProjects", "summary": "List projects", "tags": [ "Project" ], "description": "Retrieve a paginated list of projects the user has access to within the organisation.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "search", "description": "Search term to filter projects by name" }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "true", "false", "True", "False", "TRUE", "FALSE" ] }, { "type": "boolean" } ], "default": false }, "in": "query", "name": "all", "description": "If true, list all projects in the organisation (admin/owner only)" }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "true", "false", "True", "False", "TRUE", "FALSE" ] }, { "type": "boolean" } ], "default": false }, "in": "query", "name": "deleted", "description": "If true, list soft-deleted projects (admin/owner only)" }, { "schema": { "type": "number", "default": 1 }, "in": "query", "name": "page", "description": "Current page" }, { "schema": { "type": "number", "default": 10 }, "in": "query", "name": "perPage", "description": "Number of items per page" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Paginated list of projects", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the project" }, "name": { "type": "string", "description": "Name of the project" }, "key": { "type": "string", "description": "Unique key identifier for the project" }, "organisationId": { "type": "string", "format": "uuid", "description": "Organisation ID the project belongs to" }, "version": { "type": "string", "enum": [ "v1", "v2" ], "description": "Project version (v1 or v2)" }, "createdAt": { "type": "string", "description": "Timestamp when the project was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the project was last updated" }, "protected": { "type": "boolean", "description": "Whether the project is protected from deletion" }, "deletedAt": { "type": "string", "nullable": true, "description": "Timestamp when the project was soft deleted" }, "decisionsApprovalMode": { "type": "string", "nullable": true, "enum": [ "require_one_per_team", "none_create_request", "require_any", "none", null ], "description": "Approval mode for decisions" }, "decisionsApprovalGroups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the group" }, "name": { "type": "string", "description": "Name of the group" }, "description": { "type": "string", "description": "Description of the group" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID the group belongs to" }, "roleId": { "type": "string", "format": "uuid", "description": "Role ID associated with the group" } }, "required": [ "id", "name", "projectId" ] }, "description": "Groups required for decision approvals" }, "members": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Member ID" }, "owner": { "type": "boolean", "description": "Whether the member is an owner" }, "user": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "User ID" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id", "email", "firstName", "lastName" ], "description": "User details" } }, "required": [ "id", "owner", "user" ] }, "description": "List of project members" } }, "required": [ "id", "name", "organisationId", "version", "createdAt", "updatedAt" ] }, "description": "List of projects" }, "paginate": { "type": "object", "properties": { "current": { "type": "number", "description": "Current page number" }, "from": { "type": "number", "description": "Starting record number" }, "to": { "type": "number", "description": "Ending record number" }, "total": { "type": "number", "description": "Total number of records" }, "pageSize": { "type": "number", "description": "Number of records per page" } }, "required": [ "current", "from", "to", "total", "pageSize" ], "description": "Pagination metadata" } }, "required": [ "results", "paginate" ], "description": "Paginated list of projects" } } } } } }, "post": { "operationId": "createProject", "summary": "Create a project", "tags": [ "Project" ], "description": "Create a new project within the organisation with optional content copying from an existing project.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the project" }, "key": { "type": "string", "pattern": "^[a-z0-9]{2,}(-[a-z0-9]+)*$", "description": "Unique key identifier for the project (lowercase letters, numbers, and hyphens)" }, "copyContentRef": { "type": "string", "format": "uuid", "description": "Project ID to copy content from" }, "protected": { "type": "boolean", "default": false, "description": "Whether the project should be protected from deletion" }, "version": { "type": "string", "nullable": true, "enum": [ "v1", "v2", null ], "default": "v1", "description": "Project version to create (v1 or v2)" } }, "required": [ "name", "key" ] } } }, "required": true }, "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "The created project with details", "content": { "application/json": { "schema": { "type": "object", "properties": { "project": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the project" }, "name": { "type": "string", "description": "Name of the project" }, "key": { "type": "string", "description": "Unique key identifier for the project" }, "organisationId": { "type": "string", "format": "uuid", "description": "Organisation ID the project belongs to" }, "version": { "type": "string", "enum": [ "v1", "v2" ], "description": "Project version (v1 or v2)" }, "createdAt": { "type": "string", "description": "Timestamp when the project was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the project was last updated" }, "protected": { "type": "boolean", "description": "Whether the project is protected from deletion" }, "deletedAt": { "type": "string", "nullable": true, "description": "Timestamp when the project was soft deleted" }, "decisionsApprovalMode": { "type": "string", "nullable": true, "enum": [ "require_one_per_team", "none_create_request", "require_any", "none", null ], "description": "Approval mode for decisions" }, "decisionsApprovalGroups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the group" }, "name": { "type": "string", "description": "Name of the group" }, "description": { "type": "string", "description": "Description of the group" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID the group belongs to" }, "roleId": { "type": "string", "format": "uuid", "description": "Role ID associated with the group" } }, "required": [ "id", "name", "projectId" ] }, "description": "Groups required for decision approvals" } }, "required": [ "id", "name", "organisationId", "version", "createdAt", "updatedAt" ], "description": "The created project" } }, "required": [ "project" ], "description": "The created project with details" } } } } } } }, "/api/projects/{projectId}": { "get": { "operationId": "getProject", "summary": "Get a project", "tags": [ "Project" ], "description": "Retrieve detailed information about a specific project by its ID.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Unique identifier of the project" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Project details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the project" }, "name": { "type": "string", "description": "Name of the project" }, "key": { "type": "string", "description": "Unique key identifier for the project" }, "organisationId": { "type": "string", "format": "uuid", "description": "Organisation ID the project belongs to" }, "version": { "type": "string", "enum": [ "v1", "v2" ], "description": "Project version (v1 or v2)" }, "createdAt": { "type": "string", "description": "Timestamp when the project was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the project was last updated" }, "protected": { "type": "boolean", "description": "Whether the project is protected from deletion" }, "deletedAt": { "type": "string", "nullable": true, "description": "Timestamp when the project was soft deleted" }, "decisionsApprovalMode": { "type": "string", "nullable": true, "enum": [ "require_one_per_team", "none_create_request", "require_any", "none", null ], "description": "Approval mode for decisions" }, "decisionsApprovalGroups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the group" }, "name": { "type": "string", "description": "Name of the group" }, "description": { "type": "string", "description": "Description of the group" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID the group belongs to" }, "roleId": { "type": "string", "format": "uuid", "description": "Role ID associated with the group" } }, "required": [ "id", "name", "projectId" ] }, "description": "Groups required for decision approvals" } }, "required": [ "id", "name", "organisationId", "version", "createdAt", "updatedAt" ], "description": "Project details" } } } } } }, "put": { "operationId": "updateProject", "summary": "Update a project", "tags": [ "Project" ], "description": "Update the name, key, or protection status of an existing project.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "New name for the project" }, "key": { "type": "string", "pattern": "^[a-z0-9]{2,}(-[a-z0-9]+)*$", "description": "New unique key identifier for the project" }, "protected": { "type": "boolean", "example": false, "description": "Whether the project should be protected from deletion (admin/owner only)" } }, "required": [ "name", "key" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Unique identifier of the project to update" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Updated project details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the project" }, "name": { "type": "string", "description": "Name of the project" }, "key": { "type": "string", "description": "Unique key identifier for the project" }, "organisationId": { "type": "string", "format": "uuid", "description": "Organisation ID the project belongs to" }, "version": { "type": "string", "enum": [ "v1", "v2" ], "description": "Project version (v1 or v2)" }, "createdAt": { "type": "string", "description": "Timestamp when the project was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the project was last updated" }, "protected": { "type": "boolean", "description": "Whether the project is protected from deletion" }, "deletedAt": { "type": "string", "nullable": true, "description": "Timestamp when the project was soft deleted" }, "decisionsApprovalMode": { "type": "string", "nullable": true, "enum": [ "require_one_per_team", "none_create_request", "require_any", "none", null ], "description": "Approval mode for decisions" }, "decisionsApprovalGroups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the group" }, "name": { "type": "string", "description": "Name of the group" }, "description": { "type": "string", "description": "Description of the group" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID the group belongs to" }, "roleId": { "type": "string", "format": "uuid", "description": "Role ID associated with the group" } }, "required": [ "id", "name", "projectId" ] }, "description": "Groups required for decision approvals" } }, "required": [ "id", "name", "organisationId", "version", "createdAt", "updatedAt" ], "description": "Updated project details" } } } } } }, "delete": { "operationId": "deleteProject", "summary": "Delete a project", "tags": [ "Project" ], "description": "Soft delete a project, making it recoverable. Protected projects cannot be deleted.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Unique identifier of the project to delete" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Deletion confirmation", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ], "description": "Operation status" } }, "required": [ "status" ], "description": "Deletion confirmation" } } } } } } }, "/api/projects/{projectId}/approvals": { "put": { "operationId": "updateProjectApprovals", "summary": "Update project approvals", "tags": [ "Project" ], "description": "Configure the approval workflow settings for decisions within the project.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "decisionsApprovalMode": { "type": "string", "nullable": true, "enum": [ "require_one_per_team", "none_create_request", "require_any", "none", null ], "description": "Approval mode for decisions (require_one_per_team, none_create_request, require_any, none)" }, "decisionsApprovalGroups": { "type": "array", "nullable": true, "items": { "type": "string", "format": "uuid" }, "description": "Array of group IDs required for decision approvals" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Unique identifier of the project" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Updated project with approval settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the project" }, "name": { "type": "string", "description": "Name of the project" }, "key": { "type": "string", "description": "Unique key identifier for the project" }, "organisationId": { "type": "string", "format": "uuid", "description": "Organisation ID the project belongs to" }, "version": { "type": "string", "enum": [ "v1", "v2" ], "description": "Project version (v1 or v2)" }, "createdAt": { "type": "string", "description": "Timestamp when the project was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the project was last updated" }, "protected": { "type": "boolean", "description": "Whether the project is protected from deletion" }, "deletedAt": { "type": "string", "nullable": true, "description": "Timestamp when the project was soft deleted" }, "decisionsApprovalMode": { "type": "string", "nullable": true, "enum": [ "require_one_per_team", "none_create_request", "require_any", "none", null ], "description": "Approval mode for decisions" }, "decisionsApprovalGroups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the group" }, "name": { "type": "string", "description": "Name of the group" }, "description": { "type": "string", "description": "Description of the group" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID the group belongs to" }, "roleId": { "type": "string", "format": "uuid", "description": "Role ID associated with the group" } }, "required": [ "id", "name", "projectId" ] }, "description": "Groups required for decision approvals" } }, "required": [ "id", "name", "organisationId", "version", "createdAt", "updatedAt" ], "description": "Updated project with approval settings" } } } } } }, "get": { "operationId": "getProjectApprovals", "summary": "Get project with approvals", "tags": [ "Project" ], "description": "Retrieve project details including the configured approval groups for decisions.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Unique identifier of the project" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Project details with approval configuration", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the project" }, "name": { "type": "string", "description": "Name of the project" }, "key": { "type": "string", "description": "Unique key identifier for the project" }, "organisationId": { "type": "string", "format": "uuid", "description": "Organisation ID the project belongs to" }, "version": { "type": "string", "enum": [ "v1", "v2" ], "description": "Project version (v1 or v2)" }, "createdAt": { "type": "string", "description": "Timestamp when the project was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the project was last updated" }, "protected": { "type": "boolean", "description": "Whether the project is protected from deletion" }, "deletedAt": { "type": "string", "nullable": true, "description": "Timestamp when the project was soft deleted" }, "decisionsApprovalMode": { "type": "string", "nullable": true, "enum": [ "require_one_per_team", "none_create_request", "require_any", "none", null ], "description": "Approval mode for decisions" }, "decisionsApprovalGroups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the group" }, "name": { "type": "string", "description": "Name of the group" }, "description": { "type": "string", "description": "Description of the group" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID the group belongs to" }, "roleId": { "type": "string", "format": "uuid", "description": "Role ID associated with the group" } }, "required": [ "id", "name", "projectId" ] }, "description": "Groups required for decision approvals" } }, "required": [ "id", "name", "organisationId", "version", "createdAt", "updatedAt" ], "description": "Project details with approval configuration" } } } } } } }, "/api/projects/{projectId}/permanently": { "delete": { "operationId": "permanentlyDeleteProject", "summary": "Permanently delete a project", "tags": [ "Project" ], "description": "Permanently delete a soft-deleted project. This action cannot be undone.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Unique identifier of the project to permanently delete" } ], "security": [ { "internalAuth": [] } ], "responses": { "200": { "description": "Permanent deletion confirmation", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ], "description": "Operation status" } }, "required": [ "status" ], "description": "Permanent deletion confirmation" } } } } } } }, "/api/projects/{projectId}/restore": { "put": { "operationId": "restoreProject", "summary": "Restore a project", "tags": [ "Project" ], "description": "Restore a soft-deleted project, making it active again. If the project key conflicts, a new key will be generated.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Unique identifier of the project to restore" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Restored project details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the project" }, "name": { "type": "string", "description": "Name of the project" }, "key": { "type": "string", "description": "Unique key identifier for the project" }, "organisationId": { "type": "string", "format": "uuid", "description": "Organisation ID the project belongs to" }, "version": { "type": "string", "enum": [ "v1", "v2" ], "description": "Project version (v1 or v2)" }, "createdAt": { "type": "string", "description": "Timestamp when the project was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the project was last updated" }, "protected": { "type": "boolean", "description": "Whether the project is protected from deletion" }, "deletedAt": { "type": "string", "nullable": true, "description": "Timestamp when the project was soft deleted" }, "decisionsApprovalMode": { "type": "string", "nullable": true, "enum": [ "require_one_per_team", "none_create_request", "require_any", "none", null ], "description": "Approval mode for decisions" }, "decisionsApprovalGroups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the group" }, "name": { "type": "string", "description": "Name of the group" }, "description": { "type": "string", "description": "Description of the group" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID the group belongs to" }, "roleId": { "type": "string", "format": "uuid", "description": "Role ID associated with the group" } }, "required": [ "id", "name", "projectId" ] }, "description": "Groups required for decision approvals" } }, "required": [ "id", "name", "organisationId", "version", "createdAt", "updatedAt" ], "description": "Restored project details" } } } } } } }, "/api/audit-logs": { "get": { "operationId": "listAuditLogs", "summary": "List audit logs", "tags": [ "Audit log" ], "description": "Retrieve a paginated list of audit log entries for the organisation. Supports filtering by project, user, date range, type, and action.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "projectId", "description": "Filter by project ID" }, { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "userId", "description": "Filter by user ID" }, { "schema": { "type": "string" }, "in": "query", "name": "fromDate", "description": "Filter entries from this date (inclusive)" }, { "schema": { "type": "string" }, "in": "query", "name": "toDate", "description": "Filter entries until this date (inclusive)" }, { "schema": { "type": "string", "enum": [ "organisation", "user", "group", "accessToken", "project", "document", "release", "member", "personalAccessToken" ] }, "in": "query", "name": "type", "description": "Filter by audit log type" }, { "schema": { "type": "string" }, "in": "query", "name": "action", "description": "Filter by action name" }, { "schema": { "type": "string" }, "in": "query", "name": "orderBy", "description": "Field to order results by" }, { "schema": { "type": "string" }, "in": "query", "name": "sort", "description": "Sort direction (ASC or DESC)" }, { "schema": { "type": "number", "default": 1 }, "in": "query", "name": "page", "description": "Current page" }, { "schema": { "type": "number", "default": 10 }, "in": "query", "name": "perPage", "description": "Number of items per page" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Paginated list of audit logs", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the audit log entry" }, "createdAt": { "type": "string", "description": "Timestamp when the action was performed" }, "type": { "type": "string", "enum": [ "organisation", "user", "group", "accessToken", "project", "document", "release", "member", "personalAccessToken" ], "description": "Category of the audited resource" }, "action": { "type": "string", "description": "Specific action that was performed" }, "ipAddress": { "type": "string", "nullable": true, "description": "IP address of the client that performed the action" }, "userAgent": { "type": "string", "nullable": true, "description": "User agent of the client that performed the action" }, "refId": { "type": "string", "nullable": true, "description": "Reference ID of the affected resource" }, "user": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true } }, "required": [ "id", "email", "firstName", "lastName" ], "description": "User who performed the action" }, "project": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "description": "Project associated with the audit log entry" } }, "required": [ "id", "createdAt", "type", "action", "ipAddress", "userAgent", "refId" ] }, "description": "List of audit log entries" }, "paginate": { "type": "object", "properties": { "current": { "type": "number", "description": "Current page number" }, "from": { "type": "number", "description": "Starting record number on the current page" }, "to": { "type": "number", "description": "Ending record number on the current page" }, "total": { "type": "number", "description": "Total number of records" }, "pageSize": { "type": "number", "description": "Number of records per page" } }, "required": [ "current", "from", "to", "total", "pageSize" ], "description": "Pagination metadata" } }, "required": [ "results", "paginate" ], "description": "Paginated list of audit logs" } } } } } } }, "/api/audit-logs/export": { "get": { "operationId": "exportAuditLogs", "summary": "Export audit logs", "tags": [ "Audit log" ], "description": "Export audit log entries as a CSV file. Supports filtering by project, user, and date range.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "projectId", "description": "Filter by project ID" }, { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "userId", "description": "Filter by user ID" }, { "schema": { "type": "string" }, "in": "query", "name": "fromDate", "description": "Filter entries from this date (inclusive)" }, { "schema": { "type": "string" }, "in": "query", "name": "toDate", "description": "Filter entries until this date (inclusive)" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "CSV file containing audit log entries", "content": { "text/csv": { "schema": { "type": "string", "description": "CSV file containing audit log entries" } } } } } } }, "/api/audit-logs/{auditLogId}": { "get": { "operationId": "getAuditLog", "summary": "Get audit log", "tags": [ "Audit log" ], "description": "Retrieve a single audit log entry by ID, including the full data payload.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "auditLogId", "required": true, "description": "Audit log entry ID" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Audit log entry with full details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the audit log entry" }, "createdAt": { "type": "string", "description": "Timestamp when the action was performed" }, "type": { "type": "string", "enum": [ "organisation", "user", "group", "accessToken", "project", "document", "release", "member", "personalAccessToken" ], "description": "Category of the audited resource" }, "action": { "type": "string", "description": "Specific action that was performed" }, "ipAddress": { "type": "string", "nullable": true, "description": "IP address of the client that performed the action" }, "userAgent": { "type": "string", "nullable": true, "description": "User agent of the client that performed the action" }, "refId": { "type": "string", "nullable": true, "description": "Reference ID of the affected resource" }, "user": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true } }, "required": [ "id", "email", "firstName", "lastName" ], "description": "User who performed the action" }, "project": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "description": "Project associated with the audit log entry" }, "data": { "nullable": true, "description": "Detailed payload of the action, containing before/after state" }, "organisationId": { "type": "string", "nullable": true, "format": "uuid", "description": "Organisation ID associated with the audit log" } }, "required": [ "id", "createdAt", "type", "action", "ipAddress", "userAgent", "refId", "organisationId" ], "description": "Audit log entry with full details" } } } } } } }, "/api/personal-access-tokens": { "get": { "operationId": "listPersonalAccessTokens", "summary": "List tokens", "tags": [ "Personal access token" ], "description": "Retrieve all personal access tokens for the authenticated user or a specified service user.", "parameters": [ { "schema": { "type": "string", "nullable": true, "format": "uuid" }, "in": "path", "name": "userId", "required": true, "description": "Service user ID to list tokens for (admin only)" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "List of personal access tokens", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the personal access token" }, "note": { "type": "string", "description": "Description or note for the token" }, "permissions": { "type": "array", "items": { "type": "string", "enum": [ "owner", "documents", "releases", "releases:manage", "releases:deploy", "releases:delete", "integrations:manage", "documents:full", "documents:view-content", "documents:edit-content", "documents:edit-view", "branches", "branches:create", "branches:merge", "branches:delete", "project:manage", "environments", "environments:manage", "environments:delete" ] }, "description": "List of permissions granted to this token" }, "allProjects": { "type": "boolean", "description": "Whether the token has access to all projects" }, "projects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the project" }, "name": { "type": "string", "description": "Name of the project" }, "key": { "type": "string", "description": "Project key" }, "organisationId": { "type": "string", "format": "uuid", "description": "Organisation ID the project belongs to" }, "version": { "type": "string", "description": "Project version" }, "createdAt": { "type": "string", "description": "Timestamp when the project was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the project was last updated" }, "protected": { "type": "boolean", "description": "Whether the project is protected" } }, "required": [ "id", "name", "organisationId", "version", "createdAt", "updatedAt" ] }, "description": "List of projects the token has access to" }, "user": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the user" }, "email": { "type": "string", "format": "email", "description": "Email address of the user" }, "firstName": { "type": "string", "nullable": true, "description": "First name of the user" }, "lastName": { "type": "string", "nullable": true, "description": "Last name of the user" }, "type": { "type": "string", "description": "User type (e.g., member, admin, owner)" }, "status": { "type": "string", "description": "User status (e.g., active, disabled)" }, "isService": { "type": "boolean", "description": "Whether the user is a service account" }, "createdAt": { "type": "string", "description": "Timestamp when the user was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the user was last updated" } }, "required": [ "id", "email", "type", "status", "createdAt", "updatedAt" ], "description": "User who owns the token" }, "createdAt": { "type": "string", "description": "Timestamp when the token was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the token was last updated" }, "expiresAt": { "type": "string", "nullable": true, "description": "Timestamp when the token expires, null if indefinite" } }, "required": [ "id", "note", "permissions", "allProjects", "projects", "user", "createdAt", "updatedAt" ] }, "description": "List of personal access tokens" } } } } } }, "post": { "operationId": "createPersonalAccessToken", "summary": "Create token", "tags": [ "Personal access token" ], "description": "Create a new personal access token with specified permissions and project access.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string", "minLength": 1, "maxLength": 100, "example": "Token used to generate releases", "description": "A descriptive note for the token (1-100 characters)" }, "allProjects": { "type": "boolean", "description": "Indicates if token can be used for all projects." }, "projects": { "type": "array", "items": { "type": "string", "format": "uuid" }, "default": [], "description": "List of projects where token can be used. Applicable if allProjects is false." }, "permissions": { "type": "array", "items": { "type": "string", "enum": [ "owner", "documents", "releases", "releases:manage", "releases:deploy", "releases:delete", "integrations:manage", "documents:full", "documents:view-content", "documents:edit-content", "documents:edit-view", "branches", "branches:create", "branches:merge", "branches:delete", "project:manage", "environments", "environments:manage", "environments:delete" ] }, "default": [], "description": "List of permissions to grant to the token" }, "expiry": { "type": "string", "enum": [ "week", "month", "three_months", "year", "indefinite" ], "description": "Token expiration period (week, month, three_months, year, or indefinite)" } }, "required": [ "note", "allProjects", "expiry" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "nullable": true, "format": "uuid" }, "in": "path", "name": "userId", "required": true, "description": "Service user ID to create token for (admin only)" } ], "security": [ { "internalAuth": [] } ], "responses": { "200": { "description": "Created personal access token with the generated token value", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the personal access token" }, "note": { "type": "string", "description": "Description or note for the token" }, "permissions": { "type": "array", "items": { "type": "string", "enum": [ "owner", "documents", "releases", "releases:manage", "releases:deploy", "releases:delete", "integrations:manage", "documents:full", "documents:view-content", "documents:edit-content", "documents:edit-view", "branches", "branches:create", "branches:merge", "branches:delete", "project:manage", "environments", "environments:manage", "environments:delete" ] }, "description": "List of permissions granted to this token" }, "allProjects": { "type": "boolean", "description": "Whether the token has access to all projects" }, "projects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the project" }, "name": { "type": "string", "description": "Name of the project" }, "key": { "type": "string", "description": "Project key" }, "organisationId": { "type": "string", "format": "uuid", "description": "Organisation ID the project belongs to" }, "version": { "type": "string", "description": "Project version" }, "createdAt": { "type": "string", "description": "Timestamp when the project was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the project was last updated" }, "protected": { "type": "boolean", "description": "Whether the project is protected" } }, "required": [ "id", "name", "organisationId", "version", "createdAt", "updatedAt" ] }, "description": "List of projects the token has access to" }, "user": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the user" }, "email": { "type": "string", "format": "email", "description": "Email address of the user" }, "firstName": { "type": "string", "nullable": true, "description": "First name of the user" }, "lastName": { "type": "string", "nullable": true, "description": "Last name of the user" }, "type": { "type": "string", "description": "User type (e.g., member, admin, owner)" }, "status": { "type": "string", "description": "User status (e.g., active, disabled)" }, "isService": { "type": "boolean", "description": "Whether the user is a service account" }, "createdAt": { "type": "string", "description": "Timestamp when the user was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the user was last updated" } }, "required": [ "id", "email", "type", "status", "createdAt", "updatedAt" ], "description": "User who owns the token" }, "createdAt": { "type": "string", "description": "Timestamp when the token was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the token was last updated" }, "expiresAt": { "type": "string", "nullable": true, "description": "Timestamp when the token expires, null if indefinite" }, "token": { "type": "string", "description": "The generated token value (only returned on create or regenerate)" } }, "required": [ "id", "note", "permissions", "allProjects", "projects", "user", "createdAt", "updatedAt", "token" ], "description": "Created personal access token with the generated token value" } } } } } } }, "/api/personal-access-tokens/{patId}": { "get": { "operationId": "getPersonalAccessToken", "summary": "Get token", "tags": [ "Personal access token" ], "description": "Retrieve a single personal access token by ID.", "parameters": [ { "schema": { "type": "string", "nullable": true, "format": "uuid" }, "in": "path", "name": "userId", "required": true, "description": "Service user ID to get token for (admin only)" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "patId", "required": true, "description": "Personal access token ID" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Personal access token details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the personal access token" }, "note": { "type": "string", "description": "Description or note for the token" }, "permissions": { "type": "array", "items": { "type": "string", "enum": [ "owner", "documents", "releases", "releases:manage", "releases:deploy", "releases:delete", "integrations:manage", "documents:full", "documents:view-content", "documents:edit-content", "documents:edit-view", "branches", "branches:create", "branches:merge", "branches:delete", "project:manage", "environments", "environments:manage", "environments:delete" ] }, "description": "List of permissions granted to this token" }, "allProjects": { "type": "boolean", "description": "Whether the token has access to all projects" }, "projects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the project" }, "name": { "type": "string", "description": "Name of the project" }, "key": { "type": "string", "description": "Project key" }, "organisationId": { "type": "string", "format": "uuid", "description": "Organisation ID the project belongs to" }, "version": { "type": "string", "description": "Project version" }, "createdAt": { "type": "string", "description": "Timestamp when the project was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the project was last updated" }, "protected": { "type": "boolean", "description": "Whether the project is protected" } }, "required": [ "id", "name", "organisationId", "version", "createdAt", "updatedAt" ] }, "description": "List of projects the token has access to" }, "user": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the user" }, "email": { "type": "string", "format": "email", "description": "Email address of the user" }, "firstName": { "type": "string", "nullable": true, "description": "First name of the user" }, "lastName": { "type": "string", "nullable": true, "description": "Last name of the user" }, "type": { "type": "string", "description": "User type (e.g., member, admin, owner)" }, "status": { "type": "string", "description": "User status (e.g., active, disabled)" }, "isService": { "type": "boolean", "description": "Whether the user is a service account" }, "createdAt": { "type": "string", "description": "Timestamp when the user was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the user was last updated" } }, "required": [ "id", "email", "type", "status", "createdAt", "updatedAt" ], "description": "User who owns the token" }, "createdAt": { "type": "string", "description": "Timestamp when the token was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the token was last updated" }, "expiresAt": { "type": "string", "nullable": true, "description": "Timestamp when the token expires, null if indefinite" } }, "required": [ "id", "note", "permissions", "allProjects", "projects", "user", "createdAt", "updatedAt" ], "description": "Personal access token details" } } } } } }, "delete": { "operationId": "deletePersonalAccessToken", "summary": "Delete token", "tags": [ "Personal access token" ], "description": "Note that any pipelines that depend on the token will stop functioning.", "parameters": [ { "schema": { "type": "string", "nullable": true, "format": "uuid" }, "in": "path", "name": "userId", "required": true, "description": "Service user ID to delete token for (admin only)" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "patId", "required": true, "description": "Personal access token ID to delete" } ], "security": [ { "internalAuth": [] } ], "responses": { "200": { "description": "Deleted personal access token details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the personal access token" }, "note": { "type": "string", "description": "Description or note for the token" }, "permissions": { "type": "array", "items": { "type": "string", "enum": [ "owner", "documents", "releases", "releases:manage", "releases:deploy", "releases:delete", "integrations:manage", "documents:full", "documents:view-content", "documents:edit-content", "documents:edit-view", "branches", "branches:create", "branches:merge", "branches:delete", "project:manage", "environments", "environments:manage", "environments:delete" ] }, "description": "List of permissions granted to this token" }, "allProjects": { "type": "boolean", "description": "Whether the token has access to all projects" }, "projects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the project" }, "name": { "type": "string", "description": "Name of the project" }, "key": { "type": "string", "description": "Project key" }, "organisationId": { "type": "string", "format": "uuid", "description": "Organisation ID the project belongs to" }, "version": { "type": "string", "description": "Project version" }, "createdAt": { "type": "string", "description": "Timestamp when the project was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the project was last updated" }, "protected": { "type": "boolean", "description": "Whether the project is protected" } }, "required": [ "id", "name", "organisationId", "version", "createdAt", "updatedAt" ] }, "description": "List of projects the token has access to" }, "user": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the user" }, "email": { "type": "string", "format": "email", "description": "Email address of the user" }, "firstName": { "type": "string", "nullable": true, "description": "First name of the user" }, "lastName": { "type": "string", "nullable": true, "description": "Last name of the user" }, "type": { "type": "string", "description": "User type (e.g., member, admin, owner)" }, "status": { "type": "string", "description": "User status (e.g., active, disabled)" }, "isService": { "type": "boolean", "description": "Whether the user is a service account" }, "createdAt": { "type": "string", "description": "Timestamp when the user was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the user was last updated" } }, "required": [ "id", "email", "type", "status", "createdAt", "updatedAt" ], "description": "User who owns the token" }, "createdAt": { "type": "string", "description": "Timestamp when the token was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the token was last updated" }, "expiresAt": { "type": "string", "nullable": true, "description": "Timestamp when the token expires, null if indefinite" } }, "required": [ "id", "note", "permissions", "allProjects", "projects", "user", "createdAt", "updatedAt" ], "description": "Deleted personal access token details" } } } } } } }, "/api/personal-access-tokens/{patId}/regenerate": { "post": { "operationId": "regeneratePersonalAccessToken", "summary": "Regenerate token", "tags": [ "Personal access token" ], "description": "Note that any pipelines that depend on the token will stop functioning.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "expiry": { "type": "string", "enum": [ "week", "month", "three_months", "year", "indefinite" ], "description": "New token expiration period (week, month, three_months, year, or indefinite)" } }, "required": [ "expiry" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "nullable": true, "format": "uuid" }, "in": "path", "name": "userId", "required": true, "description": "Service user ID to regenerate token for (admin only)" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "patId", "required": true, "description": "Personal access token ID to regenerate" } ], "security": [ { "internalAuth": [] } ], "responses": { "200": { "description": "Regenerated personal access token with the new token value", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the personal access token" }, "note": { "type": "string", "description": "Description or note for the token" }, "permissions": { "type": "array", "items": { "type": "string", "enum": [ "owner", "documents", "releases", "releases:manage", "releases:deploy", "releases:delete", "integrations:manage", "documents:full", "documents:view-content", "documents:edit-content", "documents:edit-view", "branches", "branches:create", "branches:merge", "branches:delete", "project:manage", "environments", "environments:manage", "environments:delete" ] }, "description": "List of permissions granted to this token" }, "allProjects": { "type": "boolean", "description": "Whether the token has access to all projects" }, "projects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the project" }, "name": { "type": "string", "description": "Name of the project" }, "key": { "type": "string", "description": "Project key" }, "organisationId": { "type": "string", "format": "uuid", "description": "Organisation ID the project belongs to" }, "version": { "type": "string", "description": "Project version" }, "createdAt": { "type": "string", "description": "Timestamp when the project was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the project was last updated" }, "protected": { "type": "boolean", "description": "Whether the project is protected" } }, "required": [ "id", "name", "organisationId", "version", "createdAt", "updatedAt" ] }, "description": "List of projects the token has access to" }, "user": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the user" }, "email": { "type": "string", "format": "email", "description": "Email address of the user" }, "firstName": { "type": "string", "nullable": true, "description": "First name of the user" }, "lastName": { "type": "string", "nullable": true, "description": "Last name of the user" }, "type": { "type": "string", "description": "User type (e.g., member, admin, owner)" }, "status": { "type": "string", "description": "User status (e.g., active, disabled)" }, "isService": { "type": "boolean", "description": "Whether the user is a service account" }, "createdAt": { "type": "string", "description": "Timestamp when the user was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the user was last updated" } }, "required": [ "id", "email", "type", "status", "createdAt", "updatedAt" ], "description": "User who owns the token" }, "createdAt": { "type": "string", "description": "Timestamp when the token was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the token was last updated" }, "expiresAt": { "type": "string", "nullable": true, "description": "Timestamp when the token expires, null if indefinite" }, "token": { "type": "string", "description": "The generated token value (only returned on create or regenerate)" } }, "required": [ "id", "note", "permissions", "allProjects", "projects", "user", "createdAt", "updatedAt", "token" ], "description": "Regenerated personal access token with the new token value" } } } } } } }, "/api/users/service/{userId}/personal-access-tokens": { "get": { "operationId": "listPersonalAccessTokens", "summary": "List service account tokens", "tags": [ "Personal access token" ], "description": "Retrieve all personal access tokens for the authenticated user or a specified service user.", "parameters": [ { "schema": { "type": "string", "nullable": true, "format": "uuid" }, "in": "path", "name": "userId", "required": true, "description": "Service user ID to list tokens for (admin only)" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "List of personal access tokens", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the personal access token" }, "note": { "type": "string", "description": "Description or note for the token" }, "permissions": { "type": "array", "items": { "type": "string", "enum": [ "owner", "documents", "releases", "releases:manage", "releases:deploy", "releases:delete", "integrations:manage", "documents:full", "documents:view-content", "documents:edit-content", "documents:edit-view", "branches", "branches:create", "branches:merge", "branches:delete", "project:manage", "environments", "environments:manage", "environments:delete" ] }, "description": "List of permissions granted to this token" }, "allProjects": { "type": "boolean", "description": "Whether the token has access to all projects" }, "projects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the project" }, "name": { "type": "string", "description": "Name of the project" }, "key": { "type": "string", "description": "Project key" }, "organisationId": { "type": "string", "format": "uuid", "description": "Organisation ID the project belongs to" }, "version": { "type": "string", "description": "Project version" }, "createdAt": { "type": "string", "description": "Timestamp when the project was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the project was last updated" }, "protected": { "type": "boolean", "description": "Whether the project is protected" } }, "required": [ "id", "name", "organisationId", "version", "createdAt", "updatedAt" ] }, "description": "List of projects the token has access to" }, "user": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the user" }, "email": { "type": "string", "format": "email", "description": "Email address of the user" }, "firstName": { "type": "string", "nullable": true, "description": "First name of the user" }, "lastName": { "type": "string", "nullable": true, "description": "Last name of the user" }, "type": { "type": "string", "description": "User type (e.g., member, admin, owner)" }, "status": { "type": "string", "description": "User status (e.g., active, disabled)" }, "isService": { "type": "boolean", "description": "Whether the user is a service account" }, "createdAt": { "type": "string", "description": "Timestamp when the user was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the user was last updated" } }, "required": [ "id", "email", "type", "status", "createdAt", "updatedAt" ], "description": "User who owns the token" }, "createdAt": { "type": "string", "description": "Timestamp when the token was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the token was last updated" }, "expiresAt": { "type": "string", "nullable": true, "description": "Timestamp when the token expires, null if indefinite" } }, "required": [ "id", "note", "permissions", "allProjects", "projects", "user", "createdAt", "updatedAt" ] }, "description": "List of personal access tokens" } } } } } }, "post": { "operationId": "createPersonalAccessToken", "summary": "Create service account token", "tags": [ "Personal access token" ], "description": "Create a new personal access token with specified permissions and project access.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string", "minLength": 1, "maxLength": 100, "example": "Token used to generate releases", "description": "A descriptive note for the token (1-100 characters)" }, "allProjects": { "type": "boolean", "description": "Indicates if token can be used for all projects." }, "projects": { "type": "array", "items": { "type": "string", "format": "uuid" }, "default": [], "description": "List of projects where token can be used. Applicable if allProjects is false." }, "permissions": { "type": "array", "items": { "type": "string", "enum": [ "owner", "documents", "releases", "releases:manage", "releases:deploy", "releases:delete", "integrations:manage", "documents:full", "documents:view-content", "documents:edit-content", "documents:edit-view", "branches", "branches:create", "branches:merge", "branches:delete", "project:manage", "environments", "environments:manage", "environments:delete" ] }, "default": [], "description": "List of permissions to grant to the token" }, "expiry": { "type": "string", "enum": [ "week", "month", "three_months", "year", "indefinite" ], "description": "Token expiration period (week, month, three_months, year, or indefinite)" } }, "required": [ "note", "allProjects", "expiry" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "nullable": true, "format": "uuid" }, "in": "path", "name": "userId", "required": true, "description": "Service user ID to create token for (admin only)" } ], "security": [ { "internalAuth": [] } ], "responses": { "200": { "description": "Created personal access token with the generated token value", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the personal access token" }, "note": { "type": "string", "description": "Description or note for the token" }, "permissions": { "type": "array", "items": { "type": "string", "enum": [ "owner", "documents", "releases", "releases:manage", "releases:deploy", "releases:delete", "integrations:manage", "documents:full", "documents:view-content", "documents:edit-content", "documents:edit-view", "branches", "branches:create", "branches:merge", "branches:delete", "project:manage", "environments", "environments:manage", "environments:delete" ] }, "description": "List of permissions granted to this token" }, "allProjects": { "type": "boolean", "description": "Whether the token has access to all projects" }, "projects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the project" }, "name": { "type": "string", "description": "Name of the project" }, "key": { "type": "string", "description": "Project key" }, "organisationId": { "type": "string", "format": "uuid", "description": "Organisation ID the project belongs to" }, "version": { "type": "string", "description": "Project version" }, "createdAt": { "type": "string", "description": "Timestamp when the project was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the project was last updated" }, "protected": { "type": "boolean", "description": "Whether the project is protected" } }, "required": [ "id", "name", "organisationId", "version", "createdAt", "updatedAt" ] }, "description": "List of projects the token has access to" }, "user": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the user" }, "email": { "type": "string", "format": "email", "description": "Email address of the user" }, "firstName": { "type": "string", "nullable": true, "description": "First name of the user" }, "lastName": { "type": "string", "nullable": true, "description": "Last name of the user" }, "type": { "type": "string", "description": "User type (e.g., member, admin, owner)" }, "status": { "type": "string", "description": "User status (e.g., active, disabled)" }, "isService": { "type": "boolean", "description": "Whether the user is a service account" }, "createdAt": { "type": "string", "description": "Timestamp when the user was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the user was last updated" } }, "required": [ "id", "email", "type", "status", "createdAt", "updatedAt" ], "description": "User who owns the token" }, "createdAt": { "type": "string", "description": "Timestamp when the token was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the token was last updated" }, "expiresAt": { "type": "string", "nullable": true, "description": "Timestamp when the token expires, null if indefinite" }, "token": { "type": "string", "description": "The generated token value (only returned on create or regenerate)" } }, "required": [ "id", "note", "permissions", "allProjects", "projects", "user", "createdAt", "updatedAt", "token" ], "description": "Created personal access token with the generated token value" } } } } } } }, "/api/users/service/{userId}/personal-access-tokens/{patId}": { "get": { "operationId": "getPersonalAccessToken", "summary": "Get service account token", "tags": [ "Personal access token" ], "description": "Retrieve a single personal access token by ID.", "parameters": [ { "schema": { "type": "string", "nullable": true, "format": "uuid" }, "in": "path", "name": "userId", "required": true, "description": "Service user ID to get token for (admin only)" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "patId", "required": true, "description": "Personal access token ID" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Personal access token details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the personal access token" }, "note": { "type": "string", "description": "Description or note for the token" }, "permissions": { "type": "array", "items": { "type": "string", "enum": [ "owner", "documents", "releases", "releases:manage", "releases:deploy", "releases:delete", "integrations:manage", "documents:full", "documents:view-content", "documents:edit-content", "documents:edit-view", "branches", "branches:create", "branches:merge", "branches:delete", "project:manage", "environments", "environments:manage", "environments:delete" ] }, "description": "List of permissions granted to this token" }, "allProjects": { "type": "boolean", "description": "Whether the token has access to all projects" }, "projects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the project" }, "name": { "type": "string", "description": "Name of the project" }, "key": { "type": "string", "description": "Project key" }, "organisationId": { "type": "string", "format": "uuid", "description": "Organisation ID the project belongs to" }, "version": { "type": "string", "description": "Project version" }, "createdAt": { "type": "string", "description": "Timestamp when the project was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the project was last updated" }, "protected": { "type": "boolean", "description": "Whether the project is protected" } }, "required": [ "id", "name", "organisationId", "version", "createdAt", "updatedAt" ] }, "description": "List of projects the token has access to" }, "user": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the user" }, "email": { "type": "string", "format": "email", "description": "Email address of the user" }, "firstName": { "type": "string", "nullable": true, "description": "First name of the user" }, "lastName": { "type": "string", "nullable": true, "description": "Last name of the user" }, "type": { "type": "string", "description": "User type (e.g., member, admin, owner)" }, "status": { "type": "string", "description": "User status (e.g., active, disabled)" }, "isService": { "type": "boolean", "description": "Whether the user is a service account" }, "createdAt": { "type": "string", "description": "Timestamp when the user was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the user was last updated" } }, "required": [ "id", "email", "type", "status", "createdAt", "updatedAt" ], "description": "User who owns the token" }, "createdAt": { "type": "string", "description": "Timestamp when the token was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the token was last updated" }, "expiresAt": { "type": "string", "nullable": true, "description": "Timestamp when the token expires, null if indefinite" } }, "required": [ "id", "note", "permissions", "allProjects", "projects", "user", "createdAt", "updatedAt" ], "description": "Personal access token details" } } } } } }, "delete": { "operationId": "deletePersonalAccessToken", "summary": "Delete service account token", "tags": [ "Personal access token" ], "description": "Note that any pipelines that depend on the token will stop functioning.", "parameters": [ { "schema": { "type": "string", "nullable": true, "format": "uuid" }, "in": "path", "name": "userId", "required": true, "description": "Service user ID to delete token for (admin only)" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "patId", "required": true, "description": "Personal access token ID to delete" } ], "security": [ { "internalAuth": [] } ], "responses": { "200": { "description": "Deleted personal access token details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the personal access token" }, "note": { "type": "string", "description": "Description or note for the token" }, "permissions": { "type": "array", "items": { "type": "string", "enum": [ "owner", "documents", "releases", "releases:manage", "releases:deploy", "releases:delete", "integrations:manage", "documents:full", "documents:view-content", "documents:edit-content", "documents:edit-view", "branches", "branches:create", "branches:merge", "branches:delete", "project:manage", "environments", "environments:manage", "environments:delete" ] }, "description": "List of permissions granted to this token" }, "allProjects": { "type": "boolean", "description": "Whether the token has access to all projects" }, "projects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the project" }, "name": { "type": "string", "description": "Name of the project" }, "key": { "type": "string", "description": "Project key" }, "organisationId": { "type": "string", "format": "uuid", "description": "Organisation ID the project belongs to" }, "version": { "type": "string", "description": "Project version" }, "createdAt": { "type": "string", "description": "Timestamp when the project was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the project was last updated" }, "protected": { "type": "boolean", "description": "Whether the project is protected" } }, "required": [ "id", "name", "organisationId", "version", "createdAt", "updatedAt" ] }, "description": "List of projects the token has access to" }, "user": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the user" }, "email": { "type": "string", "format": "email", "description": "Email address of the user" }, "firstName": { "type": "string", "nullable": true, "description": "First name of the user" }, "lastName": { "type": "string", "nullable": true, "description": "Last name of the user" }, "type": { "type": "string", "description": "User type (e.g., member, admin, owner)" }, "status": { "type": "string", "description": "User status (e.g., active, disabled)" }, "isService": { "type": "boolean", "description": "Whether the user is a service account" }, "createdAt": { "type": "string", "description": "Timestamp when the user was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the user was last updated" } }, "required": [ "id", "email", "type", "status", "createdAt", "updatedAt" ], "description": "User who owns the token" }, "createdAt": { "type": "string", "description": "Timestamp when the token was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the token was last updated" }, "expiresAt": { "type": "string", "nullable": true, "description": "Timestamp when the token expires, null if indefinite" } }, "required": [ "id", "note", "permissions", "allProjects", "projects", "user", "createdAt", "updatedAt" ], "description": "Deleted personal access token details" } } } } } } }, "/api/users/service/{userId}/personal-access-tokens/{patId}/regenerate": { "post": { "operationId": "regeneratePersonalAccessToken", "summary": "Regenerate service account token", "tags": [ "Personal access token" ], "description": "Note that any pipelines that depend on the token will stop functioning.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "expiry": { "type": "string", "enum": [ "week", "month", "three_months", "year", "indefinite" ], "description": "New token expiration period (week, month, three_months, year, or indefinite)" } }, "required": [ "expiry" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "nullable": true, "format": "uuid" }, "in": "path", "name": "userId", "required": true, "description": "Service user ID to regenerate token for (admin only)" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "patId", "required": true, "description": "Personal access token ID to regenerate" } ], "security": [ { "internalAuth": [] } ], "responses": { "200": { "description": "Regenerated personal access token with the new token value", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the personal access token" }, "note": { "type": "string", "description": "Description or note for the token" }, "permissions": { "type": "array", "items": { "type": "string", "enum": [ "owner", "documents", "releases", "releases:manage", "releases:deploy", "releases:delete", "integrations:manage", "documents:full", "documents:view-content", "documents:edit-content", "documents:edit-view", "branches", "branches:create", "branches:merge", "branches:delete", "project:manage", "environments", "environments:manage", "environments:delete" ] }, "description": "List of permissions granted to this token" }, "allProjects": { "type": "boolean", "description": "Whether the token has access to all projects" }, "projects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the project" }, "name": { "type": "string", "description": "Name of the project" }, "key": { "type": "string", "description": "Project key" }, "organisationId": { "type": "string", "format": "uuid", "description": "Organisation ID the project belongs to" }, "version": { "type": "string", "description": "Project version" }, "createdAt": { "type": "string", "description": "Timestamp when the project was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the project was last updated" }, "protected": { "type": "boolean", "description": "Whether the project is protected" } }, "required": [ "id", "name", "organisationId", "version", "createdAt", "updatedAt" ] }, "description": "List of projects the token has access to" }, "user": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the user" }, "email": { "type": "string", "format": "email", "description": "Email address of the user" }, "firstName": { "type": "string", "nullable": true, "description": "First name of the user" }, "lastName": { "type": "string", "nullable": true, "description": "Last name of the user" }, "type": { "type": "string", "description": "User type (e.g., member, admin, owner)" }, "status": { "type": "string", "description": "User status (e.g., active, disabled)" }, "isService": { "type": "boolean", "description": "Whether the user is a service account" }, "createdAt": { "type": "string", "description": "Timestamp when the user was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the user was last updated" } }, "required": [ "id", "email", "type", "status", "createdAt", "updatedAt" ], "description": "User who owns the token" }, "createdAt": { "type": "string", "description": "Timestamp when the token was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the token was last updated" }, "expiresAt": { "type": "string", "nullable": true, "description": "Timestamp when the token expires, null if indefinite" }, "token": { "type": "string", "description": "The generated token value (only returned on create or regenerate)" } }, "required": [ "id", "note", "permissions", "allProjects", "projects", "user", "createdAt", "updatedAt", "token" ], "description": "Regenerated personal access token with the new token value" } } } } } } }, "/api/projects/{projectId}/integrations": { "get": { "operationId": "listIntegrations", "summary": "List integrations", "tags": [ "Integration" ], "description": "Retrieve a paginated list of integrations for the specified project.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "search", "description": "Search term to filter integrations by name" }, { "schema": { "type": "number", "default": 1 }, "in": "query", "name": "page", "description": "Current page" }, { "schema": { "type": "number", "default": 10 }, "in": "query", "name": "perPage", "description": "Number of items per page" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project ID" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Paginated list of integrations", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the integration" }, "type": { "type": "string", "enum": [ "http" ], "description": "Type of integration" }, "config": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "post", "get", "delete", "put", "patch" ], "description": "HTTP method for the request" }, "url": { "type": "string", "description": "URL endpoint for the HTTP request" }, "timeout": { "type": "number", "default": 5000, "description": "Request timeout in milliseconds" }, "output": { "type": "string", "nullable": true, "description": "Output mapping configuration" }, "headers": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Header name" }, "value": { "type": "string", "description": "Header value" } }, "required": [ "key", "value" ], "description": "HTTP header key-value pair" }, "default": [], "description": "HTTP headers to include in the request" }, "cookies": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Cookie name" }, "value": { "type": "string", "description": "Cookie value" } }, "required": [ "key", "value" ], "description": "HTTP cookie key-value pair" }, "default": [], "description": "Cookies to include in the request" }, "enableInputs": { "type": "boolean", "default": false, "description": "Enable custom input fields" }, "inputs": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "control": { "type": "string", "enum": [ "text", "checkbox" ], "description": "Input control type" }, "name": { "type": "string", "description": "Input field name" }, "label": { "type": "string", "description": "Input field label" } }, "required": [ "control", "name", "label" ], "description": "Custom input field configuration" }, "default": [], "description": "Custom input field definitions" } }, "required": [ "method", "url", "timeout", "headers", "cookies", "enableInputs", "inputs" ], "description": "Integration configuration" }, "name": { "type": "string", "description": "Name of the integration" }, "description": { "type": "string", "nullable": true, "description": "Description of the integration" }, "group": { "type": "string", "nullable": true, "description": "Group the integration belongs to" }, "kind": { "type": "string", "description": "Unique kind identifier for the integration" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID the integration belongs to" }, "createdAt": { "type": "string", "description": "Timestamp when the integration was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the integration was last updated" }, "deletedAt": { "type": "string", "nullable": true, "description": "Timestamp when the integration was deleted" } }, "required": [ "id", "type", "config", "name", "kind", "projectId", "createdAt", "updatedAt" ], "description": "Integration entity" }, "description": "List of integrations" }, "paginate": { "type": "object", "properties": { "current": { "type": "number", "description": "Current page number" }, "from": { "type": "number", "description": "Starting record number on the current page" }, "to": { "type": "number", "description": "Ending record number on the current page" }, "total": { "type": "number", "description": "Total number of records" }, "pageSize": { "type": "number", "description": "Number of records per page" } }, "required": [ "current", "from", "to", "total", "pageSize" ], "description": "Pagination metadata" } }, "required": [ "results", "paginate" ], "description": "Paginated list of integrations" } } } } } }, "post": { "operationId": "createIntegration", "summary": "Create integration", "tags": [ "Integration" ], "description": "Create a new integration within the specified project.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the integration" }, "description": { "type": "string", "nullable": true, "description": "Description of the integration" }, "group": { "type": "string", "nullable": true, "description": "Group the integration belongs to" }, "type": { "type": "string", "enum": [ "http" ], "description": "Type of integration" }, "kind": { "type": "string", "pattern": "^[a-z][a-z0-9_.]*$", "description": "Unique kind identifier (lowercase, alphanumeric with dots and underscores)" }, "config": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "post", "get", "delete", "put", "patch" ], "description": "HTTP method for the request" }, "url": { "type": "string", "description": "URL endpoint for the HTTP request" }, "timeout": { "type": "number", "default": 5000, "description": "Request timeout in milliseconds" }, "output": { "type": "string", "nullable": true, "description": "Output mapping configuration" }, "headers": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Header name" }, "value": { "type": "string", "description": "Header value" } }, "required": [ "key", "value" ], "description": "HTTP header key-value pair" }, "default": [], "description": "HTTP headers to include in the request" }, "cookies": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Cookie name" }, "value": { "type": "string", "description": "Cookie value" } }, "required": [ "key", "value" ], "description": "HTTP cookie key-value pair" }, "default": [], "description": "Cookies to include in the request" }, "enableInputs": { "type": "boolean", "default": false, "description": "Enable custom input fields" }, "inputs": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "control": { "type": "string", "enum": [ "text", "checkbox" ], "description": "Input control type" }, "name": { "type": "string", "description": "Input field name" }, "label": { "type": "string", "description": "Input field label" } }, "required": [ "control", "name", "label" ], "description": "Custom input field configuration" }, "default": [], "description": "Custom input field definitions" } }, "required": [ "method", "url" ], "description": "HTTP integration configuration" } }, "required": [ "name", "type", "kind", "config" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project ID" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Created integration", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the integration" }, "type": { "type": "string", "enum": [ "http" ], "description": "Type of integration" }, "config": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "post", "get", "delete", "put", "patch" ], "description": "HTTP method for the request" }, "url": { "type": "string", "description": "URL endpoint for the HTTP request" }, "timeout": { "type": "number", "default": 5000, "description": "Request timeout in milliseconds" }, "output": { "type": "string", "nullable": true, "description": "Output mapping configuration" }, "headers": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Header name" }, "value": { "type": "string", "description": "Header value" } }, "required": [ "key", "value" ], "description": "HTTP header key-value pair" }, "default": [], "description": "HTTP headers to include in the request" }, "cookies": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Cookie name" }, "value": { "type": "string", "description": "Cookie value" } }, "required": [ "key", "value" ], "description": "HTTP cookie key-value pair" }, "default": [], "description": "Cookies to include in the request" }, "enableInputs": { "type": "boolean", "default": false, "description": "Enable custom input fields" }, "inputs": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "control": { "type": "string", "enum": [ "text", "checkbox" ], "description": "Input control type" }, "name": { "type": "string", "description": "Input field name" }, "label": { "type": "string", "description": "Input field label" } }, "required": [ "control", "name", "label" ], "description": "Custom input field configuration" }, "default": [], "description": "Custom input field definitions" } }, "required": [ "method", "url", "timeout", "headers", "cookies", "enableInputs", "inputs" ], "description": "Integration configuration" }, "name": { "type": "string", "description": "Name of the integration" }, "description": { "type": "string", "nullable": true, "description": "Description of the integration" }, "group": { "type": "string", "nullable": true, "description": "Group the integration belongs to" }, "kind": { "type": "string", "description": "Unique kind identifier for the integration" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID the integration belongs to" }, "createdAt": { "type": "string", "description": "Timestamp when the integration was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the integration was last updated" }, "deletedAt": { "type": "string", "nullable": true, "description": "Timestamp when the integration was deleted" } }, "required": [ "id", "type", "config", "name", "kind", "projectId", "createdAt", "updatedAt" ], "description": "Created integration" } } } } } } }, "/api/projects/{projectId}/integrations/{integrationId}": { "get": { "operationId": "getIntegration", "summary": "Get integration", "tags": [ "Integration" ], "description": "Retrieve a single integration by its ID.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project ID" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "integrationId", "required": true, "description": "Integration ID" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Integration details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the integration" }, "type": { "type": "string", "enum": [ "http" ], "description": "Type of integration" }, "config": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "post", "get", "delete", "put", "patch" ], "description": "HTTP method for the request" }, "url": { "type": "string", "description": "URL endpoint for the HTTP request" }, "timeout": { "type": "number", "default": 5000, "description": "Request timeout in milliseconds" }, "output": { "type": "string", "nullable": true, "description": "Output mapping configuration" }, "headers": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Header name" }, "value": { "type": "string", "description": "Header value" } }, "required": [ "key", "value" ], "description": "HTTP header key-value pair" }, "default": [], "description": "HTTP headers to include in the request" }, "cookies": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Cookie name" }, "value": { "type": "string", "description": "Cookie value" } }, "required": [ "key", "value" ], "description": "HTTP cookie key-value pair" }, "default": [], "description": "Cookies to include in the request" }, "enableInputs": { "type": "boolean", "default": false, "description": "Enable custom input fields" }, "inputs": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "control": { "type": "string", "enum": [ "text", "checkbox" ], "description": "Input control type" }, "name": { "type": "string", "description": "Input field name" }, "label": { "type": "string", "description": "Input field label" } }, "required": [ "control", "name", "label" ], "description": "Custom input field configuration" }, "default": [], "description": "Custom input field definitions" } }, "required": [ "method", "url", "timeout", "headers", "cookies", "enableInputs", "inputs" ], "description": "Integration configuration" }, "name": { "type": "string", "description": "Name of the integration" }, "description": { "type": "string", "nullable": true, "description": "Description of the integration" }, "group": { "type": "string", "nullable": true, "description": "Group the integration belongs to" }, "kind": { "type": "string", "description": "Unique kind identifier for the integration" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID the integration belongs to" }, "createdAt": { "type": "string", "description": "Timestamp when the integration was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the integration was last updated" }, "deletedAt": { "type": "string", "nullable": true, "description": "Timestamp when the integration was deleted" } }, "required": [ "id", "type", "config", "name", "kind", "projectId", "createdAt", "updatedAt" ], "description": "Integration details" } } } } } }, "put": { "operationId": "updateIntegration", "summary": "Update integration", "tags": [ "Integration" ], "description": "Update an existing integration by its ID.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the integration" }, "description": { "type": "string", "nullable": true, "description": "Description of the integration" }, "group": { "type": "string", "nullable": true, "description": "Group the integration belongs to" }, "config": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "post", "get", "delete", "put", "patch" ], "description": "HTTP method for the request" }, "url": { "type": "string", "description": "URL endpoint for the HTTP request" }, "timeout": { "type": "number", "default": 5000, "description": "Request timeout in milliseconds" }, "output": { "type": "string", "nullable": true, "description": "Output mapping configuration" }, "headers": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Header name" }, "value": { "type": "string", "description": "Header value" } }, "required": [ "key", "value" ], "description": "HTTP header key-value pair" }, "default": [], "description": "HTTP headers to include in the request" }, "cookies": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Cookie name" }, "value": { "type": "string", "description": "Cookie value" } }, "required": [ "key", "value" ], "description": "HTTP cookie key-value pair" }, "default": [], "description": "Cookies to include in the request" }, "enableInputs": { "type": "boolean", "default": false, "description": "Enable custom input fields" }, "inputs": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "control": { "type": "string", "enum": [ "text", "checkbox" ], "description": "Input control type" }, "name": { "type": "string", "description": "Input field name" }, "label": { "type": "string", "description": "Input field label" } }, "required": [ "control", "name", "label" ], "description": "Custom input field configuration" }, "default": [], "description": "Custom input field definitions" } }, "required": [ "method", "url" ], "description": "HTTP integration configuration" } }, "required": [ "name", "config" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project ID" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "integrationId", "required": true, "description": "Integration ID" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Updated integration", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the integration" }, "type": { "type": "string", "enum": [ "http" ], "description": "Type of integration" }, "config": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "post", "get", "delete", "put", "patch" ], "description": "HTTP method for the request" }, "url": { "type": "string", "description": "URL endpoint for the HTTP request" }, "timeout": { "type": "number", "default": 5000, "description": "Request timeout in milliseconds" }, "output": { "type": "string", "nullable": true, "description": "Output mapping configuration" }, "headers": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Header name" }, "value": { "type": "string", "description": "Header value" } }, "required": [ "key", "value" ], "description": "HTTP header key-value pair" }, "default": [], "description": "HTTP headers to include in the request" }, "cookies": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Cookie name" }, "value": { "type": "string", "description": "Cookie value" } }, "required": [ "key", "value" ], "description": "HTTP cookie key-value pair" }, "default": [], "description": "Cookies to include in the request" }, "enableInputs": { "type": "boolean", "default": false, "description": "Enable custom input fields" }, "inputs": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "control": { "type": "string", "enum": [ "text", "checkbox" ], "description": "Input control type" }, "name": { "type": "string", "description": "Input field name" }, "label": { "type": "string", "description": "Input field label" } }, "required": [ "control", "name", "label" ], "description": "Custom input field configuration" }, "default": [], "description": "Custom input field definitions" } }, "required": [ "method", "url", "timeout", "headers", "cookies", "enableInputs", "inputs" ], "description": "Integration configuration" }, "name": { "type": "string", "description": "Name of the integration" }, "description": { "type": "string", "nullable": true, "description": "Description of the integration" }, "group": { "type": "string", "nullable": true, "description": "Group the integration belongs to" }, "kind": { "type": "string", "description": "Unique kind identifier for the integration" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID the integration belongs to" }, "createdAt": { "type": "string", "description": "Timestamp when the integration was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the integration was last updated" }, "deletedAt": { "type": "string", "nullable": true, "description": "Timestamp when the integration was deleted" } }, "required": [ "id", "type", "config", "name", "kind", "projectId", "createdAt", "updatedAt" ], "description": "Updated integration" } } } } } }, "delete": { "operationId": "deleteIntegration", "summary": "Delete integration", "tags": [ "Integration" ], "description": "Soft delete an integration by its ID.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project ID" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "integrationId", "required": true, "description": "Integration ID" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Delete operation successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ], "description": "Operation status" } }, "required": [ "status" ], "description": "Delete operation successful" } } } } } } }, "/api/deployments": { "get": { "operationId": "listDeployments", "summary": "List deployments", "tags": [ "Deployments" ], "description": "Retrieve a list of all deployments configured for the current organisation.", "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "List of deployments", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the deployment" }, "name": { "type": "string", "description": "Name of the deployment" }, "description": { "type": "string", "description": "Description of the deployment" }, "provider": { "type": "string", "enum": [ "aws_s3", "azure_storage", "google_cloud_storage" ], "description": "Cloud storage provider type (aws_s3, azure_storage, google_cloud_storage)" }, "configuration": { "description": "Provider-specific configuration settings" }, "organisationId": { "type": "string", "format": "uuid", "description": "ID of the organisation this deployment belongs to" }, "organisation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the organisation" }, "name": { "type": "string", "description": "Name of the organisation" }, "displayName": { "type": "string", "description": "Display name of the organisation" }, "onboarded": { "type": "boolean", "description": "Whether the organisation has completed onboarding" }, "license": { "type": "string", "description": "License key of the organisation" }, "licenseData": { "description": "License data details" }, "url": { "type": "string", "description": "URL of the organisation" }, "themeLogo": { "type": "string", "description": "Theme logo URL" }, "themePrimaryColor": { "type": "string", "description": "Theme primary color" }, "preferences": { "description": "Organisation preferences" }, "createdAt": { "type": "string", "description": "Timestamp when the organisation was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the organisation was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the organisation was deleted" } }, "required": [ "id", "name", "displayName", "onboarded", "themeLogo", "themePrimaryColor", "createdAt", "updatedAt" ], "description": "Organisation associated with the deployment" }, "createdAt": { "type": "string", "description": "Timestamp when the deployment was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the deployment was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the deployment was deleted" } }, "required": [ "id", "name", "provider", "organisationId", "organisation", "createdAt", "updatedAt" ] }, "description": "List of deployments" } } } } } }, "post": { "operationId": "createDeployment", "summary": "Create deployment", "tags": [ "Deployments" ], "description": "Create a new deployment with the specified cloud storage provider configuration.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the deployment" }, "description": { "type": "string", "nullable": true, "description": "Description of the deployment" }, "provider": { "type": "string", "enum": [ "aws_s3", "azure_storage", "google_cloud_storage" ], "description": "Cloud storage provider type (aws_s3, azure_storage, google_cloud_storage)" }, "configuration": { "description": "Provider-specific configuration settings" }, "secrets": { "nullable": true, "description": "Provider-specific secrets (e.g., access keys, credentials)" } }, "required": [ "name", "provider" ] } } }, "required": true }, "security": [ { "internalAuth": [] } ], "responses": { "200": { "description": "The newly created deployment", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the deployment" }, "name": { "type": "string", "description": "Name of the deployment" }, "description": { "type": "string", "description": "Description of the deployment" }, "provider": { "type": "string", "enum": [ "aws_s3", "azure_storage", "google_cloud_storage" ], "description": "Cloud storage provider type (aws_s3, azure_storage, google_cloud_storage)" }, "configuration": { "description": "Provider-specific configuration settings" }, "organisationId": { "type": "string", "format": "uuid", "description": "ID of the organisation this deployment belongs to" }, "organisation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the organisation" }, "name": { "type": "string", "description": "Name of the organisation" }, "displayName": { "type": "string", "description": "Display name of the organisation" }, "onboarded": { "type": "boolean", "description": "Whether the organisation has completed onboarding" }, "license": { "type": "string", "description": "License key of the organisation" }, "licenseData": { "description": "License data details" }, "url": { "type": "string", "description": "URL of the organisation" }, "themeLogo": { "type": "string", "description": "Theme logo URL" }, "themePrimaryColor": { "type": "string", "description": "Theme primary color" }, "preferences": { "description": "Organisation preferences" }, "createdAt": { "type": "string", "description": "Timestamp when the organisation was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the organisation was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the organisation was deleted" } }, "required": [ "id", "name", "displayName", "onboarded", "themeLogo", "themePrimaryColor", "createdAt", "updatedAt" ], "description": "Organisation associated with the deployment" }, "createdAt": { "type": "string", "description": "Timestamp when the deployment was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the deployment was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the deployment was deleted" } }, "required": [ "id", "name", "provider", "organisationId", "organisation", "createdAt", "updatedAt" ], "description": "The newly created deployment" } } } } } } }, "/api/deployments/{deploymentId}": { "put": { "operationId": "updateDeployment", "summary": "Update deployment", "tags": [ "Deployments" ], "description": "Update an existing deployment configuration by its ID.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the deployment" }, "description": { "type": "string", "nullable": true, "description": "Description of the deployment" }, "configuration": { "description": "Provider-specific configuration settings" }, "updateSecrets": { "type": "boolean", "default": false, "description": "Whether to update the secrets" }, "secrets": { "nullable": true, "description": "Provider-specific secrets (e.g., access keys, credentials)" } }, "required": [ "name" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "deploymentId", "required": true, "description": "Unique identifier of the deployment to update" } ], "security": [ { "internalAuth": [] } ], "responses": { "200": { "description": "The updated deployment", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the deployment" }, "name": { "type": "string", "description": "Name of the deployment" }, "description": { "type": "string", "description": "Description of the deployment" }, "provider": { "type": "string", "enum": [ "aws_s3", "azure_storage", "google_cloud_storage" ], "description": "Cloud storage provider type (aws_s3, azure_storage, google_cloud_storage)" }, "configuration": { "description": "Provider-specific configuration settings" }, "organisationId": { "type": "string", "format": "uuid", "description": "ID of the organisation this deployment belongs to" }, "organisation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the organisation" }, "name": { "type": "string", "description": "Name of the organisation" }, "displayName": { "type": "string", "description": "Display name of the organisation" }, "onboarded": { "type": "boolean", "description": "Whether the organisation has completed onboarding" }, "license": { "type": "string", "description": "License key of the organisation" }, "licenseData": { "description": "License data details" }, "url": { "type": "string", "description": "URL of the organisation" }, "themeLogo": { "type": "string", "description": "Theme logo URL" }, "themePrimaryColor": { "type": "string", "description": "Theme primary color" }, "preferences": { "description": "Organisation preferences" }, "createdAt": { "type": "string", "description": "Timestamp when the organisation was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the organisation was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the organisation was deleted" } }, "required": [ "id", "name", "displayName", "onboarded", "themeLogo", "themePrimaryColor", "createdAt", "updatedAt" ], "description": "Organisation associated with the deployment" }, "createdAt": { "type": "string", "description": "Timestamp when the deployment was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the deployment was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the deployment was deleted" } }, "required": [ "id", "name", "provider", "organisationId", "organisation", "createdAt", "updatedAt" ], "description": "The updated deployment" } } } } } }, "delete": { "operationId": "deleteDeployment", "summary": "Remove deployment", "tags": [ "Deployments" ], "description": "Soft delete a deployment by its ID.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "deploymentId", "required": true, "description": "Unique identifier of the deployment to remove" } ], "security": [ { "internalAuth": [] } ], "responses": { "200": { "description": "Confirmation of the deleted deployment", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID of the deleted deployment" } }, "required": [ "id" ], "description": "Confirmation of the deleted deployment" } } } } } } }, "/api/projects/{projectId}/runs": { "get": { "operationId": "listDeploymentWorkflowRuns", "summary": "List deployment workflow runs", "tags": [ "Deployment workflows" ], "description": "Retrieve a paginated list of deployment workflow runs for a project.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "search", "description": "Search term to filter runs" }, { "schema": { "type": "number", "default": 1 }, "in": "query", "name": "page", "description": "Current page" }, { "schema": { "type": "number", "default": 10 }, "in": "query", "name": "perPage", "description": "Number of items per page" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project unique identifier" } ], "deprecated": true, "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Paginated list of deployment workflow runs", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Workflow run unique identifier" }, "name": { "type": "string", "nullable": true, "description": "Workflow run name" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "cancelled", "waiting", "failure" ], "description": "Current status of the workflow run" }, "runVersion": { "type": "string", "nullable": true, "enum": [ "v2", null ], "description": "Workflow run version" }, "releaseId": { "type": "string", "format": "uuid", "description": "Associated release ID" }, "release": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Release unique identifier" }, "name": { "type": "string", "nullable": true, "description": "Release name" }, "version": { "type": "string", "nullable": true, "description": "Release version" } }, "required": [ "id", "name", "version" ], "description": "Associated release" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID" }, "createdById": { "type": "string", "format": "uuid", "description": "ID of user who created the run" }, "createdBy": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id", "email", "firstName", "lastName" ], "description": "User who created the run" }, "createdAt": { "type": "string", "description": "Timestamp when the run was created" }, "completedAt": { "type": "string", "nullable": true, "description": "Timestamp when the run was completed" }, "cancelledById": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of user who cancelled the run" }, "cancelledBy": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id", "email", "firstName", "lastName" ], "description": "User who cancelled the run" }, "cancelledComment": { "type": "string", "nullable": true, "description": "Cancellation reason" }, "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Job unique identifier" }, "status": { "type": "string", "enum": [ "not_started", "in_progress", "waiting", "failure", "rejected", "completed" ], "description": "Current status of the job" }, "order": { "type": "number", "description": "Order of the job in the workflow" }, "environmentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Associated environment ID" }, "environment": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Environment unique identifier" }, "name": { "type": "string", "description": "Environment name" }, "key": { "type": "string", "nullable": true, "description": "Environment key" } }, "required": [ "id", "name", "key" ], "description": "Associated environment" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID" }, "deploymentWorkflowRunId": { "type": "string", "format": "uuid", "description": "Parent workflow run ID" }, "reviewedAt": { "type": "string", "nullable": true, "description": "Timestamp when the job was reviewed" }, "reviewedBy": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id", "email", "firstName", "lastName" ], "description": "User who reviewed the job" }, "reviewedComment": { "type": "string", "nullable": true, "description": "Review comment" }, "reviewedConclusion": { "type": "string", "nullable": true, "enum": [ "approved", "rejected", null ], "description": "Review conclusion (approved or rejected)" }, "previousRelease": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Release unique identifier" }, "name": { "type": "string", "nullable": true, "description": "Release name" }, "version": { "type": "string", "nullable": true, "description": "Release version" } }, "required": [ "id", "name", "version" ], "description": "Previous release before deployment" }, "previousReleaseId": { "type": "string", "nullable": true, "format": "uuid", "description": "Previous release ID" }, "event": { "type": "string", "nullable": true, "description": "Event type" }, "data": { "nullable": true, "description": "Additional job data" }, "createdAt": { "type": "string", "description": "Timestamp when the job was created" } }, "required": [ "id", "status", "order", "environmentId", "projectId", "deploymentWorkflowRunId", "createdAt" ] }, "description": "List of jobs in the workflow run" } }, "required": [ "id", "name", "status", "releaseId", "projectId", "createdById", "createdAt" ] }, "description": "List of deployment workflow runs" }, "paginate": { "type": "object", "properties": { "current": { "type": "number", "description": "Current page number" }, "from": { "type": "number", "description": "Starting record number" }, "to": { "type": "number", "description": "Ending record number" }, "total": { "type": "number", "description": "Total number of records" }, "pageSize": { "type": "number", "description": "Number of records per page" } }, "required": [ "current", "from", "to", "total", "pageSize" ], "description": "Pagination metadata" } }, "required": [ "results", "paginate" ], "description": "Paginated list of deployment workflow runs" } } } } } } }, "/api/projects/{projectId}/runs/{runId}": { "get": { "operationId": "getDeploymentWorkflowRun", "summary": "Get deployment workflow run", "tags": [ "Deployment workflows" ], "description": "Retrieve a single deployment workflow run by ID, including all associated jobs.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project unique identifier" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "runId", "required": true, "description": "Deployment workflow run unique identifier" } ], "deprecated": true, "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Deployment workflow run with jobs", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Workflow run unique identifier" }, "name": { "type": "string", "nullable": true, "description": "Workflow run name" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "cancelled", "waiting", "failure" ], "description": "Current status of the workflow run" }, "runVersion": { "type": "string", "nullable": true, "enum": [ "v2", null ], "description": "Workflow run version" }, "releaseId": { "type": "string", "format": "uuid", "description": "Associated release ID" }, "release": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Release unique identifier" }, "name": { "type": "string", "nullable": true, "description": "Release name" }, "version": { "type": "string", "nullable": true, "description": "Release version" } }, "required": [ "id", "name", "version" ], "description": "Associated release" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID" }, "createdById": { "type": "string", "format": "uuid", "description": "ID of user who created the run" }, "createdBy": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id", "email", "firstName", "lastName" ], "description": "User who created the run" }, "createdAt": { "type": "string", "description": "Timestamp when the run was created" }, "completedAt": { "type": "string", "nullable": true, "description": "Timestamp when the run was completed" }, "cancelledById": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of user who cancelled the run" }, "cancelledBy": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id", "email", "firstName", "lastName" ], "description": "User who cancelled the run" }, "cancelledComment": { "type": "string", "nullable": true, "description": "Cancellation reason" }, "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Job unique identifier" }, "status": { "type": "string", "enum": [ "not_started", "in_progress", "waiting", "failure", "rejected", "completed" ], "description": "Current status of the job" }, "order": { "type": "number", "description": "Order of the job in the workflow" }, "environmentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Associated environment ID" }, "environment": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Environment unique identifier" }, "name": { "type": "string", "description": "Environment name" }, "key": { "type": "string", "nullable": true, "description": "Environment key" } }, "required": [ "id", "name", "key" ], "description": "Associated environment" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID" }, "deploymentWorkflowRunId": { "type": "string", "format": "uuid", "description": "Parent workflow run ID" }, "reviewedAt": { "type": "string", "nullable": true, "description": "Timestamp when the job was reviewed" }, "reviewedBy": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id", "email", "firstName", "lastName" ], "description": "User who reviewed the job" }, "reviewedComment": { "type": "string", "nullable": true, "description": "Review comment" }, "reviewedConclusion": { "type": "string", "nullable": true, "enum": [ "approved", "rejected", null ], "description": "Review conclusion (approved or rejected)" }, "previousRelease": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Release unique identifier" }, "name": { "type": "string", "nullable": true, "description": "Release name" }, "version": { "type": "string", "nullable": true, "description": "Release version" } }, "required": [ "id", "name", "version" ], "description": "Previous release before deployment" }, "previousReleaseId": { "type": "string", "nullable": true, "format": "uuid", "description": "Previous release ID" }, "event": { "type": "string", "nullable": true, "description": "Event type" }, "data": { "nullable": true, "description": "Additional job data" }, "createdAt": { "type": "string", "description": "Timestamp when the job was created" } }, "required": [ "id", "status", "order", "environmentId", "projectId", "deploymentWorkflowRunId", "createdAt" ] }, "description": "List of jobs in the workflow run" } }, "required": [ "id", "name", "status", "releaseId", "projectId", "createdById", "createdAt", "jobs" ], "description": "Deployment workflow run with jobs" } } } } } } }, "/api/projects/{projectId}/runs/{runId}/cancel": { "post": { "operationId": "cancelDeploymentWorkflowRun", "summary": "Cancel deployment workflow run", "tags": [ "Deployment workflows" ], "description": "Cancel an in-progress or waiting deployment workflow run.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "type": "string", "minLength": 1, "description": "Reason for cancelling the workflow run" } }, "required": [ "comment" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "Project unique identifier" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "runId", "required": true, "description": "Deployment workflow run unique identifier" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Cancelled deployment workflow run", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Workflow run unique identifier" }, "name": { "type": "string", "nullable": true, "description": "Workflow run name" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "cancelled", "waiting", "failure" ], "description": "Current status of the workflow run" }, "runVersion": { "type": "string", "nullable": true, "enum": [ "v2", null ], "description": "Workflow run version" }, "releaseId": { "type": "string", "format": "uuid", "description": "Associated release ID" }, "release": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Release unique identifier" }, "name": { "type": "string", "nullable": true, "description": "Release name" }, "version": { "type": "string", "nullable": true, "description": "Release version" } }, "required": [ "id", "name", "version" ], "description": "Associated release" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID" }, "createdById": { "type": "string", "format": "uuid", "description": "ID of user who created the run" }, "createdBy": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id", "email", "firstName", "lastName" ], "description": "User who created the run" }, "createdAt": { "type": "string", "description": "Timestamp when the run was created" }, "completedAt": { "type": "string", "nullable": true, "description": "Timestamp when the run was completed" }, "cancelledById": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of user who cancelled the run" }, "cancelledBy": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id", "email", "firstName", "lastName" ], "description": "User who cancelled the run" }, "cancelledComment": { "type": "string", "nullable": true, "description": "Cancellation reason" }, "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Job unique identifier" }, "status": { "type": "string", "enum": [ "not_started", "in_progress", "waiting", "failure", "rejected", "completed" ], "description": "Current status of the job" }, "order": { "type": "number", "description": "Order of the job in the workflow" }, "environmentId": { "type": "string", "nullable": true, "format": "uuid", "description": "Associated environment ID" }, "environment": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Environment unique identifier" }, "name": { "type": "string", "description": "Environment name" }, "key": { "type": "string", "nullable": true, "description": "Environment key" } }, "required": [ "id", "name", "key" ], "description": "Associated environment" }, "projectId": { "type": "string", "format": "uuid", "description": "Project ID" }, "deploymentWorkflowRunId": { "type": "string", "format": "uuid", "description": "Parent workflow run ID" }, "reviewedAt": { "type": "string", "nullable": true, "description": "Timestamp when the job was reviewed" }, "reviewedBy": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } }, "required": [ "id", "email", "firstName", "lastName" ], "description": "User who reviewed the job" }, "reviewedComment": { "type": "string", "nullable": true, "description": "Review comment" }, "reviewedConclusion": { "type": "string", "nullable": true, "enum": [ "approved", "rejected", null ], "description": "Review conclusion (approved or rejected)" }, "previousRelease": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "Release unique identifier" }, "name": { "type": "string", "nullable": true, "description": "Release name" }, "version": { "type": "string", "nullable": true, "description": "Release version" } }, "required": [ "id", "name", "version" ], "description": "Previous release before deployment" }, "previousReleaseId": { "type": "string", "nullable": true, "format": "uuid", "description": "Previous release ID" }, "event": { "type": "string", "nullable": true, "description": "Event type" }, "data": { "nullable": true, "description": "Additional job data" }, "createdAt": { "type": "string", "description": "Timestamp when the job was created" } }, "required": [ "id", "status", "order", "environmentId", "projectId", "deploymentWorkflowRunId", "createdAt" ] }, "description": "List of jobs in the workflow run" } }, "required": [ "id", "name", "status", "releaseId", "projectId", "createdById", "createdAt" ], "description": "Cancelled deployment workflow run" } } } } } } }, "/api/projects/{projectId}/test-events": { "get": { "operationId": "listTestEvents", "summary": "List test events", "tags": [ "Test events" ], "description": "Retrieve all test events for a project, optionally filtered by document ID.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "documentId", "description": "Filter test events by document ID" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "ID of the project to list test events for" } ], "responses": { "200": { "description": "List of test events matching the criteria", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the test event" }, "name": { "type": "string", "description": "Name of the test event" }, "context": { "type": "string", "description": "JSON context data for the test event" }, "category": { "type": "string", "enum": [ "private", "shared", "global" ], "description": "Category of the test event (private, shared, or global)" }, "projectId": { "type": "string", "format": "uuid", "description": "ID of the project this test event belongs to" }, "userId": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of the user who owns this test event (for private events)" }, "documentId": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of the document this test event is associated with" } }, "required": [ "id", "name", "context", "category", "projectId" ] }, "description": "List of test events matching the criteria" } } } } } }, "post": { "operationId": "createTestEvent", "summary": "Create test event", "tags": [ "Test events" ], "description": "Create a new test event within a project for testing decision logic with sample data.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "testEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "context": { "type": "string" }, "category": { "type": "string", "enum": [ "private", "shared", "global" ] }, "userId": { "type": "string", "nullable": true, "format": "uuid" }, "documentId": { "type": "string", "nullable": true, "format": "uuid" } }, "required": [ "id", "name", "context", "category" ], "description": "Test event data to create" } }, "required": [ "testEvent" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "ID of the project to create the test event in" } ], "responses": { "200": { "description": "The created test event", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the test event" }, "name": { "type": "string", "description": "Name of the test event" }, "context": { "type": "string", "description": "JSON context data for the test event" }, "category": { "type": "string", "enum": [ "private", "shared", "global" ], "description": "Category of the test event (private, shared, or global)" }, "projectId": { "type": "string", "format": "uuid", "description": "ID of the project this test event belongs to" }, "userId": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of the user who owns this test event (for private events)" }, "documentId": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of the document this test event is associated with" } }, "required": [ "id", "name", "context", "category", "projectId" ], "description": "The created test event" } } } } } }, "patch": { "operationId": "upsertTestEvent", "summary": "Upsert test event", "tags": [ "Test events" ], "description": "Create a new test event or update an existing one if a matching ID is provided.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "testEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "context": { "type": "string" }, "category": { "type": "string", "enum": [ "private", "shared", "global" ] }, "userId": { "type": "string", "nullable": true, "format": "uuid" }, "documentId": { "type": "string", "nullable": true, "format": "uuid" } }, "required": [ "id", "name", "context", "category" ], "description": "Test event data to create or update" } }, "required": [ "testEvent" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "ID of the project containing the test event" } ], "responses": { "200": { "description": "The created or updated test event", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the test event" }, "name": { "type": "string", "description": "Name of the test event" }, "context": { "type": "string", "description": "JSON context data for the test event" }, "category": { "type": "string", "enum": [ "private", "shared", "global" ], "description": "Category of the test event (private, shared, or global)" }, "projectId": { "type": "string", "format": "uuid", "description": "ID of the project this test event belongs to" }, "userId": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of the user who owns this test event (for private events)" }, "documentId": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of the document this test event is associated with" } }, "required": [ "id", "name", "context", "category", "projectId" ], "description": "The created or updated test event" } } } } } } }, "/api/projects/{projectId}/test-events/{testEventId}": { "put": { "operationId": "updateTestEvent", "summary": "Update test event", "tags": [ "Test events" ], "description": "Update an existing test event with partial data.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "testEvent": { "type": "object", "properties": { "name": { "type": "string" }, "context": { "type": "string" }, "category": { "type": "string", "enum": [ "private", "shared", "global" ] }, "userId": { "type": "string", "nullable": true, "format": "uuid" }, "documentId": { "type": "string", "nullable": true, "format": "uuid" } }, "description": "Partial test event data to update" } }, "required": [ "testEvent" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "testEventId", "required": true, "description": "ID of the test event to update" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "ID of the project containing the test event" } ], "responses": { "200": { "description": "The updated test event", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the test event" }, "name": { "type": "string", "description": "Name of the test event" }, "context": { "type": "string", "description": "JSON context data for the test event" }, "category": { "type": "string", "enum": [ "private", "shared", "global" ], "description": "Category of the test event (private, shared, or global)" }, "projectId": { "type": "string", "format": "uuid", "description": "ID of the project this test event belongs to" }, "userId": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of the user who owns this test event (for private events)" }, "documentId": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of the document this test event is associated with" } }, "required": [ "id", "name", "context", "category", "projectId" ], "description": "The updated test event" } } } } } }, "delete": { "operationId": "deleteTestEvent", "summary": "Remove test event", "tags": [ "Test events" ], "description": "Delete an existing test event from a project.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "testEventId", "required": true, "description": "ID of the test event to delete" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "projectId", "required": true, "description": "ID of the project containing the test event" } ], "responses": { "200": { "description": "The deleted test event", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the test event" }, "name": { "type": "string", "description": "Name of the test event" }, "context": { "type": "string", "description": "JSON context data for the test event" }, "category": { "type": "string", "enum": [ "private", "shared", "global" ], "description": "Category of the test event (private, shared, or global)" }, "projectId": { "type": "string", "format": "uuid", "description": "ID of the project this test event belongs to" }, "userId": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of the user who owns this test event (for private events)" }, "documentId": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of the document this test event is associated with" } }, "required": [ "id", "name", "context", "category", "projectId" ], "description": "The deleted test event" } } } } } } }, "/api/templates": { "get": { "operationId": "listTemplates", "summary": "List templates", "tags": [ "Templates" ], "description": "Retrieves a list of all available templates with their summary information.", "responses": { "200": { "description": "List of available templates", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Unique identifier for the template" }, "title": { "type": "string", "description": "Display title of the template" }, "industry": { "type": "string", "description": "Industry category the template belongs to" }, "description": { "type": "string", "description": "Brief description of what the template does" } }, "required": [ "key", "title", "industry", "description" ] }, "description": "List of available templates" } } } } } } }, "/api/onboarding/finalize": { "post": { "operationId": "finalizeOnboarding", "summary": "Finalize onboarding process with template", "tags": [ "Templates" ], "description": "Completes the onboarding process by creating a new project with the selected template, including a default document and test event.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "templateKey": { "type": "string", "description": "Key of the template to use for the new project" } }, "required": [ "templateKey" ] } } }, "required": true }, "responses": { "200": { "description": "Created project and document details", "content": { "application/json": { "schema": { "type": "object", "properties": { "project": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the project" }, "name": { "type": "string", "description": "Name of the project" }, "key": { "type": "string", "description": "URL-friendly key of the project" }, "organisationId": { "type": "string", "format": "uuid", "description": "Organisation the project belongs to" }, "createdAt": { "type": "string", "description": "Timestamp when the project was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the project was last updated" } }, "required": [ "id", "name", "key", "organisationId", "createdAt", "updatedAt" ], "description": "The created project" }, "document": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique identifier of the document" }, "key": { "type": "string", "description": "URL-friendly key of the document" }, "name": { "type": "string", "description": "Name of the document" }, "path": { "type": "string", "description": "Path of the document in the project" }, "contentType": { "type": "string", "description": "Content type of the document" }, "type": { "type": "string", "description": "Type of the document (file or folder)" } }, "required": [ "id", "key", "name", "path", "contentType", "type" ], "description": "The created document from the template" } }, "required": [ "project", "document" ], "description": "Created project and document details" } } } } } } }, "/api/onboarding/skip": { "post": { "operationId": "skipOnboarding", "summary": "Skip onboarding process", "tags": [ "Templates" ], "description": "Marks the onboarding process as complete without creating a project from a template.", "responses": { "202": { "description": "Onboarding skipped successfully" } } } }, "/api/templates/{key}": { "get": { "operationId": "getTemplate", "summary": "Get a template", "tags": [ "Templates" ], "description": "Retrieves a specific template by its unique key, including the full decision graph and sample request JSON.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "key", "required": true, "description": "Unique key of the template to retrieve" } ], "responses": { "200": { "description": "Template details including decision graph", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "description": "Unique identifier for the template" }, "title": { "type": "string", "description": "Display title of the template" }, "industry": { "type": "string", "description": "Industry category the template belongs to" }, "description": { "type": "string", "description": "Brief description of what the template does" }, "requestJson": { "type": "string", "description": "Sample request JSON for testing the template" }, "decisionGraphJson": { "type": "string", "description": "JSON representation of the decision graph" } }, "required": [ "key", "title", "industry", "description", "requestJson", "decisionGraphJson" ], "description": "Template details including decision graph" } } } } } } }, "/api/roles": { "get": { "operationId": "listRoles", "summary": "List roles", "tags": [ "Roles" ], "description": "Retrieves a paginated list of roles in the organisation with optional search filtering.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "search", "description": "Search term to filter roles by name" }, { "schema": { "type": "number", "default": 1 }, "in": "query", "name": "page", "description": "Current page" }, { "schema": { "type": "number", "default": 10 }, "in": "query", "name": "perPage", "description": "Number of items per page" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Paginated list of roles", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the role" }, "name": { "type": "string", "description": "Name of the role" }, "description": { "type": "string", "nullable": true, "description": "Description of the role" }, "idpGroups": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Identity provider groups mapped to this role" }, "allProjects": { "type": "boolean", "description": "Whether this role applies to all projects" }, "projectPermissions": { "type": "array", "nullable": true, "items": { "type": "string", "enum": [ "owner", "documents", "releases", "releases:manage", "releases:deploy", "releases:delete", "integrations:manage", "documents:full", "documents:view-content", "documents:edit-content", "documents:edit-view", "branches", "branches:create", "branches:merge", "branches:delete", "project:manage", "environments", "environments:manage", "environments:delete" ] }, "description": "List of project-level permissions granted by this role" }, "projectFilePermissions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "description": "Unique identifier of the file permission" }, "effect": { "type": "string", "enum": [ "allow", "deny" ], "description": "Permission effect (allow or deny)" }, "actions": { "type": "array", "nullable": true, "items": { "type": "string", "enum": [ "visible", "modify", "write", "delete" ] }, "description": "List of actions this permission applies to" }, "patterns": { "type": "string", "nullable": true, "description": "File path patterns this permission applies to" } }, "required": [ "effect" ] }, "description": "File-level permissions granted by this role" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the group" }, "name": { "type": "string", "description": "Name of the group" }, "description": { "type": "string", "nullable": true, "description": "Description of the group" }, "projectId": { "type": "string", "format": "uuid", "description": "ID of the project this group belongs to" }, "project": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the project" } }, "description": "Project this group belongs to" }, "roleId": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of the role this group is associated with" } }, "required": [ "id", "name", "projectId" ] }, "description": "Groups associated with this role" }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the user" }, "email": { "type": "string", "format": "email", "description": "Email address of the user" }, "firstName": { "type": "string", "nullable": true, "description": "First name of the user" }, "lastName": { "type": "string", "nullable": true, "description": "Last name of the user" } }, "required": [ "id", "email" ] }, "description": "Users assigned to this role" }, "organisationId": { "type": "string", "format": "uuid", "description": "ID of the organisation this role belongs to" }, "organisation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the organisation" }, "name": { "type": "string", "description": "Name of the organisation" } }, "required": [ "id", "name" ], "description": "Organisation this role belongs to" }, "createdAt": { "type": "string", "description": "Timestamp when the role was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the role was last updated" } }, "required": [ "id", "name", "allProjects", "organisationId", "createdAt", "updatedAt" ] }, "description": "List of roles" }, "paginate": { "type": "object", "properties": { "current": { "type": "number", "description": "Current page number" }, "from": { "type": "number", "description": "Starting record number" }, "to": { "type": "number", "description": "Ending record number" }, "total": { "type": "number", "description": "Total number of records" }, "pageSize": { "type": "number", "description": "Number of records per page" } }, "required": [ "current", "from", "to", "total", "pageSize" ], "description": "Pagination metadata" } }, "required": [ "results", "paginate" ], "description": "Paginated list of roles" } } } } } }, "post": { "operationId": "createRole", "summary": "Create role", "tags": [ "Roles" ], "description": "Creates a new role with the specified permissions and project assignments.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the role" }, "description": { "type": "string", "description": "Description of the role" }, "idpGroups": { "type": "array", "nullable": true, "items": { "type": "string", "description": "Identity provider group name" }, "description": "Identity provider groups to map to this role" }, "projectPermissions": { "type": "array", "items": { "type": "string", "enum": [ "owner", "documents", "releases", "releases:manage", "releases:deploy", "releases:delete", "integrations:manage", "documents:full", "documents:view-content", "documents:edit-content", "documents:edit-view", "branches", "branches:create", "branches:merge", "branches:delete", "project:manage", "environments", "environments:manage", "environments:delete" ], "description": "Permission type" }, "description": "List of project-level permissions to grant" }, "projectFilePermissions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "effect": { "type": "string", "enum": [ "allow", "deny" ] }, "actions": { "type": "array", "nullable": true, "items": { "type": "string", "enum": [ "visible", "modify", "write", "delete" ] }, "default": [] }, "patterns": { "type": "string", "nullable": true } }, "required": [ "effect" ] }, "default": [], "description": "File-level permissions to grant" }, "allProjects": { "type": "boolean", "description": "Whether this role should apply to all projects" }, "users": { "type": "array", "items": { "type": "string", "format": "uuid", "description": "User ID" }, "description": "List of user IDs to assign to this role" }, "projects": { "type": "array", "items": { "type": "string", "format": "uuid", "description": "Project ID" }, "default": [], "description": "List of project IDs this role applies to (ignored if allProjects is true)" } }, "required": [ "name", "allProjects" ] } } }, "required": true }, "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "The created role", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the role" }, "name": { "type": "string", "description": "Name of the role" }, "description": { "type": "string", "nullable": true, "description": "Description of the role" }, "idpGroups": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Identity provider groups mapped to this role" }, "allProjects": { "type": "boolean", "description": "Whether this role applies to all projects" }, "projectPermissions": { "type": "array", "nullable": true, "items": { "type": "string", "enum": [ "owner", "documents", "releases", "releases:manage", "releases:deploy", "releases:delete", "integrations:manage", "documents:full", "documents:view-content", "documents:edit-content", "documents:edit-view", "branches", "branches:create", "branches:merge", "branches:delete", "project:manage", "environments", "environments:manage", "environments:delete" ] }, "description": "List of project-level permissions granted by this role" }, "projectFilePermissions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "description": "Unique identifier of the file permission" }, "effect": { "type": "string", "enum": [ "allow", "deny" ], "description": "Permission effect (allow or deny)" }, "actions": { "type": "array", "nullable": true, "items": { "type": "string", "enum": [ "visible", "modify", "write", "delete" ] }, "description": "List of actions this permission applies to" }, "patterns": { "type": "string", "nullable": true, "description": "File path patterns this permission applies to" } }, "required": [ "effect" ] }, "description": "File-level permissions granted by this role" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the group" }, "name": { "type": "string", "description": "Name of the group" }, "description": { "type": "string", "nullable": true, "description": "Description of the group" }, "projectId": { "type": "string", "format": "uuid", "description": "ID of the project this group belongs to" }, "project": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the project" } }, "description": "Project this group belongs to" }, "roleId": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of the role this group is associated with" } }, "required": [ "id", "name", "projectId" ] }, "description": "Groups associated with this role" }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the user" }, "email": { "type": "string", "format": "email", "description": "Email address of the user" }, "firstName": { "type": "string", "nullable": true, "description": "First name of the user" }, "lastName": { "type": "string", "nullable": true, "description": "Last name of the user" } }, "required": [ "id", "email" ] }, "description": "Users assigned to this role" }, "organisationId": { "type": "string", "format": "uuid", "description": "ID of the organisation this role belongs to" }, "organisation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the organisation" }, "name": { "type": "string", "description": "Name of the organisation" } }, "required": [ "id", "name" ], "description": "Organisation this role belongs to" }, "createdAt": { "type": "string", "description": "Timestamp when the role was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the role was last updated" } }, "required": [ "id", "name", "allProjects", "organisationId", "createdAt", "updatedAt" ], "description": "The created role" } } } } } } }, "/api/roles/{roleId}": { "put": { "operationId": "updateRole", "summary": "Update role", "tags": [ "Roles" ], "description": "Updates an existing role with new permissions, users, and project assignments.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Updated name of the role" }, "description": { "type": "string", "description": "Updated description of the role" }, "idpGroups": { "type": "array", "nullable": true, "items": { "type": "string", "description": "Identity provider group name" }, "description": "Updated identity provider groups to map to this role" }, "projectPermissions": { "type": "array", "items": { "type": "string", "enum": [ "owner", "documents", "releases", "releases:manage", "releases:deploy", "releases:delete", "integrations:manage", "documents:full", "documents:view-content", "documents:edit-content", "documents:edit-view", "branches", "branches:create", "branches:merge", "branches:delete", "project:manage", "environments", "environments:manage", "environments:delete" ], "description": "Permission type" }, "description": "Updated list of project-level permissions to grant" }, "projectFilePermissions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "effect": { "type": "string", "enum": [ "allow", "deny" ] }, "actions": { "type": "array", "nullable": true, "items": { "type": "string", "enum": [ "visible", "modify", "write", "delete" ] }, "default": [] }, "patterns": { "type": "string", "nullable": true } }, "required": [ "effect" ] }, "default": [], "description": "Updated file-level permissions to grant" }, "users": { "type": "array", "items": { "type": "string", "format": "uuid", "description": "User ID" }, "description": "Updated list of user IDs to assign to this role" }, "allProjects": { "type": "boolean", "description": "Whether this role should apply to all projects" }, "projects": { "type": "array", "items": { "type": "string", "format": "uuid", "description": "Project ID" }, "default": [], "description": "Updated list of project IDs this role applies to (ignored if allProjects is true)" } }, "required": [ "name", "allProjects" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "roleId", "required": true, "description": "Unique identifier of the role to update" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "The updated role", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the role" }, "name": { "type": "string", "description": "Name of the role" }, "description": { "type": "string", "nullable": true, "description": "Description of the role" }, "idpGroups": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Identity provider groups mapped to this role" }, "allProjects": { "type": "boolean", "description": "Whether this role applies to all projects" }, "projectPermissions": { "type": "array", "nullable": true, "items": { "type": "string", "enum": [ "owner", "documents", "releases", "releases:manage", "releases:deploy", "releases:delete", "integrations:manage", "documents:full", "documents:view-content", "documents:edit-content", "documents:edit-view", "branches", "branches:create", "branches:merge", "branches:delete", "project:manage", "environments", "environments:manage", "environments:delete" ] }, "description": "List of project-level permissions granted by this role" }, "projectFilePermissions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "description": "Unique identifier of the file permission" }, "effect": { "type": "string", "enum": [ "allow", "deny" ], "description": "Permission effect (allow or deny)" }, "actions": { "type": "array", "nullable": true, "items": { "type": "string", "enum": [ "visible", "modify", "write", "delete" ] }, "description": "List of actions this permission applies to" }, "patterns": { "type": "string", "nullable": true, "description": "File path patterns this permission applies to" } }, "required": [ "effect" ] }, "description": "File-level permissions granted by this role" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the group" }, "name": { "type": "string", "description": "Name of the group" }, "description": { "type": "string", "nullable": true, "description": "Description of the group" }, "projectId": { "type": "string", "format": "uuid", "description": "ID of the project this group belongs to" }, "project": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the project" } }, "description": "Project this group belongs to" }, "roleId": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of the role this group is associated with" } }, "required": [ "id", "name", "projectId" ] }, "description": "Groups associated with this role" }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the user" }, "email": { "type": "string", "format": "email", "description": "Email address of the user" }, "firstName": { "type": "string", "nullable": true, "description": "First name of the user" }, "lastName": { "type": "string", "nullable": true, "description": "Last name of the user" } }, "required": [ "id", "email" ] }, "description": "Users assigned to this role" }, "organisationId": { "type": "string", "format": "uuid", "description": "ID of the organisation this role belongs to" }, "organisation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the organisation" }, "name": { "type": "string", "description": "Name of the organisation" } }, "required": [ "id", "name" ], "description": "Organisation this role belongs to" }, "createdAt": { "type": "string", "description": "Timestamp when the role was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the role was last updated" } }, "required": [ "id", "name", "allProjects", "organisationId", "createdAt", "updatedAt" ], "description": "The updated role" } } } } } }, "delete": { "operationId": "deleteRole", "summary": "Delete role", "tags": [ "Roles" ], "description": "Deletes a role and removes all associated group assignments.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "roleId", "required": true, "description": "Unique identifier of the role to delete" } ], "security": [ { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Confirmation that the role was deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ], "description": "Operation status" } }, "required": [ "status" ], "description": "Confirmation that the role was deleted" } } } } } } }, "/api/health": { "get": { "operationId": "getHealthStatus", "summary": "Health check", "tags": [ "Infrastructure" ], "description": "Performs a health check on the service, verifying database connectivity.", "responses": { "200": { "description": "Service is healthy", "content": { "application/json": { "schema": { "type": "string", "enum": [ "healthy" ], "description": "Service is healthy" } } } }, "503": { "description": "Service is unhealthy", "content": { "application/json": { "schema": { "type": "string", "enum": [ "database unreachable" ], "description": "Service is unhealthy" } } } } } } }, "/api/rules/{projectId}": { "get": { "summary": "Rules OpenAPI document for the main branch", "tags": [ "Rules" ], "parameters": [ { "schema": { "description": "Return the document with an attachment header so browsers save it as a file", "anyOf": [ { "type": "string", "enum": [ "true", "false", "True", "False", "TRUE", "FALSE" ] }, { "type": "boolean" } ] }, "in": "query", "name": "download", "description": "Return the document with an attachment header so browsers save it as a file" }, { "schema": { "description": "Bypass the blob cache: rebuild the document from source and overwrite the cached copy", "anyOf": [ { "type": "string", "enum": [ "true", "false", "True", "False", "TRUE", "FALSE" ] }, { "type": "boolean" } ] }, "in": "query", "name": "refresh", "description": "Bypass the blob cache: rebuild the document from source and overwrite the cached copy" }, { "schema": { "type": "string", "description": "ProjectId or projectKey" }, "in": "path", "name": "projectId", "required": true, "description": "ProjectId or projectKey" } ], "security": [ { "projectAccessToken": [] }, { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Default Response" } }, "x-hidden": true, "description": "Returns an OpenAPI document describing the evaluable rules on the latest main-branch commit." } }, "/api/rules/{projectId}/branch/{branchId}": { "get": { "summary": "Rules OpenAPI document for a branch", "tags": [ "Rules" ], "parameters": [ { "schema": { "description": "Return the document with an attachment header so browsers save it as a file", "anyOf": [ { "type": "string", "enum": [ "true", "false", "True", "False", "TRUE", "FALSE" ] }, { "type": "boolean" } ] }, "in": "query", "name": "download", "description": "Return the document with an attachment header so browsers save it as a file" }, { "schema": { "description": "Bypass the blob cache: rebuild the document from source and overwrite the cached copy", "anyOf": [ { "type": "string", "enum": [ "true", "false", "True", "False", "TRUE", "FALSE" ] }, { "type": "boolean" } ] }, "in": "query", "name": "refresh", "description": "Bypass the blob cache: rebuild the document from source and overwrite the cached copy" }, { "schema": { "type": "string", "description": "ProjectId or projectKey" }, "in": "path", "name": "projectId", "required": true, "description": "ProjectId or projectKey" }, { "schema": { "type": "string", "description": "BranchId (branch names are not unique)" }, "in": "path", "name": "branchId", "required": true, "description": "BranchId (branch names are not unique)" } ], "security": [ { "projectAccessToken": [] }, { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Default Response" } }, "x-hidden": true, "description": "Returns an OpenAPI document describing the evaluable rules on the latest commit of a branch." } }, "/api/rules/{projectId}/branch/{branchId}/evaluate/{*}": { "post": { "summary": "Evaluate a rule on a branch", "tags": [ "Rules" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "context": { "default": {}, "description": "Evaluation context", "example": { "cart": { "total": 1500 }, "customer": { "country": "US", "tier": "gold" } }, "nullable": true, "type": "object", "properties": {}, "additionalProperties": {} }, "trace": { "default": false, "description": "Include decision trace in response", "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "string", "description": "ProjectId or projectKey" }, "in": "path", "name": "projectId", "required": true, "description": "ProjectId or projectKey" }, { "schema": { "type": "string", "description": "BranchId (branch names are not unique)" }, "in": "path", "name": "branchId", "required": true, "description": "BranchId (branch names are not unique)" }, { "schema": { "type": "string", "description": "Rule file path" }, "in": "path", "name": "*", "required": true } ], "security": [ { "projectAccessToken": [] }, { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Default Response" } }, "x-hidden": true, "description": "Evaluates a rule against the latest commit on a branch." } }, "/api/rules/{projectId}/commit/{commitId}": { "get": { "summary": "Rules OpenAPI document for a commit", "tags": [ "Rules" ], "parameters": [ { "schema": { "description": "Return the document with an attachment header so browsers save it as a file", "anyOf": [ { "type": "string", "enum": [ "true", "false", "True", "False", "TRUE", "FALSE" ] }, { "type": "boolean" } ] }, "in": "query", "name": "download", "description": "Return the document with an attachment header so browsers save it as a file" }, { "schema": { "description": "Bypass the blob cache: rebuild the document from source and overwrite the cached copy", "anyOf": [ { "type": "string", "enum": [ "true", "false", "True", "False", "TRUE", "FALSE" ] }, { "type": "boolean" } ] }, "in": "query", "name": "refresh", "description": "Bypass the blob cache: rebuild the document from source and overwrite the cached copy" }, { "schema": { "type": "string", "description": "ProjectId or projectKey" }, "in": "path", "name": "projectId", "required": true, "description": "ProjectId or projectKey" }, { "schema": { "type": "string", "description": "CommitId" }, "in": "path", "name": "commitId", "required": true, "description": "CommitId" } ], "security": [ { "projectAccessToken": [] }, { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Default Response" } }, "x-hidden": true, "description": "Returns an OpenAPI document describing the evaluable rules at a specific commit." } }, "/api/rules/{projectId}/commit/{commitId}/evaluate/{*}": { "post": { "summary": "Evaluate a rule against a specific commit", "tags": [ "Rules" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "context": { "default": {}, "description": "Evaluation context", "example": { "cart": { "total": 1500 }, "customer": { "country": "US", "tier": "gold" } }, "nullable": true, "type": "object", "properties": {}, "additionalProperties": {} }, "trace": { "default": false, "description": "Include decision trace in response", "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "string", "description": "ProjectId or projectKey" }, "in": "path", "name": "projectId", "required": true, "description": "ProjectId or projectKey" }, { "schema": { "type": "string", "description": "CommitId" }, "in": "path", "name": "commitId", "required": true, "description": "CommitId" }, { "schema": { "type": "string", "description": "Rule file path" }, "in": "path", "name": "*", "required": true } ], "security": [ { "projectAccessToken": [] }, { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Default Response" } }, "x-hidden": true, "description": "Evaluates a rule against the project state at a specific commit." } }, "/api/rules/{projectId}/env/{environmentId}": { "get": { "summary": "Rules OpenAPI document for an environment", "tags": [ "Rules" ], "parameters": [ { "schema": { "description": "Return the document with an attachment header so browsers save it as a file", "anyOf": [ { "type": "string", "enum": [ "true", "false", "True", "False", "TRUE", "FALSE" ] }, { "type": "boolean" } ] }, "in": "query", "name": "download", "description": "Return the document with an attachment header so browsers save it as a file" }, { "schema": { "description": "Bypass the blob cache: rebuild the document from source and overwrite the cached copy", "anyOf": [ { "type": "string", "enum": [ "true", "false", "True", "False", "TRUE", "FALSE" ] }, { "type": "boolean" } ] }, "in": "query", "name": "refresh", "description": "Bypass the blob cache: rebuild the document from source and overwrite the cached copy" }, { "schema": { "type": "string", "description": "ProjectId or projectKey" }, "in": "path", "name": "projectId", "required": true, "description": "ProjectId or projectKey" }, { "schema": { "type": "string", "description": "EnvironmentId or environmentKey" }, "in": "path", "name": "environmentId", "required": true, "description": "EnvironmentId or environmentKey" } ], "security": [ { "projectAccessToken": [] }, { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Default Response" } }, "x-hidden": true, "description": "Returns an OpenAPI document describing the evaluable rules inside the release an environment points to." } }, "/api/rules/{projectId}/env/{environmentId}/evaluate/{*}": { "post": { "summary": "Evaluate a rule in an environment", "tags": [ "Rules" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "context": { "default": {}, "description": "Evaluation context", "example": { "cart": { "total": 1500 }, "customer": { "country": "US", "tier": "gold" } }, "nullable": true, "type": "object", "properties": {}, "additionalProperties": {} }, "trace": { "default": false, "description": "Include decision trace in response", "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "string", "description": "ProjectId or projectKey" }, "in": "path", "name": "projectId", "required": true, "description": "ProjectId or projectKey" }, { "schema": { "type": "string", "description": "EnvironmentId or environmentKey" }, "in": "path", "name": "environmentId", "required": true, "description": "EnvironmentId or environmentKey" }, { "schema": { "type": "string", "description": "Rule file path" }, "in": "path", "name": "*", "required": true } ], "security": [ { "projectAccessToken": [] }, { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Default Response" } }, "x-hidden": true, "description": "Evaluates a rule against the release an environment points to." } }, "/api/rules/{projectId}/evaluate/{*}": { "post": { "summary": "Evaluate a rule on the main branch", "tags": [ "Rules" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "context": { "default": {}, "description": "Evaluation context", "example": { "cart": { "total": 1500 }, "customer": { "country": "US", "tier": "gold" } }, "nullable": true, "type": "object", "properties": {}, "additionalProperties": {} }, "trace": { "default": false, "description": "Include decision trace in response", "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "string", "description": "ProjectId or projectKey" }, "in": "path", "name": "projectId", "required": true, "description": "ProjectId or projectKey" }, { "schema": { "type": "string", "description": "Rule file path" }, "in": "path", "name": "*", "required": true } ], "security": [ { "projectAccessToken": [] }, { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Default Response" } }, "x-hidden": true, "description": "Evaluates a rule against the latest main-branch commit." } }, "/api/rules/{projectId}/release/{releaseId}": { "get": { "summary": "Rules OpenAPI document for a release", "tags": [ "Rules" ], "parameters": [ { "schema": { "description": "Return the document with an attachment header so browsers save it as a file", "anyOf": [ { "type": "string", "enum": [ "true", "false", "True", "False", "TRUE", "FALSE" ] }, { "type": "boolean" } ] }, "in": "query", "name": "download", "description": "Return the document with an attachment header so browsers save it as a file" }, { "schema": { "description": "Bypass the blob cache: rebuild the document from source and overwrite the cached copy", "anyOf": [ { "type": "string", "enum": [ "true", "false", "True", "False", "TRUE", "FALSE" ] }, { "type": "boolean" } ] }, "in": "query", "name": "refresh", "description": "Bypass the blob cache: rebuild the document from source and overwrite the cached copy" }, { "schema": { "type": "string", "description": "ProjectId or projectKey" }, "in": "path", "name": "projectId", "required": true, "description": "ProjectId or projectKey" }, { "schema": { "type": "string", "description": "ReleaseId or numeric release version" }, "in": "path", "name": "releaseId", "required": true, "description": "ReleaseId or numeric release version" } ], "security": [ { "projectAccessToken": [] }, { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Default Response" } }, "x-hidden": true, "description": "Returns an OpenAPI document describing the evaluable rules inside a release." } }, "/api/rules/{projectId}/release/{releaseId}/evaluate/{*}": { "post": { "summary": "Evaluate a rule against a pinned release", "tags": [ "Rules" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "context": { "default": {}, "description": "Evaluation context", "example": { "cart": { "total": 1500 }, "customer": { "country": "US", "tier": "gold" } }, "nullable": true, "type": "object", "properties": {}, "additionalProperties": {} }, "trace": { "default": false, "description": "Include decision trace in response", "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "string", "description": "ProjectId or projectKey" }, "in": "path", "name": "projectId", "required": true, "description": "ProjectId or projectKey" }, { "schema": { "type": "string", "description": "ReleaseId or numeric release version" }, "in": "path", "name": "releaseId", "required": true, "description": "ReleaseId or numeric release version" }, { "schema": { "type": "string", "description": "Rule file path" }, "in": "path", "name": "*", "required": true } ], "security": [ { "projectAccessToken": [] }, { "personalAccessToken": [] }, { "internalAuth": [] } ], "responses": { "200": { "description": "Default Response" } }, "x-hidden": true, "description": "Evaluates a rule against the decision content of a pinned release." } } }, "tags": [ { "name": "Rules", "description": "Evaluate any graph or policy as an HTTP endpoint, against a branch, commit, release, or environment. A GET on each source returns its OpenAPI document." }, { "name": "AI", "description": "AI-powered assistant for interactive conversations and decision logic generation" }, { "name": "Audit log", "description": "Track and export organisation activity logs for compliance and monitoring" }, { "name": "Branches", "description": "Manage feature branches for collaborative decision development with commits and merging" }, { "name": "Change requests", "description": "Review and approve changes before merging or deploying to environments" }, { "name": "Cloud", "description": "Cloud-specific endpoints for organisation and client management" }, { "name": "Decision", "description": "Evaluate and simulate decision graphs with trace and performance data" }, { "name": "Deployment workflows", "description": "Manage deployment workflow runs and job approvals" }, { "name": "Deployments", "description": "Configure cloud storage providers for release deployments" }, { "name": "Document", "description": "Manage decision documents, versions, and file operations within projects" }, { "name": "Environment", "description": "Configure deployment environments with approval workflows and access tokens" }, { "name": "Group", "description": "Manage permission groups for project-level access control" }, { "name": "Infrastructure", "description": "Health check and infrastructure status endpoints" }, { "name": "Integration", "description": "Configure external integrations for HTTP requests and data sources" }, { "name": "Invitation", "description": "Manage organisation invitations for new members" }, { "name": "Member", "description": "Manage project membership and group assignments" }, { "name": "Organisation", "description": "Manage organisation settings, preferences, and licensing" }, { "name": "Personal access token", "description": "Create and manage personal access tokens for API authentication" }, { "name": "Profile", "description": "Manage current user profile settings" }, { "name": "Project", "description": "Create and manage projects with approval workflows" }, { "name": "Release", "description": "Package, version, and deploy decision documents. Learn more about [Releases](https://gorules.io/developers/brms/multi-environment)" }, { "name": "Roles", "description": "Define custom roles with permissions for organisation-wide access control" }, { "name": "Security", "description": "Manage project access tokens for API authentication" }, { "name": "Templates", "description": "Browse and apply project templates for quick onboarding" }, { "name": "Test events", "description": "Manage test events for decision evaluation and testing" }, { "name": "User", "description": "Manage organisation users, invitations, and service accounts" } ] }