# Connections

> Website logins and API keys that methods run with.

Source: https://docs.fous.com/api-reference/connections
Index: https://docs.fous.com/llms.txt

- `GET /v1/connections`: List connections
- `POST /v1/connections`: Connect an account
- `GET /v1/connections/{id}`: Check a connection
- `PATCH /v1/connections/{id}`: Update a connection
- `DELETE /v1/connections/{id}`: Delete a connection
- `POST /v1/connections/{id}/sign-in`: Run a sign-in
- `DELETE /v1/connections/{id}/sign-in`: Cancel the sign-in

## The Connection object

- `id` (string, required): conn_ followed by 26 characters.
- `platform` (object, required)
  - `name` (string)
  - `domain` (string)
- `type` (string, required): session: a website login; api_key: the site’s own API key. One of `session`, `api_key`.
- `status` (string, required): pending: not signed in yet. active: runs use it. needs_attention: the site signed it out, or the key stopped working; sign in again (connect_url, or POST /v1/connections/{id}/sign-in). One of `pending`, `active`, `needs_attention`.
- `default` (boolean, required): Runs on this platform use it unless a call names another.
- `hint` (string or null): api_key: the last characters of the saved key.
- `account_hint` (string or null): session: the signed-in account, masked.
- `connect_url` (string): session, until active or while it signs in again: a Fous Studio page where a person signs in to this connection.
- `sign_in` (object): A website sign-in, while it runs and for a while after it failed. Answer its step with POST /v1/connections/{id}/sign-in.
  - `status` (string, required): working: Fous is on the site, wait (GET /v1/connections/{id}?wait=). input: the site asks for fields or a choice. approval: the person approves the sign-in on their device or by email, wait. failed: message says why. One of `working`, `input`, `approval`, `failed`.
  - `step_id` (string): input and approval: the step an answer is for.
  - `message` (string, required): What the site asks for, or why it failed, in a sentence for the person.
  - `code` (string): approval: the number the site shows, which the person picks on their device.
  - `rejected` (boolean): input: true when the website turned down the last answer; message says so and the same fields are asked again.
  - `fields` (array of object, required): What the site asks for. Values are never stored or returned.
    - `id` (string, required): The key of its value in fields.
    - `label` (string, required): What to ask the person for.
    - `type` (string, required): checkbox: true or false. select: one of options’ values. link: a sign-in link the person copies from an email without opening it. Every other type: text. One of `email`, `text`, `password`, `code`, `select`, `checkbox`, `link`.
    - `required` (boolean, required)
    - `options` (array of object): select: the values it takes.
      - `value` (string, required)
      - `label` (string, required)
    - `length` (integer): code: how many characters, when known.
  - `choices` (array of object, required): input: ways to go on (send one as choice), such as where to send a code.
    - `id` (string, required)
    - `label` (string, required)
  - `expires_at` (string): When the sign-in ends unless it moves on.
- `sign_in_ended` (object): A sign-in the call waited on ended without signing in. An account connected before is unchanged.
  - `reason` (string, required): One of `cancelled`, `expired`.
  - `message` (string, required)
- `message` (string): POST /v1/connections for a site whose login is already connected: that this one is the account runs use.
- `checked_at` (string or null)
- `created_at` (string)

```json
{
  "id": "conn_01m5kyvsdxea78rpr2j3qzzd1z",
  "platform": {
    "name": "Notion",
    "domain": "notion.so"
  },
  "type": "session",
  "created_at": "2026-10-23T08:43:26.528Z",
  "status": "active",
  "default": true,
  "account_hint": "p…@example.com",
  "checked_at": "2026-10-23T08:44:10.000Z"
}
```

## List connections

`GET https://api.fous.com/v1/connections`

Your organization’s connections, with any sign-in that runs. Free.

### Returns

- `200`: The organization’s connections.

The answer has these fields:

