MetorialDocs

Integrations

Integrations define reusable provider contracts that can then be materialized into integration instances.

The Integration object

integration.json
{
  "object": "integration",
  "id": "example_id",
  "status": "active",
  "slug": "example_slug",
  "name": "example_name",
  "description": "example_description",
  "metadata": {},
  "configuration": {
    "can_attach_custom_tool_filters": false,
    "can_attach_custom_provider_config": false,
    "can_override_tool_filters": false,
    "use_integration_name_in_tool_names": false
  },
  "implementation": {
    "type": "provider_template",
    "provider_template_id": "example_provider_template_id"
  },
  "providers": [
    {
      "object": "integration.provider",
      "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"
      },
      "callbacks": {
        "object": "integration.provider.callbacks",
        "status": "enabled",
        "callback_id": "cbk_4dEfGhJkLmNpQrSt"
      }
    },
    {
      "object": "integration.provider",
      "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"
      },
      "callbacks": {
        "object": "integration.provider.callbacks",
        "status": "enabled",
        "callback_id": "cbk_4dEfGhJkLmNpQrSt"
      }
    }
  ],
  "created_at": "2026-09-11T20:30:32.736Z",
  "updated_at": "2026-09-11T20:30:32.736Z",
  "archived_at": "2026-09-11T20:30:32.736Z"
}
object"integration"required
idstringrequired
status"active" | "archived" | "deleted"required
slugstringrequired
namestringrequired
descriptionstringrequirednullable
metadataRecord<string, any>requirednullable
created_atdaterequired
updated_atdaterequired
archived_atdaterequirednullable

Endpoints

List integrations

GET/integrations

Returns a paginated list of integrations.

Query parameters

searchstringoptional
status"active" | "archived" | "deleted" or "active" | "archived" | "deleted"[]optional
idstring or string[]optional
provider_idstring or string[]optional
integration_provider_idstring or string[]optional

Example request

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

Get integration

GET/integrations/:integration_id

Retrieves a specific integration.

Path parameters

integration_idstringrequired

The unique identifier for the integration

Example request

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

Create integration

POST/integrations

Creates a new integration.

Request body

namestringrequired
descriptionstringoptional
metadataRecord<string, any>optional
use_integration_name_in_tool_namesbooleanoptionalnullable
can_attach_custom_tool_filtersbooleanoptional
can_attach_custom_provider_configbooleanoptional
can_override_tool_filtersbooleanoptional

Example request

curl -X POST "https://api.metorial.com/integrations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_io2h4..." \
  -d '{
  "name": "example_name",
  "description": "example_description",
  "metadata": {},
  "use_integration_name_in_tool_names": false,
  "can_attach_custom_tool_filters": false,
  "can_attach_custom_provider_config": false,
  "can_override_tool_filters": false
}'

Update integration

PATCH/integrations/:integration_id

Updates a specific integration.

Path parameters

integration_idstringrequired

The unique identifier for the integration

Request body

namestringoptional
descriptionstringoptionalnullable
metadataRecord<string, any>optionalnullable
use_integration_name_in_tool_namesbooleanoptionalnullable
can_attach_custom_tool_filtersbooleanoptional
can_attach_custom_provider_configbooleanoptional
can_override_tool_filtersbooleanoptional

Example request

curl -X PATCH "https://api.metorial.com/integrations/int_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_io2h4..." \
  -d '{
  "name": "example_name",
  "description": "example_description",
  "metadata": {},
  "use_integration_name_in_tool_names": false,
  "can_attach_custom_tool_filters": false,
  "can_attach_custom_provider_config": false,
  "can_override_tool_filters": false
}'

Delete integration

DELETE/integrations/:integration_id

Archives a specific integration.

Path parameters

integration_idstringrequired

The unique identifier for the integration

Example request

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