{ "openapi": "3.0.3", "info": { "title": "quiva.ai Accounts API", "description": "API for managing accounts, users, authentication, and payments in the quiva.ai platform", "version": "1.0.0", "contact": { "name": "quiva.ai Support", "url": "https://app.quiva.ai" } }, "servers": [ { "url": "https://api.quiva.ai", "description": "Production API server" } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }, "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key" }, "oauth2": { "type": "oauth2", "description": "API integration client credentials. Tokens only work on the task-sync routes in workspaces.", "flows": { "clientCredentials": { "tokenUrl": "https://api.quiva.ai/oauth/token", "scopes": {} } } } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" } } }, "SuccessResponse": { "type": "object", "properties": { "message": { "type": "string" } } }, "CreateAccountRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Account name that members of the account will be using when signing in. It is case-insensitive. Heading and trailing spaces are trimmed" }, "root_first_name": { "type": "string", "description": "Root user first name" }, "root_last_name": { "type": "string", "description": "Root user last name" }, "root_email": { "type": "string", "format": "email", "description": "Root user email. A user is not allowed to use the same email as a root email for multiple accounts." }, "password": { "type": "string", "format": "password", "description": "Root user password.\nIt has to be a new password if the user is new to the system.\nIf the user exists, they must provide their current password.\nNew password requirements:\n- Minimum length: 8 characters \n - Must contain at least one uppercase letter \n - Must contain at least one lowercase letter \n - Must contain at least one digit (number) \n - Must contain at least one special character (punctuation or symbol) \n - Maximum length: 99 characters" }, "country": { "type": "string", "description": "Country" }, "company_name": { "type": "string", "description": "Company name" }, "address": { "type": "string", "description": "Company address" }, "website": { "type": "string", "description": "Company website" }, "phone_number": { "type": "string", "description": "Company phone number" } }, "required": [ "name", "root_email", "password" ] }, "ContactRequest": { "type": "object", "properties": { "to_email": { "type": "string", "format": "email", "description": "Recipient email" }, "subject": { "type": "string", "description": "Email subject" }, "location": { "type": "string", "description": "Location in the application" }, "message": { "type": "string", "description": "Message content" }, "phone_number": { "type": "string", "description": "Phone number" }, "preferred_contact_method": { "type": "string", "description": "Preferred contact method", "enum": [ "emai", "phone" ] } }, "required": [ "to_email", "subject", "message" ] }, "RefreshTokenObject": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID" }, "user_id": { "type": "string", "description": "User ID" }, "account": { "type": "string", "description": "Account name" }, "email": { "type": "string", "format": "email", "description": "User email" }, "role": { "type": "string", "description": "Role" }, "expiry": { "type": "integer", "format": "int64", "description": "Token expiration timestamp" }, "token": { "type": "string", "description": "Refresh token" } } }, "CreateUserRequest": { "type": "object", "properties": { "first_name": { "type": "string", "description": "First name" }, "last_name": { "type": "string", "description": "Last name" }, "email": { "type": "string", "format": "email", "description": "Email address" }, "role": { "type": "string", "enum": [ "admin", "developer", "monitor", "billing" ], "description": "Role" } }, "required": [ "first_name", "last_name", "email", "role" ] }, "AuthWithApiKeyRequest": { "type": "object", "properties": { "api_key": { "type": "string", "description": "Api key" } }, "required": [ "api_key" ] }, "CompleteAuthWithPasskeyRequest": { "type": "object", "properties": { "account": { "type": "string", "description": "Account name" }, "token": { "type": "string", "description": "MFA token" }, "credential": { "type": "string", "description": "WebAuthn credential" }, "email": { "type": "string", "description": "User email" }, "remember_device": { "type": "boolean", "description": "Remember this device for 30 days. The response then carries `device_token`." } }, "required": [ "credential" ] }, "WebAuthCredentialAlias": { "type": "object", "properties": { "id": { "type": "string", "description": "Credential ID (base64 encoded)" }, "alias": { "type": "string", "description": "User-friendly name" }, "created_on": { "type": "string", "description": "Creation date" } }, "required": [ "id", "alias", "created_on" ] }, "ErrorResponse": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Error message" } } }, "StripePrice": { "type": "object", "required": [ "id", "currency", "unit_amount", "amount" ], "properties": { "id": { "type": "string", "description": "Price ID" }, "currency": { "type": "string", "description": "Currency" }, "lookup_key": { "type": "string", "description": "Lookup key" }, "nickname": { "type": "string", "description": "Nickname" }, "unit_amount": { "type": "number", "description": "Unit amount in cents" }, "amount": { "type": "number", "description": "Amount in currency units" }, "metadata": { "type": "object", "description": "Metadata" } } }, "StripeProduct": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "Product ID" }, "name": { "type": "string", "description": "Product name" }, "marketing_features": { "type": "array", "description": "Marketing features" }, "description": { "type": "string", "description": "Product description" }, "price": { "$ref": "#/components/schemas/StripePrice", "description": "Default price" }, "metadata": { "type": "object", "description": "Metadata" } } }, "SubItem": { "type": "object", "required": [ "quantity" ], "properties": { "id": { "type": "string", "description": "Subscription item ID" }, "quantity": { "type": "number", "description": "Quantity" }, "price": { "type": "string", "description": "Price ID" } } }, "SubscriptionItem": { "type": "object", "required": [ "id", "quantity", "price" ], "properties": { "id": { "type": "string", "description": "Subscription item ID" }, "quantity": { "type": "number", "description": "Quantity" }, "price": { "$ref": "#/components/schemas/StripePrice", "description": "Price" } } }, "SessionObject": { "type": "object", "required": [ "account_id", "user_id", "account", "role", "expiry", "ip", "agent", "platform", "token", "refresh_token", "is_suspended", "location" ], "properties": { "account_id": { "type": "string", "description": "Account ID" }, "user_id": { "type": "string", "description": "User ID" }, "account": { "type": "string", "description": "Account name" }, "email": { "type": "string", "description": "User email" }, "role": { "type": "string", "description": "User role" }, "expiry": { "type": "number", "description": "Subscription" }, "ip": { "type": "string", "description": "IP address" }, "agent": { "type": "string", "description": "User agent" }, "platform": { "type": "string", "description": "Platform" }, "token": { "type": "string", "description": "Authentication token" }, "refresh_token": { "type": "string", "description": "Refresh token" }, "is_suspended": { "type": "boolean", "description": "Whether the user is suspended" }, "location": { "type": "string", "description": "Location" } } }, "UpdateUserRequest": { "type": "object", "properties": { "email": { "type": "string", "description": "User email (optional, defaults to current user)" }, "first_name": { "type": "string", "description": "First name" }, "last_name": { "type": "string", "description": "Last name" }, "sound": { "type": "boolean", "description": "Enable sound" }, "theme": { "type": "string", "description": "UI theme (light, dark, auto)" }, "totp_enabled": { "type": "boolean", "description": "Enable TOTP authentication" }, "passkey_enabled": { "type": "boolean", "description": "Enable passkey authentication" } } }, "MfaInfo": { "type": "object", "required": [ "passkey_enabled", "totp_enabled" ], "properties": { "passkey_enabled": { "type": "boolean", "description": "Whether passkey authentication is enabled" }, "totp_enabled": { "type": "boolean", "description": "Whether TOTP authentication is enabled" } } }, "UserInfo": { "type": "object", "required": [ "email", "role", "is_suspended", "email_confirmed", "first_name", "last_name", "invitation_pending" ], "properties": { "email": { "type": "string", "description": "User email" }, "role": { "type": "string", "description": "Role" }, "is_suspended": { "type": "boolean", "description": "Whether the user is suspended" }, "email_confirmed": { "type": "boolean", "description": "Whether the email is confirmed" }, "first_name": { "type": "string", "description": "First name" }, "last_name": { "type": "string", "description": "Last name" }, "invitation_pending": { "type": "boolean", "description": "Whether the invitation is pending" } } }, "CheckoutURLRequest": { "type": "object", "required": [ "base_subscription", "message" ], "properties": { "base_subscription": { "type": "string", "description": "Base subscription price ID" }, "addons": { "type": "array", "description": "Subscription addons", "items": { "type": "object", "required": [ "id", "type", "quantity" ], "properties": { "id": { "type": "string", "description": "Addon price ID" }, "type": { "type": "string", "description": "Addon type" }, "quantity": { "type": "number", "description": "Quantity" } } } } } }, "UserProfileImage": { "type": "object", "properties": { "name": { "type": "string", "description": "File name" }, "contentType": { "type": "string", "description": "Content type" } } }, "AccountPublicInfo": { "type": "object", "properties": { "name": { "type": "string", "description": "Account name (normalized)" }, "id": { "type": "string", "description": "Account unique identifier - 10 digits" }, "display_name": { "type": "string", "description": "Account display name" }, "root_email": { "type": "string", "format": "email", "description": "Root user email address" }, "subscription_status": { "type": "string", "description": "Subscription status", "enum": [ "active", "pending", "cancelled" ] }, "subscription_plan": { "type": "string", "description": "Subscription plan" }, "emergency_credit": { "type": "number", "format": "float", "description": "Emergency credit amount" }, "country": { "type": "string", "description": "Country" }, "company_name": { "type": "string", "description": "Company name" }, "address": { "type": "string", "description": "Address" }, "website": { "type": "string", "description": "Website" }, "phone_number": { "type": "string", "description": "Phone number" }, "scheduled_for_deletion": { "type": "boolean", "description": "Whether the account is scheduled for deletion" }, "deletion_date": { "type": "string", "format": "date-time", "description": "If the account is scheduled for deletion, it will be deleted on this date" }, "region": { "type": "string", "description": "Region" }, "provider": { "type": "string", "description": "Provider" }, "bstier": { "type": "integer", "description": "BS tier" }, "cloud": { "type": "boolean", "description": "Cloud functionality enabled. It true, the user has access to quiva.ai Cloud" }, "hub": { "type": "boolean", "description": "Hub functionality enabled. It true, the user has access to quiva.ai Hub" } } }, "UpdateAccountRequest": { "type": "object", "properties": { "country": { "type": "string", "description": "Country" }, "company_name": { "type": "string", "description": "Company name" }, "address": { "type": "string", "description": "Address" }, "website": { "type": "string", "description": "Website" }, "phone_number": { "type": "string", "description": "Phone number" }, "onboarding_progress": { "type": "object", "description": "Onboarding progress" }, "region": { "type": "string", "description": "Region" }, "provider": { "type": "string", "description": "Provider" }, "cloud": { "type": "boolean", "description": "Cloud enabled" }, "hub": { "type": "boolean", "description": "Hub enabled" } } }, "RefreshTokenRequest": { "type": "object", "properties": { "auth_token": { "type": "string", "description": "Current authentication token" }, "refresh_token": { "type": "string", "description": "Refresh token to use for generating a new authentication token" } }, "required": [ "auth_token", "refresh_token" ], "example": { "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } }, "ExportRequest": { "type": "object", "properties": { "export": { "type": "object", "properties": { "name": { "type": "string", "description": "Unique name for the export within the account" }, "subject": { "type": "string", "description": "Subject pattern defining what is being exported" }, "token_position": { "type": "integer", "description": "Optional parameter that determines how authentication is handled" }, "type": { "type": "string", "enum": [ "stream", "service" ], "description": "Type of resource being exported" } }, "required": [ "name", "subject", "type" ] } }, "required": [ "export" ] }, "ImportRequest": { "type": "object", "properties": { "import": { "type": "object", "properties": { "name": { "type": "string", "description": "Unique name for the import within the account" }, "subject": { "type": "string", "description": "Subject pattern to be imported" }, "account": { "type": "string", "description": "Account from which the resource is being imported" }, "token_position": { "type": "integer", "description": "Optional parameter for authentication handling" } }, "required": [ "name", "subject", "account" ] } }, "required": [ "import" ] }, "CredentialAssertion": { "type": "object", "description": "WebAuthn credential assertion options for the client to process", "properties": { "challenge": { "type": "string", "description": "Base64-encoded challenge to be signed by the authenticator" }, "timeout": { "type": "integer", "description": "Time in milliseconds the user has to respond to the authentication prompt" }, "rpId": { "type": "string", "description": "Relying party identifier (usually the domain name)" }, "allowCredentials": { "type": "array", "description": "List of credentials that are allowed for this authentication", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Base64-encoded credential ID" }, "type": { "type": "string", "description": "Credential type (e.g., 'public-key')" }, "transports": { "type": "array", "description": "List of allowed transports (e.g., 'internal', 'usb')", "items": { "type": "string" } } } } }, "userVerification": { "type": "string", "description": "User verification requirement (e.g., 'preferred', 'required')" } } }, "BeginAuthWithPasskeyRequest": { "type": "object", "properties": { "account": { "type": "string", "description": "Account name (optional)" }, "email": { "type": "string", "format": "email", "description": "User's email address" } }, "required": [ "email" ], "example": { "email": "user@example.com", "account": "acme" } }, "AuthWithRecoveryCodeRequest": { "type": "object", "properties": { "token": { "type": "string", "description": "MFA token received from password authentication" }, "code": { "type": "string", "description": "Recovery code" } }, "required": [ "token", "code" ], "example": { "token": "mfa_token_abcdef1234567890", "code": "ABCD-1234" } }, "AuthWithTOTPRequest": { "type": "object", "properties": { "token": { "type": "string", "description": "MFA token received from password authentication" }, "code": { "type": "string", "description": "6-digit TOTP code from authenticator app" }, "email": { "type": "string", "format": "email", "description": "User's email address (optional when authenticated)" }, "remember_device": { "type": "boolean", "description": "Remember this device for 30 days. The response then carries `device_token`." } }, "required": [ "token", "code" ], "example": { "token": "mfa_token_abcdef1234567890", "code": "123456" } }, "ApiKeyRequest": { "type": "object", "required": [ "key_name" ], "properties": { "key_name": { "type": "string", "description": "API key name" }, "email": { "type": "string", "format": "email", "description": "Issue the key for another user of the account (root and administrators only). Defaults to the caller." }, "scope": { "type": "string", "enum": [ "user", "account" ], "default": "user", "description": "`user` keys act as the issuing user. `account` keys are shared by the account and can be issued only by root and administrators." }, "expiry_days": { "type": "integer", "description": "Days until the key expires. Defaults to 90. A negative value means the key does not expire." }, "allow_endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyEndpoint" }, "description": "Restrict the key to these endpoints" }, "allow_sub_subjects": { "type": "array", "items": { "type": "string" } }, "deny_sub_subjects": { "type": "array", "items": { "type": "string" } }, "allow_pub_subjects": { "type": "array", "items": { "type": "string" } }, "deny_pub_subjects": { "type": "array", "items": { "type": "string" } }, "resp_permission": { "type": "object", "description": "Response permission for request/reply", "properties": { "max": { "type": "integer" }, "ttl": { "type": "integer", "description": "Nanoseconds" } } } } }, "ApiKeyResponse": { "type": "object", "description": "Returned once, on creation. The full key cannot be read again.", "properties": { "key": { "type": "string", "description": "API key" }, "name": { "type": "string" }, "created_on": { "type": "string", "format": "date-time" }, "expires_on": { "type": "string", "format": "date-time" }, "creds": { "type": "string", "description": "API credentials string for CLI use. Not returned for restricted keys." } } }, "DeleteApiKeyRequest": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "User email (optional, defaults to current user)" }, "key": { "type": "string", "description": "API key" }, "id": { "type": "string", "description": "API key ID (alternative to key)" } } }, "ViewApiKey": { "type": "object", "description": "Key metadata. The key itself is never returned.", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "last_4_characters": { "type": "string" }, "created_on": { "type": "string", "format": "date-time" }, "expires_on": { "type": "string", "format": "date-time" }, "account": { "type": "string", "description": "Account name" }, "account_id": { "type": "string" }, "user_id": { "type": "string" }, "scope": { "type": "string", "enum": [ "user", "account" ] }, "allow_endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyEndpoint" } }, "permissions": { "type": "object", "additionalProperties": true } } }, "AuthWithPasswordRequest": { "type": "object", "properties": { "account": { "type": "string", "description": "Account name or sign-in slug (optional). If it is omitted and the user belongs to several accounts, the response asks the caller to pick one (`select_account`)." }, "email": { "type": "string", "format": "email", "description": "User's email address" }, "password": { "type": "string", "format": "password", "description": "User's password" }, "device_token": { "type": "string", "description": "Remembered-device token from an earlier MFA sign-in (valid for 30 days). A valid token skips the TOTP step." } }, "required": [ "email", "password" ], "example": { "account": "acme", "email": "user@example.com", "password": "SecurePassword123" } }, "AuthResponse": { "type": "object", "description": "Tokens and the signed-in user and account.", "properties": { "refresh_token": { "type": "string", "description": "Refresh token" }, "auth_token": { "type": "string", "description": "Authentication token (JWT)" }, "passkey_enabled": { "type": "boolean" }, "totp_enabled": { "type": "boolean" }, "first_sign_in": { "type": "boolean", "description": "True on the first sign-in after an invitation; the app routes it to MFA setup" }, "account": { "$ref": "#/components/schemas/AccountPublicInfo" }, "user": { "type": "string", "format": "email", "description": "User email" }, "user_id": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "role": { "type": "string", "description": "Role on the signed-in account" }, "mfa": { "$ref": "#/components/schemas/MfaInfo" }, "theme": { "type": "string" }, "sound": { "type": "boolean" }, "advanced_mode": { "type": "boolean" }, "voice_transcription": { "type": "boolean" }, "onboarding_progress": { "type": "object", "additionalProperties": true }, "timezone": { "type": "string" }, "notification_preferences": { "type": "object", "additionalProperties": true }, "folder": { "type": "string", "description": "Set for client users filed under a folder" }, "device_token": { "type": "string", "description": "Present when `remember_device` was set on an MFA step. Send it as `device_token` on later password sign-ins." } } }, "MfaRequiredResponse": { "type": "object", "properties": { "token": { "type": "string", "description": "MFA token. Use it with the TOTP, recovery-code or passkey authentication request." }, "passkey_enabled": { "type": "boolean", "description": "Whether passkey authentication is enabled" }, "totp_enabled": { "type": "boolean", "description": "Whether TOTP authentication is enabled" } } }, "ProfileImageUploadRequest": { "type": "object", "properties": { "file_name": { "type": "string", "description": "File name" }, "file": { "type": "string", "format": "byte", "description": "Base64 encoded file content" }, "content_type": { "type": "string", "description": "Content type" }, "is_chunk": { "type": "boolean", "description": "Whether the file is being uploaded in chunks" }, "chunk_index": { "type": "integer", "description": "Current chunk index" }, "total_chunks": { "type": "integer", "description": "Total number of chunks" } }, "required": [ "file_name", "file", "content_type" ] }, "IntegrationError": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "description": "Stable machine code. Branch on this, not on `error`." } }, "required": [ "error" ] }, "IntegrationScopes": { "type": "object", "description": "Space id to scopes. Space ids are upper-cased on write and match `^\\w{1,64}$`. At most 500 spaces.", "additionalProperties": { "type": "array", "items": { "type": "string", "enum": [ "tasks:read", "tasks:write", "comments:write", "space:configure" ] } } }, "IntegrationSecretView": { "type": "object", "properties": { "secret_id": { "type": "string" }, "last_4": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "retires_at": { "type": "string", "format": "date-time" }, "revoked_at": { "type": "string", "format": "date-time" }, "last_used_at": { "type": "string", "format": "date-time" } }, "required": [ "secret_id", "last_4", "created_at", "created_by" ] }, "Integration": { "type": "object", "properties": { "id": { "type": "string", "description": "Also the OAuth `client_id`." }, "account_id": { "type": "string" }, "name": { "type": "string", "maxLength": 100 }, "user_id": { "type": "string", "description": "The principal user that writes are attributed to." }, "environment": { "type": "string", "maxLength": 64, "description": "Label only in this release." }, "scopes": { "$ref": "#/components/schemas/IntegrationScopes" }, "secrets": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrationSecretView" } }, "token_epoch": { "type": "integer" }, "disabled": { "type": "boolean" }, "deleted_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" } }, "required": [ "id", "account_id", "name", "user_id", "environment", "scopes", "secrets", "token_epoch", "disabled" ] }, "CreateIntegrationRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "environment": { "type": "string", "maxLength": 64 }, "scopes": { "$ref": "#/components/schemas/IntegrationScopes" } }, "required": [ "name" ] }, "UpdateIntegrationRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "environment": { "type": "string", "maxLength": 64 }, "scopes": { "$ref": "#/components/schemas/IntegrationScopes" }, "disabled": { "type": "boolean" } }, "description": "A scope or `disabled` change bumps the token epoch: outstanding tokens answer 401 within 30 seconds." }, "RotateSecretRequest": { "type": "object", "properties": { "grace_seconds": { "type": "integer", "minimum": 0, "maximum": 2592000, "description": "Default 604800 (7 days). 0 retires the old secret immediately." } } }, "IntegrationCreated": { "type": "object", "properties": { "integration": { "$ref": "#/components/schemas/Integration" }, "client_id": { "type": "string" }, "client_secret": { "type": "string", "description": "Shown once." } }, "required": [ "integration", "client_id", "client_secret" ] }, "SecretRotated": { "type": "object", "properties": { "integration": { "$ref": "#/components/schemas/Integration" }, "secret_id": { "type": "string" }, "client_secret": { "type": "string", "description": "Shown once." } }, "required": [ "integration", "secret_id", "client_secret" ] }, "OAuthTokenRequest": { "type": "object", "properties": { "grant_type": { "type": "string", "enum": [ "client_credentials" ] }, "client_id": { "type": "string" }, "client_secret": { "type": "string" } }, "required": [ "grant_type", "client_id", "client_secret" ], "description": "Also accepted form-encoded. Send no Authorization header: the gateway refuses one it cannot resolve before this endpoint runs." }, "OAuthTokenResponse": { "type": "object", "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string", "enum": [ "Bearer" ] }, "expires_in": { "type": "integer", "description": "Seconds. Cache the token for this long." } }, "required": [ "access_token", "token_type", "expires_in" ] }, "TaskSubscription": { "type": "object", "properties": { "id": { "type": "string" }, "account_id": { "type": "string" }, "integration_id": { "type": "string" }, "spaces": { "type": "array", "items": { "type": "string" } }, "event_kinds": { "type": "array", "items": { "type": "string", "enum": [ "task-created", "task-updated", "task-status-changed", "task-moved", "task-deleted", "task-action-added", "task-action-completed", "task-action-deleted", "comment-created", "comment-updated", "comment-deleted" ] }, "description": "Empty means all kinds." }, "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "previous_secret_until": { "type": "string", "format": "date-time", "description": "While in the future, deliveries carry a second signature from the previous secret." }, "environment": { "type": "string" }, "paused": { "type": "boolean" }, "paused_reason": { "type": "string", "enum": [ "", "endpoint_gone", "consecutive_failures", "failing_for_24h", "integration_disabled", "scope_removed" ] }, "paused_at": { "type": "string" }, "consecutive_failures": { "type": "integer" }, "failing_since": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "account_id", "integration_id", "spaces", "event_kinds", "url", "paused" ] }, "CreateSubscriptionRequest": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "https only. Private, loopback and link-local hosts are refused." }, "spaces": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Each space needs `tasks:read` on the integration." }, "event_kinds": { "type": "array", "items": { "type": "string", "enum": [ "task-created", "task-updated", "task-status-changed", "task-moved", "task-deleted", "task-action-added", "task-action-completed", "task-action-deleted", "comment-created", "comment-updated", "comment-deleted" ] } } }, "required": [ "url", "spaces" ] }, "UpdateSubscriptionRequest": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "https only. Private, loopback and link-local hosts are refused." }, "spaces": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Each space needs `tasks:read` on the integration." }, "event_kinds": { "type": "array", "items": { "type": "string", "enum": [ "task-created", "task-updated", "task-status-changed", "task-moved", "task-deleted", "task-action-added", "task-action-completed", "task-action-deleted", "comment-created", "comment-updated", "comment-deleted" ] } }, "paused": { "type": "boolean", "enum": [ false ], "description": "Only `false` is accepted: it resumes and clears the failure counters. The delivery worker does the pausing." }, "rotate_secret": { "type": "boolean", "description": "Issues a new secret, returned once. The previous secret keeps signing for 24 hours." } } }, "SubscriptionCreated": { "type": "object", "properties": { "subscription": { "$ref": "#/components/schemas/TaskSubscription" }, "secret": { "type": "string", "description": "`whsec_` + base64 of 32 bytes. Shown once." } }, "required": [ "subscription", "secret" ] }, "SubscriptionUpdated": { "type": "object", "properties": { "subscription": { "$ref": "#/components/schemas/TaskSubscription" }, "secret": { "type": "string", "description": "Present only when `rotate_secret` was true." } }, "required": [ "subscription" ] }, "ReplayRequest": { "type": "object", "properties": { "from_cursor": { "oneOf": [ { "type": "string", "pattern": "^[0-9]+$" }, { "type": "integer", "minimum": 0 } ], "description": "Exclusive start. Required unless `test` is true." }, "to_cursor": { "oneOf": [ { "type": "string", "pattern": "^[0-9]+$" }, { "type": "integer", "minimum": 0 } ], "description": "Inclusive end. Omit or 0 for the end of the stream. Must be greater than `from_cursor`." }, "test": { "type": "boolean", "description": "Send a synthetic `test` event instead. Works on a paused subscription." } } }, "ReplayAccepted": { "type": "object", "properties": { "request_id": { "type": "string" }, "type": { "type": "string", "enum": [ "replay", "test" ] } }, "required": [ "request_id", "type" ] }, "TaskDelivery": { "type": "object", "properties": { "stream_seq": { "type": "integer", "description": "0 is the latest test event." }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "status": { "type": "string", "enum": [ "sending", "delivered", "retrying", "failed" ] }, "attempts": { "type": "integer" }, "last_status_code": { "type": "integer" }, "latency_ms": { "type": "integer" }, "response_excerpt": { "type": "string", "maxLength": 512 }, "delivered_at": { "type": "string" }, "last_error": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "stream_seq", "event_id", "status" ] }, "DeliveryPage": { "type": "object", "properties": { "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/TaskDelivery" } }, "next_cursor": { "type": "string", "description": "Empty when there is no next page." }, "has_more": { "type": "boolean" } }, "required": [ "deliveries", "next_cursor", "has_more" ] }, "LoginAccount": { "type": "object", "required": [ "id", "name", "role" ], "properties": { "id": { "type": "string" }, "name": { "type": "string", "description": "Account name (sign-in key)" }, "display_name": { "type": "string" }, "role": { "type": "string", "description": "The user's role on that account" }, "invitation_pending": { "type": "boolean" } } }, "AccountSelectResponse": { "type": "object", "description": "Returned instead of tokens when an email-only sign-in matches several accounts. Pass `token` and the chosen account id to `POST /accounts/auth-select-account`.", "required": [ "select_account", "accounts", "token" ], "properties": { "select_account": { "type": "boolean", "enum": [ true ] }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/LoginAccount" } }, "token": { "type": "string", "description": "Single-use token that names the user. Spent when the pick is valid." } } }, "AuthSelectAccountRequest": { "type": "object", "required": [ "token", "account_id" ], "properties": { "token": { "type": "string", "description": "The `token` from the `select_account` response" }, "account_id": { "type": "string", "description": "Id of one of the accounts in the picker list" }, "device_token": { "type": "string", "description": "Remembered-device token; skips TOTP when valid" } } }, "ApiKeyEndpoint": { "type": "object", "required": [ "method", "path" ], "properties": { "method": { "type": "string", "description": "HTTP method" }, "path": { "type": "string", "description": "HTTP path" }, "gateway_id": { "type": "string" }, "subjects": { "type": "array", "items": { "type": "string" }, "description": "Subjects allowed on the request body" } } }, "ChangeAccountSlugRequest": { "type": "object", "required": [ "slug", "email_code" ], "properties": { "slug": { "type": "string", "description": "3-63 lowercase letters, numbers or hyphens. Reserved platform names are refused." }, "email_code": { "type": "string", "description": "Email verification code, see `GET /accounts/email-code`" } } }, "AccountSlugResponse": { "type": "object", "properties": { "slug": { "type": "string" }, "slug_aliases": { "type": "array", "items": { "type": "string" }, "description": "Previous slugs, up to 3, that still sign in" }, "slug_published": { "type": "boolean", "description": "False while the sign-in address's DNS record is not yet published" } } }, "ClientBrandingRequest": { "type": "object", "required": [ "account" ], "properties": { "account": { "type": "string", "description": "Account slug or legacy account name" } } }, "ClientBranding": { "type": "object", "description": "Brand for a sign-in page. An unknown account returns only `account`.", "properties": { "account": { "type": "string" }, "display_name": { "type": "string" }, "app_name": { "type": "string" }, "primary_color": { "type": "string" }, "secondary_color": { "type": "string" }, "logo_data_uri": { "type": "string" }, "favicon_data_uri": { "type": "string" }, "favicon_dark_data_uri": { "type": "string", "description": "Present only when a dark-mode icon is set" }, "ui_theme": { "type": "object", "additionalProperties": true, "description": "Present only when the account set a theme" } } }, "SendClientSignInRequest": { "type": "object", "required": [ "email", "template_key" ], "properties": { "email": { "type": "string", "format": "email", "description": "The client. The mail goes to the address on file for that client, never to an address in the body." }, "template_key": { "type": "string", "description": "Key of a published email template that carries the `{sign_in_url}` tag" }, "data": { "type": "object", "additionalProperties": true, "description": "Values for the template's tags. `sign_in_url` is always the minted link." }, "redirect_path": { "type": "string", "description": "Path in the app the client lands on after signing in" }, "contact_folder": { "type": "string", "description": "Folder the mail belongs to, echoed in delivery events" }, "task_id": { "type": "string", "description": "Task the mail belongs to, echoed in delivery events" } } }, "ImageKeyRequest": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "Key of the uploaded file in the account's workspace storage" } } }, "ImageKeyResponse": { "type": "object", "properties": { "key": { "type": "string", "description": "Stored key" } } }, "EmailTemplateData": { "type": "object", "description": "Record data a template merges. The caller loads it; a declared tag with no value renders blank.", "properties": { "record_configs": { "type": "array", "items": { "type": "string" }, "description": "Whole record sets by config id" }, "fields": { "type": "array", "items": { "type": "string" }, "description": "Exact `.` fields" } } }, "EmailTemplateAttachment": { "type": "object", "properties": { "key": { "type": "string" }, "filename": { "type": "string", "description": "May hold {tags}" }, "size": { "type": "integer" }, "type": { "type": "string" } } }, "EmailTemplateVersion": { "type": "object", "properties": { "subject": { "type": "string" }, "html": { "type": "string" }, "text": { "type": "string", "description": "Derived from the HTML at render time when empty" }, "notes": { "type": "string" }, "data": { "$ref": "#/components/schemas/EmailTemplateData" }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/EmailTemplateAttachment" } }, "saved_at": { "type": "string", "format": "date-time" }, "saved_by": { "type": "string" } } }, "EmailTemplate": { "type": "object", "description": "One per account and key. A template holds a draft and a published version.", "properties": { "key": { "type": "string", "description": "Slug that flows and Abbie reference. Never changes after creation." }, "name": { "type": "string" }, "description": { "type": "string" }, "draft": { "$ref": "#/components/schemas/EmailTemplateVersion" }, "published": { "$ref": "#/components/schemas/EmailTemplateVersion" }, "data": { "$ref": "#/components/schemas/EmailTemplateData" }, "sample_data": { "type": "object", "additionalProperties": true, "description": "What the preview renders against" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Every {tag} in the draft's subject, html and text" }, "source": { "type": "string", "enum": [ "abbie", "api" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "updated_by": { "type": "string" }, "published_at": { "type": "string", "format": "date-time" }, "published_by": { "type": "string" } } }, "EmailTemplateSummary": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "published", "published_with_draft" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "data": { "$ref": "#/components/schemas/EmailTemplateData" }, "source": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "updated_by": { "type": "string" }, "published_at": { "type": "string" }, "published_by": { "type": "string" } } }, "SaveEmailTemplateRequest": { "type": "object", "required": [ "key", "subject", "html" ], "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "subject": { "type": "string" }, "html": { "type": "string" }, "text": { "type": "string" }, "notes": { "type": "string" }, "sample_data": { "type": "object", "additionalProperties": true }, "data": { "$ref": "#/components/schemas/EmailTemplateData" }, "source": { "type": "string", "enum": [ "abbie", "api" ] }, "session_id": { "type": "string" } } }, "EmailTemplateKeyRequest": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string" } } }, "EmailTemplateAttachmentRequest": { "type": "object", "required": [ "key", "file_key" ], "properties": { "key": { "type": "string", "description": "Template key" }, "bucket": { "type": "string", "description": "Bucket to copy the file from (add only)" }, "file_key": { "type": "string", "description": "File to add, or the attached file to remove" }, "filename": { "type": "string" } } }, "RenderEmailTemplateRequest": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string" }, "version": { "type": "string", "enum": [ "draft", "published" ], "description": "Defaults to the draft when there is one, else the published version" }, "data": { "type": "object", "additionalProperties": true, "description": "Values for the tags. Without it the stored sample data is used." } } }, "RenderedEmailTemplate": { "type": "object", "properties": { "version": { "type": "string" }, "subject": { "type": "string" }, "html": { "type": "string" }, "text": { "type": "string" }, "unresolved": { "type": "array", "items": { "type": "string" }, "description": "Tags the data did not answer. A send refuses on them." } } } } }, "tags": [ { "name": "Account Management", "description": "Operations related to account creation, updating, and deletion" }, { "name": "User Management", "description": "Operations related to user creation, updating, and deletion" }, { "name": "Authentication", "description": "Operations related to authentication and session management" }, { "name": "API Keys", "description": "Operations related to API key management" }, { "name": "Multi-Factor Authentication", "description": "Operations related to MFA setup and verification" }, { "name": "Payment", "description": "Operations related to subscription and payment management" }, { "name": "Mesh Nodes", "description": "Operations related to mesh node management" }, { "name": "Integrations", "description": "Machine identities and client credentials for task sync" }, { "name": "Task Subscriptions", "description": "Webhook subscriptions that push task events to your endpoint" }, { "name": "Email Templates", "description": "Account email templates used by flows, Abbie and the client sign-in email" }, { "name": "Branding", "description": "Sign-in branding and account images" }, { "name": "Client Access", "description": "Passwordless sign-in and invitations for client users" }, { "name": "Sync Packages", "description": "Install, upgrade and remove sync packages for an account" }, { "name": "Terms", "description": "Terms documents, provider terms and the acceptance log" }, { "name": "Email Sending", "description": "Sending identity and outbound email" }, { "name": "Usage and Billing", "description": "Cost events, billing events, credit budget and spend guard" }, { "name": "Notifications", "description": "In-app notifications for the signed-in user" }, { "name": "Resource Access", "description": "Per-user grants on resources such as spaces" }, { "name": "Document Branding", "description": "Account theme and logo used on generated documents" } ], "paths": { "/accounts/oauth/login": { "get": { "summary": "Initiate OAuth login flow", "description": "Generates OAuth URL for authentication with external providers (Auth0)", "tags": [ "Authentication" ], "x-resource-type": "service", "security": [], "operationId": "getOAuthLoginUrl", "parameters": [ { "name": "Referer", "in": "header", "required": true, "description": "Referer URL", "schema": { "type": "string" }, "example": "https://app.quiva.ai/" }, { "name": "account", "in": "query", "required": true, "description": "Account identifier for the login request", "schema": { "type": "string" } }, { "name": "connection", "in": "query", "required": false, "description": "OAuth connection type (e.g., github, google-oauth2)", "schema": { "type": "string" }, "examples": { "github": { "value": "github", "description": "GitHub OAuth connection" }, "google": { "value": "google-oauth2", "description": "Google OAuth connection" } } } ], "responses": { "200": { "description": "OAuth URL generated successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "oauth_url": { "type": "string", "format": "uri", "description": "URL to redirect user for OAuth authentication", "example": "https://domain.auth0.com/authorize?client_id=...&response_type=code&redirect_uri=...&state=..." } } } } } } } }, "400": { "description": "Bad request - missing required parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/accounts/oauth/callback": { "get": { "summary": "OAuth callback handler", "description": "Handles OAuth callback from external authentication provider", "tags": [ "Authentication" ], "x-resource-type": "service", "security": [], "operationId": "handleOAuthCallback", "parameters": [ { "name": "code", "in": "query", "required": true, "description": "Authorization code from OAuth provider", "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": true, "description": "State parameter to prevent CSRF attacks", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Authentication successful - typically redirects user", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Success response (implementation may vary based on authOrMFA function)" } } } } } }, "400": { "description": "Bad request - invalid parameters or authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/accounts/info": { "get": { "summary": "Get account information", "description": "Retrieves comprehensive information about the authenticated user's current account in a public-facing format (no sensitive data is returned).", "operationId": "getAccountInfo", "x-resource-type": "service", "tags": [ "Account Management" ], "responses": { "200": { "description": "Account information retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AccountPublicInfo" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/api-key": { "post": { "summary": "Issue API key", "description": "Issues a new API key. The full key is returned once. User keys act as the issuing user and work on every endpoint that user can reach. Account keys (`scope: account`) can be issued only by root and administrators. Keys expire after 90 days unless `expiry_days` says otherwise. This is not an API integration: integrations are machine identities for task sync only.", "operationId": "issueApiKey", "x-resource-type": "service", "tags": [ "API Keys" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyRequest" } } } }, "responses": { "200": { "description": "API key created successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ApiKeyResponse" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden. Only root and administrators can issue account keys or keys for another user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete API key", "description": "Delete an API key.\n- A key can be delted by providing the full key or by id.\n- Deleted API keys cannot be recovered", "operationId": "deleteApiKey", "x-resource-type": "service", "tags": [ "API Keys" ], "parameters": [ { "name": "key", "in": "query", "description": "Full API key (available for preview only on creation)", "required": false, "schema": { "type": "string" } }, { "name": "id", "in": "query", "description": "Key id (available in the key list)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "API key deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Key not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/api-keys": { "get": { "summary": "View API keys", "description": "Lists the metadata of the API keys that belong to the current session's account. Users see their own user keys and the account's shared keys. Root and administrators can list another user's keys with `email`. The key itself is never returned. Keys of the user's other accounts are not listed: sign in to that account to see them.", "operationId": "viewApiKeys", "x-resource-type": "service", "tags": [ "API Keys" ], "parameters": [ { "name": "email", "in": "query", "description": "User email (optional, defaults to current user)", "schema": { "type": "string", "format": "email" } } ], "responses": { "200": { "description": "API keys retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ViewApiKey" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/auth-with-password": { "post": { "tags": [ "Authentication" ], "summary": "Authenticate with password", "description": "Authenticates a user with email and password. Depending on the user, the response is one of: tokens (`AuthResponse`), an MFA token when TOTP is on and the device is not remembered (`MfaRequiredResponse`), or an account picker (`AccountSelectResponse`) when no `account` was given and the user belongs to several accounts. Send `device_token` from an earlier MFA sign-in to skip TOTP.", "operationId": "authWithPassword", "x-resource-type": "service", "security": [], "requestBody": { "description": "Authentication credentials", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthWithPasswordRequest" }, "examples": { "basicAuth": { "summary": "Basic authentication", "value": { "email": "user@example.com", "password": "SecurePassword123" } }, "withAccount": { "summary": "With account specified", "value": { "account": "acme", "email": "user@example.com", "password": "SecurePassword123" } }, "rememberedDevice": { "summary": "With a remembered device", "value": { "email": "user@example.com", "password": "SecurePassword123", "device_token": "device_token_abcdef" } } } } } }, "responses": { "200": { "description": "Authentication successful or MFA required", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/AuthResponse" }, { "$ref": "#/components/schemas/MfaRequiredResponse" }, { "$ref": "#/components/schemas/AccountSelectResponse" } ] } } }, "examples": { "authSuccess": { "summary": "Authentication successful (no MFA)", "value": { "data": { "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "passkey_enabled": false, "totp_enabled": false, "account": { "name": "acme", "id": "acct_12345", "display_name": "ACME Corporation", "root_email": "admin@acme.com", "subscription_status": "active" } } } }, "mfaRequired": { "summary": "MFA verification required", "value": { "data": { "token": "mfa_token_abcdef1234567890", "passkey_enabled": true, "totp_enabled": true } } }, "selectAccount": { "summary": "Several accounts: pick one", "value": { "data": { "select_account": true, "accounts": [ { "id": "acct_12345", "name": "acme", "display_name": "ACME Corporation", "role": "admin" }, { "id": "acct_67890", "name": "globex", "display_name": "Globex", "role": "member" } ], "token": "select_token_abcdef1234567890" } } } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Invalid credentials" } } } } } } }, "/accounts/profile-image": { "post": { "summary": "Upload profile image", "description": "Uploads a profile image for the user", "operationId": "uploadProfileImage", "x-resource-type": "service", "tags": [ "User Management" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileImageUploadRequest" } } } }, "responses": { "200": { "description": "Profile image uploaded successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete profile image", "description": "Deletes the user's profile image", "operationId": "deleteProfileImage", "x-resource-type": "service", "tags": [ "User Management" ], "responses": { "200": { "description": "Profile image deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/recovery-codes": { "post": { "summary": "Issue recovery codes", "description": "Generates new recovery codes for a user", "operationId": "issueRecoveryCodes", "tags": [ "Multi-Factor Authentication" ], "x-resource-type": "service", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "User email (optional, defaults to current user)" } } }, "example": { "email": "user@example.com" } } } }, "responses": { "200": { "description": "Recovery codes issued successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "string" } } } }, "example": { "data": [ "ABCD-1234", "EFGH-5678", "IJKL-9012" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "View recovery codes", "description": "Retrieves existing recovery codes for a user", "operationId": "viewRecoveryCodes", "tags": [ "Multi-Factor Authentication" ], "x-resource-type": "service", "parameters": [ { "name": "email", "in": "query", "description": "User email (optional, defaults to current user)", "schema": { "type": "string", "format": "email" } } ], "responses": { "200": { "description": "Recovery codes retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "string" } } } }, "example": { "data": [ "ABCD-1234", "EFGH-5678", "IJKL-9012" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/auth-with-recovery-code": { "post": { "tags": [ "Authentication", "Multi-Factor Authentication" ], "summary": "Authenticate with recovery code", "description": "Complete authentication using a recovery code after initial password verification. Recovery codes are one-time use.", "operationId": "authWithRecoveryCode", "x-resource-type": "service", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthWithRecoveryCodeRequest" }, "example": { "token": "mfa_token_abcdef1234567890", "code": "ABCD-1234" } } } }, "responses": { "200": { "description": "Authentication successful", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AuthResponse" } } } } } }, "401": { "description": "Invalid recovery code or token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Used or invalid recovery code" } } } } } } }, "/accounts/remove-user": { "delete": { "summary": "Remove user from account", "description": "Removes a user from the current account, or with `folder` removes every client link filed at that folder or beneath it. The user record itself is not deleted (use `DELETE /accounts/user` for that). Handled by `delete.user-from-account`.", "operationId": "removeUser", "tags": [ "User Management" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "User email" }, "folder": { "type": "string", "description": "Remove every link filed at this folder or beneath it, instead of `email`" } } }, "example": { "email": "user@example.com" } } } }, "responses": { "200": { "description": "User removed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/request-reset-password": { "post": { "summary": "Request password reset", "description": "Requests a password reset for a user", "operationId": "requestResetPassword", "tags": [ "Authentication" ], "x-resource-type": "service", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "User email" } }, "required": [ "email" ] }, "example": { "email": "user@example.com" } } } }, "responses": { "200": { "description": "Password reset request processed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } } } } }, "/accounts/reset-password": { "post": { "summary": "Reset password", "description": "Resets a user's password", "operationId": "resetPassword", "tags": [ "Authentication" ], "x-resource-type": "service", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "User email" }, "token": { "type": "string", "description": "Password reset token" }, "password": { "type": "string", "description": "Current password (required when authenticated)" }, "new_password": { "type": "string", "description": "New password.\n\nRequirements:\n- Minimum length: 8 characters \n - Must contain at least one uppercase letter \n - Must contain at least one lowercase letter \n - Must contain at least one digit (number) \n - Must contain at least one special character (punctuation or symbol) \n - Maximum length: 99 characters" } }, "required": [ "token", "new_password" ] }, "example": { "email": "user@example.com", "token": "abcdef123456", "new_password": "NewSecureP@ssw0rd!" } } } }, "responses": { "200": { "description": "Password reset successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/set-password": { "post": { "summary": "Set password", "description": "Sets a password for a new user", "operationId": "setPassword", "tags": [ "Authentication" ], "x-resource-type": "service", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "Set password token" }, "password": { "type": "string", "description": "New password.\n\nRequirements:\n- Minimum length: 8 characters \n - Must contain at least one uppercase letter \n - Must contain at least one lowercase letter \n - Must contain at least one digit (number) \n - Must contain at least one special character (punctuation or symbol) \n - Maximum length: 99 characters" } }, "required": [ "token", "password" ] }, "example": { "token": "abcdef123456", "password": "SecureP@ssw0rd!" } } } }, "responses": { "200": { "description": "Password set successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "account_id": { "type": "string" }, "user_id": { "type": "string" }, "account": { "type": "string" }, "email": { "type": "string", "format": "email" } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/generate-totp-key": { "post": { "summary": "Generate TOTP key", "description": "Generates a TOTP key for multi-factor authentication", "operationId": "generateTotpKey", "tags": [ "Multi-Factor Authentication" ], "x-resource-type": "service", "responses": { "200": { "description": "TOTP key generated successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "otpauth_url": { "type": "string", "description": "OTP Auth URL for QR code generation" }, "secret": { "type": "string", "description": "TOTP secret key" } } } } }, "example": { "data": { "otpauth_url": "otpauth://totp/quiva.ai:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=quiva.ai", "secret": "JBSWY3DPEHPK3PXP" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/confirm-totp-registration": { "post": { "summary": "Confirm TOTP registration", "description": "Confirms a TOTP registration by validating a code", "operationId": "confirmTotpRegistration", "tags": [ "Multi-Factor Authentication" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "TOTP code" }, "secret": { "type": "string", "description": "TOTP secret key" } }, "required": [ "code", "secret" ] }, "example": { "code": "123456", "secret": "JBSWY3DPEHPK3PXP" } } } }, "responses": { "200": { "description": "TOTP registration confirmed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "recovery_codes": { "type": "array", "items": { "type": "string" } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/auth-with-totp": { "post": { "tags": [ "Authentication", "Multi-Factor Authentication" ], "summary": "Authenticate with TOTP", "description": "Complete authentication using a Time-based One-Time Password (TOTP) after initial password verification.", "operationId": "authWithTotp", "x-resource-type": "service", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthWithTOTPRequest" }, "example": { "token": "mfa_token_abcdef1234567890", "code": "123456" } } } }, "responses": { "200": { "description": "Authentication successful", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AuthResponse" } } } } } }, "401": { "description": "Invalid TOTP code or token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Unauthorized" } } } } } } }, "/accounts/totp": { "delete": { "summary": "Remove TOTP", "description": "Disables TOTP authentication for a user", "operationId": "removeTotp", "tags": [ "Multi-Factor Authentication" ], "x-resource-type": "service", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "User email (optional, defaults to current user)" } } }, "example": { "email": "user@example.com" } } } }, "responses": { "200": { "description": "TOTP removed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/set-emergency-credit": { "patch": { "summary": "Set emergency credit", "description": "Sets the emergency credit amount for an account.\n- Allows users with appropriate permissions (root, admin, or billing roles) to configure a maximum monthly emergency budget.\n- For accounts with fixed resource allocations, emergency credit funds the provisioning of additional resources when regular allocations are exhausted.", "operationId": "setEmergencyCredit", "tags": [ "Account Management" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "emergency_credit": { "type": "number", "format": "float", "description": "Emergency credit amount" } }, "required": [ "emergency_credit" ] }, "example": { "emergency_credit": 100 } } } }, "responses": { "200": { "description": "Emergency credit set successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/rename": { "patch": { "summary": "Rename account", "description": "Renames an account\n- Allows the root user of an account to change the display name and internal name of their account\n- They must request a verification code to be able to finalize the process (see **/accounts/email-code**)\n- Once an account name is changed, all user sessions will be automatically revoked. Affected users will be notified about the change by email.", "operationId": "renameAccount", "tags": [ "Account Management" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "new_name": { "type": "string", "description": "New account name. Cannot clash with the name of another account on the platform" }, "email_code": { "type": "string", "description": "Email verification code. To obtain one, see **/accounts/email-code**" } }, "required": [ "new_name", "email_code" ] }, "example": { "new_name": "new-acme", "email_code": "123456" } } } }, "responses": { "200": { "description": "Account renamed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Account name already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts": { "post": { "summary": "Create account", "description": "- Creates a new account and a user if the provided email does not exist on the system.\n- Associates the user with the account with root privileges.\n- Sends an email to the user to verify their email address if the email is not already verified on the system.\n- A user can be a member of any number of accounts but they can be a root of at most one account.", "operationId": "createAccount", "tags": [ "Account Management" ], "x-resource-type": "service", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccountRequest" }, "example": { "name": "acme", "root_first_name": "John", "root_last_name": "Doe", "root_email": "admin@acme.com", "password": "SecureP@ssw0rd!", "country": "US", "company_name": "ACME Corporation", "address": "123 Main St, Anytown, USA", "website": "https://acme.com", "phone_number": "+1234567890" } } } }, "responses": { "200": { "description": "Account created successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "email_confirmed": { "type": "boolean" } } } } }, "example": { "data": { "email_confirmed": false, "description": "This flag confirms whether a new or an existing user is the root of the newly created account." } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update account", "description": "Updates account information.\n - An update can be made to any of the non-critical editable account properties only by root and admin users.\n - Critical account properties such as name, ID, and root email address cannot be changed with this request\n - To update *name*, see **/accounts/rename**\n- To update *root_email*, see **/accounts/request-email-address-change**", "operationId": "updateAccount", "tags": [ "Account Management" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAccountRequest" }, "example": { "country": "US", "company_name": "ACME Corporation Updated", "address": "456 New St, Anytown, USA", "website": "https://new-acme.com", "phone_number": "+9876543210", "region": "us-east-1", "provider": "aws", "cloud": true, "hub": false } } } }, "responses": { "200": { "description": "Account updated successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AccountPublicInfo" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/users": { "post": { "summary": "Create/Add user", "description": "Creates a new user and sends an invitation email if the user does not exist. Adds the new or existing user to the current account. If the user already exists and is already a member of the account, an error is returned \n - If the user already exists but isn't a member of the account, they are added without creating a new user record \n - The user won't be able to access the account until they complete the activation process by setting their password \n - For security, new users must set their own password via the activation link \n - The function schedules cleanup tasks to remove unactivated user accounts after a certain period of time (48 hours)", "operationId": "createUser", "tags": [ "User Management" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUserRequest" }, "example": { "first_name": "Jane", "last_name": "Smith", "email": "jane.smith@example.com", "role": "developer" } } } }, "responses": { "200": { "description": "User created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/account": { "delete": { "summary": "Delete account", "description": "Deletes the current account.\n- Allows the root user of an account to delete the entire account from the platform.\n- The root user must request a verification code to be able to finalize the process (see **/accounts/email-code**)\n- This is a significant operation that removes all account data and revokes access for all users associated with the account.\n- Users, however, are not deleted and they can continue to sign in to the platform if they are members of any other active accounts.\n - There is an option to delete the account immediately or in 14 days. If the latter, the deletion can be unscheduled (see **/accounts/cancel-account-deletion**)", "operationId": "deleteAccount", "tags": [ "Account Management" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "in_14_days": { "type": "boolean", "description": "Schedule deletion in 14 days. If this flag is set to true, the account data will not be deactivated immediately and will be accessible in the next 14 days. After this period is up, it will no longer be possible to log in with the account. If the root user wishes to recover it, they can contact a platform administrator up to a year after the account was deleted." }, "email_code": { "type": "string", "description": "Email verification code. To obtain one, see **/accounts/email-code**" } }, "required": [ "email_code" ] }, "example": { "in_14_days": true, "email_code": "123456" } } } }, "responses": { "200": { "description": "Account scheduled for deletion or deleted successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "message": { "type": "string" }, "deletion_date": { "type": "string", "format": "date-time" } } } } }, "example": { "data": { "message": "The accounts is going to be deleted on 2023-05-12T12:34:56Z", "deletion_date": "2023-05-12T12:34:56Z" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/cancel-account-deletion": { "post": { "summary": "Cancel account deletion", "description": "Cancels the deletion of an account.\n- Allows the root user of an account to reverse a scheduled account deletion if the current date is before *deletion_date*.", "operationId": "cancelAccountDeletion", "tags": [ "Account Management" ], "x-resource-type": "service", "responses": { "200": { "description": "Account deletion cancelled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Account not scheduled for deletion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/user": { "delete": { "summary": "Delete user", "description": "Deletes the current user", "operationId": "deleteUser", "tags": [ "User Management" ], "x-resource-type": "service", "parameters": [ { "name": "email_code", "in": "query", "description": "Email verification code. To obtain one, see **/accounts/email-code**", "schema": { "type": "string" } } ], "responses": { "200": { "description": "User deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Cannot delete root user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update user", "description": "Updates user information", "operationId": "updateUser", "tags": [ "User Management" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserRequest" }, "example": { "first_name": "John", "last_name": "Smith", "theme": "dark", "sound": true } } } }, "responses": { "200": { "description": "User updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/request-email-address-change": { "post": { "summary": "Request email address change", "description": "Initiates an email address change process", "operationId": "requestEmailAddressChange", "tags": [ "User Management" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "description": "Current password" }, "token": { "type": "string", "description": "MFA token (required if MFA is enabled)" }, "new_email": { "type": "string", "format": "email", "description": "New email address" } }, "required": [ "new_email" ] }, "example": { "password": "SecureP@ssw0rd!", "new_email": "new.email@example.com" } } } }, "responses": { "200": { "description": "Email change request initiated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/change-email-address-action": { "post": { "summary": "Complete email address change", "description": "Completes an email address change process", "operationId": "changeEmailAddressAction", "tags": [ "User Management" ], "x-resource-type": "service", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "Email change token" } }, "required": [ "token" ] }, "example": { "token": "abcdef123456" } } } }, "responses": { "200": { "description": "Email change action completed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/email-code": { "get": { "summary": "Get email verification code", "description": "Sends a verification code to the user's email", "operationId": "getEmailCode", "tags": [ "Authentication" ], "x-resource-type": "service", "responses": { "200": { "description": "Email code sent successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/import": { "post": { "summary": "Add import", "description": "Adds a new import to the account.\n- When an account adds an import, it's essentially creating a mapping that allows it to access and utilize resources (such as data streams or services) that are exported by another account. This request creates a trust relationship between accounts where one account can consume resources produced by another.", "operationId": "addImport", "tags": [ "Account Management" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportRequest" } } } }, "responses": { "200": { "description": "Import added successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Remove import", "description": "Removes an import from the account. Allows an account to discontinue the integration with resources from another account. This operation effectively severs the connection to external resources that an account was consuming.", "operationId": "removeImport", "tags": [ "Account Management" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Import name" } }, "required": [ "name" ] }, "example": { "name": "example-import" } } } }, "responses": { "200": { "description": "Import removed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/export": { "post": { "summary": "Add export", "description": "Adds a new export to the account.\n - Enables an account to make its internal resources (such as data streams or services) available to other accounts.", "operationId": "addExport", "tags": [ "Account Management" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportRequest" } } } }, "responses": { "200": { "description": "Export added successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Remove export", "description": "Removes an export from the account.\n - Allows an account to discontinue sharing a previously exported resource with other accounts. This operation effectively revokes external access to the specified resource.", "operationId": "removeExport", "tags": [ "Account Management" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Export name" } }, "required": [ "name" ] }, "example": { "name": "example-export" } } } }, "responses": { "200": { "description": "Export removed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/users/list": { "get": { "summary": "List users by account", "description": "Lists all users in the current account", "operationId": "listUsersByAccount", "tags": [ "User Management" ], "x-resource-type": "service", "responses": { "200": { "description": "Users retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UserInfo" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/list": { "get": { "summary": "List accounts by user", "description": "Lists all accounts for the current user", "operationId": "listAccountsByUser", "tags": [ "Account Management" ], "x-resource-type": "service", "responses": { "200": { "description": "Accounts retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "string" } } } }, "example": { "data": [ "acct_123456789", "acct_987654321" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/mesh-nodes": { "put": { "summary": "Update mesh nodes", "description": "Updates the number of mesh nodes and the available regions", "operationId": "updateMeshNodes", "tags": [ "Mesh Nodes" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "num_nodes": { "type": "number", "description": "has to be an odd number - 1, 2 or 5" }, "regions": { "type": "array", "items": { "type": "string", "description": "Availability regions. The number of specified regions cannot exceed the number of regions" } } }, "required": [ "num_nodes", "regions" ] }, "example": { "num_nodes": 3, "regions": [ "eu" ] } } } }, "responses": { "200": { "description": "Mesh nodes updated successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "Success message" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/begin-passkey-registration": { "post": { "summary": "Begin passkey registration", "description": "Initiates the passkey registration process", "operationId": "beginPasskeyRegistration", "tags": [ "Multi-Factor Authentication" ], "x-resource-type": "service", "responses": { "200": { "description": "Passkey registration initiated successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "WebAuthn registration options" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/complete-passkey-registration": { "post": { "summary": "Complete passkey registration", "description": "Completes the passkey registration process", "operationId": "completePasskeyRegistration", "tags": [ "Multi-Factor Authentication" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "credential": { "type": "object", "description": "WebAuthn credential" }, "credential_alias": { "type": "string", "description": "User-friendly name for the passkey" } }, "required": [ "credential", "credential_alias" ] } } } }, "responses": { "200": { "description": "Passkey registration completed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "passkey": { "$ref": "#/components/schemas/WebAuthCredentialAlias" }, "recovery_codes": { "type": "array", "items": { "type": "string" } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/begin-auth-with-passkey": { "post": { "tags": [ "Authentication", "Multi-Factor Authentication" ], "summary": "Begin passkey authentication", "description": "Initiates the WebAuthn passkey authentication flow. Returns a challenge for the client to sign with the user's passkey.", "operationId": "beginAuthWithPasskey", "x-resource-type": "service", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeginAuthWithPasskeyRequest" }, "example": { "email": "user@example.com", "account": "acme" } } } }, "responses": { "200": { "description": "Passkey authentication challenge", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CredentialAssertion" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "User not found or passkeys not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/passkey": { "delete": { "summary": "Remove passkey", "description": "Removes a specific passkey", "operationId": "removePasskey", "tags": [ "Multi-Factor Authentication" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Passkey ID (base64 encoded)" }, "email": { "type": "string", "format": "email", "description": "User email (optional, defaults to current user)" } }, "required": [ "id" ] }, "example": { "id": "cGFzc2tleV9pZA==", "email": "user@example.com" } } } }, "responses": { "200": { "description": "Passkey removed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Passkey not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/role": { "patch": { "summary": "Update user role", "description": "Updates a user's role in an account", "operationId": "updateRole", "tags": [ "User Management" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "User email" }, "role": { "type": "string", "enum": [ "admin", "developer", "monitor", "billing" ], "description": "New role" } }, "required": [ "email", "role" ] }, "example": { "email": "user@example.com", "role": "admin" } } } }, "responses": { "200": { "description": "Role updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/suspend-user": { "patch": { "summary": "Suspend user", "description": "Suspends or unsuspends a user in an account. Suspended users have no access to any of the resources and services associated with the account", "operationId": "suspendUser", "tags": [ "User Management" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "User email" }, "suspend": { "type": "boolean", "description": "Set true to suspend, false to unsuspend" } }, "required": [ "email", "suspend" ] }, "example": { "email": "user@example.com", "suspend": true } } } }, "responses": { "200": { "description": "User suspended/unsuspended successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/user-mfa-info": { "get": { "summary": "Get user MFA info", "description": "Retrieves MFA information for a user", "operationId": "getUserMfaInfo", "tags": [ "Multi-Factor Authentication" ], "x-resource-type": "service", "parameters": [ { "name": "email", "in": "query", "description": "User email (optional, defaults to current user)", "schema": { "type": "string", "format": "email" } } ], "responses": { "200": { "description": "MFA information retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/MfaInfo" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/user-login-data": { "get": { "summary": "Get user login data", "description": "Retrieves login data for the current user", "operationId": "getUserLoginData", "tags": [ "User Management" ], "x-resource-type": "service", "responses": { "200": { "description": "User login data retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/AccountPublicInfo" }, "user": { "type": "string", "format": "email" }, "user_id": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "role": { "type": "string" }, "mfa": { "$ref": "#/components/schemas/MfaInfo" }, "theme": { "type": "string" }, "sound": { "type": "boolean" }, "profile_image": { "$ref": "#/components/schemas/UserProfileImage" } }, "required": [ "account", "user", "user_id", "role" ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/token-validate": { "post": { "tags": [ "Authentication" ], "summary": "Validate token", "description": "Validates an authentication or refresh token.", "operationId": "validateToken", "x-resource-type": "service", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "Token to validate" } }, "required": [ "token" ] }, "example": { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } } } }, "responses": { "200": { "description": "Token validation result", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "boolean" } } }, "example": { "data": true } } } } } } }, "/accounts/api-creds": { "get": { "summary": "Get API credentials", "description": "Retrieves credentials for a specific API key. -Allows users to retrieve the full credential string that can be used with the CLI.", "operationId": "getApiCreds", "tags": [ "API Keys" ], "x-resource-type": "service", "parameters": [ { "name": "key", "in": "query", "description": "Full API key", "schema": { "type": "string" }, "required": true, "example": "ms-d28f9a3c5b6e7d4a1c8f9a3c5b6e7d4a" } ], "responses": { "200": { "description": "API credentials retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "string" } } }, "example": { "data": "-----BEGIN quiva.ai USER JWT-----\n[JWT TOKEN]\n------END quiva.ai USER JWT------\n************************* IMPORTANT *************************\nBKEY Seed printed below can be used to sign and prove identity.\nBKEYs are sensitive and should be treated as secrets.\n-----BEGIN USER BKEY SEED-----\n[BKEY SEED]\n------END USER BKEY SEED------\n*************************************************************" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "API key not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/auth-with-api-key": { "post": { "tags": [ "Authentication", "API Keys" ], "summary": "Authenticate with API key", "description": "Authenticates a user using an API key.", "operationId": "authWithApiKey", "x-resource-type": "service", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthWithApiKeyRequest" }, "example": { "api_key": "ms-d28f9a3c5b6e7d4a1c8f9a3c5b6e7d4a" } } } }, "responses": { "200": { "description": "Authentication successful", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AuthResponse" } } } } } }, "401": { "description": "Invalid or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Unauthorized" } } } } } } }, "/accounts/mfa-settings": { "patch": { "summary": "Update MFA settings", "description": "Updates multi-factor authentication settings for a user", "operationId": "updateMfaSettings", "tags": [ "Multi-Factor Authentication" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "totp_enabled": { "type": "boolean", "description": "Enable or disable TOTP (Time-based One-Time Password)" }, "passkey_enabled": { "type": "boolean", "description": "Enable or disable passkey authentication" } } }, "example": { "totp_enabled": true, "passkey_enabled": false } } } }, "responses": { "200": { "description": "MFA settings updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/session-tokens": { "get": { "summary": "Get session tokens", "description": "Retrieves all active session tokens for the current user", "operationId": "getSessionTokens", "tags": [ "Authentication" ], "x-resource-type": "service", "responses": { "200": { "description": "Session tokens retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "auth": { "type": "array", "items": { "$ref": "#/components/schemas/SessionObject" } }, "refresh": { "type": "array", "items": { "$ref": "#/components/schemas/RefreshTokenObject" } } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/auth-token": { "delete": { "summary": "Revoke auth token", "description": "Revokes a specific authentication token", "operationId": "revokeAuthToken", "tags": [ "Authentication" ], "x-resource-type": "service", "parameters": [ { "name": "token", "in": "query", "description": "Auth token to revoke", "schema": { "type": "string" }, "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "required": true } ], "responses": { "200": { "description": "Token revoked successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/refresh-token": { "delete": { "summary": "Revoke refresh token", "description": "Revokes a specific refresh token", "operationId": "revokeRefreshToken", "tags": [ "Authentication" ], "x-resource-type": "service", "parameters": [ { "name": "token", "in": "query", "description": "Refresh token to revoke", "schema": { "type": "string" }, "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "required": true } ], "responses": { "200": { "description": "Token revoked successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Authentication" ], "summary": "Refresh authentication token", "description": "Issues a new authentication token using a valid refresh token.", "operationId": "refreshToken", "x-resource-type": "service", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshTokenRequest" }, "example": { "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } } } }, "responses": { "200": { "description": "New authentication token issued", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AuthResponse" } } } } } }, "401": { "description": "Invalid or expired tokens", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Unauthorized" } } } } } } }, "/accounts/tokens": { "delete": { "summary": "Revoke all tokens", "description": "Revokes all tokens for a specific user", "operationId": "revokeTokens", "tags": [ "Authentication" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "User email" } }, "required": [ "email" ] }, "example": { "email": "user@example.com" } } } }, "responses": { "200": { "description": "Tokens revoked successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/confirm-email": { "post": { "summary": "Confirm email", "description": "Confirms a user's email address using a token or code\n - This process ensures that the person registering or using an email address actually has access to it. When a user registers a new account or adds a new email address to their profile, the system sends a confirmation email containing either a token (a long, randomly generated string) or a numerical code. This function processes the verification when the user clicks the confirmation link in the email or manually enters the provided code. It accepts either:\n- a) A token parameter, which is included in the confirmation link\n- b) A code parameter, which is a shorter numerical sequence that can be manually entered", "operationId": "confirmEmail", "tags": [ "Account Management" ], "x-resource-type": "service", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "Email confirmation token" }, "code": { "type": "string", "description": "Email confirmation code (alternative to token)" } }, "oneOf": [ { "required": [ "token" ] }, { "required": [ "code" ] } ] }, "example": { "token": "abcdef123456" } } } }, "responses": { "200": { "description": "Email confirmed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "account": { "type": "string" }, "email": { "type": "string", "format": "email" }, "account_id": { "type": "string" }, "user_id": { "type": "string" } } } } }, "example": { "data": { "account": "acme", "email": "user@example.com", "account_id": "acct_123456789", "user_id": "usr_123456789" } } } } }, "400": { "description": "Invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/resend-confirmation": { "post": { "summary": "Resend email confirmation", "description": "Resends email confirmation link to user. Always returns success for security reasons.", "tags": [ "Account Management" ], "operationId": "resendAccountConfirmation", "security": [], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "description": "Email address to resend confirmation to", "example": "user@example.com" } } } } } }, "responses": { "200": { "description": "Confirmation email sent (always returns success)", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "message": { "type": "string", "example": "Please check your inbox. If a root account is associated with this email and remains unconfirmed, a reconfirmation message should have been sent." } } } } } } } } } } }, "/accounts/submit-contact-form": { "post": { "summary": "Submit contact form", "description": "Submits a contact form\n- The function provides a structured mechanism for authenticated users to send inquiries, feedback, or support requests directly to the quiva.ai team or specific team members. This communication channel is integrated within the platform, allowing users to reach out for assistance without leaving the application environment.", "operationId": "submitContactForm", "tags": [ "Account Management" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactRequest" }, "example": { "to_email": "support@example.com", "subject": "Billing question", "location": "Account settings", "message": "I have a question about my billing cycle.", "phone_number": "+1234567890", "preferred_contact_method": "email" } } } }, "responses": { "200": { "description": "Contact form submitted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/complete-auth-with-passkey": { "post": { "tags": [ "Authentication", "Multi-Factor Authentication" ], "summary": "Complete passkey authentication", "description": "Completes the WebAuthn passkey authentication flow by verifying the signed challenge.", "operationId": "completeAuthWithPasskey", "x-resource-type": "service", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteAuthWithPasskeyRequest" } } } }, "responses": { "200": { "description": "Authentication successful", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AuthResponse" } } } } } }, "401": { "description": "Invalid credential or verification failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/all-passkeys": { "delete": { "summary": "Remove all passkeys", "description": "Removes all passkeys for a user", "operationId": "removeAllPasskeys", "tags": [ "Multi-Factor Authentication" ], "x-resource-type": "service", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "User email (optional, defaults to current user)" } } }, "example": { "email": "user@example.com" } } } }, "responses": { "200": { "description": "All passkeys removed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/payment/webhook": { "post": { "summary": "Process payment webhook", "description": "Processes payment webhooks from Stripe", "operationId": "processPaymentWebhook", "tags": [ "Payment" ], "x-resource-type": "service", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Stripe webhook event object" } } } }, "responses": { "200": { "description": "Webhook processed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/payment/products": { "get": { "summary": "Get products", "description": "Retrieves all available products", "operationId": "getProducts", "tags": [ "Payment" ], "x-resource-type": "service", "responses": { "200": { "description": "Products retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StripeProduct" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/payment/prices": { "get": { "summary": "Get prices", "description": "Retrieves all available prices", "operationId": "getPrices", "tags": [ "Payment" ], "x-resource-type": "service", "responses": { "200": { "description": "Prices retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StripePrice" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/payment/checkout-url": { "post": { "summary": "Get checkout URL", "description": "Generates a Stripe checkout URL for subscription", "operationId": "getCheckoutUrl", "tags": [ "Payment" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutURLRequest" }, "example": { "base_subscription": "price_1234567890", "addons": [ { "id": "price_0987654321", "type": "addon", "quantity": 2 } ] } } } }, "responses": { "200": { "description": "Checkout URL generated successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "string", "format": "uri" } } }, "example": { "data": "https://checkout.stripe.com/c/pay/cs_test_1234567890" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/payment/dashboard-url": { "get": { "summary": "Get dashboard URL", "description": "Generates a Stripe customer portal URL", "operationId": "getDashboardUrl", "tags": [ "Payment" ], "x-resource-type": "service", "responses": { "200": { "description": "Dashboard URL generated successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "string", "format": "uri" } } }, "example": { "data": "https://billing.stripe.com/p/session/live_1234567890" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/payment/subscription-items": { "get": { "summary": "Get subscription items", "description": "Retrieves all items in the current subscription", "operationId": "getSubscriptionItems", "tags": [ "Payment" ], "x-resource-type": "service", "responses": { "200": { "description": "Subscription items retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "has_default_payment_method": { "type": "boolean" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionItem" } } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No subscription found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/payment/subscription": { "get": { "summary": "Get subscription", "description": "Retrieves the current subscription", "operationId": "getSubscription", "tags": [ "Payment" ], "x-resource-type": "service", "responses": { "200": { "description": "Subscription retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Stripe subscription object" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No subscription found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update subscription", "description": "Updates the current subscription", "operationId": "updateSubscription", "tags": [ "Payment" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SubItem" } } }, "required": [ "items" ] }, "example": { "items": [ { "id": "si_1234567890", "quantity": 2 } ] } } } }, "responses": { "200": { "description": "Subscription updated successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Stripe subscription object" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No subscription found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Cancel subscription", "description": "Cancels the current subscription", "operationId": "cancelSubscription", "tags": [ "Payment" ], "x-resource-type": "service", "responses": { "200": { "description": "Subscription cancelled successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Stripe subscription object" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No subscription found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/payment/free-subscription": { "post": { "summary": "Create free subscription", "description": "Creates a free subscription", "operationId": "createFreeSubscription", "tags": [ "Payment" ], "x-resource-type": "service", "responses": { "200": { "description": "Free subscription created successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Stripe subscription object" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/oauth/token": { "post": { "summary": "Mint an integration token", "tags": [ "Authentication" ], "security": [], "description": "Public. Cache the token for `expires_in`: every mint creates a session. The reply is not wrapped in `data`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthTokenRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/OAuthTokenRequest" } } } }, "responses": { "200": { "description": "Token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthTokenResponse" } } } }, "400": { "description": "`invalid_request`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "401": { "description": "`invalid_client`. The text is the same for every cause.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "503": { "description": "`temporarily_unavailable`. Retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } } } } }, "/accounts/integrations": { "post": { "summary": "Create an integration", "tags": [ "Integrations" ], "description": "Account root or admin. Returns the first `client_secret` once.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateIntegrationRequest" } } } }, "responses": { "200": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/IntegrationCreated" } }, "required": [ "data" ] } } } }, "400": { "description": "Bad request. `code` names the cause.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "401": { "description": "Not authenticated, the caller is not a root or admin user, or the integration token was revoked (`token_revoked`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "403": { "description": "Forbidden: `scope_denied`, or `integration_not_allowed` for an integration bearer outside workspaces.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "503": { "description": "A backing store is unreachable. Retry. `code` is `storage_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } } } }, "get": { "summary": "List integrations", "tags": [ "Integrations" ], "description": "Deleted records are included with `deleted_at`.", "responses": { "200": { "description": "Integrations, oldest first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Integration" } } }, "required": [ "data" ] } } } }, "401": { "description": "Not authenticated, the caller is not a root or admin user, or the integration token was revoked (`token_revoked`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "403": { "description": "Forbidden: `scope_denied`, or `integration_not_allowed` for an integration bearer outside workspaces.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "503": { "description": "A backing store is unreachable. Retry. `code` is `storage_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } } } } }, "/accounts/integrations/{id}": { "get": { "summary": "Read an integration", "tags": [ "Integrations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Integration id (`I` + 12 hex).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The integration. Never carries a secret or hash.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Integration" } }, "required": [ "data" ] } } } }, "401": { "description": "Not authenticated, the caller is not a root or admin user, or the integration token was revoked (`token_revoked`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "403": { "description": "Forbidden: `scope_denied`, or `integration_not_allowed` for an integration bearer outside workspaces.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "503": { "description": "A backing store is unreachable. Retry. `code` is `storage_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } } } }, "patch": { "summary": "Update or disable an integration", "tags": [ "Integrations" ], "description": "A scope or `disabled` change bumps the token epoch and prunes subscriptions that cover spaces no longer readable.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Integration id (`I` + 12 hex).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateIntegrationRequest" } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Integration" } }, "required": [ "data" ] } } } }, "400": { "description": "Bad request. `code` names the cause.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "401": { "description": "Not authenticated, the caller is not a root or admin user, or the integration token was revoked (`token_revoked`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "403": { "description": "Forbidden: `scope_denied`, or `integration_not_allowed` for an integration bearer outside workspaces.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "503": { "description": "A backing store is unreachable. Retry. `code` is `storage_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } } } }, "delete": { "summary": "Delete an integration", "tags": [ "Integrations" ], "description": "Keeps the record for attribution. Revokes every secret, disables it, drops its sessions and pauses its subscriptions.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Integration id (`I` + 12 hex).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The deleted record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Integration" } }, "required": [ "data" ] } } } }, "401": { "description": "Not authenticated, the caller is not a root or admin user, or the integration token was revoked (`token_revoked`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "403": { "description": "Forbidden: `scope_denied`, or `integration_not_allowed` for an integration bearer outside workspaces.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "503": { "description": "A backing store is unreachable. Retry. `code` is `storage_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } } } } }, "/accounts/integrations/{id}/secrets": { "post": { "summary": "Rotate the client secret", "tags": [ "Integrations" ], "description": "Issues a new secret, shown once. The previous live secret retires after `grace_seconds`. At most two secrets are live.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Integration id (`I` + 12 hex).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotateSecretRequest" } } } }, "responses": { "200": { "description": "Rotated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SecretRotated" } }, "required": [ "data" ] } } } }, "400": { "description": "Bad request. `code` names the cause.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "401": { "description": "Not authenticated, the caller is not a root or admin user, or the integration token was revoked (`token_revoked`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "403": { "description": "Forbidden: `scope_denied`, or `integration_not_allowed` for an integration bearer outside workspaces.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "409": { "description": "`two_secrets_live`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "503": { "description": "A backing store is unreachable. Retry. `code` is `storage_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } } } } }, "/accounts/integrations/{id}/secrets/{secret_id}": { "delete": { "summary": "Revoke a client secret", "tags": [ "Integrations" ], "description": "Immediate. Bumps the token epoch and drops the integration's sessions.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Integration id (`I` + 12 hex).", "schema": { "type": "string" } }, { "name": "secret_id", "in": "path", "required": true, "description": "Secret id (`S` + 12 hex).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The integration.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Integration" } }, "required": [ "data" ] } } } }, "401": { "description": "Not authenticated, the caller is not a root or admin user, or the integration token was revoked (`token_revoked`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "403": { "description": "Forbidden: `scope_denied`, or `integration_not_allowed` for an integration bearer outside workspaces.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "503": { "description": "A backing store is unreachable. Retry. `code` is `storage_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } } } } }, "/accounts/integrations/{id}/subscriptions": { "post": { "summary": "Create a webhook subscription", "tags": [ "Task Subscriptions" ], "description": "Up to 25 per integration. `400 bad_url`, `400 space_not_in_scope`, `409 subscription_limit`, `409 integration_disabled`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Integration id (`I` + 12 hex).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSubscriptionRequest" } } } }, "responses": { "200": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SubscriptionCreated" } }, "required": [ "data" ] } } } }, "400": { "description": "Bad request. `code` names the cause.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "401": { "description": "Not authenticated, the caller is not a root or admin user, or the integration token was revoked (`token_revoked`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "403": { "description": "Forbidden: `scope_denied`, or `integration_not_allowed` for an integration bearer outside workspaces.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "409": { "description": "Conflict. `code` names the cause.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "503": { "description": "A backing store is unreachable. Retry. `code` is `storage_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } } } }, "get": { "summary": "List webhook subscriptions", "tags": [ "Task Subscriptions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Integration id (`I` + 12 hex).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Subscriptions, oldest first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TaskSubscription" } } }, "required": [ "data" ] } } } }, "401": { "description": "Not authenticated, the caller is not a root or admin user, or the integration token was revoked (`token_revoked`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "403": { "description": "Forbidden: `scope_denied`, or `integration_not_allowed` for an integration bearer outside workspaces.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "503": { "description": "A backing store is unreachable. Retry. `code` is `storage_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } } } } }, "/accounts/integrations/{id}/subscriptions/{sid}": { "patch": { "summary": "Update, resume or rotate a subscription", "tags": [ "Task Subscriptions" ], "description": "`paused: false` resumes and answers `409 integration_disabled` while the integration is disabled.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Integration id (`I` + 12 hex).", "schema": { "type": "string" } }, { "name": "sid", "in": "path", "required": true, "description": "Subscription id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSubscriptionRequest" } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SubscriptionUpdated" } }, "required": [ "data" ] } } } }, "400": { "description": "Bad request. `code` names the cause.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "401": { "description": "Not authenticated, the caller is not a root or admin user, or the integration token was revoked (`token_revoked`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "403": { "description": "Forbidden: `scope_denied`, or `integration_not_allowed` for an integration bearer outside workspaces.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "409": { "description": "Conflict. `code` names the cause.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "503": { "description": "A backing store is unreachable. Retry. `code` is `storage_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } } } }, "delete": { "summary": "Delete a subscription", "tags": [ "Task Subscriptions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Integration id (`I` + 12 hex).", "schema": { "type": "string" } }, { "name": "sid", "in": "path", "required": true, "description": "Subscription id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } } } }, "required": [ "data" ] } } } }, "401": { "description": "Not authenticated, the caller is not a root or admin user, or the integration token was revoked (`token_revoked`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "403": { "description": "Forbidden: `scope_denied`, or `integration_not_allowed` for an integration bearer outside workspaces.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "503": { "description": "A backing store is unreachable. Retry. `code` is `storage_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } } } } }, "/accounts/integrations/{id}/subscriptions/{sid}/replay": { "post": { "summary": "Replay events or send a test event", "tags": [ "Task Subscriptions" ], "description": "Queued in the background; read the outcome in the delivery log. Replay covers `from < sequence <= to`, ignores delivered markers, keeps kind and echo filters, and is capped at 10 000 events. A paused subscription refuses replay (`409 subscription_paused`) but accepts a test.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Integration id (`I` + 12 hex).", "schema": { "type": "string" } }, { "name": "sid", "in": "path", "required": true, "description": "Subscription id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplayRequest" } } } }, "responses": { "202": { "description": "Accepted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ReplayAccepted" } }, "required": [ "data" ] } } } }, "400": { "description": "Bad request. `code` names the cause.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "401": { "description": "Not authenticated, the caller is not a root or admin user, or the integration token was revoked (`token_revoked`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "403": { "description": "Forbidden: `scope_denied`, or `integration_not_allowed` for an integration bearer outside workspaces.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "409": { "description": "Conflict. `code` names the cause.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "503": { "description": "A backing store is unreachable. Retry. `code` is `storage_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } } } } }, "/accounts/integrations/{id}/subscriptions/{sid}/deliveries": { "get": { "summary": "Read the delivery log", "tags": [ "Task Subscriptions" ], "description": "Newest first. Rows are kept 30 days.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Integration id (`I` + 12 hex).", "schema": { "type": "string" } }, { "name": "sid", "in": "path", "required": true, "description": "Subscription id.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` from the previous page.", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, { "name": "limit", "in": "query", "required": false, "description": "1 to 200. Default 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "A page.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DeliveryPage" } }, "required": [ "data" ] } } } }, "400": { "description": "Bad request. `code` names the cause.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "401": { "description": "Not authenticated, the caller is not a root or admin user, or the integration token was revoked (`token_revoked`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "403": { "description": "Forbidden: `scope_denied`, or `integration_not_allowed` for an integration bearer outside workspaces.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } }, "503": { "description": "A backing store is unreachable. Retry. `code` is `storage_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationError" } } } } } } }, "/accounts/auth-select-account": { "post": { "summary": "Finish sign-in on the chosen account", "description": "Public. Completes an email-only sign-in that returned `select_account`. The token is single-use and every refusal is the same 401, so a token cannot be used to probe memberships. The response is `AuthResponse`, or `MfaRequiredResponse` when the account's user has TOTP on and the device is not remembered.", "operationId": "authSelectAccount", "x-resource-type": "service", "tags": [ "Authentication" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthSelectAccountRequest" }, "example": { "token": "select_token_abcdef1234567890", "account_id": "acct_12345" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/AuthResponse" }, { "$ref": "#/components/schemas/MfaRequiredResponse" } ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/slug": { "patch": { "summary": "Change the sign-in address (slug)", "description": "Root user only. Changes the account's sign-in slug, which is also its sign-in subdomain, and publishes its DNS record. The caller confirms with an email code (see `GET /accounts/email-code`), exactly as for rename. The old slug stays as an alias (up to 3). The owner is notified by email. A refused change keeps the code, so it can be resubmitted.", "operationId": "changeAccountSlug", "x-resource-type": "service", "tags": [ "Account Management" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeAccountSlugRequest" }, "example": { "slug": "acme", "email_code": "123456" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AccountSlugResponse" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The slug is taken, or the account already holds 3 previous slugs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/client-branding": { "post": { "summary": "Get sign-in branding", "description": "Public. Returns an account's brand for its sign-in page. An unknown account is a 200 with only `account` set. Rate limited per key.", "operationId": "getClientBranding", "x-resource-type": "service", "tags": [ "Branding" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientBrandingRequest" }, "example": { "account": "acme" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ClientBranding" } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/favicon-dark": { "post": { "summary": "Upload the dark-mode favicon", "description": "Root and administrators. Sets the favicon shown in dark mode, from a file already uploaded to the account's profile-image storage. Accepted extensions match the light favicon. The stored name is reduced to URL-safe characters and prefixed `dark_`.", "operationId": "uploadFaviconDark", "x-resource-type": "service", "tags": [ "Branding" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageKeyRequest" }, "example": { "key": "icon-white.png" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ImageKeyResponse" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Remove the dark-mode favicon", "description": "Root and administrators. Clears the dark-mode favicon so the light one is used in both themes.", "operationId": "deleteFaviconDark", "x-resource-type": "service", "tags": [ "Branding" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/record-image": { "post": { "summary": "Publish a record image", "description": "Staff users (not clients). Copies an image from the account's workspace storage into the public record-image store and returns its key. Used for record images and avatars.", "operationId": "uploadRecordImage", "x-resource-type": "service", "tags": [ "Branding" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageKeyRequest" }, "example": { "key": "uploads/photo.png" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ImageKeyResponse" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete a record image", "description": "Staff users (not clients). Deletes a published record image. A missing image is not an error.", "operationId": "deleteRecordImage", "x-resource-type": "service", "tags": [ "Branding" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageKeyRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ImageKeyResponse" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/send-client-sign-in": { "post": { "summary": "Email a client a sign-in link", "description": "Root and administrators. Emails one client of the caller's account a single-use sign-in link inside a published email template, so a flow can send a branded email the client opens in one click. The template must carry the `{sign_in_url}` tag. The link is a credential: it is never returned and never logged. 4xx when the client or template is missing or the template has unresolved tags.", "operationId": "sendClientSignIn", "x-resource-type": "service", "tags": [ "Authentication" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendClientSignInRequest" }, "example": { "email": "client@example.com", "template_key": "client-sign-in", "data": { "first_name": "Sam" } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/email-templates": { "get": { "summary": "List email templates", "description": "Lists the account's email templates, without their bodies. `published` also returns templates that hold a published version and a draft.", "operationId": "listEmailTemplates", "x-resource-type": "service", "tags": [ "Email Templates" ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Filter by status", "schema": { "type": "string", "enum": [ "draft", "published", "published_with_draft" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EmailTemplateSummary" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/email-template": { "get": { "summary": "Get an email template", "description": "Returns one template with its draft and published versions.", "operationId": "getEmailTemplate", "x-resource-type": "service", "tags": [ "Email Templates" ], "parameters": [ { "name": "key", "in": "query", "required": true, "description": "Template key", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EmailTemplate" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a template or replace its draft", "description": "Any member can write a draft. The published version is untouched until it is published. `key` is immutable after creation.", "operationId": "saveEmailTemplate", "x-resource-type": "service", "tags": [ "Email Templates" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveEmailTemplateRequest" }, "example": { "key": "welcome", "name": "Welcome", "subject": "Welcome, {first_name}", "html": "

