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

​
Getting Started: Your First API Call

Follow these steps to authenticate and make your first request to the Elementum API.
1

1. Get Your API Credentials

To authenticate with the Elementum API, you first need a client_id and client_secret. You can generate these from your Elementum workspace:
  1. Sign in to Elementum
  2. Navigate to User Settings > OAuth section
  3. Click “Create New Token”
  4. Select “API Access”
  5. Click “Generate Token”
  6. Save your Client ID and Client Secret securely
Securely store your client_secret as it provides access to your Elementum data and should not be exposed in frontend applications or public repositories.
2

2. Request an Access Token

Once you have your credentials, you can request an access token from our OAuth 2.0 endpoint. This token is used to authenticate your subsequent API requests. The token is a short-lived Bearer token that expires after 24 hours.Here’s an example of how to request an access token using cURL:
curl -X POST 'https://api.elementum.io/oauth/token' \
--header 'Content-Type: application/json' \
--data-raw '{
    "grant_type": "client_credentials",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
}'
A successful request will return an access_token.
3

3. Make Your First API Call

Now you can use your access token to make authenticated requests to the API. Include the token in the Authorization header as a Bearer token.Let’s try retrieving a list of records. Replace YOUR_ACCESS_TOKEN, {recordType}, and {alias} with your actual data.
curl -X GET 'https://api.elementum.io/v1/apps/your-app-alias' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

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

Each API endpoint requires a record type and alias to identify the specific data you want to work with:
  • Record Types: apps, elements, tasks, etc.
  • Aliases: Unique identifiers you can find in the App/Element/Task Settings
  • Admins can configure aliases during the App/Element/Task creation process
Example endpoint structure: /{recordType}/{alias}

​
Filtering Results

Use RSQL filters to refine your search results when retrieving records:

​
Operators

OperatorDescriptionExample
==EqualStatus==Open
!=Not EqualStatus!=Closed
=gt=Greater ThanPriority=gt=3
=ge=Greater/EqualPriority=ge=3
=lt=Less ThanPriority=lt=5
=le=Less/EqualPriority=le=5
=in=In ListStatus=in=(Open,Review)
=lk=LikeTitle=lk=*urgent*

​
Combining Filters

  • AND: Use semicolon (;) - Status==Open;Priority==High
  • OR: Use comma (,) - Status==Open,Status==Closed
AND operators take precedence over OR operators in filter expressions.

​
Error Handling

The Elementum API uses standard HTTP status codes to indicate the success or failure of an API request.
Status CodeMeaning
200 OKThe request was successful.
201 CreatedThe resource was successfully created.
202 AcceptedThe request was accepted for processing, but has not yet been completed.
400 Bad RequestThe request was improperly formatted or contained invalid parameters.
401 UnauthorizedYour access token is wrong, expired, or you did not provide one.
403 ForbiddenYou don’t have permission to access the requested resource.
404 Not FoundThe requested resource could not be found.
429 Too Many RequestsYou’re sending too many requests.
500 Internal Server ErrorWe 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.

​
Best Practices

  • Match field names exactly as configured in your record definitions
  • Use ISO8601 format for dates: YYYY-MM-DDTHH:MM:SS.SSSZ
  • Include all required fields when creating records
  • URL encode special characters in filter strings
  • Remember that access tokens expire after 24 hours

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