REST API¶
Overview¶
The Mythradon platform offers comprehensive functionality through its JSON REST-style APIs. These APIs provide the ability to perform all CRUD operations and are automatically generated for any entities or fields created using the Entity Manager within the Mythradon Tools. These APIs are accessible to a wide range of programming languages, making integration with external systems seamless.
Mythradon APIs have been meticulously crafted with a focus on best practices, encompassing adherence to JSON REST standards and ensuring secure, authenticated access. They boast support for specialised user accounts and roles to enable precise endpoint restriction. Authentication methods, such as HMAC or key-based authentication, are employed to guarantee the integrity of incoming requests. Moreover, every interaction with the APIs is systematically documented in audit logs, facilitating analysis and troubleshooting as needed.
REST API Access¶
Mythradon is a single-page application (SPA) that communicates with its backend via a RESTful API. This architecture enables all operations available through the user interface to also be performed programmatically using any language capable of making HTTP requests.
To explore how the API functions, developers can inspect network activity through the browser’s developer tools (typically accessible via the F12 key, then selecting the Network tab).
Request Format¶
Most API responses are returned in JSON format. Similarly, POST and PUT requests typically require a JSON payload in the request body.
All API requests must include the following HTTP headers:
Content-Type: application/jsonX-API-Key: <Your API Key>
The X-API-Key is issued to an API User. For details on creating and managing API users, refer to API User Accounts.
API Endpoint Structure¶
The base path for all API requests is:
For example, a request to retrieve a specific contact might look like this:
In this documentation, we omit the domain and base path (/api/v1/) in API examples for brevity. If you're using one of our client libraries or SDKs, these components are automatically included.
Best Practice: Use a Dedicated API User¶
It is strongly recommended to create a dedicated API User account with only the necessary permissions (via assigned roles) to perform required actions. This ensures both better security and traceability of API activity.
API Functions¶
- CRUD operations - create, read, update, delete
- Related records
- Stream
- Currency Rate
- Attachments
- I18n
- Account
- Search Parameters
Authentication¶
Mythradon provides three secure authentication methods for accessing the API. Choose the option that best aligns with your integration needs and security standards:
- API Key Authentication – Simple and secure token-based authentication using a unique API key assigned to an API User.
- HMAC Authentication – A highly secure method that signs requests using a combination of API Key and Secret. Ideal for integrations that require tamper-proof request validation.
- Standard User Authentication – Uses a username and password combination. Optionally supports Two-Factor Authentication (2FA) for enhanced security.
Note
🔐 The authentication method (API Key or HMAC) is configured when creating an API User. For setup instructions, see API Users.
Authentication Method Comparison¶
| Method | Use Case | Security Level | Best For | Supports 2FA | Session-Based |
|---|---|---|---|---|---|
| API Key Authentication | Programmatic access with minimal setup | Medium | Low-risk automations or internal tools | ❌ No | ❌ No |
| HMAC Authentication | High-security integrations with strict verification needs | High | External systems or partners requiring secure and verifiable requests | ❌ No | ❌ No |
| Standard User Authentication | Manual access, mobile/desktop apps, or non-server apps logging in as named users | Medium–High | Trusted internal users or low-frequency access | ✅ Optional | ✅ Yes |
Key Considerations¶
-
API Key Authentication Simple token-based method best suited for server-side scripts or internal services. Keys should be stored securely and rotated periodically.
-
HMAC Authentication Uses a shared secret to verify the integrity and authenticity of each request. Best for high-trust, high-security scenarios such as third-party integrations.
-
Standard User Authentication Ideal for desktop or mobile applications where a specific user logs in and maintains a session. Supports Two-Factor Authentication (2FA) for added protection.
API Key Authentication¶
API Key Authentication allows secure, token-based access to the API using a unique key assigned to an API User. This method is straightforward to implement and is ideal for internal or server-to-server integrations where the key can be stored securely.
How It Works¶
- Include your API key in every request using the
X-Api-Keyheader.
Example:
- The API key is tied to a specific API User and can be revoked or regenerated at any time.
- This method is recommended for trusted environments with minimal exposure to public access.
API Key
API Keys should be treated as sensitive credentials. Do not expose them in frontend code or client-side applications.
HMAC Authentication¶
HMAC (Hash-Based Message Authentication Code) is a more secure authentication method that ensures the integrity and authenticity of each request by signing it with a secret key.
How It Works¶
- Construct the string to sign using the HTTP method and URI path:
- Generate an HMAC SHA256 hash using the secret key:
- Concatenate your API key with the hashed value:
- Base64-encode the result and include it in the request header:
Header Example:
Full Signature Example:
Note
Recommended: Use HMAC authentication when security and data integrity are critical—especially in public APIs or third-party integrations.
Both methods are configured via the API Users section, where you can generate and manage your credentials.
Standard User Authentication¶
Standard User Authentication allows you to authenticate with the API using a username and password combination. This method supports session-based access and optionally Two-Factor Authentication (2FA).
Initial Authentication Request¶
To begin a session, send a request with a base64-encoded string of your username:password using the Espo-Authorization header.
cURL Example:
curl -X GET https://<your-Mythradon-domain>/api/v1/App/user \
-H 'Content-Type: application/json' \
-H 'Espo-Authorization: <Authorization Key>'
Replace <Authorization Key> with the Base64-encoded string:
Base64(username:password)
Tip: Encoding Credentials¶
You can generate the Base64-encoded string as follows:
- Linux/macOS Terminal:
- Online Tool (for testing only):
Security Note
Never use public tools for generating credentials for production systems.
Two-Factor Authentication (2FA)¶
If the user account has Two-Factor Authentication enabled, the initial response will not include a token. Instead, you'll receive:
- A response header:
X-Status-Reason: second-step-required
- A JSON response body:
{
"status": "secondStepRequired",
"message": "enterTotpCode",
"view": null,
"token": null,
"data": {}
}
To complete the login, send a second request that includes the user's 2FA code.
cURL Example (Second Step with 2FA):
curl -X GET https://<your-Mythradon-domain>/api/v1/App/user \
-H 'Content-Type: application/json' \
-H 'Espo-Authorization: <Authorization Key>' \
-H 'Espo-Authorization-Code: <2FA Code>' \
-H 'Espo-Authorization-Create-Token-Secret: true'
<2FA Code>is the time-based one-time code (TOTP) from the user's authenticator app or SMS, depending on their configured 2FA method.
Note
2FA is required only once per session. After successful verification, a token will be returned and can be used for subsequent requests.
Authenticated User Response¶
After successful authentication (and 2FA, if applicable), the response will include a token within the user object:
Using the Token for Subsequent Requests¶
For all future API calls within the session, replace the password with the token in the Espo-Authorization header:
Use this new encoded value in the same header format:
HTTP Headers¶
The following headers are used for authenticating API requests. Authentication methods include standard user login (with optional Two-Factor Authentication), API Key, and HMAC-based authentication.
| Header | Description |
|---|---|
| Espo-Authorization | Required for standard user login. Use the format Base64Encode('Username:Password') for the initial request. If successful, a JSON response will return an authentication token. For all subsequent requests, use the format Base64Encode('Username:Token'). |
| Espo-Authorization-Code | Required for users with Two-Factor Authentication (2FA) enabled. This is the 2FA code in plain text—typically from an authenticator app (e.g., Google Authenticator, Authy) or received via SMS, depending on the user’s configured 2FA method. |
| Espo-Authorization-Create-Token-Secret | Used during the second step of 2FA authentication. Set this header to 'true' to indicate that the 2FA code is being submitted in conjunction with the Espo-Authorization-Code. |
| X-Status-Reason | A response header returned by the server when additional authentication is required. If 2FA is enabled, this header will be present with the value 'second-step-required'. |
| X-Api-Key | Required for API User authentication using API Key authentication. This value is obtained from the API User account. Format: X-Api-Key: <YourApiKey>. |
| X-Hmac-Authorization | Required for API User authentication using HMAC-based authentication. Constructed using the API Key and API Secret from the API User account. Format: X-Hmac-Authorization: base64Encode(apiKey + ':' + hashHmacSha256(method + ' /' + uri, secretKey)). |
| X-Skip-Duplicate-Check | Skips checking for duplicates and will not return a HTTP 409 error if a duplicate record is found. Format: X-Skip-Duplicate-Check: true. |
| X-No-Total | Optional header that improves performance by skipping the total record count in list responses. Format: X-No-Total: true. Note: Do not use this if you rely on the total value for paging. |
HTTP Error Codes¶
The Mythradon API may return the following HTTP status codes:
| Code | Description |
|---|---|
| 200 | Success. The request was completed successfully. |
| 401 | Unauthorised. The API key is missing, invalid, or does not have permission to access the requested resource. |
| 404 | Not Found. The requested resource (e.g., entity or record) does not exist. |
| 409 | Conflict. A duplicate record was detected. The request was not completed. This can be bypassed by sending the X-Skip-Duplicate-Check: true header with the request. |
CRUD APIs¶
The Mythradon CRUD APIs are designed to be entity-agnostic, meaning they follow a consistent and predictable structure for all entity types—standard or custom. This makes it easy to interact with any record in the system using the same set of API patterns.
Uniform API Structure¶
You can perform standard operations (such as retrieve, create, update, and delete) on any entity using the same syntax. Simply substitute the entity name in the URL path.
Example – Retrieve a list of records:
Replace <EntityName> with the name of the entity, such as Contact, Account, Lead, or a custom entity like ModelCust.
Benefits¶
- Consistency – One unified API structure across all entities
- Simplicity – Easier to build and scale integrations
- Flexibility – Works with both standard and custom entities
Retrieve List of Records¶
To retrieve a list of records use:
Note
If no JSON response is returned, verify that the Role assigned to the authenticated user has the required access permissions.
Select Fields¶
The Mythradon REST API lets you choose which attributes (fields) to include in the response. By returning only the attributes you need, you can reduce payload size and improve performance.
You can pass attributes as a comma-separated string in the select query parameter (URL encoded with no whitespace.)
Example
GET https://<your-Mythradon-domain>/api/v1/Account?select=id%2Cname%2CassignedUserId
Note
The comma-separated string provided to the select parameter is URL encoded.
Note
System attributes such id, createdAt, createdById, assignedUserId are always included in the query result set and can be omitted from the select parameter.
The following example show how to fetch a list of Contact records that only include the firstName and lastName attributes.
curl -X GET https://<your-Mythradon-domain>/api/v1/Contact?select=firstName%2ClastName \
-H 'Content-Type: application/json' \
-H 'X-Api-Key: <Your API Key>'
Ordering Results¶
You can control the order of results using the orderBy and order query parameters:
orderBy– the field name to sort by.order– the sort direction. Accepted values are:asc– ascending (A → Z, 0 → 9, oldest → newest)desc– descending (Z → A, 9 → 0, newest → oldest)
Example: Return contacts ordered by creation date (newest first):
curl -X GET "https://<your-Mythradon-domain>/api/v1/Contact?orderBy=createdAt&order=desc" \
-H "Content-Type: application/json" \
-H "X-Api-Key: <Your API Key>"
Tip
You can combine select, orderBy, and order in the same request to fetch only the fields you need, in the order you prefer.
Search Parameters¶
The Mythradon searchParams is used to execute a filter or query when retrieving one or more records.
Note
If you know the Mythradon unique id for a record. It is best to reference the record directly using the id. Refer to Retrieve Specific Record section below.
The searchParams is used in API requests to filter, sort, and select specific data when retrieving records. The params are passed as a JSON object in the searchParams GET parameter.
Example 1: Basic Filtering, Selection, and Ordering
Retrieve a list of accounts:
- Select only
idandnameattributes - Filter by
namecontaining "Acme" - Limit result to 30 records
- Order by
createdAtin descending order
=== GET
``` bash
GET https://<your-Mythradon-domain>/api/v1/Account?searchParams={
"select": ["id", "name"],
"where": [
{ "type": "contains", "attribute": "name", "value": "Acme" }
],
"maxSize": 30,
"orderBy": "createdAt",
"order": "desc"
}
```
!!! note
The searchParams need to be url encoded. Tools such as Postman will automatically perform certain levels of encoding.
=== CURL
``` bash
curl -X GET -d "searchParams={'select':['id','name']}" https://<your-Mythradon-domain>/api/v1/Account \
-H 'X-Api-Key: <Your API Key>' \
-H 'Content-Type: application/json' > /tmp/accounts.json
```
Parameters explained:
-
select– Array of attributes to return. Example: ["id", "name", "status"] -
where- Array of filter condition objects:type→ comparison operator (equals,contains,in,greaterThan,lessThan, etc.)attribute→ the field to filter onvalue→ value(s) to compare against
maxSize– Maximum number of records to return.orderBy– Attribute used to sort results.order– Sort direction:asc= ascending (oldest → newest)desc= descending (newest → oldest)
Example 2: Filtering with Multiple Conditions
Retrieve opportunities linked to a specific account, filtered by both status and stage:
GET https://<your-Mythradon-domain>/api/v1/Account/5564764442a6d024c/opportunities?searchParams={
"where": [
{ "type": "equals", "attribute": "status", "value": "Open" },
{ "type": "equals", "attribute": "stage", "value": "Qualification" }
]
}
Example 3: Filtering with in Operator
Retrieve leads where the status is either "New" or "Assigned":
GET https://<your-Mythradon-domain>/api/v1/Lead?searchParams={
"where": [
{ "type": "in", "attribute": "status", "value": ["New", "Assigned"] }
]
}
Retrieving Paged Lists of Records¶
When accessing large datasets through the Mythradon REST API, it's essential to implement pagination to efficiently manage and retrieve records in smaller, more manageable chunks. This helps prevent performance issues and ensures that your application remains responsive, even when working with thousands of records.
For details on how to structure paged requests and handle paginated responses, see Querying Records with Paging.
Retrieve Specific Record¶
You can retrieve an individual record in Mythradon by using its unique id.
Examples – Retrieve Contact
To retrieve a specific Contact, send a GET request to the following endpoint, replacing <RecordId> with the actual ID of the Contact:
How to Find the Record ID
The id of a record is shown in the URL when viewing that record in the detail view within Mythradon.
For example:
In this case, the record ID is:
Use this ID in your API call to fetch the specific record.
Create a New Record¶
To create a new record
Example – Create Contact:
curl -X POST https://<your-Mythradon-domain>/api/v1/Contact \
-H 'Content-Type: application/json' \
-H 'X-Hmac-Authorization: <Your Base64 Encoded Signature>'
-d '{
"salutationName": "Mr.",
"firstName": "Max",
"lastName": "Johnson",
"title": "Co-Founder",
"emailAddress": "max.johnson@example.com"
}'
curl -X POST https://<your-Mythradon-domain>/api/v1/Contact \
-H 'Content-Type: application/json' \
-H 'Espo-Authorization: <Your Base64 Encoded Username:Password/Token>'
-d '{
"salutationName": "Mr.",
"firstName": "Max",
"lastName": "Johnson",
"title": "Co-Founder",
"emailAddress": "max.johnson@example.com"
}'
See also¶
- API User Accounts
- Metadata API
- Mythradon Marketing
- Mythradon Sales
- Mythradon Service
- Mythradon System Administration
- Mythradon Tools