Introduction

​

Base URL

The Metal API is available at the following URL:

https://api.getmetal.io

​

Authentication

Metal uses API keys to authenticate requests. You can view and manage your API keys in the Metal Application. There are two headers that you’ll retrieve from each Key.

​

API Key Headers

​

Example Authenticated Request

curl --location --request GET 'https://api.getmetal.io' \
--header 'Content-Type: application/json' \
--header 'x-metal-api-key: pk_1234567890' \
--header 'x-metal-client-id: ci_1234567890' \

​

Response Codes

Metal uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.), and codes in the 5xx range indicate an error with Metal’s servers.

​

Normal pagination

For certain endpoints, such as /v1/indexes/:id/documents, pagination can be achieved using the page and limit query parameters.

Both page and limit should be positive integers with a maximum value of 100. This constraint means that using this method, callers can retrieve a maximum of 10,000 (i.e., 100 * 100) records.

​

Deep pagination

To fetch documents beyond the limitations of normal pagination, you should utilize the lastObjectIdSeen value returned. This ID enables the API to access data from a deeper point in the dataset. Below is an illustrative script to demonstrate this approach:

const fetchAllDocuments = () => {
  do {
    try {
      const response = await axios
        .get('https://api.getmetal.io/v1/indexes/<indexID>/documents', {
          headers: {
            'x-metal-api-key': '<your_key>',
            'x-metal-client-id': '<your_client_id>',
          },
          params: {
            lt: lastSeenObjectId, // this will be a querystring parameter `lt=${lastSeenObjectId}`
            limit: 100,
          },
        });

      documents = documents.concat(response.data.data);

      lastSeenObjectId = response.data.lastSeenObjectId;
    } catch (error) {
      console.error('Error fetching documents:', error);
      break;
    }
  } while (lastSeenObjectId);

  return documents;
}