API Reference

AlgoBridge exposes a REST API for programmatic access to mappings, health status, monitoring, and sync control.

Base URL

https://your-instance.example.com/api/v1

Authentication

All API requests require a Bearer token. Generate tokens in Settings → API Tokens.

curl -H "Authorization: Bearer sfbs_tok_xxxxxxxxxxxx" \
  https://your-instance.example.com/api/v1/t/{workspaceId}/mappings

Tokens are workspace-scoped. A token created in workspace abc cannot access workspace xyz.

Mappings

List mappings

Returns all active mappings for a workspace.

GET /api/v1/t/:workspaceId/mappings

Response

{
  "success": true,
  "data": [
    {
      "id": "m_01j9...",
      "sf_object": "Contact",
      "pg_table": "contact",
      "sync_direction": "bidirectional",
      "active": true,
      "field_count": 14,
      "created_at": "2026-01-15T10:23:00Z"
    }
  ]
}

Health

Get workspace health

Returns the health status of the PostgreSQL connection, Salesforce connection, and sync engine.

GET /api/v1/t/:workspaceId/health

Response

{
  "success": true,
  "data": {
    "pg": { "status": "healthy", "latency_ms": 4 },
    "sf": { "status": "healthy", "org_id": "00D..." },
    "sync": {
      "status": "running",
      "last_run_at": "2026-03-24T12:00:10Z",
      "pending_rows": 0
    }
  }
}

Status values: healthy | degraded | error | unknown

Monitoring

List activity

Returns the sync activity log (most recent first).

GET /api/v1/t/:workspaceId/monitoring/activity

Query parameters

Parameter	Type	Default	Description
`limit`	integer	`50`	Number of rows to return (max 200)
`offset`	integer	`0`	Pagination offset
`state`	string	—	Filter by state: `NEW`, `PENDING`, `SUCCESS`, `FAILED`
`table`	string	—	Filter by PostgreSQL table name

Response

{
  "success": true,
  "data": [
    {
      "id": 88432,
      "table_name": "contact",
      "sfid": "003Dn00000BxYzAIAV",
      "action": "UPDATE",
      "state": "SUCCESS",
      "_ab_lastop": "UPDATED",
      "created_at": "2026-03-24T12:00:08Z",
      "synced_at": "2026-03-24T12:00:12Z"
    }
  ],
  "meta": { "total": 4291, "limit": 50, "offset": 0 }
}

List errors

Returns only rows in FAILED state with error details.

GET /api/v1/t/:workspaceId/monitoring/errors

Response

{
  "success": true,
  "data": [
    {
      "id": 88100,
      "table_name": "opportunity",
      "sfid": null,
      "action": "INSERT",
      "state": "FAILED",
      "_ab_err": "FIELD_CUSTOM_VALIDATION_EXCEPTION: Close Date is required",
      "created_at": "2026-03-24T11:45:00Z"
    }
  ]
}

Sync Control

Trigger an immediate poll

Bypasses the 10-second schedule and runs a sync cycle immediately for a specific mapping.

POST /api/v1/t/:workspaceId/mappings/:mappingId/poll-now

Response

{
  "success": true,
  "data": {
    "triggered": true,
    "mapping_id": "m_01j9...",
    "message": "Poll triggered. Results will appear in monitoring within seconds."
  }
}

Error responses

All errors follow the same envelope:

{
  "success": false,
  "error": {
    "code": "WORKSPACE_NOT_FOUND",
    "message": "Workspace not found or access denied"
  }
}

Common error codes

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Missing or invalid API token
`FORBIDDEN`	403	Token does not have access to this workspace
`WORKSPACE_NOT_FOUND`	404	Workspace ID does not exist
`MAPPING_NOT_FOUND`	404	Mapping ID does not exist
`RATE_LIMITED`	429	Exceeded 300 requests/minute per IP
`INTERNAL_ERROR`	500	Unexpected server error

Abort a running poll

Aborts an in-progress poll cycle for a specific mapping.

POST /api/v1/t/:workspaceId/mappings/:mappingId/abort

Response

{
  "success": true,
  "data": { "aborted": true }
}

Configuration

Export mapping configuration

Returns all mappings for a workspace as a Heroku Connect-compatible JSON object. Use this to back up or clone your configuration.

GET /api/v1/t/:workspaceId/config/export

Response

{
  "success": true,
  "data": {
    "version": 1,
    "mappings": [
      {
        "object_name": "Contact",
        "config": {
          "sf_notify_enabled": true,
          "sf_polling_seconds": 60,
          "fields": { "Email": {}, "FirstName": {}, "LastName": {} },
          "upsert_field": "Email"
        }
      }
    ]
  }
}

