{ "openapi": "3.1.0", "info": { "title": "Procera API", "version": "0.4.0-dev", "description": "Generated from the server's router. Request and response bodies are described in words; typed schemas are planned." }, "servers": [ { "url": "https://your-procera.example.com" } ], "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "A session access token or a personal API token (prc_live_…)." } } }, "security": [ { "bearer": [] } ], "paths": { "/api/v1/auth/login": { "post": { "tags": [ "Sign-in and account" ], "operationId": "auth_login", "summary": "Signs in with `email` and `password`", "description": "Signs in with `email` and `password`. Returns an access token and sets the refresh cookie, or answers `mfa_required` (with `mfa_token`) or `password_change_required`. 429 when rate-limited.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "login.password_change_required", "login.password_ok_mfa_required", "login.succeeded", "password.reset_requested" ] } }, "/api/v1/auth/mfa": { "post": { "tags": [ "Sign-in and account" ], "operationId": "auth_mfa", "summary": "Completes sign-in with the `mfa_token` and exactly one of `code` (TOTP or recovery code) or `credential` (passkey assertion); 422 otherwise", "description": "Completes sign-in with the `mfa_token` and exactly one of `code` (TOTP or recovery code) or `credential` (passkey assertion); 422 otherwise. Returns an access token and the refresh cookie.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "login.succeeded" ] } }, "/api/v1/auth/mfa/webauthn/options": { "post": { "tags": [ "Sign-in and account" ], "operationId": "auth_mfa_passkey_options", "summary": "Passkey challenge for the second sign-in step (after the password).", "description": "Passkey challenge for the second sign-in step (after the password).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/auth/refresh": { "post": { "tags": [ "Sign-in and account" ], "operationId": "auth_refresh", "summary": "A new access token from the refresh cookie (rotating it)", "description": "A new access token from the refresh cookie (rotating it). Requires the `X-Requested-With: procera` header (403 without it); 401 without a valid cookie.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/auth/logout": { "post": { "tags": [ "Sign-in and account" ], "operationId": "auth_logout", "summary": "Ends the session behind the refresh cookie and clears it; 204", "description": "Ends the session behind the refresh cookie and clears it; 204. Requires the `X-Requested-With: procera` header.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "logout" ] } }, "/api/v1/me": { "get": { "tags": [ "Sign-in and account" ], "operationId": "auth_me", "summary": "The signed-in user's account and the current token's facts (methods used, auth time, plane, workspace, expiry).", "description": "The signed-in user's account and the current token's facts (methods used, auth time, plane, workspace, expiry).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/me/sign-out-everywhere": { "post": { "tags": [ "Sign-in and account" ], "operationId": "auth_sign_out_everywhere", "summary": "Revokes every session of the caller's account and invalidates its outstanding access tokens, then clears the refresh cookie; 204.", "description": "Revokes every session of the caller's account and invalidates its outstanding access tokens, then clears the refresh cookie; 204.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "sessions.revoked_all" ] } }, "/api/v1/me/mfa/totp": { "post": { "tags": [ "Sign-in and account" ], "operationId": "auth_totp_begin", "summary": "Starts authenticator-app enrolment and returns the secret to scan; confirm it with `POST /me/mfa/totp/confirm`.", "description": "Starts authenticator-app enrolment and returns the secret to scan; confirm it with `POST /me/mfa/totp/confirm`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "mfa.totp_enrollment_started" ] } }, "/api/v1/me/mfa/totp/confirm": { "post": { "tags": [ "Sign-in and account" ], "operationId": "auth_totp_confirm", "summary": "Confirms TOTP enrolment with a `code`; returns the recovery codes (shown once) and an upgraded access token for this session.", "description": "Confirms TOTP enrolment with a `code`; returns the recovery codes (shown once) and an upgraded access token for this session.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "mfa.totp_enabled" ] } }, "/api/v1/me/mfa/webauthn": { "get": { "tags": [ "Sign-in and account" ], "operationId": "auth_list_passkeys", "summary": "The caller's registered passkeys.", "description": "The caller's registered passkeys.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } }, "post": { "tags": [ "Sign-in and account" ], "operationId": "auth_register_passkey", "summary": "Registers a passkey (`name`, `credential`) answering the challenge from `/me/mfa/webauthn/options`; 201", "description": "Registers a passkey (`name`, `credential`) answering the challenge from `/me/mfa/webauthn/options`; 201. Recovery codes are returned once when it is the first second factor.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "mfa.webauthn_added" ] } }, "/api/v1/me/mfa/webauthn/options": { "post": { "tags": [ "Sign-in and account" ], "operationId": "auth_passkey_registration_options", "summary": "A WebAuthn registration challenge for adding a passkey.", "description": "A WebAuthn registration challenge for adding a passkey.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/me/mfa/webauthn/{id}": { "delete": { "tags": [ "Sign-in and account" ], "operationId": "auth_remove_passkey", "summary": "Removes one of the caller's passkeys; 204", "description": "Removes one of the caller's passkeys; 204. Needs a sign-in within the last 5 minutes (401 `step_up_required`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "mfa.webauthn_removed" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/email-actions/{token}": { "get": { "tags": [ "Email approvals" ], "operationId": "email_actions_view", "summary": "What the confirm page shows (no session; the link is the key): `{state: open|used|expired|closed, deciding_as, workspace, step, outcomes, request {display_id, title, type_name, initiator, submitted_at", "description": "What the confirm page shows (no session; the link is the key): `{state: open|used|expired|closed, deciding_as, workspace, step, outcomes, request {display_id, title, type_name, initiator, submitted_at, due_at}, answers [{label, type, value}], expires_at}`. Answers marked confidential or restricted are left out. 404 for an unknown link.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "post": { "tags": [ "Email approvals" ], "operationId": "email_actions_decide", "summary": "Decides once through the link: `outcome` `approved`, or `rejected` with a `comment`", "description": "Decides once through the link: `outcome` `approved`, or `rejected` with a `comment`. Candidacy, separation of duties and \"one decision wins\" apply as in My work. 409 when the link was used or expired or the step is already decided. Returns `{outcome, display_id, status}`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "instance.advanced", "instance.completed", "webhook.created", "work.decided_by_email", "work_item.decided" ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/webhook-events": { "get": { "tags": [ "Outgoing webhooks" ], "operationId": "webhooks_catalogue", "summary": "The event types a webhook can receive, with what each means.", "description": "The event types a webhook can receive, with what each means.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/webhooks": { "get": { "tags": [ "Outgoing webhooks" ], "operationId": "webhooks_list", "summary": "The workspace's endpoints with their last delivery (`connector:view`).", "description": "The workspace's endpoints with their last delivery (`connector:view`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } }, "post": { "tags": [ "Outgoing webhooks" ], "operationId": "webhooks_create", "summary": "A new endpoint (`url` https, `events` types or `[\"*\"]`, `description`; `connector:configure`; at most 20)", "description": "A new endpoint (`url` https, `events` types or `[\"*\"]`, `description`; `connector:configure`; at most 20). 201 with the endpoint and its `secret` (shown only here). 422 for a URL inside a private network or a port other than 443/80/8443/8080.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/webhooks/{id}": { "get": { "tags": [ "Outgoing webhooks" ], "operationId": "webhooks_one", "summary": "One endpoint (`connector:view`), with an `ETag` of its revision.", "description": "One endpoint (`connector:view`), with an `ETag` of its revision.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "tags": [ "Outgoing webhooks" ], "operationId": "webhooks_update", "summary": "Changes the URL, events, description or on/off (`connector:configure`; honours `If-Match`)", "description": "Changes the URL, events, description or on/off (`connector:configure`; honours `If-Match`). Turning an endpoint back on clears why it was turned off.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "webhook.updated" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "delete": { "tags": [ "Outgoing webhooks" ], "operationId": "webhooks_remove", "summary": "Removes an endpoint and its delivery log (`connector:configure`)", "description": "Removes an endpoint and its delivery log (`connector:configure`). 204.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "webhook.deleted" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/webhooks/{id}/rotate-secret": { "post": { "tags": [ "Outgoing webhooks" ], "operationId": "webhooks_rotate", "summary": "A new signing secret (`connector:manage_secrets`); the previous one also signs for 24 hours", "description": "A new signing secret (`connector:manage_secrets`); the previous one also signs for 24 hours. Returns `{secret, previous_valid_until}`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "webhook.secret_rotated" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/webhooks/{id}/test": { "post": { "tags": [ "Outgoing webhooks" ], "operationId": "webhooks_test", "summary": "Queues a `webhook.test` event for the endpoint (`connector:configure`); the next delivery pass sends it", "description": "Queues a `webhook.test` event for the endpoint (`connector:configure`); the next delivery pass sends it. 202 with the delivery.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "webhook.tested" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/webhooks/{id}/deliveries": { "get": { "tags": [ "Outgoing webhooks" ], "operationId": "webhooks_deliveries", "summary": "The endpoint's deliveries, newest first (at most 200), each with its state, attempts, last status, error and duration, a response excerpt and the event body (`connector:view`).", "description": "The endpoint's deliveries, newest first (at most 200), each with its state, attempts, last status, error and duration, a response excerpt and the event body (`connector:view`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/webhooks/deliveries/{id}/replay": { "post": { "tags": [ "Outgoing webhooks" ], "operationId": "webhooks_replay", "summary": "Sends a delivery again from the start of its retry schedule, with the same event id (`connector:configure`).", "description": "Sends a delivery again from the start of its retry schedule, with the same event id (`connector:configure`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "webhook.replayed" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/me/api-tokens": { "get": { "tags": [ "API tokens" ], "operationId": "tokens_mine", "summary": "My tokens in this workspace, newest first.", "description": "My tokens in this workspace, newest first.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } }, "post": { "tags": [ "API tokens" ], "operationId": "tokens_create", "summary": "A new token with some of my own permissions; the secret is shown once.", "description": "A new token with some of my own permissions; the secret is shown once.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "api_token.created" ] } }, "/api/v1/me/api-tokens/{id}": { "delete": { "tags": [ "API tokens" ], "operationId": "tokens_revoke_mine", "summary": "Revoke one of my tokens (repeating it is a no-op).", "description": "Revoke one of my tokens (repeating it is a no-op).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "api_token.revoked" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/api-tokens": { "get": { "tags": [ "API tokens" ], "operationId": "tokens_all", "summary": "Every token in the workspace (`api_token:manage`).", "description": "Every token in the workspace (`api_token:manage`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/api-tokens/{id}": { "delete": { "tags": [ "API tokens" ], "operationId": "tokens_revoke_any", "summary": "Revoke anyone's token (`api_token:manage`).", "description": "Revoke anyone's token (`api_token:manage`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "api_token.revoked" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/me/workspaces": { "get": { "tags": [ "Workspace and members" ], "operationId": "workspace_my_workspaces", "summary": "The workspaces I belong to, and which one my current token is for (`active`).", "description": "The workspaces I belong to, and which one my current token is for (`active`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/session/workspace": { "post": { "tags": [ "Workspace and members" ], "operationId": "workspace_switch_workspace", "summary": "Issues an access token for the chosen workspace (or none, for the home view).", "description": "Issues an access token for the chosen workspace (or none, for the home view).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "session.workspace_selected" ] } }, "/api/v1/session/step-up": { "post": { "tags": [ "Workspace and members" ], "operationId": "workspace_step_up", "summary": "Re-authenticates within the current sign-in and returns an access token with a fresh `auth_time`.", "description": "Re-authenticates within the current sign-in and returns an access token with a fresh `auth_time`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "session.stepped_up" ] } }, "/api/v1/session/step-up/webauthn/options": { "post": { "tags": [ "Workspace and members" ], "operationId": "workspace_step_up_passkey_options", "summary": "Passkey challenge for step-up.", "description": "Passkey challenge for step-up.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/invitations/preview": { "get": { "tags": [ "Workspace and members" ], "operationId": "workspace_preview", "summary": "Public: what the invitation page shows to the holder of the link.", "description": "Public: what the invitation page shows to the holder of the link.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/invitations/accept": { "post": { "tags": [ "Workspace and members" ], "operationId": "workspace_accept", "summary": "Accepts an invitation (body `{token}`) for the signed-in user and returns the new `workspace_id` and `membership_id`.", "description": "Accepts an invitation (body `{token}`) for the signed-in user and returns the new `workspace_id` and `membership_id`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "member.joined" ] } }, "/api/v1/invitations/register": { "post": { "tags": [ "Workspace and members" ], "operationId": "workspace_register", "summary": "Creates an account from an invitation (`token`, `display_name`, `password`) and joins the workspace; 201", "description": "Creates an account from an invitation (`token`, `display_name`, `password`) and joins the workspace; 201. Sign in afterwards to get a workspace token.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "member.joined", "user.created" ] } }, "/api/v1/permission-catalog": { "get": { "tags": [ "Workspace and members" ], "operationId": "workspace_permission_catalog", "summary": "Every permission and the built-in role templates with their permissions.", "description": "Every permission and the built-in role templates with their permissions.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/me/permissions": { "get": { "tags": [ "Workspace and members" ], "operationId": "workspace_my_permissions", "summary": "My effective permissions in this workspace, and whether I manage a team (`manages`: I have direct reports or hold `work:view_team` on a department).", "description": "My effective permissions in this workspace, and whether I manage a team (`manages`: I have direct reports or hold `work:view_team` on a department).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/members": { "get": { "tags": [ "Workspace and members" ], "operationId": "workspace_list_members", "summary": "Every member of the workspace (`member:view`).", "description": "Every member of the workspace (`member:view`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/members/invitations": { "get": { "tags": [ "Workspace and members" ], "operationId": "workspace_list_invitations", "summary": "The workspace's invitations (`member:invite`)", "description": "The workspace's invitations (`member:invite`). Links are never included.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } }, "post": { "tags": [ "Workspace and members" ], "operationId": "workspace_invite", "summary": "Invites an email address with a set of `roles` (`member:invite`); 201", "description": "Invites an email address with a set of `roles` (`member:invite`); 201. The invitation link is sent by email only and is never returned here.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "member.invited" ] } }, "/api/v1/members/invitations/{id}": { "delete": { "tags": [ "Workspace and members" ], "operationId": "workspace_revoke_invitation", "summary": "Revokes a pending invitation so its link stops working (`member:invite`); 204.", "description": "Revokes a pending invitation so its link stops working (`member:invite`); 204.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "member.invitation_revoked" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/members/invitations/{id}/link": { "post": { "tags": [ "Workspace and members" ], "operationId": "workspace_copy_invitation_link", "summary": "A fresh one-time link for a pending invitation, for the inviter to hand over when email isn't set up", "description": "A fresh one-time link for a pending invitation, for the inviter to hand over when email isn't set up. The earlier link stops working. Only this response carries the token; lists never do.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "member.invitation_link_copied" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/members/{id}/deactivate": { "post": { "tags": [ "Workspace and members" ], "operationId": "workspace_deactivate", "summary": "Deactivates a member, ending their access to the workspace (`member:deactivate`); 204.", "description": "Deactivates a member, ending their access to the workspace (`member:deactivate`); 204.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "member.deactivated" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/members/{id}/reactivate": { "post": { "tags": [ "Workspace and members" ], "operationId": "workspace_reactivate", "summary": "Brings a deactivated member back with the roles they had", "description": "Brings a deactivated member back with the roles they had. Restoring access is treated like granting it: step-up, and no restoring roles the caller could not grant.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "member.reactivated" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/roles": { "get": { "tags": [ "Workspace and members" ], "operationId": "workspace_list_roles", "summary": "The workspace's roles with their permissions (`role:view`).", "description": "The workspace's roles with their permissions (`role:view`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } }, "post": { "tags": [ "Workspace and members" ], "operationId": "workspace_create_role", "summary": "A custom role (`key`, `name`, `permissions`, optional `cloned_from` template); `role:manage` plus a recent step-up (401 `step_up_required` otherwise); 201.", "description": "A custom role (`key`, `name`, `permissions`, optional `cloned_from` template); `role:manage` plus a recent step-up (401 `step_up_required` otherwise); 201.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "role.created" ] } }, "/api/v1/roles/{id}": { "patch": { "tags": [ "Workspace and members" ], "operationId": "workspace_update_role", "summary": "Replaces a role's `permissions` (`role:manage` plus a recent step-up); 204", "description": "Replaces a role's `permissions` (`role:manage` plus a recent step-up); 204. The audit entry records what was added, removed and how many members it affects.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "role.updated" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/roles/{id}/preview": { "post": { "tags": [ "Workspace and members" ], "operationId": "workspace_preview_role", "summary": "Shows what a role change would do before saving it.", "description": "Shows what a role change would do before saving it.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/role-grants": { "get": { "tags": [ "Workspace and members" ], "operationId": "workspace_list_grants", "summary": "Role grants in the workspace, optionally for one `?membership_id=` (`role:view`).", "description": "Role grants in the workspace, optionally for one `?membership_id=` (`role:view`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } }, "post": { "tags": [ "Workspace and members" ], "operationId": "workspace_create_grant", "summary": "Grants `role_key` to exactly one of `membership_id` or `group_id` (else 422), with an optional scope, `expires_at` and `reason`; `member:manage_roles` plus a recent step-up; 201 `{id}`.", "description": "Grants `role_key` to exactly one of `membership_id` or `group_id` (else 422), with an optional scope, `expires_at` and `reason`; `member:manage_roles` plus a recent step-up; 201 `{id}`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "role.granted" ] } }, "/api/v1/role-grants/{id}": { "delete": { "tags": [ "Workspace and members" ], "operationId": "workspace_revoke_grant", "summary": "Revokes a role grant (`member:manage_roles` plus a recent step-up); 204.", "description": "Revokes a role grant (`member:manage_roles` plus a recent step-up); 204.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "role.revoked" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/departments": { "get": { "tags": [ "Directory" ], "operationId": "directory_list_departments", "summary": "Every department in the workspace (`directory:view`).", "description": "Every department in the workspace (`directory:view`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } }, "post": { "tags": [ "Directory" ], "operationId": "directory_create_department", "summary": "A new department (`name`, optional `parent_id`); `directory:manage`; 201.", "description": "A new department (`name`, optional `parent_id`); `directory:manage`; 201.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/departments/{id}": { "patch": { "tags": [ "Directory" ], "operationId": "directory_update_department", "summary": "Renames a department, moves it (`parent_id`, `null` for the root) or sets its head (`head_membership_id`); `directory:manage`; 204.", "description": "Renames a department, moves it (`parent_id`, `null` for the root) or sets its head (`head_membership_id`); `directory:manage`; 204.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "department.updated" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "delete": { "tags": [ "Directory" ], "operationId": "directory_delete_department", "summary": "Deletes an empty department (`directory:manage`); 204", "description": "Deletes an empty department (`directory:manage`); 204. A department that still has sub-departments, members or positions is refused with 409.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "department.deleted" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/departments/{id}/usage": { "get": { "tags": [ "Directory" ], "operationId": "directory_department_usage", "summary": "What refers to a department, shown before deleting it: role grants scoped to it, and active or draft campaigns, announcements and policies whose audience names it", "description": "What refers to a department, shown before deleting it: role grants scoped to it, and active or draft campaigns, announcements and policies whose audience names it. Titles only, and only for people who manage the directory.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/groups": { "get": { "tags": [ "Directory" ], "operationId": "directory_list_groups", "summary": "Every group in the workspace (`directory:view`).", "description": "Every group in the workspace (`directory:view`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } }, "post": { "tags": [ "Directory" ], "operationId": "directory_create_group", "summary": "A new group (`name`, optional `description`); `directory:manage`; 201.", "description": "A new group (`name`, optional `description`); `directory:manage`; 201.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "group.created" ] } }, "/api/v1/groups/{id}": { "delete": { "tags": [ "Directory" ], "operationId": "directory_delete_group", "summary": "Deletes a group (`directory:manage`); 204.", "description": "Deletes a group (`directory:manage`); 204.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "group.deleted" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/groups/{id}/members": { "get": { "tags": [ "Directory" ], "operationId": "directory_group_members", "summary": "The membership ids in a group (`directory:view`).", "description": "The membership ids in a group (`directory:view`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "post": { "tags": [ "Directory" ], "operationId": "directory_add_group_member", "summary": "Adds a member (`membership_id`) to a group (`directory:manage`); 204.", "description": "Adds a member (`membership_id`) to a group (`directory:manage`); 204.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "group.member_added" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/groups/{id}/members/{membership_id}": { "delete": { "tags": [ "Directory" ], "operationId": "directory_remove_group_member", "summary": "Removes a member from a group (`directory:manage`); 204.", "description": "Removes a member from a group (`directory:manage`); 204.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "group.member_removed" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "membership_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/positions": { "get": { "tags": [ "Directory" ], "operationId": "directory_list_positions", "summary": "Every position in the workspace (`directory:view`).", "description": "Every position in the workspace (`directory:view`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } }, "post": { "tags": [ "Directory" ], "operationId": "directory_create_position", "summary": "Positions are off unless `directory.positions.enabled`.", "description": "Positions are off unless `directory.positions.enabled`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "position.created" ] } }, "/api/v1/locations": { "get": { "tags": [ "Directory" ], "operationId": "directory_list_locations", "summary": "The directory locations in use, with how many active members each has (audience pickers).", "description": "The directory locations in use, with how many active members each has (audience pickers).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/positions/{id}": { "delete": { "tags": [ "Directory" ], "operationId": "directory_delete_position", "summary": "Deletes a position (`directory:manage`); 204.", "description": "Deletes a position (`directory:manage`); 204.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "position.deleted" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/members/{id}": { "patch": { "tags": [ "Directory" ], "operationId": "directory_update_member", "summary": "Sets a member's directory fields (`title`, `department_id`, `manager_membership_id`, `location`; `null` clears one); `directory:manage`", "description": "Sets a member's directory fields (`title`, `department_id`, `manager_membership_id`, `location`; `null` clears one); `directory:manage`. Returns `{changed}`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "member.directory_updated" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/members/{id}/directory": { "get": { "tags": [ "Directory" ], "operationId": "directory_member_directory", "summary": "A member's directory fields, groups and resolved manager (explicit, department head or none); `directory:view`.", "description": "A member's directory fields, groups and resolved manager (explicit, department head or none); `directory:view`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/members/{id}/holdings": { "get": { "tags": [ "Directory" ], "operationId": "directory_member_holdings", "summary": "What a member holds, for the leaving flow (docs/design/ia-competitive-analysis.md §8.3): documents they own, drafts and reviews they started, campaigns they run, groups, direct reports, role grants an", "description": "What a member holds, for the leaving flow (docs/design/ia-competitive-analysis.md §8.3): documents they own, drafts and reviews they started, campaigns they run, groups, direct reports, role grants and open acknowledgements, plus the workspace's hand-over default. Titles and counts only.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/members/import": { "post": { "tags": [ "Directory" ], "operationId": "directory_import", "summary": "CSV directory import", "description": "CSV directory import. `mode=plan` (default) reports what would change and rolls back; `mode=apply` commits.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "member.directory_imported" ] } }, "/api/v1/artifacts": { "get": { "tags": [ "Library (SOPs and policies)" ], "operationId": "library_list", "summary": "The SOPs and policies the caller may view, filtered by `kind`, `state` and `collection` (sub-collections included)", "description": "The SOPs and policies the caller may view, filtered by `kind`, `state` and `collection` (sub-collections included). Drafts and restricted ones show only to authors of the kind.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } }, "post": { "tags": [ "Library (SOPs and policies)" ], "operationId": "library_create", "summary": "A new SOP or policy (`kind`, `key`, `title`, optional `criticality`, `content`) with its first draft (`:create`)", "description": "A new SOP or policy (`kind`, `key`, `title`, optional `criticality`, `content`) with its first draft (`:create`). 201 with the artifact and version; 409 `key_taken`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "artifact.created" ] } }, "/api/v1/artifacts/{id}": { "get": { "tags": [ "Library (SOPs and policies)" ], "operationId": "library_get_artifact", "summary": "One document, the versions the caller may see and `my_actions` (what the caller may do with it, scoped grants included)", "description": "One document, the versions the caller may see and `my_actions` (what the caller may do with it, scoped grants included). Returns an `ETag` of its revision.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/artifacts/{id}/versions": { "post": { "tags": [ "Library (SOPs and policies)" ], "operationId": "library_new_version", "summary": "Starts a new draft from the latest version's content (`:edit_draft`)", "description": "Starts a new draft from the latest version's content (`:edit_draft`). 201; 409 when a draft or review is already open.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "version.created" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/versions/{id}": { "get": { "tags": [ "Library (SOPs and policies)" ], "operationId": "library_get_version", "summary": "One version with its content and review state (`:view`; drafts only for authors of the kind)", "description": "One version with its content and review state (`:view`; drafts only for authors of the kind). Returns an `ETag` of its revision.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "tags": [ "Library (SOPs and policies)" ], "operationId": "library_edit", "summary": "Replaces a draft's `content` (`:edit_draft`)", "description": "Replaces a draft's `content` (`:edit_draft`). Send `If-Match: \"\"` to guard against overwrites (412 when stale); 409 when the version is not a draft.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "version.edited" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/versions/{a}/diff/{b}": { "get": { "tags": [ "Library (SOPs and policies)" ], "operationId": "library_diff_versions", "summary": "Semantic diff between two versions of the same artifact: block-level added/removed/changed with word-level changes inside changed blocks.", "description": "Semantic diff between two versions of the same artifact: block-level added/removed/changed with word-level changes inside changed blocks.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "a", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "b", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/artifacts/{id}/review-cadence": { "put": { "tags": [ "Library (SOPs and policies)" ], "operationId": "library_set_cadence", "summary": "Sets the document's review cadence in `days`, or `null` for the workspace default (`:publish`).", "description": "Sets the document's review cadence in `days`, or `null` for the workspace default (`:publish`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "artifact.review_cadence_set" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/artifacts/{id}/recertify": { "post": { "tags": [ "Library (SOPs and policies)" ], "operationId": "library_recertify", "summary": "The owner confirms the published content is still correct, with an optional `comment`; a new review period starts now (`:publish`).", "description": "The owner confirms the published content is still correct, with an optional `comment`; a new review period starts now (`:publish`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "artifact.recertified" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/artifacts/{id}/verification": { "post": { "tags": [ "Library (SOPs and policies)" ], "operationId": "library_verify", "summary": "Verifying a controlled artifact needs a recent authentication, like approving it.", "description": "Verifying a controlled artifact needs a recent authentication, like approving it.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "artifact.verified" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "delete": { "tags": [ "Library (SOPs and policies)" ], "operationId": "library_unverify", "summary": "Removes the document's verification badge (`:approve`).", "description": "Removes the document's verification badge (`:approve`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "artifact.verification_removed" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/artifacts/{id}/change-requests": { "get": { "tags": [ "Library (SOPs and policies)" ], "operationId": "library_list_change_requests", "summary": "Change requests proposed for a document, optionally filtered by `state` (`:view`).", "description": "Change requests proposed for a document, optionally filtered by `state` (`:view`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "post": { "tags": [ "Library (SOPs and policies)" ], "operationId": "library_open_change_request", "summary": "Proposes a change to a document with a `title` and optional `body`; any reader may (`:view`)", "description": "Proposes a change to a document with a `title` and optional `body`; any reader may (`:view`). 201.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "change_request.opened" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/change-requests/{id}": { "get": { "tags": [ "Library (SOPs and policies)" ], "operationId": "library_get_change_request", "summary": "One change request (`:view` on its document).", "description": "One change request (`:view` on its document).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/change-requests/{id}/resolve": { "post": { "tags": [ "Library (SOPs and policies)" ], "operationId": "library_resolve_change_request", "summary": "`decision` `accepted`, `declined` (needs a `resolution`) or `implemented` (needs a `version_id` of the same document); `:publish`", "description": "`decision` `accepted`, `declined` (needs a `resolution`) or `implemented` (needs a `version_id` of the same document); `:publish`. 409 from a wrong state.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "change_request.resolved" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/artifacts/{id}/applicability": { "put": { "tags": [ "Library (SOPs and policies)" ], "operationId": "library_set_applicability", "summary": "Sets a document's `category`, who it applies to (`applicability` audience, `null` = everyone) and the `restricted` flag (`:publish`)", "description": "Sets a document's `category`, who it applies to (`applicability` audience, `null` = everyone) and the `restricted` flag (`:publish`). 422 for an empty audience.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "artifact.applicability_set" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/me/policies": { "get": { "tags": [ "Library (SOPs and policies)" ], "operationId": "library_portal", "summary": "The policies that apply to the caller, with what changed since the previous version.", "description": "The policies that apply to the caller, with what changed since the previous version.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/collections": { "get": { "tags": [ "Library (SOPs and policies)" ], "operationId": "library_list_collections", "summary": "The collections the caller may see, or all of them with `collection:manage` (`collection:view`)", "description": "The collections the caller may see, or all of them with `collection:manage` (`collection:view`). `can_manage` says which.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } }, "post": { "tags": [ "Library (SOPs and policies)" ], "operationId": "library_create_collection", "summary": "A new collection with a `name`, optionally under `parent_id` (`collection:manage`)", "description": "A new collection with a `name`, optionally under `parent_id` (`collection:manage`). 201.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "collection.created" ] } }, "/api/v1/collections/{id}": { "patch": { "tags": [ "Library (SOPs and policies)" ], "operationId": "library_update_collection", "summary": "Renames a collection and/or moves it (and its subtree) under `parent_id` (`null` = top level); `collection:manage`", "description": "Renames a collection and/or moves it (and its subtree) under `parent_id` (`null` = top level); `collection:manage`. A collection cannot move under itself.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "collection.updated" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "delete": { "tags": [ "Library (SOPs and policies)" ], "operationId": "library_delete_collection", "summary": "Deletes an empty collection (`collection:manage`)", "description": "Deletes an empty collection (`collection:manage`). 204; 409 while it still holds documents or sub-collections.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "collection.deleted" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/collections/{id}/visibility": { "put": { "tags": [ "Library (SOPs and policies)" ], "operationId": "library_set_collection_visibility", "summary": "Sets who may see a collection (`visibility` audience, `null` = everyone); `collection:manage`", "description": "Sets who may see a collection (`visibility` audience, `null` = everyone); `collection:manage`. 422 for an empty audience.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "collection.visibility_set" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/artifacts/{id}/collection": { "put": { "tags": [ "Library (SOPs and policies)" ], "operationId": "library_set_artifact_collection", "summary": "Filing a document needs `publish` on its kind (the people who control where it lives).", "description": "Filing a document needs `publish` on its kind (the people who control where it lives).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "artifact.collection_set" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/artifacts/{id}/owner": { "put": { "tags": [ "Library (SOPs and policies)" ], "operationId": "library_set_owner", "summary": "Changes a document's accountable owner to an active member (`membership_id`); `:publish`.", "description": "Changes a document's accountable owner to an active member (`membership_id`); `:publish`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "artifact.owner_set" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/artifacts/{id}/raci": { "get": { "tags": [ "Library (SOPs and policies)" ], "operationId": "library_get_raci", "summary": "A document's RACI assignments (`:view`).", "description": "A document's RACI assignments (`:view`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "put": { "tags": [ "Library (SOPs and policies)" ], "operationId": "library_set_raci", "summary": "Replaces a document's RACI, with at most one accountable assignee (`:publish`).", "description": "Replaces a document's RACI, with at most one accountable assignee (`:publish`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "artifact.raci_set" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/raci/export": { "get": { "tags": [ "Library (SOPs and policies)" ], "operationId": "library_export_raci", "summary": "RACI of every document the caller may see, as CSV", "description": "RACI of every document the caller may see, as CSV. Audited.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/versions/{id}/export": { "get": { "tags": [ "Library (SOPs and policies)" ], "operationId": "library_export_version", "summary": "A self-contained, print-ready HTML document (browsers print it as a tagged PDF), Markdown, or a Word document with real headings, lists and tables", "description": "A self-contained, print-ready HTML document (browsers print it as a tagged PDF), Markdown, or a Word document with real headings, lists and tables. Superseded and retired versions carry a \"not the current version\" banner. Audited.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/versions/{id}/submit": { "post": { "tags": [ "Library (SOPs and policies)" ], "operationId": "library_submit", "summary": "Sends a draft for review (`:edit_draft`); when the workspace requires no review for it, it is approved at once.", "description": "Sends a draft for review (`:edit_draft`); when the workspace requires no review for it, it is approved at once.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "version.approved", "version.submitted", "version.withdrawn" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/versions/{id}/withdraw": { "post": { "tags": [ "Library (SOPs and policies)" ], "operationId": "library_withdraw", "summary": "Takes a version out of review back to draft (`:edit_draft`).", "description": "Takes a version out of review back to draft (`:edit_draft`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/versions/{id}/reviews": { "post": { "tags": [ "Library (SOPs and policies)" ], "operationId": "library_review", "summary": "Records a `decision` (`approve`, `reject`, `changes_requested`; the last two need a `comment`)", "description": "Records a `decision` (`approve`, `reject`, `changes_requested`; the last two need a `comment`). Authors cannot review their own (403); controlled approvals need step-up.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "campaign.activated", "campaign.created", "version.approved", "version.published", "version.retired", "version.reviewed", "version.scheduled" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/versions/{id}/publish": { "post": { "tags": [ "Library (SOPs and policies)" ], "operationId": "library_publish", "summary": "Publishes an approved version now or at `effective_at`, as a `major` or `minor` `change` (`:publish`; controlled needs step-up)", "description": "Publishes an approved version now or at `effective_at`, as a `major` or `minor` `change` (`:publish`; controlled needs step-up). `reack` says who must re-acknowledge.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/versions/{id}/publish-preview": { "get": { "tags": [ "Library (SOPs and policies)" ], "operationId": "library_publish_preview", "summary": "What publishing a version would do: its number as a major or minor change, whether each asks for a re-acknowledgement, how many people that reaches and by when.", "description": "What publishing a version would do: its number as a major or minor change, whether each asks for a re-acknowledgement, how many people that reaches and by when.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/versions/{id}/retire": { "post": { "tags": [ "Library (SOPs and policies)" ], "operationId": "library_retire", "summary": "Retires a published or deprecated version with a `reason`; it is read-only afterwards (`:publish`).", "description": "Retires a published or deprecated version with a `reason`; it is read-only afterwards (`:publish`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/campaigns": { "get": { "tags": [ "Acknowledgement campaigns" ], "operationId": "campaigns_list", "summary": "Every acknowledgement campaign in the workspace, optionally filtered by `?state=`", "description": "Every acknowledgement campaign in the workspace, optionally filtered by `?state=`. Needs `campaign:view`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } }, "post": { "tags": [ "Acknowledgement campaigns" ], "operationId": "campaigns_create", "summary": "A draft campaign for a published SOP or policy version (`version_id`, `audience`, optional `title`, `due_at`, `audience_snapshot`, `ack_text`)", "description": "A draft campaign for a published SOP or policy version (`version_id`, `audience`, optional `title`, `due_at`, `audience_snapshot`, `ack_text`). Needs `campaign:manage`; 201.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "campaign.created" ] } }, "/api/v1/campaigns/{id}": { "get": { "tags": [ "Acknowledgement campaigns" ], "operationId": "campaigns_get_campaign", "summary": "One campaign with an `ETag`; a draft also carries `audience_preview`, the number of active members its audience reaches now", "description": "One campaign with an `ETag`; a draft also carries `audience_preview`, the number of active members its audience reaches now. Needs `campaign:view`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/campaigns/{id}/recipients": { "get": { "tags": [ "Acknowledgement campaigns" ], "operationId": "campaigns_recipients", "summary": "The campaign's assignments, optionally `?state=pending|completed|overdue` (422 otherwise)", "description": "The campaign's assignments, optionally `?state=pending|completed|overdue` (422 otherwise). Needs `campaign:view`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/campaigns/{id}/evidence": { "get": { "tags": [ "Acknowledgement campaigns" ], "operationId": "campaigns_evidence", "summary": "Evidence export as CSV", "description": "Evidence export as CSV. The export itself is audited (`campaign.evidence_exported`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/campaigns/{id}/activate": { "post": { "tags": [ "Acknowledgement campaigns" ], "operationId": "campaigns_activate", "summary": "Launches a draft, snapshotting its audience into assignments and notifying every assignee", "description": "Launches a draft, snapshotting its audience into assignments and notifying every assignee. Needs `campaign:manage`; 409 unless it is a draft.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "campaign.activated" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/campaigns/{id}/close": { "post": { "tags": [ "Acknowledgement campaigns" ], "operationId": "campaigns_close", "summary": "Closes an active campaign (optional `reason`), freezing it as evidence; open assignments stay as the record", "description": "Closes an active campaign (optional `reason`), freezing it as evidence; open assignments stay as the record. Needs `campaign:manage`; 409 in any other state.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "campaign.closed" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/campaigns/{id}/cancel": { "post": { "tags": [ "Acknowledgement campaigns" ], "operationId": "campaigns_cancel", "summary": "Cancels a draft or active campaign; a `reason` is required (422)", "description": "Cancels a draft or active campaign; a `reason` is required (422). Needs `campaign:manage`; 409 in any other state.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "campaign.cancelled" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/campaigns/{id}/remind": { "post": { "tags": [ "Acknowledgement campaigns" ], "operationId": "campaigns_remind", "summary": "Sends a reminder now to every open assignment of active members and returns `{reminded}`", "description": "Sends a reminder now to every open assignment of active members and returns `{reminded}`. Needs `campaign:manage`; 409 unless the campaign is active.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "campaign.reminded" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/me/acknowledgements": { "get": { "tags": [ "Acknowledgement campaigns" ], "operationId": "campaigns_my_acknowledgements", "summary": "The caller's own acknowledgements (`?state=pending|completed`; default: open and completed), limited to the kinds they may acknowledge.", "description": "The caller's own acknowledgements (`?state=pending|completed`; default: open and completed), limited to the kinds they may acknowledge.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/acknowledgements/{id}/complete": { "post": { "tags": [ "Acknowledgement campaigns" ], "operationId": "campaigns_complete", "summary": "Acknowledges the caller's own assignment, optionally checking `content_hash` (409 `content_changed`)", "description": "Acknowledges the caller's own assignment, optionally checking `content_hash` (409 `content_changed`). 409 `already_acknowledged` on repeat; needs `sop:acknowledge` for SOPs or `policy:view` for policies (announcements are acknowledged on the announcement).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "acknowledgement.completed" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/announcements": { "get": { "tags": [ "Announcements" ], "operationId": "announcements_list", "summary": "Announcements the caller composes or decides on, optionally filtered by `?state=`; managers see all", "description": "Announcements the caller composes or decides on, optionally filtered by `?state=`; managers see all. Each item says whether publishing it `needs_approval`. Needs `announcement:create` or `announcement:publish`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } }, "post": { "tags": [ "Announcements" ], "operationId": "announcements_create", "summary": "A new draft announcement (title, content, audience, priority, ack and timing fields)", "description": "A new draft announcement (title, content, audience, priority, ack and timing fields). Needs `announcement:create`; 201 with an `ETag`. 409 when announcements are turned off.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "announcement.created" ] } }, "/api/v1/announcements/feed": { "get": { "tags": [ "Announcements" ], "operationId": "announcements_feed", "summary": "The published, unexpired announcements sent to the caller, with read and acknowledgement receipts; `?unread=true` keeps only unread ones", "description": "The published, unexpired announcements sent to the caller, with read and acknowledgement receipts; `?unread=true` keeps only unread ones. Needs `announcement:view`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/announcements/{id}": { "get": { "tags": [ "Announcements" ], "operationId": "announcements_get_one", "summary": "One announcement the caller may see (author, publisher once submitted, or recipient), with an `ETag`", "description": "One announcement the caller may see (author, publisher once submitted, or recipient), with an `ETag`. Anyone else gets 404.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "tags": [ "Announcements" ], "operationId": "announcements_edit", "summary": "Replaces a draft's content; author with `announcement:create`, or a manager", "description": "Replaces a draft's content; author with `announcement:create`, or a manager. Optional `If-Match: \"\"` (412 if stale); 409 unless the announcement is a draft.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "announcement.edited" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/announcements/{id}/submit": { "post": { "tags": [ "Announcements" ], "operationId": "announcements_submit", "summary": "Sends the author's draft for approval; approvers are notified when the workspace's approval rule applies to its audience", "description": "Sends the author's draft for approval; approvers are notified when the workspace's approval rule applies to its audience. 409 unless it is a draft.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "announcement.submitted" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/announcements/{id}/approve": { "post": { "tags": [ "Announcements" ], "operationId": "announcements_approve", "summary": "Approves a pending announcement and publishes it now, or schedules it for `publish_at`", "description": "Approves a pending announcement and publishes it now, or schedules it for `publish_at`. Needs `announcement:publish`; 403 `sod_violation` if the approver is the author.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "announcement.approved", "announcement.published", "announcement.rejected", "announcement.scheduled", "campaign.activated", "campaign.created" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/announcements/{id}/reject": { "post": { "tags": [ "Announcements" ], "operationId": "announcements_reject", "summary": "Returns a pending announcement to draft with a required `comment` (422 if empty)", "description": "Returns a pending announcement to draft with a required `comment` (422 if empty). Needs `announcement:publish`; 409 unless it is pending approval.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/announcements/{id}/publish": { "post": { "tags": [ "Announcements" ], "operationId": "announcements_publish", "summary": "Publishes a draft now, or schedules it for its `publish_at`, when no approval applies (409 otherwise)", "description": "Publishes a draft now, or schedules it for its `publish_at`, when no approval applies (409 otherwise). Author holding `announcement:publish`, or a manager; 422 if expired.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "announcement.archived", "announcement.published", "announcement.read", "announcement.scheduled", "campaign.activated", "campaign.closed", "campaign.created" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/announcements/{id}/archive": { "post": { "tags": [ "Announcements" ], "operationId": "announcements_archive", "summary": "Withdraws a scheduled or published announcement with a `reason` and closes its acknowledgement campaign", "description": "Withdraws a scheduled or published announcement with a `reason` and closes its acknowledgement campaign. Needs `announcement:publish` or authorship; 409 otherwise.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/announcements/{id}/reads": { "post": { "tags": [ "Announcements" ], "operationId": "announcements_read", "summary": "Records that the caller read it (first read only; repeats change nothing) and returns the receipt", "description": "Records that the caller read it (first read only; repeats change nothing) and returns the receipt. Needs `announcement:view`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/announcements/{id}/acks": { "post": { "tags": [ "Announcements" ], "operationId": "announcements_acknowledge", "summary": "Acknowledges the announcement and completes the caller's campaign assignment with it: one acknowledgement, one audit record (`announcement.acknowledged`, citing the assignment).", "description": "Acknowledges the announcement and completes the caller's campaign assignment with it: one acknowledgement, one audit record (`announcement.acknowledged`, citing the assignment).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "announcement.acknowledged" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/announcements/{id}/analytics": { "get": { "tags": [ "Announcements" ], "operationId": "announcements_analytics", "summary": "Reach, read and acknowledgement counts, overall and by department", "description": "Reach, read and acknowledgement counts, overall and by department. Author with `announcement:create`, or `announcement:manage`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/request-types": { "get": { "tags": [ "Requests" ], "operationId": "requests_types", "summary": "The request types the caller may start (enabled in this workspace, and the caller is in the type's audience), with their start forms priced in the workspace currency", "description": "The request types the caller may start (enabled in this workspace, and the caller is in the type's audience), with their start forms priced in the workspace currency. `?scope=all` lists every built-in with `enabled` and `audience`, for Settings › Requests (`workspace:settings.view`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/requests": { "get": { "tags": [ "Requests" ], "operationId": "requests_list", "summary": "Requests by `scope`: `mine` (default, `request:view_own`) or `all` (`request:view_all`), optionally filtered by `status`.", "description": "Requests by `scope`: `mine` (default, `request:view_own`) or `all` (`request:view_all`), optionally filtered by `status`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } }, "post": { "tags": [ "Requests" ], "operationId": "requests_start", "summary": "Starts a request of `type` with `input` answers (201, with `Location`)", "description": "Starts a request of `type` with `input` answers (201, with `Location`). Requires an `Idempotency-Key` (a repeat replays the first response; 409 if reused for another body). Needs `request:start`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "instance.started", "request.started" ] } }, "/api/v1/requests/preview": { "post": { "tags": [ "Requests" ], "operationId": "requests_preview", "summary": "\"Who approves this\" before sending (`request:start`): a dry run of the routing for the answers so far", "description": "\"Who approves this\" before sending (`request:start`): a dry run of the routing for the answers so far. A read: nothing is written, nothing is audited, the transaction rolls back.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/requests/{id}": { "get": { "tags": [ "Requests" ], "operationId": "requests_detail", "summary": "One request in full, plus `can_cancel` (whether you may cancel it)", "description": "One request in full, plus `can_cancel` (whether you may cancel it). 404 unless you may see it (view-all, involved, or in your team).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/requests/{id}/cancel": { "post": { "tags": [ "Requests" ], "operationId": "requests_cancel", "summary": "Cancels an open request with a `reason`", "description": "Cancels an open request with a `reason`. Only the requester or a holder of `request:cancel`; 404 if you can't see it.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "instance.cancelled", "request.cancelled" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/requests/{id}/comments": { "get": { "tags": [ "Requests" ], "operationId": "requests_conversation", "summary": "The conversation on a request (internal notes hidden from the requester) and its watchers.", "description": "The conversation on a request (internal notes hidden from the requester) and its watchers.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "post": { "tags": [ "Requests" ], "operationId": "requests_comment", "summary": "Posts a comment (`request:comment` and able to see the request)", "description": "Posts a comment (`request:comment` and able to see the request). Each mentioned member must be able to see the request too (422 on `/mentions` naming who can't). Audited `request.commented`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "request.commented" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/requests/{id}/watch": { "put": { "tags": [ "Requests" ], "operationId": "requests_watch", "summary": "Follows a request: new comments and its outcome reach the caller", "description": "Follows a request: new comments and its outcome reach the caller. Audited `request.watched`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "request.watched" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "delete": { "tags": [ "Requests" ], "operationId": "requests_unwatch", "summary": "Stops following a request", "description": "Stops following a request. Audited `request.unwatched`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "request.unwatched" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/work": { "get": { "tags": [ "My work" ], "operationId": "work_list", "summary": "Work items by `state`: `open` (default) and `done` are yours (`work:view_assigned`); `unassigned` and `overdue` are workspace-wide and need `work:reassign`.", "description": "Work items by `state`: `open` (default) and `done` are yours (`work:view_assigned`); `unassigned` and `overdue` are workspace-wide and need `work:reassign`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/work/workload": { "get": { "tags": [ "My work" ], "operationId": "work_workload", "summary": "Workload per person: `scope=team` (default) is the caller's reporting line, for a manager in the directory or `work:view_team`; `scope=all` is everyone and needs workspace oversight.", "description": "Workload per person: `scope=team` (default) is the caller's reporting line, for a manager in the directory or `work:view_team`; `scope=all` is everyone and needs workspace oversight.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/work/workload/{member}": { "get": { "tags": [ "My work" ], "operationId": "work_held", "summary": "The open steps one person holds: visible for someone in the caller's reporting line, or anyone with workspace oversight", "description": "The open steps one person holds: visible for someone in the caller's reporting line, or anyone with workspace oversight. Others get 404.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "member", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/operations/incidents": { "get": { "tags": [ "My work" ], "operationId": "work_incidents", "summary": "Technical incidents: `monitoring:view_dashboards` or `request:retry`.", "description": "Technical incidents: `monitoring:view_dashboards` or `request:retry`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/operations/incidents/{source}/{id}/retry": { "post": { "tags": [ "My work" ], "operationId": "work_retry_incident", "summary": "Runs an incident again (audited `incident.retried`, a reason required).", "description": "Runs an incident again (audited `incident.retried`, a reason required).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "incident.retried" ], "parameters": [ { "name": "source", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/operations/incidents/{source}/{id}/dismiss": { "post": { "tags": [ "My work" ], "operationId": "work_dismiss_incident", "summary": "Gives up on an incident (audited `incident.dismissed`, a reason required).", "description": "Gives up on an incident (audited `incident.dismissed`, a reason required).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "incident.dismissed" ], "parameters": [ { "name": "source", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/work/{id}/decisions": { "post": { "tags": [ "My work" ], "operationId": "work_decide", "summary": "Records your decision (`outcome`, `comment`, `fields`, `files`)", "description": "Records your decision (`outcome`, `comment`, `fields`, `files`). Requires `If-Match` with the item's revision (428 without) and `work:complete`; 409 when already decided. An optional `Idempotency-Key` replays the first response.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "instance.advanced", "instance.completed", "work_item.decided", "work_item.reassigned" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/work/{id}/reassign": { "post": { "tags": [ "My work" ], "operationId": "work_reassign", "summary": "Moves an open step to one member (admin oversight)", "description": "Moves an open step to one member (admin oversight). `Idempotency-Key` optional: a replay of the same key returns the first answer.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/work/{id}/delegate": { "post": { "tags": [ "My work" ], "operationId": "work_delegate", "summary": "Hands a step the caller holds to a colleague", "description": "Hands a step the caller holds to a colleague. Separation of duties is re-checked (422 `sod_excluded` on `/membership_id`); audited `work_item.delegated`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/processes": { "get": { "tags": [ "Processes (Guided Studio)" ], "operationId": "processes_list", "summary": "Every process in the workspace, with its draft and published versions.", "description": "Every process in the workspace, with its draft and published versions.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } }, "post": { "tags": [ "Processes (Guided Studio)" ], "operationId": "processes_create", "summary": "A new process with its first draft from a template.", "description": "A new process with its first draft from a template.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "artifact.created" ] } }, "/api/v1/process-templates": { "get": { "tags": [ "Processes (Guided Studio)" ], "operationId": "processes_templates", "summary": "A blank process and every built-in request type.", "description": "A blank process and every built-in request type.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/processes/validate": { "post": { "tags": [ "Processes (Guided Studio)" ], "operationId": "processes_validate", "summary": "The problems publishing would report, in plain language.", "description": "The problems publishing would report, in plain language.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/processes/test-run": { "post": { "tags": [ "Processes (Guided Studio)" ], "operationId": "processes_test_run", "summary": "What a draft does for these answers and choices, worked out in memory (nothing is stored, nobody is told).", "description": "What a draft does for these answers and choices, worked out in memory (nothing is stored, nobody is told).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/processes/who": { "post": { "tags": [ "Processes (Guided Studio)" ], "operationId": "processes_who", "summary": "Who each candidate of a step reaches in the directory today.", "description": "Who each candidate of a step reaches in the directory today.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/processes/{id}": { "get": { "tags": [ "Processes (Guided Studio)" ], "operationId": "processes_one", "summary": "`GET /processes/{id}`.", "description": "`GET /processes/{id}`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/processes/{id}/draft": { "put": { "tags": [ "Processes (Guided Studio)" ], "operationId": "processes_save_draft", "summary": "`PUT /processes/{id}/draft` with `If-Match: \"\"`: saves the open draft, or opens a new draft from the published version first (then If-Match is not needed).", "description": "`PUT /processes/{id}/draft` with `If-Match: \"\"`: saves the open draft, or opens a new draft from the published version first (then If-Match is not needed).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "version.approved", "version.created", "version.edited", "version.published", "version.submitted", "work_item.delegated" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/processes/{id}/publish": { "post": { "tags": [ "Processes (Guided Studio)" ], "operationId": "processes_publish", "summary": "Submits the draft and, when no review is needed, publishes it", "description": "Submits the draft and, when no review is needed, publishes it. A process that does not compile is refused with its problems (422 `{problems}`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/me/out-of-office": { "get": { "tags": [ "Out of office and delegation" ], "operationId": "delegation_mine", "summary": "Your current out-of-office period and delegate, if any, and `can_set`: whether you may change it (`work:delegate` and the self-service setting)", "description": "Your current out-of-office period and delegate, if any, and `can_set`: whether you may change it (`work:delegate` and the self-service setting). Membership only.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } }, "put": { "tags": [ "Out of office and delegation" ], "operationId": "delegation_set_mine", "summary": "Sets your out-of-office from `starts_on` to `ends_on` (dates) with a `delegate` and optional `note`", "description": "Sets your out-of-office from `starts_on` to `ends_on` (dates) with a `delegate` and optional `note`. Needs `work:delegate`; 403 when self-service is turned off.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "member.ooo_set" ] }, "delete": { "tags": [ "Out of office and delegation" ], "operationId": "delegation_clear_mine", "summary": "Clears your out-of-office (204)", "description": "Clears your out-of-office (204). Same checks as setting it.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "member.ooo_cleared" ] } }, "/api/v1/members/{id}/out-of-office": { "get": { "tags": [ "Out of office and delegation" ], "operationId": "delegation_theirs", "summary": "Someone's out-of-office", "description": "Someone's out-of-office. Needs `work:delegate` and either `work:reassign` over that person or being their manager; 404 if they are not in the workspace.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "put": { "tags": [ "Out of office and delegation" ], "operationId": "delegation_set_theirs", "summary": "Sets someone's out-of-office (`starts_on`, `ends_on`, `delegate`, `note`)", "description": "Sets someone's out-of-office (`starts_on`, `ends_on`, `delegate`, `note`). Needs `work:delegate` and either `work:reassign` or being their manager.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "member.ooo_set" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "delete": { "tags": [ "Out of office and delegation" ], "operationId": "delegation_clear_theirs", "summary": "Clears someone's out-of-office (204)", "description": "Clears someone's out-of-office (204). Needs `work:delegate` and either `work:reassign` or being their manager.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "member.ooo_cleared" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/files": { "get": { "tags": [ "Files" ], "operationId": "files_list", "summary": "The workspace Files view (`file:view_all`), or the caller's own uploads.", "description": "The workspace Files view (`file:view_all`), or the caller's own uploads.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } }, "post": { "tags": [ "Files" ], "operationId": "files_create", "summary": "Starts a resumable upload from `name`, `size` and optional `content_type` (`file:upload`)", "description": "Starts a resumable upload from `name`, `size` and optional `content_type` (`file:upload`). 201 with the file and the `chunk_size` to send it in.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/files/usage": { "get": { "tags": [ "Files" ], "operationId": "files_usage", "summary": "Storage usage for the workspace Files view (`file:view_all`).", "description": "Storage usage for the workspace Files view (`file:view_all`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/files/orphans": { "get": { "tags": [ "Files" ], "operationId": "files_orphans", "summary": "Completed files nothing links to, older than `files.orphan_purge_after` (`file:view_all`).", "description": "Completed files nothing links to, older than `files.orphan_purge_after` (`file:view_all`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/files/orphans/purge": { "post": { "tags": [ "Files" ], "operationId": "files_purge_orphans", "summary": "Deletes every orphaned file and returns how many (`file:delete`).", "description": "Deletes every orphaned file and returns how many (`file:delete`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "file.orphans_purged" ] } }, "/api/v1/files/retention": { "post": { "tags": [ "Files" ], "operationId": "files_set_retention", "summary": "Bulk retention change (E2E-R1-12): sets or clears the class of the chosen files, with a reason.", "description": "Bulk retention change (E2E-R1-12): sets or clears the class of the chosen files, with a reason.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "file.retention_changed" ] } }, "/api/v1/files/{id}": { "get": { "tags": [ "Files" ], "operationId": "files_get_file", "summary": "One file and the records it is linked to, for anyone who may see it (its uploader, `file:view_all`, or a reader of what it is attached to); otherwise 404.", "description": "One file and the records it is linked to, for anyone who may see it (its uploader, `file:view_all`, or a reader of what it is attached to); otherwise 404.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "delete": { "tags": [ "Files" ], "operationId": "files_delete_file", "summary": "Deletes a file (204)", "description": "Deletes a file (204). Uploaders may delete their own unattached files; anything else needs `file:delete`. Your own file attached to a record without it is 409 `file_linked`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/files/{id}/content": { "put": { "tags": [ "Files" ], "operationId": "files_append", "summary": "One chunk at `offset` (raw bytes)", "description": "One chunk at `offset` (raw bytes). Resume by reading `received` from `GET /files/{id}`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/files/{id}/complete": { "post": { "tags": [ "Files" ], "operationId": "files_complete", "summary": "Finishes the caller's own upload once every byte has arrived; the file is hashed, type-sniffed and scanned", "description": "Finishes the caller's own upload once every byte has arrived; the file is hashed, type-sniffed and scanned. 409 when the upload is not open or bytes are still missing.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "file.deleted", "file.quarantined", "file.rejected", "file.scan_failed", "file.uploaded" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/files/{id}/download-url": { "get": { "tags": [ "Files" ], "operationId": "files_download_url", "summary": "A signed, single-member download link valid for 5 minutes.", "description": "A signed, single-member download link valid for 5 minutes.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/files/{id}/preview-url": { "get": { "tags": [ "Files" ], "operationId": "files_preview_url", "summary": "A signed preview link for a clean previewable file (`kind: image|pdf|docx|xlsx|csv`), or `kind: none` and no URL", "description": "A signed preview link for a clean previewable file (`kind: image|pdf|docx|xlsx|csv`), or `kind: none` and no URL. Same permission rules as `download-url`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/files/{id}/links": { "post": { "tags": [ "Files" ], "operationId": "files_link", "summary": "Attaches a file the caller can see to a draft document version (`object_type: artifact_version`, `object_id`); needs `edit_draft` on its kind", "description": "Attaches a file the caller can see to a draft document version (`object_type: artifact_version`, `object_id`); needs `edit_draft` on its kind. 204; 409 past draft.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "file.linked" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/files/{id}/links/{object_type}/{object_id}": { "delete": { "tags": [ "Files" ], "operationId": "files_unlink", "summary": "Detaches a file from a draft document version (`edit_draft` on its kind)", "description": "Detaches a file from a draft document version (`edit_draft` on its kind). 204; 409 once the version is past draft.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "file.unlinked" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "object_type", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "object_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/versions/{id}/attachments": { "get": { "tags": [ "Files" ], "operationId": "files_attachments", "summary": "Files attached to a document version (readers of the version see them).", "description": "Files attached to a document version (readers of the version see them).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/files/download/{token}": { "get": { "tags": [ "Files" ], "operationId": "files_download", "summary": "Serves a file for a valid token; re-checks membership, permission and file state every time.", "description": "Serves a file for a valid token; re-checks membership, permission and file state every time.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/files/preview/{token}": { "get": { "tags": [ "Files" ], "operationId": "files_preview", "summary": "Serves a previewable file for a valid preview token, re-authorized on every request, under a strict sandboxing CSP", "description": "Serves a previewable file for a valid preview token, re-authorized on every request, under a strict sandboxing CSP. Anything not on the preview allow-list is 415.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/notifications": { "get": { "tags": [ "Notifications" ], "operationId": "notifications_inbox", "summary": "Your in-app notifications, newest first, with the unread count", "description": "Your in-app notifications, newest first, with the unread count. Query: `unread=true` for unread only, `limit` (default 50).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/notifications/read-all": { "post": { "tags": [ "Notifications" ], "operationId": "notifications_read_all", "summary": "Marks all your notifications read; returns how many were marked.", "description": "Marks all your notifications read; returns how many were marked.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/notifications/{id}/read": { "post": { "tags": [ "Notifications" ], "operationId": "notifications_read_one", "summary": "Marks one of your notifications read (204).", "description": "Marks one of your notifications read (204).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/me/notification-preferences": { "get": { "tags": [ "Notifications" ], "operationId": "notifications_get_preferences", "summary": "Your delivery preferences (digests, quiet hours), with your overrides applied over the workspace defaults.", "description": "Your delivery preferences (digests, quiet hours), with your overrides applied over the workspace defaults.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } }, "put": { "tags": [ "Notifications" ], "operationId": "notifications_put_preferences", "summary": "Replaces the caller's overrides; `null` fields follow the workspace defaults", "description": "Replaces the caller's overrides; `null` fields follow the workspace defaults. Audited.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "notification_preferences.changed" ] } }, "/api/v1/me/profile": { "get": { "tags": [ "Profile" ], "operationId": "profile_get_profile", "summary": "Your email, display name, time zone and language, plus the languages offered", "description": "Your email, display name, time zone and language, plus the languages offered. Shared by every workspace you belong to.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } }, "patch": { "tags": [ "Profile" ], "operationId": "profile_update_profile", "summary": "Changes any of `display_name`, `timezone` (IANA name) and `locale`; omitted fields are kept", "description": "Changes any of `display_name`, `timezone` (IANA name) and `locale`; omitted fields are kept. 422 for an invalid value. Audited; returns the updated profile.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "user.profile_updated" ] } }, "/api/v1/views": { "get": { "tags": [ "Saved views and exports" ], "operationId": "views_list", "summary": "My views and the views shared with me for a list (mine first, then by name).", "description": "My views and the views shared with me for a list (mine first, then by name).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } }, "post": { "tags": [ "Saved views and exports" ], "operationId": "views_create", "summary": "Saves a view of a list (`list`, `name`, `state`), private or shared with everyone (`shared`) or one role (`shared_role`); `is_default` makes it your default for that list", "description": "Saves a view of a list (`list`, `name`, `state`), private or shared with everyone (`shared`) or one role (`shared_role`); `is_default` makes it your default for that list. 201.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "view.created" ] } }, "/api/v1/views/roles": { "get": { "tags": [ "Saved views and exports" ], "operationId": "views_share_roles", "summary": "The roles a view can be shared with.", "description": "The roles a view can be shared with.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/views/{id}": { "patch": { "tags": [ "Saved views and exports" ], "operationId": "views_update", "summary": "Only the owner changes a view (shared views included).", "description": "Only the owner changes a view (shared views included).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "view.updated" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "delete": { "tags": [ "Saved views and exports" ], "operationId": "views_remove", "summary": "Deletes one of your saved views (204)", "description": "Deletes one of your saved views (204). 403 for a shared view you don't own.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "view.deleted" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/exports": { "post": { "tags": [ "Saved views and exports" ], "operationId": "views_record_export", "summary": "Records that the member exported a grid view", "description": "Records that the member exported a grid view. CSV: the browser builds the file from rows it was already allowed to see, and gets 204. XLSX: the browser sends exactly those cells and gets the workbook back; text cells stay text (no formulas).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "data.exported" ] } }, "/api/v1/branding": { "get": { "tags": [ "Settings" ], "operationId": "settings_branding", "summary": "The workspace look for every member: the accent with its contrast-safe shades, the default theme, the logo and the effective terminology (every term, workspace label or product default)", "description": "The workspace look for every member: the accent with its contrast-safe shades, the default theme, the logo and the effective terminology (every term, workspace label or product default). Readable without settings permissions: it is what the UI paints.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/workspace": { "patch": { "tags": [ "Settings" ], "operationId": "settings_rename_workspace", "summary": "Renames the workspace (owners and admins: `workspace:settings.manage`)", "description": "Renames the workspace (owners and admins: `workspace:settings.manage`). Recorded on the workspace chain, and on the system chain by the platform service.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "workspace.renamed" ] } }, "/api/v1/branding/logo": { "get": { "tags": [ "Settings" ], "operationId": "settings_branding_logo", "summary": "The workspace logo for every member: the image bytes (metadata stripped, as previews), served inline only as an image, never sniffed, never cached across workspaces.", "description": "The workspace logo for every member: the image bytes (metadata stripped, as previews), served inline only as an image, never sniffed, never cached across workspaces.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/settings": { "get": { "tags": [ "Settings" ], "operationId": "settings_list", "summary": "The effective value of every workspace setting (`workspace:settings.view`).", "description": "The effective value of every workspace setting (`workspace:settings.view`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/settings/effective": { "get": { "tags": [ "Settings" ], "operationId": "settings_effective", "summary": "The explainer: final value and every contributing layer.", "description": "The explainer: final value and every contributing layer.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/settings/{key}": { "get": { "tags": [ "Settings" ], "operationId": "settings_effective_by_path", "summary": "One setting's effective value and the layers behind it, with its revision as the ETag (`workspace:settings.view`); 404 for an unknown key.", "description": "One setting's effective value and the layers behind it, with its revision as the ETag (`workspace:settings.view`); 404 for an unknown key.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "put": { "tags": [ "Settings" ], "operationId": "settings_update", "summary": "Sets a workspace setting (`value`, optional `reason`) under the key's own permission (some also need step-up); optional `If-Match: \"\"` (412 if stale), 422 if invalid.", "description": "Sets a workspace setting (`value`, optional `reason`) under the key's own permission (some also need step-up); optional `If-Match: \"\"` (412 if stale), 422 if invalid.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "setting.changed" ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/settings/{key}/history": { "get": { "tags": [ "Settings" ], "operationId": "settings_history", "summary": "The last 100 changes to one setting, newest first (`workspace:settings.view`).", "description": "The last 100 changes to one setting, newest first (`workspace:settings.view`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/settings/departments/{id}": { "get": { "tags": [ "Settings" ], "operationId": "settings_department_view", "summary": "Department-scopable keys resolved for one department, with its own overrides.", "description": "Department-scopable keys resolved for one department, with its own overrides.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/settings/departments/{id}/{key}": { "put": { "tags": [ "Settings" ], "operationId": "settings_set_override", "summary": "Sets a department override (`value`, optional `reason`) under the key's permission on that department; optional `If-Match` (412 if stale), 422 if not scopable.", "description": "Sets a department override (`value`, optional `reason`) under the key's permission on that department; optional `If-Match` (412 if stale), 422 if not scopable.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "setting.override_set" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "delete": { "tags": [ "Settings" ], "operationId": "settings_clear_override", "summary": "Removes a department's override so the workspace value applies again; optional `If-Match` (412 if stale), 404 if there is no override.", "description": "Removes a department's override so the workspace value applies again; optional `If-Match` (412 if stale), 404 if there is no override.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "setting.override_cleared" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/settings/profile/plan": { "get": { "tags": [ "Settings" ], "operationId": "settings_profile_plan", "summary": "Preview of a profile switch: every key that would change", "description": "Preview of a profile switch: every key that would change. The ETag is the plan basis.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/settings/profile/apply": { "post": { "tags": [ "Settings" ], "operationId": "settings_profile_apply", "summary": "Applies the plan whose basis is in `If-Match` (required): step-up, a reason, and the permission of every key it changes", "description": "Applies the plan whose basis is in `If-Match` (required): step-up, a reason, and the permission of every key it changes. One audit event (`settings.profile_switched`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "settings.profile_switched" ] } }, "/api/v1/audit/events": { "get": { "tags": [ "Audit trail" ], "operationId": "audit_events", "summary": "Audit events filtered by time, `actor` or `member`, action, category, object and result, in keyset pages (`page[size]`, `page[cursor]`)", "description": "Audit events filtered by time, `actor` or `member`, action, category, object and result, in keyset pages (`page[size]`, `page[cursor]`). `audit:view` sees the workspace chain; `audit:view_own` sees only the caller's own events.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/audit/objects/{object_type}/{id}/timeline": { "get": { "tags": [ "Audit trail" ], "operationId": "audit_object_timeline", "summary": "Every event for one object, oldest first", "description": "Every event for one object, oldest first. `artifact` spans all of the artifact's versions (the library records lifecycle events per version).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "object_type", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/audit/verify": { "get": { "tags": [ "Audit trail" ], "operationId": "audit_verify_chain", "summary": "Recomputes the workspace chain and reports the first sequence that does not verify.", "description": "Recomputes the workspace chain and reports the first sequence that does not verify.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/audit/saved-queries": { "get": { "tags": [ "Audit trail" ], "operationId": "audit_list_saved", "summary": "The caller's saved audit queries", "description": "The caller's saved audit queries. Needs `audit:view` or `audit:view_own`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } }, "post": { "tags": [ "Audit trail" ], "operationId": "audit_save", "summary": "Saves a named set of audit `filters` for the caller; 201", "description": "Saves a named set of audit `filters` for the caller; 201. Needs `audit:view` or `audit:view_own`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "audit.query_saved" ] } }, "/api/v1/audit/saved-queries/{id}": { "delete": { "tags": [ "Audit trail" ], "operationId": "audit_delete_saved", "summary": "Deletes one of the caller's saved audit queries; 204 (404 if not theirs)", "description": "Deletes one of the caller's saved audit queries; 204 (404 if not theirs). Needs `audit:view` or `audit:view_own`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "audit.query_deleted" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/audit/exports": { "get": { "tags": [ "Audit trail" ], "operationId": "audit_list_exports", "summary": "The caller's background exports, newest first.", "description": "The caller's background exports, newest first.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } }, "post": { "tags": [ "Audit trail" ], "operationId": "audit_export", "summary": "Synchronous export of up to 10 000 events (newest first)", "description": "Synchronous export of up to 10 000 events (newest first). `Procera-Export-Truncated: true` means more matched; narrow the filters. Larger exports move to the export job later.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "audit.export_requested", "audit.exported" ] } }, "/api/v1/audit/exports/{id}": { "get": { "tags": [ "Audit trail" ], "operationId": "audit_get_export", "summary": "The state of one of the caller's background audit exports (rows, file, error)", "description": "The state of one of the caller's background audit exports (rows, file, error). Needs `audit:export`; 404 for anyone else's.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/audit/query": { "post": { "tags": [ "Audit trail" ], "operationId": "audit_run_query", "summary": "`POST /audit/query`: AND/OR filter tree, sorted on the chain, keyset pages.", "description": "`POST /audit/query`: AND/OR filter tree, sorted on the chain, keyset pages.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/security/encryption": { "get": { "tags": [ "Encryption keys" ], "operationId": "encryption_status", "summary": "The active key version, every key version with how many values it still wraps, and how many await rewrap", "description": "The active key version, every key version with how many values it still wraps, and how many await rewrap. Needs `workspace:settings.view`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/security/encryption/rotate": { "post": { "tags": [ "Encryption keys" ], "operationId": "encryption_rotate", "summary": "Rotates to a new key version; existing values are rewrapped in the background", "description": "Rotates to a new key version; existing values are rewrapped in the background. Needs `workspace:settings.manage`, a recent sign-in and a `reason` (422 if empty).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "key.rotated" ] } }, "/api/v1/templates": { "get": { "tags": [ "Templates" ], "operationId": "templates_list", "summary": "The packs, what each creates and, for members who may install it, which of its documents already exist in the workspace (by key).", "description": "The packs, what each creates and, for members who may install it, which of its documents already exist in the workspace (by key).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/templates/{key}/install": { "post": { "tags": [ "Templates" ], "operationId": "templates_install", "summary": "Creates a pack's documents as drafts (`documents` to pick some, `on_conflict` `skip` or `copy`, `campaign` for a suggested plan)", "description": "Creates a pack's documents as drafts (`documents` to pick some, `on_conflict` `skip` or `copy`, `campaign` for a suggested plan). 201 when anything was created. Needs `template:install` and `:create` for each kind installed.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "artifact.created", "department.created", "template.installed" ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/auth/password/forgot": { "post": { "tags": [ "Password recovery" ], "operationId": "recovery_forgot", "summary": "Always 202 with the same body, whether or not the account exists (no enumeration)", "description": "Always 202 with the same body, whether or not the account exists (no enumeration). The email is queued in the background so the answer takes the same time either way.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/auth/password/reset/check": { "get": { "tags": [ "Password recovery" ], "operationId": "recovery_check", "summary": "Whether a reset link still works, so the page can say so before the person types a password.", "description": "Whether a reset link still works, so the page can say so before the person types a password.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/auth/password/reset": { "post": { "tags": [ "Password recovery" ], "operationId": "recovery_reset", "summary": "Sets a new password from a reset link (`token`, `password`); 204, and the account owner is emailed", "description": "Sets a new password from a reset link (`token`, `password`); 204, and the account owner is emailed. An invalid, expired or used link is refused with 400. Rate-limited per IP.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "password.reset" ] } }, "/api/v1/auth/password/expired": { "post": { "tags": [ "Password recovery" ], "operationId": "recovery_expired", "summary": "After `password_change_required`: sets the new password and continues the sign-in (two-step verification next when the account has it).", "description": "After `password_change_required`: sets the new password and continues the sign-in (two-step verification next when the account has it).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "login.password_ok_mfa_required", "login.succeeded", "password.changed" ] } }, "/api/v1/me/password": { "post": { "tags": [ "Password recovery" ], "operationId": "recovery_change", "summary": "Account › Security: change the password", "description": "Account › Security: change the password. Other sessions end; this one continues with the returned access token.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/members/{id}/security/reset-link": { "post": { "tags": [ "Password recovery" ], "operationId": "recovery_admin_reset_link", "summary": "Emails the member a password reset link", "description": "Emails the member a password reset link. Needs `member:security.manage` on the member, a recent step-up and a `reason`; 204, 409 if deactivated.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "member.mfa_reset", "member.password_change_required", "member.password_reset_link_sent", "member.signed_out_everywhere", "mfa.reset", "password.change_required", "password.reset_requested", "sessions.revoked_all" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/members/{id}/security/require-password-change": { "post": { "tags": [ "Password recovery" ], "operationId": "recovery_admin_require_change", "summary": "Makes the member choose a new password at next sign-in (`member:security.manage`, step-up, `reason`); 204", "description": "Makes the member choose a new password at next sign-in (`member:security.manage`, step-up, `reason`); 204. 409 if deactivated or used in other workspaces.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/members/{id}/security/sign-out-everywhere": { "post": { "tags": [ "Password recovery" ], "operationId": "recovery_admin_sign_out", "summary": "Ends all of the member's sessions (`member:security.manage`, step-up, `reason`); 204", "description": "Ends all of the member's sessions (`member:security.manage`, step-up, `reason`); 204. 409 if deactivated or used in other workspaces.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/members/{id}/security/reset-mfa": { "post": { "tags": [ "Password recovery" ], "operationId": "recovery_admin_reset_mfa", "summary": "Removes the member's two-step verification (`member:security.manage`, step-up, `reason`); 204", "description": "Removes the member's two-step verification (`member:security.manage`, step-up, `reason`); 204. 409 if deactivated or used in other workspaces.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/sysapi/v1/bootstrap": { "post": { "tags": [ "System plane: workspaces" ], "operationId": "system_bootstrap", "summary": "One-time creation of the first system owner from the bootstrap `token`, with `email`, `display_name` and `password` (201)", "description": "One-time creation of the first system owner from the bootstrap `token`, with `email`, `display_name` and `password` (201). 401 for a bad or used token, 409 once bootstrapped.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "platform.bootstrapped", "user.created" ] } }, "/sysapi/v1/me": { "get": { "tags": [ "System plane: workspaces" ], "operationId": "system_me", "summary": "Your user id and system roles", "description": "Your user id and system roles. Like every system route, needs a system role and MFA.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/sysapi/v1/workspaces": { "get": { "tags": [ "System plane: workspaces" ], "operationId": "system_list", "summary": "The console's workspace grid (`?state=&profile=&q=`): metadata, quotas and usage counts.", "description": "The console's workspace grid (`?state=&profile=&q=`): metadata, quotas and usage counts.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } }, "post": { "tags": [ "System plane: workspaces" ], "operationId": "system_create", "summary": "Creates a workspace (201, with `Location` and `ETag`); 409 if the slug is taken", "description": "Creates a workspace (201, with `Location` and `ETag`); 409 if the slug is taken. Needs `system.owner` or `system.admin`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "member.invited", "workspace.created" ] } }, "/sysapi/v1/workspaces/{id}": { "get": { "tags": [ "System plane: workspaces" ], "operationId": "system_get_one", "summary": "One workspace with its quotas and usage counts, as the console lists it, with an `ETag` of its revision", "description": "One workspace with its quotas and usage counts, as the console lists it, with an `ETag` of its revision. Any system role.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "tags": [ "System plane: workspaces" ], "operationId": "system_rename", "summary": "Renames a workspace (`name`)", "description": "Renames a workspace (`name`). Honours `If-Match` (412 when stale). Needs `system.owner` or `system.admin`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "workspace.renamed" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/sysapi/v1/workspaces/{id}/suspend": { "post": { "tags": [ "System plane: workspaces" ], "operationId": "system_suspend", "summary": "Suspends a workspace, `mode` `read_only` or `locked`, with a `reason`", "description": "Suspends a workspace, `mode` `read_only` or `locked`, with a `reason`. Needs `system.owner`/`system.admin` and a recent sign-in; `If-Match` honoured (412).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "workspace.suspended" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/sysapi/v1/workspaces/{id}/restore": { "post": { "tags": [ "System plane: workspaces" ], "operationId": "system_restore", "summary": "Returns a suspended or deletion-scheduled workspace to active (409 otherwise)", "description": "Returns a suspended or deletion-scheduled workspace to active (409 otherwise). Needs `system.owner`/`system.admin` and a recent sign-in; `If-Match` honoured (412).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "workspace.restored" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/sysapi/v1/workspaces/{id}/schedule-deletion": { "post": { "tags": [ "System plane: workspaces" ], "operationId": "system_schedule_deletion", "summary": "Schedules deletion after `grace_days`, with a `reason`", "description": "Schedules deletion after `grace_days`, with a `reason`. Needs `system.owner`/`system.admin` and a recent sign-in; `If-Match` honoured (412).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "workspace.deletion_scheduled" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/sysapi/v1/workspaces/{id}/quotas": { "put": { "tags": [ "System plane: workspaces" ], "operationId": "system_quotas", "summary": "Replaces a workspace's quotas; returns the workspace with usage", "description": "Replaces a workspace's quotas; returns the workspace with usage. Needs `system.owner` or `system.admin` and a recent sign-in.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "workspace.quotas_changed" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/sysapi/v1/workspaces/{id}/owner-invitation/link": { "post": { "tags": [ "System plane: workspaces" ], "operationId": "system_owner_invitation_link", "summary": "A fresh one-time link to the owner's pending invitation (for when email isn't set up)", "description": "A fresh one-time link to the owner's pending invitation (for when email isn't set up). Handing over a credential needs a recent authentication; the earlier link stops working.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "member.invitation_link_copied", "platform.floor_changed", "workspace.owner_invitation_link_copied" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/sysapi/v1/settings": { "get": { "tags": [ "System plane: workspaces" ], "operationId": "system_platform_settings", "summary": "The platform floors every workspace's settings are held to", "description": "The platform floors every workspace's settings are held to. Any system role.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/sysapi/v1/settings/{key}": { "put": { "tags": [ "System plane: workspaces" ], "operationId": "system_set_floor", "summary": "Sets a platform floor", "description": "Sets a platform floor. Raising it never rewrites workspace values; looser ones resolve as clamped. Floors bind every workspace's security, so this needs a recent authentication (step-up) and, when `If-Match` carries the listed revision, refuses a stale edit (412).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/sysapi/v1/quota-defaults": { "get": { "tags": [ "System plane: console" ], "operationId": "system_console_quota_defaults", "summary": "The quota bundle each configuration profile starts with", "description": "The quota bundle each configuration profile starts with. Any system role.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/sysapi/v1/quota-defaults/{profile}": { "put": { "tags": [ "System plane: console" ], "operationId": "system_console_set_quota_defaults", "summary": "Replaces one profile's default quotas for new workspaces", "description": "Replaces one profile's default quotas for new workspaces. Needs `system.owner` or `system.admin` and a recent sign-in; `If-Match` honoured (412).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "platform.quota_defaults_changed" ], "parameters": [ { "name": "profile", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/sysapi/v1/health": { "get": { "tags": [ "System plane: console" ], "operationId": "system_console_health", "summary": "Platform health", "description": "Platform health. `status` is `ok`, `degraded` (something needs a look) or `down`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/sysapi/v1/system-audit/events": { "get": { "tags": [ "System plane: console" ], "operationId": "system_console_audit_events", "summary": "The system chain through the shared explorer, newest first", "description": "The system chain through the shared explorer, newest first. System administrators' names are resolved; every other actor keeps its pseudonymous subject reference.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/sysapi/v1/system-audit/verify": { "get": { "tags": [ "System plane: console" ], "operationId": "system_console_audit_verify", "summary": "Recomputes the system chain and reports the first sequence that does not verify.", "description": "Recomputes the system chain and reports the first sequence that does not verify.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/sysapi/v1/email": { "get": { "tags": [ "System plane: email" ], "operationId": "system_email_email", "summary": "The email relay in use (`source`: environment, database or none), the stored settings without the password, and the mail queue, with an `ETag`", "description": "The email relay in use (`source`: environment, database or none), the stored settings without the password, and the mail queue, with an `ETag`. Needs owner, admin or auditor.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } }, "put": { "tags": [ "System plane: email" ], "operationId": "system_email_set_email", "summary": "Saves the SMTP relay settings", "description": "Saves the SMTP relay settings. Requires `If-Match` (428 without; `\"0\"` when none stored), a recent sign-in and `system.owner`/`system.admin`; 409 when set by the environment.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "platform.email_changed" ] } }, "/sysapi/v1/email/test": { "post": { "tags": [ "System plane: email" ], "operationId": "system_email_test_email", "summary": "Sends one test message to `to` through the relay in use and returns whether it was sent (or a safe error category); audited either way", "description": "Sends one test message to `to` through the relay in use and returns whether it was sent (or a safe error category); audited either way. 409 if email is not set up.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "platform.email_tested" ] } }, "/sysapi/v1/platform": { "get": { "tags": [ "System plane: email" ], "operationId": "system_email_platform_basics", "summary": "Read-only deployment facts: nothing here is configurable from the console yet.", "description": "Read-only deployment facts: nothing here is configurable from the console yet.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/work-locations": { "get": { "tags": [ "Hr" ], "operationId": "hr_locations", "summary": "Locations with their time zone, work week, holiday calendar and active member count (`directory:view`).", "description": "Locations with their time zone, work week, holiday calendar and active member count (`directory:view`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } }, "post": { "tags": [ "Hr" ], "operationId": "hr_create_location", "summary": "A new location (`calendar:manage`)", "description": "A new location (`calendar:manage`). 201. Audited `work_location.created`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "work_location.created" ] } }, "/api/v1/work-locations/{id}": { "get": { "tags": [ "Hr" ], "operationId": "hr_location", "summary": "One location, with an `ETag` of its revision (`directory:view`).", "description": "One location, with an `ETag` of its revision (`directory:view`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "tags": [ "Hr" ], "operationId": "hr_update_location", "summary": "`PATCH /work-locations/{id}` (the full location, as for create, plus `archived`): changes it (`calendar:manage`; honours `If-Match`); a rename renames it on members' profiles; a location people work a", "description": "`PATCH /work-locations/{id}` (the full location, as for create, plus `archived`): changes it (`calendar:manage`; honours `If-Match`); a rename renames it on members' profiles; a location people work at can't be archived (409). Audited `work_location.updated`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "work_location.updated" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/holiday-calendars": { "get": { "tags": [ "Hr" ], "operationId": "hr_calendars", "summary": "Calendars with the locations using them and the years they have holidays in (`directory:view`).", "description": "Calendars with the locations using them and the years they have holidays in (`directory:view`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } }, "post": { "tags": [ "Hr" ], "operationId": "hr_create_calendar", "summary": "A new calendar, empty or a copy of another's holidays (`calendar:manage`)", "description": "A new calendar, empty or a copy of another's holidays (`calendar:manage`). 201. Audited `holiday_calendar.created`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "holiday_calendar.created" ] } }, "/api/v1/holiday-calendars/{id}": { "get": { "tags": [ "Hr" ], "operationId": "hr_calendar", "summary": "One calendar, with an `ETag` of its revision (`directory:view`).", "description": "One calendar, with an `ETag` of its revision (`directory:view`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "tags": [ "Hr" ], "operationId": "hr_rename_calendar", "summary": "Renames a calendar (`calendar:manage`; honours `If-Match`)", "description": "Renames a calendar (`calendar:manage`; honours `If-Match`). Audited `holiday_calendar.updated`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "holiday_calendar.updated" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "delete": { "tags": [ "Hr" ], "operationId": "hr_delete_calendar", "summary": "Deletes a calendar and its holidays when no location uses it (409 otherwise; `calendar:manage`)", "description": "Deletes a calendar and its holidays when no location uses it (409 otherwise; `calendar:manage`). 204. Audited `holiday_calendar.deleted`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "holiday_calendar.deleted" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/holiday-calendars/{id}/holidays": { "get": { "tags": [ "Hr" ], "operationId": "hr_holidays", "summary": "The year's holidays `[{date, name, optional}]` (`directory:view`).", "description": "The year's holidays `[{date, name, optional}]` (`directory:view`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/holiday-calendars/{id}/holidays/{date}": { "put": { "tags": [ "Hr" ], "operationId": "hr_put_holiday", "summary": "Adds the holiday on that date or renames it (`calendar:manage`)", "description": "Adds the holiday on that date or renames it (`calendar:manage`). 201 when new, 200 when changed. Audited `holiday.set`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "holiday.set" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "date", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "delete": { "tags": [ "Hr" ], "operationId": "hr_delete_holiday", "summary": "Removes it (`calendar:manage`)", "description": "Removes it (`calendar:manage`). 204. Audited `holiday.removed`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "holiday.removed" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "date", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/holiday-calendars/{id}/import": { "post": { "tags": [ "Hr" ], "operationId": "hr_import", "summary": "Imports CSV (`date,name[,optional]`) or iCal text, at most 400 holidays and 1 MB (`calendar:manage`) → `{added, updated, skipped: [{line, text, reason}]}`", "description": "Imports CSV (`date,name[,optional]`) or iCal text, at most 400 holidays and 1 MB (`calendar:manage`) → `{added, updated, skipped: [{line, text, reason}]}`. Audited `holiday_calendar.imported`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "holiday_calendar.imported" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/holiday-calendars/{id}/copy-year": { "post": { "tags": [ "Hr" ], "operationId": "hr_copy_year", "summary": "Copies a year's holidays to the same month and day of another year, skipping dates already taken (`calendar:manage`) → as import", "description": "Copies a year's holidays to the same month and day of another year, skipping dates already taken (`calendar:manage`) → as import. Audited `holiday_calendar.year_copied`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "holiday_calendar.year_copied" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/members/{id}/hr": { "get": { "tags": [ "Hr" ], "operationId": "hr_member_hr", "summary": "`{employee_no, employment_type, work_location_id, start_date, probation_end}` (`directory:view`).", "description": "`{employee_no, employment_type, work_location_id, start_date, probation_end}` (`directory:view`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "put": { "tags": [ "Hr" ], "operationId": "hr_set_member_hr", "summary": "`PUT /members/{id}/hr` (the whole record): sets it (`directory:manage`); the work location also becomes the profile's location; 409 for a duplicate employee number", "description": "`PUT /members/{id}/hr` (the whole record): sets it (`directory:manage`); the work location also becomes the profile's location; 409 for a duplicate employee number. Audited `member.hr_updated`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "member.hr_updated" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/me/holidays": { "get": { "tags": [ "Hr" ], "operationId": "hr_my_holidays", "summary": "The caller's work location (or `null`) and its holidays in the range (default: today and the next 366 days; at most 2 years).", "description": "The caller's work location (or `null`) and its holidays in the range (default: today and the next 366 days; at most 2 years).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/leave-types": { "get": { "tags": [ "Hr" ], "operationId": "hr_leave_types", "summary": "The workspace's leave types (`directory:view`).", "description": "The workspace's leave types (`directory:view`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } }, "post": { "tags": [ "Hr" ], "operationId": "hr_create_leave_type", "summary": "`POST /leave-types {key?, name, colour?, paid?, limited?, sensitive?, half_days?, needs_attachment_after_days?, min_notice_days?, max_consecutive_days?, negative_limit_days?, counts_non_working_days?,", "description": "`POST /leave-types {key?, name, colour?, paid?, limited?, sensitive?, half_days?, needs_attachment_after_days?, min_notice_days?, max_consecutive_days?, negative_limit_days?, counts_non_working_days?, optional_holidays_only?}` → 201 (`time_off:manage_policies`). Audited `leave_type.created`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "leave_type.created" ] } }, "/api/v1/leave-types/defaults": { "post": { "tags": [ "Hr" ], "operationId": "hr_leave_defaults", "summary": "For a workspace without leave types, the common ones (annual, sick, casual, optional holiday, unpaid) and a \"Standard\" policy for everyone → 201 `{types, policy}` (409 when types exist; `time_off:mana", "description": "For a workspace without leave types, the common ones (annual, sick, casual, optional holiday, unpaid) and a \"Standard\" policy for everyone → 201 `{types, policy}` (409 when types exist; `time_off:manage_policies`). Audited `leave_type.defaults_created`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "leave_type.defaults_created" ] } }, "/api/v1/leave-types/{id}": { "patch": { "tags": [ "Hr" ], "operationId": "hr_update_leave_type", "summary": "`PATCH /leave-types/{id}` (the whole type, plus `archived`; the key never changes): honours `If-Match` (`time_off:manage_policies`)", "description": "`PATCH /leave-types/{id}` (the whole type, plus `archived`; the key never changes): honours `If-Match` (`time_off:manage_policies`). Audited `leave_type.updated`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "leave_type.updated" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/leave-policies": { "get": { "tags": [ "Hr" ], "operationId": "hr_policies", "summary": "Policies with their rules and how many people each applies to (`time_off:manage_policies` or `time_off:view_all`).", "description": "Policies with their rules and how many people each applies to (`time_off:manage_policies` or `time_off:view_all`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } }, "post": { "tags": [ "Hr" ], "operationId": "hr_create_policy", "summary": "`POST /leave-policies {name, audience, priority?, year_start_month?, rules: [{leave_type_id, yearly_days, accrual upfront|monthly, prorate?, probation_waits?, carry_over_max_days?, carry_over_expiry_m", "description": "`POST /leave-policies {name, audience, priority?, year_start_month?, rules: [{leave_type_id, yearly_days, accrual upfront|monthly, prorate?, probation_waits?, carry_over_max_days?, carry_over_expiry_months?}]}` → 201 (`time_off:manage_policies`). Audited `leave_policy.created`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "leave_policy.created" ] } }, "/api/v1/leave-policies/{id}": { "get": { "tags": [ "Hr" ], "operationId": "hr_policy", "summary": "One policy with an `ETag` (as the list).", "description": "One policy with an `ETag` (as the list).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "tags": [ "Hr" ], "operationId": "hr_update_policy", "summary": "`PATCH /leave-policies/{id}` (the whole policy, plus `archived`): honours `If-Match`; new rules apply from the next grant or accrual (`time_off:manage_policies`)", "description": "`PATCH /leave-policies/{id}` (the whole policy, plus `archived`): honours `If-Match`; new rules apply from the next grant or accrual (`time_off:manage_policies`). Audited `leave_policy.updated`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "leave_policy.updated" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/leave-policies/{id}/members": { "get": { "tags": [ "Hr" ], "operationId": "hr_policy_members", "summary": "Who it applies to now `{count, items: [{id, name}]}` (25 at most; as the list).", "description": "Who it applies to now `{count, items: [{id, name}]}` (25 at most; as the list).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/members/{id}/leave-policy": { "put": { "tags": [ "Hr" ], "operationId": "hr_assign_policy", "summary": "Gives one person a policy regardless of audiences, or goes back to audiences (`time_off:manage_policies`) → `{policy: {id, name, via}}`", "description": "Gives one person a policy regardless of audiences, or goes back to audiences (`time_off:manage_policies`) → `{policy: {id, name, via}}`. Audited `leave_policy.assigned`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "leave_policy.assigned" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/me/time-off": { "get": { "tags": [ "Hr" ], "operationId": "hr_my_time_off", "summary": "My policy and balances for the leave year containing `on` (default today): per type `{leave_type, year_start, year_end, yearly_days, accrual, granted, carried, taken, pending, adjusted, expired, avail", "description": "My policy and balances for the leave year containing `on` (default today): per type `{leave_type, year_start, year_end, yearly_days, accrual, granted, carried, taken, pending, adjusted, expired, available, entries}`, and my leave `requests`. Procera writes due grants first.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/members/{id}/time-off": { "get": { "tags": [ "Hr" ], "operationId": "hr_member_time_off", "summary": "Someone's policy and balances, as `/me/time-off` (themselves, or `time_off:view_all`).", "description": "Someone's policy and balances, as `/me/time-off` (themselves, or `time_off:view_all`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/members/{id}/time-off/adjustments": { "post": { "tags": [ "Hr" ], "operationId": "hr_adjust", "summary": "A correction in the current leave year (`time_off:adjust_balances`, step-up) → 201 entry", "description": "A correction in the current leave year (`time_off:adjust_balances`, step-up) → 201 entry. Audited `time_off.adjusted`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "time_off.adjusted" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/time-off/balances": { "get": { "tags": [ "Hr" ], "operationId": "hr_all_balances", "summary": "Everyone's current-year balances by type `{types, items: [{id, name, email, policy, balances: {type_id: {available, taken, pending}}}]}` (`time_off:view_all`).", "description": "Everyone's current-year balances by type `{types, items: [{id, name, email, policy, balances: {type_id: {available, taken, pending}}}]}` (`time_off:view_all`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/time-off/quote": { "post": { "tags": [ "Hr" ], "operationId": "hr_quote", "summary": "How many days a leave request would take for me, date by date, my balance before and after, and any problems (`[{field, code, message}]`) the request would be refused for", "description": "How many days a leave request would take for me, date by date, my balance before and after, and any problems (`[{field, code, message}]`) the request would be refused for. Changes nothing.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/team-calendar": { "get": { "tags": [ "Hr" ], "operationId": "hr_team_calendar", "summary": "Who's out between two dates (≤ 92 days) → `{from, to, people [{id, name, title, department, location_id, me}], absences [{membership_id, start_date, start_half, end_date, end_half, state, label, colou", "description": "Who's out between two dates (≤ 92 days) → `{from, to, people [{id, name, title, department, location_id, me}], absences [{membership_id, start_date, start_half, end_date, end_half, state, label, colour, request_id?, days?}], holidays [{location_id, date, name, optional}], work_weeks}`. `team` (default) is me, my manager, my manager's other reports and my reports; `department`/`location` default to mine. Colleagues see approved time off as \"Out\"; the person, their manager chain and HR (`time_off:view_all`) see the type and pending requests. `everyone` needs `time_off:view_all`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/org-chart": { "get": { "tags": [ "Hr" ], "operationId": "hr_org_chart", "summary": "Everyone active with their manager, title, department and location, and whether they're out today (approved leave, never why) → `{items: [{id, name, title, department, location, manager_id, out_today}", "description": "Everyone active with their manager, title, department and location, and whether they're out today (approved leave, never why) → `{items: [{id, name, title, department, location, manager_id, out_today}]}` (`directory:view`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/envelopes": { "get": { "tags": [ "Signing" ], "operationId": "signing_list", "summary": "Envelopes I sent (default), or every envelope with `document:view_all`; newest first, at most 500, without fields.", "description": "Envelopes I sent (default), or every envelope with `document:view_all`; newest first, at most 500, without fields.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } }, "post": { "tags": [ "Signing" ], "operationId": "signing_create", "summary": "A draft envelope for an uploaded, clean PDF (`title`, optional `message`, `file_id`, `order` sequential|parallel, `mode` simple|strong, `expires_in_days` 1–365, default 30, `bulk` to send a copy to ea", "description": "A draft envelope for an uploaded, clean PDF (`title`, optional `message`, `file_id`, `order` sequential|parallel, `mode` simple|strong, `expires_in_days` 1–365, default 30, `bulk` to send a copy to each person in a group; `document:send_for_signature`). 201 with the envelope; 422 for a PDF that can't be signed.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "envelope.created", "file.linked" ] } }, "/api/v1/envelopes/{id}": { "get": { "tags": [ "Signing" ], "operationId": "signing_one", "summary": "An envelope with its recipients and fields, for its sender, its recipients (once sent) or `document:view_all`.", "description": "An envelope with its recipients and fields, for its sender, its recipients (once sent) or `document:view_all`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/envelopes/{id}/recipients": { "put": { "tags": [ "Signing" ], "operationId": "signing_recipients", "summary": "Replaces a draft's recipients in signing order (`[{membership_id, role: signer|cc}]`, at most 50, active members)", "description": "Replaces a draft's recipients in signing order (`[{membership_id, role: signer|cc}]`, at most 50, active members). Honours `If-Match`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "envelope.recipients_set" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/envelopes/{id}/fields": { "put": { "tags": [ "Signing" ], "operationId": "signing_fields", "summary": "Replaces a draft's fields (`kind` signature|initials|date_signed| name|text|checkbox, `recipient_id` of a signer, `page`, `x`/`y`/`w`/`h` as fractions of the page from its top-left corner, `required`,", "description": "Replaces a draft's fields (`kind` signature|initials|date_signed| name|text|checkbox, `recipient_id` of a signer, `page`, `x`/`y`/`w`/`h` as fractions of the page from its top-left corner, `required`, `label`). Honours `If-Match`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "envelope.fields_set" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/envelopes/{id}/send": { "post": { "tags": [ "Signing" ], "operationId": "signing_send", "summary": "Sends a draft (every signer needs a signature field); the document and fields are frozen and the signers whose turn it is are notified", "description": "Sends a draft (every signer needs a signature field); the document and fields are frozen and the signers whose turn it is are notified. Honours `If-Match`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "envelope.sent" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/envelopes/{id}/void": { "post": { "tags": [ "Signing" ], "operationId": "signing_void", "summary": "Cancels a sent envelope with a `reason` (its sender, or anyone with `document:void`); signers who were asked are told.", "description": "Cancels a sent envelope with a `reason` (its sender, or anyone with `document:void`); signers who were asked are told.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "envelope.voided" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/envelopes/{id}/send-bulk": { "post": { "tags": [ "Signing" ], "operationId": "signing_send_bulk", "summary": "Sends a bulk draft to everyone in `audience` (`all`, `departments`, `groups`, `roles`, `locations`): one copy each, signed by that person, grouped in a batch (at most 2,000 people)", "description": "Sends a bulk draft to everyone in `audience` (`all`, `departments`, `groups`, `roles`, `locations`): one copy each, signed by that person, grouped in a batch (at most 2,000 people). Honours `If-Match`. 201 with the batch.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "envelope.bulk_sent" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/envelopes/{id}/remind": { "post": { "tags": [ "Signing" ], "operationId": "signing_remind", "summary": "Reminds the signer whose turn it is now (its sender; at most once an hour per signer)", "description": "Reminds the signer whose turn it is now (its sender; at most once an hour per signer). Returns `{reminded}`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "envelope.reminded" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/envelope-batches": { "get": { "tags": [ "Signing" ], "operationId": "signing_batches", "summary": "Group sends I made (or everyone's with `document:view_all`), newest first, with their counts.", "description": "Group sends I made (or everyone's with `document:view_all`), newest first, with their counts.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/envelope-batches/{id}": { "get": { "tags": [ "Signing" ], "operationId": "signing_batch", "summary": "A group send with each person's progress (its sender or `document:view_all`): `counts {total, signed, waiting, viewed, declined, cancelled, expired}`, `rows`.", "description": "A group send with each person's progress (its sender or `document:view_all`): `counts {total, signed, waiting, viewed, declined, cancelled, expired}`, `rows`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/envelope-batches/{id}/remind": { "post": { "tags": [ "Signing" ], "operationId": "signing_remind_batch", "summary": "Reminds everyone in a group send who hasn't signed yet (its sender; at most once an hour each)", "description": "Reminds everyone in a group send who hasn't signed yet (its sender; at most once an hour each). Returns `{reminded}`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "envelope.batch_reminded" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/envelope-batches/{id}/void": { "post": { "tags": [ "Signing" ], "operationId": "signing_void_batch", "summary": "Cancels every copy still waiting for a signature, with a `reason` (its sender, or `document:void`)", "description": "Cancels every copy still waiting for a signature, with a `reason` (its sender, or `document:void`). Returns `{cancelled}`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "envelope.batch_voided" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/envelopes/{id}/document": { "get": { "tags": [ "Signing" ], "operationId": "signing_document", "summary": "The PDF (`application/pdf`): the original the signers review, or the signed copy with its certificate once everyone has signed (409 before).", "description": "The PDF (`application/pdf`): the original the signers review, or the signed copy with its certificate once everyone has signed (409 before).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/me/signatures": { "get": { "tags": [ "Signing" ], "operationId": "signing_inbox", "summary": "The envelopes I'm on: `to_sign` when it's my turn, then the rest (waiting, signed, declined, completed copies).", "description": "The envelopes I'm on: `to_sign` when it's my turn, then the rest (waiting, signed, declined, completed copies).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/signing/{recipient}": { "get": { "tags": [ "Signing" ], "operationId": "signing_ceremony", "summary": "The signing ceremony for my recipient row: the envelope, my fields, whether it's my turn, everyone's progress, and the consent text", "description": "The signing ceremony for my recipient row: the envelope, my fields, whether it's my turn, everyone's progress, and the consent text. The first open is recorded.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "recipient", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/signing/{recipient}/sign": { "post": { "tags": [ "Signing" ], "operationId": "signing_sign", "summary": "Signs on my turn with `document_hash` (the one shown), `consent: true`, `adopted {kind: typed|drawn, text, image?}` and `values` for my text and checkbox fields", "description": "Signs on my turn with `document_hash` (the one shown), `consent: true`, `adopted {kind: typed|drawn, text, image?}` and `values` for my text and checkbox fields. `strong` envelopes need a recent sign-in (401 `step_up_required`). The last signature completes the envelope.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "envelope.completed", "envelope.declined", "envelope.signed", "file.linked", "file.uploaded" ], "parameters": [ { "name": "recipient", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/signing/{recipient}/decline": { "post": { "tags": [ "Signing" ], "operationId": "signing_decline", "summary": "Declines with a `reason`; the envelope ends for everyone and the sender is told.", "description": "Declines with a `reason`; the envelope ends for everyone and the sender is told.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "parameters": [ { "name": "recipient", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/auth/sso/discover": { "post": { "tags": [ "Sso" ], "operationId": "sso_discover", "summary": "The workspaces whose identity provider vouches for this email's domain (`{items: [{id, slug, name}]}`); empty when none do", "description": "The workspaces whose identity provider vouches for this email's domain (`{items: [{id, slug, name}]}`); empty when none do. No session needed.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/auth/sso/start": { "get": { "tags": [ "Sso" ], "operationId": "sso_start", "summary": "Redirects (303) to the workspace's identity provider with a one-time state, a nonce and a PKCE challenge", "description": "Redirects (303) to the workspace's identity provider with a one-time state, a nonce and a PKCE challenge. 404 when the workspace has no provider.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/auth/sso/callback": { "get": { "tags": [ "Sso" ], "operationId": "sso_callback", "summary": "The provider's redirect", "description": "The provider's redirect. Verifies the sign-in, opens a session in the workspace (refresh cookie) and redirects (303) into the app; any problem redirects to the sign-in page with `sso_error` (refusals are logged). Audited `login.sso_succeeded`.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } } }, "/api/v1/sso": { "get": { "tags": [ "Sso" ], "operationId": "sso_config", "summary": "The workspace's provider settings (never the secret: `has_secret`), or `null` (`workspace:settings.view`).", "description": "The workspace's provider settings (never the secret: `has_secret`), or `null` (`workspace:settings.view`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } } }, "put": { "tags": [ "Sso" ], "operationId": "sso_save", "summary": "Sets the provider (`issuer`, `client_id`, `client_secret` (absent keeps it, empty clears it), `domains`, `enabled`, `required`); the issuer's discovery document must answer first (`workspace:settings.", "description": "Sets the provider (`issuer`, `client_id`, `client_secret` (absent keeps it, empty clears it), `domains`, `enabled`, `required`); the issuer's discovery document must answer first (`workspace:settings.manage`, step-up; honours `If-Match`).", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "sso.configured" ] }, "delete": { "tags": [ "Sso" ], "operationId": "sso_remove", "summary": "Removes the provider; everyone signs in with passwords again (`workspace:settings.manage`, step-up)", "description": "Removes the provider; everyone signs in with passwords again (`workspace:settings.manage`, step-up). 204.", "responses": { "default": { "description": "See the description; errors are RFC 9457 problem details.", "content": { "application/problem+json": {} } } }, "x-audit-events": [ "sso.removed" ] } } } }