API Reference

The Synqly API is a REST API that lets you build and operate integrations programmatically. It is organized around two surfaces that serve distinct purposes and require different credentials.

All API endpoints are relative to a base URL. If you are using Synqly Mesh, the base URL will depend on the region your Organization is deployed in:

If you are unsure of which region is applicable for your Organization, please contact us for support.

All requests require a bearer token in the Authorization header:

Authorization: Bearer <YOUR_TOKEN>

Synqly has two token types, each scoped to a separate API surface. Sending the wrong token type to an API surface returns an error.

For more detail about each token type, see Organization Tokens and Integration Tokens.

The API accepts JSON-encoded request bodies. Include the Content-Type header on all requests that carry a body:

Content-Type: application/json

All responses are JSON-encoded. Successful responses wrap the returned resource in a result field:

{
  "result": {}
}

List responses include a cursor field alongside result. To retrieve the next page, pass the cursor value as the cursor query parameter on the next request. An empty string or null cursor indicates there are no further pages.

{
  "result": [],
  "cursor": "account-xyz"
}

When Meta Functions are used, their output is returned in the meta field alongside result.

If non-fatal warnings or issues occurred during processing, a messages field will be present alongside result.

Error responses use a different structure. See Errors below.

Rate limiting is determined by the upstream provider. When a rate limit is exceeded, the API may return an HTTP 429 Too Many Requests response from the provider.

In some cases, Synqly may automatically retry requests if the provider supplies a Retry-After header and the retry can be completed within the request deadline. In these cases, the retry is handled transparently and the final response is returned to the client.

If no automatic retry is performed, the 429 response is returned to the client.

Clients should implement exponential back-off when handling 429 responses. Avoid fixed-interval retries.

Error responses use a consistent structure regardless of the error code:

{
  "type": "https://docs.synqly.com/problems/not-found",
  "occurred_at": "2024-01-15T10:30:00Z",
  "status": 404,
  "instance": "/v1/accounts/account-123",
  "message": "Account not found",
  "detail": "No account with ID 'account-123' exists in this organization.",
  "cause": [
    {
      "type": "https://docs.synqly.com/problems/resource-not-found",
      "message": "Account not found"
    }
  ]
}

The current API version is v1, encoded in the URL path. Breaking changes are introduced under a new version with advance notice. Non-breaking additions — new fields, new endpoints — may be made to the current version at any time.

Synqly provides SDKs for Go, Python, and Node.js that handle authentication, serialization, and type safety automatically.

If your language is not yet supported, use the REST API directly — see the Quick Start Guide.