Integration Instances

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

Integration Instances object

Attributes

object

String

status

Enum

name

String

description

StringNullable

metadata

ObjectNullable

A key-value map

integration_id

String

identity_actor_id

StringNullable

identity_id

StringNullable

implementation

ObjectNullable

providers

Object

created_at

Date

updated_at

Date

archived_at

DateNullable

{
  "object": "integration.instance",
  "status": "draft",
  "metadata": {},
  "implementation": {
    "type": "magic_mcp_server"
  },
  "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"
        },
        "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"
        },
        "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"
        },
        "auth_method": {
          "object": "provider.capabilities.auth_method",
          "id": "pam_2mNpQrStUvWxYzAb",
          "type": "oauth",
          "key": "oauth2",
          "name": "OAuth 2.0",
          "description": "Authenticate using OAuth 2.0",
          "capabilities": {},
          "input_schema": {
            "type": "json_schema",
            "schema": {}
          },
          "output_schema": {
            "type": "json_schema",
            "schema": {}
          },
          "scopes": [
            {
              "object": "provider.capabilities.auth_method.scope",
              "id": "pams_8tUvWxYzAbCdEfGh",
              "scope": "repo",
              "name": "Repository Access",
              "description": "Full control of private repositories"
            },
            {
              "object": "provider.capabilities.auth_method.scope",
              "id": "pams_8tUvWxYzAbCdEfGh",
              "scope": "repo",
              "name": "Repository Access",
              "description": "Full control of private repositories"
            }
          ],
          "provider_id": "pro_5gHjKlMnPqRsTuVw",
          "provider_specification_id": "psp_9gHjKlMnPqRsTuVw",
          "created_at": "2025-09-15T10:30:00.000Z",
          "updated_at": "2026-01-10T14:45:00.000Z"
        },
        "auth_credentials": {
          "object": "provider.auth_credentials",
          "id": "par_4sTuVwXyZaBcDeFg",
          "type": "oauth",
          "status": "active",
          "is_default": true,
          "is_managed": true,
          "name": "GitHub OAuth",
          "description": "OAuth credentials for GitHub API",
          "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"
        }
      },
      "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"
      }
    },
    {
      "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"
        },
        "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"
        },
        "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"
        },
        "auth_method": {
          "object": "provider.capabilities.auth_method",
          "id": "pam_2mNpQrStUvWxYzAb",
          "type": "oauth",
          "key": "oauth2",
          "name": "OAuth 2.0",
          "description": "Authenticate using OAuth 2.0",
          "capabilities": {},
          "input_schema": {
            "type": "json_schema",
            "schema": {}
          },
          "output_schema": {
            "type": "json_schema",
            "schema": {}
          },
          "scopes": [
            {
              "object": "provider.capabilities.auth_method.scope",
              "id": "pams_8tUvWxYzAbCdEfGh",
              "scope": "repo",
              "name": "Repository Access",
              "description": "Full control of private repositories"
            },
            {
              "object": "provider.capabilities.auth_method.scope",
              "id": "pams_8tUvWxYzAbCdEfGh",
              "scope": "repo",
              "name": "Repository Access",
              "description": "Full control of private repositories"
            }
          ],
          "provider_id": "pro_5gHjKlMnPqRsTuVw",
          "provider_specification_id": "psp_9gHjKlMnPqRsTuVw",
          "created_at": "2025-09-15T10:30:00.000Z",
          "updated_at": "2026-01-10T14:45:00.000Z"
        },
        "auth_credentials": {
          "object": "provider.auth_credentials",
          "id": "par_4sTuVwXyZaBcDeFg",
          "type": "oauth",
          "status": "active",
          "is_default": true,
          "is_managed": true,
          "name": "GitHub OAuth",
          "description": "OAuth credentials for GitHub API",
          "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"
        }
      },
      "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"
      }
    }
  ]
}

List integration instances

Returns a paginated list of integration instances.

Query Parameters

limit

NumberOptional

after

StringOptional

before

StringOptional

cursor

StringOptional

order

EnumOptional

StringOptional

status

UnionOptional

integration_id

UnionOptional

provider_id

UnionOptional

integration_provider_id

UnionOptional

identity_id

UnionOptional

identity_credential_id

UnionOptional

identity_actor_id

UnionOptional

provider_deployment_id

UnionOptional

provider_config_id

UnionOptional

provider_auth_config_id

UnionOptional

session_template_id

UnionOptional

created_at

ObjectOptional

Filter integration instance creation time by date range

updated_at

ObjectOptional

Filter integration instance last update time by date range

GEThttp://api.metorial.com/integration-instances

cURL

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

Get integration instance

Retrieves a specific integration instance.

URL Parameters

integration_instance_id

String

The unique identifier for the integration_instance

GEThttp://api.metorial.com/integration-instances/:integration_instance_id

cURL

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

Create integration instance session template

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

URL Parameters

integration_instance_id

String

The unique identifier for the integration_instance

Request Body

name

StringOptional

description

StringOptional

metadata

ObjectOptional

A key-value map

POSThttp://api.metorial.com/integration-instances/:integration_instance_id/session-template

cURL

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

Create integration instance session

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

URL Parameters

integration_instance_id

String

The unique identifier for the integration_instance

Request Body

name

StringOptional

description

StringOptional

metadata

ObjectOptional

A key-value map

POSThttp://api.metorial.com/integration-instances/:integration_instance_id/session

cURL

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

Create integration instance

Creates a new integration instance.

Request Body

integration_id

String

name

String

description

StringOptional

metadata

ObjectOptional

A key-value map

identity_actor_id

StringOptionalNullable

identity_id

StringOptionalNullable

providers

ObjectOptional

POSThttp://api.metorial.com/integration-instances

cURL

curl -X POST "https://api.metorial.com/integration-instances" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_..." \
  -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": {
    "provider_id": "example_provider_id",
    "provider_config_id": "example_provider_config_id",
    "provider_auth_config_id": "example_provider_auth_config_id",
    "tool_filters": {
      "type": "example_type",
      "keys": [
        "example_item"
      ]
    },
    "is_override_tool_filter": false
  }
}'

Update integration instance

Updates a specific integration instance.

URL Parameters

integration_instance_id

String

The unique identifier for the integration_instance

Request Body

name

StringOptional

description

StringOptionalNullable

metadata

ObjectOptionalNullable

A key-value map

identity_actor_id

StringOptionalNullable

identity_id

StringOptionalNullable

providers

ObjectOptional

PATCHhttp://api.metorial.com/integration-instances/:integration_instance_id

cURL

curl -X PATCH "https://api.metorial.com/integration-instances/int_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_..." \
  -d '{
  "name": "example_name",
  "description": "example_description",
  "metadata": {},
  "identity_actor_id": "example_identity_actor_id",
  "identity_id": "example_identity_id",
  "providers": {
    "provider_id": "example_provider_id",
    "provider_config_id": "example_provider_config_id",
    "provider_auth_config_id": "example_provider_auth_config_id",
    "tool_filters": {
      "type": "example_type",
      "keys": [
        "example_item"
      ]
    },
    "is_override_tool_filter": false
  }
}'

Delete integration instance

Archives a specific integration instance.

URL Parameters

integration_instance_id

String

The unique identifier for the integration_instance

DELETEhttp://api.metorial.com/integration-instances/:integration_instance_id

cURL

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