Hello {first_name}

", "sample_data": { "first_name": "Sam" } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EmailTemplate" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete an email template", "description": "Root and administrators.", "operationId": "deleteEmailTemplate", "x-resource-type": "service", "tags": [ "Email Templates" ], "parameters": [ { "name": "key", "in": "query", "required": true, "description": "Template key", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "key": { "type": "string" } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/email-template-publish": { "post": { "summary": "Publish the draft", "description": "Root and administrators. Makes the draft the published version that sends render.", "operationId": "publishEmailTemplate", "x-resource-type": "service", "tags": [ "Email Templates" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailTemplateKeyRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EmailTemplate" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/email-template-discard": { "post": { "summary": "Discard the draft", "description": "Root and administrators. Drops the draft and keeps the published version.", "operationId": "discardEmailTemplateDraft", "x-resource-type": "service", "tags": [ "Email Templates" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailTemplateKeyRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EmailTemplate" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/email-template-render": { "post": { "summary": "Render a template", "description": "Renders one version the way a send would. A send refuses on unresolved tags.", "operationId": "renderEmailTemplate", "x-resource-type": "service", "tags": [ "Email Templates" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenderEmailTemplateRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/RenderedEmailTemplate" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/email-template-attachment": { "post": { "summary": "Attach a file", "description": "Adds a file from storage to the draft. The list is frozen when the draft is published.", "operationId": "addEmailTemplateAttachment", "x-resource-type": "service", "tags": [ "Email Templates" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailTemplateAttachmentRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EmailTemplate" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/email-template-attachment-remove": { "post": { "summary": "Remove an attachment", "description": "Removes the attached file whose key is `file_key` from the draft.", "operationId": "removeEmailTemplateAttachment", "x-resource-type": "service", "tags": [ "Email Templates" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailTemplateAttachmentRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EmailTemplate" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/request-client-magic-link": { "post": { "summary": "Request a client sign-in link", "description": "Regenerates a client's magic link and 6-digit code and re-sends the invitation email. Public. Always answers success so that account names and emails cannot be enumerated.", "operationId": "requestClientMagicLink", "tags": [ "Client Access" ], "x-resource-type": "service", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address of the client user" }, "account": { "type": "string", "description": "Account name the client belongs to" } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Always a success message" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/auth-with-magic-link": { "post": { "summary": "Sign in with a magic link or code", "description": "Signs a client in with a single-use magic-link `token`, or with the 6-digit `code` together with `email` and `account`. Repeated wrong codes lock the sign-in until an admin clears it (see **/accounts/clear-client-signin-lock**).", "operationId": "authWithMagicLink", "tags": [ "Client Access" ], "x-resource-type": "service", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "Single-use token from the link" }, "code": { "type": "string", "description": "6-digit code from the invitation email" }, "email": { "type": "string", "description": "Email address of the client user" }, "account": { "type": "string", "description": "Account name; required with `code`" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Sign-in code locked after too many attempts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/send-client-invite": { "post": { "summary": "Send a client invitation email", "description": "Sends a client user's invitation email with a fresh sign-in link. Admin or root only. The user must hold the client role in the caller's account.", "operationId": "sendClientInvite", "tags": [ "Client Access" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address of the client user" } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Caller is not an admin or root", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/clear-client-signin-lock": { "post": { "summary": "Clear a client sign-in lock", "description": "Clears the failed sign-in code attempts for a client once the lock has tripped. Admin or root only.", "operationId": "clearClientSigninLock", "tags": [ "Client Access" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address of the client user" } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Caller is not an admin or root", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/vertical-updates": { "get": { "summary": "List vertical template updates", "description": "For each stamped template of the account's verticals, reports whether the copy is current, can take the update safely, or has been edited. Read only. Admin or root. Apply updates with `reapply_verticals` on **PATCH /accounts**.", "operationId": "getVerticalUpdates", "tags": [ "Account Management" ], "x-resource-type": "service", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "updates": { "type": "array", "items": { "type": "object" } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Caller is not an admin or root", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/export-activation": { "post": { "summary": "Mint an export activation token", "description": "Mints the activation token that lets one named account import a token-required export of the caller's account. Admin or root only. The response carries the fields the importing side must echo back on its import.", "operationId": "mintExportActivation", "tags": [ "Account Management" ], "x-resource-type": "service", "x-path-derived": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account that will import the export" }, "export_name": { "type": "string", "description": "Name of a token-required export" }, "expires_in_seconds": { "type": "integer", "description": "Optional token lifetime" } }, "required": [ "account_id", "export_name" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "token": { "type": "string", "description": "Activation token" }, "export_name": { "type": "string", "description": "Export name" }, "subject": { "type": "string", "description": "Subject to echo on import" }, "import_type": { "type": "string", "description": "Import type to echo on import" }, "account": { "type": "string", "description": "Issuing account" }, "target_account": { "type": "string", "description": "Importing account" }, "expires_at": { "type": "integer", "description": "Unix expiry" } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Caller is not an admin or root", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/fontawesome/token": { "post": { "summary": "Get an icon font access token", "description": "Returns a short-lived access token for the icon font service, used by the app to load icons. Any signed-in user.", "operationId": "getFontawesomeToken", "tags": [ "Branding" ], "x-resource-type": "service", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "access_token": { "type": "string", "description": "Access token" }, "expires_in": { "type": "integer", "description": "Seconds until expiry" } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/document-theme": { "get": { "summary": "Get the document theme", "description": "Returns the resolved document theme for the caller's own account, including the logo as a data URI when one is set. The account comes from the session; it cannot be asked for.", "operationId": "getDocumentTheme", "tags": [ "Document Branding" ], "x-resource-type": "service", "x-path-derived": true, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "logo_data_uri": { "type": "string", "description": "Logo as a data URI, empty when no logo is set" } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/document-logo": { "post": { "summary": "Set the document logo", "description": "Files the account's document logo. Upload the image to the account's profile-images storage first, then name its key here. Admin or root only.", "operationId": "uploadDocumentLogo", "tags": [ "Document Branding" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageKeyRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ImageKeyResponse" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Caller is not an admin or root", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Remove the document logo", "description": "Clears the document logo and removes the stored object. Admin or root only.", "operationId": "deleteDocumentLogo", "tags": [ "Document Branding" ], "x-resource-type": "service", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Caller is not an admin or root", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/assign-resources": { "post": { "summary": "Assign resources to a user", "description": "Grants a member of the caller's account access to resources such as spaces, with optional read, write, execute and delete permissions. Admin or root only.", "operationId": "assignUserResources", "tags": [ "Resource Access" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string", "description": "Member to grant" }, "resources": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Resource type, for example `space`" }, "id": { "type": "string", "description": "Resource id" }, "read": { "type": "boolean" }, "write": { "type": "boolean" }, "execute": { "type": "boolean" }, "delete": { "type": "boolean" } }, "required": [ "type", "id" ] } } }, "required": [ "user_id", "resources" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Caller is not an admin or root", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/unassign-resources": { "post": { "summary": "Remove resource assignments from a user", "description": "Removes a member's grants on the named resources. Admin or root only.", "operationId": "unassignUserResources", "tags": [ "Resource Access" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string", "description": "Member to change" }, "resources": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Resource type" }, "id": { "type": "string", "description": "Resource id" } }, "required": [ "type", "id" ] } } }, "required": [ "user_id", "resources" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Caller is not an admin or root", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/assigned-resources": { "get": { "summary": "List resources assigned to a user", "description": "Lists the resources assigned to a user. Members can read their own; an admin can name any member of the account.", "operationId": "listAssignedResources", "tags": [ "Resource Access" ], "x-resource-type": "service", "parameters": [ { "name": "user_id", "in": "query", "required": false, "description": "User to list; defaults to the caller", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "Only this resource type", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Resource type, for example `space`" }, "id": { "type": "string", "description": "Resource id" }, "read": { "type": "boolean" }, "write": { "type": "boolean" }, "execute": { "type": "boolean" }, "delete": { "type": "boolean" } }, "required": [ "type", "id" ] } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/sync-packages": { "get": { "summary": "List sync packages", "description": "Lists the sync packages available to the account and the account's installs.", "operationId": "listSyncPackages", "tags": [ "Sync Packages" ], "x-resource-type": "service", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "packages": { "type": "array", "items": { "type": "object" } }, "installs": { "type": "array", "items": { "type": "object" } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/sync-packages/installs": { "get": { "summary": "List sync package installs", "description": "Lists the account's sync package installs.", "operationId": "listSyncPackageInstalls", "tags": [ "Sync Packages" ], "x-resource-type": "service", "x-path-derived": true, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "installs": { "type": "array", "items": { "type": "object" } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/sync-packages/install": { "post": { "summary": "Install a sync package", "description": "Installs a package into a space. Sending only `install_id` repairs an existing install with its stored values.", "operationId": "installSyncPackage", "tags": [ "Sync Packages" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "package": { "type": "string", "description": "Package key" }, "instance": { "type": "string", "description": "Instance name" }, "space_id": { "type": "string", "description": "Target space" }, "params": { "type": "object", "description": "Package parameters" }, "install_id": { "type": "string", "description": "Existing install to repair" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "install": { "type": "object" } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/sync-packages/upgrade": { "post": { "summary": "Upgrade a sync package install", "description": "Upgrades an install to the current package version.", "operationId": "upgradeSyncPackage", "tags": [ "Sync Packages" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "install_id": { "type": "string", "description": "Install to upgrade" }, "params": { "type": "object", "description": "Package parameters" } }, "required": [ "install_id" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "install": { "type": "object" } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/sync-packages/uninstall": { "post": { "summary": "Uninstall a sync package", "description": "Removes an install, and with `remove_connection` its connection.", "operationId": "uninstallSyncPackage", "tags": [ "Sync Packages" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "install_id": { "type": "string", "description": "Install to remove" }, "remove_connection": { "type": "boolean" } }, "required": [ "install_id" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "install": { "type": "object" } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/terms/documents": { "get": { "summary": "List terms documents", "description": "Returns the platform, provider and account layers of terms documents and the provider bindings. Admin or root.", "operationId": "listTermsDocuments", "tags": [ "Terms" ], "x-resource-type": "service", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Caller is not an admin or root", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/terms/document": { "post": { "summary": "Create a terms document draft", "description": "Starts a draft. Nothing is shown to anyone until it is published. Admin or root.", "operationId": "createTermsDocument", "tags": [ "Terms" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Document id" }, "kind": { "type": "string", "description": "Document kind" }, "title": { "type": "string", "description": "Title" }, "body": { "type": "string", "description": "Document text" }, "show": { "type": "object", "description": "Rules for when the document is shown" } }, "required": [ "id", "kind", "title" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Caller is not an admin or root", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "summary": "Update a terms document draft", "description": "Edits a draft. `revision` must match the revision read with the document; a mismatch answers 409 instead of merging. Admin or root.", "operationId": "updateTermsDocument", "tags": [ "Terms" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Document id" }, "kind": { "type": "string", "description": "Document kind" }, "title": { "type": "string", "description": "Title" }, "body": { "type": "string", "description": "Document text" }, "show": { "type": "object" }, "revision": { "type": "integer", "description": "Revision the edit is based on" } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Caller is not an admin or root", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Archive a terms document", "description": "Soft archive: prompting stops, versions stay readable and the acceptance log is untouched. Admin or root.", "operationId": "archiveTermsDocument", "tags": [ "Terms" ], "x-resource-type": "service", "parameters": [ { "name": "document_id", "in": "query", "required": true, "description": "Document to archive", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Caller is not an admin or root", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/terms/document/publish": { "post": { "summary": "Publish a terms document", "description": "Publishes the draft as the next version. Admin or root.", "operationId": "publishTermsDocument", "tags": [ "Terms" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "document_id": { "type": "string", "description": "Document id" }, "change_note": { "type": "string", "description": "What changed" } }, "required": [ "document_id" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "document": { "type": "object" }, "version": { "type": "object" } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Caller is not an admin or root", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/terms/document/versions": { "get": { "summary": "List terms document versions", "description": "Lists the published versions of one document. Admin or root.", "operationId": "listTermsDocumentVersions", "tags": [ "Terms" ], "x-resource-type": "service", "parameters": [ { "name": "document_id", "in": "query", "required": true, "description": "Document id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "versions": { "type": "array", "items": { "type": "object" } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Caller is not an admin or root", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/terms/version": { "get": { "summary": "Get a terms version", "description": "Returns one version of a document; the latest when `version` is omitted.", "operationId": "getTermsVersion", "tags": [ "Terms" ], "x-resource-type": "service", "parameters": [ { "name": "layer", "in": "query", "required": true, "description": "Layer: platform, provider or account", "schema": { "type": "string" } }, { "name": "document_id", "in": "query", "required": true, "description": "Document id", "schema": { "type": "string" } }, { "name": "version", "in": "query", "required": false, "description": "Version number", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/terms/provider": { "put": { "summary": "Enable or disable a provider", "description": "Enables or disables a provider and records the organisation's acceptance. Enabling requires `accepted_version` to equal the current version. Admin or root.", "operationId": "setTermsProvider", "tags": [ "Terms" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "provider_id": { "type": "string", "description": "Provider id" }, "enabled": { "type": "boolean" }, "record_config_ids": { "type": "array", "items": { "type": "string" } }, "accepted_version": { "type": "integer", "description": "Provider terms version accepted" } }, "required": [ "provider_id", "enabled" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Caller is not an admin or root", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/terms/provider-status": { "get": { "summary": "Get provider terms status", "description": "Whether a provider is enabled for the account and which version was accepted.", "operationId": "getTermsProviderStatus", "tags": [ "Terms" ], "x-resource-type": "service", "parameters": [ { "name": "provider_id", "in": "query", "required": true, "description": "Provider id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/terms/pending": { "get": { "summary": "List terms the caller must accept", "description": "Returns what the caller must accept now. With `context=record_config:` it answers the assessment question instead of the sign-in one. Self only, unless an admin names a member of their own account.", "operationId": "getTermsPending", "tags": [ "Terms" ], "x-resource-type": "service", "parameters": [ { "name": "context", "in": "query", "required": false, "description": "Optional `record_config:`", "schema": { "type": "string" } }, { "name": "user_id", "in": "query", "required": false, "description": "Member to check; admin only", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/terms/accept": { "post": { "summary": "Accept terms", "description": "Records an acceptance. A stale reference answers 409 with the current pending list, so consent is never logged against a document nobody saw.", "operationId": "acceptTerms", "tags": [ "Terms" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "acceptances": { "type": "array", "items": { "type": "object" } }, "context": { "type": "string", "description": "Acceptance context" } }, "required": [ "acceptances" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "accepted": { "type": "array", "items": { "type": "object" } }, "pending": { "type": "array", "items": { "type": "object" } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A referenced document is no longer current", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/terms/pending-for-signin": { "post": { "summary": "Preview terms for a sign-in link", "description": "Shows what a sign-in link's holder will be asked to accept, without spending the link. Public, and reveals nothing the holder does not already have. A wrong code counts as an attempt.", "operationId": "getTermsPendingForSignin", "tags": [ "Terms" ], "x-resource-type": "service", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "Magic-link token" }, "code": { "type": "string", "description": "6-digit code" }, "email": { "type": "string", "description": "Email address of the client user" }, "account": { "type": "string", "description": "Account name" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/terms/acceptances": { "get": { "summary": "Export the acceptance log", "description": "An admin or root can ask for any member of their account; anyone else gets their own rows only. `format=csv` returns a ready-to-send file.", "operationId": "listTermsAcceptances", "tags": [ "Terms" ], "x-resource-type": "service", "parameters": [ { "name": "user_id", "in": "query", "required": false, "description": "Member to export", "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "Output format", "schema": { "type": "string", "enum": [ "json", "csv" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "acceptances": { "type": "array", "items": { "type": "object" } }, "count": { "type": "integer" }, "truncated": { "type": "boolean" }, "csv": { "type": "string", "description": "CSV text when format=csv" }, "filename": { "type": "string", "description": "Suggested file name" } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/sender-identity": { "get": { "summary": "Get the sending identity", "description": "The account's email sending identity. Any member can read it.", "operationId": "getSenderIdentity", "tags": [ "Email Sending" ], "x-resource-type": "service", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "Sending identity: domain, from_address, display_name, reply_to, DNS records and verification state", "additionalProperties": true } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Set the sending identity", "description": "Sets the sending domain and from address, then provisions the sending side. Admin only, because the sending domain is the account's outbound reputation.", "operationId": "setSenderIdentity", "tags": [ "Email Sending" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "description": "Sending domain" }, "from_address": { "type": "string", "description": "From address" }, "display_name": { "type": "string", "description": "Display name" }, "reply_to": { "type": "string", "description": "Reply-to address" }, "failure_task_space_id": { "type": "string", "description": "Space where a failed email raises a task" }, "track_engagement": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "Sending identity: domain, from_address, display_name, reply_to, DNS records and verification state", "additionalProperties": true } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Caller is not an admin or root", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/sender-identity-verify": { "post": { "summary": "Verify the sending identity", "description": "Runs the DNS check and returns the same object as **GET /accounts/sender-identity**. Records not yet published are a resting state: the call succeeds with per-record reasons.", "operationId": "verifySenderIdentity", "tags": [ "Email Sending" ], "x-resource-type": "service", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "Sending identity: domain, from_address, display_name, reply_to, DNS records and verification state", "additionalProperties": true } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/send-commercial-email": { "post": { "summary": "Send an email from the account", "description": "The sanctioned send for account email. Stamps scope and class so suppression and consent apply. `queued` means accepted by the outbox, not delivered. Give either `template_key` with `data`, or `subject` with `html`/`text`, never both.", "operationId": "sendCommercialEmail", "tags": [ "Email Sending" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "type": "string", "description": "Recipient" }, "subject": { "type": "string", "description": "Subject" }, "html": { "type": "string", "description": "HTML body" }, "text": { "type": "string", "description": "Text body" }, "from_address": { "type": "string", "description": "From address" }, "reply_to": { "type": "string", "description": "Reply-to" }, "template_key": { "type": "string", "description": "Published email template to render" }, "data": { "type": "object", "description": "Template tag values" }, "contact_folder": { "type": "string", "description": "Contact folder the mail belongs to" }, "task_id": { "type": "string", "description": "Task the mail belongs to" }, "class": { "type": "string", "description": "commercial (default) or transactional" }, "cc": { "type": "array", "items": { "type": "string" } }, "bcc": { "type": "array", "items": { "type": "string" } }, "idempotency_key": { "type": "string", "description": "Collapses repeats inside the outbox duplicate window" }, "ref": { "type": "object", "description": "Sender keys echoed on the activity row and delivery events" }, "attachments": { "type": "array", "items": { "type": "object" } }, "attachment_refs": { "type": "array", "items": { "type": "object" } } }, "required": [ "to" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "queued": { "type": "boolean" } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/cost-events": { "get": { "summary": "List cost events", "description": "Spend events for the account. Account-wide roles see every user's spend; other roles see their own.", "operationId": "listCostEvents", "tags": [ "Usage and Billing" ], "x-resource-type": "service", "parameters": [ { "name": "start_date", "in": "query", "required": false, "description": "Window start (with end_date)", "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "required": false, "description": "Window end", "schema": { "type": "string" } }, { "name": "session_id", "in": "query", "required": false, "description": "Only this session", "schema": { "type": "string" } }, { "name": "correlation_id", "in": "query", "required": false, "description": "Only this request", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number", "schema": { "type": "integer" } }, { "name": "page_size", "in": "query", "required": false, "description": "Rows per page", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/billing-events": { "get": { "summary": "List billing events", "description": "Subscription and credit events recorded against the account.", "operationId": "listBillingEvents", "tags": [ "Usage and Billing" ], "x-resource-type": "service", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/admin/export-cost-events": { "post": { "summary": "Email a cost events export", "description": "Exports the account's cost events and emails the file. Admin or root only.", "operationId": "exportCostEvents", "tags": [ "Usage and Billing" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "start_date": { "type": "string", "description": "Window start" }, "end_date": { "type": "string", "description": "Window end" }, "email": { "type": "string", "description": "Where to send the export" } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Caller is not an admin or root", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/ai-budget-limits": { "get": { "summary": "Get budget limits and spend guard", "description": "The account's spend guard state and budget limits.", "operationId": "getBudgetLimits", "tags": [ "Usage and Billing" ], "x-resource-type": "service", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Set the spend guard", "description": "Sets `guard_percent` (5 to 100; 100 leaves the credit balance as the only gate). Admin, root or billing role on a subscribed account. Returns the fresh budget state.", "operationId": "setBudgetLimits", "tags": [ "Usage and Billing" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "guard_percent": { "type": "integer", "description": "Percent of budget at which spend is stopped", "minimum": 5, "maximum": 100 } }, "required": [ "guard_percent" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/ai-budget-limits/override": { "post": { "summary": "Override the spend guard", "description": "Arms a temporary override of the spend guard, or with `clear: true` removes an active one. Admin, root or billing role on a subscribed account.", "operationId": "setSpendGuardOverride", "tags": [ "Usage and Billing" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clear": { "type": "boolean", "description": "Remove an active override" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/ai-budget": { "get": { "summary": "Get the credit balance", "description": "The account's credit balance and budget state.", "operationId": "getCredits", "tags": [ "Usage and Billing" ], "x-resource-type": "service", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/usage-summary": { "get": { "summary": "Get a usage summary", "description": "Usage totals for the account. Defaults to the last twelve months; send `start_date` and `end_date` to choose the window.", "operationId": "getUsageSummary", "tags": [ "Usage and Billing" ], "x-resource-type": "service", "x-path-derived": true, "parameters": [ { "name": "start_date", "in": "query", "required": false, "description": "Window start (with end_date)", "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "required": false, "description": "Window end", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/auto-topup": { "patch": { "summary": "Set auto top-up", "description": "Sets the credit level that triggers an automatic top-up and the pack to buy. A zero `threshold` turns it off. Admin, root or billing role.", "operationId": "setAutoTopup", "tags": [ "Usage and Billing" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "threshold": { "type": "number", "description": "Credit level that triggers a top-up; 0 disables" }, "pack": { "type": "string", "description": "Credit pack key; required when threshold is above 0" } }, "required": [ "threshold" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/credit-warning": { "patch": { "summary": "Set the credit warning level", "description": "Sets the remaining-credit level at which the account is warned. Zero restores the platform default; values between 0 and 1 are refused. Admin, root or billing role.", "operationId": "setCreditWarning", "tags": [ "Usage and Billing" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "threshold": { "type": "number", "description": "Whole number of credits, or 0 for the default" } }, "required": [ "threshold" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/payment/credit-packs": { "get": { "summary": "List credit packs", "description": "Credit packs the account's plan can buy, priced in the customer's currency.", "operationId": "listCreditPacks", "tags": [ "Payment" ], "x-resource-type": "service", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/payment/payment-methods": { "get": { "summary": "List payment methods", "description": "The payment methods on file for the account.", "operationId": "listPaymentMethods", "tags": [ "Payment" ], "x-resource-type": "service", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/payment/ai-budget": { "post": { "summary": "Buy a credit pack", "description": "Creates a checkout for a credit pack. Admin, root or billing role on a subscribed paid plan. `return_path` is an app-relative path to return to.", "operationId": "buyCreditPack", "tags": [ "Payment" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pack": { "type": "string", "description": "Credit pack key" }, "return_path": { "type": "string", "description": "App-relative return path" } }, "required": [ "pack" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/payment/subscription-schedule": { "delete": { "summary": "Cancel a scheduled downgrade", "description": "Releases the subscription schedule so a pending downgrade no longer takes effect.", "operationId": "cancelSubscriptionSchedule", "tags": [ "Payment" ], "x-resource-type": "service", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/users/notifications": { "get": { "summary": "List notifications", "description": "The signed-in user's in-app notifications, newest first.", "operationId": "listUserNotifications", "tags": [ "Notifications" ], "x-resource-type": "service", "parameters": [ { "name": "viewed", "in": "query", "required": false, "description": "Filter by viewed state", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "subject": { "type": "string", "description": "Notification subject" }, "title": { "type": "string", "description": "Title" }, "description": { "type": "string", "description": "Description" }, "created_at": { "type": "string", "format": "date-time" }, "viewed": { "type": "boolean" }, "refs": { "type": "array", "items": { "type": "object" } } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/users/notifications/viewed": { "patch": { "summary": "Mark a notification viewed", "description": "Marks one notification viewed.", "operationId": "markNotificationViewed", "tags": [ "Notifications" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "description": "Notification subject" } }, "required": [ "subject" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/users/notifications/viewed-all": { "patch": { "summary": "Mark notifications viewed", "description": "Marks a batch of the caller's own notifications viewed. Subjects outside the caller's own tree are reported as failed.", "operationId": "markNotificationsViewed", "tags": [ "Notifications" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subjects": { "type": "array", "items": { "type": "string" } } }, "required": [ "subjects" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }