> ## Documentation Index
> Fetch the complete documentation index at: https://docs.letsflow.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# HTTP API

> Connect an HTTP API and use it in automations.

export const flowWebUrl = "https://app.letsflow.ai";

Use HTTP API to connect an API that Flow does not publish as its own integration. An organization administrator creates it from **Integrations**. Flow builds automation actions from the API source you provide.

## Automation imports

Use the HTTP namespace when you author an automation:

```typescript theme={null}
import * as api from "@flow/integrations/http/example_api";
```

Replace `example_api` with your connector key. Existing published automations keep running with the compatibility namespace. Before you edit, test, or publish one again, ask Flow to migrate its imports and save a draft. Migration does not publish the draft.

Import HTTP request and result types from `@flow/integrations/http`. Import common integration types from `@flow/integrations`:

```typescript theme={null}
import type { IntegrationActionResult, IntegrationCallOptions } from "@flow/integrations";
import type { HttpRequestOptions, HttpResultData } from "@flow/integrations/http";
```

## Who can create it

Only an organization administrator can create a custom integration. Anyone else sees **Organization administrator required**, and **Connect** stays unavailable. Ask an administrator to set it up from this page.

## Connect in Flow

<Steps>
  <Step title="Find HTTP API">
    1. Open **Integrations**.
    2. Choose **Add connection**.
    3. In **Add connection**, search for **HTTP API**.
    4. Select the **HTTP API** card.

    The wizard is titled **Connect an HTTP API**.

    <a className="flow-app-link" href={flowWebUrl}>
      Open Flow

      <svg aria-hidden="true" viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
        <path d="M7 7h10v10" />

        <path d="M7 17 17 7" />
      </svg>
    </a>
  </Step>

  <Step title="Choose who can use the connection">
    On **Teams**, **Connection available to** starts at **All teams**. **All teams** includes every current team and teams created later. That choice makes the connection available to all teams in the organization.

    Clear **All teams** and select teams when only those teams should use the connection. That choice makes the connection available only to the teams you select.

    Select **Continue**.
  </Step>

  <Step title="Review permissions">
    **Permissions** shows **Automations**: run provider actions from your automations. **How it's granted** reads **Follows the API credentials you provide**.

    Select **Continue**. Flow builds the actions from the API source on **Connect**.
  </Step>

  <Step title="Enter the API and connect">
    Complete the fields in the tables below, then choose **Connect**.

    **No authentication** creates the connection without a credential window. **API key** opens a window where you enter the key. If Flow skips part of the API source, it shows **Connected with setup warnings**.
  </Step>
</Steps>

## Connection fields

| Field | When you see it | What to enter |
| - | - | - |
| **Integration name** | Always | Required. Names the custom integration and its connection. The placeholder is **Example API**. The name must be 1 to 120 characters and contain a letter or digit. |
| **Connection description (optional)** | Always | What this connection is for. The placeholder is **Describe to teammates what this connection is for**. |
| **API description** | Always | Required. What the API is used for. The placeholder is **Describe the API and what it is used for.** |
| **Definition source** | Always | Required. Starts at **OpenAPI URL**. The choices are in [API source](#api-source). |
| **Source URL** | **OpenAPI URL** or **Documentation URL** | Required HTTPS address, without credentials. The placeholder is `https://developer.example.com/openapi.yaml`. |
| **API document** | **Paste OpenAPI** or **Paste documentation** | Required text area for either an OpenAPI document or API documentation. The placeholder is **Paste an OpenAPI document or API documentation.** |
| **API base URL** | Always | Required HTTPS address, such as `https://api.example.com`. Leave out any username, password, or query string. |
| **Authentication** | Always | **No authentication** or **API key**. Starts at **No authentication**. |

## API source

| Choice | What Flow uses |
| - | - |
| **OpenAPI URL** | The OpenAPI document at **Source URL**. Flow creates actions from the operations it can use. |
| **Paste OpenAPI** | The OpenAPI document you paste. Flow creates actions from the operations it can use. |
| **Documentation URL** | The page at **Source URL**. Flow uses an OpenAPI document linked from that page when it finds one. Otherwise Flow reads the documentation and creates actions from it. |
| **Paste documentation** | The documentation you paste. Flow reads it and creates actions from it. |
| **Arbitrary HTTP requests only** | No API document. This choice adds no actions. |

## API key fields

These fields appear when **Authentication** is **API key**.

| Field | What to enter |
| - | - |
| **Token location** | **Request header** or **Query parameter**. Starts at **Request header**. |
| **Header or query parameter name** | The header name, or the query parameter name. A request header starts at `Authorization`. Switching to **Query parameter** clears the default name, but keeps a name you entered. Check that the name is the query parameter you want to use. **Connect** stays unavailable if the name is empty. |
| **Token format** | **Bearer token** sends the word Bearer and the token. **Auth token** sends the token alone. Starts at **Bearer token**. |
| **Credential label** | Optional name for the credential. The placeholder is **API token**. |

## After you connect

Flow opens the integration you named. On the **Automations** tab, an organization administrator selects **Enable**.

For **All teams**, the tab says **Automations is not yet enabled on this connection**. An organization administrator selects **Enable**. Anyone else sees **Ask an organization admin to enable Automation.**

For a selected team, the tab says that team hasn't enabled Automation on this connection. An organization administrator, or that team's manager, selects **Enable**. Anyone else sees **Ask an organization admin or this team's manager to enable Automation.**

Once enabled, automations can use this connection's actions, subject to your action policies.

A **No authentication** connection shows its endpoint on the connection details. **Reauthorize** stays unavailable and explains **This connection does not use authentication**. The integrations list labels that connection **No Auth**.

## Related

* [Automation integrations](/automations/connectors)
* [Use integration actions](/automations/build/connectors)

## Uncertain requests

An API can accept a request before its response times out. If Flow cannot safely repeat a POST or PATCH request, it stops automatic retries and reports an uncertain outcome. Adding an arbitrary idempotency header does not make the request safe to repeat.

An API can also change data before returning HTTP 408, 429, or 503. A `Retry-After` header suggests when to retry; it does not prove that the request had no effect. Flow keeps these unprotected requests uncertain, even when the response includes that header.

For example, an API might create an onboarding ticket while Flow is waiting for a response. Check that API for the ticket before you rerun the automation. A rerun can create another ticket. See [Run history and debugging](/automations/run/run-history-and-debugging) for recovery guidance.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.