Introduction
Learn how to use CATMA’s public JSON API. This API allows you to give an external system read-only access to your CATMA project data for a limited time.
Please ensure that you have read and understood the relevant sections of our Privacy Policy and Terms of Use, in particular the sections relating to “allowing other systems/tools to access data”.
Contact us if you have any questions related to the use of this API.
Getting Started
The base-URL for the API is: https://app.catma.de/api/v1
We publish an OpenAPI definition at https://app.catma.de/api/v1/openapi.[json|yaml]
You can explore the API using our self-hosted Swagger UI. Alternatively we have also published a public Postman collection:
Endpoints Table
| HTTP Method | Endpoint Path (<path parameters> are always required) | Headers | Form Parameters (URL-encoded form submission; non-alphanumeric characters in both keys and values must be percent-encoded) | Query Parameters (optional URL parameters; non-alphanumeric characters in both keys and values must be percent-encoded) |
|---|---|---|---|---|
| POST | /auth | Authorization: “Bearer <CATMA access token>” or Authorization: “Basic <base64-encoded username:password>” (example) Content-Type: “application/x-www-form-urlencoded” (always required) | access_token or (username and password) (required if no ‘Authorization’ header is supplied) | |
| GET | /auth/google | |||
| GET | /projects | Authorization: “Bearer <JWT received from /auth>” | ||
| GET | /projects/<namespace>/<project_id>/export | as above | includeExtendedMetadata (boolean) page (int) pageSize (int) forcePull (boolean) | |
| GET | /projects/<namespace>/<project_id>/export/doc/<document_id> | as above |
Step 1 – Authentication
You can authenticate with:
- a CATMA access token
- your CATMA username and password
- your Google account*
For options 1 and 2, make a POST request to /auth and supply credentials using either the ‘Authorization’ header or form parameters (see the exploration options or the table above for further details). For option 3, make a GET request to /auth/google.
A JWT (JSON Web Token) is returned upon successful authentication. This is a short-lived token that should be used to authenticate requests to any of the other, non-authentication endpoints (using the ‘Authorization’ header).
Currently, no token refresh mechanism has been implemented. Simply re-authenticate if the token has expired.
*Only use this if you log in to CATMA using the ‘Sign in with Google’ option. A browser is required to complete the OAuth flow. Responds with a 307 redirect and a URL in the ‘Location’ header that you must visit in your browser. As with the other options, a JWT is returned upon successful authentication.
Step 2 – List the projects you have access to
Make a GET request to /projects to list the projects that you have access to, together with all information that is required to export data from your projects.
Step 3 – Export project data
Make a GET request to /projects/<namespace>/<project_id>/export to export project data.
Required path parameters:
- namespace: a username, as projects are always owned by a particular user
- project_id: use the
/projectsendpoint (step 2) to list available projects with their namespace and ID
Optional query parameters:
- includeExtendedMetadata (boolean)
- page (int)
- pageSize (int)
- forcePull (boolean)
Output is paginated and pageSize defaults to 100 (the no. of annotations returned per page). Links to previous and next pages are also returned. Extended metadata is only returned with the first page by default, unless specified with includeExtendedMetadata=true. Use forcePull=true to force the server to update its copy of the project.
Retrieving document content
Make a GET request to /projects/<namespace>/<project_id>/export/doc/<document_id> to fetch the plain text content of a particular document.
Required path parameters are the same as for the project export request above, with the addition of:
- document_id: you will find this in the output of the project export request
Note that the extended metadata for each document (see the project export request) includes a bodyUrl, so you should not need to ‘manually’ construct the URL to retrieve document content in your own code.
Sample Response and Data Structure
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.
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.
Sample Response
{
"exportId": "E_167025E1-42F6-4BD1-8E16-0D5D0760982C",
"exportCreatedAt": "2025-05-20T18:04:27.8406849+02:00",
"totalPages": 1,
"pageNo": 1,
"pageSize": 100,
"prevPage": null,
"nextPage": null,
"extendedMetadata": {
"documents": {
"D_C64DD6D5-491F-4DD0-AA2F-9FCE27BFE265": {
"id": "D_C64DD6D5-491F-4DD0-AA2F-9FCE27BFE265",
"author": null,
"description": null,
"publisher": null,
"title": "Alice's Adventures in Wonderland",
"bodyUrl": "https://app.catma.de/api/v1/projects/dummyUser/CATMA_B5BDABFB-D5DB-41A7-928F-E1E74363C703_Alice_in_Wonderland/export/doc/D_C64DD6D5-491F-4DD0-AA2F-9FCE27BFE265",
"crc32bChecksum": "8bbfc3f6",
"size": 174691,
"responsibleUser": "dummyUser"
}
},
"annotationCollections": {
"C_7A377EF2-068D-46D8-98EE-0F31EBD48BE0": {
"id": "C_7A377EF2-068D-46D8-98EE-0F31EBD48BE0",
"author": null,
"description": null,
"publisher": null,
"name": "Alice's Adventures in Wonderland Default Annotations",
"responsibleUser": "dummyUser",
"documentId": "D_C64DD6D5-491F-4DD0-AA2F-9FCE27BFE265"
}
},
"tagsets": {
"T_CE049907-661B-42FE-A478-50ED12E9F728": {
"id": "T_CE049907-661B-42FE-A478-50ED12E9F728",
"name": "Test Tagset",
"description": null,
"responsibleUser": "dummyUser"
}
},
"tags": {
"CATMA_AF04D847-B1F0-4D3E-8D8B-9E33DB91F180": {
"id": "CATMA_AF04D847-B1F0-4D3E-8D8B-9E33DB91F180",
"parentId": "",
"name": "character",
"properties": {
"system": {
"color": "#2c907f",
"author": "dummyUser"
},
"user": {
"CATMA_40F3D04A-E932-4557-942C-DCE731E466C2": {
"id": "CATMA_40F3D04A-E932-4557-942C-DCE731E466C2",
"name": "gender",
"possibleValues": ["m", "f", "other", "unknown"]
}
}
},
"tagsetId": "T_CE049907-661B-42FE-A478-50ED12E9F728"
},
"CATMA_E1B53E2E-1223-4EB3-8410-FDD844C52A4D": {
"id": "CATMA_E1B53E2E-1223-4EB3-8410-FDD844C52A4D",
"parentId": "",
"name": "character-trait",
"properties": {
"system": {
"color": "#fffc5a",
"author": "dummyUser"
},
"user": {}
},
"tagsetId": "T_CE049907-661B-42FE-A478-50ED12E9F728"
}
}
},
"documents": [
{
"id": "D_C64DD6D5-491F-4DD0-AA2F-9FCE27BFE265",
"title": "Alice's Adventures in Wonderland",
"annotations": [
{
"id": "CATMA_3545DD7C-2C52-41FF-BCA4-7B1EF9BC6423",
"phrases": [
{
"startOffset": 1529,
"endOffset": 1534,
"phrase": "Alice"
}
],
"annotationCollectionId": "C_7A377EF2-068D-46D8-98EE-0F31EBD48BE0",
"annotationCollectionName": "Alice's Adventures in Wonderland Default Annotations",
"tagId": "CATMA_AF04D847-B1F0-4D3E-8D8B-9E33DB91F180",
"tagName": "character",
"tagColor": "#2c907f",
"tagPath": "/character",
"author": "dummyUser",
"createdAt": "2023-06-12T14:35:29.564+02:00",
"userProperties": [
{
"id": "CATMA_40F3D04A-E932-4557-942C-DCE731E466C2",
"name": "gender",
"values": ["f"]
}
]
},
{
"id": "CATMA_CA94366F-CAB5-47B4-AF8C-F33EA199C8AA",
"phrases": [
{
"startOffset": 1585,
"endOffset": 1591,
"phrase": "sister"
}
],
"annotationCollectionId": "C_7A377EF2-068D-46D8-98EE-0F31EBD48BE0",
"annotationCollectionName": "Alice's Adventures in Wonderland Default Annotations",
"tagId": "CATMA_AF04D847-B1F0-4D3E-8D8B-9E33DB91F180",
"tagName": "character",
"tagColor": "#2c907f",
"tagPath": "/character",
"author": "dummyUser",
"createdAt": "2023-06-12T14:35:31.221+02:00",
"userProperties": [
{
"id": "CATMA_40F3D04A-E932-4557-942C-DCE731E466C2",
"name": "gender",
"values": ["f"]
}
]
},
{
"id": "CATMA_8AB04E00-BF62-4FDB-B01D-6E083646EAC5",
"phrases": [
{
"startOffset": 1683,
"endOffset": 1689,
"phrase": "sister"
}
],
"annotationCollectionId": "C_7A377EF2-068D-46D8-98EE-0F31EBD48BE0",
"annotationCollectionName": "Alice's Adventures in Wonderland Default Annotations",
"tagId": "CATMA_AF04D847-B1F0-4D3E-8D8B-9E33DB91F180",
"tagName": "character",
"tagColor": "#2c907f",
"tagPath": "/character",
"author": "dummyUser",
"createdAt": "2023-06-12T14:35:33.729+02:00",
"userProperties": [
{
"id": "CATMA_40F3D04A-E932-4557-942C-DCE731E466C2",
"name": "gender",
"values": ["f"]
}
]
},
{
"id": "CATMA_21F4631E-A95F-4250-9E2E-D409DBEA0096",
"phrases": [
{
"startOffset": 1792,
"endOffset": 1797,
"phrase": "Alice"
}
],
"annotationCollectionId": "C_7A377EF2-068D-46D8-98EE-0F31EBD48BE0",
"annotationCollectionName": "Alice's Adventures in Wonderland Default Annotations",
"tagId": "CATMA_AF04D847-B1F0-4D3E-8D8B-9E33DB91F180",
"tagName": "character",
"tagColor": "#2c907f",
"tagPath": "/character",
"author": "dummyUser",
"createdAt": "2023-06-12T14:35:35.114+02:00",
"userProperties": [
{
"id": "CATMA_40F3D04A-E932-4557-942C-DCE731E466C2",
"name": "gender",
"values": ["f"]
}
]
},
{
"id": "CATMA_B1CC0D5C-7CD3-4456-AD28-DAD3A41D88EB",
"phrases": [
{
"startOffset": 2086,
"endOffset": 2098,
"phrase": "White Rabbit"
}
],
"annotationCollectionId": "C_7A377EF2-068D-46D8-98EE-0F31EBD48BE0",
"annotationCollectionName": "Alice's Adventures in Wonderland Default Annotations",
"tagId": "CATMA_AF04D847-B1F0-4D3E-8D8B-9E33DB91F180",
"tagName": "character",
"tagColor": "#2c907f",
"tagPath": "/character",
"author": "dummyUser",
"createdAt": "2023-06-12T14:35:38.829+02:00",
"userProperties": [
{
"id": "CATMA_40F3D04A-E932-4557-942C-DCE731E466C2",
"name": "gender",
"values": ["unknown"]
}
]
},
{
"id": "CATMA_72A4136D-939D-4AF2-8DB4-60C5E4A5F85D",
"phrases": [
{
"startOffset": 2749,
"endOffset": 2758,
"phrase": "curiosity"
}
],
"annotationCollectionId": "C_7A377EF2-068D-46D8-98EE-0F31EBD48BE0",
"annotationCollectionName": "Alice's Adventures in Wonderland Default Annotations",
"tagId": "CATMA_E1B53E2E-1223-4EB3-8410-FDD844C52A4D",
"tagName": "character-trait",
"tagColor": "#fffc5a",
"tagPath": "/character-trait",
"author": "dummyUser",
"createdAt": "2023-06-12T14:35:45.649+02:00",
"userProperties": []
}
]
}
]
}Description of Elements
exportId: A unique ID for the response (as returned data may be different for each request).
exportCreatedAt: The date and time at which the data was exported in ISO 8601 format.
totalPages: As output is paginated, this is the total no. of pages given the current page size.
pageNo: The current page number returned (request parameter).
pageSize: The current page size (request parameter).
prevPage: The URL to fetch the previous page.
nextPage: The URL to fetch the next page.
extendedMetadata: Contains information about the resources included in the export:
documents: An object keyed by document ID, the values representing a particular document:
id: The unique ID of the document.
author: The author of the text.
description: The description of the text.
publisher: The publisher of the text.
title: The title 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.
responsibleUser: The user marked as being responsible for the resource.
annotationCollections: An object keyed by annotation collection ID, the values representing a particular collection:
id: The unique ID of the annotation collection.
author: The author of the annotation collection.
description: The description of the annotation collection.
publisher: The publisher of the annotation collection.
name: The name of the annotation collection.
responsibleUser: The user marked as being responsible for the resource.
documentId: The ID of the document to which the annotation collection belongs.
tagsets: An object keyed by tagset ID, the values representing a particular tagset:
id: The unique ID of the tagset.
name: The name of the tagset.
description: The description of the tagset.
responsibleUser: The user marked as being responsible for the resource.
tags: An object keyed by tag ID, the values representing a particular tag:
id: The unique ID of the tag.
parentId: The unique ID of the tag's parent tag, if any. Null or empty means it is a top level tag.
This can be used to reconstruct the tag hierarchy if desired.
name: The name of the tag.
properties: An object with keys 'system' and 'user':
system: An object representing the standard system properties:
color: The color of the tag in HTML/hex notation.
author: The author of the tag.
user: An object keyed by property ID, the values representing a particular user-defined property:
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.
tagsetId: The ID of the tagset to which the tag belongs.
documents: An array that contains an entry for each document for which annotations are being returned
as part of the current page of results (pagination is based on annotations):
id: The unique ID of the document.
title: The title of the document.
annotations: An array that contains an entry for each annotation associated with the document.
May contain all or only some annotations (depending on pagination):
id: The unique ID of the annotation.
phrases: An array that contains an entry for each phrase/text-segment that forms part of the annotation.
Will contain multiple entries for discontinuous annotations:
startOffset: The starting character offset of the phrase.
endOffset: The ending character offset of the phrase.
phrase: The actual text-segment that was annotated.
annotationCollectionId: The ID of the annotation collection to which the annotation belongs.
annotationCollectionName: The name of the annotation collection to which the annotation belongs.
tagId: The ID of the tag that was used for the annotation.
tagName: The name of the tag that was used for the annotation.
tagColor: The color of the tag that was used for the annotation in HTML/hex notation.
tagPath: The complete path of the tag that was used for the annotation.
author: The author of the annotation.
createdAt: The date and time at which the annotation was created in ISO 8601 format.
userProperties: An array that contains an entry for each user-defined property of the tag that was used for the annotation:
id: The unique ID of the property.
name: The name of the property.
values: An array containing the values that have been defined for the property for the particular annotation.
