MetorialDocs

Integration Instances

Integration instances materialize an integration for a specific actor, identity, or runtime configuration.

The Integration Instance object

integration_instance.json
{
  "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.754Z",
  "updated_at": "2026-09-11T20:30:32.754Z",
  "archived_at": "2026-09-11T20:30:32.754Z"
}
object"integration.instance"required
idstringrequired
status"draft" | "active" | "archived" | "deleted"required
namestringrequired
descriptionstringrequirednullable
metadataRecord<string, any>requirednullable
integration_idstringrequired
identity_actor_idstringrequirednullable
identity_idstringrequirednullable
created_atdaterequired
updated_atdaterequired
archived_atdaterequirednullable

Endpoints

List integration instances

GET/integration-instances

Returns a paginated list of integration instances.

Query parameters

searchstringoptional
status"draft" | "active" | "archived" | "deleted" or "draft" | "active" | "archived" | "deleted"[]optional
idstring or string[]optional
integration_idstring or string[]optional
provider_idstring or string[]optional
integration_provider_idstring or string[]optional
identity_idstring or string[]optional
identity_credential_idstring or string[]optional
identity_actor_idstring or string[]optional
provider_deployment_idstring or string[]optional
provider_config_idstring or string[]optional
provider_auth_config_idstring or string[]optional
session_template_idstring or string[]optional

Example request

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

Get integration instance

GET/integration-instances/:integration_instance_id

Retrieves a specific integration instance.

Path parameters

integration_instance_idstringrequired

The unique identifier for the integration_instance

Example request

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

Create integration instance session template

POST/integration-instances/:integration_instance_id/session-template

Creates or updates the shared session template for a specific integration instance.

Path parameters

integration_instance_idstringrequired

The unique identifier for the integration_instance

Request body

namestringoptional
descriptionstringoptional
metadataRecord<string, any>optional

Example request

curl -X POST "https://api.metorial.com/integration-instances/int_Rm4Mnheq2bfEPhBhP7SY/session-template" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_io2h4..." \
  -d '{
  "name": "example_name",
  "description": "example_description",
  "metadata": {}
}'

Create integration instance session

POST/integration-instances/:integration_instance_id/session

Creates a session from the shared session template of a specific integration instance.

Path parameters

integration_instance_idstringrequired

The unique identifier for the integration_instance

Request body

namestringoptional
descriptionstringoptional
metadataRecord<string, any>optional

Example request

curl -X POST "https://api.metorial.com/integration-instances/int_Rm4Mnheq2bfEPhBhP7SY/session" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_io2h4..." \
  -d '{
  "name": "example_name",
  "description": "example_description",
  "metadata": {}
}'

Create integration instance

POST/integration-instances

Creates a new integration instance.

Request body

integration_idstringrequired
namestringrequired
descriptionstringoptional
metadataRecord<string, any>optional
identity_actor_idstringoptionalnullable
identity_idstringoptionalnullable

Example request

curl -X POST "https://api.metorial.com/integration-instances" \
  -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",
  "providers": [
    {
      "tool_filters": {
        "type": "tool_keys"
      }
    },
    {
      "tool_filters": {
        "type": "tool_keys"
      }
    }
  ]
}'

Update integration instance

PATCH/integration-instances/:integration_instance_id

Updates a specific integration instance.

Path parameters

integration_instance_idstringrequired

The unique identifier for the integration_instance

Request body

namestringoptional
descriptionstringoptionalnullable
metadataRecord<string, any>optionalnullable
identity_actor_idstringoptionalnullable
identity_idstringoptionalnullable

Example request

curl -X PATCH "https://api.metorial.com/integration-instances/int_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_io2h4..." \
  -d '{
  "name": "example_name",
  "description": "example_description",
  "metadata": {},
  "identity_actor_id": "example_identity_actor_id",
  "identity_id": "example_identity_id",
  "providers": [
    {
      "tool_filters": {
        "type": "tool_keys"
      }
    },
    {
      "tool_filters": {
        "type": "tool_keys"
      }
    }
  ]
}'

Delete integration instance

DELETE/integration-instances/:integration_instance_id

Archives a specific integration instance.

Path parameters

integration_instance_idstringrequired

The unique identifier for the integration_instance

Example request

curl -X DELETE "https://api.metorial.com/integration-instances/int_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Authorization: Bearer metorial_sk_io2h4..."