Skip to main content
Welcome to the Metorial API! This guide will help you quickly understand how to start using our API and make your first requests.
What you’ll learn:
  • How to use the Metorial API
  • How to get your API key
  • How to make your first API request
Recommended reading:

​
What is the Metorial API?

The Metorial API is a simple, user-friendly way to interact with Metorial’s services. It uses standard web communication (REST) and always returns data in JSON format, making it easy to work with across different programming languages.

​
Before You Begin: Getting Your API Key

To use the Metorial API, you’ll need an API key. You can generate these in two types: Publishable API Keys (metorial_pk_):
  • Used for public data access
  • Safe to use in client-side code
  • Starts with metorial_pk_
Secret API Keys (metorial_sk_):
  • Provides full project access
  • Must be kept private
  • Starts with metorial_sk_
You can generate both publishable and secret API keys in your Metorial dashboard by navigating to Developer → API Keys.
Create API Key dialog in Metorial dashboard

​
Making Your First API Request

When making a request, you’ll always use this base URL: 
https://api.metorial.com
To authenticate, include your API key in the request header: 
Authorization: Bearer metorial_sk_abc123
Here’s a simple request to list your provider deployments: 
curl -X GET https://api.metorial.com/provider-deployments \
  -H "Authorization: Bearer metorial_sk_abc123"

​
API Resources

The Metorial API covers these resource groups: Providers
  • GET/POST /provider-deployments — Create and manage provider deployments
  • GET/POST /provider-configs — Manage provider configurations
  • GET/POST /provider-auth-configs — Manage stored credentials (OAuth tokens, API keys)
  • GET/POST /provider-setup-sessions — Create OAuth/config authorization flows for users
  • GET /provider-versions — Browse available provider versions
  • GET /provider-specifications — View tools and auth methods for a provider version
Sessions
  • POST /sessions — Create a session connected to one or more providers
  • GET /session-connections — View connections within a session
  • GET /session-messages — View tool calls and messages
  • GET /session-events — View session events
  • GET /session-participants — View session participants
  • GET/POST /session-templates — Save and reuse session configurations

​
Client Libraries

We make integration super easy with official SDKs for:

JavaScript

Use Metorial with JavaScript or TypeScript.

Python

Use Metorial with Python.

​
Important Things to Know

​
Rate Limits

We have some basic usage limits to keep things fair:
  • 1000 requests per IP every 10 seconds
  • Development environments: 100 requests per 10 minutes
  • Production environments: 5000 requests per 10 minutes

​
Handling Responses

Our API uses standard HTTP response codes:
  • 200: Success!
  • 400: Something’s wrong with your request
  • 401: Invalid API key
  • 403: Not enough permissions
  • 404: Can’t find what you’re looking for
  • 429: You’ve hit the rate limit

​
Pagination

When fetching lists of items, we support cursor-based pagination. Each response includes has_more_before, has_more_after, and pagination cursors to help you fetch more items easily.

​
Need More Help?

Check out our full documentation or reach out to our support team. Happy coding!

SDK Documentation

Explore SDKs for easier integration.