Agent Skills API

The Agent Skills API exposes skills stored in Notion as directories of files. You can either download individual skills following the Agent Skills standard, or groups of related skills following the Agent Plugins standard. Teams use Notion as a skills library to edit, review, and share skills. Each skill’s main SKILL.md file is a Notion page. Supporting files and folders can be attached through its Files property. For one example of how to use the API, see the notion-skills-github-sync sample repo, which sets up a recurring script that syncs skills from Notion into a GitHub plugin marketplace, which can further be synced into Claude, ChatGPT, or other agents.

List plugins

List available plugins

Get a plugin

Download a single plugin

Get a skill

Download a single skill

Requirements

You have a connection token or personal access token with the Read content capability.
The connection has access to the skill databases you expect to see. Skills not shared with the connection are omitted.
Requests send Notion-Version: 2026-03-11.

Sync workflow

Here is an example of a common usage pattern for this API: syncing all plugins from a workspace to a local directory.

List plugins

Call List plugins and page through the results. Each entry has an id, name, description, and version_id.

cURL

curl -X GET "https://api.notion.com/v1/ai/plugins?page_size=100" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2026-03-11"

Response

{
  "object": "list",
  "results": [
    {
      "id": "b2d0a1f4-9c3e-4c07-9a1d-5f6e7c8b9a01",
      "name": "Engineering",
      "description": "Skills for engineering workflows.",
      "version_id": "ba9d2c7735c0029282f9f8e7bef99b438c51ad416f82ca8a8d6ce56c5a1fa95c"
    },
    {
      "id": "1a7f3c92-4de8-4b15-8c60-2e9d4f0a6b73",
      "name": "Weekly status update",
      "description": "Write the Monday status update from last week's project pages.",
      "version_id": "43dd93dd612651c00ebbaa9ca5fad10d845e2b145aba8ac219033654d6a58c93"
    }
  ],
  "next_cursor": null,
  "has_more": false,
  "type": "plugin",
  "request_id": "b7c1fd7e-2c84-4f55-877e-d3ad7db2ac4b"
}

The first result is a tagged plugin holding every skill tagged Engineering. The second is an untagged skill, which becomes a plugin of its own.

Compare version_id values

Compare each plugin’s version_id against the value you stored the last time you downloaded it. Equal values mean the plugin has not changed and you can skip it. Only after all pages have been fetched successfully, remove local directories for plugin IDs missing from the complete list. An incomplete or failed listing must not delete local plugins.

Fetch changed plugin directories

For each plugin whose version_id changed, call Get a plugin directory to receive a signed URL.

cURL

curl -X GET "https://api.notion.com/v1/ai/plugins/$PLUGIN_ID" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2026-03-11"

Response

{
  "id": "b2d0a1f4-9c3e-4c07-9a1d-5f6e7c8b9a01",
  "version_id": "ba9d2c7735c0029282f9f8e7bef99b438c51ad416f82ca8a8d6ce56c5a1fa95c",
  "url": "https://s3.us-west-2.amazonaws.com/notion-temporary-files/public-api/plugin-directories/b2d0a1f4-9c3e-4c07-9a1d-5f6e7c8b9a01/ba9d2c7735c0029282f9f8e7bef99b438c51ad416f82ca8a8d6ce56c5a1fa95c/engineering.tar.gz?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600&X-Amz-Signature=...",
  "request_id": "91a4ee8c-61f6-4c27-bd41-09aa35299929"
}

Download and extract the archive

Set SIGNED_URL to the url from the previous response, then download and extract the gzipped tar archive into your plugins directory.

cURL

mkdir -p ./plugins
curl --fail --location "$SIGNED_URL" -o plugin.tar.gz &&
  tar -xzf plugin.tar.gz -C ./plugins

plugins/engineering/
├── plugin.json
└── skills/
    ├── code-review/
    │   ├── SKILL.md
    │   └── checklist.pdf
    └── incident-postmortem/
        └── SKILL.md

For a complete example of a sync script, see notion-skills-github-sync.

Get started

Agent APIs

API versions

Data APIs

Resources

Compliance

Link previews

List plugins

Get a plugin

Get a skill

Requirements

Sync workflow

List plugins

Get a plugin

Get a skill

​Requirements

​Sync workflow

Requirements

Sync workflow