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.

318 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 Fly 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

Wallet

GET/api/wallet/currencies

Get supported currencies and chains

GET/api/wallet/fees

Get all chain network fees (fee oracle snapshot)

GET/api/wallet/network-status

Get network status (congestion + fee metric per chain)

POST/api/wallet/estimate-network-fee

Estimate network fee (preferred; reads from fee oracle cache)

POST/api/wallet/calculate-fee

Get network fee only (alias for POST /api/wallet/estimate-network-fee)

GET/api/wallet/projects/{projectId}/fee-config

Get project fee configuration (for non-custodial / external users)

PATCH/api/wallet/projects/{projectId}/fee-config

Update project fee configuration (for non-custodial / external users)

POST/api/wallet/generate-key

Generate private key

POST/api/wallet/validate-address

Validate cryptocurrency address

POST/api/wallet/create

Create new wallet (for testing non-custodial)

GET/api/wallet

Get user wallets

GET/api/wallet/{walletId}/balance

Get wallet balance

GET/api/wallet/{walletId}/private-key

Get wallet private key (WARNING: Sensitive data; for testing non-custodial)

POST/api/wallet/{walletId}/withdraw

Prepare withdrawal (semi-transaction; broadcast via non-custodial)

GET/api/wallet/transactions/{transactionId}

Get transaction details

GET/api/wallet/transactions

Get transaction history (custodial wallets; same monitoring as non-custodial)

POST/api/wallet/non-custodial/register-address

Register a non-custodial wallet address

GET/api/wallet/non-custodial/addresses

List registered non-custodial addresses

GET/api/wallet/non-custodial/addresses/{addressId}

Get non-custodial address by ID

PUT/api/wallet/non-custodial/addresses/{addressId}

Update a monitored wallet address

DELETE/api/wallet/non-custodial/addresses/{addressId}

Delete or deactivate a monitored wallet address

GET/api/wallet/non-custodial/addresses/{addressId}/balance

Get balance for a non-custodial address

GET/api/wallet/non-custodial/addresses/{addressId}/transactions

Get transaction history for a non-custodial address

GET/api/wallet/non-custodial/transactions/{txHash}

Get transaction by hash

POST/api/wallet/non-custodial/broadcast

Broadcast a client-signed transaction

POST/api/wallet/non-custodial/speed-up

Get replacement tx params for speed-up (stuck EVM tx)

POST/api/wallet/non-custodial/cancel

Get replacement tx params for cancel (stuck EVM tx)

POST/api/wallet/non-custodial/estimate-gas

Estimate network fee from blockchain (all supported chains; not controlled by Mudbase)

GET/api/wallet/non-custodial/webhooks

List wallet webhooks

POST/api/wallet/non-custodial/webhooks

Create a wallet webhook

PUT/api/wallet/non-custodial/webhooks/{webhookId}

Update a wallet webhook

DELETE/api/wallet/non-custodial/webhooks/{webhookId}

Delete a wallet webhook

GET/api/wallet/non-custodial/webhooks/{webhookId}/logs

Get webhook delivery logs

POST/api/wallet/non-custodial/webhooks/test

Test a webhook delivery (sends a single test payload)

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/billing/webhooks/flutterwave

Payment gateway webhook

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

Enable payment processing for organization

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

Initialize fiat payment with split (org subaccount + platform fee)

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

Get fee breakdown 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: August 2026

Edit this page on GitHub