Create Connection

post/v1/graphs/{graph_id}/connections

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) is refused (409) beside a live QuickBooks connection or on a graph with no chart of accounts.

Authentication

Authenticate in any one of these ways — not all of them:

API key in the X-API-Key header.
Bearer token in the Authorization header.

Path parameters

Name	Type	Description
`graph_id`required	string	Graph Id

Request body

Required, application/json.

Field Type Description

providerrequired

string

Connection provider type

One of: quickbooks, external, mercury, plaid

entity_idoptional

string

Entity identifier. Required for QuickBooks.

quickbooks_configoptional

QuickBooksConnectionConfig

QuickBooks-specific connection configuration.

QuickBooksConnectionConfig fields

Field	Type	Description
`realm_id`optional	string	QuickBooks Realm ID
`refresh_token`optional	string	OAuth refresh token

external_configoptional

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.

ExternalConnectionConfig fields

Field	Type	Description
`source_name`required	string	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`optional	string	Human-readable label for the connections UI.

mercury_configoptional

MercuryConnectionConfig

Mercury bank-feed connection configuration. A bank feed is native accounting: the graph must already have a chart of accounts and no live QuickBooks connection. 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.

MercuryConnectionConfig fields

Field Type Description

since_dateoptional

string (date)

First day of the backfill (ISO 8601). Defaults to 1 January of last year. Incremental syncs never look back before it.

include_treasuryoptional

boolean

Capture treasury-account activity alongside checking/savings.

Default: true

api_keyoptional

string

A personal read-only Mercury API token, for deployments that allow the api_key credential mode. Omit to connect over OAuth.

plaid_configoptional

PlaidConnectionConfig

Plaid bank-feed connection configuration. A bank feed is native accounting: the graph must already have a chart of accounts and no live QuickBooks connection. 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.

PlaidConnectionConfig fields

Field	Type	Description
`since_date`optional	string (date)	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 1 January of last year.

Example request

curl

curl -X POST "https://api.robosystems.ai/v1/graphs/{graph_id}/connections" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "provider": "quickbooks"
}'

Responses

201 Successful Response

Field	Type	Description
`connection_id`required	string	Unique connection identifier
`provider`required	string	Connection provider type
`entity_id`optional	string	Entity identifier
`status`required	string	Connection status
`created_at`required	string (date-time) \| string	Creation timestamp
`updated_at`optional	string (date-time) \| string	Last update timestamp
`last_sync`optional	string (date-time) \| string	Last sync timestamp
`write_policy`optional	string	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`optional	string	External-provider registered source slug — the value the integration stamps on the events it emits. Null for platform providers.
`metadata`required	object	Provider-specific metadata

Status	Meaning
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