This API is in an experimental / beta phase and as such is subject to change without warning.
We welcome your feedback – please Contact us if you have any.
With version 6.5 we added a (experimental) JSON API, which allows you to give an external system read-only access to your CATMA project data for a limited time.
You will find a menu option in the three-dot menu of the project module, as shown below:
On selecting this option a dialog will open explaining some details. Once you click the button to enable the API for a project, a unique API URL will be generated for you. This URL will work until you close the project or until your CATMA session ends, whichever occurs first (your session ends when you log out, or automatically after some period of inactivity).
Getting Started and Authentication
The API currently only accepts GET requests and does not support any kind of filtering or other query parameters.
Because of how the URL is tied to your session, no authentication is currently required to use the API. However, please note that this may change in future.
Sample Response and Data Structure
Below you can see what a response from the API might look like. You can also download this sample response as a JSON file here (right-click to download).
You will find a description of the different elements below the sample.
{
"exportId": "E_167025E1-42F6-4BD1-8E16-0D5D0760982C",
"documents": [
{
"sourceDocument": {
"id": "D_C64DD6D5-491F-4DD0-AA2F-9FCE27BFE265",
"bodyUrl": "https://app.catma.de/catma/xyz",
"crc32bChecksum": "ABCD1234",
"size": 168184,
"title": "Alice's Adventures in Wonderland"
},
"tags": [
{
"id": "CATMA_AF04D847-B1F0-4D3E-8D8B-9E33DB91F180",
"parentId": "",
"name": "character",
"colour": "#2C907F",
"properties": [
{
"id": "CATMA_40F3D04A-E932-4557-942C-DCE731E466C2",
"name": "gender",
"possibleValues": ["m", "f", "unknown"]
}
]
},
{
"id": "CATMA_E1B53E2E-1223-4EB3-8410-FDD844C52A4D",
"parentId": "",
"name": "character-trait",
"colour": "#FFFC5A",
"properties": []
}
],
"annotations": [
{
"id": "CATMA_3545DD7C-2C52-41FF-BCA4-7B1EF9BC6423",
"sourceDocumentId": "D_C64DD6D5-491F-4DD0-AA2F-9FCE27BFE265",
"startOffset": 1529,
"endOffset": 1534,
"phrase": "Alice",
"tagId": "CATMA_AF04D847-B1F0-4D3E-8D8B-9E33DB91F180",
"tagName": "character",
"properties": [
{
"id": "CATMA_40F3D04A-E932-4557-942C-DCE731E466C2",
"name": "gender",
"values": [
"f"
]
}
]
},
{
"id": "CATMA_CA94366F-CAB5-47B4-AF8C-F33EA199C8AA",
"sourceDocumentId": "D_C64DD6D5-491F-4DD0-AA2F-9FCE27BFE265",
"startOffset": 1585,
"endOffset": 1591,
"phrase": "sister",
"tagId": "CATMA_AF04D847-B1F0-4D3E-8D8B-9E33DB91F180",
"tagName": "character",
"properties": [
{
"id": "CATMA_40F3D04A-E932-4557-942C-DCE731E466C2",
"name": "gender",
"values": [
"f"
]
}
]
},
{
"id": "CATMA_8AB04E00-BF62-4FDB-B01D-6E083646EAC5",
"sourceDocumentId": "D_C64DD6D5-491F-4DD0-AA2F-9FCE27BFE265",
"startOffset": 1683,
"endOffset": 1689,
"phrase": "sister",
"tagId": "CATMA_AF04D847-B1F0-4D3E-8D8B-9E33DB91F180",
"tagName": "character",
"properties": [
{
"id": "CATMA_40F3D04A-E932-4557-942C-DCE731E466C2",
"name": "gender",
"values": [
"f"
]
}
]
},
{
"id": "CATMA_21F4631E-A95F-4250-9E2E-D409DBEA0096",
"sourceDocumentId": "D_C64DD6D5-491F-4DD0-AA2F-9FCE27BFE265",
"startOffset": 1792,
"endOffset": 1797,
"phrase": "Alice",
"tagId": "CATMA_AF04D847-B1F0-4D3E-8D8B-9E33DB91F180",
"tagName": "character",
"properties": [
{
"id": "CATMA_40F3D04A-E932-4557-942C-DCE731E466C2",
"name": "gender",
"values": [
"f"
]
}
]
},
{
"id": "CATMA_B1CC0D5C-7CD3-4456-AD28-DAD3A41D88EB",
"sourceDocumentId": "D_C64DD6D5-491F-4DD0-AA2F-9FCE27BFE265",
"startOffset": 2086,
"endOffset": 2098,
"phrase": "White Rabbit",
"tagId": "CATMA_AF04D847-B1F0-4D3E-8D8B-9E33DB91F180",
"tagName": "character",
"properties": [
{
"id": "CATMA_40F3D04A-E932-4557-942C-DCE731E466C2",
"name": "gender",
"values": [
"unknown"
]
}
]
},
{
"id": "CATMA_72A4136D-939D-4AF2-8DB4-60C5E4A5F85D",
"sourceDocumentId": "D_C64DD6D5-491F-4DD0-AA2F-9FCE27BFE265",
"startOffset": 2749,
"endOffset": 2758,
"phrase": "curiosity",
"tagId": "CATMA_E1B53E2E-1223-4EB3-8410-FDD844C52A4D",
"tagName": "character-trait",
"properties": []
}
]
}
]
}Following is a description of the different elements:
exportId: A unique ID for the response (as returned data may be different for each request).
documents: An array that contains an entry for each document in your project.
sourceDocument: Contains information about the particular document:
id: The unique ID of the document.
bodyUrl: A URL which can be used to retrieve the document body/text.
crc32bChecksum: A CRC32B checksum that can be used to verify that the document body/text retrieved
via the bodyUrl was not corrupted during transfer.
size: The size of the document in bytes.
title: The title of the document.
tags: An array that contains an entry for each tag that was used to annotate the document:
id: The unique ID of the tag.
parentId: The unique ID of this tag's parent tag, if any. Null or empty means this is a top level tag.
This can be used to reconstruct the tag hierarchy if desired.
name: The name of the tag.
colour: The colour of the tag in HTML/hex notation.
properties: An array that contains an entry for each property of the tag:
id: The unique ID of the property.
name: The name of the property.
possibleValues: An array containing pre-defined possible values for the property.
Note that actual values are not constrained to this list.
annotations: An array that contains an entry for each annotation on the document:
id: The unique ID of the annotation.
sourceDocumentId: The unique ID of the document that the annotation relates to.
startOffset: The starting character offset of the annotation.
endOffset: The ending character offset of the annotation.
phrase: The actual text segment that was annotated.
tagId: The unique ID of the tag that the annotation relates to.
tagName: The name of the tag that the annotation relates to.
properties: An array that contains an entry for each property of the annotation:
id: The unique ID of the property.
name: The name of the property.
values: An array containing actual values for the property.
Some information is not returned by the API (may change in future). This includes:
- Information about tagsets or annotation collections and how tags and annotations respectively relate to these.
- Authorship and timestamp metadata (including system properties other than colour).
The data structure is purposefully relatively flat, trading some data repetition for the benefit of not having to do referential lookups often. This repetition will be particularly evident with the tags, when a project contains multiple documents that have been annotated using the same tagset(s) and tags.
