API Reference
A RESTful API with resource-oriented URLs, JSON-encoded responses, and standard HTTP status codes.
Base URL
Every request goes to a single host, with the resource path appended.
https://api.metorial.comAuthentication
Authenticate with a bearer token. Each key is scoped to one environment within a project, so the same code can target live or test data by swapping the key.
- Publishable keys (
metorial_pk_) read public data and are safe in client-side code. - Secret keys (
metorial_sk_) have full project access and must stay server-side.
Prefer an SDK
The JavaScript and Python SDKs handle authentication, pagination, and retries for you.
Resources
Providers
ProvidersA provider is a read-only template for an MCP server integration (like GitHub or Slack). To use…Provider VersionsA version is a specific release of a provider (e.g., v1.2.0). Each version has its own tools…Provider SpecificationsA specification defines what a provider version can do: its tools, auth methods, and required…Provider TriggersA provider trigger describes an event source a provider can emit for callbacks. Use triggers to…Provider ToolsA tool is a single action a provider can perform like 'search_issues' or 'send_message'. Tools…Provider Auth MethodsAn auth method defines one way to authenticate with a provider (OAuth, API token, or custom…
Integrations
IntegrationsIntegrations define reusable provider contracts that can then be materialized into integration…Integration ProvidersIntegration providers define the shared provider-level contract for a given integration.Integration Setup SessionsIntegration setup sessions orchestrate configuring every provider required by an integration…Integration InstancesIntegration instances materialize an integration for a specific actor, identity, or runtime…Integration Instance ProvidersIntegration instance providers resolve the effective per-instance provider materialization for…Integration Instance GroupsIntegration instance groups combine instance providers into a grouped routed configuration.Integration Instance Group ProvidersIntegration instance group providers define the effective routed provider set for an…
Sessions
SessionsSessions are connections to providers that allow clients to interact with MCP servers. Each…Session TemplatesSession templates define reusable configurations for sessions, including which providers to…Session Template ProvidersSession template providers define which providers should be included when a session is created…Session ProvidersSession providers represent the providers that are actively connected to a session. Each…Session ParticipantsSession participants represent the clients and other entities that are connected to a session…Session ErrorsSession errors track errors that occurred during a session. This read-only resource provides…Provider RunsProvider runs track the execution of provider operations within a session. This read-only…Session MessagesSession messages represent the MCP protocol messages exchanged during a session. This read-only…Session ConnectionsSession connections represent the MCP connections established within a session. This read-only…Tool CallsTool calls represent individual tool invocations within a session. They track the input…
Configurations
Provider DeploymentsA deployment is a running instance of a provider, pinned to a specific version. Deployments…Provider ConfigsA config holds settings for a deployment, like API endpoints or feature flags. Create configs…Provider Config VaultsA config vault is a saved, reusable set of configuration values. Use vaults to store…Provider Auth ConfigsAn auth config is a user's authenticated connection to a provider. Created when a user…Provider Auth CredentialsAuth credentials store your OAuth app registration (client ID, client secret, and scopes)…Provider Setup SessionsA setup session tracks an in-progress OAuth flow, storing state during the redirect. On…Provider Auth ImportsAn auth import lets you bring in existing OAuth tokens or credentials from another system, so…Provider Auth ExportsAn auth export lets you extract OAuth tokens or credentials from Metorial to use in other…
Skills
Skill ConfigurationsManage configuration profiles for skill execution.SkillsSkills group provider and integration capabilities into reusable, owned compositions.Skill AgentsManage sub-agents attached to a skill.Skill GroupsSkill groups organize skills into reusable collections.Skill Group ItemsSkill group items link groups to skills.Skill ItemsSkill items attach integrations and providers to skills.Skill ParticipantsInspect participants associated with an instance skill.Skill TemplatesSkill templates define reusable starting points for skills.Skill Template ItemsSkill template items link template definitions to provider and integration items.Skill VersionsInspect version history and snapshots for a skill.Skill ExportsExport skills, skill plugins, and skill marketplaces as zip files.Skill ImportsImport skills from public repositories or uploaded files.Skill MarketplacesManage skill marketplaces for an instance.Skill Marketplace PluginsManage plugin links for skill marketplaces.Skill PluginsManage skill plugins for an instance.Skill Plugin SkillsManage skill links for skill plugins.
Portals
PortalUse Portals to create custom branded MCP server marketplaces for your organization.Portal AccessManage which consumer groups can access portal provider templates and MCP servers.Portal ListingsRead the shared listings available on a portal surface.Portal Access RequestsReview and resolve access requests for a portal.Portal Consumer GroupsManage the consumer groups that drive portal visibility and access rules.Portal Consumer ProfilesManage the consumers and effective group assignments for a portal.Portal Consumer InvitesList and inspect consumer invites for a portal.
Custom Providers
Custom ProvidersCustom providers allow you to deploy your own MCP servers. Create providers from container…Custom Provider VersionsVersions represent different releases of a custom provider. Each version can be deployed to…Custom Provider DeploymentsDeployments track the build and deployment process of custom provider versions. View deployment…
File Collections
DocumentsCreate and manage instance documents backed by Cargo.Document VersionsInspect document version history for an instance document.Document ParticipantsInspect document participants and their linked Metorial resources.StoresCreate and manage instance stores backed by Cargo.Store ItemsInspect items within an instance store.Store ParticipantsInspect participants assigned to an instance store.