API integration

This page describes the steps you need to take to integrate with the standard Metamaze API. This page serves as a tutorial.

This page describes the steps you need to take to integrate with the standard Metamaze API. This page serves as a tutorial. The full documentation and contract can be found at https://app.metamaze.eu/docs/index.html

For this tutorial, we will use Postman to perform the API request.

Step 1: Configure the input API and get a Bearer token

  1. Go to Project Settings of your project using the navigation side bar.

  2. In the Project Settings, open the Setup Input / Output modal to configure the API

Opening Setup Input / Output modal in the project settings

3. In the Input settings modal

a. Enable input by clicking the toggle and switching it to on.

b. Create (or refresh) a new Bearer token by clicking the two blue arrows.

c. Copy the Bearer token and stored it for later use.

d. Click Save to store the generated Bearer token.

Input settings modal

Step 2: Find your organisationId and projectId

You can find the organisationId and projectId in the URL of e.g. the project settings:

Url parameters organisationId and projectId

Step 3: Base64 encode your document

To add documents to your JSON API request, you need to base64 encode them. In Linux and on Mac OS X, you can just run

> base64 <inputfile>

Tip: to immediately copy the base64 encoded file to your clipboard you can use > base64 <inputfile> | pbcopy

Step 4: Create your request to start processing

In Postman, create a new request.

  1. Change the type from GET to POST

  2. Set the request URL to https://app.metamaze.eu/gql/api/organisations/{{organisationId}}/projects/{{projectId}}/process where {{organisationId}} and {{projectId}} are the values from Step 2.

  3. Under the Authorization tab, choose Bearer Token as the type. Fill in the generated Bearer Token from Step 1.

  4. Under Body, change the type to raw and select JSON as the body format.

  5. Add the following request body where you replace {{base64 encoded file}} with the output from Step 3. You can add optional metadata too

"files": [
"name": "mm-api-example.pdf",
"id": "mm-api-example",
"file": "{{base64 encoded file}}"
"metadata": {"example-key": "example-value"}

In Postman, you can click "Code" (top-right, under the Send and Save buttons) to quickly export your API call to the most popular programming languages immediately.

6. Click Send to send the request. You will receive a response like this with status code 200. Store the uploadId: we will need it to fetch the status and the results

Step 5: Create a new request to fetch the results

In Postman, create a new request.

  1. Keep the request type as GET now.

  2. Set the request URL to https://app.metamaze.eu/gql/api/organisations/{{organisationId}}/projects/{{projectId}}/process/{{uploadId}} where {{organisationId}} and {{projectId}} are the values from Step 2, and {{uploadId}} is the ID you received in the response of Step 4.

  3. As above, add the Bearer Token authentication.

  4. Click Send to send the request and fetch the results.

  5. You will find the extracted values under documents[].aggregatedEntities.


In this tutorial, we showed the easiest way to integrate Metamaze. For other topics like receiving results immediately (push instead of pull), advanced authentication, restricting document types, uploading training data or adding metadata you can find information in.the full API documentation.