> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/integrations/catalog/estuary-flow.md).

# Estuary Flow

Connect to Estuary Flow to work with real-time data pipelines: list the captures pulling data from your sources and the collections they land in, create a new capture, publish drafted catalog changes, and check whether a publish succeeded.

### Connectors

Choose the connector that matches your authentication method. The options below use the names shown in StackAI.

| Connector                    | Authentication |
| ---------------------------- | -------------- |
| Estuary Flow (Refresh Token) | Refresh Token  |

#### Estuary Flow (Refresh Token)

Connect to Estuary Flow with a refresh token generated in the dashboard under Admin, CLI-API section, to list captures and collections, create captures, and publish catalog changes. The connection carries the capabilities of the user who generated the token: reading a catalog prefix needs a 'read' grant on it, and publishing needs 'admin'.

**Set up in Estuary Flow**

1. Prepare the Estuary Flow account or service that the workflow will access. Grant access to the required resources and operations.
2. **Refresh Token:** In the Estuary dashboard open Admin, find the CLI-API section, choose Generate token, give it a name, and paste the value here. Paste the generated refresh token, not the short-lived access token shown on the same tab. The connection carries every capability the user who created it holds.

**Set up in StackAI**

1. Open **Settings → Connections**, add a connection, and select **Estuary Flow (Refresh Token)**.
2. Enter the credentials and connection details in the fields below.
3. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it.

**Connection fields**