- `connections` ([array of Connection](https://docs.fous.com/api-reference/connections.md#the-connection-object), required)

### Example request

```bash
curl 'https://api.fous.com/v1/connections' \
  -H "Authorization: Bearer $FOUS_API_KEY"
```

### Response 200

```json
{
  "connections": [
    {
      "id": "conn_01m5kyvsdxea78rpr2j3qzzd1z",
      "platform": {
        "name": "Notion",
        "domain": "notion.so"
      },
      "type": "session",
      "created_at": "2026-10-23T08:43:26.528Z",
      "status": "active",
      "default": true,
      "account_hint": "p…@example.com",
      "checked_at": "2026-10-23T08:44:10.000Z"
    }
  ]
}
```

## Connect an account

`POST https://api.fous.com/v1/connections`

type "session": a website login, signed in inside Fous one step at a time. The answer carries the sign-in’s first step (sign_in, after up to wait seconds): the fields the site asks for, which you answer with POST /v1/connections/{id}/sign-in using the person’s details, or the person signs in at connect_url, a Fous Studio page. Once signed in, the connection turns active and becomes the site’s default. An organization has one login per site: asking again answers 200 with that connection, and its sign-in when one runs (an active login stays as it is; to sign in another account, restart the sign-in on it). type "api_key": the site’s own API key, stored encrypted and never returned. The same key sent again for the same site answers 200 with the connection already there (made the site’s default) instead of adding another.

### Request body

Required, JSON.

- `platform` (string, required): The site’s domain.
- `type` (string, required): One of `session`, `api_key`.
- `api_key` (string): type api_key only.
- `login_url` (string): type session only: the site’s sign-in page (https, on the site), when it is not the obvious one.
- `attest` (boolean, required): Your confirmation that you are authorized to use this account for this purpose. Kept on the connection with who confirmed it and when. Must be `true`.
- `wait` (integer): type session: seconds to wait for the sign-in’s first step. Default 30.

### Returns

A [Connection](https://docs.fous.com/api-reference/connections.md#the-connection-object) object.

- `200`: The site’s connection already there: its login (with its sign-in when one runs), or that API key saved before.
- `201`: Created; a login’s sign-in is under way. The same Connection, with status "pending".

### Errors

| Status | Code | When |
| --- | --- | --- |
| 400 | `invalid_request` | Invalid body, or no attest: true |
| 429 | `rate_limited` | Too many requests for the plan this minute |
| 503 | `service_unavailable` | No browser is free for a sign-in now |

### Example request

```bash
curl 'https://api.fous.com/v1/connections' \
  -H "Authorization: Bearer $FOUS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "platform": "notion.so",
    "type": "session",
    "attest": true
  }'
```

With every optional parameter:

```bash
curl 'https://api.fous.com/v1/connections' \
  -H "Authorization: Bearer $FOUS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "platform": "notion.so",
    "type": "session",
    "api_key": "example",
    "login_url": "https://example.com",
    "attest": true,
    "wait": 30
  }'
```

### Response 201

```json
{
  "id": "conn_01m5kyvsdxea78rpr2j3qzzd1z",
  "platform": {
    "name": "Notion",
    "domain": "notion.so"
  },
  "type": "session",
  "created_at": "2026-10-23T08:43:26.528Z",
  "status": "pending",
  "default": false,
  "account_hint": null,
  "connect_url": "https://app.fous.com/org_01M4CD7TVHDBPFQHZD05XMW5PB/connections?connect=conn_01m5kyvsdxea78rpr2j3qzzd1z",
  "checked_at": null,
  "sign_in": {
    "status": "input",
    "step_id": "stp_7h2k9q",
    "message": "Enter your email to continue.",
    "fields": [
      {
        "id": "fld_1",
        "label": "Email address",
        "type": "email",
        "required": true
      }
    ],
    "choices": [],
    "expires_at": "2026-10-23T08:53:41.000Z"
  }
}
```

### Response 200

```json
{
  "id": "conn_01m5kyvsdxea78rpr2j3qzzd1z",
  "platform": {
    "name": "Notion",
    "domain": "notion.so"
  },
  "type": "session",
  "created_at": "2026-10-23T08:43:26.528Z",
  "status": "active",
  "default": true,
  "account_hint": "p…@example.com",
  "checked_at": "2026-10-23T08:44:10.000Z",
  "message": "This organization already has a connected notion.so account (p…@example.com); runs use it. To use another account, sign in again on this connection (it replaces it) or remove it in Studio."
}
```

### Error 400

```json
{
  "error": {
    "code": "invalid_request",
    "message": "Connecting an account needs your confirmation that you are authorized to use it: send attest: true.",
    "doc_url": "https://docs.fous.com/guides/errors#invalid_request",
    "request_id": "req_mh7c2k9xQ1v3Zt8LbN0pRwY4"
  }
}
```

## Check a connection

`GET https://api.fous.com/v1/connections/{id}`

The connection and its sign-in, if one runs. With wait, the answer is held while the sign-in works or waits for the person’s approval, until it moves on.

### Path parameters

- `id` (string, required): conn_ followed by 26 characters.

### Query parameters

- `wait` (integer): Seconds to hold the answer while the sign-in works or waits for an approval, 0 to 60. Default 0.

### Returns

A [Connection](https://docs.fous.com/api-reference/connections.md#the-connection-object) object.

- `200`: The connection.

### Errors

| Status | Code | When |
| --- | --- | --- |
| 400 | `invalid_request` | wait is not 0 to 60 |
| 404 | `not_found` | Unknown connection |

### Example request

```bash
curl 'https://api.fous.com/v1/connections/conn_01m5kyvsdxea78rpr2j3qzzd1z' \
  -H "Authorization: Bearer $FOUS_API_KEY"
```

With every optional parameter:

```bash
curl 'https://api.fous.com/v1/connections/conn_01m5kyvsdxea78rpr2j3qzzd1z?wait=30' \
  -H "Authorization: Bearer $FOUS_API_KEY"
```

### Response 200

```json
{
  "id": "conn_01m5kyvsdxea78rpr2j3qzzd1z",
  "platform": {
    "name": "Notion",
    "domain": "notion.so"
  },
  "type": "session",
  "created_at": "2026-10-23T08:43:26.528Z",
  "status": "active",
  "default": true,
  "account_hint": "p…@example.com",
  "checked_at": "2026-10-23T08:44:10.000Z"
}
```

### Error 400

```json
{
  "error": {
    "code": "invalid_request",
    "message": "wait must be a whole number of seconds, 0 to 60.",
    "doc_url": "https://docs.fous.com/guides/errors#invalid_request",
    "request_id": "req_mh7c2k9xQ1v3Zt8LbN0pRwY4"
  }
}
```

## Update a connection

`PATCH https://api.fous.com/v1/connections/{id}`

Makes the connection its site’s default: the account runs and builds on that site use when a call names none (a working connection still comes before a default that does not work).

### Path parameters

- `id` (string, required): conn_ followed by 26 characters.

### Request body

Required, JSON.

- `default` (boolean, required): Must be `true`.

### Returns

A [Connection](https://docs.fous.com/api-reference/connections.md#the-connection-object) object.

- `200`: The connection, now the default.

### Errors

| Status | Code | When |
| --- | --- | --- |
| 404 | `not_found` | Unknown connection |

### Example request

```bash
curl 'https://api.fous.com/v1/connections/conn_01m5kyvsdxea78rpr2j3qzzd1z' \
  -X PATCH \
  -H "Authorization: Bearer $FOUS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "default": true
  }'
```

### Response 200

```json
{
  "id": "conn_01m5kyvsdxea78rpr2j3qzzd1z",
  "platform": {
    "name": "Notion",
    "domain": "notion.so"
  },
  "type": "session",
  "created_at": "2026-10-23T08:43:26.528Z",
  "status": "active",
  "default": true,
  "account_hint": "p…@example.com",
  "checked_at": "2026-10-23T08:44:10.000Z"
}
```

### Error 404

```json
{
  "error": {
    "code": "not_found",
    "message": "No such connection.",
    "doc_url": "https://docs.fous.com/guides/errors#not_found",
    "request_id": "req_mh7c2k9xQ1v3Zt8LbN0pRwY4"
  }
}
```

## Delete a connection

`DELETE https://api.fous.com/v1/connections/{id}`

Removes the connection and wipes its saved key or sign-in. Only a person signed in to Fous Studio removes a connection: an API key gets 403.

### Path parameters

- `id` (string, required): conn_ followed by 26 characters.

### Returns

- `200`: Disconnected.

The answer has these fields:

- `id` (string)
- `deleted` (boolean)

### Errors

| Status | Code | When |
| --- | --- | --- |
| 403 | `forbidden` | Only Studio removes connections |
| 404 | `not_found` | Unknown connection |

### Example request

```bash
curl 'https://api.fous.com/v1/connections/conn_01m5kyvsdxea78rpr2j3qzzd1z' \
  -X DELETE \
  -H "Authorization: Bearer $FOUS_API_KEY"
```

### Response 200

```json
{
  "id": "conn_01m5kyvsdxea78rpr2j3qzzd1z",
  "deleted": true
}
```

### Error 403

```json
{
  "error": {
    "code": "forbidden",
    "message": "Remove connections in Fous Studio.",
    "doc_url": "https://docs.fous.com/guides/errors#forbidden",
    "request_id": "req_mh7c2k9xQ1v3Zt8LbN0pRwY4"
  }
}
```

## Run a sign-in

`POST https://api.fous.com/v1/connections/{id}/sign-in`

A website login’s sign-in, run inside Fous. {"attest": true} starts one (or answers with the one that runs); add "restart": true to start again in its place, for instance to sign in another account; login_url names the sign-in page. {"step_id", "fields"} answers the current step with the person’s details, by field id; {"step_id", "choice"} picks one of its choices. {} answers with the sign-in as it is. Each call waits up to wait seconds while the sign-in works, then answers with the connection and its next step (sign_in), until it is active. Values are used once to sign in and never returned; Fous keeps them sealed only to sign the account in again by itself when the site signs it out. Starting a sign-in counts against the plan’s requests per minute.

### Path parameters

- `id` (string, required): conn_ followed by 26 characters.

### Request body

Required, JSON.

- `attest` (boolean): To start or restart: your confirmation that you are authorized to use this account. Must be `true`.
- `restart` (boolean): With attest: start again in place of the sign-in that runs.
- `login_url` (string): With attest: the site’s sign-in page (https, on the site).
- `step_id` (string): The step you answer (sign_in.step_id).
- `fields` (object): With step_id: a value for each of the step’s field ids (required ones filled in).
- `choice` (string): With step_id: the id of one of the step’s choices.
- `wait` (integer): Seconds to wait for the next step. Default 30.

### Returns

A [Connection](https://docs.fous.com/api-reference/connections.md#the-connection-object) object.

- `200`: The connection and its next step; active, without sign_in, once signed in.

### Errors

| Status | Code | When |
| --- | --- | --- |
| 400 | `invalid_request` | Invalid answer, an API key, or no attest: true |
| 404 | `not_found` | No such connection, or no sign-in runs |
| 409 | `conflict` | Still working on the last answer, or not the current step |
| 429 | `rate_limited` | Too many requests for the plan this minute |
| 503 | `service_unavailable` | No browser is free for a sign-in now |

### Example request

```bash
curl 'https://api.fous.com/v1/connections/conn_01m5kyvsdxea78rpr2j3qzzd1z/sign-in' \
  -H "Authorization: Bearer $FOUS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "step_id": "stp_7h2k9q",
    "fields": {
      "fld_1": "person@example.com"
    }
  }'
```

With every optional parameter:

```bash
curl 'https://api.fous.com/v1/connections/conn_01m5kyvsdxea78rpr2j3qzzd1z/sign-in' \
  -H "Authorization: Bearer $FOUS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "attest": true,
    "restart": true,
    "login_url": "https://example.com",
    "step_id": "stp_7h2k9q",
    "fields": {
      "fld_1": "person@example.com"
    },
    "choice": "example",
    "wait": 30
  }'
```

### Response 200

```json
{
  "id": "conn_01m5kyvsdxea78rpr2j3qzzd1z",
  "platform": {
    "name": "Notion",
    "domain": "notion.so"
  },
  "type": "session",
  "created_at": "2026-10-23T08:43:26.528Z",
  "status": "pending",
  "default": false,
  "account_hint": null,
  "connect_url": "https://app.fous.com/org_01M4CD7TVHDBPFQHZD05XMW5PB/connections?connect=conn_01m5kyvsdxea78rpr2j3qzzd1z",
  "checked_at": null,
  "sign_in": {
    "status": "input",
    "step_id": "stp_4n8w2c",
    "message": "Enter your password to continue.",
    "fields": [
      {
        "id": "fld_2",
        "label": "Password",
        "type": "password",
        "required": true
      }
    ],
    "choices": [],
    "expires_at": "2026-10-23T08:54:02.000Z"
  }
}
```

### Error 400

```json
{
  "error": {
    "code": "invalid_request",
    "message": "Answer with exactly the step’s field ids (required ones filled in), or with one of its choices.",
    "doc_url": "https://docs.fous.com/guides/errors#invalid_request",
    "request_id": "req_mh7c2k9xQ1v3Zt8LbN0pRwY4"
  }
}
```

## Cancel the sign-in

`DELETE https://api.fous.com/v1/connections/{id}/sign-in`

Stops the sign-in that runs (none: nothing to stop). The connection keeps its status.

### Path parameters

- `id` (string, required): conn_ followed by 26 characters.

### Returns

A [Connection](https://docs.fous.com/api-reference/connections.md#the-connection-object) object.

- `200`: The connection.

### Errors

| Status | Code | When |
| --- | --- | --- |
| 400 | `invalid_request` | An API key |
| 404 | `not_found` | Unknown connection |

### Example request

```bash
curl 'https://api.fous.com/v1/connections/conn_01m5kyvsdxea78rpr2j3qzzd1z/sign-in' \
  -X DELETE \
  -H "Authorization: Bearer $FOUS_API_KEY"
```

### Response 200

```json
{
  "id": "conn_01m5kyvsdxea78rpr2j3qzzd1z",
  "platform": {
    "name": "Notion",
    "domain": "notion.so"
  },
  "type": "session",
  "created_at": "2026-10-23T08:43:26.528Z",
  "status": "pending",
  "default": false,
  "account_hint": null,
  "connect_url": "https://app.fous.com/org_01M4CD7TVHDBPFQHZD05XMW5PB/connections?connect=conn_01m5kyvsdxea78rpr2j3qzzd1z",
  "checked_at": null
}
```

### Error 400

```json
{
  "error": {
    "code": "invalid_request",
    "message": "Only a website login (type session) signs in; this connection is an API key.",
    "doc_url": "https://docs.fous.com/guides/errors#invalid_request",
    "request_id": "req_mh7c2k9xQ1v3Zt8LbN0pRwY4"
  }
}
```