/figshare/collections

POST /api/figshare/collections

Price: 1 credit

Get one Figshare collection by id, page address or DOI. A collection groups the deposits that belong together, usually the supplementary material of a single publication. Returns the title, description, authors, subject categories, tags, references, funding awards, related materials, the number of items it holds and the publication it accompanies.

How to use it

A collection is a container, not a deposit: it carries no files and `article_count` is the only count of what is inside, so use /figshare/articles/search with `source_doi` set to this collection's `source_doi` to reach the individual records. Its `doi` is usually the accompanying publication's DOI rather than one Figshare minted, which is why the same DOI resolves both here and on /figshare/articles/search. Do not pass a collection id to /figshare/articles — the two id spaces overlap in range and the article route answers 412 for a collection id.

Parameters

• access-token string required

Request body

• timeout integer — Max scrapping execution timeout (in seconds) (default: 300; min: 20; max: 1500)
• collection string required — Figshare collection id, the address of its Figshare page, or its DOI (examples: "8708787", "https://figshare.com/collections/_/8708787", "10.1021/acs.jafc.6c06281"; minLength: 1)

Response

• @type string (default: "FigshareCollectionDetail")
• id string required
• url string required
• doi string nullable
• description string nullable
• citation string nullable
• version string nullable
• article_count integer nullable
• created_at string nullable
• modified_at string nullable
• published_at string nullable
• timeline object nullable
  • @type string (default: "FigshareTimeline")
  • posted_at string nullable
  • submitted_at string nullable
  • revised_at string nullable
  • first_online_date string nullable
  • publisher_publication_date string nullable
  • publisher_acceptance_date string nullable
• group_id string nullable
• institution_id string nullable
• group_resource_id string nullable
• source_doi string nullable
• source_title string nullable
• source_url string nullable
• source_version string nullable
• authors array (default: [])
  • @type string (default: "FigshareAuthor")
  • id string nullable
  • full_name string required
  • first_name string nullable
  • last_name string nullable
  • orcid string nullable
  • alias string nullable
  • is_active boolean nullable
• categories array (default: [])
  • @type string (default: "FigshareCategory")
  • id string required
  • parent_category_id string nullable
  • taxonomy_id string nullable
  • path string nullable
  • source_id string nullable
• tags array (default: [])
• references array (default: [])
• funding array (default: [])
  • @type string (default: "FigshareFunding")
  • id string nullable
  • grant_code string nullable
  • funder_name string nullable
  • url string nullable
  • is_user_defined boolean nullable
• related_materials array (default: [])
  • @type string (default: "FigshareRelatedMaterial")
  • id string nullable
  • identifier string nullable
  • identifier_type string nullable
  • relation string nullable
  • link_url string nullable
  • is_linkout boolean nullable
• custom_fields array (default: [])
  • @type string (default: "FigshareCustomField")
  • name string required
  • values array (default: [])
  • field_type string nullable
  • is_mandatory boolean nullable
• is_public boolean nullable

Errors

• 422 — The request body did not validate Check the fields against this schema. A URN with the wrong prefix is the most common cause.
• 408 — The request ran past its time limit Raise `timeout` in the request body, up to the maximum this endpoint documents. Lowering `count` or turning off the `with_*` flags also helps, because less work finishes sooner.
• 412 — No Figshare collection carries this id or DOI Retrying will not help: either the entity does not exist, or the input points at a different one.
• 429 — Too many requests: a rate limit or a usage window is exhausted When the response carries an X-Retry-After header, wait that many seconds and retry: the same number is in the body as `detail.retry_after`, and the limit clears once that window passes. The message in the body names the limit that was hit.
• 500 — Something broke on our side Retrying will not help. If it keeps happening, send us the X-Request-ID from the response headers.
• 529 — Rate limit reached, or the endpoint is overloaded Wait at least 30 seconds, then retry.

Response headers

• X-Error — Error message text (present only on error)
• X-Request-ID — Unique request identifier
• X-Execution-Time — Execution time in seconds
• X-Result-Count — How many records the body carries. 0 means an empty result, which is a normal answer and not by itself an error. A non-zero count can come back together with X-Error when the failure happened partway through — read this header and X-Error independently.
• X-Total-Available-Results — How many records exist for this query, when the endpoint can say. On a `dry_run` request this is the answer and the body is empty. It saturates: the endpoint's documented maximum means 'at least that many', any smaller number is exact.
• X-Warning — Present when the request body carried keys this endpoint does not document. They were ignored, so any filter you meant to apply through them did not apply. Check the spelling against this schema and retry.
• X-Retry-After — Seconds to wait before retrying. Present only on 429.