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.

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

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

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}
Add watcher(s)	POST	/{recordType}/{alias}/{id}/watchers
Remove watcher(s)	DELETE	/{recordType}/{alias}/{id}/watchers
Add comment	POST	/{recordType}/{alias}/{id}/comment

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: YYYY-MM-DDTHH:MM:SS.SSSZ.
• 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}