---
title: "Upload a skill"
method: POST
path: "/v1/ai/skills/{id}/upload"
tags: ["Agent Skills"]
---

# Upload a skill

`POST /v1/ai/skills/{id}/upload`

## Request

- Base URL: `https://api.notion.com`
- URL: `https://api.notion.com/v1/ai/skills/{id}/upload`
- Auth: HTTP bearer

## Path parameters

- `id` string, required

## Headers

- `Notion-Version` '2026-03-11', required

## Request body `multipart/form-data`

- object
  - `file` object, required: The skill directory as a gzip-compressed tar archive (maximum 20 MiB).

## Response `200`

- object
  - `status` 'completed', required: Import committed.
  - `page_id` string, uuid, required: Updated skill page.
  - `version_id` string, required: Content version of the uploaded skill. Matches `version_id` from GET /v1/ai/skills/{id} until the skill changes.

## Other responses

- `400`
- `401`
- `403`
- `404`
- `406`
- `409`
- `429`
- `500`
- `503`
- `504`
- `529`

## Changes

- **2026-10-22** `3b8443976d60`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/notion/apis/notion-api/changes/v1/ai/skills/:id/upload/post.md)

---

[API](https://skmtc.dev/notion/apis/notion-api.md) - [All operations](https://skmtc.dev/notion/apis/notion-api/llms.txt) - [OpenAPI document](https://skmtc.dev/notion/apis/notion-api/revisions/8967a2a7b255?raw)