API Reference

API Reference Overview

Base URL, authentication, rate limits, pagination, and errors. Browse all endpoints below or try the API in the Playground.

Quick reference

Base URLhttps://api.mudbase.dev
AuthenticationAuthorization: Bearer YOUR_API_KEY or X-API-Key
Rate limitPer API key, configurable - see Rate Limits
SpecDownload OpenAPI

Base URL

text
https://api.mudbase.dev
https://api.mudbase.dev

Authentication

Send your API key in the Authorization: Bearer YOUR_API_KEY header, or use X-API-Key for server-to-server. See Authentication (Concepts) and User Authentication.

Get your API key
Create and manage API keys in the Mudbase Console under your project settings.

Rate limits

Limits are set per API key and vary by endpoint - auth endpoints are stricter than general traffic. When exceeded, the API returns 429 Too Many Requests. See Rate Limits.

Pagination

List endpoints support limit and cursor (or offset). Responses include next_page when more results exist. See Pagination.

Errors

Standard HTTP status codes: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 429 Rate limited, 5xx Server error. See Error Explorer for full reference.

Try the API

Use the Playground to send live requests, or import the OpenAPI spec into Postman.

Open API PlaygroundRun in PostmanDownload OpenAPI

Endpoints

All API operations grouped by tag. Filter by path, method, or tag, or click any endpoint for parameters, request/response schemas, and try-it-live.

294 endpoints

Authentication

POST/api/auth/register

Register new user

POST/api/auth/login

Login user

GET/api/auth/session

Get current session

POST/api/auth/logout

Logout user

POST/api/auth/refresh

Refresh access token (org and project)

POST/api/auth/verify-email

Verify email address (no auth)

POST/api/auth/resend-verification

Resend verification email (no auth)

POST/api/auth/password-reset

Request password reset (organization / platform)

POST/api/auth/password-reset/validate

Validate password reset token

POST/api/auth/password-reset/{token}

Reset password with token (organization / platform)

GET/api/auth/oauth-org/providers

Get available OAuth providers for organization-based auth

GET/api/auth/oauth-org/{provider}

Initiate OAuth authentication for organization

GET/api/auth/oauth-org/callback/{provider}

OAuth callback handler for organization

POST/api/auth/local/register

Register new user (project-based)

POST/api/auth/local/login

Login user (project-based)

POST/api/auth/local/logout

Logout user (project-based)

GET/api/auth/local/session

Get current session (project-based)

POST/api/auth/accept-invite

Accept organization invitation

POST/api/auth/local/password-reset

Request password reset (project-based, OTP)

POST/api/auth/local/password-reset/confirm

Confirm password reset with OTP (project-based)

POST/api/auth/local/password-reset/{token}

Reset password with token (project-based, legacy)

GET/api/auth/oauth/{provider}/{projectId}

Initiate OAuth authentication

GET/api/auth/oauth/callback/{provider}

OAuth callback handler (project-based)

GET/api/auth/oauth/providers/available

Get all available OAuth providers

POST/api/auth/magic-link/send

Send magic link

POST/api/auth/magic-link/verify

Verify magic link

POST/api/auth/otp/send

Send OTP code

POST/api/auth/otp/verify

Verify OTP code

POST/api/auth/anonymous

Create anonymous session

POST/api/auth/anonymous/convert

Convert anonymous account to full account

Organizations

GET/api/orgs

Get all organizations for user

GET/api/orgs/{orgId}

Get organization details by ID

PATCH/api/orgs/{orgId}

Update organization

DELETE/api/orgs/{orgId}

Delete organization

GET/api/orgs/{orgId}/projects/{projectId}/domains

List custom domains and DNS verification hints

POST/api/orgs/{orgId}/projects/{projectId}/domains

Add a custom domain

GET/api/orgs/{orgId}/projects/{projectId}/domains/{hostname}/dns-instructions

Get DNS TXT record instructions for one hostname

PATCH/api/orgs/{orgId}/projects/{projectId}/domains/primary

Set primary custom domain

POST/api/orgs/{orgId}/projects/{projectId}/domains/{hostname}/verify-dns

Verify domain ownership via DNS TXT

POST/api/orgs/{orgId}/projects/{projectId}/domains/{hostname}/platform-ready

Notify platform ops that hosting or edge work is ready (email)

POST/api/orgs/{orgId}/projects/{projectId}/domains/{hostname}/submit-cname

Custom domain step 2 (optional): org confirms routing CNAME was added

POST/api/orgs/{orgId}/projects/{projectId}/domains/{hostname}/verify-platform-dns

Custom domain step 3: verify platform DNS (manual TXT or managed certificate readiness)

PATCH/api/orgs/{orgId}/projects/{projectId}/domains/{hostname}

Update domain status or regenerate verification token

DELETE/api/orgs/{orgId}/projects/{projectId}/domains/{hostname}

Remove a custom domain

POST/internal/provision-enterprise

Provision enterprise dedicated API/DB (internal)

GET/internal/custom-domain/sweep-status

Custom domain background sweep status (internal)

POST/internal/domain-dns/recheck-batch

Batch DNS re-verification for drift (internal)

POST/internal/org/custom-domain-addon

Enable/disable Growth/Scale custom domain add-on (internal)

GET/api/orgs/{orgId}/members

Get organization members

GET/api/orgs/{orgId}/users

List organization users with metadata

