Figshare Skill
Interact with the Figshare v2 REST API to search, download, create, and upload research outputs.
Prerequisites
- -
curl and jq available on PATH. - For authenticated endpoints (anything under
/account/... or uploads), a personal token from https://figshare.com/account/applications exported as:
CODEBLOCK0
- - Public endpoints (search, public articles, downloads) need no token.
Always confirm with the user before creating, modifying, publishing, or deleting anything on their account — these are hard to reverse.
API Basics
- - Base URL: INLINECODE3
- Auth header: INLINECODE4
- Content-Type:
application/json for POST/PUT bodies - Rate limit: keep it under ~1 request/second to avoid abuse throttling
- Errors: JSON body with
message, code; common codes 400/401/403/404/422
Common Recipes
Search public articles
CODEBLOCK1
Field operators: :title:, :author:, :tag:, :category:, :doi:, :resource_doi:.
Get a public article (by ID or DOI)
CODEBLOCK2
Download all files from a public article
CODEBLOCK3
List your own articles
CODEBLOCK4
Create an article (draft)
CODEBLOCK5
Response is { "location": ".../account/articles/{id}", "entity_id": 123 }.
Update / publish an article
CODEBLOCK6
Always ask before publishing — it's permanent for that version.
Collections & projects
CODEBLOCK7
Uploading Files (Multi-part Flow)
Figshare uploads are 3-step: initiate → PUT each part → complete. Use the bundled helpers for anything non-trivial:
CODEBLOCK8
The raw flow, in case you need to adapt it:
- 1. Initiate — compute md5 + size, POST to article:
CODEBLOCK9
Response has location pointing at /account/articles/$ART/files/$FILE_ID.
- 2. Fetch upload info from that file record — it contains an
upload_url. GET the upload_url to learn the part layout (parts: [{partNo, startOffset, endOffset}]).
- 3. Upload parts — for each part, PUT the byte range to
${upload_url}/${partNo}:
CODEBLOCK10
- 4. Complete — POST to the file record to finalize:
CODEBLOCK11
Why three steps: Figshare streams large files through a separate upload service. Skipping the complete call leaves the file in a pending state and it won't appear on the article.
Pagination
Most list endpoints accept either page+page_size or limit+offset. Max page_size is typically 1000. For large harvests, loop until an empty page:
CODEBLOCK12
Troubleshooting
- - 401 — token missing/expired; re-check
$FIGSHARE_TOKEN. - 403 on
/account/... — token lacks the needed scope; regenerate with full permissions. - 422 on article create — missing required field (usually
title) or bad categories/defined_type. - Upload parts mismatch — md5 or size in step 1 didn't match the bytes actually uploaded; recompute and restart.
- Published article won't update — publishing freezes a version; create a new version instead.
References
- - API reference: https://docs.figshare.com/
- Token management: https://figshare.com/account/applications
- Category IDs: INLINECODE30
- License IDs: INLINECODE31
Figshare 技能
与 Figshare v2 REST API 交互，实现研究成果的搜索、下载、创建和上传。
前提条件
- - 系统 PATH 中需包含 curl 和 jq。
- 对于需要身份验证的端点（/account/... 路径下的所有内容或上传操作），需从 https://figshare.com/account/applications 获取个人令牌，并导出为：
bash
export FIGSHARE_TOKEN=xxxxxxxxxxxxxxxx
在创建、修改、发布或删除用户账户中的任何内容前，务必先与用户确认——这些操作难以撤销。
API 基础
- - 基础 URL： https://api.figshare.com/v2
- 认证头： Authorization: token $FIGSHARE_TOKEN
- 内容类型： POST/PUT 请求体使用 application/json
- 速率限制： 保持约每秒1次请求以下，避免触发滥用限制
- 错误处理： JSON 响应体包含 message 和 code；常见状态码为 400/401/403/404/422
常用操作
搜索公开文章
bash
curl -s -X POST https://api.figshare.com/v2/articles/search \
-H Content-Type: application/json \
-d {searchfor: :title: single cell, pagesize: 20} | jq
字段操作符：:title:、:author:、:tag:、:category:、:doi:、:resource_doi:。
获取公开文章（按 ID 或 DOI）
bash
curl -s https://api.figshare.com/v2/articles/{article_id} | jq
或从 figshare.com URL 解析：URL 末尾的数字即为 article_id
下载公开文章的所有文件
bash
ART=12345678
curl -s https://api.figshare.com/v2/articles/$ART/files \
| jq -r .[] | \(.download_url)\t\(.name) \
| while IFS=$\t read -r url name; do curl -L -o $name $url; done
列出自己的文章
bash
curl -s -H Authorization: token $FIGSHARE_TOKEN \
https://api.figshare.com/v2/account/articles?page=1&page_size=50 | jq
创建文章（草稿）
bash
curl -s -X POST https://api.figshare.com/v2/account/articles \
-H Authorization: token $FIGSHARE_TOKEN \
-H Content-Type: application/json \
-d {
title: 我的数据集,
description: 此处填写完整描述。,
defined_type: dataset,
tags: [演示],
categories: [2]
} | jq
响应为 { location: .../account/articles/{id}, entity_id: 123 }。
更新/发布文章
bash
更新元数据
curl -s -X PUT https://api.figshare.com/v2/account/articles/$ART \
-H Authorization: token $FIGSHARE_TOKEN \
-H Content-Type: application/json \
-d {title: 新标题}
发布（变为公开，分配 DOI，版本被冻结）
curl -s -X POST https://api.figshare.com/v2/account/articles/$ART/publish \
-H Authorization: token $FIGSHARE_TOKEN
发布前务必询问用户——该版本发布后不可更改。
合集与项目
bash
创建包含现有文章的合集
curl -s -X POST https://api.figshare.com/v2/account/collections \
-H Authorization: token $FIGSHARE_TOKEN \
-H Content-Type: application/json \
-d {title: 我的合集, articles: [123, 456]}
创建项目
curl -s -X POST https://api.figshare.com/v2/account/projects \
-H Authorization: token $FIGSHARE_TOKEN \
-H Content-Type: application/json \
-d {title: 研究项目}
上传文件（多部分流程）
Figshare 上传分为 3 个步骤：初始化 → PUT 每个部分 → 完成。对于复杂操作，请使用附带的辅助脚本：
bash
将文件上传到现有草稿文章
./scripts/upload.sh
批量下载公开文章的所有文件（接受 ID 或 figshare.com URL）
./scripts/download.sh idorurl> [outputdir]
为已发布的文章预留、上传并发布新版本
./scripts/new-version.sh
原始流程（如需自行调整）：
- 1. 初始化 — 计算 md5 和大小，向文章发送 POST 请求：
bash
SIZE=$(stat -f%z $FILE 2>/dev/null || stat -c%s $FILE)
MD5=$(md5sum $FILE | awk {print $1}) # macOS 上使用：md5 -q
curl -s -X POST https://api.figshare.com/v2/account/articles/$ART/files \
-H Authorization: token $FIGSHARE_TOKEN \
-H Content-Type: application/json \
-d {\md5\:\$MD5\,\name\:\$(basename $FILE)\,\size\:$SIZE}
响应中的 location 指向 /account/articles/$ART/files/$FILE_ID。
- 2. 获取上传信息 — 从文件记录中获取 uploadurl。通过 GET 请求访问 uploadurl 获取分片布局（parts: [{partNo, startOffset, endOffset}]）。
- 3. 上传分片 — 对每个分片，将字节范围 PUT 到 ${upload_url}/${partNo}：
bash
dd if=$FILE bs=1 skip=$START count=$((END-START+1)) 2>/dev/null \
| curl -s -X PUT --data-binary @- ${upload_url}/${partNo} \
-H Authorization: token $FIGSHARE_TOKEN
- 4. 完成 — 向文件记录发送 POST 请求以完成上传：
bash
curl -s -X POST https://api.figshare.com/v2/account/articles/$ART/files/$FILE_ID \
-H Authorization: token $FIGSHARE_TOKEN
为什么需要三步：Figshare 通过独立的上传服务流式传输大文件。跳过完成步骤会导致文件处于待处理状态，不会显示在文章中。
分页
大多数列表端点支持 page+pagesize 或 limit+offset 参数。最大 pagesize 通常为 1000。对于大量数据获取，循环请求直到返回空页：
bash
page=1
while :; do
out=$(curl -s https://api.figshare.com/v2/articles?page=$page&page_size=100)
[ $(echo $out | jq length) = 0 ] && break
echo $out | jq -c .[]
page=$((page+1))
sleep 1
done
故障排除
- - 401 — 令牌缺失或已过期；重新检查 $FIGSHARETOKEN。
- 403 访问 /account/... — 令牌缺少所需权限；重新生成并授予完整权限。
- 422 创建文章 — 缺少必填字段（通常是 title）或 categories/definedtype 无效。
- 上传分片不匹配 — 步骤1中的 md5 或大小与实际上传的字节不匹配；重新计算并重试。
- 已发布的文章无法更新 — 发布会冻结版本；请创建新版本。
参考
- - API 参考文档：https://docs.figshare.com/
- 令牌管理：https://figshare.com/account/applications
- 分类 ID：GET https://api.figshare.com/v2/categories
- 许可证 ID：GET https://api.figshare.com/v2/licenses