| StackAI field | Required | What to enter                                                                                                                                                                                                                                                                                                                                                                              |
| ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Refresh Token | Yes      | In the Estuary dashboard open Admin, find the CLI-API section, choose Generate token, give it a name, and paste the value here. Paste the generated refresh token, not the short-lived access token shown on the same tab. The connection carries every capability the user who created it holds. [Provider instructions](https://docs.estuary.dev/guides/how_to_generate_refresh_token/). |

#### Verify the connection

Check that the connection is healthy. Then run a read operation against a resource the connected account can access. A successful connection check confirms authentication; it does not guarantee permission for every action.

If access is denied, check the credential or OAuth permissions, the selected account or environment, and access to the specific resource. Update expired credentials or reconnect after permissions change.

### Use an action

1. Add the required **Estuary Flow** action to the workflow.
2. Select a connection when the action requests one.
3. Complete the required fields. Use the reference picker when a value comes from another workflow step.
4. Run the workflow and inspect the action’s output. Check the result before using it in a later step.

### Actions

#### List Captures

List the data sources (captures) in your Estuary account, with their connector and when each last changed.

**Inputs**

| Field           | Type    | Required | Description                                                                   |
| --------------- | ------- | -------- | ----------------------------------------------------------------------------- |
| Catalog prefix  | string  | No       | Only show captures under this tenant or folder prefix.                        |
| Search          | string  | No       | Find captures whose name or connector contains this text.                     |
| Maximum results | integer | No       | How many captures to return at most. Minimum: 1. Maximum: 1000. Default: 100. |
| Start at        | integer | No       | Skip this many captures before returning results. Minimum: 0. Default: 0.     |

**Outputs**

| Field          | Type          | Description                                                                             |
| -------------- | ------------- | --------------------------------------------------------------------------------------- |
| Captures       | object\_array | The matching captures.                                                                  |
| Next offset    | integer       | Pass this back as Start at to get the next page. Empty when there are no more captures. |
| Returned count | integer       | How many captures this call returned.                                                   |

#### List Collections

List the collections (data streams) in your Estuary account that you can read from or send to a destination.

**Inputs**

| Field           | Type    | Required | Description                                                                      |
| --------------- | ------- | -------- | -------------------------------------------------------------------------------- |
| Catalog prefix  | string  | No       | Only show collections under this tenant or folder prefix.                        |
| Search          | string  | No       | Find collections whose name contains this text.                                  |
| Maximum results | integer | No       | How many collections to return at most. Minimum: 1. Maximum: 1000. Default: 100. |
| Start at        | integer | No       | Skip this many collections before returning results. Minimum: 0. Default: 0.     |

**Outputs**

| Field          | Type          | Description                                                                                |
| -------------- | ------------- | ------------------------------------------------------------------------------------------ |
| Collections    | object\_array | The collections found, most useful fields only.                                            |
| Next offset    | integer       | Pass this back as Start at to get the next page. Empty when there are no more collections. |
| Returned count | integer       | How many collections this call returned.                                                   |

#### Create Capture

Create a new data source in Estuary and publish it so it starts moving data into a collection.

**Inputs**

| Field                      | Type            | Required | Description                                                                                                                                                           |
| -------------------------- | --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Capture name               | string          | Yes      | The full name for the new source, starting with your tenant prefix.                                                                                                   |
| Source connector           | select (string) | Yes      | Which kind of system this capture reads from. Options load from the selected connection.                                                                              |
| Connector version          | select (string) | Yes      | Which version of that connector to use. Options load from the selected connection.                                                                                    |
| Connection settings (JSON) | secret          | Yes      | The source's connection settings as JSON, such as bucket and region. Values are masked, because this usually contains credentials for the source system.              |
| Target collection          | select (string) | Yes      | The collection this source should write its data into. The collection must already exist; this action does not create one. Options load from the selected connection. |
| Source resource (JSON)     | textarea        | Yes      | Which table, stream, or path in the source feeds the target collection, as JSON.                                                                                      |
| Show advanced options      | boolean         | No       | Show the data plane choice and the validate-only switch. Default: false.                                                                                              |
| Data plane                 | select (string) | No       | Where this capture runs. Leave empty to use your account default. Options load from the selected connection.                                                          |
| Validate only              | boolean         | No       | Check that the capture is valid without actually creating it.                                                                                                         |

**Outputs**

| Field          | Type     | Description                                                                                                             |
| -------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- |
| Status         | string   | Whether the capture was created, is still publishing, or failed.                                                        |
| Capture name   | string   | The full name of the capture that now exists.                                                                           |
| Publication ID | string   | Identifier for the publish job, usable with Get Publication Status.                                                     |
| Draft ID       | string   | The draft this action created. If the publish failed, fix the draft in Estuary and republish it with Publish Data Flow. |
| Errors         | textarea | Why the capture could not be published, when it failed.                                                                 |

#### Publish Data Flow

Publish a pending draft in Estuary so your changes go live, or validate it first without publishing.

**Inputs**

| Field                | Type            | Required | Description                                                                       |
| -------------------- | --------------- | -------- | --------------------------------------------------------------------------------- |
| Draft ID             | select (string) | Yes      | The Estuary draft you want to publish. Options load from the selected connection. |
| Validate only        | boolean         | No       | Check that the draft is valid without publishing it. Default: false.              |
| Description          | string          | No       | A short note recorded with this publish, useful in the change history.            |
| Skip unchanged specs | boolean         | No       | Drop specs that have not actually changed before publishing. Default: true.       |

**Outputs**

| Field          | Type     | Description                                                         |
| -------------- | -------- | ------------------------------------------------------------------- |
| Status         | string   | Whether the publish succeeded, is still running, or failed and why. |
| Publication ID | string   | Identifier for the publish job, usable with Get Publication Status. |
| Errors         | textarea | Per-spec error messages when the publish failed.                    |

#### Get Publication Status

Check whether an Estuary publish finished, and get the reason when it failed.

**Inputs**

| Field          | Type   | Required | Description                        |
| -------------- | ------ | -------- | ---------------------------------- |
| Publication ID | string | Yes      | The publish job you want to check. |

**Outputs**

| Field    | Type     | Description                                                                |
| -------- | -------- | -------------------------------------------------------------------------- |
| Status   | string   | The publish outcome, or that it is still running.                          |
| Finished | boolean  | True once the publish has stopped running, whether it succeeded or failed. |
| Errors   | textarea | Why the publish failed, when it did.                                       |

### Important behavior

Actions that create, update, send, or delete data can change the connected service. Review their inputs before running them. A retry can repeat an operation; consider this when configuring retries for actions that change data.

The catalog lists the fields and capabilities available in the supplied provider definition. Availability can also depend on your deployment and organization’s Feature Access settings.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/integrations/catalog/estuary-flow.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
