---
title: Symbiant API
description: "Symbiant has a REST API so your own systems can read and write Symbiant data. This article explains how to get access, authenticate and make requests. The examples use the Incidents module, but every module works the same way. **Note:**…"
url: "https://support.symbiant.co.uk/kb/symbiant-api/"
updated: "2026-10-30"
category: Advanced System Functionality
---

# Symbiant API

Symbiant has a REST API so your own systems can read and write Symbiant data. This article explains how to get access, authenticate and make requests. The examples use the Incidents module, but every module works the same way.

**Note:** Before you can use the API, Symbiant must allow your server's IP address to connect. Raise a [support ticket](https://support.symbiant.co.uk/submit-ticket/) to arrange this.

## What You Need

- A Symbiant user account with an **API-enabled role**. If you don't have one, raise a support ticket.
- An **EDN** (Extensible Data Notation) parser for your language, for example [edn-java](https://github.com/bpsm/edn-java), [jsedn](https://github.com/shaunxcode/jsedn), [edn-ruby](https://github.com/relevance/edn-ruby) or [edn_format for Python](https://pypi.org/project/edn-format/).
- A **Transit** encoder and decoder, for example [transit-java](https://github.com/cognitect/transit-java), [transit-js](https://github.com/cognitect/transit-js), [transit-ruby](https://github.com/cognitect/transit-ruby) or [transit-python](https://github.com/cognitect/transit-python).

**Warning:** These libraries are written by third parties. Symbiant can't guarantee them, and you use them at your own risk.

## How Access Works

Every API request is made as a specific user with an API-enabled role. The API applies the same permissions as the Symbiant app: the user can only read and change what they could in the app, including only records in their divisions. Make sure the user has the roles and divisions the job needs.

## Getting an API Token

1. Sign in to Symbiant as the API-enabled user.
2. Click the three dots (⋮) at the top right, then **API token**. If you don't see it, the user doesn't have an API-enabled role.

![API token in the menu](https://support.symbiant.co.uk/wp-content/uploads/2026/10/symbiant-api-01-api-menu.png)

1. A text file downloads. It contains everything you need:

![The parts of the API token file](https://support.symbiant.co.uk/wp-content/uploads/2026/10/symbiant-api-02-api-token-file.png)

| Item | What it's for |
| --- | --- |
| `:id_token` | The token you send with every request |
| `:expires_in` | How many seconds the token lasts (for example 900, which is 15 minutes) |
| `:refresh_token` | Used to get a new `:id_token` without signing in again |
| `:api_url` | The address to send requests to. In the examples below it is written `{{:api_url}}` |
| `:client_id`, `:refresh_url` | Used when refreshing the token |

**Critical:** Keep the token file secret. Anyone with it can act as that user until it expires.

## Making Requests

The API follows the usual REST pattern. The address starts with `/read/` for reading and `/write/` for changes:

| Action | Method | Address |
| --- | --- | --- |
| Read records | GET | `{{:api_url}}/read/modules/{module}` |
| Read one record | GET | `{{:api_url}}/read/modules/{module}/{reference}` |
| Create a record | POST | `{{:api_url}}/write/modules/{module}` |
| Update a record | PATCH | `{{:api_url}}/write/modules/{module}/{reference}` |
| Delete a record | DELETE | `{{:api_url}}/write/modules/{module}/{reference}` |

**Tip:** `:api_url` already ends with a slash, so don't add a second one.

Every request needs these headers:

![The headers every request needs](https://support.symbiant.co.uk/wp-content/uploads/2026/10/symbiant-api-03-api-get-template.png)

Request and response bodies are EDN, encoded with Transit (JSON). Attribute names are namespaced keywords, for example `:incident/reference` (written `"~:incident/reference"` in Transit).

## Reading a Record (GET)

This reads incident 9:

![A GET request for one incident](https://support.symbiant.co.uk/wp-content/uploads/2026/10/symbiant-api-04-api-get-example.png)

The response holds the record's attributes and values. Drop-down and linked values come back with their text and IDs:

![Part of the response](https://support.symbiant.co.uk/wp-content/uploads/2026/10/symbiant-api-05-api-get-response.png)

## GET Filters

Add filters to the address to narrow the results:

| Filter | Meaning | Value |
| --- | --- | --- |
| `p` | pull | A comma-separated list of the attributes to return |
| `e` | equal to | Attribute and value separated by a comma; use a semi-colon to go into nested attributes |
| `n` | not equal to | As above |
| `l` | less than | As above |
| `g` | greater than | As above |
| `le` | less than or equal to | As above |
| `ge` | greater than or equal to | As above |
| `c` | contains | As above. Text values only, URL encoded, and case sensitive |
| `x` | exists | Must have the listed attributes |
| `m` | missing | Must not have the listed attributes |

For example, `?p=incident/reference,generic/summary` returns only the reference and summary of every incident:

![A GET with the pull filter](https://support.symbiant.co.uk/wp-content/uploads/2026/10/symbiant-api-06-api-get-filter.png)

## Finding Resources and Attributes (help)

Put `/help` in front of any address to see its structure instead of its data:

- `{{:api_url}}/help` lists every resource and attribute.
- `{{:api_url}}/help/read/modules/{module}/{reference}` shows what a GET returns.
- `{{:api_url}}/help/write/modules/{module}` shows what a POST needs. Add a reference to see what a PATCH accepts.

The results show each attribute, whether it's required, whether it holds a list, and which is the primary key.

![The help output for creating an incident](https://support.symbiant.co.uk/wp-content/uploads/2026/10/symbiant-api-07-api-help.png)

Module names match the app. When you open a module, the address bar shows its name, for example `app.symbiant.cloud/modules/incidents` or `/modules/register-risks`. Use the same name in the API.

## Creating a Record (POST)

The primary key (for example `:incident/reference`) is always required, along with any attributes the help output marks as required (for example `:generic/summary`). Linked values such as divisions are given by ID.

![A POST creating an incident](https://support.symbiant.co.uk/wp-content/uploads/2026/10/symbiant-api-08-api-post.png)

## Updating a Record (PATCH)

Always include the primary key, then only the attributes you're changing. Don't send unchanged attributes, because they would add noise to the audit trail. This example adds a division to incident 101:

![A PATCH adding a division](https://support.symbiant.co.uk/wp-content/uploads/2026/10/symbiant-api-09-api-patch.png)

## Removing Values

To remove a value, put it under `:tx/retract` in a PATCH:

![Removing a division with tx/retract](https://support.symbiant.co.uk/wp-content/uploads/2026/10/symbiant-api-10-api-retract.png)

## Deleting a Record (DELETE)

**Critical:** A DELETE request removes the record straight away.

![A DELETE request](https://support.symbiant.co.uk/wp-content/uploads/2026/10/symbiant-api-11-api-delete.png)

## Refreshing the Token

Before the `:id_token` expires, use the refresh token to get a new one. Send a POST to the `:refresh_url` from your token file:

![Refreshing the token](https://support.symbiant.co.uk/wp-content/uploads/2026/10/symbiant-api-12-api-refresh.png)

The response contains a new `id_token` and `refresh_token`. It doesn't include the URLs or client ID, so keep using those from the original token file.

## Testing the Connection with Postman

You can check you can connect with a tool such as [Postman](https://www.postman.com/). Postman can't decode Transit, so use it only to test the connection. (The Postman screenshots are from an earlier version of this article.)

1. Create a **GET** request.

![A GET request in Postman](https://support.symbiant.co.uk/wp-content/uploads/2022/05/GET_Request.png)

1. Open **Headers**, then add **Origin** (your Symbiant app address, for example `https://app.symbiant.cloud`) and **Content-Type** (`application/transit+json`).

![The Origin header](https://support.symbiant.co.uk/wp-content/uploads/2022/05/Origin_Type.png)

![The Content-Type header](https://support.symbiant.co.uk/wp-content/uploads/2022/05/Content-Type.png)

1. Open **Authorization**, set **Auth Type** to **Bearer Token**, and paste in only the `:id_token` value (not the whole file, and not the refresh token).

![Choosing Bearer Token](https://support.symbiant.co.uk/wp-content/uploads/2022/05/Auth_Type.png)

1. Enter an address, for example `{{:api_url}}/read/modules/incidents/1`, and click **Send**. A **200 OK** status with data in the body means the connection works.

![A successful response](https://support.symbiant.co.uk/wp-content/uploads/2022/05/Body_Response.png)