Import mapping configuration

Imports a previously exported JSON configuration. Existing mappings are updated; new ones are created.

POST /api/v1/t/:workspaceId/config/import

Request body: the JSON object returned by the export endpoint.

Response

{
  "success": true,
  "data": { "created": 2, "updated": 1, "skipped": 0 }
}

Save a baseline snapshot

Pins the current mapping configuration as a named baseline. Used as the reference point for drift detection.

POST /api/v1/t/:workspaceId/config/baseline

Response

{
  "success": true,
  "data": { "baseline_id": "bl_01j9...", "captured_at": "2026-05-01T08:00:00Z" }
}

Get configuration drift

Compares the live configuration against the most recent baseline snapshot.

GET /api/v1/t/:workspaceId/config/drift

Response

{
  "success": true,
  "data": {
    "baseline_id": "bl_01j9...",
    "captured_at": "2026-05-01T08:00:00Z",
    "drifted": true,
    "changes": [
      {
        "mapping_id": "m_01j9...",
        "sf_object": "Contact",
        "type": "field_added",
        "field": "MobilePhone"
      }
    ]
  }
}

Audit Log

List audit log entries

Returns the workspace audit log (most recent first).

GET /api/v1/t/:workspaceId/audit-log

Query parameters

Parameter	Type	Default	Description
`limit`	integer	`50`	Number of entries to return (max 500)
`offset`	integer	`0`	Pagination offset
`actor`	string	—	Filter by actor email
`action`	string	—	Filter by action type (e.g. `mapping.created`)

Response

{
  "success": true,
  "data": [
    {
      "id": "al_01j9...",
      "actor": "alice@example.com",
      "action": "mapping.created",
      "resource_type": "mapping",
      "resource_id": "m_01j9...",
      "detail": { "sf_object": "Contact", "pg_table": "contact" },
      "created_at": "2026-05-01T09:15:00Z"
    }
  ],
  "meta": { "total": 312, "limit": 50, "offset": 0 }
}

Download audit log as CSV

Returns a CSV file of the audit log. Accepts the same filter parameters as the list endpoint.

GET /api/v1/t/:workspaceId/audit-log?format=csv

The response has Content-Type: text/csv and Content-Disposition: attachment; filename="audit-log.csv".

Webhooks

List webhook deliveries

Returns the delivery history for a specific webhook endpoint.

GET /api/v1/t/:workspaceId/webhooks/:webhookId/deliveries

Response

{
  "success": true,
  "data": [
    {
      "id": "wd_01j9...",
      "event": "sync.broken",
      "status": "failed",
      "response_code": 500,
      "delivered_at": "2026-05-01T10:00:00Z",
      "next_retry_at": null
    }
  ]
}

Retry a failed delivery

Re-sends a specific delivery attempt.

POST /api/v1/t/:workspaceId/webhooks/:webhookId/deliveries/:deliveryId/retry

Response

{
  "success": true,
  "data": { "queued": true, "delivery_id": "wd_01j9..." }
}

Metrics

Prometheus metrics

Returns current metrics in Prometheus text exposition format. This endpoint is unauthenticated — no Bearer token required. Intended for scraping by a Prometheus server or Grafana Agent.

GET /api/metrics

Response (Content-Type: text/plain; version=0.0.4)

# HELP algobridge_sync_rows_total Total rows synced to Salesforce
# TYPE algobridge_sync_rows_total counter
algobridge_sync_rows_total{workspace_id="ws_abc",object="Contact"} 14293

# HELP algobridge_sync_errors_total Total rows that failed to sync
# TYPE algobridge_sync_errors_total counter
algobridge_sync_errors_total{workspace_id="ws_abc",object="Contact"} 3

# HELP algobridge_trigger_log_queue_depth Current rows in NEW state
# TYPE algobridge_trigger_log_queue_depth gauge
algobridge_trigger_log_queue_depth{workspace_id="ws_abc"} 0

# HELP algobridge_sf_api_calls_total Total Salesforce API calls made
# TYPE algobridge_sf_api_calls_total counter
algobridge_sf_api_calls_total{workspace_id="ws_abc",api="SOAP"} 4821

Note: The /api/metrics path is intentionally outside the authenticated /api/v1/ prefix. Do not add authentication to this endpoint — Prometheus scrapers do not support Bearer tokens by default.

Rate limits

The API is rate-limited to 300 requests per minute per IP address. If you exceed this limit, the API returns 429 Too Many Requests.

For bulk operations, use the poll-now endpoint sparingly — it directly invokes the Salesforce API and counts against your org’s daily API call limit.