> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elementum.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Elementum API

> Get started with the Elementum API to integrate with your systems and streamline workflow automation.

## Overview

Our API is designed to provide you with programmatic access to core features of Elementum, enabling you to build integrations, automate workflows, and extend the capabilities of your Elementum workspace.

This guide will walk you through the essential steps to get started, from authentication to making your first API call.

<CardGroup cols={2}>
  <Card title="Elementum API Specification" icon="code" href="https://api.elementum.io">
    View the full OpenAPI specification file for a complete list of endpoints and schemas.
  </Card>

  <Card title="API Status" icon="chart-line" href="https://status.elementum.io">
    Check the current status of our API services and get notified of any issues.
  </Card>
</CardGroup>

## Authentication

API access is at the user level. You create a Client ID and Secret for a user; those credentials are used to obtain a Bearer token. Tokens expire after 24 hours and are required for all API requests.

### Step 1: Create API credentials

1. Sign in to Elementum in your web browser
2. Open the **User Settings** menu and go to the **OAuth** section
3. Select **Create New Token**, choose **API Access**, and click **Generate Token**
4. Save the generated **Client ID** and **Client Secret** immediately — they are shown only once and cannot be retrieved later

<Warning>
  Store your Client ID and Client Secret securely. They provide access to your Elementum data. Do not expose them in frontend applications or public repositories.
</Warning>

### Step 2: Obtain a Bearer token

Request an access token from the OAuth 2.0 endpoint. Use this step each time you need a new Bearer token (for example, after expiry).

* **Endpoint:** `POST https://api.elementum.io/oauth/token` (EU: `https://api.eu.elementum.io/oauth/token`)
* **Content-Type:** `application/x-www-form-urlencoded`
* **Authorization:** Basic Auth with your Client ID as the username and Client Secret as the password (base64-encoded `client_id:client_secret`)
* **Body:** `grant_type=client_credentials`

Example with cURL:

```bash theme={null}
curl -X POST 'https://api.elementum.io/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --user 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' \
  --data 'grant_type=client_credentials'
```

A successful response returns an `access_token`. Use it in the `Authorization` header as `Bearer {access_token}` for all API requests. Records created or updated via the API are attributed to the API user.

### Step 3: Make authenticated API calls

Include the access token in the `Authorization` header:

```bash theme={null}
curl -X GET 'https://api.elementum.io/v1/apps/your-app-namespace' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json'
```

