Skills API | Metorial Docs

The Skill object

skill.json

{
  "object": "skill",
  "id": "example_id",
  "status": "active",
  "slug": "example_slug",
  "name": "example_name",
  "description": "example_description",
  "image_url": "example_image_url",
  "client_name": "example_client_name",
  "client_description": "example_client_description",
  "client_metadata": {},
  "license": "example_license",
  "compatibility": "example_compatibility",
  "metadata": {},
  "store_id": "example_store_id",
  "hierarchy": {
    "object": "skill.hierarchy",
    "type": "root",
    "parent_skill_id": "example_parent_skill_id",
    "creator": {
      "type": "organization_actor",
      "name": "example_name",
      "image_url": "example_image_url",
      "email": "example_email",
      "organization_actor": {
        "object": "organization.actor",
        "id": "omem_5fGhJkLmNpQrStUv",
        "type": "member",
        "organization_id": "org_7hNkPqRsTuVwXyZa",
        "name": "Alex Chen",
        "email": "[email protected]",
        "image_url": "https://avatar-cdn.metorial.com/aimg_1234567890",
        "member": {
          "object": "organization.member#preview",
          "id": "ome_7hNkPqRsTuVwXyZa",
          "status": "active",
          "role": "member"
        },
        "teams": [
          {
            "id": "tm_3eFgHjKlMnPqRsTu",
            "name": "Engineering",
            "slug": "engineering",
            "assignment_id": "tmas_8jKlMnPqRsTuVwXy"
          },
          {
            "id": "tm_3eFgHjKlMnPqRsTu",
            "name": "Engineering",
            "slug": "engineering",
            "assignment_id": "tmas_8jKlMnPqRsTuVwXy"
          }
        ],
        "created_at": "2026-09-11T20:30:32.776Z",
        "updated_at": "2026-09-11T20:30:32.776Z"
      },
      "consumer": {
        "object": "consumer",
        "id": "example_id",
        "name": "example_name",
        "email": "example_email",
        "image_url": "example_image_url",
        "user_id": "example_user_id",
        "created_at": "2026-09-11T20:30:32.776Z",
        "updated_at": "2026-09-11T20:30:32.776Z"
      },
      "consumer_profile": {
        "object": "consumer.profile",
        "id": "example_id",
        "name": "example_name",
        "email": "example_email",
        "image_url": "example_image_url",
        "consumer_id": "example_consumer_id",
        "user_id": "example_user_id",
        "status": "active",
        "created_at": "2026-09-11T20:30:32.776Z",
        "updated_at": "2026-09-11T20:30:32.776Z",
        "groups": [
          {
            "object": "consumer.profile.group_assignment",
            "group": {
              "object": "consumer.group",
              "id": "example_id",
              "status": "active",
              "name": "example_name",
              "description": "example_description",
              "is_default": false,
              "created_at": "2026-09-11T20:30:32.776Z",
              "updated_at": "2026-09-11T20:30:32.776Z"
            },
            "assigned_via": "default"
          }
        ]
      }
    },
    "fork": {
      "id": "example_id",
      "parent_skill_id": "example_parent_skill_id",
      "creator": {
        "type": "organization_actor",
        "name": "example_name",
        "image_url": "example_image_url",
        "email": "example_email",
        "organization_actor": {
          "object": "organization.actor",
          "id": "omem_5fGhJkLmNpQrStUv",
          "type": "member",
          "organization_id": "org_7hNkPqRsTuVwXyZa",
          "name": "Alex Chen",
          "email": "[email protected]",
          "image_url": "https://avatar-cdn.metorial.com/aimg_1234567890",
          "member": {
            "object": "organization.member#preview",
            "id": "ome_7hNkPqRsTuVwXyZa",
            "status": "active",
            "role": "member"
          },
          "teams": [
            {
              "id": "tm_3eFgHjKlMnPqRsTu",
              "name": "Engineering",
              "slug": "engineering",
              "assignment_id": "tmas_8jKlMnPqRsTuVwXy"
            },
            {
              "id": "tm_3eFgHjKlMnPqRsTu",
              "name": "Engineering",
              "slug": "engineering",
              "assignment_id": "tmas_8jKlMnPqRsTuVwXy"
            }
          ],
          "created_at": "2026-09-11T20:30:32.776Z",
          "updated_at": "2026-09-11T20:30:32.776Z"
        },
        "consumer": {
          "object": "consumer",
          "id": "example_id",
          "name": "example_name",
          "email": "example_email",
          "image_url": "example_image_url",
          "user_id": "example_user_id",
          "created_at": "2026-09-11T20:30:32.776Z",
          "updated_at": "2026-09-11T20:30:32.776Z"
        },
        "consumer_profile": {
          "object": "consumer.profile",
          "id": "example_id",
          "name": "example_name",
          "email": "example_email",
          "image_url": "example_image_url",
          "consumer_id": "example_consumer_id",
          "user_id": "example_user_id",
          "status": "active",
          "created_at": "2026-09-11T20:30:32.776Z",
          "updated_at": "2026-09-11T20:30:32.776Z",
          "groups": [
            {
              "object": "consumer.profile.group_assignment",
              "group": {
                "object": "consumer.group",
                "id": "example_id",
                "status": "active",
                "name": "example_name",
                "description": "example_description",
                "is_default": false,
                "created_at": "2026-09-11T20:30:32.776Z",
                "updated_at": "2026-09-11T20:30:32.776Z"
              },
              "assigned_via": "default"
            }
          ]
        }
      },
      "original_creator": {
        "type": "organization_actor",
        "name": "example_name",
        "image_url": "example_image_url",
        "email": "example_email",
        "organization_actor": {
          "object": "organization.actor",
          "id": "omem_5fGhJkLmNpQrStUv",
          "type": "member",
          "organization_id": "org_7hNkPqRsTuVwXyZa",
          "name": "Alex Chen",
          "email": "[email protected]",
          "image_url": "https://avatar-cdn.metorial.com/aimg_1234567890",
          "member": {
            "object": "organization.member#preview",
            "id": "ome_7hNkPqRsTuVwXyZa",
            "status": "active",
            "role": "member"
          },
          "teams": [
            {
              "id": "tm_3eFgHjKlMnPqRsTu",
              "name": "Engineering",
              "slug": "engineering",
              "assignment_id": "tmas_8jKlMnPqRsTuVwXy"
            },
            {
              "id": "tm_3eFgHjKlMnPqRsTu",
              "name": "Engineering",
              "slug": "engineering",
              "assignment_id": "tmas_8jKlMnPqRsTuVwXy"
            }
          ],
          "created_at": "2026-09-11T20:30:32.776Z",
          "updated_at": "2026-09-11T20:30:32.776Z"
        },
        "consumer": {
          "object": "consumer",
          "id": "example_id",
          "name": "example_name",
          "email": "example_email",
          "image_url": "example_image_url",
          "user_id": "example_user_id",
          "created_at": "2026-09-11T20:30:32.776Z",
          "updated_at": "2026-09-11T20:30:32.776Z"
        },
        "consumer_profile": {
          "object": "consumer.profile",
          "id": "example_id",
          "name": "example_name",
          "email": "example_email",
          "image_url": "example_image_url",
          "consumer_id": "example_consumer_id",
          "user_id": "example_user_id",
          "status": "active",
          "created_at": "2026-09-11T20:30:32.776Z",
          "updated_at": "2026-09-11T20:30:32.776Z",
          "groups": [
            {
              "object": "consumer.profile.group_assignment",
              "group": {
                "object": "consumer.group",
                "id": "example_id",
                "status": "active",
                "name": "example_name",
                "description": "example_description",
                "is_default": false,
                "created_at": "2026-09-11T20:30:32.776Z",
                "updated_at": "2026-09-11T20:30:32.776Z"
              },
              "assigned_via": "default"
            }
          ]
        }
      },
      "created_at": "2026-09-11T20:30:32.776Z"
    },
    "entity": {
      "object": "skill.entity",
      "id": "example_id",
      "name": "example_name",
      "slug": "example_slug",
      "description": "example_description",
      "parent_skill_id": "example_parent_skill_id",
      "created_at": "2026-09-11T20:30:32.776Z",
      "updated_at": "2026-09-11T20:30:32.776Z"
    }
  },
  "integrations": [
    {
      "object": "integration#preview",
      "metadata": {},
      "configuration": {}
    },
    {
      "object": "integration#preview",
      "metadata": {},
      "configuration": {}
    }
  ],
  "providers": [
    {
      "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"
    },
    {
      "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"
    }
  ],
  "created_at": "2026-09-11T20:30:32.776Z",
  "updated_at": "2026-09-11T20:30:32.776Z"
}

