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:

  export FIGSHARE_TOKEN=xxxxxxxxxxxxxxxx
  

• 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: https://api.figshare.com/v2
• Auth header: Authorization: token $FIGSHARE_TOKEN
• 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

curl -s -X POST https://api.figshare.com/v2/articles/search \
  -H "Content-Type: application/json" \
  -d '{"search_for": ":title: single cell", "page_size": 20}' | jq

Field operators: :title:, :author:, :tag:, :category:, :doi:, :resource_doi:.

Get a public article (by ID or DOI)

curl -s https://api.figshare.com/v2/articles/{article_id} | jq
# or resolve from a figshare.com URL: the numeric tail is the article_id

Download all files from a public article

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

List your own articles

curl -s -H "Authorization: token $FIGSHARE_TOKEN" \
  "https://api.figshare.com/v2/account/articles?page=1&page_size=50" | jq

Create an article (draft)

curl -s -X POST https://api.figshare.com/v2/account/articles \
  -H "Authorization: token $FIGSHARE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My dataset",
    "description": "Full description here.",
    "defined_type": "dataset",
    "tags": ["demo"],
    "categories": [2]
  }' | jq

Response is { "location": ".../account/articles/{id}", "entity_id": 123 }.

Update / publish an article

# update metadata
curl -s -X PUT https://api.figshare.com/v2/account/articles/$ART \
  -H "Authorization: token $FIGSHARE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "New title"}'

# publish (becomes public, assigns DOI, version is frozen)
curl -s -X POST https://api.figshare.com/v2/account/articles/$ART/publish \
  -H "Authorization: token $FIGSHARE_TOKEN"

Always ask before publishing — it's permanent for that version.

Collections & projects