API Reference

Authentication & base URL

The base URL is https://bridglet.com/api/v1. All requests are HTTPS and JSON.

Create an API key on the API Keys page of your dashboard and send it as a Bearer token on every request. Live keys start with bk_live_ and test keys with bk_test_. The key is shown once at creation — store it securely.

export BRIDGLET_KEY="bk_live_..."

http GET https://bridglet.com/api/v1/directories \
  Authorization:"Bearer $BRIDGLET_KEY"

Rate limits

The API allows 120 requests per minute per account. Requests over the limit get a 429 Too Many Requests response; wait for the current minute to pass and retry. Rate-limit headers are not currently returned, so back off on any 429.

HTTP/1.1 429 Too Many Requests

{"error": "Rate limit exceeded"}

Error format

Errors come in two shapes. A single problem uses an "error" string; validation failures use an "errors" object keyed by field name.

Directory limits per plan: Free 1, Starter 5, Pro 25, Business unlimited. See pricing for details.

Lists your directories, newest first. Pass external_id as a query parameter to filter to directories with that external ID.

# All directories
http GET https://bridglet.com/api/v1/directories \
  Authorization:"Bearer $BRIDGLET_KEY"

# Filtered by your own reference ID
http GET https://bridglet.com/api/v1/directories external_id==cust_12345 \
  Authorization:"Bearer $BRIDGLET_KEY"

HTTP/1.1 200 OK

{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "name": "Acme Invoices",
      "slug": "acme-invoices",
      "external_id": "cust_12345",
      "sftp_username": "acme-invoices_k9x2m1",
      "storage_bytes": 48291,
      "inserted_at": "2026-03-28T14:22:31.000000Z"
    }
  ]
}

Provisions a new SFTP directory. The response includes the SFTP password — this is the only time it is returned. Parameters are nested under directory:

• name (required) — display name, max 100 characters. The slug and SFTP username derive from it.
• description — free-text notes.
• external_id — your own reference (customer ID, order ID). Echoed in webhooks and filterable on list.
• metadata — arbitrary JSON object stored as-is.
• max_connections — cap on concurrent SFTP connections for this directory.
• retention_days — auto-delete files older than this many days; 0 (default) keeps files forever.

http POST https://bridglet.com/api/v1/directories \
  Authorization:"Bearer $BRIDGLET_KEY" \
  directory[name]="Acme Invoices" \
  directory[external_id]=cust_12345 \
  directory[max_connections]:=10

HTTP/1.1 201 Created

{
  "data": {
    "id": "a1b2c3d4-...",
    "name": "Acme Invoices",
    "description": null,
    "slug": "acme-invoices",
    "external_id": "cust_12345",
    "metadata": {},
    "sftp_host": "sftp.bridglet.com",
    "sftp_port": 2222,
    "sftp_username": "acme-invoices_k9x2m1",
    "sftp_password": "kJ9xmP2qR7zLn4wa",
    "webhook_url": null,
    "webhook_secret": "Zx9v...24-byte-secret...",
    "max_connections": 10,
    "storage_bytes": 0,
    "retention_days": 0,
    "auth_mode": "password",
    "public_key_fingerprint": null,
    "inserted_at": "2026-03-28T14:22:31.000000Z",
    "updated_at": "2026-03-28T14:22:31.000000Z"
  }
}

Fetches one directory. The response has the same shape as the create response, except sftp_password is never included — passwords are only returned at creation.

http GET https://bridglet.com/api/v1/directories/a1b2c3d4-... \
  Authorization:"Bearer $BRIDGLET_KEY"

Updates a directory. Two kinds of updates share this endpoint:

Basic fields

name, description, webhook_url, external_id, metadata, and max_connections. The slug and SFTP username never change on update. The webhook URL must start with https:// or http://.

http PATCH https://bridglet.com/api/v1/directories/a1b2c3d4-... \
  Authorization:"Bearer $BRIDGLET_KEY" \
  directory[webhook_url]=https://example.com/bridglet-webhook

Auth settings

If the request includes auth_mode or public_key, only those auth fields are applied (requires the account admin role). auth_mode is one of "password", "public_key", or "both"; public_key is an OpenSSH public key. The response includes the key's SHA256 fingerprint.

http PATCH https://bridglet.com/api/v1/directories/a1b2c3d4-... \
  Authorization:"Bearer $BRIDGLET_KEY" \
  directory[auth_mode]=public_key \
  directory[public_key]="ssh-ed25519 AAAA... user@host"

HTTP/1.1 200 OK

{
  "data": {
    "id": "a1b2c3d4-...",
    "auth_mode": "public_key",
    "public_key_fingerprint": "SHA256:mVX0Ic...",
    "...": "...other directory fields..."
  }
}

Permanently deletes a directory and all files in it. The SFTP credentials stop working immediately. This cannot be undone.

http DELETE https://bridglet.com/api/v1/directories/a1b2c3d4-... \
  Authorization:"Bearer $BRIDGLET_KEY"

HTTP/1.1 204 No Content

Lists the files currently in a directory, newest first.

http GET https://bridglet.com/api/v1/directories/a1b2c3d4-.../uploads \
  Authorization:"Bearer $BRIDGLET_KEY"

HTTP/1.1 200 OK

{
  "data": [
    {
      "id": "f6e5d4c3-...",
      "filename": "report_2026-03-28.csv",
      "size_bytes": 48291,
      "uploaded_at": "2026-03-28T14:22:31.000000Z"
    }
  ]
}

Removes the stored public key and reverts the directory to password authentication (requires the account admin role). Returns the updated directory with auth_mode set to "password" and a cleared fingerprint.

http DELETE https://bridglet.com/api/v1/directories/a1b2c3d4-.../public_key \
  Authorization:"Bearer $BRIDGLET_KEY"