object"skill"required

idstringrequired

status"active" | "archived" | "deleted"required

slugstringrequired

namestringrequired

descriptionstringrequirednullable

image_urlstringrequired

client_namestringrequired

client_descriptionstringrequirednullable

client_metadataRecord<string, any>requirednullable

licensestringrequirednullable

compatibilitystringrequirednullable

metadataRecord<string, any>required

store_idstringrequired

hierarchyobjectrequired

integrationsobject[]required

providersobject[]required

created_atdaterequired

updated_atdaterequired

Endpoints

List skills

GET/skills

Returns a paginated list of skills.

Query parameters

searchstringoptional

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

idstring or string[]optional

skill_group_idstring or string[]optional

integration_idstring or string[]optional

provider_idstring or string[]optional

created_atobjectoptional

Filter skill creation time by date range

updated_atobjectoptional

Filter skill last update time by date range

Example request

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

Get skill

GET/skills/:skill_id

Retrieves a specific skill.

Path parameters

skill_idstringrequired

The unique identifier for the skill

Example request

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

Create skill

POST/skills

Creates a new skill.

Request body

namestringrequired

descriptionstringoptional

metadataRecord<string, any>optional

client_namestringoptional

client_descriptionstringoptional

licensestringoptional

compatibilitystringoptional

