canonical: https://jentic.com/apis/metorial.com/metorial # Metorial API Metorial is a control plane for AI integrations that lets teams register providers, attach identities and credentials, and orchestrate sessions that downstream agents and applications can use. The API exposes resources for publishers, providers, identities, sessions, and provider configurations so AI infrastructure can be managed declaratively rather than hardcoded into each agent. It is consumed via a bearer-token authenticated REST interface with 21 endpoints. ## For AI agents Manage AI provider integrations, identities, and sessions so agents can talk to upstream model providers under a single, governed control plane. ## Scope Does not run model inference, store conversation history, or generate text - use for AI provider, identity, and session management only. ## Capabilities - Register and inspect AI providers and provider deployments available to your tenant - Create, update, and delete identities that map agents or human users to provider credentials - Open sessions that bind an identity to a provider configuration for a working agent run - Maintain provider configurations including credentials, scoping, and rotation metadata - List publishers and resolve their published providers for downstream selection ## Use cases ### Centralised AI Provider Credential Management Engineering teams running multiple agents across providers like OpenAI, Anthropic, and self-hosted models avoid scattering API keys by registering each provider once in Metorial and creating per-agent identities that reference the central configuration. The /provider-configs and /identities endpoints let platform owners rotate credentials in one place while agents continue to call through their stable identity. Example prompt: Create a provider configuration for OpenAI with the production credential, then create an identity scoped to it and verify it via GET `/provider-configs/{id}.` ### Per-Agent Session Isolation When an autonomous agent runs many parallel tasks, each task can be scoped to its own Metorial session so quotas, audit logs, and credential exposure stay isolated. POST /sessions binds an identity to a provider configuration for the lifetime of a job, and PATCH `/sessions/{id}` lets the orchestrator update metadata as the agent progresses. Example prompt: Create a session for identity 'agent-42' tied to provider config 'anthropic-prod', then update the session description with the running task ID. ### Multi-Tenant AI Platform Onboarding Platforms that resell AI capabilities to many customers can use Metorial publishers and provider deployments to expose curated provider catalogues per tenant. The publishers and provider-deployments endpoints describe what is available, while identities map customers to the right credential tier without leaking secrets between tenants. Example prompt: List all publishers, then for the selected publisher list the provider deployments and create an identity tied to the chosen deployment. ### Agent Provisioning Through Jentic An autonomous agent that needs an AI provider can call Metorial through Jentic to provision an identity and open a session on demand. The agent searches for the operation by intent, loads the schema for POST /identities or POST /sessions, and executes with arguments derived from the runtime context - without ever holding the bearer token directly. Example prompt: Search Jentic for 'create an AI agent identity', load POST /identities, then POST /sessions for the new identity, and return the session ID. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | `/identities` | Create a new identity for an agent or user | | POST | `/sessions` | Open a session binding an identity to a provider configuration | | GET | `/sessions/{id}` | Retrieve session details | | POST | `/provider-configs` | Create a provider configuration | | PATCH | `/provider-configs/{id}` | Update an existing provider configuration | | GET | `/providers` | List available AI providers | ## Key resources - **Identities** — Create, retrieve, update, and delete identities that represent agents or users - **Sessions** — Open and manage time-bound sessions that bind an identity to a provider configuration - **Providers** — List and inspect AI providers and their available deployments - **Provider Configurations** — CRUD for credential and scoping configurations attached to providers - **Publishers** — List the publishers that expose curated provider catalogues ## Why Jentic - **Setup:** Wiring Metorial by hand means reading its bearer scheme, distinguishing the publishable metorial_pk_ key from the secret metorial_sk_ key, and setting the Authorization header yourself. Through Jentic you install once, import Metorial from the API Directory, store the token once, and your agent calls it. - **Permission scoping:** Metorial puts sessions and provider configs by id in the URL path (`/sessions/{id}`, `/provider-configs/{id}`), so a rule can pin your agent to specific resources. You choose the operations it may call, so patching a provider config is not included unless you add it. - **Credential handling:** Your Metorial bearer token is stored once, encrypted, by your own Jentic One instance and injected into the Authorization header at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'create an AI agent identity' or 'open a Metorial session', and Jentic returns the matching Metorial operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **OpenAI** — Upstream LLM provider managed via Metorial - **Anthropic Messages API** — Anthropic Claude messaging endpoint that Metorial can broker - **Portkey** — AI gateway with provider routing, observability, and key vaulting ## FAQ ### What authentication does the Metorial API use? Metorial uses HTTP bearer authentication - every request needs an Authorization header with a token issued from your Metorial instance. Through Jentic the token lives in the encrypted vault and is injected at call time so agents never handle it directly. ### Can I create multiple identities under one provider configuration? Yes. POST /identities creates an identity, and you can then attach it to an existing provider configuration via a session. This is the recommended pattern for fanning out many agents while keeping a single rotated credential. ### What are the rate limits for the Metorial API? Metorial does not document fixed rate limits in this OpenAPI spec - limits are tenant-specific and set by your Metorial deployment. Inspect response headers and back off on 429 responses; for high-volume orchestrators contact Metorial support to raise the cap. ### How do I open a session for an agent through Jentic? Search Jentic for 'create a Metorial session', load POST /sessions, and execute with the identity ID and provider configuration ID. Jentic handles the bearer token from your stored Metorial credential. ### Does Metorial actually call upstream LLM providers for me? Metorial is the control plane for identities, sessions, and provider configurations - actual model invocations happen at the provider you configure, with Metorial managing the credential and session boundary around each call. ### Can I update a provider configuration without breaking active sessions? PATCH `/provider-configs/{id}` updates fields in place. Active sessions continue to reference the same configuration; if you rotate the underlying credential, the new value takes effect for subsequent calls without re-creating sessions. ### Can I limit what my agent is allowed to do with the Metorial API? Yes. Because you run Jentic One yourself, your own rules decide which Metorial operations the agent can call, so you can grant it POST /sessions and GET `/sessions/{id}` while withholding write operations like PATCH `/provider-configs/{id}.` Since Metorial addresses sessions and provider configs by id in the URL path, you can also pin the agent to specific resources rather than the whole account. Your Metorial bearer token stays stored on your own instance and is added to the request only for the operations you have permitted.