# HTTP API

Call the API from your backend with an application key for the target environment.

```sh
export BROWSERLAYER_API_URL=https://api.browserlayer.dev
# Load BROWSERLAYER_API_KEY from your server's secret configuration.
curl "$BROWSERLAYER_API_URL/connections" \
  -H "Authorization: Bearer $BROWSERLAYER_API_KEY"
```

## Accounts and Link

| Method | Path                          | Body / result                                                          |
| ------ | ----------------------------- | ---------------------------------------------------------------------- |
| POST   | `/link-sessions`              | `{ integration, connection? }` → `{ connection, run, hostedUrl, url }` |
| POST   | `/link-sessions`              | `{ run }` → hosted Link for an existing input wait                     |
| GET    | `/connections`                | Connections visible to this key                                        |
| GET    | `/connections/:id`            | Connection state                                                       |
| POST   | `/connections/:id/disconnect` | Disconnect and delete recoverable credentials                          |

Save IDs against your signed-in user. The API key scopes an environment; your backend enforces which user owns each connection and run. Operator test accounts are unavailable to application keys.

## Endpoints

| Method | Path               | Body / result                                                 |
| ------ | ------------------ | ------------------------------------------------------------- |
| POST   | `/runs`            | `{ integration, flow, connection?, input }` → admitted run ID |
| GET    | `/runs/:id`        | Current status, output/error and any input interaction        |
| POST   | `/runs/:id/cancel` | Request cancellation                                          |

Use `Idempotency-Key` on `POST /runs`. Persist it before admission and reuse it after ambiguous network failures. `flow` is the public endpoint's filename ID. Internal flows and scheduled syncs are not callable through this route.

See [endpoint calls](/docs/call-endpoint) for polling and input handling. Admission does not mean the operation completed.

## Syncs

| Method | Path                                                        | Result                                  |
| ------ | ----------------------------------------------------------- | --------------------------------------- |
| GET    | `/connections/:id/syncs`                                    | Schedules and pending runs              |
| GET    | `/connections/:id/syncs/:sync/records?limit=100&cursor=...` | `{ changes, cursor, hasMore }`          |
| POST   | `/connections/:id/syncs/:sync/pause`                        | Stop new scheduled occurrences          |
| POST   | `/connections/:id/syncs/:sync/start`                        | Enable scheduling and make the sync due |
| POST   | `/connections/:id/syncs/:sync/trigger`                      | Enable scheduling and make the sync due |

`limit` must be 1–1000. Omit `cursor` on the first read. Pausing does not cancel an active run. A waiting sync retains one occurrence until it finishes.

## Errors

Error envelope:

```json
{ "error": { "code": "NOT_FOUND", "message": "Resource not found" } }
```

| Code                        | Next step                                                           |
| --------------------------- | ------------------------------------------------------------------- |
| `NOT_FOUND`                 | Check IDs and environment; the resource may be hidden from this key |
| `FORBIDDEN`                 | Use a key authorized for this environment and operation             |
| `CONNECTION_BUSY`           | Inspect the current run; don't repeatedly start the same mutation   |
| `INPUT_UNAVAILABLE`         | Fetch the run again; it no longer has an attachable input wait      |
| `CONNECTION_REQUIRES_INPUT` | Reconnect, then deliberately begin a new business operation         |
| `ACTION_UNCERTAIN`          | Inspect the website before deciding whether to repeat an action     |

Execution failures appear on the run, even when the admission request succeeded. Check `status` and `error` when polling.

## Operator commands

Deployments, promotion, API key creation and delivery administration require operator access. Use the [CLI](/docs/cli); do not give your application an operator credential.