MetorialDocs

Session Templates

Session templates define reusable configurations for sessions, including which providers to include. Templates can be used to quickly create new sessions with consistent settings.

The Session Template object

session_template.json
{
  "object": "session.template",
  "id": "stm_2bCdEfGhJkLmNpQr",
  "status": "active",
  "name": "Production Template",
  "description": "Template for production sessions",
  "metadata": {},
  "integration_instance_id": "example_integration_instance_id",
  "integration_instance_group_id": "example_integration_instance_group_id",
  "identity_actor_id": "example_identity_actor_id",
  "identity_id": "example_identity_id",
  "providers": [
    {
      "object": "session.template.provider",
      "id": "stp_3cDeFgHjKlMnPqRs",
      "status": "active",
      "tool_filter": {
        "type": "allow_all"
      },
      "provider_id": "pro_5gHjKlMnPqRsTuVw",
      "session_template_id": "stm_2bCdEfGhJkLmNpQr",
      "deployment": {
        "object": "provider.deployment#preview",
        "id": "pde_1aBcDeFgHjKlMnPq",
        "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",
        "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"
      },
      "created_at": "2025-09-15T10:30:00.000Z",
      "updated_at": "2026-01-10T14:45:00.000Z"
    },
    {
      "object": "session.template.provider",
      "id": "stp_3cDeFgHjKlMnPqRs",
      "status": "active",
      "tool_filter": {
        "type": "allow_all"
      },
      "provider_id": "pro_5gHjKlMnPqRsTuVw",
      "session_template_id": "stm_2bCdEfGhJkLmNpQr",
      "deployment": {
        "object": "provider.deployment#preview",
        "id": "pde_1aBcDeFgHjKlMnPq",
        "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",
        "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"
      },
      "created_at": "2025-09-15T10:30:00.000Z",
      "updated_at": "2026-01-10T14:45:00.000Z"
    }
  ],
  "created_at": "2025-09-15T10:30:00.000Z",
  "updated_at": "2026-01-10T14:45:00.000Z"
}
object"session.template"required
idstringrequired
status"active" | "archived" | "deleted"required
namestringrequired
descriptionstringrequirednullable
metadataRecord<string, any>requirednullable
integration_instance_idstringrequirednullable
integration_instance_group_idstringrequirednullable
identity_actor_idstringrequirednullable
identity_idstringrequirednullable
created_atdaterequired
updated_atdaterequired

Endpoints

List session templates

GET/session-templates

Returns a paginated list of session templates.

Query parameters

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

Filter by status (active, archived)

idstring or string[]optional

Filter by session template ID(s)

session_idstring or string[]optional

Filter templates that include sessions with these IDs

session_provider_idstring or string[]optional

Filter templates that include session providers with these IDs

provider_idstring or string[]optional

Filter templates that include providers with these IDs

provider_deployment_idstring or string[]optional

Filter templates that include provider deployments with these IDs

provider_config_idstring or string[]optional

Filter templates that include provider configs with these IDs

provider_auth_config_idstring or string[]optional

Filter templates that include provider auth configs with these IDs

Example request

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

Get session template

GET/session-templates/:session_template_id

Retrieves a specific session template by ID.

Path parameters

session_template_idstringrequired

The unique identifier for the session_template

Example request

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

Create session template

POST/session-templates

Creates a new session template.

Request body

namestringrequired
descriptionstringoptional
metadataRecord<string, any>optional

Custom key-value pairs for storing additional information

Example request

curl -X POST "https://api.metorial.com/session-templates" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_io2h4..." \
  -d '{
  "name": "Production Template",
  "description": "Template for production sessions",
  "metadata": {},
  "providers": [
    {
      "tool_filters": {
        "type": "tool_keys"
      }
    },
    {
      "tool_filters": {
        "type": "tool_keys"
      }
    }
  ]
}'

Update session template

PATCH/session-templates/:session_template_id

Updates a specific session template.

Path parameters

session_template_idstringrequired

The unique identifier for the session_template

Request body

namestringoptional
descriptionstringoptional
metadataRecord<string, any>optional

Custom key-value pairs for storing additional information

Example request

curl -X PATCH "https://api.metorial.com/session-templates/ses_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_io2h4..." \
  -d '{
  "name": "Updated Template Name",
  "description": "Updated description",
  "metadata": {}
}'

Delete session template

DELETE/session-templates/:session_template_id

Deletes a specific session template.

Path parameters

session_template_idstringrequired

The unique identifier for the session_template

Example request

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

List session template tools

GET/session-templates/:session_template_id/tools

Returns the effective set of tools available through the providers in a session template, filtered by the tool filters of each provider, deployment, config, and auth config.

Path parameters

session_template_idstringrequired

The unique identifier for the session_template

Example request

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