# 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.

Management API
Configure your integration platform — create accounts, define integration points, manage members, roles, and tokens.

Used to **set up** Synqly.

Connector API
Operate live integrations — query a SIEM, push a ticket, pull identity events, write to storage.

Used to **act on** a live integration.

## Base URL

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:

| Region | Base URL |
|  --- | --- |
| North America | `https://api.synqly.com` |
| Europe | `https://api-eu.synqly.com` |


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

## Authentication

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.

| Token type | Authenticates | How to obtain |
|  --- | --- | --- |
| Organization token | Management API | [Synqly UI](https://app.synqly.com) or [Create Organization Token API](https://docs.synqly.com/api-reference/management/tokens/tokens_create_token) |
| Integration token | Connector API | [Create Integration Token API](https://docs.synqly.com/api-reference/management/tokens/tokens_create_integration_token) |


For more detail about each token type, see [Organization Tokens](https://docs.synqly.com/guides/getting-started/concepts/organization-access-tokens) and [Integration Tokens](https://docs.synqly.com/guides/getting-started/concepts/integration-access-tokens).

## Request format

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


```
Content-Type: application/json
```

## Response format

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


```json
{
  "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.


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

When [Meta Functions](/api-reference/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](#errors) below.

## HTTP methods

| Method | Usage |
|  --- | --- |
| `GET` | Retrieve a resource or a list of resources |
| `POST` | Create a resource |
| `PUT` | Replace a resource |
| `PATCH` | Update specific fields on a resource |
| `DELETE` | Delete a resource |


## HTTP status codes

| Code | Meaning |
|  --- | --- |
| `200 OK` | Request succeeded |
| `400 Bad Request` | Invalid request body or parameters |
| `401 Unauthorized` | Missing or invalid token |
| `403 Forbidden` | Token valid but lacks permission for the operation |
| `404 Not Found` | Resource does not exist |
| `405 Method Not Allowed` | HTTP method not supported for this endpoint |
| `409 Conflict` | Resource already exists or state conflict |
| `415 Unsupported Media Type` | Request body is not JSON or `Content-Type` header is missing |
| `429 Too Many Requests` | Rate limit exceeded — see [Rate limiting](#rate-limiting) |
| `500 Internal Server Error` | Unexpected server-side error |


## Rate limiting

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.

## Errors

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


```json
{
  "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"
    }
  ]
}
```

| Field | Type | Description |
|  --- | --- | --- |
| `type` | URI string | Identifies the problem type. |
| `occurred_at` | datetime string | When the problem occurred. |
| `status` | integer | HTTP status code — matches the response code. |
| `instance` | URI string | Identifies this specific occurrence of the problem. |
| `message` | string | Short, human-readable summary of the problem. Always present. |
| `detail` | string | More detailed explanation. Omitted when not applicable. |
| `remediation` | string | How to fix the problem. Omitted when no remediation is available. |
| `cause` | array | Root cause(s) for the problem. Each entry has `type` and `message`. |
| `context` | object | Additional context — may include the problematic parameter or related resources. |


## Versioning

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.

## SDKs

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

| Language | Package |
|  --- | --- |
| Go | [github.com/Synqly/go-sdk](https://github.com/Synqly/go-sdk) |
| Python | [github.com/Synqly/python-sdk](https://github.com/Synqly/python-sdk) |
| Node.js | [@synqly/client-sdk](https://www.npmjs.com/package/@synqly/client-sdk) |


If your language is not yet supported, use the REST API directly — see the [Quick Start Guide](https://docs.synqly.com/guides/getting-started/overview).