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

# Integrations

> Connect an external system once, then turn it into agent skills — either pre-built actions or fields you map yourself.

An **integration** lets an agent act inside an external system — recognize a caller in your CRM,
book on a calendar, look up an order, capture a request. You connect the provider **once** for
your organization, then turn it into [skills](/concepts/skills) on any agent. No code, no
per-agent credentials.

There are two ways to turn a connected provider into a skill:

<CardGroup cols={2}>
  <Card title="Provision pre-built actions" icon="bolt">
    For curated providers, ready-made actions (e.g. "find a customer", "book a visit") install as skills in one call.
  </Card>

  <Card title="Map fields yourself (open model)" icon="diagram-project">
    For any REST/GraphQL provider, discover its full schema and map its fields onto your agent's parameters — like a Zapier you build for your agent.
  </Card>
</CardGroup>

## 1. Provision pre-built actions

For curated providers (Google Calendar, Google Sheets, Shopify, and field-service software), the
actions are already built — you just connect and provision.

<Steps>
  <Step title="Connect the provider">
    `POST /integrations/{kind}/connect` — OAuth returns an `oauthUrl` to approve; API-key
    providers take `{ "credentials": { … } }`. Credentials are stored encrypted, never echoed.
  </Step>

  <Step title="See its actions">
    `GET /integrations/{kind}/actions` lists each action's slug, the parameters it collects, and
    any config an operator must still fill.
  </Step>

  <Step title="Provision onto an agent">
    `POST /agents/{agentId}/integrations/{kind}/provision` turns chosen actions into skills (omit
    `actions` to provision the important ones). Re-running is idempotent.
  </Step>
</Steps>

| Provider        | Connect via | Status |
| --------------- | ----------- | ------ |
| Google Calendar | OAuth       | Live   |
| Google Sheets   | OAuth       | Live   |
| Shopify         | API key     | Live   |

## 2. Map fields from a discovered schema (the open model)

For any provider whose schema can be introspected (REST/OpenAPI, GraphQL, or a **SQL database**),
you don't wait for pre-built actions — you **discover** the provider's entire data model and **map**
the fields you want onto your agent's parameters. The mapping is the integration; there's no
per-provider code.

Your own **[Postgres or MySQL database](/integrations/sql-database)** is the clearest example:
connect with a least-privilege credential, discover the schema, scope out sensitive columns, and
bind a read (or a scoped write) as a skill — walk through it in
[Connect a SQL database](/guides/connect-sql-database).

<Steps>
  <Step title="Discover the schema">
    `POST /integrations/{kind}/discover` introspects the connected provider into a normalized
    **schema** — every object, field, relationship, and operation — and returns a summary
    (object / field / relationship counts). Re-running refreshes it.
  </Step>

  <Step title="Browse the catalog">
    `GET /integrations/{kind}/schema` returns the discovered schema: the objects, their fields
    (with types, whether they're required, allowed values, and what's sensitive), the
    relationships between objects, and the operations you can run. This is the catalog you map from.
  </Step>

  <Step title="Map a binding">
    `POST /agents/{id}/integrations/{kind}/bindings` authors a **binding**: pick an operation,
    map your agent's inputs to its arguments, and **project** which provider fields come back as
    your own output names. It's validated against the schema and compiles to a skill.
  </Step>
</Steps>

<Note>
  A binding maps to your **canonical parameters** (`caller_phone`, `caller_name`,
  `service_address`, …), so the same mapping concept works across any provider, and your agent's
  prompt stays the same whatever system is behind it. Bindings are authored with a human (or the
  AI assistant) in the loop and validated up front — what reaches a live call is a frozen,
  pre-approved skill.
</Note>

Walk through it end to end in [Map an integration's fields](/guides/map-integration-fields).

### Shortcuts: auto-map and preset packs

You don't have to author every binding by hand:

* **Auto-map from a goal** — `POST /agents/{id}/integrations/{kind}/bindings/auto` takes a
  plain-language goal ("look up a caller by phone and return their open tickets"). The AI
  assistant proposes a binding over the discovered schema, validates it, and saves it as a
  **disabled draft** for you to review before enabling. This is the fastest way to go from intent
  to a working skill.
* **Install a preset pack** — many providers ship a **Connector Pack**: curated, ready-to-install
  preset skills plus guidance on how the provider's operations behave and how to identify a caller.
  `GET /integrations/{kind}/pack` reads it; `POST /agents/{id}/integrations/{kind}/pack/install`
  installs the presets onto an agent in one call.

To build a mapping UI of your own, browse the discovered schema piece by piece with
`GET /integrations/{kind}/objects`, `GET /integrations/{kind}/objects/{object}`, and
`GET /integrations/{kind}/operations` instead of pulling the whole schema at once.

## Custom integrations

If a provider can't be introspected, an agent can still reach any system you run: a webhook skill
that calls your own HTTP endpoint, or tools exposed over MCP. See [Build a custom
integration](/integrations/custom).

## In the API

| Action                             | Endpoint                                                   | Scope                |
| ---------------------------------- | ---------------------------------------------------------- | -------------------- |
| Browse the provider catalog        | `GET /integrations/catalog`                                | `integrations:read`  |
| Connect a provider                 | `POST /integrations/{kind}/connect`                        | `integrations:write` |
| List a provider's actions          | `GET /integrations/{kind}/actions`                         | `integrations:read`  |
| Provision actions as skills        | `POST /agents/{agentId}/integrations/{kind}/provision`     | `skills:write`       |
| **Discover the schema**            | `POST /integrations/{kind}/discover`                       | `integrations:write` |
| **Read the discovered schema**     | `GET /integrations/{kind}/schema`                          | `integrations:read`  |
| Browse the discovered objects      | `GET /integrations/{kind}/objects`                         | `integrations:read`  |
| Get one object's detail            | `GET /integrations/{kind}/objects/{object}`                | `integrations:read`  |
| Browse bindable operations         | `GET /integrations/{kind}/operations`                      | `integrations:read`  |
| **Map a binding**                  | `POST /agents/{agentId}/integrations/{kind}/bindings`      | `skills:write`       |
| **Auto-map a binding from a goal** | `POST /agents/{agentId}/integrations/{kind}/bindings/auto` | `skills:write`       |
| Read a provider's preset pack      | `GET /integrations/{kind}/pack`                            | `integrations:read`  |
| Install a provider's preset pack   | `POST /agents/{agentId}/integrations/{kind}/pack/install`  | `skills:write`       |
| Disconnect a provider              | `DELETE /integrations/{kind}`                              | `integrations:write` |

Skills run on the **published** agent — [publish](/concepts/agents) after provisioning or binding.