Upload a skill

TypeScript SDK

import { Client } from "@notionhq/client"

const notion = new Client({
  auth: process.env.NOTION_API_KEY,
  notionVersion: "2026-03-11"
})

import { readFile } from "fs/promises"

const skillId = "b55c9c91-384d-452b-81db-d1ef79372b75"
const response = await notion.request({
  method: "post",
  path: "ai/skills/" + encodeURIComponent(skillId) + "/upload",
  formDataParams: {
    file: {
      filename: "skill.tar.gz",
      data: new Blob([await readFile("./skill.tar.gz")], {
        type: "application/gzip"
      })
    }
  }
})

curl --request POST \
  --url https://api.notion.com/v1/ai/skills/{id}/upload \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --header 'Notion-Version: <notion-version>' \
  --form 'file={}'

import requests

url = "https://api.notion.com/v1/ai/skills/{id}/upload"

payload = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n{}\r\n-----011000010111000001101001--"
headers = {
    "Notion-Version": "<notion-version>",
    "Authorization": "Bearer <token>",
    "Content-Type": "multipart/form-data; boundary=---011000010111000001101001"
}

response = requests.post(url, data=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.notion.com/v1/ai/skills/{id}/upload",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n{}\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data; boundary=---011000010111000001101001",
    "Notion-Version: <notion-version>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.notion.com/v1/ai/skills/{id}/upload"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n{}\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Notion-Version", "<notion-version>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "multipart/form-data; boundary=---011000010111000001101001")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.notion.com/v1/ai/skills/{id}/upload")
  .header("Notion-Version", "<notion-version>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "multipart/form-data; boundary=---011000010111000001101001")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n{}\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.notion.com/v1/ai/skills/{id}/upload")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Notion-Version"] = '<notion-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'multipart/form-data; boundary=---011000010111000001101001'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n{}\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "status": "completed",
  "page_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "version_id": "<string>"
}

{
  "object": "error",
  "message": "<string>",
  "code": "invalid_json",
  "status": 400,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "unauthorized",
  "status": 401,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "restricted_resource",
  "status": 403,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "object_not_found",
  "status": 404,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "row_limit_exceeded",
  "status": 406,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "conflict_error",
  "status": 409,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "rate_limited",
  "status": 429,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "internal_server_error",
  "status": 500,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "service_unavailable",
  "status": 503,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "gateway_timeout",
  "status": 504,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "service_overload",
  "status": 529,
  "additional_data": {}
}

POST

skills

{id}

upload

TypeScript SDK

import { Client } from "@notionhq/client"

const notion = new Client({
  auth: process.env.NOTION_API_KEY,
  notionVersion: "2026-03-11"
})

import { readFile } from "fs/promises"

const skillId = "b55c9c91-384d-452b-81db-d1ef79372b75"
const response = await notion.request({
  method: "post",
  path: "ai/skills/" + encodeURIComponent(skillId) + "/upload",
  formDataParams: {
    file: {
      filename: "skill.tar.gz",
      data: new Blob([await readFile("./skill.tar.gz")], {
        type: "application/gzip"
      })
    }
  }
})

curl --request POST \
  --url https://api.notion.com/v1/ai/skills/{id}/upload \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --header 'Notion-Version: <notion-version>' \
  --form 'file={}'

import requests

url = "https://api.notion.com/v1/ai/skills/{id}/upload"

payload = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n{}\r\n-----011000010111000001101001--"
headers = {
    "Notion-Version": "<notion-version>",
    "Authorization": "Bearer <token>",
    "Content-Type": "multipart/form-data; boundary=---011000010111000001101001"
}

response = requests.post(url, data=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.notion.com/v1/ai/skills/{id}/upload",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n{}\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data; boundary=---011000010111000001101001",
    "Notion-Version: <notion-version>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.notion.com/v1/ai/skills/{id}/upload"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n{}\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Notion-Version", "<notion-version>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "multipart/form-data; boundary=---011000010111000001101001")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.notion.com/v1/ai/skills/{id}/upload")
  .header("Notion-Version", "<notion-version>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "multipart/form-data; boundary=---011000010111000001101001")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n{}\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.notion.com/v1/ai/skills/{id}/upload")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Notion-Version"] = '<notion-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'multipart/form-data; boundary=---011000010111000001101001'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n{}\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "status": "completed",
  "page_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "version_id": "<string>"
}

{
  "object": "error",
  "message": "<string>",
  "code": "invalid_json",
  "status": 400,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "unauthorized",
  "status": 401,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "restricted_resource",
  "status": 403,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "object_not_found",
  "status": 404,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "row_limit_exceeded",
  "status": 406,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "conflict_error",
  "status": 409,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "rate_limited",
  "status": 429,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "internal_server_error",
  "status": 500,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "service_unavailable",
  "status": 503,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "gateway_timeout",
  "status": 504,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "service_overload",
  "status": 529,
  "additional_data": {}
}

Imports a skill directory into an existing page in a Skills database. Pass the page ID in the path, and send a gzipped tar archive of the directory under the file key of a multipart/form-data body. The archive can be up to 20 MiB.

Like Send a file upload, this endpoint takes multipart form data instead of JSON. Include a boundary in the Content-Type header.

The archive must contain SKILL.md with name and description frontmatter, either at the root or in one directory named after the skill. Uploading replaces the page’s title, Description, content, and Files. Each file and folder next to SKILL.md becomes a file or folder in Files. The response includes the updated page ID and version_id. It matches the version_id from Get a skill until the skill changes again, so you can tell whether a later download returns what you uploaded. To import a new skill, create a page in a Skills database first.

Errors

Status	Code	Cause
400	`validation_error`	The ID is malformed, `file` is missing or not sent as form data, the archive is invalid, or the page is not in a Skills database.
403	`restricted_resource`	The token lacks the Read content, Insert content, or Update content capability.
404	`object_not_found`	No page with that ID is shared with the connection.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Notion-Version

enum<string>

required

The API version to use for this request. The latest version is 2026-03-11.

Available options:

2026-03-11

Path Parameters

string

required

Target page in a Skills database. Create a new page first to import a new skill.

Body

multipart/form-data

file

object

required

The skill directory as a gzip-compressed tar archive (maximum 20 MiB).

Response

status

string

required

Import committed.

Allowed value: "completed"

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.

Notion API

Objects

Endpoints

Webhook events

Errors

Authorizations

Headers

Path Parameters

Body

Response

​Errors

Authorizations

Headers

Path Parameters

Body

Response

Errors