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

Title	Header	Example Key
API Key	`x-metal-api-key`	`pk_1234567890`
Client ID	`x-metal-client-id`	`ci_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.

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

Overview

🔑 Account

📈 Analytics

🚀 Apps

📄 Data Entities

🗄️ Datasources

🧬 Embedding Documents

🔗 Indexes

Introduction

Base URL

Authentication

API Key Headers

Example Authenticated Request

Response Codes

​Base URL

​Authentication

​API Key Headers

​Example Authenticated Request

​Response Codes

​Normal pagination

​Deep pagination

Base URL

Authentication

API Key Headers

Example Authenticated Request

Response Codes

Normal pagination

Deep pagination