# Connect API

> Create, read, and cancel hosted Connect sessions.

## Create a Hosted Connect session

`POST /connect/sessions` on `https://api.finchnode.com/api/v1`

Categories must be a subset of the app allowlist. Reusing an Idempotency-Key with the same body returns the original session and an Idempotent-Replayed header. Reusing it with a different body returns idempotency_conflict.

Parameters:

- `Idempotency-Key` (header, string): App- and environment-scoped retry key.

Body:

- `externalId` (string): Opaque caller reference. Do not place email, name, or health information here.
- `categories` (string[])
- `syncMode` (string)
- `durationDays` (integer)
- `returnUrl` (string)

Responses:

- `201`: Session created or idempotently recovered.
- `400`: Request validation failed.
- `401`: API key is missing, invalid, or revoked.
- `403`: App scope, environment, or consent does not authorize the request.
- `409`: Request conflicts with resource state or idempotency history.
- `413`: Request body exceeds 64 KiB.
- `429`: Request budget exceeded.

## Retrieve Connect session and source-sync state

`GET /connect/sessions/{sessionId}` on `https://api.finchnode.com/api/v1`

Parameters:

- `sessionId` (path, string, required)

Responses:

- `200`: Current session. Subject is non-null only after completion.
- `401`: API key is missing, invalid, or revoked.
- `404`: App-scoped resource does not exist.
- `429`: Request budget exceeded.

## Cancel an incomplete Connect session

`POST /connect/sessions/{sessionId}/cancel` on `https://api.finchnode.com/api/v1`

Parameters:

- `sessionId` (path, string, required)

Responses:

- `200`: Canceled session. Repeating the request is safe.
- `401`: API key is missing, invalid, or revoked.
- `404`: App-scoped resource does not exist.
- `409`: Request conflicts with resource state or idempotency history.
- `410`: Consent or session is no longer active.