MetorialDocs

Custom Provider Versions

Versions represent different releases of a custom provider. Each version can be deployed to environments.

The Custom Provider Version object

custom_provider_version.json
{
  "object": "custom_provider.version",
  "id": "cpv_1aBcDeFgHjKlMnPq",
  "status": "queued",
  "config": {
    "object": "custom_provider.version.config",
    "schema": {
      "type": "json_schema",
      "schema": {}
    },
    "transformer": "example_transformer"
  },
  "index": 1,
  "identifier": "v1.0.0",
  "deployment": {
    "object": "custom_provider.deployment",
    "id": "cpd_1aBcDeFgHjKlMnPq",
    "status": "failed",
    "trigger": "manual",
    "custom_provider_id": "cpr_1aBcDeFgHjKlMnPq",
    "provider_id": "pro_5gHjKlMnPqRsTuVw",
    "custom_provider_version_id": "cpv_1aBcDeFgHjKlMnPq",
    "commit": {
      "object": "custom_provider.deployment.commit",
      "id": "example_id",
      "type": "create_version",
      "message": "example_message",
      "created_at": "2026-10-17T09:50:02.656Z"
    },
    "immutable_bucket": {
      "object": "bucket",
      "id": "example_id",
      "is_immutable": false,
      "is_read_only": false,
      "scm_repo_link": {
        "object": "bucket.scm_repo",
        "is_linked": true,
        "path": "example_path",
        "repository": {
          "object": "scm.repository",
          "id": "example_id",
          "provider": {
            "object": "scm.provider",
            "type": "github",
            "id": "example_id",
            "name": "example_name",
            "owner": "example_owner"
          },
          "url": "example_url",
          "is_private": false,
          "default_branch": "example_default_branch",
          "created_at": "2026-10-17T09:50:02.656Z"
        }
      },
      "created_at": "2026-10-17T09:50:02.656Z"
    },
    "actor": {
      "object": "custom_provider.actor#preview",
      "id": "act_1aBcDeFgHjKlMnPq",
      "type": "external",
      "identifier": "mtea-orgact_1aBcDeFgHjKlMnPq",
      "name": "John Doe",
      "organization_actor_id": "ora_1aBcDeFgHjKlMnPq",
      "created_at": "2025-09-15T10:30:00.000Z"
    },
    "scm_push": {
      "object": "scm.push",
      "id": "example_id",
      "actor": {
        "object": "scm.actor",
        "id": "example_id",
        "external_id": "example_external_id",
        "name": "example_name",
        "email": "example_email"
      },
      "commit": {
        "object": "scm.commit",
        "id": "example_id",
        "sha": "example_sha",
        "branch": "example_branch",
        "message": "example_message",
        "created_at": "2026-10-17T09:50:02.656Z"
      },
      "repository": {
        "object": "scm.repository",
        "id": "example_id",
        "provider": {
          "object": "scm.provider",
          "type": "github",
          "id": "example_id",
          "name": "example_name",
          "owner": "example_owner"
        },
        "url": "example_url",
        "is_private": false,
        "default_branch": "example_default_branch",
        "created_at": "2026-10-17T09:50:02.656Z"
      },
      "created_at": "2026-10-17T09:50:02.656Z"
    },
    "created_at": "2025-09-15T10:30:00.000Z",
    "updated_at": "2026-01-10T14:45:00.000Z"
  },
  "environments": [
    {
      "object": "custom_provider.environment",
      "id": "cpenv_1aBcDeFgHjKlMnPq",
      "environment": {
        "object": "custom_provider.environment",
        "id": "cpenv_1aBcDeFgHjKlMnPq",
        "custom_provider_id": "cpr_1aBcDeFgHjKlMnPq",
        "provider_id": "pro_5gHjKlMnPqRsTuVw",
        "current_provider_version_id": "prv_4dEfGhJkLmNpQrSt",
        "instance_id": "ins_2cDeFgHjKlMnPqRs",
        "created_at": "2025-09-15T10:30:00.000Z",
        "updated_at": "2026-01-10T14:45:00.000Z"
      }
    },
    {
      "object": "custom_provider.environment",
      "id": "cpenv_1aBcDeFgHjKlMnPq",
      "environment": {
        "object": "custom_provider.environment",
        "id": "cpenv_1aBcDeFgHjKlMnPq",
        "custom_provider_id": "cpr_1aBcDeFgHjKlMnPq",
        "provider_id": "pro_5gHjKlMnPqRsTuVw",
        "current_provider_version_id": "prv_4dEfGhJkLmNpQrSt",
        "instance_id": "ins_2cDeFgHjKlMnPqRs",
        "created_at": "2025-09-15T10:30:00.000Z",
        "updated_at": "2026-01-10T14:45:00.000Z"
      }
    }
  ],
  "custom_provider_id": "cpr_1aBcDeFgHjKlMnPq",
  "provider_id": "pro_5gHjKlMnPqRsTuVw",
  "actor": {
    "object": "custom_provider.actor#preview",
    "id": "act_1aBcDeFgHjKlMnPq",
    "type": "external",
    "identifier": "mtea-orgact_1aBcDeFgHjKlMnPq",
    "name": "John Doe",
    "organization_actor_id": "ora_1aBcDeFgHjKlMnPq",
    "created_at": "2025-09-15T10:30:00.000Z"
  },
  "container_image": {
    "container_registry": "https://index.docker.io/v1/",
    "container_image_tag": "v1.0.0",
    "container_image": "my-app-image"
  },
  "remote_mcp_server": {
    "url": "https://mcp.example.com",
    "transport": "grpc"
  },
  "created_at": "2025-09-15T10:30:00.000Z",
  "updated_at": "2026-01-10T14:45:00.000Z"
}
object"custom_provider.version"required
idstringrequired
status"queued" | "deploying" | "deployment_succeeded" | "deployment_failed"required
indexnumberrequired
identifierstringrequired
custom_provider_idstringrequired
provider_idstringrequirednullable
created_atdaterequired
updated_atdaterequired

