> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/developer-guide/platform-api/integrations.md).

# Integrations

Integrations connect a workspace to external REST APIs such as CRMs, scheduling systems, and custom backends. The Platform API integration surface manages the connection, credential configuration, endpoint definitions, and isolated endpoint tests.

The operations below expose the exact request and response contracts. The surrounding guidance focuses on modeling and design choices.

## Key Concepts

* **Connection**: a REST base URL plus optional authentication configuration.
* **Endpoint definitions**: child resources that describe callable HTTP operations, input schemas, path/query/body mapping, and response handling.
* **Endpoint IDs**: management operations address endpoint child resources by ID. Human-readable endpoint names remain useful for skill configuration and review.
* **Endpoint testing**: test one endpoint with sample parameters before exposing it to a skill or conversation flow.
* **Approval policies**: integrations can require human approval before write operations, or before every endpoint call, depending on workflow risk.
* **Managed connectors**: EHR/FHIR and MCP-style capabilities are handled by connector, data-source, or system-provisioned infrastructure rather than the public REST integrations CRUD surface.

## Integration Operations

### Create an Integration

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/integrations" method="post" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

### List Integrations

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/integrations" method="get" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

### Get an Integration

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/integrations/{integration\_id}" method="get" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

### Update an Integration

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/integrations/{integration\_id}" method="patch" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

### Delete an Integration

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/integrations/{integration\_id}" method="delete" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

## Authentication

The `auth` object's `type` field selects one of the supported credential schemes. Inline secret values are provisioned to secure storage on creation and never returned in API responses.

| `auth.type`                 | Use case                                                                                                                                                  |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `static_header`             | API key or static bearer token sent in a fixed header. For a bearer token, set `header_name` to `Authorization` and store `Bearer <token>` as the secret. |
| `oauth2_client_credentials` | OAuth2 client-credentials grant.                                                                                                                          |
| `oauth2_jwt_bearer`         | OAuth2 JWT-bearer grant.                                                                                                                                  |
| `custom_token_exchange`     | Per-request bearer token minted from a workspace secret plus dynamic identifiers.                                                                         |

The inline secret is a single sibling `secret_value` field on the create/update body; there are no per-type `*_value` fields. SMART on FHIR Backend Services authentication is handled at the connector and data-source layer, not as an integration auth type.

### Custom Token Exchange

`custom_token_exchange` covers third-party APIs that require a per-call bearer token derived from a workspace-level secret plus one or more request-scoped identifiers. For example, an integration can combine a workspace credential with a per-end-user identifier to mint a user-scoped bearer token.

The integration-level `secret_value` is referenced in exchange templates with the `{secret}` placeholder. Treat token reuse and caching as implementation details rather than part of the integration contract.

When the token exchange needs the authenticated external-user identity, bind that parameter with `auth.identity_bindings` so the value is resolved from verified session context instead of model-supplied tool input. See [External User Subject-Key Binding](/developer-guide/platform-api/integrations/external-user-subject-key-binding.md).

## Endpoint Definitions

Define endpoints as child resources on the integration. Each endpoint describes one callable operation:

* HTTP method and path relative to the integration base URL.
* Input schema for the arguments callers may provide.
* Mapping from those arguments into path parameters, query parameters, headers, and request body.
* Optional response shaping so the agent sees only the useful result.

Create or update endpoints before wiring them into a skill. Use endpoint tests to validate auth, parameter mapping, response shape, and upstream error behavior without starting a live conversation.

### Create an Endpoint

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/integrations/{integration\_id}/endpoints" method="post" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

### List Endpoints

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/integrations/{integration\_id}/endpoints" method="get" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

### Get an Endpoint

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/integrations/{integration\_id}/endpoints/{endpoint\_id}" method="get" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

### Update an Endpoint

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/integrations/{integration\_id}/endpoints/{endpoint\_id}" method="patch" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

### Delete an Endpoint

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/integrations/{integration\_id}/endpoints/{endpoint\_id}" method="delete" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

### Test an Endpoint

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/integrations/{integration\_id}/endpoints/{endpoint\_id}/test" method="post" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

## Approval Policies

Use approval policies when an integration call can create, update, delete, or otherwise affect external records. A write-gated policy routes write operations through human approval before execution; an all-gated policy requires approval for every endpoint call. Treat missing approval policy values on older integrations as no approval required.

See [Approval-Gated Integration Writes](/developer-guide/platform-api/integrations/approval-gated-integration-writes.md) for the approval lifecycle, channel coverage, and guidance on deciding what to gate.

## Usage with Skills

Skills reference integration endpoints through `integration_tools`, giving the skill's LLM access to selected external API operations during execution:

```json
{
  "slug": "check-appointments",
  "integration_tools": [
    { "integration": "scheduling", "endpoint": "list_slots" }
  ]
}
```

Keep endpoint input schemas narrow and explicit. The agent uses the schema to decide when to call a tool and how to populate arguments; overly broad schemas increase the chance of malformed upstream requests.


---

# 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.amigo.ai/developer-guide/platform-api/integrations.md?ask=<question>&goal=<endgoal>
```

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