API Builder — Wizard Walkthrough
This page walks through each step of the API Builder wizard, explaining not just what to do but why the system is designed this way.
Step 1: Technical Warning
What this step does: Displays a warning that the API Builder requires technical knowledge.
Why it exists: Building API integrations involves decisions that can affect data accuracy, security, and workflow reliability. Misconfigured authentication can expose credentials. Incorrect response mapping can produce garbage data in your workflows. This warning ensures that users entering the builder understand the stakes.
Click "I understand, let's build" to proceed.
Note: This warning is skipped when editing an existing integration — you've already acknowledged it.
Step 2: General Information
What you need before starting this step: Your API's base URL, and the authentication method it uses (from the API's documentation).
Configure the core settings of your integration:
| Field | Required | Description |
|---|---|---|
| Display Name | ✅ Yes | A friendly name for this integration (e.g., "Stripe Payments", "Weather API"). This appears in the workflow node library and integrations list. |
| Base URL | ✅ Yes | The root URL of the API (e.g., https://api.example.com/v1). All endpoint paths are appended to this. |
| Authentication Type | ✅ Yes | How the API authenticates requests. |
Why Base URL Is Separate
You might wonder why the base URL is set once, rather than entering full URLs for each endpoint. Three reasons:
- DRY (Don't Repeat Yourself) — If an API has 10 endpoints, they all share the same base. Entering it once eliminates repetition and typos.
- Version management — When the API releases v2, you update one field (
/v1→/v2) instead of editing every endpoint. - Environment switching — Some APIs have different base URLs for production vs. sandbox. Changing the base URL switches all endpoints at once.
Authentication Configuration
Depending on the auth type you select, additional fields appear:
| Auth Type | Additional Fields | What Happens at Runtime |
|---|---|---|
| API Key (Custom Header) | Header Name (e.g., X-API-Key, Authorization) | Your API key is sent in the specified header with every request |
| Bearer Token | — | Your token is sent as Authorization: Bearer <token> |
| Basic Auth | — | Username and password are Base64-encoded and sent as Authorization: Basic <encoded> |
| No Auth | — | No credentials are sent. Use this only for truly public APIs |
How do I know which header name to use for API Key auth? Check the API's documentation. Common header names include Authorization, X-API-Key, api-key, and X-Auth-Token. The docs will specify exactly which header the API expects.
Click "Next: Define Endpoints" when ready.
Step 3: Define Endpoints
What you need before starting this step: The API documentation for each endpoint you want to use — method, path, parameters, and a sample JSON response.
This is the core of the API Builder. Here you define each API endpoint (operation) that your integration supports. Each endpoint becomes an action you can trigger from a workflow.
Endpoint List
If you've already added endpoints, they appear as cards showing:
- HTTP Method — Color-coded badge (GET = blue, POST = green, PUT/DELETE = gray)
- Path — The endpoint path (e.g.,
/users/{id}) - Summary — A brief description of what the endpoint does
- Endpoint ID — The auto-generated identifier used internally
Click any endpoint card to edit it, or click the trash icon to delete it.
Adding / Editing an Endpoint
The endpoint form has three sections: identity, parameters, and response configuration.
Endpoint Identity
| Field | Required | Description |
|---|---|---|
| Method | ✅ Yes | HTTP method: GET, POST, PUT, or DELETE |
| Path | ✅ Yes | The endpoint path relative to the Base URL (e.g., /users/{id}, /orders). Use {paramName} for path parameters. |
| Summary | ❌ No | A short description (e.g., "Get All Users", "Create Order"). Helps your team understand what this endpoint does. |
| Endpoint ID | Auto | Automatically generated from the method + path (e.g., get_users_id). Used internally to identify this endpoint in workflows. |
Why is the ID auto-generated? Consistency. The ID is derived from the method and path so it's always predictable and unique. This prevents naming conflicts when your integration has many endpoints.
Parameters
Click "Add Param" to define parameters the endpoint accepts:
| Field | Options | Description |
|---|---|---|
| Name | Text | The parameter name exactly as the API expects it (e.g., id, limit, page, sort_by) |
| In | Query / Path / Header / Body | Where this parameter is sent in the HTTP request |
| Required | Checkbox | Whether the API requires this parameter |
Where does each parameter type go?
- Query → Added to the URL:
GET /users?limit=10&page=2 - Path → Injected into the URL:
GET /users/42(replaces{id}) - Header → Sent as an HTTP header:
X-Custom: value - Body → Sent as JSON in the request body (POST/PUT only)
Important: Parameter names must match the API's documentation exactly. userId is different from user_id — the API won't recognize parameters with the wrong name.
Response Data Handling
This is the most powerful part of the endpoint form. It lets you map API response fields to structured workflow outputs. See JSON Response Parser for a thorough explanation.
Click "Add Endpoint" (or "Update Endpoint" if editing) to save this endpoint to your integration.
Click "Next: Workflow Usage" when you've defined all your endpoints.
Step 4: Review & Save
What this step does: Shows a summary of your integration and saves it to the database.
The review screen displays:
- Service name — The display name you chose
- Base URL — The API root
- Number of endpoints — How many operations you defined
Click "Save Definition" to save the integration. This creates a record with:
- A unique service key that identifies this integration
- Your complete API definition (base URL, auth config, all endpoints)
- A credential schema that matches your auth type — this determines what fields are shown when users add credentials later
After saving, you're redirected to the Integrations page.
Why is saving separate from adding credentials? The integration definition describes how to talk to an API — the shape of requests, the structure of responses. Credentials are the actual secret values (API keys, tokens) that authorize access. Keeping them separate means:
- The definition can be reused across environments (staging vs. production)
- Credentials are stored with encryption, isolated from the definition
- Different team members can use the same integration with their own credentials
After Saving: Credentials & Workflow Usage
Configuring Credentials
Once the integration definition is saved, you need to add credentials before it can be used:
- Go to Integrations and find your new custom integration.
- Click "Add Credential" or "Configure".
- Enter the authentication details based on your auth type:
| Auth Type | What You Enter |
|---|---|
| API Key | Your API key value |
| Bearer Token | Your access token |
| Basic Auth | Username and password |
- Save the credential.
Credentials are stored with encryption and are never exposed in the UI after saving.
Using in Workflows
After saving the definition and adding credentials, your custom integration appears as a node in the Workflow Editor:
- Open a workflow in the Workflow Editor.
- Open the Node Library.
- Find your custom integration in the App or Custom category — it appears with the Display Name you chose.
- Drag it onto the canvas.
- In the Properties Panel:
- Select the credential to use
- Select the endpoint to call
- Set any required parameters (the parameter list comes from your endpoint definition)
- The node's outputs are the fields you defined in the endpoint's response configuration — downstream nodes can reference them by label.
┌──────────────┐ ┌──────────────────┐ ┌──────────────┐
│ Trigger Node │ ──▶ │ Your Custom API │ ──▶ │ Process Data │
│ │ │ Node │ │ │
│ Provides: │ │ Calls: │ │ Receives: │
│ - customerId │ │ GET /customers/ │ │ - Name │
│ │ │ {customerId} │ │ - Email │
│ │ │ │ │ - Revenue │
└──────────────┘ └──────────────────┘ └──────────────┘
Next Steps
- JSON Response Parser — Deep dive into the response mapping system
- Examples — See complete real-world integrations built from scratch
- Troubleshooting & Glossary — Common issues and technical term reference