> For the complete documentation index, see [llms.txt](https://docs.digibee.com/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digibee.com/documentation/developer-guide/development-cycle/build-overview/api/how-to-create-an-api-pipeline.md).
# How to create an API pipeline
This guide walks you through creating and configuring an API pipeline on the Digibee Integration Platform. If you are not familiar with the concept yet, read the [**API**](/documentation/developer-guide/development-cycle/build-overview/api.md) documentation before getting started.
## **Step-by-step guide**
Follow the steps below to create and fully configure an API pipeline.
### **Step 1: Create the pipeline**
1. On the **Pipelines** page, click **Create new**.
2. Select the **API** option.
A sidesheet with the configuration options will open on the right side of the screen.
### **Step 2: Configure the General tab**
You must complete and save all fields in the **General** tab to enable the other tabs.
| Field | Description |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Project** | The project this API belongs to. |
| **API name** | A name for the API. Must be all lowercase with hyphens as separators only. |
| **Description** | A brief description of the API's purpose. |
| **API type** | The gateway where this API is published. **External API** makes the endpoint accessible over the internet. **Internal API** restricts access to other pipelines in your realm or through a VPN. You can enable one or both, but at least one must be enabled. |
Click **Save API** to proceed.
### **Step 3: Configure the remaining tabs**
#### **Endpoints**
**Endpoints**
Click **Import OpenAPI Spec** to import an existing specification, or click **Add endpoint** to add routes manually.
{% hint style="info" %}
Importing an OpenAPI spec adds new routes to the list without overwriting existing ones. Only routes that match an already configured route are updated.
{% endhint %}
| Field | Description |
| ----------- | ----------------------------------------------------------------------- |
| **Method** | The HTTP method: `GET`, `POST`, `PUT`, `PATCH`, `OPTIONS`, or `DELETE`. |
| **Path** | The endpoint path (for example, `/users`). |
| **Summary** | A brief description of the route. |
Once saved, each endpoint becomes a [**Block Execution**](/documentation/connectors-and-triggers/connectors/logic/block-execution.md) connector in the Canvas, configured through its [**OnProcess**](/documentation/developer-guide/development-cycle/build-overview/pipelines/subpipelines.md#onprocess) and [**OnException**](/documentation/developer-guide/development-cycle/build-overview/pipelines/subpipelines.md#onexception) subflows. The **Actions** column then becomes available for each endpoint:
| Icon | Action | Description |
| ------------------------------------------------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| :repeat: **OnProcess** | Open success subflow | Opens the OnProcess subflow for that endpoint in the Canvas. |
| :square-exclamation: **OnException** | Open error subflow | Opens the OnException subflow for that endpoint in the Canvas. |
| :trash: **Delete** | Remove endpoint | Removes the endpoint from this interface. The Block Execution and its subflows remain in the Canvas but disconnected from the flow. |
Inside the Canvas, you can navigate between configured endpoints and switch between their OnProcess and OnException subflows using the **Endpoints** menu in the left sidebar.
Click **Configure API** at any time to return to the configuration page.
**Response headers**
Click **Add key and value** to add response headers returned by the endpoint after processing.
| Field | Description |
| --------- | ----------------- |
| **Key** | The header name. |
| **Value** | The header value. |
#### **Auth**
Enable the authentication methods that apply to your API.
| Option | How it works |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Consumer (API Key)** | Requires a valid API key configured on the platform and associated with this pipeline. Manage API keys on the [Consumers (API Keys)](/documentation/developer-guide/platform-administration/settings/api-keys-consumers.md) page. If this pipeline has associated Consumers, they appear under the **Allowed consumers** section once this option is enabled. |
| **External JWT (Token JWT)** | Requires a JWT token previously generated by another endpoint. Read more in the [JWT implementation](/documentation/connectors-and-triggers/connectors/security/digibee-jwt/digibee-jwt-implementation.md) article. |
| **Basic Auth** | Requires Basic Auth credentials present in the request. Register credentials beforehand on the [Consumers](/documentation/developer-guide/platform-administration/settings/api-keys-consumers.md) page. |
#### **Advanced**
**Timeout and request size**
These parameters define the performance boundaries of your API: how long the pipeline can take to respond and how large the incoming payload can be.
| Parameter | Description | Default |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| **Timeout** | Maximum time (in milliseconds) for the pipeline to process a request before returning a timeout response. Maximum: 900,000 ms. | 30000 ms |
| **Max request size (MB)** | Maximum allowed payload size in megabytes. Cannot exceed 5 MB. If exceeded, the API returns HTTP 413 with `{"message": "Request size limit exceeded"}`. | 5 MB |
**Rate limit**
Applies rate limiting on the API gateway to control how many requests can be made within a given time interval. Available only when **API Key** or **Basic Auth** is enabled in the **Auth** tab.
| Parameter | Description | Default |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| **Limit by** | The entity to which the limits apply. | `API` |
| **Aggregate by** | `Consumer` applies limits per group of credentials. `Credential (API Key, Basic Auth)` applies limits per individual credential. | `Consumer` |
**Rate limit windows**
Click **Add window** to define one or more time-based request limits.
| Field | Description |
| ------------ | ---------------------------------------------------------------------------------------- |
| **Order** | The sequence in which the limit windows are evaluated. Use the arrow buttons to reorder. |
| **Interval** | The unit of time: `seconds`, `minutes`, `hours`, `days`, or `months`. |
| **Limit** | The maximum number of requests allowed within the window. Must be greater than zero. |
{% hint style="info" %}
If multiple windows are configured with the same interval value, only one is considered. Misconfigured windows are ignored and a warning is logged on the [Pipeline Logs](/documentation/developer-guide/development-cycle/dashboards/pipeline-logs.md) page.
{% endhint %}
**Add Cross-Origin Resource Sharing (CORS)**
Cross-Origin Resource Sharing (CORS) is a mechanism that controls which origins are allowed to make requests to your endpoint. Enable this option to define CORS headers specifically for this pipeline.
Click **Add key and value** to add CORS headers.
| Field | Description |
| --------- | --------------------- |
| **Key** | The CORS header name. |
| **Value** | The allowed value. |
{% hint style="info" %}
To configure CORS globally across all pipelines instead of individually, use the [CORS HTTP header policy](/documentation/developer-guide/platform-administration/governance/policies/transformation/cors-http-header.md).
{% endhint %}
**mTLS enabled API**
Enable this option to publish the API on a dedicated gateway with mutual TLS (mTLS) enforced by default. To use this feature in your realm, contact Digibee Support to complete the setup.
{% hint style="info" %}
**mTLS enabled API** does not support **API Key**, **Token JWT**, or **Basic Auth**. You can enable **External API** and **Internal API** alongside mTLS, but it is recommended to leave them disabled.
{% endhint %}
**Allow redelivery of messages**
Enable this option to allow messages to be redelivered if the Pipeline Engine fails. When enabled, messages returned to the processing queue become available for reprocessing by other pipeline replicas or by the same replica after a restart. Read more in the [Pipeline Engine](/documentation/developer-guide/development-cycle/overview/runtime/pipeline-engine.md) article.
#### **Documentation**
Include your API documentation in OpenAPI 3.0 format. This content describes your API's contract and you can use it to generate client SDKs, test your API, or import into tools like Postman or Swagger UI.
### **Next steps**
Once your API pipeline is configured, deploy it on the [Run page](/documentation/developer-guide/development-cycle/overview.md) to make it available for consumption. After deployment, the generated endpoint will be visible on the pipeline card.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.digibee.com/documentation/developer-guide/development-cycle/build-overview/api/how-to-create-an-api-pipeline.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.