MetorialDocs

Session Providers

Session providers represent the providers that are actively connected to a session. Each session can have multiple providers, and providers can be added or removed during the session lifecycle.

The Session Provider object

session_provider.json
{
  "object": "session.provider",
  "id": "spr_3cDeFgHjKlMnPqRs",
  "status": "active",
  "usage": {
    "total_productive_client_message_count": 0,
    "total_productive_provider_message_count": 0
  },
  "tool_filter": {
    "type": "allow_all",
    "ignore_parent_filters": false
  },
  "provider_id": "pro_5gHjKlMnPqRsTuVw",
  "session_id": "ses_4dEfGhJkLmNpQrSt",
  "from_template_id": "stm_2bCdEfGhJkLmNpQr",
  "from_template_provider_id": "stp_3cDeFgHjKlMnPqRs",
  "deployment": {
    "object": "provider.deployment#preview",
    "id": "pde_1aBcDeFgHjKlMnPq",
    "is_default": false,
    "name": "Production",
    "description": "Production deployment",
    "metadata": {},
    "provider_id": "pro_5gHjKlMnPqRsTuVw",
    "created_at": "2025-09-15T10:30:00.000Z",
    "updated_at": "2026-01-10T14:45:00.000Z"
  },
  "config": {
    "object": "provider.config#preview",
    "id": "pcf_7dEfGhJkLmNpQrSt",
    "is_default": false,
    "name": "Production Config",
    "description": "Configuration for production environment",
    "metadata": {},
    "provider_id": "pro_5gHjKlMnPqRsTuVw",
    "created_at": "2025-09-15T10:30:00.000Z",
    "updated_at": "2026-01-10T14:45:00.000Z"
  },
  "auth_config": {
    "object": "provider.auth_config#preview",
    "id": "example_id"
  },
  "created_at": "2025-09-15T10:30:00.000Z",
  "updated_at": "2026-01-10T14:45:00.000Z"
}
object"session.provider"required
idstringrequired
status"active" | "archived" | "deleted"required
provider_idstringrequired
session_idstringrequired
from_template_idstringrequirednullable
from_template_provider_idstringrequirednullable
created_atdaterequired
updated_atdaterequired

Endpoints

List session providers

GET/session-providers

Returns a paginated list of providers connected to a session.

Query parameters

idstring or string[]optional

Filter by session provider ID(s)

session_idstring or string[]optional

Filter by session ID(s)

session_template_idstring or string[]optional

Filter by session template ID(s)

provider_idstring or string[]optional

Filter by provider ID(s)

provider_deployment_idstring or string[]optional

Filter by provider deployment ID(s)

provider_config_idstring or string[]optional

Filter by provider config ID(s)

provider_auth_config_idstring or string[]optional

Filter by provider auth config ID(s)

status"active" | "archived" or "active" | "archived"[]optional

Filter by provider status

Example request

curl -X GET "https://api.metorial.com/session-providers" \
  -H "Authorization: Bearer metorial_sk_io2h4..."

Get session provider

GET/session-providers/:session_provider_id

Retrieves a specific provider connected to a session.

Path parameters

session_provider_idstringrequired

The unique identifier for the session_provider

Example request

curl -X GET "https://api.metorial.com/session-providers/ses_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Authorization: Bearer metorial_sk_io2h4..."

Create session provider

POST/session-providers

Adds a new provider to an active session.

Request body

session_idstringrequired

Example request

curl -X POST "https://api.metorial.com/session-providers" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_io2h4..." \
  -d '{
  "session_id": "example_session_id",
  "tool_filters": {
    "type": "tool_keys",
    "keys": [
      "example_keys"
    ]
  }
}'

Update session provider

PATCH/session-providers/:session_provider_id

Updates a provider connected to a session.

Path parameters

session_provider_idstringrequired

The unique identifier for the session_provider

Request body

Example request

curl -X PATCH "https://api.metorial.com/session-providers/ses_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_io2h4..." \
  -d '{
  "tool_filters": {
    "type": "tool_keys",
    "keys": [
      "example_keys"
    ]
  }
}'

Delete session provider

DELETE/session-providers/:session_provider_id

Removes a provider from a session.

Path parameters

session_provider_idstringrequired

The unique identifier for the session_provider

Example request

curl -X DELETE "https://api.metorial.com/session-providers/ses_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Authorization: Bearer metorial_sk_io2h4..."