> ## 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.

# Build a custom integration

> Call your own endpoint from a conversation with an http_webhook skill.

No native connector for your system? Build a [skill](/concepts/skills) of type `http_webhook`. The
agent collects inputs from the caller, then calls **your** HTTP endpoint and uses the response in
the conversation. Your service is the integration — Flowyte handles the conversation and the call.

## How it works

A custom skill has two halves:

* **`parametersSchema`** — a JSON Schema describing what the agent collects from the caller. Use a
  proper object schema with a top-level `properties` map (not a flat map). Put only caller-supplied
  inputs here.
* **`executionConfig`** — where to send them: `url` (required), plus optional `method`, `headers`,
  and `timeout_ms`. Operator settings live here, never in `parametersSchema`.

When the agent decides the skill is relevant, it fills the parameters in natural language and POSTs
them to your `url`.

## Create the skill

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://builder.flowyte.com/api/v1/agents/AGENT_ID/skills \
    -H "Authorization: Bearer flowyte_sk_…" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Check warranty status",
      "description": "Look up a warranty by serial number.",
      "skillType": "http_webhook",
      "parametersSchema": {
        "type": "object",
        "properties": {
          "serial_number": { "type": "string", "description": "Product serial number" }
        },
        "required": ["serial_number"]
      },
      "requiredParams": ["serial_number"],
      "executionConfig": {
        "url": "https://api.yourco.com/warranty/lookup",
        "method": "POST",
        "headers": { "X-Api-Key": "…" },
        "timeout_ms": 4000
      }
    }'
  ```

  ```python Python theme={null}
  import requests

  requests.post(
      "https://builder.flowyte.com/api/v1/agents/AGENT_ID/skills",
      headers={"Authorization": "Bearer flowyte_sk_…"},
      json={
          "name": "Check warranty status",
          "description": "Look up a warranty by serial number.",
          "skillType": "http_webhook",
          "parametersSchema": {
              "type": "object",
              "properties": {
                  "serial_number": {"type": "string", "description": "Product serial number"}
              },
              "required": ["serial_number"],
          },
          "requiredParams": ["serial_number"],
          "executionConfig": {
              "url": "https://api.yourco.com/warranty/lookup",
              "method": "POST",
              "headers": {"X-Api-Key": "…"},
              "timeout_ms": 4000,
          },
      },
  )
  ```
</CodeGroup>

<Tip>
  Keep your endpoint fast — return within `timeout_ms` so the agent doesn't stall the caller. Return
  a small JSON body the agent can read back.
</Tip>

## The MCP path (coming soon)

A managed MCP gateway — exposing your tools to the agent over the Model Context Protocol, the same
surface a customer's own LLM can drive — is on the roadmap. The `mcp` skill type is reserved for it.
Until it ships, use `http_webhook` for custom actions. Reserved endpoints respond with **403**
(not 404), so a 403 means a capability exists but isn't enabled for you yet.

## In the API

| Action                 | Endpoint                                         | Scope          |
| ---------------------- | ------------------------------------------------ | -------------- |
| Create a custom skill  | `POST /agents/{agentId}/skills`                  | `skills:write` |
| List skills            | `GET /agents/{agentId}/skills`                   | `skills:read`  |
| Update / remove        | `PATCH` · `DELETE /agents/{agentId}/skills/{id}` | `skills:write` |
| Browse all skill types | `GET /skill-types`                               | `skills:read`  |

<Warning>
  New skills land on the **draft**. [Publish](/concepts/agents) so phone and chat callers can use them.
</Warning>