​
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

TitleHeaderExample Key
API Keyx-metal-api-keypk_1234567890
Client IDx-metal-client-idci_1234567890

​
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.
CodeDescription
200OK - Everything worked as expected.
400Bad Request - Often missing a required parameter.
401Unauthorized - No valid API key provided.
402Request Failed - Parameters were valid but request failed.
404Not Found - The requested item doesn’t exist.
422Usage Limit Exceeded - Hit a feature or usage limit based on your plan.
429Rate Limit Exceeded - Too many requests hit the API too quickly.
5xxServer Errors - something went wrong on Metal’s end.

​
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;
}