Elementum API

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.

Elementum API Specification

View the full OpenAPI specification file for a complete list of endpoints and schemas.

API Status

Check the current status of our API services and get notified of any issues.

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

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

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.

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:

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:

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

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

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

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

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 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}

Introduction

Access Token

Records

Related-items

Attachments

Watchers

Comments

Users

Groups

Overview

Elementum API Specification

API Status

Authentication

Step 1: Create API credentials

Step 2: Obtain a Bearer token

Step 3: Make authenticated API calls

Base URL

Core Concepts

Record Types and Namespaces

File Attachments

Filtering Results

Operators

Combining Filters

Error Handling

Rate Limiting

Endpoint reference

Best Practices and important notes

Versioning

​Overview

Elementum API Specification

API Status

​Authentication

​Step 1: Create API credentials

​Step 2: Obtain a Bearer token

​Step 3: Make authenticated API calls

​Base URL

​Core Concepts

​Record Types and Namespaces

​File Attachments

​Filtering Results

​Operators

​Combining Filters

​Error Handling

​Rate Limiting

​Endpoint reference

​Best Practices and important notes

​Versioning

Overview

Authentication

Step 1: Create API credentials

Step 2: Obtain a Bearer token

Step 3: Make authenticated API calls

Base URL

Core Concepts

Record Types and Namespaces

File Attachments

Filtering Results

Operators

Combining Filters

Error Handling

Rate Limiting

Endpoint reference

Best Practices and important notes

Versioning