Skills › Scientific Agent Skills › paper-lookup › figshare.md

figshare.md

94 lines · skills/paper-lookup/references/figshare.md at 5f2bc03

Open on GitHub

1# Figshare

3A general research repository (figures, datasets, posters, papers, media).

4Use it when the user names Figshare or a `figshare.com` DOI, or wants files

5deposited there. It is not a journal index. For OA journal PDFs use Unpaywall;

6for EBI-hosted study packages use BioStudies; for CERN-style software dumps

7prefer Zenodo.

9All figures below verified 2026-09-10.

Figshare

A general research repository (figures, datasets, posters, papers, media). Use it when the user names Figshare or a figshare.com DOI, or wants files deposited there. It is not a journal index. For OA journal PDFs use Unpaywall; for EBI-hosted study packages use BioStudies; for CERN-style software dumps prefer Zenodo.

All figures below verified 2026-09-10.

Raw lines 1 to 10

11## Base URL

13```

14https://api.figshare.com/v2

15```

17Docs: https://docs.figshare.com/v2/

Base URL

https://api.figshare.com/v2

Docs: https://docs.figshare.com/v2/

Raw lines 11 to 18

19## Authentication

21Public article metadata does not need a token. Private records, uploads, and

22account endpoints do (`Authorization: token ACCESS_TOKEN`). This skill only

23uses the public routes.

Authentication

Public article metadata does not need a token. Private records, uploads, and account endpoints do (Authorization: token ACCESS_TOKEN). This skill only uses the public routes.

Raw lines 19 to 24

25## Rate Limits

27The official recommendation is **at most 1 request/second**. Abuse can be throttled or blocked even though the docs describe no automatic rate limiter. Serialize.

Rate Limits

The official recommendation is at most 1 request/second. Abuse can be throttled or blocked even though the docs describe no automatic rate limiter. Serialize.

Raw lines 25 to 28

29## Key Endpoints

Key Endpoints

Raw lines 29 to 30

31### 1. Search — POST, not GET

33```

34POST /v2/articles/search

35Content-Type: application/json

37{"search_for": "CRISPR", "page": 1, "page_size": 10}

38```

40Verified: HTTP 200, a **bare JSON array** (no `total`, no `hits` wrapper).

41First hit was a CRISPR supplementary dataset (`defined_type_name: dataset`).

43There is no count in the body and no useful `Link`/`X-Count` header on this

44call. Walk `page` until a page comes back shorter than `page_size` or empty.

45Do not invent a total. The API limits paging depth to an offset of 1,000 (page limit depends on `page_size`); a 422 beyond that is a bound, not completion. Narrow a query or use the documented bulk interface for larger sets.

47**GET is not a search.** This is the trap that produces a confident wrong

48paper:

50```

51GET /v2/articles?search_for=CRISPR&page_size=1

52```

54Verified: HTTP 200, one article, title *Social capital in the workplace…*,

55DOI `10.1016/j.labeco.2007.07.006`. The query string is ignored; you are

56listing articles. If the user asked for CRISPR and you used GET, you will

57report the wrong object with a 200.

1. Search — POST, not GET

POST /v2/articles/search
Content-Type: application/json

{"search_for": "CRISPR", "page": 1, "page_size": 10}

Verified: HTTP 200, a bare JSON array (no total, no hits wrapper). First hit was a CRISPR supplementary dataset (defined_type_name: dataset).

There is no count in the body and no useful Link/X-Count header on this call. Walk page until a page comes back shorter than page_size or empty. Do not invent a total. The API limits paging depth to an offset of 1,000 (page limit depends on page_size); a 422 beyond that is a bound, not completion. Narrow a query or use the documented bulk interface for larger sets.

GET is not a search. This is the trap that produces a confident wrong paper:

GET /v2/articles?search_for=CRISPR&page_size=1

Verified: HTTP 200, one article, title Social capital in the workplace…, DOI 10.1016/j.labeco.2007.07.006. The query string is ignored; you are listing articles. If the user asked for CRISPR and you used GET, you will report the wrong object with a 200.

Raw lines 31 to 58

59### 2. One article

61```

62GET /v2/articles/{id}

63```

65```

66GET /v2/articles/12345

67```

69Verified: HTTP 200 with `id`, `title`, `doi`, `defined_type_name`, `url`,

70authors, files, license. Use this after search, or when the user already

71has a Figshare id.

73Files, when public, appear on the article object. A 404 is either no such

74id or a record you are not allowed to read (the API uses 404 for both).

2. One article

GET /v2/articles/{id}

GET /v2/articles/12345

Verified: HTTP 200 with id, title, doi, defined_type_name, url, authors, files, license. Use this after search, or when the user already has a Figshare id.

Files, when public, appear on the article object. A 404 is either no such id or a record you are not allowed to read (the API uses 404 for both).

Raw lines 59 to 75

76## Typical Workflow

781. `POST /articles/search` with a JSON body.

792. Read `id`, `title`, `doi`, `defined_type_name` from each element.

803. `GET /articles/{id}` only if you need files or a fuller record.

814. If they wanted papers *about* a topic, go to OpenAlex / PubMed. Figshare

82 search is repository search.

Typical Workflow

POST /articles/search with a JSON body.
Read id, title, doi, defined_type_name from each element.
GET /articles/{id} only if you need files or a fuller record.
If they wanted papers about a topic, go to OpenAlex / PubMed. Figshare search is repository search.

Raw lines 76 to 83

84## Failure Modes

86| What you did | What happens | What to do |

87|---|---|---|

88| `GET /articles?search_for=…` | HTTP 200, unrelated latest-ish articles | POST `/articles/search` |

89| Expected `{hits: …, total: N}` | A raw array | Treat `[]` as empty; no total to reconcile |

90| Reported a Figshare hit as a journal article | `defined_type_name` may be dataset, figure, media | Read and report the type |

Failure Modes

What you did	What happens	What to do
`GET /articles?search_for=…`	HTTP 200, unrelated latest-ish articles	POST `/articles/search`
Expected `{hits: …, total: N}`	A raw array	Treat `[]` as empty; no total to reconcile
Reported a Figshare hit as a journal article	`defined_type_name` may be dataset, figure, media	Read and report the type

Raw lines 84 to 91

92## Official sources reviewed 2026-09-30

94- https://docs.figshare.com/v2/

Official sources reviewed 2026-09-30

https://docs.figshare.com/v2/

Raw lines 92 to 94