Connections | Fous API Reference

The Connection object

idstringrequired
conn_ followed by 26 characters.
platformobjectrequired
Show child attributesHide child attributes
- namestring
- domainstring
typestringrequired
session: a website login; api_key: the site’s own API key.
sessionapi_key
statusstringrequired
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).
pendingactiveneeds_attention
defaultbooleanrequired
Runs on this platform use it unless a call names another.
hintstring or null
api_key: the last characters of the saved key.
account_hintstring or null
session: the signed-in account, masked.
connect_urlstring
session, until active or while it signs in again: a Fous Studio page where a person signs in to this connection.
sign_inobject
A website sign-in, while it runs and for a while after it failed. Answer its step with POST /v1/connections/{id}/sign-in.
Show child attributesHide child attributes
- statusstringrequired
  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.
  workinginputapprovalfailed
- step_idstring
  input and approval: the step an answer is for.
- messagestringrequired
  What the site asks for, or why it failed, in a sentence for the person.
- codestring
  approval: the number the site shows, which the person picks on their device.
- rejectedboolean
  input: true when the website turned down the last answer; message says so and the same fields are asked again.
- fieldsarray of objectrequired
  What the site asks for. Values are never stored or returned.
  Show child attributesHide child attributes
  - idstringrequired
    The key of its value in fields.
  - labelstringrequired
    What to ask the person for.
  - typestringrequired
    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.
    emailtextpasswordcodeselectcheckboxlink
  - requiredbooleanrequired
  - optionsarray of object
    select: the values it takes.
    Show child attributesHide child attributes
    valuestringrequired
    labelstringrequired
  - lengthinteger
    code: how many characters, when known.
- choicesarray of objectrequired
  input: ways to go on (send one as choice), such as where to send a code.
  Show child attributesHide child attributes
  - idstringrequired
  - labelstringrequired
- expires_atstring
  When the sign-in ends unless it moves on.
sign_in_endedobject
A sign-in the call waited on ended without signing in. An account connected before is unchanged.
Show child attributesHide child attributes
- reasonstringrequired
  cancelledexpired
- messagestringrequired
messagestring
POST /v1/connections for a site whose login is already connected: that this one is the account runs use.
checked_atstring or null
created_atstring

Connection

{  "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

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

Returns

200The organization’s connections.

The answer has these fields:

connectionsarray of Connectionrequired

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

// Save as fous.mts, then run: npx tsx fous.mtsconst response = await fetch('https://api.fous.com/v1/connections', {  headers: {    Authorization: `Bearer ${process.env.FOUS_API_KEY}`,  },});const result = await response.json();if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);console.log(result);

import osimport requestsresponse = requests.get(    "https://api.fous.com/v1/connections",    headers={        "Authorization": f"Bearer {os.environ['FOUS_API_KEY']}",    },    timeout=180,)result = response.json()if not response.ok:    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")print(result)

Sent with your key, kept for this tab only. A run uses credits like any call.

Response 200

{  "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"    }  ]}

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.

platformstringrequired
The site’s domain.
typestringrequired
sessionapi_key
api_keystringOptional
type api_key only.
login_urlstringOptional
type session only: the site’s sign-in page (https, on the site), when it is not the obvious one.
attestbooleanrequired
Your confirmation that you are authorized to use this account for this purpose. Kept on the connection with who confirmed it and when.
true
waitintegerdefault 30Optional
type session: seconds to wait for the sign-in’s first step.

Returns

A Connection object.

200The site’s connection already there: its login (with its sign-in when one runs), or that API key saved before.
201Created; 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

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  }'

// Save as fous.mts, then run: npx tsx fous.mtsconst response = await fetch('https://api.fous.com/v1/connections', {  method: 'POST',  headers: {    Authorization: `Bearer ${process.env.FOUS_API_KEY}`,    'Content-Type': 'application/json',  },  body: JSON.stringify({    platform: 'notion.so',    type: 'session',    attest: true  }),});const result = await response.json();if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);console.log(result);

import osimport requestsresponse = requests.post(    "https://api.fous.com/v1/connections",    headers={        "Authorization": f"Bearer {os.environ['FOUS_API_KEY']}",    },    json={        "platform": "notion.so",        "type": "session",        "attest": True    },    timeout=180,)result = response.json()if not response.ok:    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")print(result)

Sent with your key, kept for this tab only. A run uses credits like any call.

{  "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"  }}

