# Integrations

Integrations connect your workspace to external APIs, including EHR systems, CRMs, scheduling platforms, MCP servers, and custom backends. Each integration defines connection credentials, available endpoints, and health check configuration.

## Key Concepts

* **Base URL + Auth**: Each integration stores connection details for an external API
* **Endpoints**: Named operations (e.g., `list_slots`, `book_appointment`) with HTTP method and path
* **Health Check**: Verify connectivity for all enabled integrations at once
* **Endpoint Testing**: Test a specific endpoint with sample parameters before wiring it into a skill
* **Protocols**: REST (default), FHIR, or MCP (Model Context Protocol)

## Endpoints

| Method   | Path                                                         | Description                                     |
| -------- | ------------------------------------------------------------ | ----------------------------------------------- |
| `POST`   | `/v1/{workspace_id}/integrations`                            | Create an integration                           |
| `GET`    | `/v1/{workspace_id}/integrations`                            | List integrations (paginated, filterable)       |
| `GET`    | `/v1/{workspace_id}/integrations/{id}`                       | Get an integration                              |
| `PUT`    | `/v1/{workspace_id}/integrations/{id}`                       | Update an integration                           |
| `DELETE` | `/v1/{workspace_id}/integrations/{id}`                       | Delete an integration                           |
| `POST`   | `/v1/{workspace_id}/integrations/{id}/endpoints/{name}/test` | Test a specific endpoint                        |
| `GET`    | `/v1/{workspace_id}/integrations/health-check`               | Check connectivity for all enabled integrations |

## Integration Fields

| Field          | Type           | Description                                                       |
| -------------- | -------------- | ----------------------------------------------------------------- |
| `id`           | string         | Unique identifier                                                 |
| `name`         | string         | Slug-format identifier (lowercase, hyphens/underscores, 2+ chars) |
| `display_name` | string         | Human-readable name                                               |
| `protocol`     | string         | `rest`, `fhir`, or `mcp`                                          |
| `base_url`     | string         | API base URL (max 2,048 chars)                                    |
| `auth`         | object or null | Authentication credentials (see below)                            |
| `endpoints`    | array          | Named endpoint configurations                                     |
| `enabled`      | boolean        | Whether the integration is active                                 |
| `builtin`      | boolean        | True for platform-managed integrations (read-only)                |

### Authentication

The `auth` object supports multiple credential types. Secret values (API keys, tokens, private keys) are provisioned to secure storage on creation and never returned in API responses.

| Auth Field            | Description                                          |
| --------------------- | ---------------------------------------------------- |
| `api_key_value`       | API key authentication                               |
| `bearer_token_value`  | Bearer token authentication                          |
| `client_secret_value` | OAuth2 client credentials                            |
| `private_key_value`   | Private key for JWT signing (SMART Backend Services) |

### MCP Integrations

When `protocol` is `mcp`, additional fields configure the MCP server connection:

| Field           | Type   | Description                                        |
| --------------- | ------ | -------------------------------------------------- |
| `mcp_transport` | string | `stdio`, `sse`, or `http`                          |
| `mcp_command`   | string | Command to launch the MCP server (stdio transport) |
| `mcp_args`      | array  | Command arguments                                  |
| `mcp_url`       | string | Server URL (sse/http transport)                    |
| `mcp_headers`   | object | HTTP headers for server connection                 |

## Usage with Skills

Integrations are referenced by [Skills](https://docs.amigo.ai/developer-guide/platform-api/platform-api/skills) via the `integration_tools` field, giving the skill's LLM access to external API endpoints during execution:

```json
{
  "slug": "check-appointments",
  "integration_tools": [
    { "integration_id": "int_abc123", "endpoint_name": "list_slots" }
  ]
}
```

## Endpoint Testing

Test any endpoint in isolation before wiring it into production skills:

```
POST /v1/{workspace_id}/integrations/{id}/endpoints/{endpoint_name}/test
```

Send sample parameters in the request body. The response includes the raw API response, any post-processing results, execution duration, and retry count. This lets you validate connectivity and data formats without affecting production.

## Built-in Integrations

Every workspace includes three immutable, platform-managed integrations that cannot be modified or deleted:

* **Google Maps** - Location search, geocoding, and directions
* **Google Search** - Web search for real-time information retrieval
* **Amigo FHIR** - Clinical data access (see [FHIR](https://docs.amigo.ai/developer-guide/platform-api/platform-api/fhir))

These are available automatically. Custom integrations you create are separate from these built-ins.

## Health Check

Check connectivity for all enabled integrations in a single call:

```
GET /v1/{workspace_id}/integrations/health-check
```

Returns a summary with healthy/unhealthy/total counts and per-integration status.

## Filtering and Pagination

The list endpoint supports:

* `enabled` filter: show only active or inactive integrations
* `protocol` filter: filter by protocol type
* `search`: text search across integration names
* `sort_by`: `name`, `created_at`, or `updated_at`
* Cursor-based pagination with `limit` and `continuation_token`

## API Reference

* [Integrations](https://docs.amigo.ai/api-reference/readme/platform/integrations)