> ## Documentation Index > Fetch the complete documentation index at: https://paper.brimble.io/llms.txt > Use this file to discover all available pages before exploring further. # Get a bucket > **API key scope:** `storage.read` **Team role permission:** `storage.read` ## OpenAPI ````yaml /api-reference/core.openapi.yaml get /v1/storage/buckets/{bucketId} openapi: 3.0.3 info: title: Brimble API version: 1.0.0 description: > The Brimble API lets you deploy and manage projects, databases, domains, sandboxes, object storage and more. ## Base URL All endpoints are relative to `https://api.brimble.io/core`, for example `GET https://api.brimble.io/core/v1/projects`. ## Authentication Create an API key in the dashboard under **Settings → API keys** and send it in the `x-brimble-key` header: ``` x-brimble-key: ``` Each API key carries permission scopes such as `project.read` or `project.deploy`. Every endpoint lists the scope it needs; a key without that scope gets `403`. Dashboard session tokens (`Authorization: Bearer `) are also accepted, but integrations should use API keys. ## Teams Endpoints act on your personal workspace unless you pass a team. Most endpoints accept `teamId` (as a query parameter, or in the body for writes). API keys created for a team act in that team. Inside a team, your team role must also allow the action; each endpoint lists the team permission it checks. ## Responses Successful responses are JSON with this shape: ```json { "message": "Projects fetched", "data": { } } ``` Errors return a `message`: ```json { "message": "Project not found", "data": {} } ``` Requests that fail validation return `400` with every invalid field: ```json { "errors": [{ "type": "field", "msg": "Project name should be provided", "path": "name", "location": "body" }] } ``` ## Rate limits Requests made with an API key are rate limited. Responses include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Bucket`. Command execution and file transfer endpoints use separate buckets. ## Idempotency Endpoints that accept an `Idempotency-Key` header return the original result when retried with the same key and body, instead of repeating the operation. ## Streaming Command execution endpoints can stream output as Server-Sent Events (`text/event-stream`). Each event is `data: ` where the JSON has a `type` of `stdout`, `stderr`, `done` or `error`. ## Webhooks To receive events instead of polling, configure a webhook with `PATCH /v1/webhooks`. See the [Webhooks guide](/webhooks/overview) and the [Webhook events reference](/webhooks/events) for every payload. contact: name: Brimble url: https://brimble.io servers: - url: https://api.brimble.io/core description: Production security: - ApiKeyAuth: [] - BearerAuth: [] tags: - name: Projects description: Create, deploy, configure and manage projects. - name: Deployments and Logs description: Deployment history, build logs and request logs. - name: Environments description: Project environments (production, staging, previews) and their variables. - name: Secrets description: >- Secrets (environment variables) set on a single project. Not to be confused with Environments, which group projects into production, staging and preview. - name: Webhooks description: >- Receive events from Brimble at your own endpoint (or a Discord or Slack channel). Configure the destination and events with `PATCH /v1/webhooks`; use `*` to receive every event. See the [Webhooks guide](/webhooks/overview) for setup, and the [Webhook events reference](/webhooks/events) for the payload each event delivers. | Event | Sent when | | --- | --- | | `project.created` | A project is created | | `project.updated` | A project is updated | | `project.deleted` | A project is deleted | | `project.domain.updated` | A project domain changes | | `deployment.created` | A deployment is queued | | `deployment.started` | A deployment starts | | `deployment.success` | A deployment succeeds | | `deployment.failed` | A deployment fails | | `environment.variables.added` | Environment variables are added | | `environment.variables.updated` | Environment variables are updated | | `environment.variables.deleted` | Environment variables are deleted | | `domain.created` | A domain is added | | `domain.purchased` | A domain is purchased | | `domain.renewed` | A domain is renewed | | `domain.expired` | A domain expires | | `dns.record.created` | A DNS record is created | | `dns.record.updated` | A DNS record is updated | | `dns.record.deleted` | A DNS record is deleted | | `database.created` | A database is created | | `database.backup.completed` | A database backup completes | | `autoscaling.group.created` | An autoscaling rule is created | | `autoscaling.group.updated` | An autoscaling rule is updated | | `autoscaling.group.deleted` | An autoscaling rule is deleted | | `payment.successful` | A payment succeeds | | `payment.failed` | A payment fails | Test deliveries sent with `POST /v1/webhooks/test` include the header `X-Brimble-Test: true`. - name: Git Providers description: Connected git accounts, repositories and linking repositories to projects. - name: Domains description: Custom domains, DNS records and domain registration. - name: Databases description: 'Managed databases: provisioning, backups, users and linking to projects.' - name: Log Drains description: Stream logs to external destinations. - name: Sandboxes description: Isolated sandboxes for running code, with files and snapshots. - name: Object Storage description: S3-compatible buckets, objects and credentials. - name: Scaling and Networking description: Autoscaling rules, networking and CDN cache, and rate limits. - name: Teams description: Teams, members, invitations and roles. - name: Catalog description: Regions, frameworks and plans. No authentication required. paths: /v1/storage/buckets/{bucketId}: get: tags: - Object Storage summary: Get a bucket description: |- **API key scope:** `storage.read` **Team role permission:** `storage.read` operationId: getBucket parameters: - name: bucketId in: path required: true schema: type: string - $ref: '#/components/parameters/TeamId' responses: '200': description: Storage bucket fetched content: application/json: schema: type: object required: - message - data properties: message: type: string example: Storage bucket fetched data: type: object properties: storage_used: type: number objectCount: type: number url: type: string _id: $ref: '#/components/schemas/ObjectId' name: type: string project: allOf: - $ref: '#/components/schemas/ObjectId' nullable: true project_environment: oneOf: - $ref: '#/components/schemas/ObjectId' - $ref: '#/components/schemas/IProjectEnvironment' nullable: true user_id: allOf: - $ref: '#/components/schemas/ObjectId' nullable: true team: allOf: - $ref: '#/components/schemas/ObjectId' nullable: true bucket_name: type: string provider: type: string is_public: type: boolean versioning: type: boolean region: type: string storage_increased_by: type: number storage_decreased_by: type: number reserved_bytes: type: number cors_rules: type: array items: type: object properties: allowedOrigins: type: array items: type: string allowedHeaders: type: array items: type: string nullable: true allowedMethods: type: array items: type: string nullable: true exposeHeaders: type: array items: type: string nullable: true maxAgeSeconds: type: number nullable: true required: - allowedOrigins lifecycle_rules: type: array items: $ref: '#/components/schemas/StorageLifecycleRule' nullable: true status: type: string enum: - active - deleting - deleted starred: type: boolean createdAt: type: string format: date-time updatedAt: type: string format: date-time capabilities: $ref: '#/components/schemas/StorageBucketCapabilities' required: - storage_used - objectCount - url - _id - name - project - project_environment - user_id - team - bucket_name - provider - is_public - versioning - region - storage_increased_by - storage_decreased_by - reserved_bytes - cors_rules - lifecycle_rules - status - starred - createdAt - updatedAt - capabilities '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' components: parameters: TeamId: name: teamId in: query required: false schema: $ref: '#/components/schemas/ObjectId' description: >- Team to act in. Omit for your personal workspace. API keys created for a team use that team automatically. schemas: ObjectId: type: string pattern: ^[a-fA-F0-9]{24}$ example: 6a81bed11470bfcd2a5dbcfa IProjectEnvironment: type: object properties: name: type: string slug: type: string owner: $ref: '#/components/schemas/IUser' team: allOf: - $ref: '#/components/schemas/ITeam' nullable: true inherit_from: allOf: - $ref: '#/components/schemas/IProjectEnvironment' nullable: true isDefault: type: boolean createdAt: type: string format: date-time updatedAt: type: string format: date-time _id: $ref: '#/components/schemas/ObjectId' required: - name - slug - owner - isDefault - createdAt - updatedAt - _id StorageLifecycleRule: type: object properties: id: type: string nullable: true prefix: type: string nullable: true expirationDays: type: number nullable: true transitions: type: array items: $ref: '#/components/schemas/StorageLifecycleRuleTransition' nullable: true StorageBucketCapabilities: type: object properties: cors: type: boolean publicToggle: type: boolean customDomain: type: boolean lifecycle: type: boolean versioning: type: boolean bucketPolicy: type: boolean objectAcl: type: boolean publicWebsite: type: boolean copyObject: type: boolean objectTagging: type: boolean notifications: type: boolean replication: type: boolean select: type: boolean objectLock: type: boolean inventory: type: boolean nativeIam: type: boolean required: - cors - publicToggle - customDomain - lifecycle - versioning - bucketPolicy - objectAcl - publicWebsite - copyObject - objectTagging - notifications - replication - select - objectLock - inventory - nativeIam IUser: type: object properties: first_name: type: string last_name: type: string email: type: string username: type: string email_verified_at: type: string company: type: string nullable: true ai_usage_count: type: number github: $ref: '#/components/schemas/IGit' gitlab: $ref: '#/components/schemas/IGit' location: type: string interests: type: array items: type: string bitbucket: $ref: '#/components/schemas/IGit' origin: allOf: - $ref: '#/components/schemas/IOrigin' nullable: true following: type: array items: $ref: '#/components/schemas/IFollowing' projects: type: array items: $ref: '#/components/schemas/IProject' teams: type: array items: $ref: '#/components/schemas/ITeam' avatar: type: string freeTrialActive: type: boolean activated: type: boolean is_waitlist: type: boolean build_disabled: type: boolean build_disabled_by: type: string enum: - system - user - payment_failure sandbox_disabled: type: boolean sandbox_disabled_by: type: string enum: - system - payment_failure nullable: true spending_limit: type: number spending_limit_action: type: string enum: - notify - pause nullable: true spending_limit_breached_at: type: string format: date-time nullable: true build_minutes: type: number llm_tokens: type: number llm_tokens_used: type: number llm_tokens_team_granted: type: boolean disabled: type: boolean disabled_at: type: string format: date-time has_payment_method: type: boolean notifications: type: object properties: mute: type: boolean email_categories: type: object properties: billing: type: boolean nullable: true activity: type: boolean nullable: true repositories: type: boolean nullable: true updates: type: boolean nullable: true nullable: true required: - mute totp_enabled: type: boolean nullable: true agent_byok_enabled: type: boolean referral_code: type: string nullable: true referred_by: allOf: - $ref: '#/components/schemas/ObjectId' nullable: true referred_at: type: string format: date-time nullable: true referral_converted_at: type: string format: date-time nullable: true referral_rewarded_count: type: number nullable: true referral_domain_credits: type: number nullable: true referral_invoice_credits: type: number nullable: true referral_reward_granted: type: boolean nullable: true concurrent_builds: type: number nullable: true max_concurrent_builds_per_project: type: number nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time _id: $ref: '#/components/schemas/ObjectId' required: - first_name - last_name - email - username - email_verified_at - ai_usage_count - github - gitlab - location - interests - bitbucket - following - projects - teams - avatar - freeTrialActive - activated - is_waitlist - build_disabled - build_disabled_by - sandbox_disabled - sandbox_disabled_by - spending_limit - spending_limit_action - spending_limit_breached_at - build_minutes - llm_tokens - llm_tokens_used - llm_tokens_team_granted - disabled - disabled_at - has_payment_method - notifications - agent_byok_enabled - created_at - updated_at - _id ITeam: type: object properties: name: type: string slug: type: string description: type: string size: type: number members: type: array items: $ref: '#/components/schemas/IMember' projects: type: array items: $ref: '#/components/schemas/IProject' ai_usage_count: type: number image: type: string isCreator: type: boolean build_minutes: type: number build_minutes_last_reset_at: type: string format: date-time nullable: true build_minutes_cycle_anchor: type: string format: date-time nullable: true concurrent_builds: type: number nullable: true max_concurrent_builds_per_project: type: number nullable: true spending_limit: type: number spending_limit_action: type: string enum: - notify - pause nullable: true spending_limit_breached_at: type: string format: date-time nullable: true build_disabled: type: boolean build_disabled_by: type: string enum: - system - user - payment_failure sandbox_disabled: type: boolean sandbox_disabled_by: type: string enum: - system - payment_failure nullable: true subscription: $ref: '#/components/schemas/ISubscription' enforce_2fa: type: boolean enforce_2fa_at: type: string format: date-time nullable: true enforce_2fa_by: oneOf: - $ref: '#/components/schemas/ObjectId' - $ref: '#/components/schemas/IUser' nullable: true activation_status: type: string enum: - active - pending - deleting nullable: true activation_pending_since: type: string format: date-time nullable: true pending_member_invites: type: array items: type: string activation_checked_at: type: string format: date-time nullable: true _id: $ref: '#/components/schemas/ObjectId' required: - name - slug - description - size - members - projects - ai_usage_count - image - isCreator - build_minutes - build_minutes_last_reset_at - build_minutes_cycle_anchor - spending_limit - spending_limit_action - spending_limit_breached_at - build_disabled - build_disabled_by - sandbox_disabled - sandbox_disabled_by - subscription - enforce_2fa - enforce_2fa_at - enforce_2fa_by - activation_pending_since - pending_member_invites - activation_checked_at - _id StorageLifecycleRuleTransition: type: object properties: days: type: number nullable: true storageClass: type: string nullable: true ErrorResponse: type: object required: - message properties: message: type: string example: Project not found data: type: object example: {} IGit: type: object properties: git_id: type: number nullable: true installation_ids: type: array items: type: number nullable: true installation_id: type: string nullable: true scope: type: string nullable: true created_at: type: number nullable: true state: type: string nullable: true expires_in: type: number nullable: true expires_at: type: number nullable: true scopes: type: string nullable: true _id: $ref: '#/components/schemas/ObjectId' required: - _id IOrigin: type: object properties: installation_id: type: string namespace_id: type: string nullable: true repository_selection: type: string enum: - all - selected nullable: true required: - installation_id IFollowing: type: object properties: user_id: type: string nullable: true followed_id: type: string nullable: true _id: $ref: '#/components/schemas/ObjectId' required: - _id IProject: type: object properties: managed_by_config: allOf: - $ref: '#/components/schemas/ConfigManagedFields' nullable: true name: type: string healthCheckPath: type: string nullable: true preStartCommand: type: string nullable: true backupEnabled: type: boolean backup_mode: type: string enum: - automatic - manual backup_schedule: type: string backup_timezone: type: string backup_retention_days: type: number nullable: true backup_destination_type: type: string enum: - platform - brimble - external backup_destination_bucket: allOf: - $ref: '#/components/schemas/ObjectId' nullable: true backup_destination_external: allOf: - $ref: '#/components/schemas/IBackupDestinationExternal' nullable: true dedicated_egress: allOf: - $ref: '#/components/schemas/IDedicatedEgress' nullable: true preview_collaboration: allOf: - $ref: '#/components/schemas/IPreviewCollaboration' nullable: true http2: type: boolean free_tier_expires_at: type: string format: date-time nullable: true free_tier_expiry_notified_at: type: string format: date-time nullable: true buildCacheEnabled: type: boolean nullable: true buildHealthCheck: type: boolean nullable: true alerting_enabled: type: boolean logDrainsEnabled: type: boolean domains: type: array items: $ref: '#/components/schemas/IDomain' environments: type: array items: $ref: '#/components/schemas/Secret' uuid: type: number pid: type: number port: type: number ip: type: string dir: type: string tlsEnabled: type: boolean sendReport: type: boolean pgbouncerEnabled: type: boolean pgbouncerConfig: allOf: - $ref: '#/components/schemas/IPgBouncerConfig' nullable: true tlsEnabledAt: type: string format: date-time nullable: true meshTlsEnabled: type: boolean nullable: true tlsCaObjectKey: type: string nullable: true tlsServerCertExpiresAt: type: string format: date-time nullable: true tlsHost: type: string nullable: true tlsPort: type: number nullable: true tlsSslModeHint: type: string nullable: true tlsProvisioning: type: boolean nullable: true tlsClaimedAt: type: string format: date-time nullable: true tlsMigration: allOf: - $ref: '#/components/schemas/ITlsMigration' nullable: true pendingMqEvent: allOf: - $ref: '#/components/schemas/IPendingMqEvent' nullable: true passwordRotation: allOf: - $ref: '#/components/schemas/IPasswordRotation' nullable: true rolloutInterruptedJobId: type: string nullable: true activeOperationMessageId: type: string nullable: true lastCompletedMessageId: type: string nullable: true lastFailedMessageId: type: string nullable: true provisionProgress: allOf: - $ref: '#/components/schemas/IDatabaseProvisionProgress' nullable: true dbImage: $ref: '#/components/schemas/IDbImage' ha: type: boolean haCluster: allOf: - $ref: '#/components/schemas/IHaCluster' nullable: true public: type: boolean installCommand: type: string buildCommand: type: string startCommand: type: string outputDirectory: type: string runtimeVersions: allOf: - $ref: '#/components/schemas/RuntimeVersions' nullable: true workBenchEnabled: type: boolean user_id: $ref: '#/components/schemas/IUser' monitor_id: type: string nomadJobId: type: string watchPaths: type: array items: type: string repo: type: object properties: name: type: string full_name: type: string id: oneOf: - type: string - type: number branch: type: string installationId: oneOf: - type: string - type: number git: type: string enum: - GITHUB - GITLAB - BITBUCKET - DOCKER - HUGGINGFACE - ORIGIN required: - name - full_name - id - branch - installationId - git nullable: true rootDir: type: string nullable: true dockerfile: type: string nullable: true team: $ref: '#/components/schemas/ITeam' server: $ref: '#/components/schemas/IServer' isPrivate: type: boolean status: type: string enum: - AWAITING_CONFIG_APPROVAL - INACTIVE - ACTIVE - INPROGRESS - FAILED - PENDING - CANCELLED - SUPERSEDED - DEGRADED - PAYMENT DUE - NOMAD_READY - NOMAD_FAILED framework: type: string description: type: string logs: type: array items: $ref: '#/components/schemas/ILog' log: $ref: '#/components/schemas/ILog' maintenance: type: boolean preview_deployments_enabled: type: boolean starred: type: boolean passwordEnabled: type: boolean disabled: type: boolean disabled_at: type: string format: date-time nullable: true disabled_by: type: string enum: - payment_failure - billing_restricted - plan_limit - plan_feature - subscription_ended nullable: true deletedAt: type: string format: date-time nullable: true authEnabled: type: boolean deployedInCluster: type: boolean screenshot: type: object properties: image: type: string public_id: type: string required: - image - public_id createdAt: type: string format: date-time updatedAt: type: string format: date-time container_stats_schedule_id: type: string nullable: true lastProcessed: type: number tracking_token: type: string from: type: string previews: type: array items: $ref: '#/components/schemas/IPreview' project_environment: allOf: - $ref: '#/components/schemas/IProjectEnvironment' nullable: true inherit_environment_vars: type: boolean replicas: type: number vaultPath: type: string nullable: true specs: $ref: '#/components/schemas/IProjectSpecs' desiredSpecs: allOf: - $ref: '#/components/schemas/IProjectSpecs' nullable: true currentSpecs: allOf: - $ref: '#/components/schemas/IProjectSpecs' nullable: true last_requested: type: string format: date-time isPaused: type: boolean paused_by: type: string nullable: true billable: type: boolean serviceType: type: string enum: - database - web-service - static - mcp - liscense - worker nullable: true cronEnabled: type: boolean nullable: true cronExpression: type: string nullable: true cronTimezone: type: string nullable: true cronCommand: type: string nullable: true last_backup_url: type: string nullable: true last_backup_at: type: string format: date-time nullable: true replica_ready: type: boolean autoscaling_group: allOf: - $ref: '#/components/schemas/IAutoScalingGroup' nullable: true isPaid: type: boolean hasUpdates: type: boolean nullable: true whiteListedIps: type: array items: type: string nullable: true diskSize: type: number nullable: true persistent_mount_path: type: string nullable: true volumeMount: type: string required: - name - backupEnabled - backup_mode - backup_schedule - backup_timezone - backup_destination_type - http2 - alerting_enabled - logDrainsEnabled - domains - environments - uuid - pid - port - ip - dir - tlsEnabled - sendReport - pgbouncerEnabled - dbImage - ha - public - installCommand - buildCommand - startCommand - outputDirectory - workBenchEnabled - user_id - monitor_id - nomadJobId - watchPaths - repo - team - server - isPrivate - status - framework - description - logs - log - maintenance - preview_deployments_enabled - starred - passwordEnabled - disabled - authEnabled - deployedInCluster - screenshot - createdAt - updatedAt - container_stats_schedule_id - lastProcessed - tracking_token - from - previews - inherit_environment_vars - replicas - vaultPath - specs - last_requested - isPaused - paused_by - billable - replica_ready - isPaid - volumeMount IMember: type: object properties: user: $ref: '#/components/schemas/IUser' team: $ref: '#/components/schemas/ITeam' role: type: string enum: - CREATOR - ADMINISTRATOR - MEMBER - VIEWER - CUSTOM accepted: type: boolean invitedBy: $ref: '#/components/schemas/IUser' email: type: string featureOnboarded: type: boolean custom_role: oneOf: - $ref: '#/components/schemas/ObjectId' - $ref: '#/components/schemas/IRole' nullable: true project_environments: type: array items: $ref: '#/components/schemas/IProjectEnvironment' createdAt: type: string format: date-time updatedAt: type: string format: date-time _id: $ref: '#/components/schemas/ObjectId' required: - user - team - role - accepted - invitedBy - email - featureOnboarded - project_environments - createdAt - updatedAt - _id ISubscription: type: object properties: initial_start_date: type: string team_id: $ref: '#/components/schemas/ITeam' due_amount: type: number admin_id: $ref: '#/components/schemas/IUser' downgraded: type: boolean billable_id: $ref: '#/components/schemas/IUser' project_id: allOf: - $ref: '#/components/schemas/IProject' nullable: true plan_type: type: string enum: - FREE_PLAN - DEVELOPER_PLAN - TEAM_PLAN - DOMAIN_PLAN - HACKER_PLAN - LISCENSE_PLAN - EMAIL_FORWARDING_PLAN status: type: string enum: - active - in-active amount: type: number transaction_retries: type: number debit_date: type: string start_date: type: string expiry_date: type: string reminder_date: type: string is_pending_downgrade: type: boolean grafana_org_id: type: string job_identifier: type: string trigger_created: type: boolean trigger_created_at: type: string disabled_at: type: string format: date-time specifications: type: object additionalProperties: {} created_at: type: string format: date-time updated_at: type: string format: date-time _id: $ref: '#/components/schemas/ObjectId' required: - initial_start_date - team_id - due_amount - admin_id - downgraded - billable_id - plan_type - status - amount - transaction_retries - debit_date - start_date - expiry_date - reminder_date - is_pending_downgrade - grafana_org_id - job_identifier - trigger_created - trigger_created_at - disabled_at - specifications - created_at - updated_at - _id ConfigManagedFields: type: object properties: path: type: string fields: type: array items: type: string commit: type: string applied_at: type: string format: date-time required: - path - fields - commit - applied_at IBackupDestinationExternal: type: object properties: endpoint: type: string nullable: true region: type: string nullable: true bucket_name: type: string nullable: true IDedicatedEgress: type: object properties: enabled: type: boolean pool: type: string nullable: true updated_at: type: string format: date-time nullable: true required: - enabled IPreviewCollaboration: type: object properties: enabled: type: boolean site_id: type: string nullable: true script_src: type: string nullable: true api_origin: type: string nullable: true external_collaborators: type: array items: type: string enabled_at: type: string format: date-time nullable: true updated_at: type: string format: date-time nullable: true required: - enabled - external_collaborators IDomain: type: object properties: name: type: string project: $ref: '#/components/schemas/IProject' user_id: $ref: '#/components/schemas/IUser' team_id: allOf: - $ref: '#/components/schemas/ITeam' nullable: true primary: type: boolean preview: $ref: '#/components/schemas/IPreview' provider: type: string subscription: $ref: '#/components/schemas/ISubscription' cashier_subscription_id: type: string nullable: true auto_renewal: type: boolean renewal_duration: type: number is_discounted: type: boolean purchased: type: boolean privacy_enabled: type: boolean renewal_date: type: string renewal_price: type: number job_identifier: type: string cloudflare_custom_hostname_id: type: string nullable: true cloudflare_custom_hostname_status: type: string nullable: true trigger_created: type: boolean trigger_created_at: type: string nameservers: type: array items: type: string nameservers_next_check_at: type: string format: date-time nullable: true registration_next_check_at: type: string format: date-time nullable: true dns: type: array items: $ref: '#/components/schemas/IDns' project_environment: allOf: - $ref: '#/components/schemas/IProjectEnvironment' nullable: true is_pending_verification: type: boolean last_expiry_notification_at: type: string format: date-time nullable: true wildcard_enabled: type: boolean wildcard_verified: type: boolean email_forwarding_enabled: type: boolean redirect: type: object properties: url: type: string status: type: number enum: - 301 - 302 - 307 - 308 nullable: true required: - url nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time _id: $ref: '#/components/schemas/ObjectId' required: - name - project - user_id - primary - preview - provider - subscription - cashier_subscription_id - auto_renewal - renewal_duration - is_discounted - purchased - privacy_enabled - renewal_date - renewal_price - job_identifier - trigger_created - trigger_created_at - nameservers - dns - is_pending_verification - wildcard_enabled - wildcard_verified - email_forwarding_enabled - createdAt - updatedAt - _id Secret: type: object properties: name: type: string value: type: string project: $ref: '#/components/schemas/IProject' user: $ref: '#/components/schemas/IUser' environment: type: string is_system: type: boolean nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time _id: $ref: '#/components/schemas/ObjectId' required: - name - value - project - user - environment - createdAt - updatedAt - _id IPgBouncerConfig: type: object properties: defaultPoolSize: type: number maxDbConnections: type: number maxDbClientConnections: type: number maxUserConnections: type: number maxClientConn: type: number maxPreparedStatements: type: number serverLifetime: type: number serverIdleTimeout: type: number required: - defaultPoolSize - maxDbConnections - maxDbClientConnections - maxUserConnections - maxClientConn - maxPreparedStatements - serverLifetime - serverIdleTimeout ITlsMigration: type: object properties: phase: type: string enum: - allow - prefer nullable: true interruptedJobId: type: string nullable: true IPendingMqEvent: type: object properties: event: type: string data: type: object additionalProperties: {} messageId: type: string nullable: true createdAt: type: string format: date-time required: - event - data - createdAt IPasswordRotation: type: object properties: applied: type: boolean nullable: true vaultSynced: type: boolean nullable: true IDatabaseProvisionProgress: type: object properties: phase: type: string enum: - preparing - provisioning - ready - failed message: type: string step: type: string enum: - queued - saving-credentials - choosing-host - reserving-port - creating-storage - checking-capacity - handing-off - applying-config - preparing-runtime - registering-job - waiting-healthy - preparing-cluster - registering-member - waiting-member - initializing-replica-set - ready - failed operation: type: string enum: - create - retry - refresh memberIndex: type: number nullable: true updatedAt: type: string format: date-time required: - phase - message - step - operation - updatedAt IDbImage: type: object properties: name: type: string enum: - mysql - postgresql - mongodb - redis - wordpress - sqlite - duckdb image_url: type: string version: type: string envs: type: array items: type: object properties: value: type: string type: type: string required: - value - type is_available: type: boolean is_default: type: boolean backup_supported: type: boolean restore_supported: type: boolean pgbouncer_supported: type: boolean pgvector_supported: type: boolean manage_user: type: boolean image: type: string ha_image: type: string nullable: true free: type: boolean erd: type: boolean analytics: type: boolean has_port: type: boolean port: type: number httpPort: type: number nullable: true volumePath: type: string protocol: oneOf: - type: string - type: array items: type: string tls_enabled: type: boolean tls_protocol: type: string nullable: true tls_params: type: object additionalProperties: oneOf: - type: string - type: number - type: boolean nullable: true connection: allOf: - $ref: '#/components/schemas/IDbImageConnection' nullable: true ha: type: boolean workbench: type: boolean workbench_mode: type: string enum: - sql - kv - document password_mode: type: string enum: - provided - generated password_change_mode: type: string enum: - live - template httpTitle: type: string httpSubtext: type: string params: type: object additionalProperties: oneOf: - type: string - type: number - type: boolean recommendations: type: array items: type: object properties: cpu: type: string memory: type: string storage: type: string required: - cpu - memory - storage _id: $ref: '#/components/schemas/ObjectId' required: - name - image_url - version - envs - is_available - is_default - backup_supported - restore_supported - pgbouncer_supported - pgvector_supported - manage_user - image - free - erd - analytics - has_port - port - volumePath - protocol - tls_enabled - ha - workbench - workbench_mode - password_mode - password_change_mode - httpTitle - httpSubtext - params - recommendations - _id IHaCluster: type: object properties: clusterName: type: string regions: type: array items: oneOf: - $ref: '#/components/schemas/ObjectId' - $ref: '#/components/schemas/IRegion' nullable: true members: type: array items: $ref: '#/components/schemas/IHaClusterMember' required: - clusterName - members RuntimeVersions: type: object additionalProperties: type: string IServer: type: object properties: name: type: string url: type: string grpc_address: type: string nullable: true ipv6: type: string nullable: true domain: type: string nullable: true node_id: type: string force_deactivation: type: boolean userId: $ref: '#/components/schemas/ObjectId' teamId: allOf: - $ref: '#/components/schemas/ObjectId' nullable: true ip_address: type: string private_ip_address: type: string type: type: string protocol: type: string enum: - TCP - UDP - HTTP - HTTPS status: type: string enum: - active - in-progress - in-active default: type: boolean tag: type: string region: $ref: '#/components/schemas/IRegion' webhook_url: type: string nullable: true is_custom_provision: type: boolean firewall_id: type: string nullable: true specifications: type: object additionalProperties: {} plugin_id: type: string nullable: true provider: type: string provider_location: type: string nullable: true provider_identifier: type: string nullable: true topology_path: type: string nullable: true cert_storage_path: type: string nullable: true meta: type: object additionalProperties: {} _id: $ref: '#/components/schemas/ObjectId' required: - name - url - node_id - force_deactivation - userId - ip_address - private_ip_address - type - protocol - status - default - tag - region - is_custom_provision - specifications - provider - meta - _id ILog: type: object properties: name: type: string key: type: string commit: type: object properties: sha: type: string branch: type: string message: type: string committer: type: object properties: name: type: string email: type: string username: type: string required: - name - email - username required: - sha - branch - message - committer source: type: string status: type: string enum: - AWAITING_CONFIG_APPROVAL - INACTIVE - ACTIVE - INPROGRESS - FAILED - PENDING - CANCELLED - SUPERSEDED - DEGRADED - PAYMENT DUE - NOMAD_READY - NOMAD_FAILED project: $ref: '#/components/schemas/IProject' user: allOf: - $ref: '#/components/schemas/IUser' nullable: true team: allOf: - $ref: '#/components/schemas/ITeam' nullable: true jobs: type: array items: type: object properties: id: type: number name: type: string required: - id - name environment: type: string enum: - PREVIEW - PRODUCTION preview: $ref: '#/components/schemas/IPreview' startTime: oneOf: - type: string - type: string format: date-time endTime: oneOf: - type: string - type: string format: date-time createdAt: oneOf: - type: string - type: string format: date-time updatedAt: oneOf: - type: string - type: string format: date-time deleted: type: boolean _id: $ref: '#/components/schemas/ObjectId' required: - name - key - commit - source - status - project - jobs - environment - preview - startTime - endTime - createdAt - updatedAt - deleted - _id IPreview: type: object properties: name: type: string healthCheckPath: type: string nullable: true pid: type: number port: type: number ip: type: string http2: type: boolean dir: type: string branch: type: string pr_number: type: number nullable: true server: $ref: '#/components/schemas/IServer' project: $ref: '#/components/schemas/IProject' issue_comment_id: type: number status: type: string enum: - AWAITING_CONFIG_APPROVAL - INACTIVE - ACTIVE - INPROGRESS - FAILED - PENDING - CANCELLED - SUPERSEDED - DEGRADED - PAYMENT DUE - NOMAD_READY - NOMAD_FAILED log: $ref: '#/components/schemas/ILog' last_requested: type: string format: date-time isPaused: type: boolean _id: $ref: '#/components/schemas/ObjectId' required: - name - pid - port - ip - http2 - dir - branch - server - project - issue_comment_id - status - log - last_requested - isPaused - _id IProjectSpecs: type: object properties: memory: type: number cpu: type: number storage: type: number region: oneOf: - $ref: '#/components/schemas/ObjectId' - $ref: '#/components/schemas/IRegion' nullable: true required: - memory - cpu - storage IAutoScalingGroup: type: object properties: _id: $ref: '#/components/schemas/ObjectId' name: type: string project: allOf: - $ref: '#/components/schemas/ObjectId' nullable: true replicas: type: number user_id: allOf: - $ref: '#/components/schemas/IUser' nullable: true team_id: allOf: - $ref: '#/components/schemas/ITeam' nullable: true subscription_id: $ref: '#/components/schemas/ICashierSubscription' min_containers: type: number max_containers: type: number active: type: boolean max_cpu: type: number max_memory: type: number meta: type: object additionalProperties: {} createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - _id - name - replicas - subscription_id - min_containers - max_containers - active - max_cpu - max_memory - meta - createdAt - updatedAt IRole: type: object properties: key: type: string name: type: string description: type: string team: oneOf: - $ref: '#/components/schemas/ObjectId' - $ref: '#/components/schemas/ITeam' nullable: true is_system: type: boolean is_custom: type: boolean actions: type: array items: type: string scoped_to_environments: type: boolean created_at: type: string format: date-time nullable: true updated_at: type: string format: date-time nullable: true _id: $ref: '#/components/schemas/ObjectId' required: - key - name - description - is_system - is_custom - actions - scoped_to_environments - _id IDns: type: object properties: name: type: string ttl: type: number type: type: string value: type: string domain: $ref: '#/components/schemas/IDomain' isProxied: type: boolean nullable: true managed_by: type: string nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time _id: $ref: '#/components/schemas/ObjectId' required: - name - ttl - type - value - domain - createdAt - updatedAt - _id IDbImageConnection: type: object properties: user: type: boolean nullable: true database: type: boolean nullable: true protocol: type: string nullable: true port: type: number nullable: true authEnv: type: string nullable: true IRegion: type: object properties: _id: $ref: '#/components/schemas/ObjectId' name: type: string country: type: string cname: type: string continent: type: string enum: - Africa - Europe - America - Asia nullable: true enabled: type: boolean nullable: true dbVolumePath: type: string is_paid: type: boolean logo: type: string provider: type: string provider_identifier: type: string storage_pricing_factor: type: number compute_pricing_factor: type: number floating_ip: type: string nullable: true type: type: string enum: - web - database - sandbox nullable: true ceph_cluster_id: type: string nullable: true volume_backend: type: string enum: - ceph - cloud - s3 nullable: true csi: allOf: - $ref: '#/components/schemas/IRegionCsiConfig' nullable: true required: - _id - name - country - cname - dbVolumePath - is_paid - logo - provider - provider_identifier - storage_pricing_factor - compute_pricing_factor IHaClusterMember: type: object properties: index: type: number role: type: string enum: - primary - replica region: oneOf: - $ref: '#/components/schemas/ObjectId' - $ref: '#/components/schemas/IRegion' volume: oneOf: - $ref: '#/components/schemas/ObjectId' - $ref: '#/components/schemas/IVolume' nullable: true port: type: number publicHost: type: string internalHost: type: string nomadJobId: type: string nullable: true csiVolumeId: type: string nullable: true serverId: type: string nullable: true appliedStorage: type: number nullable: true status: type: string nullable: true required: - index - role - region - port - publicHost - internalHost ICashierSubscription: type: object properties: user_id: $ref: '#/components/schemas/IUser' team_id: allOf: - $ref: '#/components/schemas/ITeam' nullable: true type: type: string stripe_id: type: string stripe_status: type: string stripe_price: type: string nullable: true quantity: type: number nullable: true trial_ends_at: type: string format: date-time nullable: true ends_at: type: string format: date-time nullable: true plan_type: type: string enum: - FREE_PLAN - DEVELOPER_PLAN - TEAM_PLAN - DOMAIN_PLAN - HACKER_PLAN - LISCENSE_PLAN - EMAIL_FORWARDING_PLAN domain_id: type: string nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time _id: $ref: '#/components/schemas/ObjectId' required: - user_id - type - stripe_id - stripe_status - stripe_price - quantity - trial_ends_at - ends_at - plan_type - domain_id - created_at - updated_at - _id IRegionCsiConfig: type: object properties: plugin_id: type: string nullable: true topology_path: type: string nullable: true require_topology: type: boolean nullable: true availability_zone: type: string nullable: true parameters: type: object additionalProperties: type: string nullable: true parameters_env: type: object additionalProperties: type: string nullable: true fs_type: type: string nullable: true attachment_modes: type: array items: type: string nullable: true IVolume: type: object properties: name: type: string user: allOf: - $ref: '#/components/schemas/IUser' nullable: true team: allOf: - $ref: '#/components/schemas/ITeam' nullable: true namespace: type: string size: type: number type: type: string mount_path: type: string nullable: true csi_volume_id: type: string nullable: true region: allOf: - $ref: '#/components/schemas/IRegion' nullable: true attached_sandbox_id: allOf: - $ref: '#/components/schemas/ObjectId' nullable: true attached_project_id: allOf: - $ref: '#/components/schemas/ObjectId' nullable: true last_attached_at: type: string format: date-time nullable: true deleted_at: type: string format: date-time nullable: true created_at: type: string format: date-time nullable: true updated_at: type: string format: date-time nullable: true _id: $ref: '#/components/schemas/ObjectId' required: - name - namespace - size - type - csi_volume_id - region - attached_sandbox_id - attached_project_id - last_attached_at - _id responses: Unauthorized: description: Missing, invalid or expired credentials content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Forbidden: description: >- The API key lacks the required scope, your team role lacks the permission, or the feature is not available on your account content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' ServerError: description: Unexpected server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-brimble-key description: >- API key created in the dashboard under Settings → API keys. Each key carries permission scopes; every endpoint lists the scope it needs. BearerAuth: type: http scheme: bearer bearerFormat: JWT description: Dashboard session token. Use an API key for integrations. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.