Endpoints

List custom provider versions

GET/custom-provider-versions

Returns a paginated list of versions for a custom provider.

Query parameters

status"queued" | "deploying" | "deployment_succeeded" | "deployment_failed" or "queued" | "deploying" | "deployment_succeeded" | "deployment_failed"[]optional

Filter by deployment status

idstring or string[]optional

Filter by version ID(s)

provider_idstring or string[]optional

Filter by provider IDs (matches providers connected to sessions)

provider_version_idstring or string[]optional

Filter by provider version IDs (matches providers connected to sessions)

custom_provider_idstring or string[]optional

Filter by custom provider IDs (matches providers connected to sessions)

custom_provider_deployment_idstring or string[]optional

Filter by custom provider deployment IDs (matches providers connected to sessions)

custom_provider_environment_idstring or string[]optional

Filter by custom provider environment IDs (matches providers connected to sessions)

Example request

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

Get custom provider version

GET/custom-provider-versions/:custom_provider_version_id

Retrieves a specific version of a custom provider.

Path parameters

custom_provider_version_idstringrequired

The unique identifier for the custom_provider_version

Example request

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

Get custom provider version environment

GET/custom-provider-versions/:custom_provider_version_id/env

Retrieves the environment variables for a specific version of a custom provider.

Path parameters

custom_provider_version_idstringrequired

The unique identifier for the custom_provider_version

Example request

curl -X GET "https://api.metorial.com/custom-provider-versions/cus_Rm4Mnheq2bfEPhBhP7SY/env" \
  -H "Authorization: Bearer metorial_sk_io2h4..."

Create custom provider version

POST/custom-provider-versions

Creates a new version for a custom provider.

Request body

custom_provider_idstringrequired

Custom provider ID

Example request

curl -X POST "https://api.metorial.com/custom-provider-versions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_io2h4..." \
  -d '{
  "custom_provider_id": "cp_1aBcDeFgHjKlMnPq",
  "from": {
    "type": "container",
    "image_ref": "example_image_ref",
    "username": "example_username",
    "password": "example_password"
  },
  "config": {
    "schema": {},
    "transformer": "example_transformer"
  }
}'