client_metadataRecord<string, any>optional

image_file_idstringoptionalnullable

template_idstringoptional

skill_group_idstringoptional

Example request

curl -X POST "https://api.metorial.com/skills" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_io2h4..." \
  -d '{
  "name": "example_name",
  "description": "example_description",
  "metadata": {},
  "client_name": "example_client_name",
  "client_description": "example_client_description",
  "license": "example_license",
  "compatibility": "example_compatibility",
  "client_metadata": {},
  "image_file_id": "example_image_file_id",
  "template_id": "example_template_id",
  "skill_group_id": "example_skill_group_id"
}'

Update skill

PATCH/skills/:skill_id

Updates a specific skill.

Path parameters

skill_idstringrequired

The unique identifier for the skill

Request body

namestringoptional

descriptionstringoptionalnullable

client_namestringoptional

client_descriptionstringoptional

licensestringoptionalnullable

compatibilitystringoptionalnullable

client_metadataRecord<string, any>optionalnullable

metadataRecord<string, any>optionalnullable

image_file_idstringoptionalnullable

Example request

curl -X PATCH "https://api.metorial.com/skills/ski_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_io2h4..." \
  -d '{
  "name": "example_name",
  "description": "example_description",
  "client_name": "example_client_name",
  "client_description": "example_client_description",
  "license": "example_license",
  "compatibility": "example_compatibility",
  "client_metadata": {},
  "metadata": {},
  "image_file_id": "example_image_file_id"
}'

Delete skill

DELETE/skills/:skill_id

Archives a specific skill.

Path parameters

skill_idstringrequired

The unique identifier for the skill

Example request

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

POST/skills/:skill_id/shares

Shares a skill with consumers or organization members.

Path parameters

skill_idstringrequired

The unique identifier for the skill

Request body

consumer_profile_idsstring[]optional

organization_member_idsstring[]optional

permission"none" | "read" | "write"required

Example request

curl -X POST "https://api.metorial.com/skills/ski_Rm4Mnheq2bfEPhBhP7SY/shares" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_io2h4..." \
  -d '{
  "consumer_profile_ids": [
    "example_consumer_profile_ids"
  ],
  "organization_member_ids": [
    "example_organization_member_ids"
  ],
  "permission": "none"
}'

Duplicate skill

POST/skills/:skill_id/duplicate

Duplicates a skill.

Path parameters

skill_idstringrequired

The unique identifier for the skill

Request body

namestringrequired

descriptionstringoptional

client_namestringoptional

client_descriptionstringoptional

licensestringoptional

compatibilitystringoptional

client_metadataRecord<string, any>optional

metadataRecord<string, any>optional

Example request

curl -X POST "https://api.metorial.com/skills/ski_Rm4Mnheq2bfEPhBhP7SY/duplicate" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_io2h4..." \
  -d '{
  "name": "example_name",
  "description": "example_description",
  "client_name": "example_client_name",
  "client_description": "example_client_description",
  "license": "example_license",
  "compatibility": "example_compatibility",
  "client_metadata": {},
  "metadata": {}
}'

The Skill object

Endpoints

List skills

Query parameters

Example request

Get skill

Path parameters

Example request

Create skill

Request body

Example request

Update skill

Path parameters

Request body

Example request

Delete skill

Path parameters

Example request

Share skill

Path parameters

Request body

Example request

Duplicate skill

Path parameters

Request body

Example request