MetorialDocs

Provider Specifications

A specification defines what a provider version can do: its tools, auth methods, and required configuration fields.

The Provider Specification object

provider_specification.json
{
  "object": "provider.specification",
  "id": "psp_9gHjKlMnPqRsTuVw",
  "key": "github",
  "name": "GitHub",
  "description": "GitHub API integration",
  "config_schema": {},
  "config_visibility": "encrypted",
  "tools": [
    {
      "object": "provider.tool",
      "id": "pto_5jKlMnPqRsTuVwXy",
      "key": "create_issue",
      "name": "Create Issue",
      "description": "Creates a new issue in a GitHub repository",
      "capabilities": {},
      "input_schema": {
        "type": "json_schema",
        "schema": {}
      },
      "output_schema": {
        "type": "json_schema",
        "schema": {}
      },
      "tags": {},
      "tool_category_keys": [
        "crm"
      ],
      "specification_id": "psp_9gHjKlMnPqRsTuVw",
      "provider_id": "pro_5gHjKlMnPqRsTuVw",
      "created_at": "2025-09-15T10:30:00.000Z",
      "updated_at": "2026-01-10T14:45:00.000Z"
    },
    {
      "object": "provider.tool",
      "id": "pto_5jKlMnPqRsTuVwXy",
      "key": "create_issue",
      "name": "Create Issue",
      "description": "Creates a new issue in a GitHub repository",
      "capabilities": {},
      "input_schema": {
        "type": "json_schema",
        "schema": {}
      },
      "output_schema": {
        "type": "json_schema",
        "schema": {}
      },
      "tags": {},
      "tool_category_keys": [
        "crm"
      ],
      "specification_id": "psp_9gHjKlMnPqRsTuVw",
      "provider_id": "pro_5gHjKlMnPqRsTuVw",
      "created_at": "2025-09-15T10:30:00.000Z",
      "updated_at": "2026-01-10T14:45:00.000Z"
    }
  ],
  "tool_categories": [
    {
      "object": "provider.tool_category",
      "key": "crm",
      "name": "Zoho CRM",
      "description": "Manage leads, contacts, deals and other CRM records",
      "image_url": "https://provider-logos.metorial-cdn.com/zoho-crm.svg",
      "tool_count": 24
    },
    {
      "object": "provider.tool_category",
      "key": "crm",
      "name": "Zoho CRM",
      "description": "Manage leads, contacts, deals and other CRM records",
      "image_url": "https://provider-logos.metorial-cdn.com/zoho-crm.svg",
      "tool_count": 24
    }
  ],
  "auth_methods": [
    {
      "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"
    },
    {
      "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"
    }
  ],
  "provider_id": "pro_5gHjKlMnPqRsTuVw",
  "created_at": "2025-09-15T10:30:00.000Z",
  "updated_at": "2026-01-10T14:45:00.000Z"
}
object"provider.specification"required
idstringrequired
keystringrequired
namestringrequired
descriptionstringrequirednullable
config_schemaRecord<string, any>required
config_visibility"encrypted" | "plain"required
provider_idstringrequired
created_atdaterequired
updated_atdaterequired

Endpoints

List provider specifications

GET/provider-specifications

Returns a paginated list of provider specifications.

Query parameters

idstring or string[]optional

Filter by specification ID(s)

provider_idstring or string[]optional

Filter by provider ID(s)

provider_version_idstring or string[]optional

Filter by provider version ID(s)

provider_deployment_idstring or string[]optional

Filter by provider deployment ID(s)

provider_config_idstring or string[]optional

Filter by provider config ID(s)

Example request

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

Get provider specification

GET/provider-specifications/:provider_specification_id

Retrieves a specific provider specification by ID.

Path parameters

provider_specification_idstringrequired

The unique identifier for the provider_specification

Example request

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