Metorial API Reference
The Metorial API is a RESTful service with resource-oriented URLs. It consistently returns JSON-encoded responses and adheres to standard HTTP response codes. The API supports both URL-encoded and JSON-encoded request bodies, but JSON is the recommended format.
Each API key is tied to a specific environment within a project in your account. This enables interaction with either live or test data for your project.
Base URL
The base URL for the Metorial API is:
https://api.metorial.com
All API requests are made to this URL, with the appropriate endpoint appended.
Client Libraries
We offer first-party SDKs for the following programming languages:
These SDKs are open-source, and their repositories are available on our GitHub page. Feel free to contact us for assistance or to report issues.
Testing & Environments
You can create multiple environments for each project via the Metorial dashboard. Each environment has unique API keys, ensuring clear separation of data access.
- Example: Your
development
API key will never access theproduction
environment. - Any resources created using the API are linked to the environment associated with the provided API key.
Authentication
The Metorial API uses API keys for authentication, which you can generate from the Metorial dashboard. There are two types of API keys:
-
Publishable API Keys:
These keys allow access to public data, such as agent lists. They are safe for client-side usage and have the prefixmetorial_pk_
. -
Secret API Keys:
These keys provide full access to your project and must be kept private. Never expose them in client-side code. They have the prefixmetorial_sk_
.
Additionally, Client Tokens are JWTs linked to individual users. These tokens restrict access to user-specific resources and must be used alongside a Publishable API Key.
Using API Keys
Include the API key in the Authorization
header using the Bearer
scheme:
Authorization: Bearer metorial_pk_abc123
Using Client Tokens
When using a client token, include the Publishable API Key in the Authorization
header:
Authorization: Bearer metorial_pk_abc123
Add the client token as a query parameter in the request URL:
GET /threads?client_token=eyJhbGc...
Rate Limits
To ensure fair usage, the Metorial API imposes rate limits. If exceeded, a 429 Too Many Requests
response is returned. Rate limits vary by environment and access type:
- General Limit: 1000 requests per IP address every 10 seconds.
- Development Environment: 100 requests per API key every 10 minutes.
- Production Environment: 5000 requests per API key every 10 minutes.
- Client Tokens: 100 requests per user every 10 minutes.
Contact us if your use case requires higher limits.
Errors
The Metorial API uses standard HTTP response codes to communicate success or failure:
200 OK
: Successful request.400 Bad Request
: Invalid parameters or action.401 Unauthorized
: Invalid API key.403 Forbidden
: Insufficient permissions.404 Not Found
: Resource not found.422 Unprocessable Entity
: Validation failure; check request parameters.429 Too Many Requests
: Rate limit exceeded.5xx Server Errors
: Server issues; contact us for assistance.
Pagination
Endpoints returning lists support pagination. Responses include an items
array (resources) and a pagination
object:
1{2 "items": [3 // resources4 ],5 "pagination": {6 "afterCursor": "string | null",7 "beforeCursor": "string | null",8 "hasMoreBefore": true,9 "hasMoreAfter": true,10 "pageSize": 2511 }12}
afterCursor
andbeforeCursor
: Cursors for fetching subsequent or previous pages.hasMoreBefore
andhasMoreAfter
: Boolean flags for navigation.
To paginate, include the cursor in your query:
GET /threads?cursor=cursor_h2473hg5283ht43843
Versioning
The Metorial API is versioned to ensure backward compatibility. Each environment has a default version, which you can change in the Metorial dashboard.
Additionally, the API version can be specified as a request header:
Metorial-Version: 2025-01-01
Resource Identifiers (IDs)
All API resources have unique identifiers. Some, like Actor IDs, can optionally be user-defined. Others, like Thread IDs, are generated by Metorial and include a type-specific prefix.
Example Thread ID:
thr_0m4izbgwuHkvlAtGpjrpcA
Example User ID:
usr_0m4izbgwuHkvlAtGpjrpcA
IDs are always fewer than 255 characters in length.