What is it?
The ITONICS Innovation OS features a standardized REST API designed to facilitate data exchange between ITONICS and your external applications.
Use the API for Read (GET), Create (POST), and Update (PUT) operations to automatically synchronize content, eliminating the need for manual data handling. Since all your configured ITONICS fields are dynamically exposed as REST API endpoints, integrating and keeping other systems up-to-date is straightforward.
Please note: This feature needs to be activated by ITONICS. Please contact your Customer Success Manager or Account Manager for further assistance.
Table of contents
Building on this, the following sections provide a technical deep dive into the ITONICS REST API, explaining the basics in detail and covering authentication, data structures, request formats, and best practices to equip you with the necessary knowledge to utilize the API effectively.
Check out our public Postman API collection:
This dedicated resource provides detailed sample request bodies and complete output formats for all GET, POST, and PUT endpoints, ensuring you quickly understand the necessary technical specifications and expected JSON formats.
Introduction
The REST API returns requested data in a standard JSON format (UTF-8 encoding) and supports comprehensive data retrieval and manipulation, summarized as CRUD operations:
Create (HTTP POST request)
Read (HTTP GET request)
Update (HTTP PUT request)
(Delete (HTTP DELETE request) — Note: This operation is currently excluded.)
The API allows access to all configured entity types in your application using these operations, with one exception: the Campaign entity type (itonics_campaign_tr3), which supports Read (GET) only.
To perform any operation, the API user must be properly authenticated and possess the necessary permissions. These exact required permissions are outlined in more detail in the respective subsections of the API methods.
Besides, ITONICS recommends creating a dedicated user role to set up and utilize the API.
Create a new role and define its access rights
Go to Settings Wheel > Entity Configuration > Entity Configuration.
In the entity-specific permissions tab, locate the required permissions and enable it for the newly created role
Authentication & authorization
The ITONICS Innovation OS application offers two authentication types for the REST API: Basic Authentication and OAuth 2.
By default, Basic Authentication is enabled when the API is set up. Only one method can be active at a time. If you require OAuth 2, ITONICS can switch the authentication type upon request.
Basic Authentication
All API endpoints require the use of SSL with TLS 1.2 or above to ensure a secure connection between the ITONICS API and a client application/automation. Authentication is performed using HTTP basic authentication headers.
Authentication setup
Create a dedicated API User: You must create a new user specifically for API authentication. This username must start with 'restws'.
Assign permissions: Ensure this user is assigned to a role that has the necessary permissions within the system to execute the required requests (e.g., "Access the resource <entity type>").
Authentication format: Use the following header format for authentication: Authorization: Basic <base-64-encoded string of "username:password">
Handling writing requests (POST and PUT)
ITONICS uses cookie-based authentication for all writing requests (POST and PUT).
GET requests do not require a token.
Writing requests require an HTTP X-CSRF token in the header.
You can retrieve the token from the dedicated GET endpoint /restws/session/token.
| Method | Endpoint | Details | Sample request |
| GET | /restws/session/token (Basic authentication) | Returns an authorization token (the X-CSRF token) required for all subsequent POST and PUT requests. | /restws/session/token |
The token must then be included in the header of your writing requests using this format: X-CSRF-Token: received_token.
The X-CSRF token is valid for 2,000,000 seconds (approximately 23 days), while the token's validity is tied to the user's session and will expire if the session times out (typically after about 55 hours of inactivity) or if the user logs out, requiring you to fetch a new token.
OAuth 2.0 authentication
OAuth 2.0 (Open Authorization) is a standard protocol that allows one application (or website) to securely access resources hosted by another application on behalf of a user. This standard provides consented access, meaning it restricts and defines exactly what actions the client application is authorized to perform on those resources.
OAuth 2.0 authorization flow
To begin the OAuth 2.0 process, the user must first possess the necessary login credentials, a valid Client ID, and a Client Secret, all of which are provided by ITONICS upfront.
The authorization flow is initiated by the user, and the request, exchange, and response follow these general steps:
The user requests authorization from the authorization server, using the Client ID and Client Secret for identification, and also providing the required scopes and an endpoint URI for access token delivery.
The authorization server authenticates the user and verifies the requested scopes (Client ID and Client Secret) are permitted.
The user interacts with the authorization server to explicitly grant access.
The authorization server issues an access token to the user.
Using the access token, the user requests access to the resource from the resource server.
Grant types
In the OAuth 2.0 authorization framework, grants refer to the specific set of steps a user performs to receive authorization for resource access. The ITONICS REST API utilizes the following grant types:
1. Password grant type
The password grant type exchanges a user's direct credentials for an access token. This flow is necessary to acquire the initial access token and the refresh token.
The token is retrieved from the POST endpoint /oauth2/token using the following required parameters:
| Key | Value | Explanation |
| grant_type | password | Specifies the grant type for token retrieval |
| client_id | client_id | The Client ID obtained from the OAuth 2 server configuration |
| client_secret | client_secret | The Client Secret obtained from the OAuth 2 server configuration |
| username | username | The ITONICS Innovation OS (Enterprise) application username |
| password | password | The password for the ITONICS Innovation OS (Enterprise) application |
2. Refresh token grant type
The refresh token grant type allows a user to exchange an expired access token for a new, valid access token without requiring the user to re-authenticate with their username and password. You must execute the password grant type flow once to acquire the initial refresh token.
| Method | Endpoint | Details | Sample request |
| POST | /oauth2/token (OAuth2) | Returns an access token required for all subsequent POST and PUT requests, and a refresh token to request a new access token if invalid. | /oauth2/token |
The new token is retrieved from this POST endpoint using the following required parameters:
| Key | Value | Explanation |
| grant_type | refresh_token | Specifies the grant type for token renewal |
| client_id | client_id | The Client ID obtained from the OAuth 2 server configuration |
| client_secret | client_secret | The Client Secret obtained from the OAuth 2 server configuration |
| refresh_token | refresh_token | The refresh token used to request a new access token |
The access token must then be used in the header of all requests for authorization: Authorization: Bearer access_token
Note: the tokens' lifetime, respectively the validity period, can be configured by ITONICS. Per default 3600 seconds (1h) for the access token, and 1,209,600 seconds (336h) for the refresh token.
3. (Potential) Token retrieval error responses
When attempting to retrieve a token via the POST /oauth2/token endpoint, you may receive the following error responses.
Invalid client credentials
This error indicates an issue with the application's identification (Client ID or Client Secret).
| Key | Value | Description |
| error | "invalid_client" | The credentials provided for the client application are incorrect. |
| error_description | "The client credentials are invalid" | The Client ID or Client Secret supplied in the request is invalid or incorrect. |
Invalid user credentials
This error indicates a problem with the user's login details.
| Key | Value | Description |
| error | "invalid_grant" | The credentials provided for the user authentication failed. |
| error_description | "Invalid username and password combination" | The username or password supplied in the request is invalid. |
API methods
The ITONICS API supports all common methods (GET, POST, and PUT; DELETE operation currently excluded) and includes common meta controls for slicing and filtering your requested data sets.
All API requests follow this standardized URL pattern: {API method} https://{system URL}/api/{actual endpoint}.json?{meta control 1}&{meta control 2}
This structure is used across all available endpoints, which are detailed in the following sections for each request type.
Check out our public Postman API collection:
This dedicated resource provides detailed sample request bodies and complete output formats for all GET, POST, and PUT endpoints, ensuring you quickly understand the necessary technical specifications and expected JSON formats.
Refer to this change log article to trace changes in endpoints, expected input- or output formats, or behavior applied to the ITONICS REST API over time.
GET endpoints (Read)
The following table lists the endpoints available for reading (retrieving) data from your ITONICS application via GET requests.
| Endpoint group | Endpoint Format | Details | Sample request |
| Element retrieval | /api/{entity_type}.json | Returns a list of all elements for the specified type {entity_type} (e.g., itonics_trend). Includes all defined attributes for this {entity_type}, files (base64 encoded if configured), and relations (and if enabled, available visibility and external submitter information). | /api/itonics_trend.json |
| /api/{entity_type}/{id}.json | Returns a single element of type {entity_type} matching the URI {id}. Includes all defined attributes for this {entity_type}, files (base64 encoded if configured), and relations (incl. parent child relations if available), and if enabled/available visibility and external submitter information. | /api/itonics_trend/42.json | |
|
Required permissions:
+ “View all (unpublished) {entity_type}” permission (entity-level) → returns all (draft/review) elements of the respective entity type (or one element matching the {id}) + “View own (unpublished) {entity_type}” permission (entity-level) → returns own (draft/review) elements created by the particular user of the respective entity type (or one element matching the {id}) | |||
| Campaign & submission data retrieval | /api/itonics_campaign_tr3.json | Returns a list of all campaign elements (type itonics_campaign_tr3). Includes all defined attributes for this type, files (base64 encoded if configured), and relations. | /api/itonics_campaign_tr3.json |
| /api/itonics_campaign_tr3/{id}.json | Returns a single campaign element (type itonics_campaign_tr3) matching the URI {id}. Includes all defined attributes for this type, files (base64 encoded if configured), and relations. Further, campaign-specific (matching the URI {id}) phase information, number of submissions per phase, and visibility information. | /api/itonics_campaign_tr3/5.json | |
|
Required permissions:
+ “View all (unpublished) campaigns” permission (entity-level) → returns all (draft/review) campaign elements (or one matching the {id}) + “View own (unpublished) campaigns” permission (entity-level) → returns own (draft/review) campaign elements created by the particular user (or one matching the {id}) | |||
| /api/itonics_idea.json | Returns a list of all Idea elements (type itonics_idea). Includes all default attributes, campaign-specific custom submission field information, (active) phase information, author & evaluator assignments, rating information (past/active phases, 5-star), and external submitter information (if available) for each idea element associated with its campaign. | /api/itonics_idea.json | |
| /api/itonics_idea/{id}.json | Returns a single Idea element (type itonics_idea) matching the URI {id}. Includes all default attributes, campaign-specific custom submission field information, (active) phase information, author & evaluator assignments, rating information (past/active phases, 5-star), and external submitter information (if available) matching the URI {id}. | /api/itonics_idea/10.json | |
|
Required permissions:
+ “View all ideas” permission (campaign-phase-level) → returns submission data for all submissions in the particular campaign phase or of one submission element matching the {id} + “View own ideas” permission (campaign-phase-level) → returns submission data created by the particular user in the specific campaign phase or of one submission element matching the {id} To access submission rating data:
| |||
| Timeline Data | /api/timeline.json?entity_type={entity_type} | Returns all available element timeline information for the specified {entity_type}. Likely requires setting limits, i.e. pagination, for large data sets. | /api/timeline.json?entity_type=itonics_trend&page=2 |
| /api/timeline.json?entity_type={entity_type}&entity_id={entity_id} | Returns all timeline information for a single element of type {entity_type} matching the specified {entity_id}. | /api/timeline.json?entity_type=itonics_trend&entity_id=5 | |
|
Required permissions:
| |||
| Roadmap Data | /api/roadmap.json | Returns a list of all existing roadmaps in the system. | /api/roadmap.json |
|
Required permissions:
+ “View all roadmaps” permission (global permission) → returns full roadmap list + “View own roadmaps” permission (global permission) →returns roadmaps created by the particular user | |||
| /api/roadmap/{id}.json |
Returns all roadmap details (layer information, element information, sync roadmap-/ date information, milestone date/type/custom field information) matching the URI {id}. Use ?type=connection to retrieve roadmap connection types for the URI {id}. Note: you can make use of additional page and limit GET meta controls. |
/api/roadmap/8.json /api/roadmap/8.json?type=connection |
|
|
Required permissions:
+ “View all roadmaps” permission (global permission) → access all roadmaps + “View own roadmaps” permission (global permission) →access own roadmaps created by the particular user | |||
| Metadata & structure | /api/entity_field_properties.json?type={entity_type} | Returns all attributes and their machine names, incl. mandatory options, validations, and selection options for the specified {entity_type}. | /api/entity_field_properties.json?type=itonics_trend |
| /api/entity_field_properties.json?type=itonics_campaign_tr3 | Returns all attributes and their machine names, incl. mandatory options, validations, and selection options for the campaign entity (type itonics_campaign_tr3). | /api/entity_field_properties.json?type=itonics_campaign_tr3 | |
| /api/entity_field_properties.json?type=itonics_campaign_tr3&entity_id={id} | Returns all attributes and their machine names for the campaign entity (type itonics_campaign_tr3), and further the campaign-specific phase configuration, rating criteria per phase, and custom submission field information (incl. mandatory options, validations, and selection options) matching the URI {id}. | /api/entity_field_properties.json?type=itonics_campaign_tr3&entity_id=5 | |
|
/api/entity_field_properties.json?type=itonics_idea&camp_id={id}
/api/entity_field_properties.json?type=itonics_idea&entity_id={id} |
Returns all attributes and their machine names, and custom submission fields for the type itonics_idea of one particular campaign element matching the URI camp_id={id}. This endpoint must be queried before sending a POST request to create a new submission element for a campaign to understand the field structure. Alternatively, this endpoint can also be queried using the entity_id={id} of an existing submission element of type itonics_idea to get the same information on field structure. |
/api/entity_field_properties.json?type=itonics_idea&camp_id=10 /api/entity_field_properties.json?type=itonics_idea&entity_id=44
|
|
|
Required permissions:
| |||
| /api/entity_field_properties.json?type={entity_type}&config=milestone |
Returns all attributes and their machine names, incl. mandatory options, validations, and selection options for the milestone configuration of the specified {entity_type}. Further, this endpoint is restricted to entity types with the Roadmap module enabled. It provides global milestone type information via the utility_data property and lists all entities that currently have the Roadmap module activated. |
/api/entity_field_properties.json?type=itonics_technology_tr3&config=milestone | |
|
Required permissions:
| |||
| /api/user_field_properties.json | Returns all attributes and their machine names, and custom user fields configured from the User Field Configuration. | /api/user_field_properties.json | |
|
Required permissions:
| |||
| User / role data & statistics | /api/user.json |
Returns a list of all users, including meta information, like user ID, username, email, login/access information, role information, basic user attributes, and custom user properties. Use ?limit=x for large datasets to prevent running into timeout errors. |
/api/user.json?limit=25 |
| /api/user/{id}.json | Returns all meta information (refer to prior endpoint) for a specific user matching the URI {id}. | /api/user/212.json | |
|
Required permissions:
| |||
| /api/user_stats/user_roles.json | Returns a list of all configured user roles (and their role_id), total number of assigned users, and the percentage of user distribution across all the roles. | /api/user_stats/user_roles.json | |
| /api/user_stats/login_rate.json | Returns aggregated number of (unique) logins for a given date range (default: last 365 days). | /api/user_stats/login_rate.json | |
| /api/user_stats/active_users.json | Returns various metrics, providing current totals and percentage comparison against the previous 30-day period. | /api/user_stats/active_users.json | |
| /api/user_stats/total_users.json | Returns the overall total user count (total) plus metrics comparing the last 30 days to the preceding period. | /api/user_stats/total_users.json | |
| /api/user_stats/total_number_user.json | Returns the total count of registered users as a numerical value. | /api/user_stats/total_number_user.json | |
| /api/user_stats/contributing_users.json | Returns count of all users having rated, commented, created, or edited an element at least once. | /api/user_stats/contributing_users.json | |
|
Required permissions:
| |||
| System statistics | /api/entity_stats/entity_info.json | Returns a list of all entity types, incl. their machine names, total element count, and element creation tendency (last 60 days). | /api/entity_stats/entity_info.json |
| /api/entity_stats/general_statistics.json | Returns aggregated element creation counts for a given date range (default: last 365 days) for every entity type. | /api/entity_stats/general_statistics.json | |
| /api/entity_stats/entity_status.json | Returns the total number of all elements in the status draft, review, published, and archive. | /api/entity_stats/entity_status.json | |
| /api/entity_stats/activity_rate.json | Returns aggregated activity counts (Rate, Like, Follow, Comment, Relate) for a given date range (default: last 365 days). | /api/entity_stats/activity_rate.json | |
|
Required permissions:
| |||
| API usage statistics | /api/api_stats.json | Returns the aggregated number of API requests for a given date range (default: last 365 days). | /api/api_stats.json |
| /api/api_stats/api_count.json | Returns the total number of API requests and the count for the current month. | /api/api_stats/api_count.json | |
|
Required permissions:
| |||
GET field response formats
This section provides clarity on the expected data structures returned by the GET API for the most frequently used field types, assisting you in correctly parsing the JSON response.
Check out our public Postman API collection:
This dedicated resource provides detailed sample request bodies and complete output formats for all GET, POST, and PUT endpoints, ensuring you quickly understand the necessary technical specifications and expected JSON formats.
Endpoint /api/{entity_type}.json for element retrieval:
| Field type | Example field value | Expected API response | Notes on structure | |
| Single line input field of type text (Title) | Creative AI | “field_machine_name”: “string” |
Simple string value | |
| Simple text field (Abstract) | Creative AI (CAI) is the branch of artificial intelligence. | “field_machine_name”: “string” | Simple string value | |
| Rich text editor (RTE) field (Description) | Creative AI technologies have the potential to fundamentally alter … | “field_machine_name”: “string with <b>HTML</b> tags” | Returns text content, including HTML tags for formatting | |
| Image file (Header image) | (Base64 encoded) Image file | “Field_machine_name”: “encoded_image_data/file/png?X…” | Returns a Base64 encoded string of the image file (if configured to do so). | |
| (Element) Status | Published | “status”: “string” | Returns element status (Published, Draft, Archived, Review) as string value. | |
| Single line input field of type URL, Email, Number | https://www.itonics-innovation.com/ |
“field_machine_name”: “URL string” |
Returns simple string or numerical value represented as a string. Note: Multi-select fields return an array of strings, or numbers / emails represented as a string. |
|
jane.innovation@itonics-innovation.com |
“field_machine_name”: “email string” | |||
100 |
“field_machine_name”: “number string” | |||
| Multi-select case: 100, 200, 300 | “field_machine_name”: [“number/string”, “number/string”, “number/string”] | |||
|
List fields
|
(Searchable) Dropdown (single-select) |
Single-select case: R&D |
"field_machine_name": {"field_option_id": "string"} |
Returns a JSON object mapping the unique field option ID (key) to the displayed label (value). |
| (Searchable) Dropdown (multi-select) | Multi-select case: R&D, Marketing | "field_machine_name": {"field_option_id": "string", “field_option_id”: “string”} | Returns a JSON object mapping unique field option IDs to their labels. | |
|
Single checkbox
|
Checked
|
“field_machine_name”: “checked”
|
Returns the string "checked" when the box is checked, otherwise "unchecked". |
|
Radio button |
Value A |
“field_machine_name: {“field_option_id”: “string”}} | Returns a JSON object mapping the unique option_id to the display label. Empty state returns null. | |
| Pearl chain (with check) | In progress | “field_machine_name”: {“field_option_id”: “string”} | Returns a JSON object mapping the unique option_id to the display label. Empty state returns null. | |
| Segment/ hierarchy field |
Technology Segment > Technology Sub-segment (each level can be multi-select): ICT > AI Engineering > Machines & Robotics > |
“segment_field_machine_name”: {“segment_field_machine_name_entity_segment”: {“segment_field_option_id”: {“label”: “string”, “parent”: “parent_segment_option_id”}}, “sub_segment_field_machine_name_entity_sub_segment”: {“sub_segemnt_field_option_id”: {“label”: “string”, “parent”: “parent_segment_option_id”}}} | Returns a nested JSON object showing the full hierarchy, mapping entity segments to sub-segments via parent/child segment option IDs. | |
| Date picker field | 2025-01-01 | “field_machine_name”: “YYYY-MM-DD” | Returns a date string in the YYYY-MM-DD format. | |
| Term search field (Tags) | artificial intelligence, machine learning | “Tags”: “artificial intelligence;machine learning” | Returns a single string with all tags separated by a semicolon (;). | |
| User search fields (USF) (single-, and multi-select) | Jane Innovation, John Doe | “field_machine_name_username”: “jane.innovation,john.doe” |
Returns two separate fields: one with the technical username(s) (comma-separated for multi-select) and one with the corresponding full name(s) (again, comma-separated for multi-select) | |
| “field_machine_name_fullname”: “Jane Innovation,John Doe” | ||||
| User group search field (UGSF) |
Experts & Collaborators (groups) R&D & IT (contexts) |
“field_machine_name”: {“group”: “string1, string2”, “contexts”: “string1, string2”} | Returns a JSON object with two keys: group and context. The values are the display labels (names) of the assigned user group and user context, respectively. | |
| Element search fields (ESF) (single-, and multi-select) | OpenAI (company), AR for machine maintenance (innovation project) | “field_machine_name”: {“entity_type_machine_name”: [{“entity_id” {id}, “title”: “string”}], “entity_type_machine_name”: [{“entity_id” {id}, “title”: “string”}]} | Returns a nested JSON object grouped by {entity_type}, containing an array of linked element objects (incl. {id} and title). | |
| File fields (single-, and multi-select) | File1.png, file2.xlsx | “field_machine_name”: [{“path”: “file_path.file_type”, “filename”: “string”}, {“path”: “file_path.file_type”, “filename”: “string”}] | Returns an array of objects, where each object provides the secure path (URL) and filename. | |
| (Element-) Relations | OpenAI (company), AR for machine maintenance (innovation project) | “relations”: {“entity_type_machine_name”: [{“entity_id”: {id}, “title”: “string”}], “entity_type_machine_name”: [{“entity_id”: {id}, “title”: “string”}]} | Returns a nested JSON object grouped by {entity_type}, containing an array of linked element relation objects (incl. {id} and title), following a similar structure as element search fields (ESF). | |
| Ratings | Rating data |
“rating_info”:{“number_ratings_active”: “string”, “number_ratings_inactive”: “string”, “[rating_id]_[criteria_machine_name]”: {“criteria_name”: “string”, “average_string”: “string”, “average_decimal”: “string”, “users”: [“uid1”, “uid2”], “rating_group”: “string”, “rating_data”: [{“user”: “user_fullname”, “user_context”: “string”, “rating_type”: “string”, “rating_value”: “string”, “rating_date”: “date_string”, “comment”: “string”, “status”: “Active/Inactive”, “uid”: “user_id”}]} //…more criteria |
Returns the total count of active/inactive individual ratings as strings. The main object is indexed by the unique rating_id and criteria_machine_name. Provides the criteria label, average rating (as both decimal and string), the count of users (users, array of UIDs), and the associated rating group name. Further, an array of objects containing every individual rating action, including active and inactive (overwritten) rating submissions. Details of one rating: the user's full name (and the context in case of context rating enabled), the submitted rating value, date, any comment, and the submission status (Active or Inactive). | |
Endpoint /api/itonics_idea.json and /api/itonics_idea/{id}.json for submission/idea element retrieval:
| Field type | Example field value | Expected API response | Notes on structure | |
| Text field (Title) | Creative AI | “field_machine_name”: “string” |
Simple string value | |
| Text area field (Abstract) | Creative AI (CAI) is the branch of artificial intelligence. | “field_machine_name”: “string” | Simple string value | |
| Rich text editor (RTE) field (Description) | Creative AI technologies have the potential to fundamentally alter … | “field_machine_name”: “string with <b>HTML</b> tags” | Returns text content, including HTML tags for formatting | |
| Header Image (Image file) | Image file path (Base64 encoded if configured) | “header_image”: “https://url/path/image.jpg” | Returns the full, external URL path to the image file. | |
| List fields |
Single choice field (single-select radio button)
Multiple choice field (multi-select dropdown field) |
Yes |
“field_machine_name”: {“field_option_id”: “string”} |
Returns a JSON object mapping the unique field_option_id (key) to the displayed label (value). Note: applies for both single- and multiple choice. |
| One, two | “field_machine_name”: {“field_option_id”: “string”, “field_option_id”: “string”} | |||
| Date picker fields | 2025-10-27 | “field_machine_name”: “YYYY-MM-DD” | Returns a date string in the YYYY-MM-DD format. | |
| Tags (Term search field) | artificial intelligence, machine learning | “Tags”: “artificial intelligence;machine learning” | Returns a single string with all tags separated by a semicolon (;). | |
| Authors (system default field) | John Doe | “entity_authors_username”: “john.doe” |
Returns two separate fields: one with the technical username(s) (comma-separated for multi-select) and one with the corresponding full name(s) (again, comma-separated for multi-select) | |
| “entity_authors_fullname”: “John Doe” | ||||
| User search field (USF) (single-, and multi-select) | Jane Innovation |
“field_machine_name_username”: “jane.innovation” |
Returns two separate fields: one with the technical username(s) (comma-separated for multi-select) and one with the corresponding full name(s) (again, comma-separated for multi-select) | |
| Jane Innovation, John Doe | “field_machine_name_fullname”: “Jane Innovation,John Doe” | |||
| References | URL / file path | "attachments": [{"path”: "string", "title": "string"}] | Returns an array of objects defining attached references (path is the URL/file path, title is the display name). | |
| (Element-) Relations | OpenAI (company), Artificial intelligence challenge (campaign | “relations”: {“entity_type_machine_name”: [{“entity_id”: {id}, “title”: “string”}], “entity_type_machine_name”: [{“entity_id”: {id}, “title”: “string”}]} | Returns a nested JSON object grouped by {entity_type}, containing an array of linked element relation objects (incl. {id} and title), following a similar structure as element search fields (ESF). | |
| Five-star rating | 2.5 | "five_star": number | Returns a number value. | |
| Submission rating | Rating data and Evaluator assignments |
“ratings”:{“phase_id”: {“phase_name”: {“evaluators”: [{“evaluator_username”: “username1, username2”, “evaluator_fullname”: “fullname1, fullname2”}], “criteria_machine_name”: {“criteria_name”: “string”, “average_decimal”: “number string”, “average_string”: “string”, “users”: integer} //…more criteria }}} |
Returns a primary object indexed first by phase_id and then nested under the phase_name. An array of objects listing all assigned evaluators (usernames / fullnames are comma-separated strings if multiple exist). Each rating criterion criteria_machine_name is an object providing the average rating in both decimal and string format, along with the count of users who provided a rating. |
|
Endpoint /api/roadmap/{id}.json for roadmap data retrieval:
| Endpoint | Expected API response | Notes on structure |
| /api/roadmap/{id}.json |
{"layers": [{ "id": "string", "label": "string", "elements": [{ "element_id": number, "entity_type": "string", "url": "string", "title": "string", "abstract": "string", “start": "YYYY-MM-DD", "end": "YYYY-MM-DD", "status": number, "is_synced": boolean, "milestones": [{ "milestone_date": "YYYY-MM-DD", "milestone_description": "string", "milestone_title": "string", "milestone_type": number, "milestone_generated_id": "string", "id": "string", // ... plus any custom milestone fields // }]}], "children": [ // recursive structure: repeats the "layers" object format for sub-layers // ]}]} |
The response is a recursive structure defined by the layers array, preserving the full roadmap hierarchy. Each layer contains an elements array and a children array (for sub-layers). The milestone data is nested within each element object. |
| /api/roadmap/{id}.json?type=connection |
{"connections": { "connection_id_1": {"connection_id": number, "connection_type_id": number,"origin": { "element_id": number, "entity_type": "string"}, // or "etype": "string", "type": "milestone", "machine_id": "string" // "target": { "element_id": number, "entity_type": "string" // or "etype": "string", "type": "milestone", "machine_id": "string" // }}, // ... additional connections ... // }} |
The entire response is encapsulated within the connections object, using the connection_id as the unique object key. Each connection links an origin and target element, identified by their element_id and entity_type. |
Endpoint /api/timeline.json and /api/timeline/{id}.json for timeline data retrieval:
| Endpoint | Action in ITONICS | Expected API response | Notes on structure |
|
/api/timeline.json?entity_type={entity_type}
/api/timeline.json?entity_type={entity_type}&entity_id={entity_id} |
Element creation (Draft / review / published) |
{"changed_by": "username", "action": "draft_created / review / create"} |
Simple action taken by the user. Actions can be draft_created, review, or create (for published). |
| Publishing a draft element |
{"changed_by":"username", “action":"published", “field_label":"Status", "new_value":{"field_label":"Published", "field_value":"1"}, "old_value":{"field_label":"Draft", “field_value":"0"}} |
Uses a specific action (e.g., published). The new_value includes the numeric status code (1 for Published, 2 for Review, 0 for draft). | |
| Field value update (e.g. Title) |
{"changed_by":"username", “action":"entity_update", “field_label":"Title", "new_value":{"field_label":"Title", "field_value":"old_string_value"}, "old_value":{"field_label":"Title", “field_value":"new_string_value"}} |
Returns the (simple string, number, etc.) value for both new_value and old_value. | |
| Element liked / followed | {“changed_by”: “username”, “action”: “liked / follow”} | Simple activity action. Actions are liked, unliked, follow, or unfollowed. | |
| Element comment | {“changed_by”: “username”, “action”: “comment”, “new_value”: “<p>comment_value</p>”} | Includes the HTML encoded comment text in new_value. |
Endpoint /api/user.json and /api/user/{id}.json for user data retrieval:
| Endpoint | Expected API response | Notes on structure |
|
/api/user.json
/api/user/{id}.json |
“uid”: “id_string” “username”: “string” “mail”: “mail_string” “first_name”: “string” / “last_name”: “string” “last_edit_date”: “date_string” (0 if no edit yet) “first_login”: “string (null if no login yet) / “last_login”: “string” “profile_image”: “https://url/path/image.jpg” “user_roles”: {“role_1”,“role_2”} “user_field_machine_name”: “string / number” |
Returns the unique numerical ID as a string, the user’s login identifier/username, primary email address, date strings for last edit date, logins, and access information, as well as profile image (base64 encoded file), user role information, and default- and custom user field information. |
GET meta controls & filter options
To efficiently slice and query your data set, you can pass multiple supported meta controls and filters along with your GET request, combining them using the & symbol, or using ? character for single parameters, e.g. ?limit=100.
Standard pagination and ordering controls
These meta controls are universally available to manage data size, pagination, and sorting.
Check out our public Postman API collection:
This dedicated resource provides detailed sample request bodies and complete output formats for all GET, POST, and PUT endpoints, ensuring you quickly understand the necessary technical specifications and expected JSON formats.
| Meta control | Details | Sample request |
| limit | Returns only the defined limit of elements / users per page. The default limit is 100 results. | /api/itonics_trend.json?limit=10 |
| /api/user.json?limit=25 | ||
| For structured data, like roadmaps, this limit is applied independently to each layer or sub-layer. If limit=2, only 2 elements will be displayed in the first page of each layer, but the full structural hierarchy is always preserved, including empty layers. | /api/roadmap/{id}.json?limit=10 | |
| page |
Used for pagination, specifying the data offset based on the limit. Returns an error if the requested page is empty. Returns those x elements, where x is {limit} and the number of total elements of type {entity_type} is greater than {limit}. The returned data structure contains links to itself (self), the first page (first) and the last page (last). If your current page is not the last or the first one, the data structure will also generate links to the previous page (prev) and the next page (next). The requests are limited to 100 results per page. |
/api/itonics_trend.json?page=2&limit=13 |
| For structured data, like roadmaps, pagination applies independently to each layer or sub-layer. | /api/roadmap/{id}.json?page=2&limit=13 | |
| sort | Defines the field used for ordering the results. Available options are: ds_created (default), ds_updated, or ds_label. | /api/itonics_trend.json?sort=ds_label |
| direction | Defines the sorting order. Available options are: DESC (default) or ASC. | /api/itonics_trend.json?direction=DESC |
| from_date | Returns only data created later than the defined date. Date format: mm/dd/yyyy. | /api/user_stats/login_rate.json?from_date=01/01/2025 |
| to_date | Returns only data created earlier than the defined date. Date format: mm/dd/yyyy. | /api/user_stats/login_rate.json?to_date=01/01/2025 |
| range | Defines the time resolution for statistics (e.g., in reporting endpoints). Available options are: days (default), weeks, or months. Date format: mm/dd/yyyy. |
/api/user_stats/login_rate.json?range=weeks /api/user_stats/login_rate.json?from_date=01/01/2024&to_date=10/31/2025&range=days |
| firstname and lastname | Returns only users whose first name or last name matches with the sent query. |
/api/user.json?firstname=John&lastname=Doe
|
Dynamic data and filtering controls
These controls are used for complex filtering based on field values, text search, or element properties. To retrieve the configuration details (including machine names) necessary for filtering by specific field values, use the /api/entity_field_properties.json?type={entity_type} GET endpoint of a particular {entity_type}. Note: Filter values must be URL encoded (e.g., spaces converted to %20).
| Filter option | Details | Sample request |
| query | Full text search. Returns all elements containing the given string in any text or tag field. | /api/itonics_trend.json?query=creative%20ai |
| title | Returns all elements containing the given string in their title. | /api/itonics_technology.json?title=creative%20ai |
| List fields | Filters by the machine name of a list field. Note: The filter value must be the URL-encoded machine name of the list option. | /api/itonics_trend.json?trend_segment_hierarchy_entity_segment=Politics%20%26%20Law |
| User search fields | Filters by the machine name of a user search field. Note: The filter value must be the username of the requested user. | /api/itonics_trend.json?internal_experts=john.doe |
| Date fields | Filters elements based on a date field's value. Append _from or _to to the field's machine name. Date format: mm/dd/yyyy. | /api/itonics_innovation_project_tr3.json?last_review_date_from=01/01/2025 |
| Relations | Returns all elements related to the requested element. The filter value (element name) must be a URL-encoded string. | /api/itonics_trend.json?relates_to=Data%20Sustainability |
| Tags | Returns all elements tagged with the requested tag. The filter value (tag name) must be a URL-encoded string. | /api/itonics_trend.json?tag=artifical%20intelligence |
| Create date | Filters elements created before (_to) or after (_from) the requested date. Date format: mm/dd/yyyy. |
/api/itonics_trend.json?created_date_from=01/01/2025 /api/itonics_trend.json?created_date_to=01/01/2024 |
| Creator | Returns all elements created by the requested user. Note: The filter value must be the user's username. | /api/itonics_trend.json?created_by=john.doe |
| Update date | Filters elements updated before (_to) or after (_from) the requested date. Date format: mm/dd/yyyy. |
/api/itonics_trend.json?updated_date_from=01/01/2025 /api/itonics_trend.json?updated_date_to=01/01/2024
|
Element status filters
These specific parameters filter elements based on their status or system flags.
| Filter option | Parameter & value | Description | Sample request |
| New flag |
is_new=1 is_new=0 |
1 returns all elements created within the last 30 days. 0 returns all others. | /api/itonics_trend.json?is_new=1 |
| Archived flag |
is_archived=1 is_archived=0 |
1 returns all elements marked as "Archived." 0 returns all others. | /api/itonics_trend.json?is_archived=1 |
| Status | is_status=[0, 1, or 2] | Filters by element publishing status: 0 (Draft), 1 (Published), or 2 (Review). | /api/itonics_trend.json?is_status=0 |
POST & PUT endpoints
This section details the endpoints and required input formats for creating (POST) and updating (PUT) data. Unlike GET requests, these operations require a specific JSON body and proper X-CSRF token authentication to successfully modify resources in your ITONICS application. These writing operations are essential for automated data injection and synchronization within your ITONICS application. Note: POST and PUT requests are not available for the /api/user.json and /api/roadmap.json endpoints, you can only use GET.
Check out our public Postman API collection:
This dedicated resource provides detailed sample request bodies and complete output formats for all GET, POST, and PUT endpoints, ensuring you quickly understand the necessary technical specifications and expected JSON formats.
POST requests (Create)
The following table lists the endpoints available for creating new data records (elements, users, etc.) in your ITONICS application via POST requests.
| Endpoint group | Endpoint format | Details | Sample request |
| New element | /api/{entity_type}.json |
Creates a new element of the specified {entity_type}. All data for the different fields must be provided in the request body. Retrieve field configuration details (incl. required machine names) by querying the /api/entity_field_properties.json?type={entity_type} GET endpoint for the relevant {entity_type}. |
/api/itonics_trend.json |
|
Required permissions:
| |||
| New submission/Idea | /api/itonics_idea.json |
Creates a new submission/idea element of type itonics_idea. All data for the different fields must be provided in the request body. Supported fields are currently limited to submission defaults (Title, Abstract, Authors, Tags, Header Image, Description), no custom submission fields. Retrieve field configuration details (incl. required machine names) by querying the /api/entity_field_properties.json?type=itonics_idea GET endpoint. Mandatory field values: Title, Abstract, Authors (multi-select), and a valid campaign_id (single-select), and Tags, Description, and Header Image if set as required. Status handling:
Phase handling: Including phase_id and status in the POST request automatically publishes the submission element. Provided phase_id is ignored, and the assignment is handled automatically: time-bound campaign = active phase, and always-on campaign = first phase. Further information: You can publish submissions to a campaign that is inactive (e.g., not yet started or past its end date), but publishing to a campaign in Draft status is not allowed. |
/api/itonics_idea.json |
|
Required permissions:
| |||
PUT requests (Update)
The following table lists the endpoints available for updating or manipulating existing data records in your ITONICS application via PUT requests:
| Endpoint group | Endpoint format | Details | Sample request |
| Update element | /api/{entity_type}/{id}.json |
Updates the element of type {entity_type} matching the URI {id}. Note: An error is returned if the ID does not exist. All attributes of the element are updated/overwritten, while all data for the different fields must be provided in the request body. Retrieve field configuration details (incl. required machine names) by querying the /api/entity_field_properties.json?type={entity_type} GET endpoint for the relevant {entity_type}. |
/api/itonics_trend/42.json |
|
Required permissions:
+ “Edit all {entity_type} permission (entity-level) → access to edit all elements of the respective entity type + “Edit own {entity_type} permission (entity-level) → access to edit own elements created by the particular user | |||
| Update submission/idea | /api/itonics_idea/{id}.json |
Updates the submission element matching the URI {id}. Note: An error is returned if the ID does not exist. All attributes of the element are updated/overwritten, while all data for the different fields must be provided in the request body. Supported fields are currently limited to submission defaults (Title, Abstract, Authors, Tags, Header Image, Description), no custom submission fields. Retrieve field configuration details (incl. required machine names) by querying the /api/entity_field_properties.json?type=itonics_idea GET endpoint. Status handling: Status: 0 (Draft): Status remains Draft unless explicitly changed
Status: 1 or >0 (Published): Status remains Published unless explicitly changed
Phase handling: Valid phase_id:
Invalid phase_id:
Further information: You can update submissions of an inactive campaign (not yet started, or end date exceeded). However, updating the campaign_id via PUT is not possible, while the campaign_id is not mandatory when updating a submission. |
/api/itonics_idea/10.json |
|
Required permissions:
| |||
POST & PUT field input formats
When creating (POST) or updating (PUT) data, use the following input formats for common ITONICS field types to ensure your requests are processed correctly.
Check out our public Postman API collection:
This dedicated resource provides detailed sample request bodies and complete output formats for all GET, POST, and PUT endpoints, ensuring you quickly understand the necessary technical specifications and expected JSON formats.
Endpoint /api/{entity_type}.json for element creation and /api/{entity_type}/{id}.json for element update:
| Field type | Example field value | Expected API response | Notes on structure | |
| Single line input field of type text (Title) | Creative AI | “field_machine_name”: “string” |
Expects a simple string value | |
| Simple text field (Abstract) | Creative AI (CAI) is the branch of artificial intelligence. | “field_machine_name”: “string” | Expects a simple string value | |
| Rich text editor (RTE) field (Description) | Creative AI technologies have the potential to fundamentally alter … | “field_machine_name”: “string with <b>HTML</b> tags” | Expects text content, including HTML tags for formatting | |
| Image file (Header image) | (Base64 encoded) Image file | “Field_machine_name”: “encoded_image_data:image/png;base64,X…” | Expects a base64 encoded string prefixed with the data URI scheme (e.g. data:image/png;base64,X…) | |
| Single line input field of type URL, Email, Number | “field_machine_name”: “URL string” |
Expects a simple string or numerical value represented as a string. Note: Multi-select fields expect an array of strings, or numbers / emails represented as a string. |
||
jane.innovation@itonics-innovation.com |
“field_machine_name”: “email string”
|
|||
100 |
“field_machine_name”: “number string” |
|||
| Multi-select case: 100, 200, 300 | “field_machine_name”: [“number/string”, “number/string”, “number/string”] | |||
|
List fields
|
(Searchable) Dropdown (single-select) |
Single-select case: R&D |
"field_machine_name": 166 |
Expected value is the option_id of the selected field option, expected as an integer. |
| (Searchable) Dropdown (multi-select) | Multi-select case: R&D, Marketing |
"field_machine_name": [“166”, “167”] | Expected value is an array of strings, where each string is the option_id of a selected item. | |
|
Radio button
|
Active |
“field_machine_name”: {“field_option_id”} |
Expected value is the option_id of the selected field option, expected as a string. |
|
Single checkbox |
Yes |
“field_machine_name”: 1 |
Expected value is an integer: 1 for 'Yes' (checked), 0 for 'No' (unchecked). | |
| Pearl chain (with check) | In progress | “field_machine_name” “field_option_id” | Expected value is the option_id of the selected field option, expected as a string. | |
| Segment/ hierarchy field |
Technology Segment > Technology Sub-segment (each level can be multi-select): ICT > AI & Engineering > Machines & Robotics > |
“segment_field_machine_name”: {“segment_field_machine_name_entity_segment”: [“segment_field_option_id”, “segment_field_option_id”], “sub_segment_field_machine_name_entity_sub_segment”: [“segment_field_option_id”, “segment_field_option_id”]} | Expects a JSON object where keys are the machine names of the segment levels (e.g., segment_field_machine_name_entity_segment) and values are arrays of strings containing the segment field option_ids. Unused levels can be an empty string "". | |
| Date picker field | 01/25/2025 | “field_machine_name”: “MM/DD/YYYY” | Expected value is a string in the specified date format (MM/DD/YYYY). | |
| Term search field (Tags) | artificial intelligence, machine learning | “Tags”: “artificial intelligence, machine learning” | Expected value is a single string where individual tags are comma-separated. | |
| User search field (USF) (single-, and multi-select) | Jane Innovation |
“field_machine_name_username”: “jane.innovation” |
Single-select USF: Expected value is a string corresponding to the username used in the application. |
|
| Jane Innovation, John Doe | “field_machine_name_username”: [“jane.innovation”,”john.doe”] | The expected value is an array of strings, where each string is a username used in the application. | ||
| User group search field (UGSF) |
Experts & Collaborators (groups) R&D & IT (contexts) |
“field_machine_name”: {“group”: [“1”, “3”], “context”: [“9”, “10”]} | Expects a JSON object containing two keys: "group" and "context", each with an array of strings representing the respective option_ids. | |
| Element search fields (ESF) (single-, and multi-select) | OpenAI (company), AR for machine maintenance (innovation project) | “field_machine_name”: {“entity_type_machine_name”: [20, 21], ““entity_type_machine_name”: [3, 5]} | Expects a JSON object where keys are the machine names of the target entity types (e.g., itonics_project_tr3) and values are an array of integers representing the entity_ids of the linked elements. | |
| File fields (single-, and multi-select) | File1.png |
“field_machine_name”: “file1_base64” |
Expected value must be the base64 encoded string of the file content. |
|
| File1.png, file2.xlsx | “field_machine_name”: [“file1_base64”, “file2_base64”] | Expected value is an array of strings, where each string is the base64 encoded string of a file content. | ||
| (Element-) Relations | OpenAI (company), AR for machine maintenance (innovation project) | “relations”: {“entity_type_machine_name”: [120, 35], “entity_type_machine_name”: [45, 67]} | Expects a JSON object where keys are the machine names of the target entity types (e.g., itonics_project_tr3) and values are an array of strings representing the entity_ids of the related elements. | |
Important notes and best practices
This section covers critical information, limitations, and key best practices to help you manage successful and reliable integrations with the ITONICS REST API.
Image header file upload with base64 encoding
Due to security constraints, the ITONICS REST API cannot directly use relative URLs for images. To enable image functionality via the API, a specific module must be activated by ITONICS.
Enabling image uploads
To enable the header image upload feature, the module RESTful web services support for files and images (restws_file) must be activated by your ITONICS Customer Success Manager.
Upload method (POST/PUT):
Images must be base64 encoded for API requests, as the API accepts JSON data, not binary files. You can use an online tool (e.g., https://www.base64-image.de/) to generate the required string.
The base64 encoded image is converted back to a normal image and stored in the ITONICS application's private folder.
Retrieving Header Images (GET)
When you use a GET request to retrieve entity details along with the uploaded header image (e.g. /api/itonics_trend/42.json), the header image can be returned either as a relative URL or as a base64 encoded image with the API configuration, which can be adjusted by ITONICS upon request.
Default (relative URL):
By default, the API returns a relative URL
This URL cannot be opened without logging into the application, as the image is stored in a private, secured folder
External use (base64 encoding):
If you need to use the header image externally in third-party applications, the API must be configured to return the base64 encoded image / string. This must be configured by your ITONICS Customer Success Manager. Further, the option convert header images to base64 must be set to yes. This ensures the header image is returned as a Base64 encoded string, allowing it to be displayed externally. Refer to the following sample request for a header image with base64 encoding:
Testing & limitations
How to test the REST API?
We recommend using one of the following API testing tools to validate your integration:
Postman rest client (Desktop version)
Talend API Tester
Advanced Rest Client (ARC)
After completing the system setup, use the described endpoints to test all common scenarios, including:
Authentication: Generating and utilizing the required authentication token (e.g., X-CSRF or Access Token)
-
Basic CRUD operations:
GET requests: Verifying the functionality of meta controls, including limiting, pagination, sorting, and querying
POST and PUT requests: Testing fundamental requests to create and manipulate data using both mandatory fields and all available fields
Negative testing: Testing with invalid/missing field values, missing tags, and incorrect data combinations for dependent fields to confirm expected error handling, including HTTP status codes with correct response bodies
Note: ITONICS emphasizes the importance of performing all initial testing in a non-production (STAGE) environment to prevent data corruption.
Limitations
The following constraints and limitations apply to the ITONICS REST API usage:
Usage quotas:
The API enforces a monthly quota for total requests; while the default quota is 100 requests per month
Statistics regarding your monthly API usage can be found under the URL */manage/api
Each request is, by default, limited to 100 results per page (pagination limit)
Potential error response if quota is exceeded: 406 Not Acceptable - Maximum API request reached for this month, please contact the administrator, or your ITONICS Customer Success Manager.
Attribute validation:
The default Title field has a maximum length limit of 255 characters
Date formats are generally expected in the MM/DD/YYYY format for POST / PUT requests
User search fields require the respective user's username for input
Number fields are generally validated using the XXXX.YY format (e.g., 1024.56)
URL fields are generally validated to ensure a valid URL pattern
Email fields are generally validated to ensure a standard, valid email format
Added element relations require a valid element ID
Further known limitations
There is no POST / PUT request available for the campaign entity type (type itonics_campaign_trd3)
There are no POST / PUT request available for the corresponding /api/user.json and /api/roadmap.json GET requests
Status codes
When using and testing the API, you must check the returned HTTP status code, the response message, and the response body to verify success or diagnose errors. Below is a list of common HTTP status codes you may encounter while using and testing the API:
| HTTP status code | Response | Details |
| 200 | 200 OK | The request (typically a GET or PUT) was processed successfully, and a response was generated. |
| 201 | 201 Created | The request (typically a POST/Create) has been fulfilled and has resulted in one or more new resources being created successfully. |
| 400 | 400 Bad Request | The server could not process the request, likely due to a malformed request syntax, missing required data, or addressing the wrong endpoint, e.g. missing ‘{}’ brackets or a non base64 encoded file data, which would be indicated by ‘‘Invalid JSON”. |
| 401 | 401 Unauthorized | The request requires user authentication. This is often returned if the user is not authenticated (e.g., missing or invalid token/Basic Auth). |
| 403 | 403 Forbidden / Restricted | The request was valid and understood, but the server is refusing action. This usually means the API user lacks the necessary permissions for the resource, is blocked, or is attempting a prohibited action (e.g., creating a duplicate unique record). This code is also typically used if the request provided authentication via the WWW-Authenticate header field, but the server did not accept that authentication. The request should not be repeated. |
| 404 | 404 Not Found | The requested resource (via ID or endpoint URL) could not be found, but may be available via a future request. Subsequent requests by the client are permissible. |
| 406 | 406 Not Acceptable | The requested resource can only generate content types that do not match the Accept headers sent in the request. |
| 412 | 412 Precondition Failed | The server does not meet one of the conditions specified by the client in the request header fields. |
| 422 | 422 Unprocessable Entity | The request was well-formed but could not be processed due to semantic errors (e.g., invalid data types, non-existent entity references, and/or missing mandatory fields). |
| 500 | 500 Internal Server Error | A generic error indicating an unexpected condition was encountered on the server, and no more specific message is suitable. |
Example use cases
This section provides potential and proven use cases demonstrating how you can leverage the REST API to solve common integration challenges.
1. Enhanced reporting via business intelligence (BI) tools
Use case: Your organization needs to analyze ITONICS data alongside external datasets (e.g., market data or financial performance) in a dedicated BI environment like Microsoft PowerBI, Tableau, or Qlik.
API utilization:
The GET endpoints (e.g., /api/entity_stats/general\_statistics.json) are used to continuously pull large volumes of data (elements, users, statistics) from ITONICS
The BI tool can then perform dynamic analysis and create rich dashboards, ensuring your reporting is based on the latest ITONICS content
Further details on connecting to PowerBI are covered in this dedicated article.
2. Real-time event-driven automations (API webhooks)
Use case: You need to trigger an immediate action in an external system (like a CRM, ticketing system, or communication platform) whenever a specific event occurs in ITONICS (e.g., an element status changes to "Published" or a new comment is added).
API utilization:
API webhooks are configured within ITONICS to listen for specific events.
When an event occurs, ITONICS sends an instantaneous HTTP POST request (the payload) to one or more predefined external endpoint URLs, enabling real-time communication.
Use an automatic, subsequent GET request (e.g., via /api/{entity_type}/{id}.json or /api/timeline.json?entity_type={entity_type}&entity_id={entity_id}) based on the “subscribed” webhook notification to understand the element’s specific changes.
Further details on API webhook configuration are covered in this dedicated article.
3. Automated idea and content creation
Use Case: An external client application (such as an internal LLM application, or data preparation service) may automatically create new idea submissions or elements in ITONICS without manual input.
API utilization:
Preparation (GET): Before posting an idea, the external application uses the GET /api/entity_field_properties.json?type=itonics_idea&camp_id={id} endpoint to retrieve the required field structure and validation rules for the submission entity type of the specific target campaign.
Creation (POST): The application then uses the POST /api/itonics_idea.json endpoint to submit the new idea, ensuring the request body adheres to the required input format (including Title, Abstract, Authors, and a valid campaign_id).
Refinement (PUT): If the automation needs to update the idea content or adjust (default) fields after creation, it uses the PUT /api/itonics_idea/{id}.json endpoint. This allows for continuous data synchronization and refinement after the initial creation.