Integration Setup Sessions API

The Integration Setup Session object

integration_setup_session.json

{
  "object": "integration.setup_session",
  "id": "example_id",
  "status": "pending",
  "url": "example_url",
  "name": "example_name",
  "description": "example_description",
  "metadata": {},
  "configuration": {},
  "redirect_url": "example_redirect_url",
  "integration_id": "example_integration_id",
  "integration_instance": {
    "object": "integration.instance",
    "id": "example_id",
    "status": "draft",
    "name": "example_name",
    "description": "example_description",
    "metadata": {},
    "integration_id": "example_integration_id",
    "identity_actor_id": "example_identity_actor_id",
    "identity_id": "example_identity_id",
    "implementation": {
      "type": "magic_mcp_server",
      "magic_mcp_server_id": "example_magic_mcp_server_id"
    },
    "providers": [
      {
        "object": "integration.instance.provider",
        "status": "active",
        "metadata": {},
        "tool_filter": {
          "type": "allow_all"
        },
        "provider": {
          "object": "provider#preview",
          "id": "pro_5gHjKlMnPqRsTuVw",
          "name": "GitHub",
          "description": "Connect to GitHub repositories, issues, and pull requests",
          "slug": "github",
          "created_at": "2025-09-15T10:30:00.000Z",
          "updated_at": "2026-01-10T14:45:00.000Z"
        },
        "integration_provider": {
          "object": "integration.provider#snapshot",
          "provider_version": {
            "object": "integration.provider.version"
          },
          "status": "active",
          "metadata": {},
          "tool_filter": {
            "type": "allow_all"
          },
          "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"
          }
        },
        "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",
          "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"
        },
        "callback_instance_id": "cbi_5gHjKlMnPqRsTuVw"
      },
      {
        "object": "integration.instance.provider",
        "status": "active",
        "metadata": {},
        "tool_filter": {
          "type": "allow_all"
        },
        "provider": {
          "object": "provider#preview",
          "id": "pro_5gHjKlMnPqRsTuVw",
          "name": "GitHub",
          "description": "Connect to GitHub repositories, issues, and pull requests",
          "slug": "github",
          "created_at": "2025-09-15T10:30:00.000Z",
          "updated_at": "2026-01-10T14:45:00.000Z"
        },
        "integration_provider": {
          "object": "integration.provider#snapshot",
          "provider_version": {
            "object": "integration.provider.version"
          },
          "status": "active",
          "metadata": {},
          "tool_filter": {
            "type": "allow_all"
          },
          "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"
          }
        },
        "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",
          "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"
        },
        "callback_instance_id": "cbi_5gHjKlMnPqRsTuVw"
      }
    ],
    "created_at": "2026-09-11T20:30:32.753Z",
    "updated_at": "2026-09-11T20:30:32.753Z",
    "archived_at": "2026-09-11T20:30:32.753Z"
  },
  "created_at": "2026-09-11T20:30:32.753Z",
  "updated_at": "2026-09-11T20:30:32.753Z",
  "expires_at": "2026-09-11T20:30:32.753Z"
}

object"integration.setup_session"required

idstringrequired

status"pending" | "successful" | "expired" | "archived" | "deleted"required

urlstringrequired

namestringrequirednullable

descriptionstringrequirednullable

metadataRecord<string, any>requirednullable

configurationRecord<string, any>requirednullable

redirect_urlstringrequirednullable

integration_idstringrequired

integration_instanceobjectrequired

created_atdaterequired

updated_atdaterequired

expires_atdaterequired

Endpoints

List integration setup sessions

GET/integration-setup-sessions

Returns a paginated list of integration setup sessions.

Query parameters

idstring or string[]optional

integration_idstring or string[]optional

integration_instance_idstring or string[]optional

created_atobjectoptional

Filter integration setup session creation time by date range

updated_atobjectoptional

Filter integration setup session last update time by date range

Example request

curl -X GET "https://api.metorial.com/integration-setup-sessions" \
  -H "Authorization: Bearer metorial_sk_io2h4..."

Get integration setup session

GET/integration-setup-sessions/:integration_setup_session_id

Retrieves a specific integration setup session.

Path parameters

integration_setup_session_idstringrequired

The unique identifier for the integration_setup_session

Example request

curl -X GET "https://api.metorial.com/integration-setup-sessions/int_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Authorization: Bearer metorial_sk_io2h4..."

Create integration setup session

POST/integration-setup-sessions

Creates a new integration setup session and draft integration instance.

Request body

integration_idstringrequired

namestringrequired

descriptionstringoptional

metadataRecord<string, any>optional

identity_actor_idstringoptionalnullable

identity_idstringoptionalnullable

expires_atdateoptional

redirect_urlstringoptional

configurationobjectoptional

Example request

curl -X POST "https://api.metorial.com/integration-setup-sessions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_io2h4..." \
  -d '{
  "integration_id": "example_integration_id",
  "name": "example_name",
  "description": "example_description",
  "metadata": {},
  "identity_actor_id": "example_identity_actor_id",
  "identity_id": "example_identity_id",
  "expires_at": "2026-09-11T20:30:32.753Z",
  "redirect_url": "example_redirect_url",
  "configuration": {
    "provider_search": {
      "groups": [
        {},
        {}
      ],
      "collections": [
        {},
        {}
      ],
      "categories": [
        {},
        {}
      ]
    },
    "tool_filters": {
      "enabled": false
    },
    "ui": {
      "layout": "box"
    }
  }
}'