{  "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": {    "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

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

idstringrequired
conn_ followed by 26 characters.

Query parameters

waitintegerdefault 0Optional
Seconds to hold the answer while the sign-in works or waits for an approval, 0 to 60.

Returns

A Connection object.

200The connection.

Errors

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

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

// Save as fous.mts, then run: npx tsx fous.mtsconst response = await fetch('https://api.fous.com/v1/connections/conn_01m5kyvsdxea78rpr2j3qzzd1z', {  headers: {    Authorization: `Bearer ${process.env.FOUS_API_KEY}`,  },});const result = await response.json();if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);console.log(result);

import osimport requestsresponse = requests.get(    "https://api.fous.com/v1/connections/conn_01m5kyvsdxea78rpr2j3qzzd1z",    headers={        "Authorization": f"Bearer {os.environ['FOUS_API_KEY']}",    },    timeout=180,)result = response.json()if not response.ok:    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")print(result)

Sent with your key, kept for this tab only. A run uses credits like any call.

{  "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": {    "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

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

idstringrequired
conn_ followed by 26 characters.

Request body

Required, JSON.

defaultbooleanrequired
true

Returns

A Connection object.

200The connection, now the default.

Errors

Status	Code	When
404	`not_found`	Unknown connection

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  }'

// Save as fous.mts, then run: npx tsx fous.mtsconst response = await fetch('https://api.fous.com/v1/connections/conn_01m5kyvsdxea78rpr2j3qzzd1z', {  method: 'PATCH',  headers: {    Authorization: `Bearer ${process.env.FOUS_API_KEY}`,    'Content-Type': 'application/json',  },  body: JSON.stringify({    default: true  }),});const result = await response.json();if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);console.log(result);

import osimport requestsresponse = requests.patch(    "https://api.fous.com/v1/connections/conn_01m5kyvsdxea78rpr2j3qzzd1z",    headers={        "Authorization": f"Bearer {os.environ['FOUS_API_KEY']}",    },    json={        "default": True    },    timeout=180,)result = response.json()if not response.ok:    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")print(result)

Sent with your key, kept for this tab only. A run uses credits like any call.

{  "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": {    "code": "not_found",    "message": "No such connection.",    "doc_url": "https://docs.fous.com/guides/errors#not_found",    "request_id": "req_mh7c2k9xQ1v3Zt8LbN0pRwY4"  }}

Delete a connection

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

idstringrequired
conn_ followed by 26 characters.

Returns

200Disconnected.

The answer has these fields:

idstring
deletedboolean

Errors

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

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

// Save as fous.mts, then run: npx tsx fous.mtsconst response = await fetch('https://api.fous.com/v1/connections/conn_01m5kyvsdxea78rpr2j3qzzd1z', {  method: 'DELETE',  headers: {    Authorization: `Bearer ${process.env.FOUS_API_KEY}`,  },});const result = await response.json();if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);console.log(result);

import osimport requestsresponse = requests.delete(    "https://api.fous.com/v1/connections/conn_01m5kyvsdxea78rpr2j3qzzd1z",    headers={        "Authorization": f"Bearer {os.environ['FOUS_API_KEY']}",    },    timeout=180,)result = response.json()if not response.ok:    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")print(result)

Sent with your key, kept for this tab only. A run uses credits like any call.

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

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

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

idstringrequired
conn_ followed by 26 characters.

Request body

Required, JSON.

attestbooleanOptional
To start or restart: your confirmation that you are authorized to use this account.
true
restartbooleanOptional
With attest: start again in place of the sign-in that runs.
login_urlstringOptional
With attest: the site’s sign-in page (https, on the site).
step_idstringOptional
The step you answer (sign_in.step_id).
fieldsobjectOptional
With step_id: a value for each of the step’s field ids (required ones filled in).
choicestringOptional
With step_id: the id of one of the step’s choices.
waitintegerdefault 30Optional
Seconds to wait for the next step.

Returns

A Connection object.

200The 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

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"    }  }'

// Save as fous.mts, then run: npx tsx fous.mtsconst response = await fetch('https://api.fous.com/v1/connections/conn_01m5kyvsdxea78rpr2j3qzzd1z/sign-in', {  method: 'POST',  headers: {    Authorization: `Bearer ${process.env.FOUS_API_KEY}`,    'Content-Type': 'application/json',  },  body: JSON.stringify({    step_id: 'stp_7h2k9q',    fields: {      fld_1: 'person@example.com'    }  }),});const result = await response.json();if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);console.log(result);

import osimport requestsresponse = requests.post(    "https://api.fous.com/v1/connections/conn_01m5kyvsdxea78rpr2j3qzzd1z/sign-in",    headers={        "Authorization": f"Bearer {os.environ['FOUS_API_KEY']}",    },    json={        "step_id": "stp_7h2k9q",        "fields": {            "fld_1": "person@example.com"        }    },    timeout=180,)result = response.json()if not response.ok:    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")print(result)

Sent with your key, kept for this tab only. A run uses credits like any call.

{  "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": {    "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

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

Path parameters

idstringrequired
conn_ followed by 26 characters.

Returns

A Connection object.

200The connection.

Errors

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

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

// Save as fous.mts, then run: npx tsx fous.mtsconst response = await fetch('https://api.fous.com/v1/connections/conn_01m5kyvsdxea78rpr2j3qzzd1z/sign-in', {  method: 'DELETE',  headers: {    Authorization: `Bearer ${process.env.FOUS_API_KEY}`,  },});const result = await response.json();if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);console.log(result);

import osimport requestsresponse = requests.delete(    "https://api.fous.com/v1/connections/conn_01m5kyvsdxea78rpr2j3qzzd1z/sign-in",    headers={        "Authorization": f"Bearer {os.environ['FOUS_API_KEY']}",    },    timeout=180,)result = response.json()if not response.ok:    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")print(result)

Sent with your key, kept for this tab only. A run uses credits like any call.

{  "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": {    "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"  }}