MetorialDocs

Provider Deployments

A deployment is a running instance of a provider, pinned to a specific version. Deployments support custom configuration values and user authentication.

The Provider Deployment object

provider_deployment.json
{
  "object": "provider.deployment",
  "id": "pde_1aBcDeFgHjKlMnPq",
  "status": "active",
  "is_default": false,
  "name": "Production",
  "description": "Production deployment",
  "metadata": {},
  "tool_filter": {
    "type": "allow_all",
    "ignore_parent_filters": false
  },
  "provider_id": "pro_5gHjKlMnPqRsTuVw",
  "locked_version": {
    "object": "provider.version",
    "id": "prv_4dEfGhJkLmNpQrSt",
    "version": "1.0.0",
    "provider_id": "pro_5gHjKlMnPqRsTuVw",
    "is_current": false,
    "name": "Version 1.0.0",
    "description": "example_description",
    "metadata": {},
    "specification_id": "psp_9gHjKlMnPqRsTuVw",
    "created_at": "2025-09-15T10:30:00.000Z",
    "updated_at": "2026-01-10T14:45:00.000Z"
  },
  "default_config": {
    "object": "provider.config#preview",
    "id": "pcf_7dEfGhJkLmNpQrSt",
    "is_default": false,
    "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"
  },
  "created_at": "2025-09-15T10:30:00.000Z",
  "updated_at": "2026-01-10T14:45:00.000Z"
}
object"provider.deployment"required
idstringrequired
status"active" | "archived" | "deleted"required
is_defaultbooleanrequired
namestringrequirednullable
descriptionstringrequirednullable
metadataRecord<string, any>requirednullable
provider_idstringrequired
created_atdaterequired
updated_atdaterequired

Endpoints

List provider deployments

GET/provider-deployments

Returns a paginated list of provider deployments.

Query parameters

idstring or string[]optional

Filter by deployment ID(s)

provider_idstring or string[]optional

Filter by provider ID(s)

provider_version_idstring or string[]optional

Filter by version ID(s)

actor_idstring or string[]optional

Filter by actor ID(s)

consumer_idstring or string[]optional

Filter by consumer ID(s)

identity_idstring or string[]optional

Filter by identity ID(s)

identity_credential_idstring or string[]optional

Filter by identity credential ID(s)

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

Filter by status (active, archived)

searchstringoptional

Search by name or description

Example request

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

Get provider deployment

GET/provider-deployments/:provider_deployment_id

Retrieves a specific provider deployment by ID.

Path parameters

provider_deployment_idstringrequired

The unique identifier for the provider_deployment

Example request

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

Create provider deployment

POST/provider-deployments

Creates a new provider deployment.

Request body

namestringoptional
descriptionstringoptional
metadataRecord<string, any>optional

Custom key-value pairs for storing additional information

provider_idstringrequired

The provider to deploy

locked_provider_version_idstringoptional

Pin this deployment to a specific provider version

provider_config_idstringoptional

Existing provider config ID

Example request

curl -X POST "https://api.metorial.com/provider-deployments" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_io2h4..." \
  -d '{
  "name": "example_name",
  "description": "example_description",
  "metadata": {},
  "tool_filters": {
    "type": "tool_keys",
    "keys": [
      "example_keys"
    ]
  },
  "provider_id": "example_provider_id",
  "locked_provider_version_id": "example_locked_provider_version_id",
  "provider_config_id": "example_provider_config_id"
}'

Update provider deployment

PATCH/provider-deployments/:provider_deployment_id

Updates a specific provider deployment.

Path parameters

provider_deployment_idstringrequired

The unique identifier for the provider_deployment

Request body

namestringoptional
descriptionstringoptional
metadataRecord<string, any>optional

Custom key-value pairs for storing additional information

locked_provider_version_idstringoptionalnullable

Pin this deployment to a specific provider version, or null to follow latest

Example request

curl -X PATCH "https://api.metorial.com/provider-deployments/pro_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_io2h4..." \
  -d '{
  "name": "Updated Deployment Name",
  "description": "Updated description for this deployment",
  "metadata": {},
  "tool_filters": {
    "type": "tool_keys",
    "keys": [
      "example_keys"
    ]
  },
  "locked_provider_version_id": "prv_4dEfGhJkLmNpQrSt"
}'

Delete provider deployment

DELETE/provider-deployments/:provider_deployment_id

Permanently deletes a provider deployment.

Path parameters

provider_deployment_idstringrequired

The unique identifier for the provider_deployment

Example request

curl -X DELETE "https://api.metorial.com/provider-deployments/pro_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Authorization: Bearer metorial_sk_io2h4..."