Replace `YOUR_ACCESS_TOKEN`, the record type, and namespace with your values. See [Record Types and Namespaces](#record-types-and-namespaces) and the endpoint reference below.

## Base URL

All API requests are made to the following base URL. All endpoints in this documentation are listed relative to this base URL.

`https://api.elementum.io/v1`

<Note>
  For users in the EU region, use the EU endpoint: `https://api.eu.elementum.io/v1`
</Note>

## Core Concepts

### Record Types and Namespaces

The API supports record types such as **Apps**, **Tasks**, and **Elements**. You must specify the record type and its **alias** (namespace) in the path. Aliases are unique identifiers for the app, element, or task.

**Where to find the alias:**

* In the **Create Record** modal for that record type
* In **Admin** — aliases can be set in the Create Definition (or equivalent) modals for the app, element, or task

Example endpoint structure: `/{recordType}/{alias}` (e.g. `/{recordType}/{alias}/{id}` for a specific record).

### File Attachments

The Elementum API supports adding attachments to records via the attachment endpoints. When working with file uploads:

* **Maximum File Size**: **250MB** per file
* **Supported Operations**: Upload attachments, add URL links, delete attachments
* **File Storage**: Files are stored as attachments on records and can be accessed via the attachment URL
* **Common Use Cases**: Document uploads, image attachments, report files, contracts

**Example Endpoint**:

```
POST https://api.elementum.io/v1/elements/testelement/TTE-11/attachments
```

See the [Attachments API endpoints](/api-reference/endpoints/attachments/add-an-attachment) for specific implementation details.

## Filtering Results

Search endpoints accept **RSQL** filter strings in the `filter` query parameter. Use the operators below in your filter expressions.

### Operators

| Operator          | Description         | Example                                                            |
| ----------------- | ------------------- | ------------------------------------------------------------------ |
| `==`              | Equal To            | `Status==Open`                                                     |
| `!=`              | Not Equal To        | `Status!=Closed`                                                   |
| `=gt=`            | Greater Than        | `Created on=gt=2022-01-01T00:00:00.000Z`                           |
| `=ge=`            | Greater Or Equal To | `Created on=ge=2022-01-01T00:00:00.000Z`                           |
| `=lt=`            | Less Than           | `Created on=lt=2022-04-01T00:00:00.000Z`                           |
| `=le=`            | Less Or Equal To    | `Created on=le=2022-04-01T00:00:00.000Z`                           |
| `=bt=`            | Between             | `Created on=bt=2022-01-01T00:00:00.000Z:2022-04-01T00:00:00.000Z`  |
| `!bt=` or `=nbt=` | Not Between         | `Created on=!bt=2022-01-01T00:00:00.000Z:2022-04-01T00:00:00.000Z` |
| `=in=`            | In                  | `Status=in=Open:Closed`                                            |
| `=out=`           | Not In              | `Priority=out=Low:Medium:High`                                     |
| `=lk=`            | Like                | `Title=lk=Order 1234`                                              |

### Combining Filters

* **AND**: Use semicolon (`;`) — e.g. `Status==Open;Priority==High`. In URLs, encode as `%3b`.
* **OR**: Use comma (`,`) — e.g. `Status==Open,Status==Closed`. In URLs, encode as `%2c`.

<Note>
  AND operators take precedence over OR operators in filter expressions. URL-encode special characters when passing filters in query parameters.
</Note>

## Error Handling

The Elementum API uses standard HTTP status codes to indicate the success or failure of an API request.

| Status Code                 | Meaning                                                                  |
| --------------------------- | ------------------------------------------------------------------------ |
| `200 OK`                    | The request was successful.                                              |
| `201 Created`               | The resource was successfully created.                                   |
| `202 Accepted`              | The request was accepted for processing, but has not yet been completed. |
| `400 Bad Request`           | The request was improperly formatted or contained invalid parameters.    |
| `401 Unauthorized`          | Your access token is wrong, expired, or you did not provide one.         |
| `403 Forbidden`             | You don't have permission to access the requested resource.              |
| `404 Not Found`             | The requested resource could not be found.                               |
| `429 Too Many Requests`     | You're sending too many requests.                                        |
| `500 Internal Server Error` | We had a problem with our server. Try again later.                       |

## Rate Limiting

To ensure the stability of our services for all users, the Elementum API enforces rate limiting. If you exceed the rate limit, you will receive an HTTP `429 Too Many Requests` response.

## Endpoint reference

The base URL is `https://api.elementum.io/v1` (EU: `https://api.eu.elementum.io/v1`). Supported endpoints by area:

| Function                  | Method | Path                                                    |
| ------------------------- | ------ | ------------------------------------------------------- |
| Search for record(s)      | GET    | `/{recordType}/{alias}`                                 |
| Find record by ID         | GET    | `/{recordType}/{alias}/{id}`                            |
| Create a record           | POST   | `/{recordType}/{alias}`                                 |
| Update a record           | PUT    | `/{recordType}/{alias}/{id}`                            |
| Get related items         | GET    | `/{recordType}/{alias}/{id}/related-items`              |
| Add related item          | POST   | `/{recordType}/{alias}/{id}/related-items`              |
| Remove related item       | DELETE | `/{recordType}/{alias}/{id}/related-items/{relationId}` |
| Find attachment by ID     | GET    | `/{recordType}/{alias}/{id}/attachments/{attachmentId}` |
| Get list of attachments   | GET    | `/{recordType}/{alias}/{id}/attachments`                |
| Add attachment            | POST   | `/{recordType}/{alias}/{id}/attachments`                |
| Add link                  | POST   | `/{recordType}/{alias}/{id}/attachments/url-links`      |
| Remove attachment         | DELETE | `/{recordType}/{alias}/{id}/attachments/{attachmentId}` |
| Get watchers              | GET    | `/{recordType}/{alias}/{id}/watchers`                   |
| Add watcher(s)            | POST   | `/{recordType}/{alias}/{id}/watchers`                   |
| Remove watcher(s)         | DELETE | `/{recordType}/{alias}/{id}/watchers`                   |
| Get comments              | GET    | `/{recordType}/{alias}/{id}/comment`                    |
| Add comment               | POST   | `/{recordType}/{alias}/{id}/comment`                    |
| List users                | GET    | `/users`                                                |
| Create a user             | POST   | `/users`                                                |
| Get a user by ID          | GET    | `/users/{userId}`                                       |
| Deactivate a user         | POST   | `/users/{userId}/deactivate`                            |
| List groups               | GET    | `/groups`                                               |
| Get a group by ID         | GET    | `/groups/{groupId}`                                     |
| List users in a group     | GET    | `/groups/{groupId}/users`                               |
| Add users to a group      | POST   | `/groups/{groupId}/users`                               |
| Remove users from a group | DELETE | `/groups/{groupId}/users`                               |

See the [API Reference](/api-reference/endpoints/records/get-the-list-of-records) sections for parameters, request bodies, and response schemas.

## Best Practices and important notes

* **Field names and picklist values** match what is configured in the record type definition in Admin. Use the exact names and values from your app.
* **Date and date-time fields** must be in ISO 8601 format with UTC (`Z`) offset: `YYYY-MM-DDTHH:MM:SS.SSSZ` — for example, `2026-06-05T14:30:00.000Z`. Mixing local-timezone offsets can cause display inconsistencies; always send UTC.
* **Record creation** must include all required fields defined for that record type.
* **Relating items** (e.g. adding Elements to an App record) is done one item at a time.
* URL-encode special characters in filter strings when using query parameters.
* Access tokens expire after 24 hours; obtain a new token when needed.

## Versioning

Our API is versioned to ensure that changes are predictable and non-breaking. The current version is `v1`, which is specified in the URL of your API requests.

`https://api.elementum.io/v1/{endpoint}`