PATCH/api/orgs/{orgId}/users/{userId}/status

Update user account status (activate or suspend)

GET/api/orgs/{orgId}/users/{userId}/overview

Get user overview and data footprint

GET/api/orgs/{orgId}/projects/{projectId}/users

List project users with metadata

POST/api/orgs/{orgId}/invite

Invite team member to organization

PATCH/api/orgs/{orgId}/members/{userId}/role

Update member role

DELETE/api/orgs/{orgId}/members/{userId}

Remove team member from organization

GET/api/orgs/{orgId}/usage

Get organization usage and billing

PATCH/api/orgs/plan/{orgId}

Update organization plan

Messaging

GET/api/messaging/projects/{projectId}/messaging/devices

List registered device tokens

POST/api/messaging/projects/{projectId}/messaging/devices

Register a device push token

DELETE/api/messaging/projects/{projectId}/messaging/devices

Unregister a device push token

POST/api/messaging/projects/{projectId}/messaging/push

Send push notification

POST/api/messaging/projects/{projectId}/messaging/email

Send email

POST/api/messaging/projects/{projectId}/messaging/sms

Send SMS

GET/api/messaging/projects/{projectId}/messaging/sms-provider

Get BYO SMS provider configuration (masked)

PATCH/api/messaging/projects/{projectId}/messaging/sms-provider

Update BYO SMS provider credentials

GET/api/messaging/projects/{projectId}/messaging/push-config

Get bring-your-own push credentials status (masked)

PATCH/api/messaging/projects/{projectId}/messaging/push-config

Set or clear your own push service account (optional)

GET/api/messaging/projects/{projectId}/messaging/web-push-config

Get native Web Push (VAPID) configuration

PATCH/api/messaging/projects/{projectId}/messaging/web-push-config

Update native Web Push (VAPID) configuration

GET/api/messaging/projects/{projectId}/messaging/web-push/public-key

Get the Web Push public key (public)

GET/api/messaging/projects/{projectId}/messaging/web-push/subscriptions

List registered Web Push subscriptions

POST/api/messaging/projects/{projectId}/messaging/web-push/subscriptions

Register a browser Web Push subscription

DELETE/api/messaging/projects/{projectId}/messaging/web-push/subscriptions

Unregister a Web Push subscription

GET/api/messaging/projects/{projectId}/messaging/history

Get message history

GET/api/messaging/projects/{projectId}/messaging/stats

Get message statistics

Billing

GET/api/billing/plans

Get subscription tiers (org-level BaaS plans)

GET/api/billing/plans/{planId}

Get one subscription tier by id

POST/api/billing/org/checkout

Initialize org-level BaaS plan payment (Starter, Growth, Scale)

POST/api/billing/org/verify-payment

Verify org-level plan payment

GET/api/billing/estimate

Get billing estimate and forecast

GET/api/billing/projects/{projectId}/plans

Get billing plans

POST/api/billing/projects/{projectId}/plans

Create billing plan

PATCH/api/billing/projects/{projectId}/plans/{planId}

Update billing plan

DELETE/api/billing/projects/{projectId}/plans/{planId}

Delete billing plan

GET/api/billing/public/projects/{projectId}/plans

Get public plans (no auth required)

POST/api/billing/public/projects/{projectId}/checkout

Create checkout session (fiat)

GET/api/billing/public/projects/{projectId}/checkout/{paymentId}

Get checkout payment details (not used for fiat billing)

POST/api/billing/public/projects/{projectId}/verify-payment

Verify payment and create subscription

GET/api/billing/projects/{projectId}/subscriptions

Get subscriptions

POST/api/billing/subscriptions/{subscriptionId}/cancel

Cancel subscription

GET/api/billing/public/projects/{projectId}/subscription

Check subscription status (public)

GET/api/billing/public/projects/{projectId}/feature-access

Check feature access (public)

POST/api/billing/public/projects/{projectId}/usage

Record usage (public)

GET/api/billing/projects/{projectId}/dashboard

Get billing dashboard data

GET/api/billing/projects/{projectId}/invoices

List project invoices

GET/api/billing/projects/{projectId}/invoices/{invoiceId}

Get single invoice

GET/api/billing/projects/{projectId}/invoices/{invoiceId}/download

Download invoice PDF

GET/api/billing/projects/{projectId}/invoices/{invoiceId}/export

Export invoice (e.g. PDF URL or file)

POST/api/orgs/{orgId}/payment-processing/enable

Submit payout onboarding for organization

GET/api/orgs/{orgId}/payment-processing/status

Get payout-onboarding status for organization

POST/api/orgs/{orgId}/payment-processing/initialize-payment

Initialize fiat payment

GET/api/orgs/{orgId}/payment-processing/countries

List supported payout countries

GET/api/orgs/{orgId}/payment-processing/banks

List settlement banks for a payout country

GET/api/orgs/{orgId}/payment-processing/fee-breakdown

Preview the fee for a given amount

GET/api/orgs/{orgId}/payment-processing/records

List fiat payment records for organization

POST/api/projects/{projectId}/payment-processing/initialize-payment

Initialize fiat payment (project-scoped)

Next

NEXT →API PlaygroundSearch any endpoint and send a live request.NEXT →QuickstartInstall the SDK and make your first request.NEXT →AuthenticationAPI keys, Bearer tokens, and user sessions.

Last updated: September 2026

Edit this page on GitHub
Chat with us