Rest API (JSON)
This page describes the steps you need to take to integrate with the standard Metamaze API. This page serves as a tutorial.
Last updated
This page describes the steps you need to take to integrate with the standard Metamaze API. This page serves as a tutorial.
Last updated
This page describes the steps you need to take to integrate with the standard Metamaze API. This page serves as a tutorial. Connection through the API of Metamaze is possible via token authentication or mutual TLS certification. For technical details on how to implement it, see the Metamaze API documentation.
For this tutorial, we will use Postman to perform the API request.
Create (or refresh) a new Bearer token by clicking the two blue arrows
Copy the Bearer token and store it for later use
Click Save to store the generated Bearer token
You can find the organisationId and projectId in the URL of e.g. the project settings:
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
In Postman, create a new request.
Change the type from GET to POST
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.
Under the Authorization tab, choose Bearer Token as the type. Fill in the generated Bearer Token from Step 1.
Under Body, change the type to raw and select JSON as the body format.
Add the following request body where you replace {{base64 encoded file}} with the output from Step 3. You can add optional metadata too
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: you will need it to fetch the status and the results
In Postman, create a new request.
Set the request type as GET now.
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.
As above, add the Bearer Token authentication.
Click Send to send the request and fetch the results.
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.
In the tutorial above, authentication was with a Bearer token. You might want to consider to add certificate-based authentication for an additional layer of security.
This guide provides step-by-step instructions on generating certificates using SSL for secure communication with Metamaze using mutual TLS (mTLS).
To generate a key and a CSR, please follow the command given below:
Keep your client.key file private and protected.
After generating a CSR, you can open a support ticket via the information provided on Getting support. In that support ticket, include the client.csr file as an attachment and ask to sign it.
After verifying your information, Metamaze will sign the CSR and provide you with a signed certificate.
For reference, we will use a command similar to:
After generating the client.crt file, you can paste the content of it in the Metamaze project settings > Input > REST API. The certificate should have the following structure:
To configure Postman correctly with mTLS, follow these steps:
In Postman, navigate to Settings > Certificates and click "Add Certificate"
Enter the following information
Add HOST *.metamaze.eu
Add CRT file client.crt that was provided by Metamaze
Add your KEY file client.key
Leave PFX file empty
(Optional) If you set a passphrase when generating the key, add the passphrase here too.
Postman automatically looks at the hostname of every API call to decide if client authentication is needed. By adding the host *.metamaze.eu, all API calls will be covered.
For testing purposes, we provide an endpoint at app.metamaze.eu/test-sslthat you can use. When sending a POST request to that endpoint with an empty body, you should receive a response similar to
At the end of the process, you will have the following files:
client.csr (not needed anymore, it was used for step 2 only)
client.key (use this to sign the request to Metamaze, keep this private)
client.crt (used to validate the request in Metamaze, to be pasted in the project settings.)
Please note that both the client.key and client.crt files are necessary for secure communication with Metamaze and should be kept securely.
Note that self-signed certificates are not supported. Certificates for client authentication using mTLS must be signed by the Metamaze Certificate Authority.
