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

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.