API Documentation

Overview

The Metafast API allows you to programmatically retrieve metadata and summaries for web pages. This documentation explains how to authenticate with the API, generate API keys, and use the available endpoints.

Base URL

https://api.metafa.st/

Authentication

All API requests require authentication using an API key. Your API key should be included in the request headers.

Generating an API Key

  1. Log in to your Metafast account
  2. Navigate to an App from your dashboard
  3. Click the "App settings" button
  4. Scroll down to the API keys section
  5. Click "Generate API key" to generate your API key
  6. Important: Copy and store your API key securely

Using Your API Key

Include your API key in the Authorization header of your requests:

Authorization: Bearer YOUR_API_KEY

Rate Limiting

The API enforces rate limits to ensure fair usage. The limits are:

  • Metadata requests: 60 requests per minute
  • Summary requests: 30 requests per minute

If you exceed these limits, the API will return a 429 Too Many Requests status code with a Retry-After header indicating when you can make the next request.

Endpoints

1. Fetch Metadata

GET/api/v2/metadata

Description: Retrieves metadata information for a specified URL.

Query Parameters:

ParameterTypeRequiredDescription
urlstringYesThe URL of the webpage to fetch metadata for
forcebooleanNoForce the API to fetch the metadata even if it has already been cached

Example Request:

curl -X GET "https://api.metafa.st/api/v2/metadata?url=https://example.com" \
     -H "Authorization: Bearer YOUR_API_KEY"

Example Response:

{
  "id": "366061c7-f80d-4edc-90ac-badc31c5e5e6",
  "status": "completed",
  "error_message": null,
  "content": {
    "title": "Hazumi News | Mistral OCR",
    "description": "Mistral AI, a French startup, has developed an advanced optical character recognition (OCR) technology that can accurately extract text from images and documents. The article highlights the company's innovative approach and the potential applications of its OCR solution across various industries.",
    "favicon_url": "https://www.hazumi.news/favicon.ico",
    "og": {
      "url": "https://www.hazumi.news/posts/43282905",
      "type": "article",
      "image": "https://cdn.hazumi.news/eyJidWNrZXQiOiJoYXp1bWktaW1hZ2VzIiwia2V5IjoiNDMyODI5MDUiLCJlZGl0cyI6eyJyZXNpemUiOnsid2lkdGgiOjU3NCwiZml0IjoiY292ZXIifX19",
      "title": "Mistral OCR",
      "site_name": "Hazumi for Hacker News",
      "description": "Mistral AI, a French startup, has developed an advanced optical character recognition (OCR) technology that can accurately extract text from images and documents. The article highlights the company's innovative approach and the potential applications of its OCR solution across various industries."
    },
    "twitter": {
      "card": "summary_large_image",
      "site": "@HazumiNews",
      "image": "https://cdn.hazumi.news/eyJidWNrZXQiOiJoYXp1bWktaW1hZ2VzIiwia2V5IjoiNDMyODI5MDUiLCJlZGl0cyI6eyJyZXNpemUiOnsid2lkdGgiOjU3NCwiZml0IjoiY292ZXIifX19",
      "creator": "@HazumiNews",
      "app": {
        "id": {
          "ipad": "1670237209",
          "iphone": "1670237209"
        },
        "name": {
          "ipad": "Hazumi for Hacker News",
          "iphone": "Hazumi for Hacker News"
        }
      },
      "description": "Mistral AI, a French startup, has developed an advanced optical character recognition (OCR) technology that can accurately extract text from images and documents. The article highlights the company's innovative approach and the potential applications of its OCR solution across various industries."
    }
  },
  "usage": {
    "captured_at": "2025-03-16T14:18:27.291Z",
    "requests_remaining": 1134141,
    "transactions": [
      {
        "id": "21514676-0de8-4583-8349-63310408a34d",
        "transaction_status": "processed",
        "failure_reason": "no_failure",
        "created_at": "2025-03-16T14:18:27.308Z",
        "cost": 1
      }
    ]
  }
}

2. Fetch Summaries

GET/api/summaries

Description: Retrieves an AI-generated summary for a specified URL.

Query Parameters:

ParameterTypeRequiredDescription
urlstringYesThe URL of the webpage to summarize
forcebooleanNoForce the API to generate a summary even if it has already been cached

Example Request:

curl -X GET "https://api.metafa.st/api/summaries?url=https://example.com" \
     -H "Authorization: Bearer YOUR_API_KEY"

Example Response:

{
  "id": "1ba764ae-1744-44b5-afaa-a9d487cf6196",
  "status": "completed",
  "content": {
    "summary": "The article discusses plant-based meat alternatives and their potential environmental and health benefits."
  },
  "usage": {
    "captured_at": "2025-02-26T21:36:07.337Z",
    "requests_remaining": 4,
    "transactions": [
      {
        "id": "56a3fb11-733f-4dec-8300-93c69294e3ff",
        "transaction_status": "processed",
        "failure_reason": "no_failure",
        "created_at": "2025-02-26T21:36:07.371Z",
        "cost": 1
      }
    ]
  }
}

Response Status Codes

Status CodeDescription
200Success
400Bad Request - Your request is invalid or missing required parameters
401Unauthorized - Your API key is invalid or missing
403Forbidden - You don't have permission to access this resource
404Not Found - The specified resource could not be found
429Too Many Requests - You have exceeded the rate limit
500Internal Server Error - We had a problem with our server

Error Responses

When the API encounters an error, it will return a JSON response with an error message:

{
  "error": {
    "message": "Description of the error"
  }
}