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

# Connections API

> List, create, update and delete your n8n, Make.com and OpenClaw connections programmatically

## Overview

A **connection** links Opsmatic to one of your automation platforms — an n8n instance, a Make.com account, or an OpenClaw gateway. The Connections API lets you manage them without the dashboard.

All endpoints require an API key with the `connections` permission (see [Authentication](/api-reference/authentication)). Credentials you send are **never returned in plaintext** — responses mask `api_key` and `api_token` values.

Base URL:

```
https://api.opsmatic.com/v1
```

## List Connections

```
GET /v1/connections
```

Requires `connections: read`. Returns connections your key can access (your own plus any organization you belong to), newest first.

### Query Parameters

| Parameter         | Type                              | Description                         |
| ----------------- | --------------------------------- | ----------------------------------- |
| `service_type`    | `n8n` \| `make` \| `openclaw`     | Filter by platform                  |
| `status`          | `active` \| `inactive` \| `error` | Filter by connection status         |
| `organization_id` | string                            | Filter to a single organization     |
| `limit`           | number                            | Page size, max **100** (default 50) |
| `offset`          | number                            | Pagination offset (default 0)       |

```bash theme={null}
curl -H "Authorization: Bearer ops_your_api_key" \
  "https://api.opsmatic.com/v1/connections?service_type=n8n&status=active&limit=20"
```

### Response

```json theme={null}
{
  "connections": [
    {
      "id": "conn_abc123",
      "service_type": "n8n",
      "service_name": "Production n8n",
      "status": "active",
      "base_url": "https://n8n.example.com",
      "api_key": "****************",
      "api_token": null,
      "organization_id": "org_789",
      "organizations": { "id": "org_789", "name": "Acme Agency" },
      "created_at": "2026-01-01T00:00:00Z",
      "_credential_lengths": { "api_key": 40, "api_token": 0 }
    }
  ],
  "pagination": { "total": 1, "limit": 20, "offset": 0, "has_more": false }
}
```

<Note>
  `api_key` / `api_token` are returned masked. The `_credential_lengths` object tells you how long the stored secret is without revealing it — useful for confirming a credential was saved.
</Note>

## Create a Connection

```
POST /v1/connections
```

Requires `connections: write`. New connections are created with `status: "inactive"` until the first successful check.

### Body Fields

| Field             | Required        | Notes                                                                       |
| ----------------- | --------------- | --------------------------------------------------------------------------- |
| `service_type`    | Yes             | `n8n`, `make` or `openclaw`                                                 |
| `service_name`    | Yes             | A friendly label                                                            |
| `base_url`        | n8n only        | Your n8n instance URL                                                       |
| `api_key`         | n8n only        | n8n API key                                                                 |
| `api_token`       | Make only       | Make.com API token                                                          |
| `region`          | Make (optional) | Make.com region                                                             |
| `team_id`         | optional        | Make.com team ID                                                            |
| `organization_id` | optional        | Assign to an organization, or omit / `"personal"` for a personal connection |
| `configuration`   | optional        | Arbitrary JSON config                                                       |

<Tabs>
  <Tab title="n8n">
    ```bash theme={null}
    curl -X POST https://api.opsmatic.com/v1/connections \
      -H "Authorization: Bearer ops_your_api_key" \
      -H "Content-Type: application/json" \
      -d '{
        "service_type": "n8n",
        "service_name": "Production n8n",
        "base_url": "https://n8n.example.com",
        "api_key": "n8n_api_key_here"
      }'
    ```
  </Tab>

  <Tab title="Make.com">
    ```bash theme={null}
    curl -X POST https://api.opsmatic.com/v1/connections \
      -H "Authorization: Bearer ops_your_api_key" \
      -H "Content-Type: application/json" \
      -d '{
        "service_type": "make",
        "service_name": "Client Scenarios",
        "api_token": "make_api_token_here",
        "region": "eu2"
      }'
    ```
  </Tab>

  <Tab title="OpenClaw">
    ```bash theme={null}
    curl -X POST https://api.opsmatic.com/v1/connections \
      -H "Authorization: Bearer ops_your_api_key" \
      -H "Content-Type: application/json" \
      -d '{
        "service_type": "openclaw",
        "service_name": "Gateway US-East"
      }'
    ```
  </Tab>
</Tabs>

<Warning>
  For **OpenClaw** connections the response includes an `ingest_api_key` — a `usage-ingestion` key scoped to the new connection, returned **once**. Configure it in the daemon immediately; it can't be retrieved later. For n8n and Make connections `ingest_api_key` is `null`.
</Warning>

### Response

```json theme={null}
{
  "message": "Connection created successfully",
  "connection": {
    "id": "conn_new456",
    "service_type": "openclaw",
    "service_name": "Gateway US-East",
    "status": "inactive"
  },
  "ingest_api_key": "ops_xxxxxxxxxxxxxxxx"
}
```

## Retrieve a Connection

```
GET /v1/connections/{id}
```

Requires `connections: read` and access to that connection. Returns a single connection with masked credentials.

```bash theme={null}
curl -H "Authorization: Bearer ops_your_api_key" \
  https://api.opsmatic.com/v1/connections/conn_abc123
```

## Update a Connection

```
PUT /v1/connections/{id}
```

Requires `connections: write`. Send only the fields you want to change (e.g. rename, rotate a credential, move organizations).

```bash theme={null}
curl -X PUT https://api.opsmatic.com/v1/connections/conn_abc123 \
  -H "Authorization: Bearer ops_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_name": "Production n8n (EU)" }'
```

## Delete a Connection

```
DELETE /v1/connections/{id}
```

Requires `connections: delete`. Removes the connection and stops all monitoring for it.

```bash theme={null}
curl -X DELETE https://api.opsmatic.com/v1/connections/conn_abc123 \
  -H "Authorization: Bearer ops_your_api_key"
```

## Errors

| Status | Meaning                                                                                    |
| ------ | ------------------------------------------------------------------------------------------ |
| `400`  | Missing/invalid fields (e.g. bad `service_type`, or missing `base_url`/`api_key` for n8n)  |
| `401`  | Missing or invalid API key                                                                 |
| `403`  | Key lacks the `connections` permission, or no access to the target organization/connection |
| `404`  | Connection not found                                                                       |

## Related

<CardGroup cols={2}>
  <Card title="Connecting platforms" icon="plug" href="/connections/overview">
    Step-by-step setup for n8n, Make.com and OpenClaw
  </Card>

  <Card title="Analytics API" icon="chart-line" href="/api-reference/analytics">
    Query the data these connections produce
  </Card>
</CardGroup>