---
title: "Create Connection"
method: POST
path: "/v1/graphs/{graph_id}/connections"
tags: ["Connections"]
---

# Create Connection

`POST /v1/graphs/{graph_id}/connections`

## Request

- Base URL: `https://api.robosystems.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.robosystems.ai/v1/graphs/{graph_id}/connections`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

QuickBooks and Mercury: returns a pending connection — complete the OAuth flow to activate (Mercury may instead connect at once with a personal API token where the deployment allows it). External: registers a source namespace for an integration that writes through the public API. One connection allowed per provider per graph, except 'external' which allows one per source_name and 'plaid' which allows one per bank login (a connection still waiting on Link is returned instead of a second). Plaid: returns a pending connection — `POST /oauth/init` returns a `link_token` for Plaid Link. A bank feed (Mercury, Plaid) names the entity its accounts book to (`entity_id`, the group parent when omitted) and is refused (409) when that entity has no chart of accounts or is the one QuickBooks keeps; QuickBooks is refused (409) when the group parent's books are already native.

## Path parameters

- `graph_id` string, required

## Request body

- CreateConnectionRequest: Request to create a new connection.
  - `provider` 'quickbooks' | 'external' | 'mercury' | 'plaid', required: Connection provider type
  - `entity_id` string, nullable: Entity identifier. Required for QuickBooks.
  - `quickbooks_config` QuickBooksConnectionConfig: QuickBooks-specific connection configuration.
    - `realm_id` string, nullable: QuickBooks Realm ID
    - `refresh_token` string, nullable: OAuth refresh token
  - `external_config` ExternalConnectionConfig: External-integration connection configuration. Registers a source namespace for an integration the platform does not run: the connection is registration + telemetry, not execution config. The platform holds no credentials for the external source — the integration authenticates to its own source and writes here through the public API, stamping `source_name` on everything it emits.
    - `source_name` string, required: Source slug the integration stamps on the events it emits (lowercase letters, digits, '-', '_'; must start with a letter). Unique per graph among live connections.
    - `display_name` string, nullable: Human-readable label for the connections UI.
  - `mercury_config` MercuryConnectionConfig: Mercury bank-feed connection configuration. A bank feed is native accounting: the entity its accounts land on must already have a chart of accounts and must not be the one QuickBooks keeps (the group parent, while QuickBooks is connected). Over OAuth (the hosted default) the connection is created `pending_oauth` and activated by the callback. `api_key` — a personal **read-only** Mercury token — connects at once without a browser round-trip, but only on deployments that turn on `MERCURY_API_KEY_CONNECTIONS_ENABLED` (self-hosted and local); the hosted product refuses it.
    - `since_date` string, date, nullable: First day of the backfill (ISO 8601). Defaults to two years back. Incremental syncs never look back before it, and lines dated in a closed period are never captured.
    - `include_treasury` boolean: Capture treasury-account activity alongside checking/savings.
    - `api_key` string, nullable: A personal read-only Mercury API token, for deployments that allow the api_key credential mode. Omit to connect over OAuth.
    - `entity_id` string, nullable: The entity whose books the feed's accounts land on: a subsidiary's id, or omit for the group parent. Required when QuickBooks keeps the parent's books. Each account can be moved to another entity later with `link-bank-account`.
  - `plaid_config` PlaidConnectionConfig: Plaid bank-feed connection configuration. A bank feed is native accounting: the entity its accounts land on must already have a chart of accounts and must not be the one QuickBooks keeps (the group parent, while QuickBooks is connected). The connection is created `pending_oauth`; `POST /oauth/init` returns a `link_token` for Plaid Link, and the `public_token` Link hands back completes it through `POST /oauth/callback/plaid` (as `code`). One connection per institution login; a graph can hold several.
    - `since_date` string, date, nullable: First day of the backfill (ISO 8601), and how much history Plaid is asked to pull for the new Item (at most two years). Defaults to as far back as Plaid goes. Lines dated in a closed period are never captured, whatever the window.
    - `entity_id` string, nullable: The entity whose books the feed's accounts land on: a subsidiary's id, or omit for the group parent. Required when QuickBooks keeps the parent's books. Each account can be moved to another entity later with `link-bank-account`.

## Response `201`

Successful Response

- ConnectionResponse: Connection response model.
  - `connection_id` string, required: Unique connection identifier
  - `provider` string, required: Connection provider type
  - `entity_id` string, nullable: Entity identifier
  - `status` string, required: Connection status
  - `created_at` union, required: Creation timestamp
    - string, date-time
    - string
  - `updated_at` union: Last update timestamp
    - string, date-time
    - string
  - `last_sync` union: Last sync timestamp
    - string, date-time
    - string
  - `write_policy` string, nullable: Source-of-truth write policy: 'native' (RoboSystems is authoritative; no outbound write-back) or 'qb_authoritative' (QuickBooks is authoritative; RoboSystems-originated entries publish to QB). Set via the write-policy endpoint.
  - `source_name` string, nullable: External-provider registered source slug — the value the integration stamps on the events it emits. Null for platform providers.
  - `metadata` object, required: Provider-specific metadata

## Other responses

- `400`: Invalid request
- `401`: Authentication required
- `403`: Access denied
- `404`: Resource not found
- `409`: Connection already exists for this provider
- `422`: Validation Error
- `429`: Rate limit exceeded
- `500`: Internal server error

---

[API](https://skmtc.dev/robosystems/apis/robosystems-api.md) · [All operations](https://skmtc.dev/robosystems/apis/robosystems-api/llms.txt) · [OpenAPI document](https://skmtc.dev/robosystems/apis/robosystems-api/revisions/e661e2d5ca6a?raw)