# 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. 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](https://app.metamaze.eu/docs/index.html). For this tutorial, we will use [Postman](https://www.postman.com/) to perform the API request. ![](/files/UN135dEJgpv1Rm3LSJ14) ## API integration using token authentication ### Step 1: Configure the input API and get a Bearer token 1. Create (or refresh) a new Bearer token by clicking the two blue arrows 2. Copy the Bearer token and store it for later use 3. Click Save to store the generated Bearer token ### 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](/files/-MhHxSwhLV_hrTSwsT6I) ### 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 ` {% hint style="info" %} Tip: to immediately copy the base64 encoded file to your clipboard you can use \ `> base64 | pbcopy` {% endhint %} ### 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](https://app.metamaze.eu/gql/api/organisations/{{organisationId}}/projects/{{projectId}}/upload) 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"} } ``` {% hint style="info" %} 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. {% endhint %} 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 ![](/files/-MhI3myKt4JcukWLtzp0) ### Step 5: Create a new request to fetch the results In Postman, create a new request. 1. Set the request type as GET now. 2. Set the request URL to [https://app.metamaze.eu/gql/api/organisations/{{organisationId}}/projects/{{projectId}}/process/{{uploadId}}](https://app.metamaze.eu/gql/api/organisations/{{organisationId}}/projects/{{projectId}}/process/611b63f7b722892f406b5b95) 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`. ### Summary 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](https://app.metamaze.eu/docs/index.html). ## Generating certificates for requests to Metamaze with mTLS 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). ### Step 1: Generating a key and a Certificate Signing Request (CSR) To generate a key and a CSR, please follow the command given below: {% code overflow="wrap" %} ``` openssl req -new -newkey rsa:4096 -keyout client.key -out client.csr -nodes -subj '/CN=*.metamaze.eu' ``` {% endcode %} Keep your `client.key` file private and protected. ### Step 2: Send the CSR to Metamaze Support to sign with our CA After generating a CSR, you can [open a support ticket ](/getting-support.md)via the information provided on [Getting support](/getting-support.md). 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: {% code overflow="wrap" %} ``` openssl x509 -req -sha256 -days 365 -in client.csr -CA mm_ca.crt -CAkey mm_ca.key -set_serial 02 -out client.crt ``` {% endcode %} ### Step 3: Add the certificate content to Metamaze 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: {% code overflow="wrap" %} ``` ---BEGIN CERTIFICATE--- ... ---END CERTIFICATE--- ``` {% endcode %} ### ### Step 4: Test API calls in Postman To configure Postman correctly with mTLS, follow these steps: In Postman, navigate to Settings > Certificates and click "Add Certificate"
Enter the following information 1. Add HOST `*.metamaze.eu` 2. Add CRT file `client.crt` that was provided by Metamaze 3. Add your KEY file `client.key` 4. Leave PFX file empty 5. (Optional) If you set a passphrase when generating the key, add the passphrase here too. {% hint style="info" %} 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. {% endhint %} For testing purposes, we provide an endpoint at `app.metamaze.eu/test-ssl`that you can use. When sending a POST request to that endpoint with an empty body, you should receive a response similar to ``` Fingerprint: [the sha1 fingerprint of certificate] Verified: SUCCESS Subject: CN=*.metamaze.eu ``` ### ### Overview of files 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. {% hint style="info" %} Note that self-signed certificates are not supported. Certificates for client authentication using mTLS must be signed by the Metamaze Certificate Authority. {% endhint %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs-old.app.metamaze.eu/project/project-settings/input/api-integration.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.