Sessions

Sessions are connections to providers that allow clients to interact with MCP servers. Each session can include one or more provider deployments.

Sessions object

Attributes

object

String

String representing the object's type

id

String

Unique session identifier

name

StringNullable

Display name

description

StringNullable

Description

status

Enum

Session status

connection_status

Enum

Connection state

usage

Object

metadata

ObjectNullable

Custom key-value pairs

connection_url

StringNullable

Direct MCP connection URL for this session

provider_deployments

Object

List of provider deployments in this session

created_at

Date

Timestamp when created

updated_at

Date

Timestamp when last updated

{
  "object": "session",
  "id": "ses_4dEfGhJkLmNpQrSt",
  "name": "Production Session",
  "description": "Session for production environment",
  "status": "active",
  "connection_status": "connected",
  "usage": {},
  "metadata": {
    "environment": "production"
  },
  "connection_url": "https://subspace.metorial.io/sol_abc/ten_xyz/sessions/ses_4dEfGhJkLmNpQrSt/mcp",
  "provider_deployments": [
    {
      "object": "session.provider_deployment#preview",
      "id": "spr_3cDeFgHjKlMnPqRs",
      "name": "GitHub Provider",
      "provider_id": "pro_5gHjKlMnPqRsTuVw",
      "provider_deployment_id": "pde_1aBcDeFgHjKlMnPq"
    }
  ],
  "created_at": "2025-09-15T10:30:00.000Z",
  "updated_at": "2026-01-10T14:45:00.000Z"
}

List sessions

Returns a paginated list of sessions.

Query Parameters

limit

NumberOptional

Maximum number of items to return (1-100)

after

StringOptional

Return items after this ID

before

StringOptional

Return items before this ID

cursor

StringOptional

Pagination cursor from a previous response

order

EnumOptional

Sort order for results

status

UnionOptional

provider_id

UnionOptional

provider_deployment_id

UnionOptional
GEThttp://api.metorial.com/sessions
curl -X GET "https://api.metorial.com/sessions" \
  -H "Authorization: Bearer metorial_sk_..."

Get session

Retrieves a specific session by ID.

URL Parameters

session_id

String

The unique identifier for the session

GEThttp://api.metorial.com/sessions/:session_id
curl -X GET "https://api.metorial.com/sessions/ses_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Authorization: Bearer metorial_sk_..."

Create session

Creates a new session with provider deployments.

Request Body

name

StringOptional

description

StringOptional

metadata

ObjectOptional

A key-value map

providers

Object
POSThttp://api.metorial.com/sessions
curl -X POST "https://api.metorial.com/sessions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_..." \
  -d '{
  "name": "example_name",
  "description": "example_description",
  "metadata": {},
  "providers": {
    "provider_deployment": {
      "type": "example_type",
      "provider_deployment_id": "example_provider_deployment_id"
    },
    "provider_config": {
      "type": "example_type",
      "provider_config_id": "example_provider_config_id"
    },
    "provider_auth_config": {
      "type": "example_type",
      "provider_auth_config_id": "example_provider_auth_config_id"
    },
    "session_template_id": "example_session_template_id",
    "tool_filters": {
      "tool_keys": [
        "example_item"
      ]
    }
  }
}'

Update session

Updates a session.

URL Parameters

session_id

String

The unique identifier for the session

Request Body

name

StringOptional

description

StringOptional

metadata

ObjectOptional

Custom key-value pairs for storing additional information

PATCHhttp://api.metorial.com/sessions/:session_id
curl -X PATCH "https://api.metorial.com/sessions/ses_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_..." \
  -d '{
  "name": "example_name",
  "description": "example_description",
  "metadata": {}
}'

Delete session

Deletes a session.

URL Parameters

session_id

String

The unique identifier for the session

DELETEhttp://api.metorial.com/sessions/:session_id
curl -X DELETE "https://api.metorial.com/sessions/ses_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Authorization: Bearer metorial_sk_..."