# How to document API workflows for external users in Bubble.io: Step-by-Step Guid

- Tool: Bubble
- Difficulty: Intermediate
- Time required: 20-25 min
- Compatibility: All Bubble plans (backend workflows required)
- Last updated: March 2026

## TL;DR

Documenting your Bubble API workflows for external developers requires creating clear endpoint documentation that covers URL paths, parameters, authentication methods, response formats, and versioning. This tutorial covers how to organize your API endpoints, write parameter specifications, provide example requests and responses, and set up a documentation page within your Bubble app or as a separate resource.

## Overview: Documenting API Workflows for External Users

This tutorial guides you through creating professional API documentation for your Bubble backend workflows. External developers who consume your API need clear docs covering endpoints, authentication, parameters, and response formats.

## Before you start

- A Bubble app with backend API workflows exposed
- Backend workflows enabled in Settings → API
- Understanding of REST API concepts
- At least one backend workflow configured as a public API endpoint

## Step-by-step guide

### 1. Inventory your exposed API endpoints

Go to the Workflow tab and navigate to Backend workflows. List every workflow that is checked as 'Expose as a public API workflow.' For each, note: the workflow name (which becomes the URL path: /api/1.1/wf/workflow-name), the HTTP method, all parameters with their types, and the expected return data. Organize endpoints by category (e.g., Users, Orders, Products) for logical grouping in your documentation.

**Expected result:** You have a complete inventory of all exposed API endpoints with their parameters and return data.

### 2. Document authentication requirements

Bubble API workflows support two authentication methods: API token (sent as a Bearer token in the Authorization header) and no authentication (for public endpoints). Find your API token in Settings → API → Generate a new API token. In your documentation, specify: the base URL (https://yourapp.bubbleapps.io/api/1.1/wf/), the authentication header format (Authorization: Bearer [token]), and which endpoints require authentication versus which are public. Include a curl example showing how to authenticate.

**Expected result:** Authentication requirements are clearly documented with example headers and token format.

### 3. Write parameter specifications for each endpoint

For each endpoint, document every parameter: name, data type (text, number, date, yes/no, or custom type), whether it is required or optional, a description of what it does, and example values. For parameters that accept specific values (like status), list all valid options. Format this as a table in your documentation. Include both request parameters (what the caller sends) and response fields (what the API returns).

> Pro tip: Use a consistent documentation format across all endpoints. Tools like Swagger or Postman can help generate structured docs from your API specifications.

**Expected result:** Each endpoint has a complete parameter specification with types, descriptions, and examples.

### 4. Provide request and response examples

For each endpoint, include at least one complete example showing the request and response. Show the full curl command (or equivalent HTTP request) with real-looking sample data. Show the full JSON response including the status and data fields. Include error response examples too — what does a 400 (bad request), 401 (unauthorized), or 404 (not found) response look like? This helps developers debug integration issues quickly.

```
# Example request:
curl -X POST https://yourapp.bubbleapps.io/api/1.1/wf/create-order \
  -H "Authorization: Bearer your_api_token" \
  -H "Content-Type: application/json" \
  -d '{"customer_email": "john@example.com", "product_id": "abc123", "quantity": 2}'

# Example success response:
{"status": "success", "response": {"order_id": "1234567890", "total": 49.98}}

# Example error response:
{"statusCode": 400, "body": {"status": "BAD_REQUEST", "message": "Missing required parameter: customer_email"}}
```

**Expected result:** Each endpoint has complete request and response examples including error cases.

### 5. Build a documentation page in your Bubble app

Create a 'docs' or 'api-docs' page in your Bubble app. Use a clean layout with a sidebar navigation listing all endpoint categories and a main content area showing the documentation. For each endpoint, create a section with: endpoint title, URL, method badge (GET/POST), description, parameter table (Repeating Group of static data or hardcoded), example request (in a styled code block using an HTML element with a <pre> tag), and example response. Add a search bar that filters endpoints by name. This page serves as a living documentation resource that stays close to the API itself.

**Expected result:** A professional API documentation page is available within your Bubble app for external developers.

## Complete code example

File: `Workflow summary`

```text
API DOCUMENTATION TEMPLATE
===========================

BASE URL: https://yourapp.bubbleapps.io/api/1.1/wf/

AUTHENTICATION:
  Header: Authorization: Bearer [api_token]
  Token location: Settings → API → API token

ENDPOINT TEMPLATE:
  Name: [workflow-name]
  Method: POST
  URL: /api/1.1/wf/[workflow-name]
  Authentication: Required

  Parameters:
  | Name        | Type   | Required | Description              |
  |-------------|--------|----------|-------------------------|
  | param_name  | text   | Yes      | Description of parameter |

  Success Response (200):
  {"status": "success", "response": {...}}

  Error Responses:
  400: {"statusCode": 400, "body": {"status": "BAD_REQUEST", "message": "..."}}
  401: {"statusCode": 401, "body": {"status": "UNAUTHORIZED"}}
  404: {"statusCode": 404, "body": {"status": "NOT_FOUND"}}

VERSIONING:
  Current: v1 (api/1.1/wf/)
  Include version in endpoint names for future compatibility
  Example: create-order-v1, create-order-v2
```

## Common mistakes

- **Not documenting error responses** — Developers need to know what errors to expect and handle. Without error documentation, they cannot build robust integrations Fix: Document all possible error responses with status codes, messages, and common causes for each endpoint
- **Letting documentation fall out of sync with the actual API** — Outdated docs cause integration failures and support requests. Developers lose trust in documentation that does not match reality Fix: Update documentation every time you change an endpoint. Consider building the docs page dynamically from a Documentation Data Type.
- **Not including authentication examples** — Many integration issues stem from incorrect authentication. Without clear examples, developers waste time on auth setup Fix: Provide a complete curl example with the authorization header and a working test endpoint for verifying auth

## Best practices

- Include complete request and response examples for every endpoint
- Document all error responses with status codes and messages
- Group endpoints by category for easy navigation
- Provide authentication examples with curl or equivalent
- Keep documentation in sync with actual API changes
- Add a changelog section tracking endpoint additions and changes

## Frequently asked questions

### What URL format do Bubble API endpoints use?

The format is https://yourapp.bubbleapps.io/api/1.1/wf/[workflow-name]. The workflow name in the URL is lowercase with hyphens.

### How do external developers get an API token?

You generate API tokens in Settings → API. You can create multiple tokens for different external users and revoke them individually.

### Can I use Swagger/OpenAPI for Bubble API docs?

Bubble does not auto-generate Swagger specs, but you can manually create an OpenAPI specification file that describes your endpoints and host it alongside your documentation.

### Should I version my API endpoints?

Yes. Include a version identifier in endpoint names (e.g., create-order-v1). This lets you create new versions without breaking existing integrations.

### Can RapidDev help create API documentation for my Bubble app?

Yes. RapidDev can create comprehensive API documentation including endpoint specifications, authentication guides, example code, error references, and interactive documentation pages.

---

Source: https://www.rapidevelopers.com/bubble-tutorial/document-api-workflows-external-users-bubble
© RapidDev — https://www.rapidevelopers.com/bubble-tutorial/document-api-workflows-external-users-bubble