Introduction
The Interaxo API gives integrators direct access to the data in the Interaxo platform.
Obtaining Access
Contact Interaxo support for any questions related to API access.
Security
The Interaxo API uses OpenID Connect for identity and authorization, i.e. OAuth2 over SSL.
The API enables access to read and manipulate data in Interaxo on behalf of an Interaxo identity. All communication through the Interaxo API uses the identity of the user:
- The API can only access and read data that the user have read access to in Interaxo
- Similarly, write operations through the API require that the user has write access within Interaxo
- The API user will be set as the owner of items created through the API. This also applies to fields like "last modified by" and audit trails.
Enablement
Consumers of the API must first register an application with Interaxo, and will then be given OAuth client_id
and client_secret
tokens for integrating with the API on behalf of Interaxo users. Web-based integrations must also provide valid redirect_uri
s for recieving tokens from the Identity solution.
The integrator can then initiate a login flow process, as described below. This process will grant your application access to communicate with the API on behalf of an Interaxo identity.
Contact Interaxo support to register an application.
Authentication
To authenticate and obtain an access_token
for communication with the Interaxo API, you can use the client credentials flow. This method uses your client_id
and client_secret
to request an access_token
directly.
The relevant OpenID Connect endpoints are listed here:
https://login.collaboration-sso.com/auth/.well-known/openid-configuration
curl -d audience=https://api.interaxo.com/v1/ \
-d grant_type=client_credentials \
-d client_id=$CLIENT_ID \
-d client_secret=$CLIENT_SECRET \
https://login.collaboration-sso.com/oauth/token
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
...
"access_token" : "my-access-token",
...
}
Oauth Login parameters
Parameter | Example | Description |
---|---|---|
client_id |
example-corp-integration |
ID of registered integration application |
scope |
offline_access |
Oauth scopes the integration requests access to. |
redirect_uri |
https://example.com/oauth_callback |
The integration point callback url. |
Oauth Scopes
The following scopes are supported by the Interaxo API:
Scope | Default | Description |
---|---|---|
offline_access |
no | Allows integration point to store refresh token after user is logged out. Offline tokens expires after 30 days inactivity, while regular refresh_tokens expire after 30 minutes. |
Authorizing Requests
Request:
curl "https://api.interaxo.com/v1/$COMMUNITY/rooms" \
-H "Authorization: Bearer $TOKEN"
All authorized requests to the API must include an HTTP Authorization
header with a valid access_token
, i.e:
Authorization: Bearer {access_token}
Query Parameters
All GET
operations on collection based resources support a common set of query parameters for paging, filtering and sorting:
Parameter | Required | Type | Example | Description |
---|---|---|---|---|
limit |
No | number |
?limit=1000 |
Limit to n items |
skip |
No | number |
?skip=1000 |
Skips n first items |
sort |
No | string |
?sort=-name |
Sorts by field name. - indicates descendant sort |
Error handling
A JSON error object is returned by all errors produced by the API. This error contains an error code and a unique trace ID that can be used in trouble shooting the problem.
The Error object
Response:
HTTP/1.1 500 INTERNAL SERVER ERROR
Content-Type: application/json; charset=UTF-8
{
"trace_id" : "AJI0WC",
"code" : "file_streaming_error",
"message" : "Can not stream file"
}
All API errors contain a JSON response message with the following properties:
Key | Type | Description |
---|---|---|
trace_id |
string |
A unique code for tracing an error. |
code |
number |
See API Error Codes |
message |
string |
Error description |
errors |
array |
Array of validation errors |
Integrators should include the trace_id
value in any relevant support request.
API Error Codes
The Interaxo API uses the following error codes:
Error Code | HTTP Status | Description |
---|---|---|
validation_error | 400 | Invalid data sent |
unauthorized | 401 | Invalid OAuth token |
forbidden | 403 | Incufficient rights to the resource/operation requested |
not_found | 404 | The resource could not be found |
invalid_node_type | 422 | Item is not valid for the content resource/operation requested |
unexpected_error | 500 | Internal Server Error |
file_streaming_error | 500 | File streaming I/O error |
network_communication_error | 503 | Service unavailable |
Validation errors
Response:
HTTP/1.1 400 validation_error
Content-Type: application/json; charset=UTF-8
{
"trace_id" : "AWCQN5",
"code" : "validation_error",
"message" : "Validation failed",
"errors" : [
{
"message" : "Limit field must be positive number",
"code" : "list.invalid_limit_field"
},
{
"message" : "Invalid sort parameter",
"code" : "list.invalid_sort_field"
}
]
}
Errors of type validation_error
may also contain a set of specific error messages relating to fields in the request.
Key | Type | Description |
---|---|---|
code |
string |
Code of validation error |
message |
string |
Contains the description of a validation error |
Communities and Rooms
A community in Interaxo maps to a single customer area. Within a community a customer may have a number of rooms, which are logical containers typically used for projects or organisational units. Users of Interaxo may have access to more than one community.
To use the
curl
examples below, define variables that match your account. You can then paste these working examples in your terminal.
# Oauth2 access_token
TOKEN='my-access-token'
# Interaxo community name
COMMUNITY='my-community'
# A room within the community
ROOM='my-room'
# ID of a content item
ID='6c9d905...'
The Community object
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
[
{
"id" : "example-corp",
"name" : "Example Corp - Sample Project"
},
{
"id" : "other-corp",
"name" : "Other Corp - Sample Project"
}
]
The community object contain the following properties:
Key | Type | Description |
---|---|---|
id |
string |
Community identifier |
name |
string |
Community name |
List all communities
Request:
curl "https://api.interaxo.com/v1/communities" \
-H "Authorization: Bearer $TOKEN"
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
[
{
"id" : "example-corp",
"name" : "Example Corp - Sample Project"
},
{ ... },
]
GET https://api.interaxo.com/v1/communities
Query Parameters
Supports common collection-based query parameters for paging and sorting.
Response
Returns list of community objects.
The Workspace object
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
[
{
"id" : "my-workspace",
"name" : "My Workspace"
},
{
"id" : "another-workspace",
"name" : "Another workspace"
}
]
The workspace object contain the following properties:
Key | Type | Description |
---|---|---|
id |
string |
Workspace identifier |
name |
string |
Workspace name |
List all workspaces
Request:
curl "https://api.interaxo.com/v1/$COMMUNITY/workspaces" \
-H "Authorization: Bearer $TOKEN"
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
[
{
"id" : "my-workspace",
"name" : "My Workspace"
},
{ ... },
]
GET https://api.interaxo.com/v1/{community_id}/workspaces
Query Parameters
Supports common collection-based query parameters for paging and sorting.
Response
Returns list of workspace objects.
The Room object
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
[
{
"id": "my-room",
"name": "My room",
"description": "My description",
"content": {
"root_id": "a2afd701-ade2-4f94-94f9-1d5dbab69622"
},
"workspace": {
"id": "my-workspace",
"name": "My workspace"
},
"metadata": {
"my_key": {
"label": "My label",
"value": "Some value"
},
"another_key": {
"label": "Another label",
"value": "Another value"
}
}
},
{
"id": "another-room",
"name": "Another room",
"description": "Another description",
"content": {
"root_id": "c16748af-ff22-40c3-beea-91862d1b6921"
},
"workspace": {
"id": "another-workspace",
"name": "Another workspace"
},
"metadata": {
"my_key": {
"label": "My label",
"value": "Some value"
}
}
}
]
The room object contain the following properties:
Key | Type | Description |
---|---|---|
id |
string |
ID of a room |
name |
string |
Display name |
description |
string |
Additional description |
content |
object |
Root content item |
workspace |
object |
Workspace relation |
metadata |
map |
Room metadata |
The room.content
object contain the following properties:
Key | Type | Description |
---|---|---|
root_id |
string |
ID of a root content folder |
The room.workspace
object contain the following properties:
Key | Type | Description |
---|---|---|
id |
string |
ID of a workspace |
name |
string |
Display name of a workspace |
The room.metadata
object contain the following properties:
Key | Type | Description |
---|---|---|
label |
string |
metadata label for the provided key |
value |
string |
metadata value for the provided key |
Retrieve a room
Request:
curl "https://api.interaxo.com/v1/$COMMUNITY/rooms/$ROOM" \
-H "Authorization: Bearer $TOKEN"
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"id": "my-room",
"name": "My room",
"description": "My description",
"content": {
"root_id": "a2afd701-ade2-4f94-94f9-1d5dbab69622"
},
"workspace": {
"id": "my-workspace",
"name": "My workspace"
},
"metadata": {
"my_key": {
"label": "My label",
"value": "Some value"
},
"another_key": {
"label": "Another label",
"value": "Another value"
}
}
}
GET https://api.interaxo.com/v1/{community_id}/rooms/{room_id}
The room resource supports GET
for retrieving a room within a community.
URL Parameters
Parameter | Type | Example | Description |
---|---|---|---|
community_id |
string |
my-community |
Community identifier |
room_id |
string |
my-room |
Room identifier |
Response
Returns a room object.
List all rooms
Request:
curl "https://api.interaxo.com/v1/$COMMUNITY/rooms" \
-H "Authorization: Bearer $TOKEN"
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
[
{
"id": "my-room",
"name": "My room",
"description": "My description",
"content": {
"root_id": "a2afd701-ade2-4f94-94f9-1d5dbab69622"
},
"workspace": {
"id": "my-workspace",
"name": "My workspace"
},
"metadata": {
"my_key": {
"label": "My label",
"value": "Some value"
},
"another_key": {
"label": "Another label",
"value": "Another value"
}
}
},
{ ... }
]
GET https://api.interaxo.com/v1/{community_id}/rooms
URL Parameters
Parameter | Type | Example | Description |
---|---|---|---|
community_id |
string |
my-community |
Community identifier |
Query Parameters
Parameter | Required | Type | Example | Description |
---|---|---|---|---|
workspace |
no | string |
my-workspace |
Filter by workspace id |
key=value |
no | string |
project_ref=My Value |
Filter by room metadata |
Supports common collection-based query parameters for paging and sorting.
Response
Returns list of room objects.
Locking Rooms
Request:
JSON_BODY='
{
"lock": false
}
'
curl "https://api.interaxo.com/v1/$COMMUNITY/rooms/$ROOM" \
--header "Content-Type: application/json" \
--request PATCH \
--data $JSON_BODY \
-H "Authorization: Bearer $TOKEN"
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"id": "my-room",
"lock": "false"
// additional properties
}
PATCH https://api.interaxo.com/v1/{community_id}/rooms/{room_id}
To (un)lock a Room, issue a PATCH
request specifying the identifier of the room and modifying the lock
property for the room.
URL Parameters
Parameter | Type | Example | Description |
---|---|---|---|
community_id |
string |
my-community |
Community identifier |
room_id |
string |
my-room |
Room identifier |
Response
Returns a room object.
Users and Groups
An authority in Interaxo is either a user or a group.
The User object
Response fragment:
{
"id" : "user@example.com",
"type": "user"
}
The user
object has the following properties:
Key | Type | Description |
---|---|---|
id |
string |
User id |
type |
string |
Constant user |
Take note that while the id
property is typically an email address, it is not bound to the user profile email address. Integrators should not assume that the id
is in the format of an email address.
The Group object
Response fragment:
{
"id" : "ed11b8a55",
"type": "group",
"name": "All Participants"
}
The group
object has the following properties:
Key | Type | Description |
---|---|---|
id |
string |
Group identifier, max 100 characters. |
type |
string |
Constant group |
name |
string |
Name of Group |
Groups ids
are unique within a community.
The Person object
Response fragment:
{
"id" : "user@example.com",
"email": "user@example.com",
"name": "Example User",
"locale": "nb-NO"
}
The person
object has the following properties:
Key | Type | Description |
---|---|---|
id |
string |
The ID of the user/person. |
name |
string |
Name |
email |
string |
The email address associated with this profile. |
locale |
string |
The locale associated with this profile. |
Retrieve a profile
Request:
curl "https://api.interaxo.com/v1/$COMMUNITY/people/$PERSON_ID" \
-H "Authorization: Bearer $TOKEN"
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"id": "user@example.com",
"email": "user@example.com",
"name": "Example User",
"locale": "nb-NO"
}
GET https://api.interaxo.com/v1/{community_id}/people/{person_id}
The profile resource supports GET
for retrieving the profile for a person.
URL Parameters
Parameter | Type | Example | Description |
---|---|---|---|
community_id |
string |
my-community |
Community identifier |
person_id |
string |
user@example.com |
User id. -me- can be used to specify the currently authenticated user |
Response
Returns a person object.
Retrieve groups for a person
Request:
curl "https://api.interaxo.com/v1/$COMMUNITY/people/$PERSON_ID/groups" \
-H "Authorization: Bearer $TOKEN"
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
[
{
"id": "ae11b8a55",
"type": "group",
"name": "All Participants"
},
{...}
]
GET https://api.interaxo.com/v1/{community_id}/people/{person_id}/groups
The groups resource supports GET
for retrieving groups where person is a member.
URL Parameters
Parameter | Type | Example | Description |
---|---|---|---|
community_id |
string |
my-community |
Community identifier |
person_id |
string |
user@example.com |
User id. -me- can be used to specify the currently authenticated user |
Response
Returns list of group objects.
Room Content
Interaxo exposes a content tree under each room. This tree can be navigated and manipulated through resources that operate on single items and item children at each level.
The root_id
of the content tree is exposed through the Room resource.
Content objects
Content items in Interaxo can be grouped into 4 categories: Folders, Entries, Files and Links. The table below outlines the available items as well as the type of children items allowed under each of these.
Name | type value |
Category | Allowed Children |
---|---|---|---|
Simple Folder | simple-folder |
Folder | Folder, File, Link |
Active Folder | active-folder |
Folder | Entry |
Active Folder with Workflow | workflow-folder |
Folder | Entry |
Entry | entry |
Entry | File |
File | file |
File | |
Link (internal) | internal-link |
Link | |
Link (external) | external-link |
Link |
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"type" : "simple-folder",
"id" : "8be54905-6c9d-430d-9e3f-b40006fdba3f",
"parent_id" : "ec4e334d-74e8-4ea4-8f28-4da942a3b80c",
"name" : "Simple Folder",
"path" : "/Collaborate/All Types/Simple Folder",
"created" : "2017-01-12T10:24:41.739Z",
"last_modified" : "2017-01-12T11:06:44.101Z",
"created_by" : {
"id" : "user@example.com"
},
"last_modified_by" : {
"id" : "user@example.com"
},
"owner" : {
"id" : "user@example.com"
},
"lock_info" : {
"owner": {
"id": "user@example.com"
},
"timestamp": "2017-01-12T11:06:44.101Z"
}
"child_count": 0
}
All Content items all have a set of common properties:
Key | Type | Description |
---|---|---|
type |
string |
Type of item |
id |
string |
UUID |
parent_id |
string |
UUID of parent |
name |
string |
Display name |
path |
string |
Path relative to room, like /My Folder/My File.jpg |
created |
string |
ISO 8601 formatted creation datetime |
last_modified |
string |
ISO 8601 formatted last modified datetime |
created_by |
object |
User that created the item |
last_modified_by |
object |
User that last modified the item |
owner |
object |
User or Group that owns the item |
lock_info |
object |
Optional Lock information if the item is locked. |
The Lock Info object
The Lock Info object contain the following properties:
Key | Type | Description |
---|---|---|
owner |
object |
User who owns the lock |
timestamp |
string |
ISO 8601 formatted datetime when the item was locked |
Retrieve a content item
Request:
curl "https://api.interaxo.com/v1/$COMMUNITY/rooms/$ROOM/content/$ID" \
-H "Authorization: Bearer $TOKEN"
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"type" : "simple-folder",
"id" : "8be54905-6c9d-430d-9e3f-b40006fdba3f",
"parent_id" : "ec4e334d-74e8-4ea4-8f28-4da942a3b80c",
"name" : "Simple Folder",
"path" : "/Collaborate/All Types/Simple Folder",
"created" : "2017-01-12T10:24:41.739Z",
"last_modified" : "2017-01-12T11:06:44.101Z",
"created_by" : {
"id" : "user@example.com"
},
"last_modified_by" : {
"id" : "user@example.com"
},
"owner" : {
"id" : "user@example.com"
},
"child_count" : 0
}
GET (room context)/content/{id}
URL Parameters
Parameter | Type | Example | Description |
---|---|---|---|
id |
string |
04193719-a0... |
UUID of the item |
Response
Returns a single item of any of the item types available for the relevant parent resource.
Create and update content items
In the current version of the API, only Entries can be created and updated.
Creating and updating other content items is not supported in the current version of the API. Contact Support if this is important to you.
Delete a content item
Request:
curl -X DELETE "https://api.interaxo.com/v1/$COMMUNITY/rooms/$ROOM/content/$ID" \
-H "Authorization: Bearer $TOKEN"
Response:
HTTP/1.1 204 No Content
DELETE (room context)/content/{id}
All content items supports deletion through issuing a DELETE
request to the relevant resource.
List Children
Request:
curl "https://api.interaxo.com/v1/$COMMUNITY/rooms/$ROOM/content/$ID/children?sort=id&limit=2" \
-H "Authorization: Bearer $TOKEN"
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
[
{
"type" : "simple-folder",
"id" : "8be54905-6c9d-430d-9e3f-b40006fdba3f",
"parent_id" : "ec4e334d-74e8-4ea4-8f28-4da942a3b80c",
"name" : "Simple Folder",
"path" : "/Collaborate/All Types/Simple Folder",
"created" : "2017-01-12T10:24:41.739Z",
"last_modified" : "2017-01-12T11:06:44.101Z",
"created_by" : {
"id" : "user@example.com"
},
"last_modified_by" : {
"id" : "user@example.com"
},
"owner" : {
"id" : "user@example.com"
},
"child_count" : 0
},
{
"type" : "file",
"id" : "c2afd701-ade2-4f94-94f9-1d5dbab69622",
"parent_id" : "ec4e334d-74e8-4ea4-8f28-4da942a3b80c",
"name" : "File.txt",
"path" : "/Collaborate/All Types/File.txt",
"created" : "2017-01-12T10:31:24.459Z",
"last_modified" : "2017-01-12T10:31:24.459Z",
"created_by" : {
"id" : "user@example.com"
},
"last_modified_by" : {
"id" : "user@example.com"
},
"owner" : {
"id" : "user@example.com"
},
"version" : "1.0",
"mime_type" : "text/plain",
"file_size" : 7
}
]
GET (room context)/content/{id}/children
Lists children for a content item.
URL Parameters
Parameter | Type | Example | Description |
---|---|---|---|
id |
string |
04193719-a0... |
UUID of a container item |
Query Parameters
Supports common collection-based query parameters for paging and sorting.
Response
Returns a list containing any of the content objects available for the relevant parent resource..
Content Object Search
Search enables you to search for Content Objects in the context of a Room
You can use Content Object Search to search for any Simple Folder, Active Folder, Active Folder with Workflow, File or Entry
Note: For purposes of readability, all examples shown do not show any URL encoding of the request.
Request:
curl "https://api.interaxo.com/v1/$COMMUNITY/rooms/$ROOM/content/$ID/search?type=file&name=File.jpg" \
-H "Authorization: Bearer $TOKEN"
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
[ {
"type" : "file",
"created" : "2017-01-12T10:17:28.438Z",
"created_by" : {
"type" : "user",
"id" : "beast@mailinator.com"
},
"file_size" : 233009,
"id" : "09f1997e-eeac-4e3d-a2cb-ae2f80e33d93",
"last_modified" : "2017-01-12T10:17:28.438Z",
"last_modified_by" : {
"type" : "user",
"id" : "beast@mailinator.com"
},
"mime_type" : "image/jpeg",
"name" : "File.jpg",
"owner" : {
"type" : "user",
"id" : "beast@mailinator.com"
},
"parent_id" : "18b110e2-a103-4ab8-aec8-1db9ef8de3c1",
"path" : "/Collaborate/READ ONLY Files/File.jpg",
"version" : "1.0"
} ]
URL Parameters
Parameter | Type | Example | Description |
---|---|---|---|
room |
string |
public-api |
id of the room to search in. |
id |
string |
04193719-a0... |
id of the folder to search in. Search will be scoped to this folder and subfolders. |
Query Parameters
Parameter | Required | Type | Example | Allowed values | Description |
---|---|---|---|---|---|
type |
yes | string |
file |
file, folder, active-folder, workflow-folder, entry | Name of content item to search for |
folder_id |
no | string |
fcc8aaf3-19... |
Any folder ID in the room | Scopes the search to any number of folders |
field=value |
yes | string |
name=file.txt |
Any | Search criteria |
'skip' | no | 'numeric' | '5' | Any positive anumber | Skips results in set |
'limit' | no | 'numeric' | '5' | Any positive anumber | Limits amount of results returned |
'sort' | no | 'string' | 'name' | Name of property to sort on | Sorts search results by value of property |
Search criterias
Searching for a certain field and value has the format of {field_name=value}.
The following properties are currently supported
Property | Description |
---|---|
name |
Name of item |
created |
Date / DateTime in yyyy-mm-dd / yyyy-mm-dd'T'HH:mm:ssZ format |
version |
Version label of file |
content |
Content of file |
instruction |
Folder instruction |
Example - Search for files named file.txt
type=file&name=file.txt
Search criterias (Entries)
When searching for Entries, an extended set of properties can be searched which is defined by the field configuration of the Active Folder.
Searching for entries requires the search root (id) to be in the context of an Active Folder, Active Folder with Workflow or Step.
Range queries
Range queries have the format field_name_from=value
/ field_name_to=value
These queries are supported for Numeric and Date fields.
Example - Search for entries with a numeric value between 10 and 20 for the field "A Numeric Field":
A Numeric Field_from=10&A Numeric Field_to=20
Multiple values (OR)
It is possible to search for multiple values for the same field by repeating the field query
Example - Search for entries where "My Text Field" has the value "Hello" or "Another Hello":
My Text Field=Hello&My text Field=Another Hello
Scoping search to certain folders
It is possible to define which folder(s) should be searched by specifying the id of the folders
Example - Search file in two folder locations:
folder_id=18b110e2-a103-4ab8-aec8-1db9ef8de3c1&folder_id=0de41104-8be4-47c2-958c-bdb495697d8d
Combined queries
Queries can be combined to form more complex queries
Example - Search for files or folders named A Test OR B Test which were created on 5. Feb 2016 in two different locations
type=file&type=folder&name=A Test&name=B Test&created=2016-02-05&folder_id=18b110e2-a103-4ab8-aec8&folder_id=0de41104-8be4-47c2-958c
Partial matching
Partial matching is supported for Text fields by using the * operator.
Example: olde will match 'My Folder'
Response
Depending on which type
is searched for, returns a list of content objects.
Important note
These results are 'eventually consistent' which implies that changes made to the file name is not immediately reflected in the list of results.
Files
The File object
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"type" : "file",
"version" : "1.0",
"mime_type" : "text/plain",
"file_size" : 7,
...
}
A file in Interaxo has both meta data and content, and exists both in form of attachments to entries and child items of simple folders.
Content items with type file
has the following additional properties:
Key | Type | Description |
---|---|---|
version |
string |
File versions like 1.0 |
mime_type |
string |
Type of file like image/png |
file_size |
number |
Size of file in bytes |
content_url |
string |
File content public URL |
Create a file
Request:
curl -v --form file=@abc.txt \
"https://api.interaxo.com/v1/$COMMUNITY/rooms/$ROOM/content/$ID/children" \
-H "Authorization: Bearer $TOKEN"
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"type" : "file",
"id" : "3ab40c92-825f-4963-aab0-32552d4696b6",
"parent_id" : "ed507f9c-8e33-4616-85be-22038cd3a3a8",
"name" : "abc.txt",
"path" : "/Collaborate/Upload/Simple Folder/abc.txt",
"content_url" : "https://ix.interaxo.com/v1/community/public/v2/files/id/content?t=...",
"created" : "2017-03-16T22:19:08.281Z",
"last_modified" : "2017-03-16T22:19:08.281Z",
"created_by" : {
"id" : "user@example.com"
},
"last_modified_by" : {
"id" : "user@example.com"
},
"owner" : {
"id" : "user@example.com"
},
"version" : "1.0",
"mime_type" : "text/plain",
"file_size" : 18
}
POST (room context)/content/{id}/children
Container items of type simple-folder
or entry
supports upload of files.
URL Parameters
Parameter | Type | Example | Description |
---|---|---|---|
id |
string |
04193719-a0... |
UUID of a simple folder or an entry |
Request Body
Key | Required | Type | Description |
---|---|---|---|
file |
Yes | File |
Multipart file |
Response
Returns a file object.
Retrieve a file
To retrieve a file, issue a GET
request to the content item. This endpoint will retrieve file meta-data only, not the file content.
Search for a file in folder by file name
Request:
curl "https://api.interaxo.com/v1/$COMMUNITY/rooms/$ROOM/content/$ID/files?name=My File" \
-H "Authorization: Bearer $TOKEN"
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
[{
"type" : "file",
"id" : "3ab40c92-825f-4963-aab0-32552d4696b6",
"parent_id" : "ed507f9c-8e33-4616-85be-22038cd3a3a8",
"name" : "My File.txt",
"path" : "/Collaborate/Upload/Simple Folder/My File.txt",
"content_url" : "https://ix.interaxo.com/v1/community/public/v2/files/id/content?t=...",
"created" : "2017-03-16T22:19:08.281Z",
"last_modified" : "2017-03-16T22:48:41.912Z",
"created_by" : {
"id" : "user@example.com"
},
"last_modified_by" : {
"id" : "user@example.com"
},
"owner" : {
"id" : "user@example.com"
},
"version" : "2.0",
"mime_type" : "text/plain",
"file_size" : 18
}]
GET (room context)/content/(id)/files?name=
URL Parameters
Parameter | Type | Example | Description |
---|---|---|---|
id |
string |
04193719-a0... |
UUID of search root. Search will be scoped to this folder. |
Query Parameters
Parameter | Required | Type | Example | Description |
---|---|---|---|---|
name |
yes | string |
?name=My File |
Name of content item to search for |
Response
Returns a list of files matching the name.
Important note
These results are 'eventually consistent' which implies that changes made to the file name is not immediately reflected in the list of results.
Search for a file in a folder by folder name
Request:
curl "https://api.interaxo.com/v1/$COMMUNITY/rooms/$ROOM/content/$ID/files?name=My Folder" \
-H "Authorization: Bearer $TOKEN"
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
[{
"type" : "file",
"id" : "3ab40c92-825f-4963-aab0-32552d4696b6",
"parent_id" : "ed507f9c-8e33-4616-85be-22038cd3a3a8",
"name" : "abc.txt",
"path" : "/Collaborate/Upload/My Folder/abc.txt",
"content_url" : "https://ix.interaxo.com/v1/community/public/v2/files/id/content?t=...",
"created" : "2017-03-16T22:19:08.281Z",
"last_modified" : "2017-03-16T22:48:41.912Z",
"created_by" : {
"id" : "user@example.com"
},
"last_modified_by" : {
"id" : "user@example.com"
},
"owner" : {
"id" : "user@example.com"
},
"version" : "2.0",
"mime_type" : "text/plain",
"file_size" : 18
}]
GET (room context)/content/(id)/files?name=
URL Parameters
Parameter | Type | Example | Description |
---|---|---|---|
id |
string |
04193719-a0... |
UUID of search root. Search will be scoped to this folder. |
Query Parameters
Parameter | Required | Type | Example | Description |
---|---|---|---|---|
name |
yes | string |
?name=My Folder |
Name of folder item to search for |
Response
Returns a list of files located within a folder matching the name.
Important note
These results are 'eventually consistent' which implies that changes made to the folder name is not immediately reflected in the list of results.
Update a file
Request:
curl -X POST -v --form file=@abc.txt \
"https://api.interaxo.com/v1/$COMMUNITY/rooms/$ROOM/files/$ID/versions" \
-H "Authorization: Bearer $TOKEN"
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"type" : "file",
"id" : "3ab40c92-825f-4963-aab0-32552d4696b6",
"parent_id" : "ed507f9c-8e33-4616-85be-22038cd3a3a8",
"name" : "abc.txt",
"path" : "/Collaborate/Upload/Simple Folder/abc.txt",
"content_url" : "https://ix.interaxo.com/v1/community/public/v2/files/id/content?t=...",
"created" : "2017-03-16T22:19:08.281Z",
"last_modified" : "2017-03-16T22:48:41.912Z",
"created_by" : {
"id" : "user@example.com"
},
"last_modified_by" : {
"id" : "user@example.com"
},
"owner" : {
"id" : "user@example.com"
},
"version" : "2.0",
"mime_type" : "text/plain",
"file_size" : 18
}
POST (room context)/files/{id}/versions
The versions-endpoint allows uploading new versions of files.
URL Parameters
Parameter | Type | Example | Description |
---|---|---|---|
id |
string |
04193719-a0... |
UUID of item |
Query Parameters
Parameter | Required | Type | Example | Description |
---|---|---|---|---|
major |
No | boolean |
?major=true |
true - major version, false - minor. Major by default. |
Request Body
Key | Required | Type | Description |
---|---|---|---|
file |
Yes | File |
Multipart file |
Response
Returns the updated file.
Delete a file
To delete a file, issue a DELETE
request to the content item.
Download a file
Request:
curl "https://api.interaxo.com/v1/$COMMUNITY/rooms/$ROOM/files/$ID/content" \
-H "Authorization: Bearer $TOKEN"
GET (room context)/files/{id}/content
This endpoint allows you to download a single file by file ID.
URL Parameters
Parameter | Type | Example | Description |
---|---|---|---|
id |
string |
04193719-a0... |
UUID of a file |
Query Parameters
Parameter | Required | Type | Example | Description |
---|---|---|---|---|
version |
No | string |
?version=2.0 or ?v=2.0 |
Version of file. No version means latest |
Response
Returns the file content with the following headers:
Header | Type | Description |
---|---|---|
Content-Type |
string |
Type of a file like image/jpeg;charset=UTF-8 |
Download file thumbnail
Request:
curl "https://api.interaxo.com/v1/$COMMUNITY/rooms/$ROOM/files/$ID/thumbnail" \
-H "Authorization: Bearer $TOKEN"
GET (room context)/files/{id}/thumbnail
This endpoint allows you to download a image/png
thumbnail of the file with a maximum size of 100x?
or ?x100
. If the file is an image with original dimensions smaller than 100x100
the thumbnail will contain the original size of the image.
URL Parameters
Parameter | Type | Example | Description |
---|---|---|---|
id |
string |
04193719-a0... |
UUID of a file |
Response
Returns file thumnail with the following headers:
Header | Type | Description |
---|---|---|
Content-Type |
string |
Always image/png;charset=UTF-8 . |
Download file preview
Request:
curl "https://api.interaxo.com/v1/$COMMUNITY/rooms/$ROOM/files/$ID/preview" \
-H "Authorization: Bearer $TOKEN"
GET (room context)/files/{id}/preview
This endpoint allows you to download a image/png
preview of the file with a maximum size of 960x?
or ?x960
. If the file is an image with original dimensions smaller than 960x960
the preview will contain the original size of the image.
URL Parameters
Parameter | Type | Example | Description |
---|---|---|---|
id |
string |
04193719-a0... |
UUID of a file |
Response
Returns file binary content with the following headers:
Header | Type | Description |
---|---|---|
Content-Type |
string |
Always image/png;charset=UTF-8 . |
Links
Link items in Interaxo are references to internal content or external URLs.
Two types of links are supported:
Name | Type | Description |
---|---|---|
Internal link | internal-link |
References other content items in Interaxo |
External link | external-link |
References external content by URL |
The Link object (internal)
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"type" : "internal-link",
"target" : "_blank",
"destination" : "c2afd701-ade2-4f94-94f9-1d5dbab69622",
...
}
Links with type internal-link
has the following additional properties:
Key | Type | Description |
---|---|---|
target |
string |
Browser link target (_blank or _self ). |
destination |
string |
UUID of destination item. |
The Link object (external)
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"type" : "external-link",
"target" : "_blank",
"url" : "https://www.google.no/",
...
}
Links with type external-link
has the following additional properties:
Key | Type | Description |
---|---|---|
target |
string |
Browser link target (_blank or _self ). |
url |
string |
External url link like https://www.google.com/ . |
Create a link
Creating links is not supported in the current version of the API. Contact Support if this is important to you.
Retreive a link
To retrieve a link, issue a GET
request to the content item.
Update a link
Updating links is not supported in the current version of the API. Contact Support if this is important to you.
Delete a link
To delete a link, issue a DELETE
request to the content item.
Simple Folders
Simple folders are like regular folders in Windows explorer or other file systems. They may contain children that are files, folders, or other content items.
The Simple Folder object
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"type" : "simple-folder",
"child_count" : 0,
...
}
Folders of type simple-folder
are containers that may contain child items like files, simple folder, etc.
Folders of type simple-folder
has the following additional properties:
Key | Type | Description |
---|---|---|
child_count |
number |
Count of immediate children. |
Create a simple folder
Creating folders is not supported in the current version of the API. Contact Support if this is important to you.
Retreive a simple folder
To retrieve an simple folder, issue a GET
request to the content item.
Update a simple folder
Updating folders is not supported in the current version of the API. Contact Support if this is important to you.
Delete a simple folder
To delete a simple folder, issue a DELETE
request to the content item.
List children
To list children of a simple folder, issue a GET
request to the content item. Children of simple folders can be of type folder (simple folder, active folder, worfklow folder), file or link.
Active Folders
Active folders in Interaxo are folders where you can store rich customizable meta-data in child items called entries. Entries may contain a number of meta-data fields of various types, and users can group, sort and filter the folder based on these fields.
These are the field types currently supported in the API:
Name | Key | Description |
---|---|---|
Plain text | string |
Simple string, max 255 characters |
Number | numeric |
Numeric value with 2 decimal places |
Date | date |
ISO 8601 formatted date |
List | list |
Single/multiple selection list |
Rich text | rich-text |
Longer text with rich formatting |
Member | member |
Single/multiple selection list of interaxo users |
Autonumber | auto-number |
Autoincrementing number |
The Active Folder object
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"type" : "active-folder",
"child_count" : 1,
"fields": [ ... ],
"features": [ ... ],
...
}
Active folders have the type
property set to active-folder
, and have the following additional properties:
Key | Type | Description |
---|---|---|
child_count |
number |
Count of immediate children |
fields |
array |
Definition of Fields |
features |
array |
Names of features enabled for folder (i.e. 'main-document' or 'revisioning') |
Field Definitions
Response fragment:
{
"fields": [{
"id": "DXSGIQ",
"name": "My string field",
"type": "string",
"description": "Description",
"initial_value": "Bla",
"mandatory": true,
"entry_title": true,
"unique": false,
"revision_field": true
}, {
"id": "D2SROA",
"name": "My number field",
"type": "numeric",
"description": "aaa",
"initial_value": 1200
}, {
"id": "M3GDCK",
"name": "My date field",
"type": "date",
"description": "Initial values is WHEN_CREATED or BLANK. It is required",
"initial_value": "WHEN_CREATED",
"mandatory": true,
"revision_field": true
}, {
"id": "ZHQQPR",
"name": "My list field",
"type": "list",
"initial_value": "123",
"options": [
"123",
"456",
"789"
],
"multiple": true,
"mandatory": true,
"read_only": true,
"revision_field": true
}, {
"id": "B9RYOA",
"name": "My rich text field",
"type": "rich_text",
"revision_field": true
}]
}
All the field definitions have the following common properties:
Key | Type | Description |
---|---|---|
type |
string |
There are 6 types listed below the table |
id |
string |
Id of field like DXSGIQ |
name |
string |
Display name |
mandatory |
boolean |
Indicates if the field is mandatory |
read_only |
boolean |
Indicates if the field value can be modified after creation |
description |
string |
Additional description |
Defining plain text fields
Field definitions with type string
have the following additional properties:
Key | Type | Description |
---|---|---|
initial_value |
string |
Initial field value like My entry field value |
entry_title |
boolean |
Indicates if the field is an entry title |
unique |
boolean |
Indicates if the entry title value should be unique within a folder |
revision_field |
boolean |
Indicates if the field configured to be used in revision process |
Defining number fields
Field definitions with type numeric
have the following additional properties:
Key | Type | Description |
---|---|---|
initial_value |
number |
Initial field value like 500 (5.00) |
entry_title |
boolean |
Indicates if the field is an entry title |
unique |
boolean |
Indicates if the entry title value should be unique within a folder |
*Important Note for number field
When sending numeric values, ensure that you send the numbers with two decimal places but without a decimal separator. For example:
- To represent
3324.00
, send332400
. - To represent
123.00
, send12300
.
Similarly, when receiving numeric values, interpret them as having two decimal places. For instance:
- Receiving
332400
should be interpreted as3324.00
. - Receiving
12300
should be interpreted as123.00
.
When fetching a numeric field, divide by 100. Similarly, when sending a numeric field, multiply by 100. This ensures consistency in data representation and prevents any misinterpretation of values.
Defining date fields
Field definitions with type date
have the following additional properties:
Key | Type | Description |
---|---|---|
initial_value |
string |
Initial field value like BLANK or WHEN_CREATED |
entry_title |
boolean |
Indicates if the field is an entry title |
unique |
boolean |
Indicates if the entry title value should be unique within a folder |
revision_field |
boolean |
Indicates if the field configured to be used in revision process |
Defining list fields
Field definitions with type list
have the following additional properties:
Key | Type | Description |
---|---|---|
initial_value |
string |
Initial field value like 123 |
options |
array |
Allowed list values like ["123", "a b c"] |
multiple |
boolean |
Indicates if the field can have multiple string values |
revision_field |
boolean |
Indicates if the field configured to be used in revision process |
Defining member fields
Field definitions with type member
have the following additional properties:
Key | Type | Description |
---|---|---|
initial_value |
object |
Initial field value, an authority type. |
limited_to |
array |
Limit possible values to the following authorities. |
multiple |
boolean |
Indicates if the field can have multiple values |
Defining autonumber fields
Field definitions with type auto-number
have no additional properties.
Autonumbers are read-only and managed by Interaxo and should not be included in the request when creating or updating entries.
Defining rich text fields
Field definitions with type rich-text
have no additional properties.
Create an active folder
Creating folders is not supported in the current version of the API. Contact Support if this is important to you.
Retrieve an active folder
To retrieve an active folder, issue a GET
request to the content item.
Update an active folder
Updating folders is not supported in the current version of the API. Contact Support if this is important to you.
Delete an active folder
To delete an active folder, issue a DELETE
request to the content item.
List children (entries)
To list children of an active folder, issue a GET
request to the content item. Children of active folders are always entries.
Active Folders with Workflow
An Active Folder with Workflow (also referred to as Workflow Folder througout the API documentation) is an Active Folder where entries are further associated with a step-based workflow. As with Active Folders, these folders may only contain Entries as children. In workflow folders Entries will also contain properties describing the step of the workflow the entries reside in.
The Workflow Folder object
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"type" : "workflow-folder",
"child_count" : 3,
"steps" : [ ... ],
"fields": [ ... ],
"features": [ ... ],
...
}
The workflow folder object has the type
parameter set to workflow-folder
and is identical to the active folder object except for the additional definitions of workflow steps:
Key | Type | Description |
---|---|---|
child_count |
number |
Count of immediate children |
fields |
array |
Definition of Fields |
steps |
array |
Definition of workflow steps |
features |
array |
Names of features enabled for folder (i.e. 'main-document' or 'revisioning') |
Step definition
Response fragment:
{
"id" : "6a6d810a-c655-4c7d-8e5f-19f63c0ed9ab",
"name" : "New",
"ordinal" : 0,
"final_step" : false
}
The step
object contain additional information relating to a workflow step, and has the following properties:
Key | Type | Description |
---|---|---|
id |
string |
UUID |
name |
string |
Display name like New |
ordinal |
number |
Sequence number starting at 0. Not in use for publish/historical steps |
final_step |
boolean |
Indicates if the step is the final step of the workflow |
publish |
boolean |
Indicates if the step is used for publishing |
historical |
boolean |
Indicates if the step is used for revision |
When referencing steps (e.g. when creating entries), only the id
property is required.
Create a workflow folder
Creating folders is not supported in the current version of the API. Contact Support if this is important to you.
Retrieve a workflow folder
To retrieve an active folder with Workflow, issue a GET
request to the content item.
Update a workflow folder
Updating folders is not supported in the current version of the API. Contact Support if this is important to you.
Delete a workflow folder
To delete an active folder with Workflow, issue a DELETE
request to the content item.
List children (entries)
To retrieve an active folder with Workflow, issue a GET
request to the content item. Child resources are all of type Entry.
Entries
Entries in Interaxo are customizable meta-data containers and may also contain file attachments as chidren.
The Entry object
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"type" : "entry",
"child_count" : 1,
...
"step": {
"id": "6a6d810a-c655-4c7d-8e5f-19f63c0ed9ab",
"name": "New"
},
"fields": [ ... ]
}
Content items with type entry
has the following additional properties:
Key | Type | Description |
---|---|---|
child_count |
number |
Count of immediate children |
fields |
array |
List of field objects |
step |
object |
Entry step with its UUID and name. No value for entry in active folder |
Response fragment:
{
"fields" : [
{
"id" : "DXSGIQ",
"type" : "string",
"name" : "My string Field",
"value" : "My entry string field value"
},
{
"id" : "D2SROA",
"type" : "numeric",
"name" : "My Numeric Field",
"value" : 123
},
{
"id" : "M3GDCK",
"type" : "date",
"name" : "My Date Field",
"value" : "2017-07-12"
},
{
"id" : "ZHQQPR",
"type" : "list",
"name" : "My List Field",
"value" : ["123", "456"]
},
{
"id" : "B9RYOA",
"type" : "rich-text",
"name" : "My Rich Text Field",
"value" : "Rich text"
},
{
"id" : "YYXL5Y",
"type" : "string",
"name" : "My Second string Field",
"value" : "My second entry string field value"
},
{
"id" : "YZBDFYD",
"type" : "member",
"name" : "My Member field",
"value" : [
{
"id": "user@example.com",
"type": "user"
},
{
"id": "1a3nc45d43d",
"type": "group",
"name": "All Participants"
}
]
},
{
"id" : "YYXL5Y",
"type" : "auto-number",
"name" : "My auto-number number Field",
"value" : "000001"
}
]
}
Each entry in the fields
collection matches the corresponding field definition of the active folder, and has the following properties:
Key | Type | Description |
---|---|---|
id |
string |
id defined in the field definition |
type |
string |
type defined in the field definition |
name |
string |
name defined in the field definition |
value |
multiple | A primitive , array or object depending on field type. |
When creating an entry, only the id
, type
, and value
properties are required. The read-only name
property is included in the response.
Create an entry
Request:
JSON_BODY='
{
"type": "entry",
"step": {
"id": "6a6d810a-c655-4c7d-8e5f-19f63c0ed9ab"
},
"fields": [
{
"id": "DXSGIQ",
"type": "string",
"value": "hello world"
},
{
"id": "M3GDCK",
"type": "date",
"value": "2017-12-23"
},
{
"id": "D2SROA",
"type": "numeric",
"value": 12000
}
]
}
'
curl -H "Content-Type: application/json" -v -d $JSON_BODY \
"https://api.interaxo.com/v1/$COMMUNITY/rooms/$ROOM/content/$ID/children" \
-H "Authorization: Bearer $TOKEN"
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"type" : "entry",
"child_count" : 1,
...
"fields": [
{
"id": "DXSGIQ",
"type": "string",
"name": "Title",
"value:": "hello world"
},
{
"id": "M3GDCK",
"type": "date",
"name": "Due date",
"value:": "2017-12-23"
},
{
"id": "D2SROA",
"type": "numeric",
"name": "Amount",
"value:": 12000
}
]
}
POST (room context)/content/{id}/children
To create an entry, issue a POST request to the content item.
Entries in Workflows are by default created in the initial step of the workflow. If the workflow configuration supports creating entries in other steps, the step
parameter can be used to specify which step the entry should be created in.
URL Parameters
Parameter | Type | Example | Description |
---|---|---|---|
id |
string |
04193719-a0... |
UUID of an active folder |
Request Body
Key | Required | Type | Description |
---|---|---|---|
type |
Yes | string | constant entry |
fields |
Yes | array | List of field values |
step |
No | object | Target workflow step. |
Response
Returns a entry object.
Retrieve an entry
To retrieve an entry, issue a GET
request to the content item.
Update an entry
Request:
JSON_BODY='
{
"type": "entry",
"fields": [
{
"id": "DXSGIQ",
"type": "string"
"value": "changed title"
}
]
}
'
curl -X PUT -H "Content-Type: application/json" -v -d $JSON_BODY \
"https://api.interaxo.com/v1/$COMMUNITY/rooms/$ROOM/content/$ID" \
-H "Authorization: Bearer $TOKEN"
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"type" : "entry",
"child_count" : 1,
...
"fields": [
{
"id": "DXSGIQ",
"type": "string",
"name": "Title",
"value:": "changed title"
}
]
}
PUT (room context)/content/{id}
To update an entry, issue a PUT request to the content item.
URL Parameters
Parameter | Type | Example | Description |
---|---|---|---|
id |
string |
04193719-a0... |
UUID of an entry |
Request Body
Key | Required | Type | Description |
---|---|---|---|
fields |
Yes | array | List of field values |
Response
Returns a entry object.
Delete an entry
To delete an entry, issue a DELETE
request to the content item.
List children (attachments)
To list children of an entry, issue a GET
request to the content item. Children of entries are always file attachments.
Move an entry between steps
Entries in Active Folders with Workflow can be moved between steps, constrained by rules defined in the workflow configuration.
Request:
## identifier of step in the given workflow
STEP_ID='7c4dd34...'
JSON_BODY="\"$ENTRY_ID\""
curl -X POST -H "Content-Type: application/json" -v -d $JSON_BODY \
"https://api.interaxo.com/v1/$COMMUNITY/rooms/$ROOM/content/$ID/steps/$STEP_ID" \
-H "Authorization: Bearer $TOKEN"
Response:
HTTP/1.1 204 No Content
POST (room context)/content/{id}/{step_id}
To move an entry, issue a POST request to the relevant step with the identifier of the entry in the body of the request.
URL Parameters
Parameter | Type | Example | Description |
---|---|---|---|
id |
string |
04193719-a0... |
UUID of an active folder |
step_id |
string |
04193719-a0... |
UUID a workflow step |
Main Document
Interaxo allows you to designate one of the attachments in an Entry as the Main Document.
Retrieve a Main Document
Request:
curl "https://api.interaxo.com/v1/$COMMUNITY/rooms/$ROOM/content/$ID/document" \
-H "Authorization: Bearer $TOKEN"
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"type" : "file",
"id" : "3ab40c92-825f-4963-aab0-32552d4696b6",
"parent_id" : "ed507f9c-8e33-4616-85be-22038cd3a3a8",
"name" : "abc.txt",
"path" : "/Collaborate/Upload/In Progress/abc.txt",
"created" : "2017-03-16T22:19:08.281Z",
"last_modified" : "2017-03-16T22:19:08.281Z",
"created_by" : {
"id" : "user@example.com"
},
"last_modified_by" : {
"id" : "user@example.com"
},
"owner" : {
"id" : "user@example.com"
},
"version" : "1.0",
"mime_type" : "text/plain",
"file_size" : 18
}
GET (room context)/content/{id}/document
To retrieve file which have been marked as Main Document of entry, issue a GET request.
URL Parameters
Parameter | Type | Example | Description |
---|---|---|---|
id |
string |
04193719-a0... |
UUID of the entry |
Response
Returns the file that is marked as the main document for the entry, otherwise a 404 Not Found
.
Assign a Main Document
Request:
JSON_BODY='
{
"id": "6a6d810a-c655-4c7d-8e5f-19f63c0ed9ab"
}
'
curl "https://api.interaxo.com/v1/$COMMUNITY/rooms/$ROOM/content/$ID/document" \
--header "Content-Type: application/json" \
--request PATCH \
--data $JSON_BODY \
-H "Authorization: Bearer $TOKEN"
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
PATCH (room context)/content/{id}/document
To (re)assign a Main Document for an entry, issue a PATCH
request specifying the identifier of the File. This must be one of the existing attachments of the entry.
URL Parameters
Parameter | Type | Example | Description |
---|---|---|---|
id |
string |
04193719-a0... |
UUID of the entry |
Request Body
Key | Required | Type | Example | Description |
---|---|---|---|---|
id |
Yes | string |
04193719-a0... |
UUID of the file |
Remove a Main Document
Request:
curl "https://api.interaxo.com/v1/$COMMUNITY/rooms/$ROOM/content/$ID/document" \
--request DELETE \
-H "Authorization: Bearer $TOKEN"
Response:
HTTP/1.1 204 No Content
Content-Type: application/json; charset=UTF-8
DELETE (room context)/content/{id}/document
To unassign the Main Document of an entry, issue a DELETE
request. The actual attachment will not be deleted, only the association marking this file as the main document.
URL Parameters
Parameter | Type | Example | Description |
---|---|---|---|
id |
string |
04193719-a0... |
UUID of the entry |
Comments
Most content items in Interaxo may contain associated rich-text comments.
Comments may be represented in either raw
or html
format. Consumers should
use html
where possible, raw
is provided and used as the default for backwards compatibility.
Mentions
Mentions are represented in html
comments using a <span>
element with a data-mentiond
attribute referring to the User.
Hello <span data-mentionid="me@example.com">Example user</span>
The Comment object
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
[
{
"content": "A <strong>comment</strong>",
"format": "html",
"created": "2017-03-16T22:19:08.281Z",
"created_by" : {
"id" : "user@example.com",
"name" : "user_name",
"type" : "user",
},
"id": "3ab40c92-825f-4963-aab0-32552d4696b2",
"modified": "2017-03-16T22:19:08.281Z",
"modified_by" : {
"id" : "user@example.com",
"name" : "user_name",
"type" : "user",
}
},
{
"content": "Another <em>comment</em>.",
"format": "html",
"created": "2017-03-16T22:19:08.281Z",
"created_by" : {
"id" : "user@example.com",
"name" : "user_name",
"type" : "user",
},
"id": "3ab40c92-825f-4963-aab0-32552d4696b5",
"modified": "2017-03-16T22:19:08.281Z",
"modified_by" : {
"id" : "user@example.com",
"name" : "user_name",
"type" : "user",
}
}
]
The comment object contain the following properties:
Key | Type | Description |
---|---|---|
id |
string |
ID of a comment |
format |
string |
Comment format, e.g. raw (default) or html |
created |
string |
ISO 8601 formatted creation datetime |
created_by |
object |
User that created the comment |
content |
string |
The rich-text comment content |
modified |
string |
ISO 8601 formatted creation datetime |
modified_by |
string |
User that updated the comment |
Create a comment
Request:
JSON_BODY='
{
"content": "A <strong>comment</strong>"
}
'
curl -H "Content-Type: application/json" -v -d $JSON_BODY \
"https://api.interaxo.com/v1/$COMMUNITY/rooms/$ROOM/content/$ID/comments" \
-H "Authorization: Bearer $TOKEN"
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"content": "A <strong>comment</strong>",
"format": "html",
"created": "2017-03-16T22:19:08.281Z",
"created_by" : {
"id" : "user@example.com"
},
"id": "3ab40c92-825f-4963-aab0-32552d4696b2",
"modified": "2017-03-16T22:19:08.281Z",
"modified_by" : {
"id" : "user@example.com",
"name" : "user_name",
"type" : "user",
}
}
POST (room context)/content/{id}/comments
To create an comment, issue a POST request to the content item.
URL Parameters
Parameter | Type | Example | Description |
---|---|---|---|
id |
string |
04193719-a0... |
UUID of an content item |
Request Body
Key | Required | Type | Description |
---|---|---|---|
content |
Yes | string | Content of the comment |
Response
Returns a comment object.
Retrieve a comment
Request:
## Identifier of relevant comment
COMMENT_ID='6c9d905...'
curl "https://api.interaxo.com/v1/$COMMUNITY/rooms/$ROOM/content/$ID/comments/$COMMENT_ID" \
-H "Authorization: Bearer $TOKEN"
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"content": "A <strong>comment</strong>",
"format": "html",
"created": "2017-03-16T22:19:08.281Z",
"created_by" : {
"id" : "user@example.com"
},
"id": "3ab40c92-825f-4963-aab0-32552d4696b2",
"modified": "2017-03-16T22:19:08.281Z",
"modified_by" : {
"id" : "user@example.com",
"name" : "user_name",
"type" : "user",
}
}
GET (room context)/content/{id}/comments/{comment_id}
To retrieve a specific comment, issue a GET request to the relevant comment resource.
URL Parameters
Parameter | Type | Example | Description |
---|---|---|---|
id |
string |
04193719-a0... |
UUID of the content item |
comment_id |
string |
04193719-a0... |
UUID of the comment |
Query Parameters
Parameter | Required | Type | Example | Description |
---|---|---|---|---|
format |
no | string |
html |
Comment format, e.g. raw (default) or html |
Response
Returns a comment object.
Update a comment
Request:
## Identifier of relevant comment
COMMENT_ID='6c9d905...'
JSON_BODY='
{
"content": "An <strong>updated comment</strong>",
"format": "html"
}
'
curl -X PUT -H "Content-Type: application/json" -v -d $JSON_BODY \
"https://api.interaxo.com/v1/$COMMUNITY/rooms/$ROOM/content/$ID/comments/$COMMENT_ID" \
-H "Authorization: Bearer $TOKEN"
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"content": "An <strong>updated comment</strong>",
"format": "html",
"created": "2017-03-16T22:19:08.281Z",
"created_by" : {
"id" : "user@example.com"
},
"id": "3ab40c92-825f-4963-aab0-32552d4696b2",
"modified": "2017-03-16T22:19:08.281Z",
"modified_by" : {
"id" : "user@example.com",
"name" : "user_name",
"type" : "user",
}
}
PUT (room context)/content/{id}/comments/{comment_id}
To update a comment, issue a PUT request to the comment resource.
URL Parameters
Parameter | Type | Example | Description |
---|---|---|---|
id |
string |
04193719-a0... |
UUID of the content item |
comment_id |
string |
04193719-a0... |
UUID of the comment |
Request Body
Key | Required | Type | Description |
---|---|---|---|
content |
Yes | string | New content of the comment |
Response
Returns a comment object.
Delete a comment
Request:
## Identifier of relevant comment
COMMENT_ID='6c9d905...'
curl -X DELETE "https://api.interaxo.com/v1/$COMMUNITY/rooms/$ROOM/content/$ID/comments/$COMMENT_ID" \
-H "Authorization: Bearer $TOKEN"
Response:
HTTP/1.1 204 No Content
DELETE (room context)/content/{id}/comments/{comment_id}
To delete a comment, issue a DELETE request to the comment resource.
List all comments
Request:
curl "https://api.interaxo.com/v1/$COMMUNITY/rooms/$ROOM/content/$ID/comments?format=html" \
-H "Authorization: Bearer $TOKEN"
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
[
{
"content": "A <strong>comment</strong>",
"format": "html",
"created": "2017-03-16T22:19:08.281Z",
"created_by" : {
"id" : "user@example.com",
"name" : "user_name",
"type" : "user",
},
"id": "3ab40c92-825f-4963-aab0-32552d4696b2",
"modified": "2017-03-16T22:19:08.281Z",
"modified_by" : {
"id" : "user@example.com",
"name" : "user_name",
"type" : "user",
}
},
{
"content": "Another <em>comment</em>.",
"format": "html",
"created": "2017-03-16T22:19:08.281Z",
"created_by" : {
"id" : "user@example.com",
"name" : "user_name",
"type" : "user",
},
"id": "3ab40c92-825f-4963-aab0-32552d4696b5",
"modified": "2017-03-16T22:19:08.281Z",
"modified_by" : {
"id" : "user@example.com",
"name" : "user_name",
"type" : "user",
}
}
]
GET (room context)/content/{id}/comments
To list comments for a content item, issue a GET request to the content resource.
URL Parameters
Parameter | Type | Example | Description |
---|---|---|---|
id |
string |
04193719-a0... |
UUID of the content item |
Query Parameters
Parameter | Required | Type | Example | Description |
---|---|---|---|---|
format |
no | string |
html |
Comment format, e.g. raw (default) or html |
Supports common collection-based query parameters for paging and sorting.
Response
Returns list of comment objects.
List all mentionable users and groups
Request:
curl "https://api.interaxo.com/v1/$COMMUNITY/rooms/$ROOM/content/$ID/comments/mentionable-authorities" \
-H "Authorization: Bearer $TOKEN"
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
[
{
"type": "group",
"id": "ef1ab8a55",
"name": "All Participants"
},
{
"type": "user",
"id": "user@example.com",
"name": "Example User"
},
{
"type": "user",
"id": "someone@example.com",
"name": "Someone Else"
}
]
GET (room context)/content/{id}/comments/mentionable-authorities
To list candidate users and/or groups that can be @
-mentioned in comments for a content item, issue a GET request to the mentionable-authorities resource, optionally specifying a search query.
URL Parameters
Parameter | Type | Example | Description |
---|---|---|---|
id |
string |
04193719-a0... |
UUID of the item you are commenting on |
Query Parameters
Parameter | Required | Type | Example | Description |
---|---|---|---|---|
type |
no | string |
user , group |
Whether you want to fetch users or groups. Valid Values are user and group . If not specified, both users and groups will be returned. |
q |
no | string |
a , Ted , John , etc |
Optionally filter the list by names containing the query search string. |
limit |
no | integer |
50 |
Use this filter if you want to limit the number of results returned. Default value is 100. |
Response
Returns list of authorities.
Room-level Jobs
The Interaxo API allows triggering background jobs in Interaxo, e.g. for exporting content to various formats.
The Room-level job object
{
"id" : "6a6d810a-c655-4c7d-8e5f-19f63c0ed9ab",
"status" : "DONE",
}
The job object contains the following properties:
Parameter | Type | Example | Description |
---|---|---|---|
id |
string |
04193719-a0... |
Job UUID |
status |
string |
IN PROGRESS |
Job status |
Room-level Job statuses:
Key | Description |
---|---|
PENDING |
job has been started |
IN_PROGRESS |
job in progress |
DONE |
job completed |
CANCELLED |
job was cancelled |
Query the status of a Room-level Job
Request:
curl "https://api.interaxo.com/v1/$COMMUNITY/rooms/$ROOM/jobs/$ID" \
-H "Authorization: Bearer $TOKEN"
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"id" : "1a1d810a-c155-4c7d-8e5f-19f13c0ed9ab",
"status" : "DONE",
}
GET (room context)/jobs/{id}
Retrieves a Room-level job. Useful to check its status.
URL Parameters
Parameter | Type | Example | Description |
---|---|---|---|
id |
string |
04193719-a0... |
Job UUID |
Exporting entries
POST (room context)/jobs/content-exports
Interaxo allows exporting complete active folders, individual steps and selected entries to CSV.
Supported export formats:
Key | Description |
---|---|
excel |
Export to CSV/excel |
Request:
JSON_BODY='
{
"format" : "excel",
"item_ids" : [
"6a6d810a-c655-4c7d-8e5f-19f63c0ed9ab"
],
"fields" : [
{
"id" : "DXSGIQ",
"title" : "Text"
}
]
}
'
curl -H "Content-Type: application/json" -v -d $JSON_BODY \
"https://api.interaxo.com/v1/$COMMUNITY/rooms/$ROOM/jobs/content-exports" \
-H "Authorization: Bearer $TOKEN"
Response:
HTTP/1.1 201 CREATED
Content-Type: application/json; charset=UTF-8
Location: https://api.interaxo.com/v1/$COMMUNITY/rooms/$ROOM/jobs/$ID
{
"id" : "1a1d810a-c155-4c7d-8e5f-19f13c0ed9ab",
"status" : "PENDING",
}
Request Body
Key | Required | Type | Description |
---|---|---|---|
format |
Yes | string |
Export format |
fields |
Yes | array |
List of fields objects |
item_ids |
Yes | array |
List of content ids to export |
Export field:
Key | Required | Type | Description |
---|---|---|---|
id |
Yes | string |
Id of field like DXSGIQ |
title |
No | array |
Display name |
Response
Returns a Room-level job object.
To retrieve an export file, issue a GET
request to download file using the id
of the job as the content id. This can only be done when the job has the status DONE
Jobs
The Interaxo API allows triggering asynchronous jobs in Interaxo.
For legacy room-related jobs, see Room-level Jobs
List of Supported Jobs
Type ID | Permission | Description |
---|---|---|
room-archive |
create:jobs:room-archive |
Export of complete Rooms |
The Job object
{
"id" : "6a6d810a-c655-4c7d-8e5f-19f63c0ed9ab",
"status" : "done",
"notify_email": "me@example.com",
// Additional job-specific properties
}
The Job object contains the following properties:
Parameter | Type | Example | Description |
---|---|---|---|
type |
string |
room-archive |
Type of Job |
id |
string |
04193719-a0... |
Job id |
status |
string |
in_progress |
Job status |
notify_email |
string |
me@example.com |
Email address to notify on Job status changes |
notify_webhook |
string |
https://example.com |
Webhook to notify on Job status changes |
Job statuses:
Key | Description |
---|---|
pending |
job has been accepted but has not started |
in_progress |
job is in progress |
done |
job has completed successfully |
cancelled |
job was cancelled |
failed |
job has failed. |
Query the status of a Job
Request:
curl "https://api.interaxo.com/v1/$COMMUNITY/jobs/$ID" \
-H "Authorization: Bearer $TOKEN"
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"id" : "1a1d810a-c155-4c7d-8e5f-19f13c0ed9ab",
"status" : "done",
"notify_email": "me@example.com",
// Additional job-specific properties
}
GET (community context)/jobs/{id}
Retrieves a job. Useful to check its status.
URL Parameters
Parameter | Type | Example | Description |
---|---|---|---|
id |
string |
04193719-a0... |
Job id |
Cancel a Job
Request:
curl -X DELETE "https://api.interaxo.com/v1/$COMMUNITY/jobs/$ID" \
-H "Authorization: Bearer $TOKEN"
Response:
HTTP/1.1 202 ACCEPTED
DELETE (community context)/jobs/{id}
Aborts a pending job.
URL Parameters
Parameter | Type | Example | Description |
---|---|---|---|
id |
string |
04193719-a0... |
Job id |
Room Exports
POST (community context)/jobs
Interaxo allows exporting complete rooms to zip-archives.
Requesting an Export
Request:
JSON_BODY='
{
"type" : "room-archive",
"room_id" : "some-room-id",
"notify_email: "me@example.com"
}
'
curl -H "Content-Type: application/json" -v -d $JSON_BODY \
"https://api.interaxo.com/v1/$COMMUNITY/jobs" \
-H "Authorization: Bearer $TOKEN"
Response:
HTTP/1.1 201 CREATED
Content-Type: application/json; charset=UTF-8
Location: https://api.interaxo.com/v1/$COMMUNITY/jobs/$ID
{
"type" : "room-archive",
"id" : "1a1d810a-c155-4c7d-8e5f-19f13c0ed9ab",
"status" : "pending",
"notify_email": "me@example.com"
}
The following parameters are available, in addition to the common Job parameters.
Key | Required | Type | Description |
---|---|---|---|
room_id |
Yes | string |
ID of Room to export |
Returns a job object.
Retreiving the export archive
Request:
curl "https://api.interaxo.com/v1/$COMMUNITY/jobs/$ID" \
-H "Authorization: Bearer $TOKEN"
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"id" : "1a1d810a-c155-4c7d-8e5f-19f13c0ed9ab",
"status" : "done",
"notify_email": "me@example.com",
"download_url": "https://example.com/export-123.zip"
// Additional job-specific properties
}
When a job has completed successfully, a download_url
will be presented in the response for the Job object.
Support
For any queries relating to the Interaxo API please contact the Interaxo support center.
Symetri Collaboration can provide assistance through the whole lifecycle of integrating with Interaxo, including advisory and consulting services.