openapi: 3.0.0 info: title: SurrealDB API Server version: 1.0.0 description: HTTP API for SurrealDB account, cloud, learn, support, and website services. security: - Bearer: [] components: securitySchemes: Bearer: type: http scheme: bearer bearerFormat: JWT CloudToken: type: apiKey in: header name: X-Cloud-Token description: "SurrealDB Cloud session token, as returned by `POST /api/cloud/v0/signin`. The bare token, with no `Bearer ` prefix — it is sent on to the Cloud API as a bearer credential. Never logged. Omit it when authenticating with a personal access token: the API signs in to Cloud on that token's behalf." schemas: WebsiteStarCount: type: object properties: stars: type: number example: 30000 required: - stars WebsitePressEntry: type: object properties: id: type: string title: type: string date: type: string required: - id WebsiteEventPage: anyOf: - $ref: "#/components/schemas/WebsiteLivestreamPage" - $ref: "#/components/schemas/WebsiteEventRecordPage" WebsiteEventRecordPage: allOf: - $ref: "#/components/schemas/WebsiteEventDetail" - type: object properties: kind: type: string enum: - event slug: type: string nullable: true required: - kind WebsiteEventDetail: type: object properties: id: type: string title: type: string description: type: string address: nullable: true categories: type: array items: type: string markdown: nullable: true date: type: string end_date: type: string nullable: true external_id: type: string nullable: true href: type: string image: type: string learn: nullable: true related_webinars: type: array items: nullable: true speakers: type: array items: nullable: true venue: nullable: true WebsiteLivestreamPage: type: object properties: kind: type: string enum: - livestream youtube: $ref: "#/components/schemas/WebsiteYouTubeVideo" required: - kind - youtube WebsiteYouTubeVideo: type: object properties: id: type: string example: dQw4w9WgXcQ snippet: type: object properties: title: type: string description: type: string publishedAt: type: string channelId: type: string channelTitle: type: string thumbnails: nullable: true tags: type: array items: type: string contentDetails: type: object properties: duration: type: string example: PT3M33S definition: type: string statistics: type: object properties: viewCount: type: string likeCount: type: string commentCount: type: string WebsiteEvent: type: object properties: slug: type: string nullable: true title: type: string description: type: string date: type: string end_date: type: string nullable: true categories: type: array items: type: string href: type: string image: type: string video_id: type: string nullable: true WebsiteBlogPostDetail: allOf: - $ref: "#/components/schemas/WebsiteBlogPost" - type: object nullable: true properties: blog_url: type: string created_at: type: string updated_at: type: string WebsiteBlogPost: type: object properties: id: type: string example: blog:01hxyz slug: type: string example: introducing-surrealdb-3 title: type: string summary: type: string image_code: type: string categories: type: array items: type: string publish_date: type: string blog_url: type: string example: /blog/introducing-surrealdb-3 content: $ref: "#/components/schemas/WebsiteCmsContent" authors: type: array items: nullable: true required: - id - slug - title - blog_url WebsiteCmsContent: type: object properties: live: type: object properties: json: nullable: true description: Rich-text document tree draft: nullable: true WebsiteBlogSitemapEntry: type: object properties: slug: type: string image: type: string title: type: string summary: type: string created_at: type: string updated_at: type: string WebsiteBanner: type: object properties: id: type: string title: type: string badge: type: string link: type: object properties: href: type: string label: type: string required: - href - label order: type: number effective_date: type: string expiry_date: type: string required: - id - title SupportHelpArticle: type: object properties: id: type: string title: type: string example: Getting started description: type: string body: type: string created_at: type: number updated_at: type: number url: type: string required: - id - title - description - body - created_at - updated_at - url SupportHelpArticleDetail: allOf: - $ref: "#/components/schemas/SupportHelpArticle" - type: object properties: collection: allOf: - $ref: "#/components/schemas/SupportHelpCollection" - nullable: true author: $ref: "#/components/schemas/SupportAuthor" required: - collection - author SupportAuthor: type: object nullable: true properties: type: type: string example: admin id: type: string example: "000000" name: type: string example: SurrealDB Team avatar: type: string example: https://…/avatar.png required: - type - id SupportHelpCollection: type: object properties: id: type: string name: type: string example: Billing description: type: string icon: type: string url: type: string order: type: number image: type: string required: - id - name - description - icon - url - order SupportHelpCollectionDetail: allOf: - $ref: "#/components/schemas/SupportHelpCollection" - type: object properties: articles: type: array items: $ref: "#/components/schemas/SupportHelpArticle" required: - articles SupportTicket: type: object properties: id: type: string title: type: string description: type: string state: $ref: "#/components/schemas/SupportTicketState" type: $ref: "#/components/schemas/SupportTicketType" created_at: type: number updated_at: type: number contacts: type: array items: $ref: "#/components/schemas/SupportContact" parts: type: array items: $ref: "#/components/schemas/SupportTicketPart" open: type: boolean attributes: type: object additionalProperties: nullable: true required: - id - title - description - state - type - created_at - updated_at - contacts - parts - open - attributes SupportTicketPart: type: object properties: id: type: string part_type: type: string example: comment state: allOf: - $ref: "#/components/schemas/SupportTicketState" - nullable: true previous_ticket_state: type: string created_at: type: number updated_at: type: number attachments: type: array items: nullable: true body: type: string author: $ref: "#/components/schemas/SupportAuthor" required: - id - part_type - state - created_at - updated_at - attachments - author SupportTicketState: type: object properties: id: type: string category: type: string example: in_progress label: type: string example: In progress required: - id - category - label SupportContact: type: object properties: id: type: string email: type: string example: user@example.com name: type: string example: Ada Lovelace avatar: type: string SupportTicketType: type: object properties: id: type: string name: type: string example: Enterprise Support required: - id - name SupportTicketAttribute: type: object properties: id: type: string name: type: string example: Severity level description: type: string order: type: number data_type: type: string example: list input_options: $ref: "#/components/schemas/SupportTicketAttributeInputOptions" required: type: boolean visible_on_create: type: boolean required: - id - name - order - data_type - required - visible_on_create SupportTicketAttributeInputOptions: type: object nullable: true properties: list_options: type: array items: $ref: "#/components/schemas/SupportTicketAttributeListOption" multiline: type: boolean allow_multiple_values: type: boolean SupportTicketAttributeListOption: type: object properties: id: type: string label: type: string archived: type: boolean description: type: string required: - id - label MarkedConversation: type: object properties: id: type: string required: - id SupportConversation: type: object properties: id: type: string title: type: string description: type: string state: $ref: "#/components/schemas/ConversationState" created_at: type: number updated_at: type: number contacts: type: array items: $ref: "#/components/schemas/SupportContact" last_response_author: $ref: "#/components/schemas/SupportAuthor" initial_part: $ref: "#/components/schemas/SupportInitialPart" parts: type: array nullable: true items: $ref: "#/components/schemas/SupportConversationPart" open: type: boolean read: type: boolean priority: type: boolean has_ticket: type: boolean ticket_data: $ref: "#/components/schemas/SupportTicket" required: - id - title - state - created_at - updated_at - contacts - last_response_author - initial_part - parts - open - read - priority - has_ticket SupportConversationPart: type: object properties: id: type: string part_type: type: string example: comment body: type: string created_at: type: number updated_at: type: number attachments: type: array items: $ref: "#/components/schemas/SupportAttachment" state: $ref: "#/components/schemas/ConversationState" author: $ref: "#/components/schemas/SupportAuthor" required: - id - part_type - body - created_at - updated_at - state - author ConversationState: type: string enum: - open - closed - snoozed SupportAttachment: type: object properties: type: type: string example: upload name: type: string example: screenshot.png url: type: string content_type: type: string example: image/png filesize: type: number example: 20480 width: type: number height: type: number required: - type - name - url - content_type - filesize - width - height SupportInitialPart: type: object properties: id: type: string part_type: type: string example: comment body: type: string created_at: type: number updated_at: type: number author: $ref: "#/components/schemas/SupportAuthor" required: - id - part_type - body - created_at - updated_at - author SealPassthrough: type: object additionalProperties: nullable: true description: Opaque object proxied verbatim from the Seal API. StudioConfig: type: object properties: api_access: type: boolean description: Whether the client may use the Cloud API example: true minimum_version: type: string description: Oldest client version allowed to run, as a semantic version example: 4.0.0 minimum_version_notice: type: string description: Reason to show a client below the minimum version; empty when no reason is given example: "" spectron_maintenance: type: boolean description: Whether Spectron (Agent Memory) is under maintenance; while true the client replaces every Spectron surface with a notice and issues none of their requests example: false required: - api_access - minimum_version - minimum_version_notice - spectron_maintenance ExperienceFormSubmissionReceipt: type: object properties: submitted_at: type: string description: When the submission was stored example: 2026-07-31T09:00:00Z required: - submitted_at ExperienceFormSubmissionStatus: type: object properties: submitted: type: boolean description: Whether this account has answered the form example: false submissions: type: integer description: How many times this account has answered example: 0 last_submitted_at: type: string nullable: true description: When it last answered, or null example: null can_submit: type: boolean description: Whether another submission is accepted example: true required: - submitted - submissions - last_submitted_at - can_submit ExperienceForm: type: object properties: id: type: string minLength: 1 maxLength: 64 pattern: ^[a-z][a-z0-9_]*$ example: onboarding description: The form's identifier name: type: string minLength: 1 maxLength: 120 description: Human-readable form name example: Account onboarding description: type: string maxLength: 1000 description: Intro text shown above the fields; empty when none is set example: "" settings: type: object properties: multiple_submissions: type: boolean description: Whether one account may submit this form more than once active: type: boolean description: Whether the form is served publicly; inactive forms read as absent required: - multiple_submissions - active additionalProperties: false fields: type: array items: $ref: "#/components/schemas/ExperienceFormField" description: The fields, in the order they should be shown required: - id - name - description - settings - fields ExperienceFormField: oneOf: - type: object properties: name: type: string minLength: 1 maxLength: 64 pattern: ^[a-z][a-z0-9_]*$ example: job_title description: Stable key this field's answer is stored under label: type: string minLength: 1 maxLength: 300 description: The question, as shown description: type: string minLength: 1 maxLength: 1000 description: Helper text shown under the label required: type: boolean description: Whether a submission must answer this field kind: type: string enum: - text placeholder: type: string minLength: 1 maxLength: 200 description: Placeholder shown while the field is empty min_length: type: integer minimum: 1 maximum: 5000 max_length: type: integer minimum: 1 maximum: 5000 required: - name - label - required - kind additionalProperties: false - type: object properties: name: type: string minLength: 1 maxLength: 64 pattern: ^[a-z][a-z0-9_]*$ example: job_title description: Stable key this field's answer is stored under label: type: string minLength: 1 maxLength: 300 description: The question, as shown description: type: string minLength: 1 maxLength: 1000 description: Helper text shown under the label required: type: boolean description: Whether a submission must answer this field kind: type: string enum: - textarea placeholder: type: string minLength: 1 maxLength: 200 description: Placeholder shown while the field is empty min_length: type: integer minimum: 1 maximum: 5000 max_length: type: integer minimum: 1 maximum: 5000 required: - name - label - required - kind additionalProperties: false - type: object properties: name: type: string minLength: 1 maxLength: 64 pattern: ^[a-z][a-z0-9_]*$ example: job_title description: Stable key this field's answer is stored under label: type: string minLength: 1 maxLength: 300 description: The question, as shown description: type: string minLength: 1 maxLength: 1000 description: Helper text shown under the label required: type: boolean description: Whether a submission must answer this field kind: type: string enum: - select placeholder: type: string minLength: 1 maxLength: 200 description: Placeholder shown while the field is empty options: type: array items: type: object properties: label: type: string minLength: 1 maxLength: 200 description: Choice shown to the user example: Software Engineer value: type: string minLength: 1 maxLength: 100 description: Value stored on submission example: software_engineer required: - label - value additionalProperties: false minItems: 1 maxItems: 100 required: - name - label - required - kind - options additionalProperties: false - type: object properties: name: type: string minLength: 1 maxLength: 64 pattern: ^[a-z][a-z0-9_]*$ example: job_title description: Stable key this field's answer is stored under label: type: string minLength: 1 maxLength: 300 description: The question, as shown description: type: string minLength: 1 maxLength: 1000 description: Helper text shown under the label required: type: boolean description: Whether a submission must answer this field kind: type: string enum: - multi_select placeholder: type: string minLength: 1 maxLength: 200 description: Placeholder shown while the field is empty options: type: array items: type: object properties: label: type: string minLength: 1 maxLength: 200 description: Choice shown to the user example: Software Engineer value: type: string minLength: 1 maxLength: 100 description: Value stored on submission example: software_engineer required: - label - value additionalProperties: false minItems: 1 maxItems: 100 min_selected: type: integer minimum: 1 maximum: 100 max_selected: type: integer minimum: 1 maximum: 100 required: - name - label - required - kind - options additionalProperties: false - type: object properties: name: type: string minLength: 1 maxLength: 64 pattern: ^[a-z][a-z0-9_]*$ example: job_title description: Stable key this field's answer is stored under label: type: string minLength: 1 maxLength: 300 description: The question, as shown description: type: string minLength: 1 maxLength: 1000 description: Helper text shown under the label required: type: boolean description: Whether a submission must answer this field kind: type: string enum: - checkbox required: - name - label - required - kind additionalProperties: false - type: object properties: name: type: string minLength: 1 maxLength: 64 pattern: ^[a-z][a-z0-9_]*$ example: job_title description: Stable key this field's answer is stored under label: type: string minLength: 1 maxLength: 300 description: The question, as shown description: type: string minLength: 1 maxLength: 1000 description: Helper text shown under the label required: type: boolean description: Whether a submission must answer this field kind: type: string enum: - number placeholder: type: string minLength: 1 maxLength: 200 description: Placeholder shown while the field is empty min: type: number max: type: number required: - name - label - required - kind additionalProperties: false CloudOrganizationSpectronContextPackage: type: object properties: package_id: $ref: "#/components/schemas/CloudId" organization_id: $ref: "#/components/schemas/CloudId" enabled_at: type: string format: date-time description: Timestamp when the package was enabled for the Organization example: 2021-06-01T00:00:00Z trial_ends_at: type: string format: date-time description: Timestamp when the package's initial trial will end example: 2021-06-01T00:00:00Z disabled_at: type: string format: date-time description: Timestamp when the package was disabled for the Organization subscription_ends_at: type: string nullable: true format: date-time description: Timestamp when the subscription will end (Stripe period end) example: 2021-06-01T00:00:00Z required: - package_id - organization_id - enabled_at CloudId: type: string minLength: 26 maxLength: 26 example: 67upifj5dt6p87ch3nh5t3a8 CloudCreateOrganizationSpectronContextPackage: type: object properties: package_id: type: string coupon_code: type: string required: - package_id CloudOrganizationSpectronContextPackages: type: array items: $ref: "#/components/schemas/CloudOrganizationSpectronContextPackage" CloudSpectronContextUsage: type: object properties: context_id: type: string period_start: type: string period_end: type: string token_limit: type: integer format: int64 tokens_used: type: integer format: int64 breakdown: type: array items: $ref: "#/components/schemas/CloudSpectronUsageRow" required: - context_id - period_start - period_end - tokens_used - breakdown CloudSpectronUsageRow: type: object properties: model: type: string token_kind: type: string description: Token kind (e.g. input/output) origin: type: string description: Pipeline stage / call origin the tokens were spent in tokens: type: integer format: int64 required: - model - token_kind - origin - tokens CloudSpectronVerbs: type: array items: $ref: "#/components/schemas/CloudSpectronVerb" CloudSpectronVerb: type: object properties: name: type: string description: Full verb in : form, e.g. memory:read noun: type: string description: type: string required: - name - noun - description CloudSpectronProviders: type: array items: $ref: "#/components/schemas/CloudSpectronProvider" CloudSpectronProvider: type: object properties: provider: type: string models: type: array items: type: string required: - provider - models CloudSpectronContextConfig: type: object properties: token_limit: type: integer format: int64 billing_anchor_day: type: integer reject_unbound_keys: type: boolean llm_extraction_enabled: type: boolean pii_redaction_enabled: type: boolean ingestion_profile: type: string providers_configured: type: array items: type: string required: - reject_unbound_keys - llm_extraction_enabled - pii_redaction_enabled CloudSpectronScopes: type: array items: $ref: "#/components/schemas/CloudSpectronScope" CloudSpectronScope: type: object properties: path: type: string name: type: string depth: type: integer value_policy: type: string children_count: type: integer created_at: type: string parent: type: string display_name: type: string tombstoned_at: type: string required: - path - name - depth - value_policy - children_count - created_at CloudAddSpectronContextUser: type: object properties: user_id: type: string description: The cloud user (org member) to add to the Context required: - user_id CloudReplaceSpectronPrincipalGrants: type: object properties: grants: type: object additionalProperties: type: array items: type: string description: Per-verb map of scope-pattern lists required: - grants CloudUpdateSpectronPrincipal: type: object properties: display_name: type: string kind: type: string CloudSpectronPrincipal: type: object properties: id: type: string kind: type: string description: human | agent | service | unknown display_name: type: string grants: type: object additionalProperties: type: array items: type: string description: Per-verb map of scope-pattern lists required: - id - kind - display_name CloudCreateSpectronPrincipal: type: object properties: kind: type: string description: human | agent | service | unknown display_name: type: string grants: type: object additionalProperties: type: array items: type: string description: Per-verb map of scope-pattern lists required: - kind - display_name CloudSpectronPrincipals: type: array items: $ref: "#/components/schemas/CloudSpectronPrincipal" CloudSpectronAccessToken: type: object properties: key: type: string description: The minted access-token secret (shown once) principal_id: type: string valid_until: type: string required: - key - principal_id CloudMintSpectronAccessToken: type: object properties: ttl_seconds: type: integer description: Requested token lifetime in seconds (server-side clamped). Omit for the cloud default. format: int64 CloudMintSpectronScopedKey: type: object properties: principal_id: type: string description: The Spectron principal the key is bound to name: type: string grants: type: object additionalProperties: type: array items: type: string description: Optional attenuating grants (key ⊆ principal) required: - principal_id - name CloudSpectronContextApiKey: type: object properties: id: $ref: "#/components/schemas/CloudId" organization_id: $ref: "#/components/schemas/CloudId" spectron_context_id: $ref: "#/components/schemas/CloudId" name: type: string description: Name of the API Key for the SpectronContext key: type: string required: - id - organization_id - spectron_context_id - name CloudCreateSpectronContextAPIKey: type: object properties: name: type: string description: Name of the API Key for the SpectronContext required: - name CloudSpectronContextApiKeys: type: array items: $ref: "#/components/schemas/CloudSpectronContextApiKey" CloudUpdateSpectronContext: type: object properties: name: type: string description: Name of the Context required: - name CloudSpectronContext: type: object properties: id: $ref: "#/components/schemas/CloudId" organization_id: $ref: "#/components/schemas/CloudId" name: type: string description: Name of the Context region: type: string description: Region of the Context host: type: string description: Host of the ContextStore state: type: string description: "Provisioning state of the Context: creating until the Context is bootstrapped, then ready" example: creating required: - id - organization_id - name - region - host - state CloudCreateSpectronContext: type: object properties: name: type: string description: Name of the API Key for the Context region: type: string description: Region where to setup the Context required: - name - region CloudSpectronContexts: type: array items: $ref: "#/components/schemas/CloudSpectronContext" CloudInstanceLogs: type: object properties: from_time: type: string format: date-time example: 2021-06-01T12:00:00Z to_time: type: string format: date-time example: 2021-06-01T12:00:00Z log_lines: type: array items: type: object properties: timestamp: type: string example: 2025-07-09T12:21:23.222225Z pod: type: string example: surrealdb-34848 level: type: string example: INFO message: type: string example: This is a log message required: - timestamp - pod - level - message required: - from_time - to_time - log_lines CloudInstanceMetrics: type: object properties: metric: type: string example: cpu from_time: type: string format: date-time example: 2021-06-01T12:00:00Z to_time: type: string format: date-time example: 2021-06-01T12:00:00Z unit: type: string example: vCPU type: type: string example: timeseries values: type: object properties: timestamps: type: array items: type: string format: date-time example: 2021-06-01T12:00:00Z metrics: type: array items: type: object properties: labels: type: string example: surrealdb-replica-1 values: type: array items: type: number nullable: true required: - labels - values required: - timestamps - metrics required: - metric - from_time - to_time - unit - type - values CloudUpdateInstanceBackupPolicyRequest: type: object properties: daily_retention_days: type: integer nullable: true minimum: 0 weekly_retention_weeks: type: integer nullable: true minimum: 0 monthly_retention_months: type: integer nullable: true minimum: 0 frequency_hours: type: integer minimum: 1 maximum: 24 CloudInstanceBackupPolicyResponse: type: object properties: daily: $ref: "#/components/schemas/CloudBackupPolicyTierDaily" weekly: $ref: "#/components/schemas/CloudBackupPolicyTierWeekly" monthly: $ref: "#/components/schemas/CloudBackupPolicyTierMonthly" frequency: $ref: "#/components/schemas/CloudBackupFrequencyPolicy" required: - daily - weekly - monthly - frequency CloudBackupFrequencyPolicy: type: object properties: frequency_hours: type: integer minimum: 1 maximum: 24 allowed_frequency_hours: type: array items: type: integer minimum: 1 maximum: 24 editable: type: boolean required: - frequency_hours - allowed_frequency_hours - editable CloudBackupPolicyTierMonthly: type: object properties: retention_months: type: integer minimum: 0 min_months: type: integer minimum: 0 max_months: type: integer minimum: 0 editable: type: boolean required: - retention_months - min_months - max_months - editable CloudBackupPolicyTierWeekly: type: object properties: retention_weeks: type: integer minimum: 0 min_weeks: type: integer minimum: 0 max_weeks: type: integer minimum: 0 editable: type: boolean required: - retention_weeks - min_weeks - max_weeks - editable CloudBackupPolicyTierDaily: type: object properties: retention_days: type: integer minimum: 0 min_days: type: integer minimum: 0 max_days: type: integer minimum: 0 editable: type: boolean required: - retention_days - min_days - max_days - editable CloudInstanceStatus: type: object properties: phase: type: string example: Ready db_backups: $ref: "#/components/schemas/CloudInstanceBackupStatuses" required: - phase CloudInstanceBackupStatuses: type: array items: $ref: "#/components/schemas/CloudInstanceBackupStatus" CloudInstanceBackupStatus: type: object properties: snapshot_started_at: type: string format: date-time example: 2025-01-31T09:00:00Z snapshot_id: type: string example: rsnapshot-20250128-150405 valid_versions: type: array items: type: string example: - 3.0.0 - 2.6.1 tiers: type: array items: type: string enum: - daily - weekly - monthly - update-image on_demand: type: boolean description: wether or not this backup was an ondemand backup required: - snapshot_started_at - snapshot_id - valid_versions CloudInstanceUsage: type: array items: $ref: "#/components/schemas/CloudInstanceUsageMetric" CloudInstanceUsageMetric: type: object properties: instance_id: $ref: "#/components/schemas/CloudId" instance_type: type: string example: nano metric_type: type: string example: storage_current source: type: string example: s3 compute_hours: type: integer format: int64 example: 300 disk_used_bytes: type: integer format: int64 example: 1024 measured_period_start: type: string format: date-time example: 2021-06-01T12:00:00Z measured_period_end: type: string format: date-time example: 2021-06-01T12:00:00Z required: - instance_id - metric_type - measured_period_start - measured_period_end CloudJwks: type: object properties: keys: type: array items: type: object additionalProperties: nullable: true required: - keys title: JSON Web Key Set description: JSON Web Key Set to validate JSON Web Token CloudInstanceAuth: type: object properties: token: type: string required: - token CloudInstanceDistributedStorageSpecs: type: object properties: category: type: string example: standard autoscaling: type: boolean example: true max_compute_units: type: number minimum: 3 maximum: 9 format: int32 example: 3 units: type: integer minimum: 3 maximum: 9 format: int32 slug: type: string required: - autoscaling - max_compute_units CloudCapabilitiesConfig: type: object properties: allow_scripting: type: boolean example: false allow_guests: type: boolean example: false allow_insecure_storable_closures: type: boolean example: false allowed_experimental: type: array items: type: string example: [] denied_experimental: type: array items: type: string example: [] allowed_arbitrary_query: type: array items: type: string example: [] denied_arbitrary_query: type: array items: type: string example: [] allowed_eval_query: type: array items: type: string description: User groups allowed to run eval queries. Valid values are "guest", "record" and "system". Empty by default (eval queries are opt-in). Only supported by SurrealDB >=3.2.0. When omitted, the current value is preserved. example: [] denied_eval_query: type: array items: type: string description: User groups denied from running eval queries. Valid values are "guest", "record" and "system". Only supported by SurrealDB >=3.2.0. When omitted, the current value is preserved. example: [] allowed_rpc_methods: type: array items: type: string example: "[]" denied_rpc_methods: type: array items: type: string example: "[]" allowed_http_endpoints: type: array items: type: string example: '["health", "rpc"]' denied_http_endpoints: type: array items: type: string example: "[]" allowed_networks: type: array items: type: string example: "[]" denied_networks: type: array items: type: string example: "[]" allowed_functions: type: array items: type: string example: '["type::is::array"]' denied_functions: type: array items: type: string example: "[]" required: - allow_scripting - allow_guests - allowed_experimental - denied_experimental - allowed_arbitrary_query - denied_arbitrary_query - allowed_rpc_methods - denied_rpc_methods - allowed_http_endpoints - denied_http_endpoints - allowed_networks - denied_networks - allowed_functions - denied_functions CloudUpdateInstanceAccessType: type: object properties: access_type: $ref: "#/components/schemas/CloudAccessType" required: - access_type CloudAccessType: type: string enum: - public - private - dual default: public description: > Instance access type: - public: Accessible via public internet only (default) - private: Accessible via PrivateLink only (requires org PrivateLink enabled) - dual: Accessible via both public internet and PrivateLink (requires org PrivateLink enabled) example: public CloudUpdateInstanceVersion: type: object properties: version: $ref: "#/components/schemas/CloudInstanceVersion" required: - version CloudInstanceVersion: type: string CloudUpdateInstanceStorageSize: type: object properties: storage_size_gb: type: integer minimum: 1 format: int64 example: 1 required: - storage_size_gb CloudUpdateInstanceComputeUnits: type: object properties: compute_units: type: integer minimum: 1 format: int64 example: 1 required: - compute_units CloudUpdateInstanceType: type: object properties: slug: type: string example: shared-1 required: - slug CloudInstance: type: object properties: id: $ref: "#/components/schemas/CloudId" name: type: string maxLength: 30 example: instance-1 slug: type: string minLength: 5 maxLength: 15 example: pretty-lark version: $ref: "#/components/schemas/CloudInstanceVersion" available_versions: type: array items: $ref: "#/components/schemas/CloudInstanceVersion" description: List of available SurrealDB versions for the instance, including the current one. host: type: string description: > Primary endpoint hostname. Always present for backwards compatibility. For public/dual: public hostname. For private: PrivateLink hostname. example: aaaaaaa-aaaa.surrealdb.com private_host: type: string description: PrivateLink endpoint hostname (only present for dual access type) example: aaaaaaa-aaaa.privatelink.aws-usw2.surrealdb.cloud access_type: $ref: "#/components/schemas/CloudAccessType" region: $ref: "#/components/schemas/CloudRegion" type: $ref: "#/components/schemas/CloudInstanceType" organization_id: $ref: "#/components/schemas/CloudId" compute_units: type: integer minimum: 1 format: int64 example: 1 state: type: string example: creating storage_size: type: integer description: Storage size in GB format: int64 example: 1 storage_size_updated_at: type: string format: date-time description: The last time the instance storage size was updated example: 2021-06-01T12:00:00Z can_update_storage_size: type: boolean description: If updates to the instance storage size are currently allowed example: false storage_size_update_cooloff_hours: type: integer description: The amount of hours needed between instance storage size updates format: int example: 6 capabilities: $ref: "#/components/schemas/CloudCapabilitiesConfig" distributed_storage_specs: $ref: "#/components/schemas/CloudInstanceDistributedStorageSpecs" backup_policy: $ref: "#/components/schemas/CloudInstanceBackupPolicySummary" required: - id - name - slug - version - available_versions - host - access_type - region - type - organization_id - compute_units - state - storage_size - can_update_storage_size - storage_size_update_cooloff_hours - capabilities CloudInstanceBackupPolicySummary: type: object properties: daily_retention_days: type: integer minimum: 0 weekly_retention_weeks: type: integer minimum: 0 monthly_retention_months: type: integer minimum: 0 required: - daily_retention_days - weekly_retention_weeks - monthly_retention_months CloudInstanceType: type: object properties: slug: type: string example: shared-1 display_name: type: string example: shared instance description: type: string example: Shared instance cpu: type: number description: Number of cores example: 0.5 memory: type: integer description: RAM memory in MB format: int64 example: 512 compute_units: type: object properties: min: type: integer minimum: 1 format: int64 example: 1 max: type: integer minimum: 1 format: int64 example: 3 price_hour: type: integer minimum: 0 description: Price per hour in cents USD format: int64 example: 1 enabled: type: boolean description: Indicates if the instance type is enabled for the given organization example: true category: type: string description: Category of the instance type example: development default_storage_size: type: integer description: Default storage size of the instance type in GB example: 8 max_storage_size: type: integer description: Max storage size of the instance type in GB example: 16 restricted: type: boolean example: false required: - slug - display_name - description - cpu - memory - compute_units - price_hour - category - default_storage_size - max_storage_size - restricted CloudRegion: type: string maxLength: 16 example: aws-euw1 CloudInstanceCost: type: object properties: currency: type: string maxLength: 30 example: "" currency_symbol: type: string maxLength: 30 example: $ cost: type: number format: float64 example: 132 required: - currency - currency_symbol - cost CloudCreateInstance: type: object properties: storage: type: integer format: int example: 100 name: type: string minLength: 1 maxLength: 30 example: my-instance org: $ref: "#/components/schemas/CloudId" region: $ref: "#/components/schemas/CloudRegion" specs: $ref: "#/components/schemas/CloudInstanceSpecs" distributed_storage_specs: $ref: "#/components/schemas/CloudInstanceDistributedStorageSpecs" restore_specs: $ref: "#/components/schemas/CloudRestoreSpecs" access_type: $ref: "#/components/schemas/CloudAccessType" required: - org - region - specs CloudRestoreSpecs: type: object properties: backup_id: type: string instance_id: type: string required: - backup_id - instance_id CloudInstanceSpecs: type: object properties: slug: type: string example: shared-1 version: $ref: "#/components/schemas/CloudInstanceVersion" compute_units: type: integer minimum: 1 format: int64 example: 1 storage_backend: type: string enum: - default - skv-experimental description: Storage backend for the instance example: default required: - slug CloudUpdatePlan: type: object properties: id: $ref: "#/components/schemas/CloudId" required: - id CloudPaymentURL: type: string format: uri example: https://example.com/payment CloudPaymentInfo: type: object properties: card_last4: type: string minLength: 4 maxLength: 4 example: "1234" card_brand: type: string minLength: 1 maxLength: 100 example: Visa required: - card_last4 - card_brand CloudGetPaymentInfo: type: object properties: payment_info: type: boolean example: false info: $ref: "#/components/schemas/CloudPaymentInfo" required: - payment_info CloudCoupon: type: string example: COUPONCODE CloudCouponsInfo: type: object properties: coupons: type: array items: $ref: "#/components/schemas/CloudCouponInfo" required: - coupons CloudCouponInfo: type: object properties: name: type: string example: "123456" amount: type: integer description: Amount in cents USD example: 100 amount_remaining: type: integer description: Amount remianing in cents USD example: 100 expires_at: type: string format: date-time example: 2021-06-01T12:00:00Z required: - name - amount - amount_remaining CloudInvoices: type: array items: $ref: "#/components/schemas/CloudInvoice" CloudInvoice: type: object properties: id: type: string minLength: 1 date: type: string format: date-time example: 2021-06-01T12:00:00Z amount: type: integer description: Amount in cents USD format: int64 example: 100 status: type: string enum: - succeeded - pending - failed url: type: string format: uri description: URL to download the invoice in PDF format example: https://example.com/invoice required: - id - date - amount - status - url CloudPutBillingInfo: type: object properties: Name: type: string minLength: 1 maxLength: 100 example: John Doe Email: type: string minLength: 7 maxLength: 100 example: jonh.doe@gmail.com AddressLine1: type: string minLength: 1 maxLength: 200 example: 123 Main St AddressLine2: type: string minLength: 0 maxLength: 200 example: Apt 1 City: type: string minLength: 1 maxLength: 100 description: "City name, see: https://en.wikipedia.org/wiki/List_of_long_place_names" example: Springfield Zipcode: type: string minLength: 4 maxLength: 10 description: "Zipcode, see: https://www.geoapify.com/postcode-formats-around-the-world/" example: "12345" State: type: string minLength: 2 maxLength: 100 description: "State name, see: https://en.wikipedia.org/wiki/List_of_long_place_names" example: California Country: type: string minLength: 2 maxLength: 2 description: "Country code in ISO 3166-1 alpha-2 format, see: https://en.wikipedia.org/wiki/ISO_3166-2" example: US LegalName: type: string minLength: 1 maxLength: 100 example: John Doe Inc. TaxIdentificationNumber: type: string minLength: 9 maxLength: 20 description: "Tax Identification Number, see: https://wintershalldea.com/sites/default/files/media/files/Tax%20ID\ %20Formats%20for%20Forms.pdf" example: "123456789" Phone: type: string minLength: 7 maxLength: 20 example: "+1234567890" required: - Name - Email - AddressLine1 - City - Country CloudGetBillingInfo: type: object properties: Name: type: string minLength: 1 maxLength: 100 example: John Doe Email: type: string minLength: 7 maxLength: 100 example: jonh.doe@gmail.com AddressLine1: type: string minLength: 1 maxLength: 200 example: 123 Main St AddressLine2: type: string minLength: 0 maxLength: 200 example: Apt 1 City: type: string minLength: 1 maxLength: 100 description: "City name, see: https://en.wikipedia.org/wiki/List_of_long_place_names" example: Springfield Zipcode: type: string minLength: 4 maxLength: 10 description: "Zipcode, see: https://www.geoapify.com/postcode-formats-around-the-world/" example: "12345" State: type: string minLength: 2 maxLength: 100 description: "State name, see: https://en.wikipedia.org/wiki/List_of_long_place_names" example: California Country: type: string minLength: 2 maxLength: 2 description: "Country code in ISO 3166-1 alpha-2 format, see: https://en.wikipedia.org/wiki/ISO_3166-2" example: US LegalName: type: string minLength: 1 maxLength: 100 example: John Doe Inc. TaxIdentificationNumber: type: string minLength: 9 maxLength: 20 description: "Tax Identification Number, see: https://wintershalldea.com/sites/default/files/media/files/Tax%20ID\ %20Formats%20for%20Forms.pdf" example: "123456789" Phone: type: string minLength: 7 maxLength: 20 example: "+1234567890" required: - Name - Email CloudInvitation: type: object properties: organization_id: type: string code: type: string example: bvh68e6f1t543aru8nvj34guh8 role: type: string example: admin email: type: string example: example@example.com status: type: string example: invited required: - organization_id - code - role - email - status CloudCreateInvitation: type: object properties: role: type: string example: admin email: type: string example: example@example.com required: - role - email CloudInvitations: type: array items: $ref: "#/components/schemas/CloudInvitation" CloudOrganizationSpend: type: array items: $ref: "#/components/schemas/CloudLedgerEntryAggregation" CloudLedgerEntryAggregation: type: object properties: organization_id: $ref: "#/components/schemas/CloudId" description: type: string description: | A human readable description of the entry, examples: - "Compute Usage" - "Storage Usage" - "Compute Discount" - "Backup Fee" - "Support Fee - %" - ..other resource: type: string enum: - instance_compute_usage_hourly - instance_storage_usage_hourly - instance_network_usage_hourly - instance_backup_hourly - payment_plan_addon - prepaid_amount - manual_correction amount_millcents: type: integer description: Price in USD millcents format: int64 example: 123457 cloud_usage_units: type: integer description: Amount of billed "cloud usage units" corresponding to the usage format: int64 example: 123457 units: type: integer description: > for ledger entries of resource compute this value is the total compute minutes of all their nodes for ledger entries of resource storage this value is the total bytes measured for other ledger entries this value is 0 format: int64 example: 1234 units_literal: type: string enum: - minutes - bytes description: a descriptor of unit used for the `units` field. (optional, only for entries with `units`) effective_at: type: string format: date-time example: 2021-06-01T00:00:00Z instance_id: $ref: "#/components/schemas/CloudId" instance_type: type: string required: - organization_id - description - resource - amount_millcents - cloud_usage_units - effective_at CloudOrganizationUsage: type: array items: $ref: "#/components/schemas/CloudInstanceUsageMetric" CloudInstances: type: array items: $ref: "#/components/schemas/CloudInstance" CloudOrganizationMember: type: object properties: user_id: $ref: "#/components/schemas/CloudId" organization_id: $ref: "#/components/schemas/CloudId" role: type: string example: admin name: type: string example: Peter username: type: string example: Peter profile_picture: type: string example: https://example.com/picture.jpg required: - user_id - organization_id - role - name - username - profile_picture CloudUpdateOrganizationMember: type: object properties: role: type: string example: admin required: - role CloudOrganizationMembers: type: array items: $ref: "#/components/schemas/CloudOrganizationMember" CloudMyPermissions: type: array items: $ref: "#/components/schemas/CloudMyPermission" CloudMyPermission: type: object properties: resource: type: string action: type: string required: - resource - action CloudRoles: type: array items: $ref: "#/components/schemas/CloudRole" CloudRole: type: object properties: name: type: string example: admin permissions: type: array items: $ref: "#/components/schemas/CloudRolePermission" CloudRolePermission: type: object properties: resource: type: string example: instance action: type: string example: write CloudOrganizationSupportPlans: type: array items: $ref: "#/components/schemas/CloudOrganizationSupportPlan" CloudOrganizationSupportPlan: type: object properties: id: $ref: "#/components/schemas/CloudId" support_plan: $ref: "#/components/schemas/CloudSupportPlan" enabled_at: type: string format: date-time example: 2021-06-01T12:00:00Z disabled_at: type: string format: date-time example: 2021-06-01T12:00:00Z required: - id - support_plan - enabled_at CloudSupportPlan: type: object properties: id: $ref: "#/components/schemas/CloudId" name: type: string description: Name of the support plan example: Premium description: type: string description: Description of the support plan example: 24/7 support with dedicated account manager required: - id - name - description CloudUpdateOrganization: type: object properties: name: type: string minLength: 1 maxLength: 30 example: my org required: - name CloudOrganization: type: object properties: id: $ref: "#/components/schemas/CloudId" name: type: string example: a name billing_info: type: boolean description: > Indicates if the billing info is complete, so the system can ask an user for the payment info. example: true payment_info: type: boolean description: > Indicates if the payment info is complete, so the organization can be updated to use plan that includes paid instances. example: true max_free_instances: type: integer minimum: 0 format: int64 example: 1 max_paid_instances: type: integer minimum: 0 format: int64 example: 1 plan: $ref: "#/components/schemas/CloudPlan" available_plans: $ref: "#/components/schemas/CloudPlans" archived_at: type: string format: date-time example: 2024-06-01T12:00:00Z member_count: type: integer example: 1 user_role: type: string example: admin billing_provider: type: string enum: - stripe - aws_marketplace - azure_marketplace state: type: string enum: - created - onboarded - freezing - frozen - terminating - termianted resources_locked: type: boolean example: false privatelink_enabled: type: boolean description: > Indicates if the organization has PrivateLink enabled. When enabled, instances can be created with private or dual access types. example: false backup_bounds: $ref: "#/components/schemas/CloudOrganizationBackupBoundsView" required: - id - name - billing_info - payment_info - max_free_instances - max_paid_instances - plan - available_plans - member_count - user_role - billing_provider - state - resources_locked - privatelink_enabled CloudOrganizationBackupBoundsView: type: object properties: is_custom: type: boolean daily: type: object properties: min_days: type: integer minimum: 0 max_days: type: integer minimum: 0 required: - min_days - max_days weekly: type: object properties: min_weeks: type: integer minimum: 0 max_weeks: type: integer minimum: 0 required: - min_weeks - max_weeks monthly: type: object properties: min_months: type: integer minimum: 0 max_months: type: integer minimum: 0 required: - min_months - max_months required: - is_custom - daily - weekly - monthly CloudPlans: type: array items: $ref: "#/components/schemas/CloudPlan" CloudPlan: type: object properties: id: $ref: "#/components/schemas/CloudId" name: type: string example: free description: type: string example: Free plan regions: type: array items: $ref: "#/components/schemas/CloudRegion" instance_types: type: array items: $ref: "#/components/schemas/CloudInstanceType" storage_instance_types: type: array items: $ref: "#/components/schemas/CloudInstanceType" required: - id - name - description - regions - instance_types - storage_instance_types CloudCreateOrganization: type: object properties: name: type: string minLength: 1 maxLength: 30 example: my org required: - name CloudOrganizations: type: array items: $ref: "#/components/schemas/CloudOrganization" CloudReferralCode: type: string example: opaque-referral-code CloudReferralsInfo: type: object properties: users_referred: type: number format: int64 required: - users_referred CloudFormAnswers: nullable: true title: User form answers description: Answers to the user form CloudForm: nullable: true title: Questionary form description: Questionary form CloudEmptyBody: type: object properties: {} description: No response body. CloudTerms: type: object properties: use: type: boolean example: true marketing: type: boolean example: true CloudUpdateUserProfile: type: object properties: name: type: string example: John Doe CloudUserProfile: type: object properties: enabled_features: type: array items: type: string username: type: string example: user@example.com name: type: string example: user@example.com user_hmac: type: string example: Xw0NsCVXMBf7svAoIoKBmkpEK picture: type: string example: https://example.com/picture.jpg default_org: type: string example: AAAAAA first_name: type: string example: John last_name: type: string example: Doe required: - enabled_features - username - name - user_hmac - default_org CloudRefreshTokenInfo: type: object properties: token: type: string refresh: type: string example: Xw0NsCVXMBf7svAoIoKBmkpEK required: - token - refresh CloudRefreshToken: type: string example: Xw0NsCVXMBf7svAoIoKBmkpEK CloudLoginInfo: type: object properties: token: type: string id: $ref: "#/components/schemas/CloudId" provider: type: string description: > The identity provider used by the user to authenticate. An auth0 identity provider means the user is directly using auth0 so no a social login. example: auth0 terms_accepted_at: type: string format: date-time example: 2021-06-01T12:00:00Z marketing_accepted_at: type: string format: date-time example: 2021-06-01T12:00:00Z required: - token - id - provider CloudToken: type: string CloudBillingCountries: type: array items: $ref: "#/components/schemas/CloudBillingCountry" CloudBillingCountry: type: object properties: code: type: string minLength: 2 maxLength: 2 example: US name: type: string example: United States required: - code - name CloudInstanceTypes: type: array items: $ref: "#/components/schemas/CloudInstanceType" CloudInstanceVersions: type: array items: $ref: "#/components/schemas/CloudInstanceVersion" CloudRegions: type: array items: $ref: "#/components/schemas/CloudRegionInfo" CloudRegionInfo: type: object properties: description: type: string example: AWS provider in Ireland slug: $ref: "#/components/schemas/CloudRegion" flag: type: string description: CDN id of the region's flag asset. example: ru8l1cofibjncfyu69b9fsjk required: - description - slug - flag CloudSpectronContextPackages: type: array items: $ref: "#/components/schemas/CloudSpectronContextPackage" CloudSpectronContextPackage: type: object properties: id: $ref: "#/components/schemas/CloudId" name: type: string description: Name of the Context Package description: type: string description: Description for the Context Package cost_millcents: type: integer format: int64 token_limit: type: integer description: Limit of tokens format: int64 storage_gb: type: integer description: Included storage in gigabytes format: int64 contexts_limit: type: integer description: Amount of Contexts to create per org example: 5 billing_period: type: string enum: - monthly - yearly description: Billing schedule for the package trial_days: type: integer description: Amount of trial days on this package. 0 for no trial format: int32 example: 7 public: type: boolean description: Whether the package is publicly listed required: - id - name - description - cost_millcents - token_limit - storage_gb - contexts_limit - billing_period - trial_days - public CloudSystemMessage: type: object properties: message: type: string example: System message message_type: type: string enum: - info - warning - error timestamp: type: string format: date-time example: 2021-06-01T12:00:00Z CloudSupportPlans: type: array items: $ref: "#/components/schemas/CloudSupportPlan" CloudTCPP: type: array items: type: object properties: name: type: string example: Terms and Conditions url: type: string format: uri example: https://example.com/terms required: - name - url CloudErrorResponse: anyOf: - $ref: "#/components/schemas/CloudError" - $ref: "#/components/schemas/ApiError" description: An error relayed from the Cloud API, or raised by this API. ApiError: type: object properties: success: type: boolean example: false message: type: string example: Something went wrong code: type: string example: license_not_found required: - success - message CloudError: type: object properties: code: type: string message: type: string required: - code - message description: Represents error object CloudVersion: type: object properties: version: type: string description: API version example: 0.0.1 ui_version: type: string description: the minimum version of the UI that can interact with this API version. required: - version - ui_version ApiSuccess: type: object properties: success: type: boolean example: true message: type: string required: - success AccountApplication: type: object properties: client_id: type: string example: XIpYie6cnltLor9wU0T7bCW51NGxoyaP name: type: string example: SurrealDB Cloud description: type: string nullable: true logo_uri: type: string nullable: true login_url: type: string nullable: true example: https://app.surrealdb.com description: Auth0 initiate_login_uri when configured on the client required: - client_id - name - description - logo_uri - login_url AccountTokenDeleted: type: object properties: success: type: boolean example: true required: - success AccountCreatedPersonalAccessToken: allOf: - $ref: "#/components/schemas/AccountPersonalAccessToken" - type: object properties: secret_key: type: string example: sdbp_… required: - secret_key AccountPersonalAccessToken: type: object properties: id: type: string example: personal_access_token:01hxyz label: type: string example: My laptop MCP scopes: type: array items: type: string created_at: type: string expires_at: type: string user_id: type: string required: - id - label - scopes - created_at - expires_at - user_id AccountScopeCategory: type: object properties: category: type: string example: Account scopes: type: array items: $ref: "#/components/schemas/AccountScope" required: - category - scopes AccountScope: type: object properties: id: type: string example: read:account label: type: string example: Read account description: type: string required: - id - label - description parameters: {} paths: /api/accounts/v1/scopes: get: tags: - Accounts summary: List scopes grantable to personal access tokens description: Returns the catalogue of PAT-grantable scopes grouped by category. Backoffice scopes are only included for SurrealDB staff (verified `@surrealdb.com` email); all other callers see the user-facing scopes only. responses: "200": description: List of scope categories content: application/json: schema: type: array items: $ref: "#/components/schemas/AccountScopeCategory" /api/accounts/v1/tokens: get: tags: - Accounts summary: List personal access tokens for the authenticated user responses: "200": description: List of personal access tokens content: application/json: schema: type: array items: $ref: "#/components/schemas/AccountPersonalAccessToken" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" post: tags: - Accounts summary: Create a new personal access token requestBody: required: true content: application/json: schema: type: object properties: label: type: string minLength: 1 maxLength: 120 example: My laptop MCP scopes: type: array items: type: string minLength: 1 maxLength: 128 maxItems: 32 default: [] description: Scope ids to grant. Must be a subset of the registry at /scopes. example: - read:account duration_days: type: integer nullable: true minimum: 1 maximum: 365 default: 30 example: 30 description: PAT lifetime in days, between 1 and 365. Pass `null` to create a token with no expiration (discouraged - surface a UI warning). responses: "201": description: Personal access token created content: application/json: schema: $ref: "#/components/schemas/AccountCreatedPersonalAccessToken" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/ApiError" "403": description: Requested scopes are not grantable to this account content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/accounts/v1/tokens/{id}: delete: tags: - Accounts summary: Revoke a personal access token parameters: - schema: type: string pattern: ^[A-Za-z0-9:_-]{1,128}$ required: true name: id in: path responses: "200": description: Personal access token deleted content: application/json: schema: $ref: "#/components/schemas/AccountTokenDeleted" "404": description: Token not found or not owned by user content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/accounts/v1/applications: get: tags: - Accounts summary: List applications available to the authenticated user description: Returns user-facing Auth0 applications the caller may launch. SurrealDB staff (`@surrealdb.com`) receive every regular_web/spa/native client; everyone else receives only allowlisted clients that are also enabled on the Auth0 connection inferred from their JWT `sub` (`strategy|connection|id` for enterprise, `provider|id` for social/database). responses: "200": description: List of available applications content: application/json: schema: type: object properties: success: type: boolean example: true data: type: array items: $ref: "#/components/schemas/AccountApplication" required: - success - data "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/accounts/v1/enterprises/permission-nodes: get: tags: - Accounts summary: List enterprise permission nodes description: Static catalogue for the role editor UI. responses: "200": description: Permission node catalogue content: application/json: schema: type: object properties: success: type: boolean example: true data: type: array items: type: object properties: id: type: string label: type: string description: type: string category: type: string required: - id - label - description - category required: - success - data "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/accounts/v1/enterprises: get: tags: - Accounts summary: List enterprise organisations for the authenticated user description: Returns the enterprise organisations the caller belongs to, with effective permissions. responses: "200": description: List of enterprise organisations content: application/json: schema: type: object properties: success: type: boolean example: true data: type: array items: type: object properties: id: type: string example: org_abc123 name: type: string example: acme display_name: type: string example: Acme Inc branding: type: object properties: logo_url: type: string colors: type: object properties: primary: type: string page_background: type: string max_sso_connections: type: integer minimum: 0 example: 0 permissions: type: array items: type: string roles: type: array items: type: string is_owner: type: boolean required: - id - name - display_name - max_sso_connections - permissions - roles - is_owner required: - success - data "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/accounts/v1/enterprises/{orgId}: get: tags: - Accounts summary: Get an enterprise organisation's basic information parameters: - schema: type: string pattern: ^org_[A-Za-z0-9]{1,64}$ required: true name: orgId in: path responses: "200": description: Enterprise details content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object properties: id: type: string name: type: string display_name: type: string branding: type: object properties: logo_url: type: string colors: type: object properties: primary: type: string page_background: type: string max_sso_connections: type: integer minimum: 0 required: - id - name - display_name - max_sso_connections required: - success - data "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ApiError" "403": description: Insufficient permissions content: application/json: schema: $ref: "#/components/schemas/ApiError" "404": description: Enterprise not found content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" patch: tags: - Accounts summary: Update an enterprise organisation's display name parameters: - schema: type: string pattern: ^org_[A-Za-z0-9]{1,64}$ required: true name: orgId in: path requestBody: required: true content: application/json: schema: type: object properties: display_name: type: string minLength: 1 maxLength: 255 responses: "200": description: Updated enterprise details content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object properties: id: type: string name: type: string display_name: type: string branding: type: object properties: logo_url: type: string colors: type: object properties: primary: type: string page_background: type: string max_sso_connections: type: integer minimum: 0 required: - id - name - display_name - max_sso_connections required: - success - data "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ApiError" "403": description: Insufficient permissions content: application/json: schema: $ref: "#/components/schemas/ApiError" "404": description: Enterprise not found content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/accounts/v1/enterprises/{orgId}/roles: get: tags: - Accounts summary: List enterprise roles parameters: - schema: type: string pattern: ^org_[A-Za-z0-9]{1,64}$ required: true name: orgId in: path responses: "200": description: List of roles content: application/json: schema: type: object properties: success: type: boolean example: true data: type: array items: type: object properties: id: type: string pattern: ^r_[0-9a-f]{24}$ name: type: string description: type: string nullable: true permissions: type: array items: type: string created_at: type: string updated_at: type: string required: - id - name - description - permissions - created_at - updated_at required: - success - data "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ApiError" "403": description: Insufficient permissions content: application/json: schema: $ref: "#/components/schemas/ApiError" "404": description: Enterprise not found content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" post: tags: - Accounts summary: Create an enterprise role parameters: - schema: type: string pattern: ^org_[A-Za-z0-9]{1,64}$ required: true name: orgId in: path requestBody: required: true content: application/json: schema: type: object properties: name: type: string minLength: 1 maxLength: 128 description: type: string maxLength: 512 permissions: type: array items: type: string enum: - update:settings - read:members - add:members - update:members - remove:members - read:roles - create:roles - update:roles - delete:roles - read:domains - create:domains - delete:domains - verify:domains - read:identity_providers - create:identity_providers - delete:identity_providers - update:identity_provider_domains - update:identity_provider_apps minItems: 1 required: - name - permissions responses: "201": description: Role created content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object properties: id: type: string pattern: ^r_[0-9a-f]{24}$ name: type: string description: type: string nullable: true permissions: type: array items: type: string created_at: type: string updated_at: type: string required: - id - name - description - permissions - created_at - updated_at required: - success - data "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/ApiError" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ApiError" "403": description: Insufficient permissions content: application/json: schema: $ref: "#/components/schemas/ApiError" "404": description: Enterprise not found content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/accounts/v1/enterprises/{orgId}/roles/{roleId}: get: tags: - Accounts summary: Get an enterprise role parameters: - schema: type: string pattern: ^org_[A-Za-z0-9]{1,64}$ required: true name: orgId in: path - schema: type: string pattern: ^r_[0-9a-f]{24}$ required: true name: roleId in: path responses: "200": description: Role content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object properties: id: type: string pattern: ^r_[0-9a-f]{24}$ name: type: string description: type: string nullable: true permissions: type: array items: type: string created_at: type: string updated_at: type: string required: - id - name - description - permissions - created_at - updated_at required: - success - data "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ApiError" "403": description: Insufficient permissions content: application/json: schema: $ref: "#/components/schemas/ApiError" "404": description: Role not found content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" patch: tags: - Accounts summary: Update an enterprise role parameters: - schema: type: string pattern: ^org_[A-Za-z0-9]{1,64}$ required: true name: orgId in: path - schema: type: string pattern: ^r_[0-9a-f]{24}$ required: true name: roleId in: path requestBody: required: true content: application/json: schema: type: object properties: name: type: string minLength: 1 maxLength: 128 description: type: string nullable: true maxLength: 512 permissions: type: array items: type: string enum: - update:settings - read:members - add:members - update:members - remove:members - read:roles - create:roles - update:roles - delete:roles - read:domains - create:domains - delete:domains - verify:domains - read:identity_providers - create:identity_providers - delete:identity_providers - update:identity_provider_domains - update:identity_provider_apps minItems: 1 responses: "200": description: Updated role content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object properties: id: type: string pattern: ^r_[0-9a-f]{24}$ name: type: string description: type: string nullable: true permissions: type: array items: type: string created_at: type: string updated_at: type: string required: - id - name - description - permissions - created_at - updated_at required: - success - data "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ApiError" "403": description: Insufficient permissions content: application/json: schema: $ref: "#/components/schemas/ApiError" "404": description: Role not found content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" delete: tags: - Accounts summary: Delete an enterprise role parameters: - schema: type: string pattern: ^org_[A-Za-z0-9]{1,64}$ required: true name: orgId in: path - schema: type: string pattern: ^r_[0-9a-f]{24}$ required: true name: roleId in: path responses: "200": description: Role deleted content: application/json: schema: $ref: "#/components/schemas/ApiSuccess" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ApiError" "403": description: Insufficient permissions content: application/json: schema: $ref: "#/components/schemas/ApiError" "404": description: Role not found content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/accounts/v1/enterprises/{orgId}/members: get: tags: - Accounts summary: List enterprise members parameters: - schema: type: string pattern: ^org_[A-Za-z0-9]{1,64}$ required: true name: orgId in: path responses: "200": description: List of members content: application/json: schema: type: object properties: success: type: boolean example: true data: type: array items: type: object properties: user_id: type: string name: type: string email: type: string picture: type: string roles: type: array items: type: object properties: id: type: string pattern: ^r_[0-9a-f]{24}$ name: type: string required: - id - name required: - user_id - roles required: - success - data "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ApiError" "403": description: Insufficient permissions content: application/json: schema: $ref: "#/components/schemas/ApiError" "404": description: Enterprise not found content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/accounts/v1/enterprises/{orgId}/members/{userId}/roles: put: tags: - Accounts summary: Assign roles to a member parameters: - schema: type: string pattern: ^org_[A-Za-z0-9]{1,64}$ required: true name: orgId in: path - schema: type: string pattern: ^[A-Za-z0-9_.@|-]{1,256}$ required: true name: userId in: path requestBody: required: true content: application/json: schema: type: object properties: roles: type: array items: type: string pattern: ^r_[0-9a-f]{24}$ required: - roles responses: "200": description: Member roles updated content: application/json: schema: $ref: "#/components/schemas/ApiSuccess" "400": description: Unknown role content: application/json: schema: $ref: "#/components/schemas/ApiError" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ApiError" "403": description: Insufficient permissions content: application/json: schema: $ref: "#/components/schemas/ApiError" "404": description: Enterprise not found content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/accounts/v1/enterprises/{orgId}/members/{userId}: delete: tags: - Accounts summary: Remove a member from an enterprise parameters: - schema: type: string pattern: ^org_[A-Za-z0-9]{1,64}$ required: true name: orgId in: path - schema: type: string pattern: ^[A-Za-z0-9_.@|-]{1,256}$ required: true name: userId in: path responses: "200": description: Member removed content: application/json: schema: $ref: "#/components/schemas/ApiSuccess" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ApiError" "403": description: Insufficient permissions content: application/json: schema: $ref: "#/components/schemas/ApiError" "404": description: Enterprise not found content: application/json: schema: $ref: "#/components/schemas/ApiError" "409": description: Cannot remove the owner content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/accounts/v1/enterprises/{orgId}/invitations: get: tags: - Accounts summary: List pending enterprise invitations parameters: - schema: type: string pattern: ^org_[A-Za-z0-9]{1,64}$ required: true name: orgId in: path responses: "200": description: List of invitations content: application/json: schema: type: object properties: success: type: boolean example: true data: type: array items: type: object properties: id: type: string email: type: string nullable: true roles: type: array items: type: string token: type: string invite_link: type: string uses: type: integer max_uses: type: integer nullable: true expires_at: type: string nullable: true created_at: type: string invited_by: type: string email_sent: type: boolean required: - id - email - roles - token - invite_link - uses - max_uses - expires_at - created_at - invited_by required: - success - data "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ApiError" "403": description: Insufficient permissions content: application/json: schema: $ref: "#/components/schemas/ApiError" "404": description: Enterprise not found content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" post: tags: - Accounts summary: Create an enterprise invitation description: Creates a bound email invite or a shareable link when email is omitted. parameters: - schema: type: string pattern: ^org_[A-Za-z0-9]{1,64}$ required: true name: orgId in: path requestBody: required: true content: application/json: schema: type: object properties: email: type: string format: email roles: type: array items: type: string pattern: ^r_[0-9a-f]{24}$ default: [] max_uses: type: integer minimum: 1 expires_in_days: type: integer minimum: 1 maximum: 365 responses: "201": description: Invitation created content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object properties: id: type: string email: type: string nullable: true roles: type: array items: type: string token: type: string invite_link: type: string uses: type: integer max_uses: type: integer nullable: true expires_at: type: string nullable: true created_at: type: string invited_by: type: string email_sent: type: boolean required: - id - email - roles - token - invite_link - uses - max_uses - expires_at - created_at - invited_by required: - success - data "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/ApiError" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ApiError" "403": description: Insufficient permissions content: application/json: schema: $ref: "#/components/schemas/ApiError" "404": description: Enterprise not found content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/accounts/v1/enterprises/{orgId}/invitations/bulk: post: tags: - Accounts summary: Bulk invite members by email parameters: - schema: type: string pattern: ^org_[A-Za-z0-9]{1,64}$ required: true name: orgId in: path requestBody: required: true content: application/json: schema: type: object properties: invitations: type: array items: type: object properties: email: type: string format: email roles: type: array items: type: string pattern: ^r_[0-9a-f]{24}$ default: [] required: - email minItems: 1 maxItems: 200 required: - invitations responses: "200": description: Per-row bulk invite results content: application/json: schema: type: object properties: success: type: boolean example: true data: type: array items: type: object properties: email: type: string status: type: string enum: - invited - skipped - failed reason: type: string email_sent: type: boolean required: - email - status required: - success - data "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/ApiError" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ApiError" "403": description: Insufficient permissions content: application/json: schema: $ref: "#/components/schemas/ApiError" "404": description: Enterprise not found content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/accounts/v1/enterprises/{orgId}/invitations/{invitationId}: delete: tags: - Accounts summary: Revoke a pending enterprise invitation parameters: - schema: type: string pattern: ^org_[A-Za-z0-9]{1,64}$ required: true name: orgId in: path - schema: type: string minLength: 1 maxLength: 128 required: true name: invitationId in: path responses: "200": description: Invitation revoked content: application/json: schema: $ref: "#/components/schemas/ApiSuccess" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ApiError" "403": description: Insufficient permissions content: application/json: schema: $ref: "#/components/schemas/ApiError" "404": description: Enterprise not found content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/accounts/v1/enterprises/{orgId}/domains: get: tags: - Accounts summary: List an enterprise's email domains parameters: - schema: type: string pattern: ^org_[A-Za-z0-9]{1,64}$ required: true name: orgId in: path responses: "200": description: List of domains content: application/json: schema: type: object properties: success: type: boolean example: true data: type: array items: type: object properties: id: type: string domain: type: string verified: type: boolean verification: type: object properties: type: type: string enum: - TXT name: type: string value: type: string required: - type - name - value required: - id - domain - verified required: - success - data "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ApiError" "403": description: Insufficient permissions content: application/json: schema: $ref: "#/components/schemas/ApiError" "404": description: Enterprise not found content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" post: tags: - Accounts summary: Add an email domain to an enterprise parameters: - schema: type: string pattern: ^org_[A-Za-z0-9]{1,64}$ required: true name: orgId in: path requestBody: required: true content: application/json: schema: type: object properties: domain: type: string pattern: ^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,}$/i required: - domain responses: "201": description: Domain added content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object properties: id: type: string domain: type: string verified: type: boolean verification: type: object properties: type: type: string enum: - TXT name: type: string value: type: string required: - type - name - value required: - id - domain - verified required: - success - data "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ApiError" "403": description: Insufficient permissions content: application/json: schema: $ref: "#/components/schemas/ApiError" "404": description: Enterprise not found content: application/json: schema: $ref: "#/components/schemas/ApiError" "409": description: Domain already added content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/accounts/v1/enterprises/{orgId}/domains/{domainId}: delete: tags: - Accounts summary: Remove an email domain from an enterprise parameters: - schema: type: string pattern: ^org_[A-Za-z0-9]{1,64}$ required: true name: orgId in: path - schema: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ required: true name: domainId in: path responses: "200": description: Domain removed content: application/json: schema: $ref: "#/components/schemas/ApiSuccess" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ApiError" "403": description: Insufficient permissions content: application/json: schema: $ref: "#/components/schemas/ApiError" "404": description: Enterprise not found content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/accounts/v1/enterprises/{orgId}/domains/{domainId}/verify: post: tags: - Accounts summary: Verify ownership of an enterprise email domain via DNS description: "Resolves the domain's DNS TXT challenge and marks it verified when the record matches. A domain whose record has not been published (or has not propagated yet) returns 200 with `verified: false`, and may be retried." parameters: - schema: type: string pattern: ^org_[A-Za-z0-9]{1,64}$ required: true name: orgId in: path - schema: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ required: true name: domainId in: path responses: "200": description: Current domain verification status content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object properties: id: type: string domain: type: string verified: type: boolean verification: type: object properties: type: type: string enum: - TXT name: type: string value: type: string required: - type - name - value required: - id - domain - verified required: - success - data "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ApiError" "403": description: Insufficient permissions content: application/json: schema: $ref: "#/components/schemas/ApiError" "404": description: Enterprise not found content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/accounts/v1/enterprises/{orgId}/identity-providers: get: tags: - Accounts summary: List enterprise single sign-on identity providers parameters: - schema: type: string pattern: ^org_[A-Za-z0-9]{1,64}$ required: true name: orgId in: path responses: "200": description: List of identity providers content: application/json: schema: type: object properties: success: type: boolean example: true data: type: array items: type: object properties: id: type: string name: type: string display_name: type: string strategy: type: string created_at: type: string domain_aliases: type: array items: type: string required: - id - domain_aliases required: - success - data "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ApiError" "403": description: Insufficient permissions content: application/json: schema: $ref: "#/components/schemas/ApiError" "404": description: Enterprise not found content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" post: tags: - Accounts summary: Create an enterprise SSO connection description: Creates and enables an enterprise identity provider from admin-supplied configuration, using the Auth0 Management API. parameters: - schema: type: string pattern: ^org_[A-Za-z0-9]{1,64}$ required: true name: orgId in: path requestBody: required: true content: application/json: schema: oneOf: - type: object properties: strategy: type: string enum: - samlp display_name: type: string minLength: 1 maxLength: 120 sign_in_url: type: string format: uri signing_cert: type: string minLength: 1 sign_out_url: type: string format: uri required: - strategy - display_name - sign_in_url - signing_cert - type: object properties: strategy: type: string enum: - keycloak-samlp display_name: type: string minLength: 1 maxLength: 120 sign_in_url: type: string format: uri signing_cert: type: string minLength: 1 sign_out_url: type: string format: uri required: - strategy - display_name - sign_in_url - signing_cert - type: object properties: strategy: type: string enum: - pingfederate display_name: type: string minLength: 1 maxLength: 120 sign_in_url: type: string format: uri signing_cert: type: string minLength: 1 sign_out_url: type: string format: uri required: - strategy - display_name - sign_in_url - signing_cert - type: object properties: strategy: type: string enum: - adfs display_name: type: string minLength: 1 maxLength: 120 sign_in_url: type: string format: uri required: - strategy - display_name - sign_in_url - type: object properties: strategy: type: string enum: - oidc display_name: type: string minLength: 1 maxLength: 120 discovery_url: type: string format: uri client_id: type: string minLength: 1 client_secret: type: string minLength: 1 scopes: type: string required: - strategy - display_name - discovery_url - client_id - client_secret - type: object properties: strategy: type: string enum: - okta display_name: type: string minLength: 1 maxLength: 120 domain: type: string minLength: 1 maxLength: 255 client_id: type: string minLength: 1 client_secret: type: string minLength: 1 scopes: type: string required: - strategy - display_name - domain - client_id - client_secret - type: object properties: strategy: type: string enum: - waad display_name: type: string minLength: 1 maxLength: 120 domain: type: string minLength: 1 maxLength: 255 client_id: type: string minLength: 1 client_secret: type: string minLength: 1 scopes: type: string required: - strategy - display_name - domain - client_id - client_secret - type: object properties: strategy: type: string enum: - google-apps display_name: type: string minLength: 1 maxLength: 120 domain: type: string minLength: 1 maxLength: 255 client_id: type: string minLength: 1 client_secret: type: string minLength: 1 scopes: type: string required: - strategy - display_name - domain - client_id - client_secret responses: "201": description: Identity provider created content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object properties: id: type: string name: type: string display_name: type: string strategy: type: string created_at: type: string domain_aliases: type: array items: type: string required: - id - domain_aliases required: - success - data "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ApiError" "403": description: Insufficient permissions content: application/json: schema: $ref: "#/components/schemas/ApiError" "404": description: Enterprise not found content: application/json: schema: $ref: "#/components/schemas/ApiError" "409": description: SSO connection limit reached content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/accounts/v1/enterprises/{orgId}/identity-providers/{idpId}: get: tags: - Accounts summary: Get a single enterprise identity provider parameters: - schema: type: string pattern: ^org_[A-Za-z0-9]{1,64}$ required: true name: orgId in: path - schema: type: string pattern: ^con_[A-Za-z0-9]{1,64}$ required: true name: idpId in: path responses: "200": description: Identity provider content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object properties: id: type: string name: type: string display_name: type: string strategy: type: string created_at: type: string domain_aliases: type: array items: type: string required: - id - domain_aliases required: - success - data "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ApiError" "403": description: Insufficient permissions content: application/json: schema: $ref: "#/components/schemas/ApiError" "404": description: Enterprise not found content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" delete: tags: - Accounts summary: Remove an enterprise SSO connection parameters: - schema: type: string pattern: ^org_[A-Za-z0-9]{1,64}$ required: true name: orgId in: path - schema: type: string pattern: ^con_[A-Za-z0-9]{1,64}$ required: true name: idpId in: path responses: "200": description: Identity provider removed content: application/json: schema: $ref: "#/components/schemas/ApiSuccess" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ApiError" "403": description: Insufficient permissions content: application/json: schema: $ref: "#/components/schemas/ApiError" "404": description: Enterprise not found content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/accounts/v1/enterprises/{orgId}/identity-providers/{idpId}/allowed-apps: get: tags: - Accounts summary: List applications allowed to use an SSO connection parameters: - schema: type: string pattern: ^org_[A-Za-z0-9]{1,64}$ required: true name: orgId in: path - schema: type: string pattern: ^con_[A-Za-z0-9]{1,64}$ required: true name: idpId in: path responses: "200": description: List of applications content: application/json: schema: type: object properties: success: type: boolean example: true data: type: array items: type: object properties: client_id: type: string name: type: string logo_uri: type: string nullable: true enabled: type: boolean required: - client_id - name - logo_uri - enabled required: - success - data "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ApiError" "403": description: Insufficient permissions content: application/json: schema: $ref: "#/components/schemas/ApiError" "404": description: Enterprise not found content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" patch: tags: - Accounts summary: Update the applications allowed to use an SSO connection parameters: - schema: type: string pattern: ^org_[A-Za-z0-9]{1,64}$ required: true name: orgId in: path - schema: type: string pattern: ^con_[A-Za-z0-9]{1,64}$ required: true name: idpId in: path requestBody: required: true content: application/json: schema: type: array items: type: object properties: client_id: type: string status: type: boolean required: - client_id - status maxItems: 100 responses: "200": description: Applications updated content: application/json: schema: $ref: "#/components/schemas/ApiSuccess" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ApiError" "403": description: Insufficient permissions content: application/json: schema: $ref: "#/components/schemas/ApiError" "404": description: Enterprise not found content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/accounts/v1/enterprises/{orgId}/identity-providers/{idpId}/domains: put: tags: - Accounts summary: Set the email domains routed to an SSO connection (Home Realm Discovery) description: Assigns which of the enterprise's verified domains route to this connection. Each domain must be a verified enterprise domain. parameters: - schema: type: string pattern: ^org_[A-Za-z0-9]{1,64}$ required: true name: orgId in: path - schema: type: string pattern: ^con_[A-Za-z0-9]{1,64}$ required: true name: idpId in: path requestBody: required: true content: application/json: schema: type: object properties: domains: type: array items: type: string maxItems: 100 required: - domains responses: "200": description: Updated identity provider content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object properties: id: type: string name: type: string display_name: type: string strategy: type: string created_at: type: string domain_aliases: type: array items: type: string required: - id - domain_aliases required: - success - data "400": description: A domain is not verified for this enterprise content: application/json: schema: $ref: "#/components/schemas/ApiError" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ApiError" "403": description: Insufficient permissions content: application/json: schema: $ref: "#/components/schemas/ApiError" "404": description: Enterprise not found content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/accounts/v1/enterprises/{orgId}/permissions: get: tags: - Accounts summary: Get the caller's effective permissions within an enterprise parameters: - schema: type: string pattern: ^org_[A-Za-z0-9]{1,64}$ required: true name: orgId in: path responses: "200": description: Effective permissions content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object properties: permissions: type: array items: type: string roles: type: array items: type: string is_owner: type: boolean owner_id: type: string nullable: true required: - permissions - roles - is_owner - owner_id required: - success - data "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ApiError" "403": description: Insufficient permissions content: application/json: schema: $ref: "#/components/schemas/ApiError" "404": description: Enterprise not found content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/accounts/v1/enterprises/{orgId}/permissions/owner: put: tags: - Accounts summary: Transfer ownership of an enterprise parameters: - schema: type: string pattern: ^org_[A-Za-z0-9]{1,64}$ required: true name: orgId in: path requestBody: required: true content: application/json: schema: type: object properties: user_id: type: string pattern: ^[A-Za-z0-9_.@|-]{1,256}$ required: - user_id responses: "200": description: Ownership transferred content: application/json: schema: $ref: "#/components/schemas/ApiSuccess" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ApiError" "403": description: Insufficient permissions content: application/json: schema: $ref: "#/components/schemas/ApiError" "404": description: Enterprise not found content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/accounts/v1/me/email: post: tags: - Accounts summary: Request a change of the authenticated user's email address description: Mails a confirmation code to the requested address. Nothing changes until the code is confirmed. requestBody: required: true content: application/json: schema: type: object properties: email: type: string maxLength: 320 format: email example: new@example.com required: - email responses: "202": description: Confirmation code sent to the requested address content: application/json: schema: $ref: "#/components/schemas/ApiSuccess" "400": description: Invalid request, or not a database identity content: application/json: schema: $ref: "#/components/schemas/ApiError" "409": description: Address already in use content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/accounts/v1/me/email/confirm: post: tags: - Accounts summary: Confirm a pending email address change requestBody: required: true content: application/json: schema: type: object properties: code: type: string pattern: ^[0-9]{6}$ example: "418902" required: - code responses: "200": description: Email address changed content: application/json: schema: $ref: "#/components/schemas/ApiSuccess" "400": description: Code incorrect, expired, or no pending request content: application/json: schema: $ref: "#/components/schemas/ApiError" "409": description: Address was taken before the change was confirmed content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/accounts/v1/invitations/accept: post: tags: - Accounts summary: Accept an enterprise invitation description: Redeems an invitation token. The caller must be authenticated with a verified email. requestBody: required: true content: application/json: schema: type: object properties: token: type: string minLength: 1 maxLength: 256 required: - token responses: "200": description: Invitation accepted content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object properties: org_id: type: string enterprise_name: type: string already_member: type: boolean required: - org_id - enterprise_name - already_member required: - success - data "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ApiError" "403": description: Email mismatch content: application/json: schema: $ref: "#/components/schemas/ApiError" "404": description: Invitation not found content: application/json: schema: $ref: "#/components/schemas/ApiError" "409": description: Invitation exhausted content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/cloud/v0/version: get: tags: - Cloud operationId: cloudGetVersion summary: Get API version security: - Bearer: [] responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudVersion" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/tc-pp: get: tags: - Cloud operationId: cloudGetTCPP summary: Get the list of urls related to T&C and Privacy Policies security: - Bearer: [] responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudTCPP" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/support_plans: get: tags: - Cloud operationId: cloudGetSupportPlans summary: List available support plans description: Retrieve all available support plans. security: - Bearer: [] responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudSupportPlans" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/message: get: tags: - Cloud operationId: cloudGetSystemMessage summary: Get the last system message security: - Bearer: [] CloudToken: [] - Bearer: [] responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudSystemMessage" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/spectron_context_packages: get: tags: - Cloud operationId: cloudGetSpectronContextPackages summary: List available Context packages description: Retrieve all available Context packages. security: - Bearer: [] CloudToken: [] - Bearer: [] responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudSpectronContextPackages" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/regions: get: tags: - Cloud operationId: cloudGetRegions summary: Get regions security: - Bearer: [] CloudToken: [] - Bearer: [] responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudRegions" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/context_regions: get: tags: - Cloud operationId: cloudGetContextRegions summary: Get regions security: - Bearer: [] CloudToken: [] - Bearer: [] responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudRegions" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/instanceversions: get: tags: - Cloud operationId: cloudGetInstanceVersions summary: Get instance versions description: Get instances versions security: - Bearer: [] CloudToken: [] - Bearer: [] responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudInstanceVersions" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/instancetypes: get: tags: - Cloud operationId: cloudGetInstanceTypes summary: Get instances types security: - Bearer: [] CloudToken: [] - Bearer: [] responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudInstanceTypes" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/storageinstancetypes: get: tags: - Cloud operationId: cloudGetStorageInstanceTypes summary: Get storage instances types security: - Bearer: [] CloudToken: [] - Bearer: [] responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudInstanceTypes" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/billingcountries: get: tags: - Cloud operationId: cloudGetBillingCountries summary: Get billing countries security: - Bearer: [] CloudToken: [] - Bearer: [] responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudBillingCountries" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/signin: post: tags: - Cloud operationId: cloudSignIn summary: Sign in. description: Sign-in an existing user given an access token. security: - Bearer: [] parameters: - schema: type: string required: false name: referral in: query - schema: type: string required: false name: aws_token in: query - schema: type: string required: false name: azure_token in: query - schema: type: string required: false name: invitation in: query requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CloudToken" responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudLoginInfo" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Token expired content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Invalid token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "422": description: Invalid data in request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/refresh: post: tags: - Cloud operationId: cloudRefresh summary: Get an access token from a refresh token. description: Get a new access and refresh token from a refresh token. security: - Bearer: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CloudRefreshToken" responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudRefreshTokenInfo" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Token expired content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Invalid token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/user/profile: get: tags: - Cloud operationId: cloudGetUserProfile summary: Get user profile security: - Bearer: [] CloudToken: [] - Bearer: [] responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudUserProfile" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" patch: tags: - Cloud operationId: cloudUpdateUserProfile summary: Update user profile security: - Bearer: [] CloudToken: [] - Bearer: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CloudUpdateUserProfile" responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudUserProfile" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "422": description: Invalid data in request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/user/terms-accepted: patch: tags: - Cloud operationId: cloudSetUserTermsAccepted summary: Sets the user terms accepted to the current date security: - Bearer: [] CloudToken: [] - Bearer: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CloudTerms" responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudEmptyBody" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "422": description: Invalid data in request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/user/form: get: tags: - Cloud operationId: cloudGetFormQuestions summary: Get the questions for the current questionary form security: - Bearer: [] CloudToken: [] - Bearer: [] responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudForm" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" post: tags: - Cloud operationId: cloudSetFormAnswers summary: Saves the answers of an user to the current questionary form security: - Bearer: [] CloudToken: [] - Bearer: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CloudFormAnswers" responses: "200": description: Answers saved content: application/json: schema: $ref: "#/components/schemas/CloudEmptyBody" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/user/referrals: get: tags: - Cloud operationId: cloudGetReferrals summary: Get the referrals information of the user for the current active campaign security: - Bearer: [] CloudToken: [] - Bearer: [] responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudReferralsInfo" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "409": description: No active referral campaign content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/user/referrals/code: get: tags: - Cloud operationId: cloudGetReferralCode summary: Get the referral code of the user for current active campaign security: - Bearer: [] CloudToken: [] - Bearer: [] responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudReferralCode" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "409": description: No active referral campaign content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/organizations: get: tags: - Cloud operationId: cloudGetOrganizations summary: Get the organizations of the user description: Get the organizations of the user security: - Bearer: [] CloudToken: [] - Bearer: [] responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudOrganizations" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" post: tags: - Cloud operationId: cloudCreateOrganization summary: Create a new organzation description: Create a new organization where the user is the main user of the org. security: - Bearer: [] CloudToken: [] - Bearer: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CloudCreateOrganization" responses: "201": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudOrganization" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "422": description: Invalid data in request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/organizations/{orgID}: get: tags: - Cloud operationId: cloudGetOrganization summary: Get organization security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudOrganization" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "404": description: Organization not found content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" patch: tags: - Cloud operationId: cloudUpdateOrganization summary: Update organization security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CloudUpdateOrganization" responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudOrganization" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "422": description: Invalid data in request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/organizations/{orgID}/archive: patch: tags: - Cloud operationId: cloudArchiveOrganization summary: Archive an organization security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path responses: "202": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudEmptyBody" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/organizations/{orgID}/support_plans: get: tags: - Cloud operationId: cloudGetOrganizationSupportPlans summary: Retrieves the support plans assigned to the organization security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudOrganizationSupportPlans" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "404": description: Organization not found content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/organizations/{orgID}/roles: get: tags: - Cloud operationId: cloudGetOrganizationRoles summary: Retrieves all the roles for a given organization security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudRoles" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/organizations/{orgID}/me/permissions: get: tags: - Cloud operationId: cloudGetMyOrganizationPermissions summary: Returns the caller's resolved permissions (capabilities) in the organization. description: The union of the caller's role (RBAC) and resource (ABAC) permissions, for capability-driven UI gating. security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudMyPermissions" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/organizations/{orgID}/members: get: tags: - Cloud operationId: cloudGetOrganizationMembers summary: Retrieves all the members for a given organization security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudOrganizationMembers" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/organizations/{orgID}/members/{memberID}: patch: tags: - Cloud operationId: cloudUpdateOrganizationMember summary: Changes the role of a member from a given organization security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: memberID in: path requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CloudUpdateOrganizationMember" responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudOrganizationMember" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "422": description: Invalid data in request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" delete: tags: - Cloud operationId: cloudRemoveOrganizationMember summary: Removes a member from a given organization security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: memberID in: path responses: "202": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudEmptyBody" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "422": description: Invalid data in request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/organizations/{orgID}/instances: get: tags: - Cloud operationId: cloudGetInstances summary: Retrieves all the instances of a given organization description: Retrieves all the instances of a given organization security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudInstances" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/organizations/{orgID}/usage: get: tags: - Cloud operationId: cloudGetOrganizationUsage summary: Gets the usage of all instances for the organization security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudOrganizationUsage" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/organizations/{orgID}/spend: get: tags: - Cloud operationId: cloudGetOrganizationSpend summary: Gets the breakdown of "cloud usage credits" spend for the organization description: Gets the credit usage of an organization security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path - schema: type: string pattern: ^(0[1-9]|1[0-2])-\d{4}$ description: Period to retrieve usage for in MM-YYYY format (e.g., '03-2026' for March 2026). If not provided, defaults to current month. example: 03-2026 required: false description: Period to retrieve usage for in MM-YYYY format (e.g., '03-2026' for March 2026). If not provided, defaults to current month. name: period in: query responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudOrganizationSpend" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "422": description: Invalid data in request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/organizations/{orgID}/invitations: get: tags: - Cloud operationId: cloudGetOrganizationInvitations summary: Gets all the active invitations for the organization security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudInvitations" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" post: tags: - Cloud operationId: cloudCreateOrganizationInvitation summary: Creates an invitation within the organization security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CloudCreateInvitation" responses: "201": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudInvitation" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "422": description: Invalid data in request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/organizations/{orgID}/invitations/{invitationCode}: delete: tags: - Cloud operationId: cloudDeleteOrganizationInvitation summary: Deletes a user invitation within an organization security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: bvh68e6f1t543aru8nvj34guh8 required: true name: invitationCode in: path responses: "202": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudEmptyBody" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/organizations/{orgID}/billing: get: tags: - Cloud operationId: cloudGetOrganizationBillingInfo summary: Gets the billing record for an organization security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudGetBillingInfo" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" put: tags: - Cloud operationId: cloudSetOrganizationBillingInfo summary: Creates or updates a billing record for an organization security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CloudPutBillingInfo" responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudEmptyBody" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "422": description: Invalid data in request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/organizations/{orgID}/billing/invoices: get: tags: - Cloud operationId: cloudGetOrganizationInvoices summary: Gets the invoices of an organization security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudInvoices" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/organizations/{orgID}/billing/coupons: get: tags: - Cloud operationId: cloudGetOrganizationCoupons summary: Gets the coupons applied to an organization security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudCouponsInfo" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/organizations/{orgID}/coupon: post: tags: - Cloud operationId: cloudApplyOrganizationCoupon summary: Applies a coupon code to an organization security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CloudCoupon" responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudEmptyBody" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "412": description: Coupon cannot be applied to this organization content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "422": description: Invalid data in request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/organizations/{orgID}/payment: get: tags: - Cloud operationId: cloudGetOrganizationPaymentInfo summary: Gets the payment info of an organization security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudGetPaymentInfo" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" put: tags: - Cloud operationId: cloudSetOrganizationPaymentInfo summary: Checks if the payment info is complete and updates the organization accordingly security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudPaymentInfo" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "409": description: Payment info is not complete content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/organizations/{orgID}/payment/url: get: tags: - Cloud operationId: cloudGetOrganizationPaymentURL summary: Gets the url that can be used to gather the payment info of an organization security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudPaymentURL" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "422": description: Invalid data in request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/organizations/{orgID}/plan: patch: tags: - Cloud operationId: cloudUpdateOrganizationPlan summary: Updates the plan for a given organization description: Updates the plan for the specified organization security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CloudUpdatePlan" responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudEmptyBody" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "422": description: Invalid data in request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/instance_cost: put: tags: - Cloud operationId: cloudGetInstanceEstimatedCost summary: Returns the estimated monthly cost of an instance (in USD dollars) security: - Bearer: [] CloudToken: [] - Bearer: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CloudCreateInstance" responses: "202": description: Operation accepted content: application/json: schema: $ref: "#/components/schemas/CloudInstanceCost" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "422": description: Invalid data in request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/instances: post: tags: - Cloud operationId: cloudCreateInstance summary: Creates a new instance description: Creates a new instance of the given type in the specified region and organization security: - Bearer: [] CloudToken: [] - Bearer: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CloudCreateInstance" responses: "202": description: Operation accepted content: application/json: schema: $ref: "#/components/schemas/CloudInstance" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "412": description: Organization is not ready to deploy this instance content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "422": description: Invalid data in request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/instances/{instanceID}: get: tags: - Cloud operationId: cloudGetInstance summary: Retrieves an instance giving its ID. security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: instanceID in: path responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudInstance" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "404": description: Instance not found content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" delete: tags: - Cloud operationId: cloudDeleteInstance summary: Deletes an instance given its ID. security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: instanceID in: path responses: "202": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudEmptyBody" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "409": description: Instance cannot be deleted in its current state content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/instances/{instanceID}/type: patch: tags: - Cloud operationId: cloudUpdateInstanceType summary: Updates the type of an instance security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: instanceID in: path requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CloudUpdateInstanceType" responses: "202": description: Operation accepted content: application/json: schema: $ref: "#/components/schemas/CloudInstance" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "409": description: Instance cannot be updated in its current state content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "422": description: Invalid data in request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/instances/{instanceID}/computeunits: patch: tags: - Cloud operationId: cloudUpdateInstanceComputeUnits summary: Updates the compute units of an instance security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: instanceID in: path requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CloudUpdateInstanceComputeUnits" responses: "202": description: Operation accepted content: application/json: schema: $ref: "#/components/schemas/CloudInstance" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "422": description: Invalid data in request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/instances/{instanceID}/storagesize: patch: tags: - Cloud operationId: cloudUpdateInstanceStorageSize summary: Updates the storage size (gb) of an instance description: Updates the storage size of an instance security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: instanceID in: path requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CloudUpdateInstanceStorageSize" responses: "202": description: Operation accepted content: application/json: schema: $ref: "#/components/schemas/CloudInstance" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "422": description: Invalid data in request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/instances/{instanceID}/version: patch: tags: - Cloud operationId: cloudUpdateInstanceVersion summary: Updates the version of SurrealDB of an instance description: Updates the version of SurrealDB that an instance is running security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: instanceID in: path requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CloudUpdateInstanceVersion" responses: "202": description: Operation accepted content: application/json: schema: $ref: "#/components/schemas/CloudInstance" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "409": description: Instance cannot be updated in its current state content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "422": description: Invalid data in request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/instances/{instanceID}/access_type: patch: tags: - Cloud operationId: cloudUpdateInstanceAccessType summary: Updates the access type of an instance description: > Updates the access type of an instance (public, private, dual). Changing to private or dual requires organization PrivateLink enabled and region support. security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: instanceID in: path requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CloudUpdateInstanceAccessType" responses: "202": description: Operation accepted content: application/json: schema: $ref: "#/components/schemas/CloudInstance" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "409": description: Instance cannot be updated in its current state content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "422": description: Invalid data in request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/instances/{instanceID}/capabilities: put: tags: - Cloud operationId: cloudUpdateInstanceCapabilities summary: Updates the config of a SurrealDB instance security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: instanceID in: path requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CloudCapabilitiesConfig" responses: "202": description: Operation accepted content: application/json: schema: $ref: "#/components/schemas/CloudInstance" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "409": description: Instance cannot be updated in its current state content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "422": description: Invalid data in request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/instances/{instanceID}/distributed_storage_spec: put: tags: - Cloud operationId: cloudUpdateInstanceDistributedStorageSpec summary: Updates the distributed storage config of a SurrealDB instance security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: instanceID in: path requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CloudInstanceDistributedStorageSpecs" responses: "202": description: Operation accepted content: application/json: schema: $ref: "#/components/schemas/CloudInstance" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "409": description: Instance cannot be updated in its current state content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "422": description: Invalid data in request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/instances/{instanceID}/auth: get: tags: - Cloud operationId: cloudGetInstanceAuth summary: Gets information about the authentication of an instance security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: instanceID in: path responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudInstanceAuth" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "409": description: Instance is not in a state that can issue a token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/instances/{instanceID}/.well-known/jwks.json: get: tags: - Cloud operationId: cloudGetInstanceJwks summary: Gets the jwks file for verifying JWTs for an instance. security: - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: instanceID in: path responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudJwks" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/instances/{instanceID}/usage: get: tags: - Cloud operationId: cloudGetInstanceUsage summary: Get Instance usage description: Gets the usage for an instance security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: instanceID in: path responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudInstanceUsage" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/instances/{instanceID}/status: get: tags: - Cloud operationId: cloudGetInstanceStatus summary: Get Instance status description: Gets the status for an instance security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: instanceID in: path responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudInstanceStatus" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/instances/{instanceID}/backuppolicy: get: tags: - Cloud operationId: cloudGetInstanceBackupPolicy summary: Get the backup policy of an instance description: Returns the materialized retention values, the resolved bounds, and a per-tier editable flag. security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: instanceID in: path responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudInstanceBackupPolicyResponse" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "404": description: Instance not found content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" patch: tags: - Cloud operationId: cloudUpdateInstanceBackupPolicy summary: Update the backup policy of an instance description: > Sets per-tier retention values, validated against the resolved (min, max) bounds. Each field is optional. A field set to `null` resets the tier to the instance type's default. security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: instanceID in: path requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CloudUpdateInstanceBackupPolicyRequest" responses: "202": description: Operation accepted content: application/json: schema: $ref: "#/components/schemas/CloudInstanceBackupPolicyResponse" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "404": description: Instance not found content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "422": description: Invalid data in request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/instances/{instanceID}/backups: post: tags: - Cloud operationId: cloudTriggerOnDemandBackup summary: Trigger an on-demand backup description: Triggers an on-demand backup for the instance. security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: instanceID in: path responses: "202": description: Backup request accepted content: application/json: schema: $ref: "#/components/schemas/CloudEmptyBody" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/instances/{instanceID}/pause: post: tags: - Cloud operationId: cloudPauseInstance summary: Pauses the instance description: Pauses an instance security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: instanceID in: path responses: "202": description: Operation accepted content: application/json: schema: $ref: "#/components/schemas/CloudInstance" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "409": description: Instance cannot be paused in its current state content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/instances/{instanceID}/resume: post: tags: - Cloud operationId: cloudResumeInstance summary: Resumes the instance description: Resumes a paused instance security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: instanceID in: path responses: "202": description: Operation accepted content: application/json: schema: $ref: "#/components/schemas/CloudInstance" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "409": description: Instance cannot be resumed in its current state content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/instances/{instanceID}/metrics: get: tags: - Cloud operationId: cloudGetInstanceMetrics summary: Get Instance metrics description: Gets the metrics for an instance security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: instanceID in: path - schema: type: string example: cpu required: true name: metric in: query - schema: type: string format: date-time required: false name: from_time in: query - schema: type: string format: date-time required: false name: to_time in: query - schema: type: boolean default: false required: false name: dummy_data in: query responses: "200": description: Operation accepted content: application/json: schema: $ref: "#/components/schemas/CloudInstanceMetrics" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "422": description: Invalid data in request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/instances/{instanceID}/logs: get: tags: - Cloud operationId: cloudGetInstanceLogs summary: Get Instance logs description: Gets the logs for an instance security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: instanceID in: path - schema: type: string format: date-time required: false name: from_time in: query - schema: type: string format: date-time required: false name: to_time in: query - schema: type: string enum: - dummy_data required: false name: category in: query responses: "200": description: Operation accepted content: application/json: schema: $ref: "#/components/schemas/CloudInstanceLogs" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "422": description: Invalid data in request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/organizations/{orgID}/spectron_contexts: get: tags: - Cloud operationId: cloudGetOrgSpectronContexts summary: Get the Organization Contexts security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudSpectronContexts" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "422": description: Invalid data in request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "501": description: Spectron is not available on this deployment content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" post: tags: - Cloud operationId: cloudCreateSpectronContext summary: Create Context description: Creates a new Context security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CloudCreateSpectronContext" responses: "201": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudSpectronContext" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "422": description: Invalid data in request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "501": description: Spectron is not available on this deployment content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/organizations/{orgID}/spectron_contexts/{spectronContextID}: get: tags: - Cloud operationId: cloudRetrieveSpectronContext summary: Retrieves the Context giving its ID. security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: spectronContextID in: path responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudSpectronContext" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "422": description: Invalid data in request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "501": description: Spectron is not available on this deployment content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" patch: tags: - Cloud operationId: cloudUpdateSpectronContext summary: Updates a Context. description: Updates the Context. security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: spectronContextID in: path requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CloudUpdateSpectronContext" responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudSpectronContext" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "422": description: Invalid data in request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "501": description: Spectron is not available on this deployment content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" delete: tags: - Cloud operationId: cloudDeleteSpectronContext summary: Deletes a Context giving its ID. security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: spectronContextID in: path responses: "202": description: Operation accepted content: application/json: schema: $ref: "#/components/schemas/CloudEmptyBody" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "422": description: Invalid data in request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "501": description: Spectron is not available on this deployment content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/organizations/{orgID}/spectron_contexts/{spectronContextID}/api_keys: get: tags: - Cloud operationId: cloudGetSpectronContextApiKeys summary: Retrieve the list name and IDs for the API Keys for the Context. security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: spectronContextID in: path responses: "201": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudSpectronContextApiKeys" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "422": description: Invalid data in request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "501": description: Spectron is not available on this deployment content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" post: tags: - Cloud operationId: cloudCreateSpectronContextApiKey summary: Creates a user access API Key for the Context giving its ID. security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: spectronContextID in: path requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CloudCreateSpectronContextAPIKey" responses: "201": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudSpectronContextApiKey" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "409": description: An API key with that name already exists content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "422": description: Invalid data in request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "501": description: Spectron is not available on this deployment content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/organizations/{orgID}/spectron_contexts/{spectronContextID}/api_keys/{apiKeyID}: delete: tags: - Cloud operationId: cloudDeleteSpectronContextApiKey summary: Deletes a user access API Key for the Context. security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: spectronContextID in: path - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: apiKeyID in: path responses: "202": description: Deletion of Context API Key accepted content: application/json: schema: $ref: "#/components/schemas/CloudEmptyBody" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "422": description: Invalid data in request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "501": description: Spectron is not available on this deployment content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/organizations/{orgID}/spectron_contexts/{spectronContextID}/api_keys/{apiKeyID}/rotate: post: tags: - Cloud operationId: cloudRotateSpectronContextApiKey summary: Rotates a Spectron Context API key's secret in place. description: Proxies the Spectron management key-rotate endpoint; the new secret is returned once. security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: spectronContextID in: path - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: apiKeyID in: path responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudSpectronContextApiKey" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "404": description: API key not found content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "501": description: Spectron is not available on this deployment content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/organizations/{orgID}/spectron_contexts/{spectronContextID}/scoped_keys: post: tags: - Cloud operationId: cloudCreateSpectronContextScopedKey summary: Mints a scoped (principal-bound) API key for a Spectron Context. description: Proxies the Spectron management API scoped-key mint; the returned secret is shown once. security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: spectronContextID in: path requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CloudMintSpectronScopedKey" responses: "201": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudSpectronContextApiKey" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "404": description: Context or principal not found content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "409": description: A key with that name already exists content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "422": description: Invalid data in request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "501": description: Spectron is not available on this deployment content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/organizations/{orgID}/spectron_contexts/{spectronContextID}/access_tokens: post: tags: - Cloud operationId: cloudCreateSpectronContextAccessToken summary: Issues a Cloud-brokered, TTL-bounded access token for the caller's own principal. description: Members obtain Spectron access here rather than via the admin-only management API. cloud-api (holding the management key) create-or-gets the caller's own principal and mints a short-lived principal-bound token; SurrealDB Studio then connects directly to the Spectron instance. security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: spectronContextID in: path requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CloudMintSpectronAccessToken" responses: "201": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudSpectronAccessToken" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "404": description: Context not found content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "501": description: Spectron is not available on this deployment content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/organizations/{orgID}/spectron_contexts/{spectronContextID}/principals: get: tags: - Cloud operationId: cloudGetSpectronContextPrincipals summary: Lists the principals in a Spectron Context. description: Proxies the Spectron management API list-principals endpoint. security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: spectronContextID in: path responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudSpectronPrincipals" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "404": description: Context not found content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "501": description: Spectron is not available on this deployment content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" post: tags: - Cloud operationId: cloudCreateSpectronContextPrincipal summary: Creates a principal (human/agent/service) in a Spectron Context. description: Proxies the Spectron management API create-principal endpoint. security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: spectronContextID in: path requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CloudCreateSpectronPrincipal" responses: "201": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudSpectronPrincipal" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "404": description: Context not found content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "409": description: Principal already exists content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "422": description: Invalid data in request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "501": description: Spectron is not available on this deployment content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/organizations/{orgID}/spectron_contexts/{spectronContextID}/principals/{principalID}: patch: tags: - Cloud operationId: cloudUpdateSpectronContextPrincipal summary: Updates a principal in a Spectron Context. description: Proxies the Spectron management API update-principal endpoint. security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: spectronContextID in: path - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: principal-1 required: true name: principalID in: path requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CloudUpdateSpectronPrincipal" responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudSpectronPrincipal" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "404": description: Principal not found content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "501": description: Spectron is not available on this deployment content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" delete: tags: - Cloud operationId: cloudDeleteSpectronContextPrincipal summary: Deletes a principal from a Spectron Context. description: Proxies the Spectron management API delete-principal endpoint. security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: spectronContextID in: path - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: principal-1 required: true name: principalID in: path responses: "200": description: Principal deletion succeeded content: application/json: schema: $ref: "#/components/schemas/CloudEmptyBody" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "404": description: Principal not found content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "501": description: Spectron is not available on this deployment content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/organizations/{orgID}/spectron_contexts/{spectronContextID}/principals/{principalID}/grants: put: tags: - Cloud operationId: cloudReplaceSpectronContextPrincipalGrants summary: Replaces a principal's grants in a Spectron Context. description: Proxies the Spectron management API replace-principal-grants endpoint. security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: spectronContextID in: path - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: principal-1 required: true name: principalID in: path requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CloudReplaceSpectronPrincipalGrants" responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudSpectronPrincipal" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "404": description: Principal not found content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "501": description: Spectron is not available on this deployment content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/organizations/{orgID}/spectron_contexts/{spectronContextID}/users: post: tags: - Cloud operationId: cloudAddSpectronContextUser summary: Adds an existing cloud org user to a Spectron Context (admin only). description: Validates the target user exists and is a member of the org, then create-or-gets their Spectron principal with grants projected from their org role. security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: spectronContextID in: path requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CloudAddSpectronContextUser" responses: "200": description: User added (principal provisioned) content: application/json: schema: $ref: "#/components/schemas/CloudEmptyBody" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "404": description: Context or user not found content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "422": description: Invalid data in request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "501": description: Spectron is not available on this deployment content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/organizations/{orgID}/spectron_contexts/{spectronContextID}/scopes: get: tags: - Cloud operationId: cloudGetSpectronContextScopes summary: Lists the registered scope nodes in a Spectron Context. description: Proxies the Spectron management API list-scopes endpoint. security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: spectronContextID in: path responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudSpectronScopes" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "404": description: Context not found content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "501": description: Spectron is not available on this deployment content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/organizations/{orgID}/spectron_contexts/{spectronContextID}/config: get: tags: - Cloud operationId: cloudGetSpectronContextConfig summary: Returns a Spectron Context's configuration summary. description: Proxies the Spectron management API context summary (config view; provider keys are never returned). security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: spectronContextID in: path responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudSpectronContextConfig" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "404": description: Context not found content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "501": description: Spectron is not available on this deployment content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/organizations/{orgID}/spectron_contexts/{spectronContextID}/providers: get: tags: - Cloud operationId: cloudGetSpectronContextProviders summary: Returns the providers and selectable models for a Spectron Context. description: Proxies the Spectron management API providers endpoint. security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: spectronContextID in: path responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudSpectronProviders" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "404": description: Context not found content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "501": description: Spectron is not available on this deployment content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/organizations/{orgID}/spectron_contexts/{spectronContextID}/verbs: get: tags: - Cloud operationId: cloudGetSpectronContextVerbs summary: Returns the grant-verb catalog for a Spectron Context. description: Proxies the Spectron management verbs catalog (for grant-editor UIs). security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: spectronContextID in: path responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudSpectronVerbs" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "404": description: Context not found content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "501": description: Spectron is not available on this deployment content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/organizations/{orgID}/spectron_contexts/{spectronContextID}/usage: get: tags: - Cloud operationId: cloudGetSpectronContextUsage summary: Returns token usage (per-stage breakdown) for a Spectron Context. description: Proxies the Spectron management API usage endpoint (token consumption by stage + total for the active billing period). security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: spectronContextID in: path responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudSpectronContextUsage" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "404": description: Context not found content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "501": description: Spectron is not available on this deployment content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/organizations/{orgID}/spectron_context_packages: get: tags: - Cloud operationId: cloudGetOrganizationSpectronContextPackages summary: Retrieves the Context packages assigned to the organization security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path responses: "200": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudOrganizationSpectronContextPackages" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "404": description: Organization not found content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" post: tags: - Cloud operationId: cloudCreateOrganizationSpectronContextPackage summary: Assings a Context package to the organization security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CloudCreateOrganizationSpectronContextPackage" responses: "201": description: Operation successful content: application/json: schema: $ref: "#/components/schemas/CloudOrganizationSpectronContextPackage" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "404": description: Organization or package not found content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/cloud/v0/organizations/{orgID}/spectron_context_packages/{packageID}/cancel: post: tags: - Cloud operationId: cloudCancelOrganizationSpectronContextPackage summary: Cancels a Context package subscription for the organization security: - Bearer: [] CloudToken: [] - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: orgID in: path - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._~-]+$ example: 67upifj5dt6p87ch3nh5t3a8 required: true name: packageID in: path responses: "202": description: Operation accepted content: application/json: schema: $ref: "#/components/schemas/CloudOrganizationSpectronContextPackage" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "401": description: Invalid or missing access token, or missing Cloud session token content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "403": description: Insufficient scopes, or forbidden by Cloud content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "404": description: Organization or package not found content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "500": description: General error content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" "502": description: Cloud API unreachable content: application/json: schema: $ref: "#/components/schemas/CloudErrorResponse" /api/experience/v1/events: post: tags: - Experience summary: Record a batch of product analytics events description: "Relays analytics events to Google Analytics through the server-side GTM container. Fire-and-forget: the batch is accepted before the relay completes. Events that are not allowlisted, and events that do not match the schema, are dropped individually and counted in `dropped`; the request still succeeds even when every event is dropped. Only an invalid envelope is rejected with a 400: unparseable JSON, an unknown top-level key, or an `events` array that is missing, empty, or over the cap. There is no deduplication key, so a client must not retry a failed request — a retry double-counts in Google Analytics. A `text/plain` body is also accepted and parsed as JSON, so browser clients can post without triggering a CORS preflight." security: [] requestBody: required: true content: application/json: schema: type: object properties: events: type: array items: type: object properties: event: type: string minLength: 1 maxLength: 40 pattern: ^[a-z][a-z0-9_]*$ example: query_execute properties: type: object additionalProperties: anyOf: - type: string maxLength: 500 - type: number - type: boolean default: {} context: type: object properties: cid: type: string minLength: 1 maxLength: 64 example: "123456789.1731000000" sid: type: string minLength: 1 maxLength: 20 pattern: ^\d+$ example: "1731000000" seq: type: integer minimum: 1 maximum: 1000000 url: type: string minLength: 1 maxLength: 2048 format: uri example: https://app.surrealdb.com/ path: type: string minLength: 1 maxLength: 512 example: /query title: type: string minLength: 1 maxLength: 512 uid: type: string minLength: 1 maxLength: 128 language: type: string minLength: 2 maxLength: 35 resolution: type: string minLength: 3 maxLength: 16 pattern: ^\d+x\d+$ debug: type: boolean preview: type: string minLength: 1 maxLength: 512 required: - cid - sid - seq - url - title additionalProperties: false required: - event - context additionalProperties: false minItems: 1 maxItems: 50 required: - events additionalProperties: false responses: "202": description: Batch accepted content: application/json: schema: type: object properties: success: type: boolean example: true accepted: type: integer example: 3 dropped: type: integer example: 0 required: - success - accepted - dropped "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/ApiError" "429": description: Too many requests content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/experience/v1/forms/{id}: get: tags: - Experience summary: Retrieve a form definition description: Returns the form's fields in the order they should be shown. A form that does not exist and a form that is not currently being served both answer 404, so a client can treat one status as 'nothing to ask'. security: - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 64 pattern: ^[a-z][a-z0-9_]*$ example: onboarding required: true name: id in: path responses: "200": description: The form definition content: application/json: schema: type: object properties: success: type: boolean example: true data: $ref: "#/components/schemas/ExperienceForm" required: - success - data "401": description: Authentication failed content: application/json: schema: $ref: "#/components/schemas/ApiError" "404": description: No such form content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Failed to fetch the form content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/experience/v1/forms/{id}/submission: get: tags: - Experience summary: Retrieve the caller's submission status for a form description: Whether this account has already answered the form and whether another submission would be accepted. `can_submit` already accounts for the form's `multiple_submissions` setting, so a client does not have to combine the two itself. security: - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 64 pattern: ^[a-z][a-z0-9_]*$ example: onboarding required: true name: id in: path responses: "200": description: The caller's submission status content: application/json: schema: type: object properties: success: type: boolean example: true data: $ref: "#/components/schemas/ExperienceFormSubmissionStatus" required: - success - data "401": description: Authentication failed content: application/json: schema: $ref: "#/components/schemas/ApiError" "404": description: No such form content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Failed to fetch the submission status content: application/json: schema: $ref: "#/components/schemas/ApiError" post: tags: - Experience summary: Submit answers to a form description: "Answers are validated against the form's own fields: an unknown field name, a missing required answer, a value of the wrong type for its field, a value outside the field's bounds, and a choice that is not one of the offered options are each a 400. A form that may be answered only once returns 409 on a second attempt. Answers left empty on an optional field are not stored, so 'not asked' and 'skipped' both read as absent." security: - Bearer: [] parameters: - schema: type: string minLength: 1 maxLength: 64 pattern: ^[a-z][a-z0-9_]*$ example: onboarding required: true name: id in: path requestBody: required: true content: application/json: schema: type: object properties: values: type: object additionalProperties: anyOf: - type: string maxLength: 5000 - type: number - type: boolean - type: array items: type: string maxLength: 5000 maxItems: 100 description: Answers keyed by field name required: - values additionalProperties: false responses: "201": description: The submission was stored content: application/json: schema: type: object properties: success: type: boolean example: true data: $ref: "#/components/schemas/ExperienceFormSubmissionReceipt" required: - success - data "400": description: The answers do not satisfy the form content: application/json: schema: $ref: "#/components/schemas/ApiError" "401": description: Authentication failed content: application/json: schema: $ref: "#/components/schemas/ApiError" "404": description: No such form content: application/json: schema: $ref: "#/components/schemas/ApiError" "409": description: The form has already been answered content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Failed to store the submission content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/config/v1/studio: get: tags: - Config summary: Retrieve the SurrealDB Studio startup configuration security: [] responses: "200": description: SurrealDB Studio startup configuration content: application/json: schema: type: object properties: success: type: boolean example: true data: $ref: "#/components/schemas/StudioConfig" required: - success - data /api/seal/v1/chain/head: get: tags: - Seal summary: Get chain head description: Returns the current chain head index, hash, and timestamp. responses: "200": description: Get chain head content: application/json: schema: $ref: "#/components/schemas/SealPassthrough" "502": description: Upstream request failed content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/seal/v1/chain/entries: get: tags: - Seal summary: List chain entries description: Returns the contiguous chain suffix after the given index. Pass `after` (chain index) and `after_hash` (the hash of that entry) to fetch entries beyond a known-good point; omit both for the full chain. parameters: - schema: type: string required: false name: after in: query - schema: type: string required: false name: after_hash in: query responses: "200": description: List chain entries content: application/json: schema: $ref: "#/components/schemas/SealPassthrough" "502": description: Upstream request failed content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/seal/v1/release/lookup: get: tags: - Seal summary: Look up a release by binary hash parameters: - schema: type: string required: true name: binary_sha256 in: query responses: "200": description: Look up a release by binary hash content: application/json: schema: $ref: "#/components/schemas/SealPassthrough" "404": description: Not found content: application/json: schema: $ref: "#/components/schemas/ApiError" "502": description: Upstream request failed content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/seal/v1/release/{product}: get: tags: - Seal summary: List releases for a product parameters: - schema: type: string required: true name: product in: path - schema: type: string required: false name: cursor in: query - schema: type: string required: false name: limit in: query responses: "200": description: List releases for a product content: application/json: schema: $ref: "#/components/schemas/SealPassthrough" "404": description: Not found content: application/json: schema: $ref: "#/components/schemas/ApiError" "502": description: Upstream request failed content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/seal/v1/release/{product}/{version}: get: tags: - Seal summary: List releases for a product and version parameters: - schema: type: string required: true name: product in: path - schema: type: string required: true name: version in: path responses: "200": description: List releases for a product and version content: application/json: schema: $ref: "#/components/schemas/SealPassthrough" "404": description: Not found content: application/json: schema: $ref: "#/components/schemas/ApiError" "502": description: Upstream request failed content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/seal/v1/release/{product}/{version}/{platform}: get: tags: - Seal summary: Get release attestation for a specific platform parameters: - schema: type: string required: true name: product in: path - schema: type: string required: true name: version in: path - schema: type: string required: true name: platform in: path responses: "200": description: Get release attestation for a specific platform content: application/json: schema: $ref: "#/components/schemas/SealPassthrough" "404": description: Not found content: application/json: schema: $ref: "#/components/schemas/ApiError" "502": description: Upstream request failed content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/seal/v1/license/{licenseId}: get: tags: - Seal summary: Get license metadata description: Returns public license metadata. Does not include the certificate PEM. parameters: - schema: type: string pattern: ^[0-9A-HJKMNP-TV-Z]{32}$ example: G51RQ001KSPW1ZHEMFHB6EC7K0JEGWX5 required: true name: licenseId in: path responses: "200": description: Get license metadata content: application/json: schema: $ref: "#/components/schemas/SealPassthrough" "404": description: Not found content: application/json: schema: $ref: "#/components/schemas/ApiError" "502": description: Upstream request failed content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/seal/v1/publisher/{publisherId}: get: tags: - Seal summary: Get publisher profile parameters: - schema: type: string required: true name: publisherId in: path responses: "200": description: Get publisher profile content: application/json: schema: $ref: "#/components/schemas/SealPassthrough" "404": description: Not found content: application/json: schema: $ref: "#/components/schemas/ApiError" "502": description: Upstream request failed content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/seal/v1/publisher/{publisherId}/modules: get: tags: - Seal summary: List modules signed by a publisher parameters: - schema: type: string required: true name: publisherId in: path - schema: type: string required: false name: cursor in: query - schema: type: string required: false name: limit in: query responses: "200": description: List modules signed by a publisher content: application/json: schema: $ref: "#/components/schemas/SealPassthrough" "404": description: Not found content: application/json: schema: $ref: "#/components/schemas/ApiError" "502": description: Upstream request failed content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/seal/v1/module/recent: get: tags: - Seal summary: Recently published modules parameters: - schema: type: string required: false name: cursor in: query - schema: type: string required: false name: limit in: query responses: "200": description: Recently published modules content: application/json: schema: $ref: "#/components/schemas/SealPassthrough" "502": description: Upstream request failed content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/seal/v1/module/{org}/{name}: get: tags: - Seal summary: List versions of a module parameters: - schema: type: string required: true name: org in: path - schema: type: string required: true name: name in: path - schema: type: string required: false name: cursor in: query - schema: type: string required: false name: limit in: query responses: "200": description: List versions of a module content: application/json: schema: $ref: "#/components/schemas/SealPassthrough" "404": description: Not found content: application/json: schema: $ref: "#/components/schemas/ApiError" "502": description: Upstream request failed content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/seal/v1/module/{org}/{name}/{version}/seal: get: tags: - Seal summary: Get module seal (signature + chain proof) parameters: - schema: type: string required: true name: org in: path - schema: type: string required: true name: name in: path - schema: type: string required: true name: version in: path responses: "200": description: Get module seal (signature + chain proof) content: application/json: schema: $ref: "#/components/schemas/SealPassthrough" "404": description: Not found content: application/json: schema: $ref: "#/components/schemas/ApiError" "502": description: Upstream request failed content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/university/v1/courses: get: tags: - University summary: List university course part definitions security: [] responses: "200": description: Course part definitions content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object additionalProperties: type: object properties: parts: type: array items: anyOf: - type: array items: type: integer minItems: 1 maxItems: 1 - type: array items: type: integer minItems: 2 maxItems: 2 optional_parts: type: array items: anyOf: - type: array items: type: integer minItems: 1 maxItems: 1 - type: array items: type: integer minItems: 2 maxItems: 2 required: - parts required: - success - data /api/university/v1/certificate: get: tags: - University summary: Generate a course completion certificate parameters: - schema: type: string enum: - fundamentals example: fundamentals required: true name: course in: query - schema: type: string enum: - application/pdf required: true name: accept in: header responses: "200": description: PDF certificate content: application/pdf: schema: type: string format: binary "400": description: Missing or invalid course, or course not completed content: text/plain: schema: type: string example: Course not completed "406": description: Request must only accept application/pdf content: text/plain: schema: type: string example: Course not completed "500": description: Failed to get completion date content: text/plain: schema: type: string example: Course not completed /api/university/v1/progress/sync: post: tags: - University summary: Sync course progress and return completed parts requestBody: required: true content: application/json: schema: type: object properties: course: type: string enum: - fundamentals - book example: fundamentals part: type: integer minimum: 0 maximum: 50 example: 1 subpart: type: integer nullable: true minimum: 0 maximum: 50 example: 2 required: - course - part - subpart responses: "200": description: Completed course parts content: application/json: schema: type: object properties: success: type: boolean data: type: array items: type: array items: anyOf: - type: number - type: number nullable: true minItems: 2 maxItems: 2 required: - success - data "401": description: Authentication failed content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/support/v1/cloud/conversations: get: tags: - Cloud Support summary: List conversations for the authenticated user security: - Bearer: [] responses: "200": description: Conversations content: application/json: schema: type: object properties: success: type: boolean example: true data: type: array items: $ref: "#/components/schemas/SupportConversation" required: - success - data "500": description: Failed to fetch conversations content: application/json: schema: $ref: "#/components/schemas/ApiError" post: tags: - Cloud Support summary: Create a new conversation security: - Bearer: [] requestBody: required: true content: application/json: schema: type: object properties: body: type: string minLength: 1 maxLength: 65536 subject: type: string minLength: 1 maxLength: 256 tags: type: array items: type: string minLength: 1 maxLength: 64 maxItems: 20 required: - body - subject responses: "200": description: Conversation created content: application/json: schema: type: object properties: success: type: boolean example: true data: $ref: "#/components/schemas/SupportConversation" required: - success - data "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Failed to create conversation content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/support/v1/cloud/conversations/has_unread: get: tags: - Cloud Support summary: Check if user has unread conversations security: - Bearer: [] responses: "200": description: Unread status content: application/json: schema: type: object properties: success: type: boolean example: true data: type: boolean required: - success - data "500": description: Failed to fetch conversations content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/support/v1/cloud/conversations/{id}: get: tags: - Cloud Support summary: Get a conversation by ID security: - Bearer: [] parameters: - schema: type: string pattern: ^[0-9]{1,32}$ example: "123456" required: true name: id in: path responses: "200": description: Conversation details content: application/json: schema: type: object properties: success: type: boolean example: true data: $ref: "#/components/schemas/SupportConversation" required: - success - data "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/ApiError" "403": description: Access denied content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Failed to fetch conversation content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/support/v1/cloud/conversations/{id}/reply: post: tags: - Cloud Support summary: Reply to a conversation security: - Bearer: [] parameters: - schema: type: string pattern: ^[0-9]{1,32}$ example: "123456" required: true name: id in: path requestBody: required: true content: application/json: schema: type: object properties: body: type: string minLength: 1 maxLength: 65536 attachment_files: type: array items: type: object properties: content_type: type: string minLength: 1 maxLength: 255 data: type: string minLength: 1 maxLength: 139810134 name: type: string minLength: 1 maxLength: 255 required: - content_type - data - name maxItems: 5 reply_options: type: array items: type: object properties: text: type: string minLength: 1 maxLength: 256 uuid: type: string minLength: 1 maxLength: 64 required: - text - uuid maxItems: 10 responses: "200": description: Reply sent content: application/json: schema: type: object properties: success: type: boolean example: true data: $ref: "#/components/schemas/SupportConversation" required: - success - data "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/ApiError" "403": description: Access denied content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Failed to send reply content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/support/v1/cloud/conversations/{id}/reopen: post: tags: - Cloud Support summary: Reopen a closed conversation security: - Bearer: [] parameters: - schema: type: string pattern: ^[0-9]{1,32}$ example: "123456" required: true name: id in: path requestBody: required: true content: application/json: schema: type: object properties: body: type: string minLength: 1 maxLength: 65536 required: - body responses: "200": description: Conversation reopened content: application/json: schema: type: object properties: success: type: boolean example: true data: $ref: "#/components/schemas/SupportConversation" required: - success - data "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/ApiError" "403": description: Access denied content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Failed to reopen conversation content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/support/v1/cloud/conversations/{id}/mark_as/{state}: patch: tags: - Cloud Support summary: Mark a conversation as read security: - Bearer: [] parameters: - schema: type: string pattern: ^[0-9]{1,32}$ example: "123456" required: true name: id in: path - schema: type: string enum: - read - unread example: read required: true name: state in: path responses: "200": description: Conversation marked content: application/json: schema: type: object properties: success: type: boolean example: true data: $ref: "#/components/schemas/MarkedConversation" required: - success - data "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/ApiError" "403": description: Access denied content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Failed to mark conversation content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/support/v1/cloud/org/{org}/ticket_attributes: get: tags: - Cloud Support Tickets summary: Get ticket attributes for an organisation's support plan security: - Bearer: [] parameters: - schema: type: string pattern: ^[A-Za-z0-9]{1,64}$ example: abc123 required: true name: org in: path responses: "200": description: Ticket attributes content: application/json: schema: type: object properties: success: type: boolean example: true data: type: array items: $ref: "#/components/schemas/SupportTicketAttribute" required: - success - data "403": description: No access or no active support plan content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Failed to fetch ticket types content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/support/v1/cloud/org/{org}/tickets: get: tags: - Cloud Support Tickets summary: List tickets for an organisation security: - Bearer: [] parameters: - schema: type: string pattern: ^[A-Za-z0-9]{1,64}$ example: abc123 required: true name: org in: path responses: "200": description: Organisation tickets content: application/json: schema: type: object properties: success: type: boolean example: true data: type: array items: $ref: "#/components/schemas/SupportTicket" required: - success - data "403": description: Access denied content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Failed to fetch tickets content: application/json: schema: $ref: "#/components/schemas/ApiError" post: tags: - Cloud Support Tickets summary: Create a support ticket security: - Bearer: [] parameters: - schema: type: string pattern: ^[A-Za-z0-9]{1,64}$ example: abc123 required: true name: org in: path requestBody: required: true content: application/json: schema: type: object properties: name: type: string minLength: 1 maxLength: 256 description: type: string minLength: 1 maxLength: 16384 org_contacts: type: array items: type: string minLength: 1 maxLength: 320 maxItems: 20 email_contacts: type: array items: type: string minLength: 1 maxLength: 320 maxItems: 20 attributes: type: object additionalProperties: anyOf: - type: string maxLength: 2000 - type: number - type: boolean required: - name - description responses: "200": description: Ticket created content: application/json: schema: type: object properties: success: type: boolean example: true data: $ref: "#/components/schemas/SupportTicket" required: - success - data "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/ApiError" "403": description: No access or no active support plan content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Failed to create ticket content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/support/v1/cloud/tickets/{id}/{state}: patch: tags: - Cloud Support Tickets summary: Close or reopen a ticket security: - Bearer: [] parameters: - schema: type: string pattern: ^[0-9]{1,32}$ example: "12345" required: true name: id in: path - schema: type: string enum: - close - open example: close required: true name: state in: path responses: "200": description: Ticket updated content: application/json: schema: type: object properties: success: type: boolean example: true data: $ref: "#/components/schemas/SupportTicket" required: - success - data "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/ApiError" "403": description: Access denied content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Failed to update ticket content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/support/v1/help/collections: get: tags: - Support Help Center summary: List help center collections security: [] responses: "200": description: Collections with images content: application/json: schema: type: object properties: success: type: boolean example: true data: type: array items: $ref: "#/components/schemas/SupportHelpCollection" required: - success - data "500": description: Failed to fetch collections content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/support/v1/help/collections/{id}: get: tags: - Support Help Center summary: Get a collection with its articles security: [] parameters: - schema: type: string minLength: 1 maxLength: 20 pattern: ^\d+$ example: "123" required: true name: id in: path responses: "200": description: Collection with articles content: application/json: schema: type: object properties: success: type: boolean example: true data: $ref: "#/components/schemas/SupportHelpCollectionDetail" required: - success - data "400": description: Invalid collection ID content: application/json: schema: $ref: "#/components/schemas/ApiError" "404": description: Collection not found content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Failed to fetch articles content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/support/v1/help/articles/{id}: get: tags: - Support Help Center summary: Get an article by ID security: [] parameters: - schema: type: string minLength: 1 maxLength: 20 pattern: ^\d+$ example: "456" required: true name: id in: path responses: "200": description: Article with author and collection content: application/json: schema: type: object properties: success: type: boolean example: true data: $ref: "#/components/schemas/SupportHelpArticleDetail" required: - success - data "404": description: Article not found content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/support/v1/help/articles/search: post: tags: - Support Help Center summary: Search help center articles security: [] requestBody: required: true content: application/json: schema: type: object properties: query: type: string minLength: 1 maxLength: 256 example: getting started required: - query responses: "200": description: Search results content: application/json: schema: type: object properties: success: type: boolean example: true data: type: array items: $ref: "#/components/schemas/SupportHelpArticle" required: - success - data "400": description: No query provided content: application/json: schema: $ref: "#/components/schemas/ApiError" "404": description: No articles found content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Failed to search articles content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/website/v1/banners: get: tags: - Website summary: Get active website banners security: [] responses: "200": description: List of active banners content: application/json: schema: type: array items: $ref: "#/components/schemas/WebsiteBanner" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/website/v1/blogs: get: tags: - Website summary: Get all blog posts security: [] responses: "200": description: List of blog posts content: application/json: schema: type: array items: $ref: "#/components/schemas/WebsiteBlogPost" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/website/v1/blogs/slugs: get: tags: - Website summary: Get all blog post slugs security: [] responses: "200": description: List of blog post slugs content: application/json: schema: type: array items: type: string example: /blog/my-post "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/website/v1/blogs/sitemap: get: tags: - Website summary: Get all blog sitemap entries security: [] responses: "200": description: Sitemap entries for all published blog posts content: application/json: schema: type: array items: $ref: "#/components/schemas/WebsiteBlogSitemapEntry" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/website/v1/blogs/sitemap/{slug}: get: tags: - Website summary: Get blog sitemap entry by slug security: [] parameters: - schema: type: string example: my-post required: true name: slug in: path responses: "200": description: Sitemap entry for the blog post content: application/json: schema: type: array items: $ref: "#/components/schemas/WebsiteBlogSitemapEntry" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/website/v1/blogs/{slug}: get: tags: - Website summary: Get a blog post by slug security: [] parameters: - schema: type: string example: my-post required: true name: slug in: path responses: "200": description: Blog post, or null when absent content: application/json: schema: $ref: "#/components/schemas/WebsiteBlogPostDetail" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/website/v1/events: get: tags: - Website summary: Get all events (DB + Eventbrite + YouTube livestreams) security: [] responses: "200": description: List of events content: application/json: schema: type: array items: $ref: "#/components/schemas/WebsiteEvent" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/website/v1/events/slugs: get: tags: - Website summary: Get event slugs security: [] parameters: - schema: type: string example: webinar required: false name: category in: query responses: "200": description: List of event slugs content: application/json: schema: type: array items: type: string example: /events/my-event "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/website/v1/events/{slug}: get: tags: - Website summary: Get an event by slug security: [] parameters: - schema: type: string example: my-event required: true name: slug in: path responses: "200": description: Event or livestream page payload content: application/json: schema: $ref: "#/components/schemas/WebsiteEventPage" "404": description: Event not found content: application/json: schema: $ref: "#/components/schemas/ApiError" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/website/v1/press: get: tags: - Website summary: Get all press entries security: [] responses: "200": description: List of press entries content: application/json: schema: type: array items: $ref: "#/components/schemas/WebsitePressEntry" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" /api/website/v1/stars/{repo}: get: tags: - Website summary: Get GitHub star count for a repository security: [] parameters: - schema: type: string enum: - surrealdb - surrealist example: surrealdb required: true name: repo in: path responses: "200": description: Star count for the repository content: application/json: schema: $ref: "#/components/schemas/WebsiteStarCount" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError"