v2

latestOpenAPI 3.0.3Apache 2.02026-07-31158109678.6 KB

collections

Create collection

Create a new collection. Institutions with item-type based metadata enabled wrap metadata in a fields object; stock fields are categories, funding_list, related_materials, and publisher. categories input is a list of objects, each identified by either id (int) or source_id (string); mixed entries allowed ([{"id": 69}, {"source_id": "3001"}]). Unresolved source_id values are reported in the response warnings array. Bare integers are rejected. Unrecognised field names inside fields (e.g. a typo) are rejected with 422. licence is no longer accepted on collections (removed Apr 2026). Institutions without item-type based metadata can use the legacy flat-payload form.

post/account/collections

Request body

fundingstring

Grant number or funding authority

titlestring

Title of the collection. Required. Legacy requests send it at the top level; requests for institutions with item-type based metadata enabled send it inside the fields object, where it is validated. Not listed in top-level required because those payloads carry it within fields.

descriptionstring

The collection description. In a publisher case, usually this is the remote collection description

articlesinteger[]

List of articles to be associated with the collection

authorsobject[]

List of authors to be associated with the collection. The list can contain the following fields: id, name, first_name, last_name, email, orcid_id. If an id is supplied, it will take priority and everything else will be ignored. For adding more authors use the specific authors endpoint.

categoriesinteger[]

List of category ids to be associated with the collection(e.g [1, 23, 33, 66])

categories_by_source_idstring[]

List of category source ids to be associated with the collection, supersedes the categories property

tagsstring[]

List of tags to be associated with the collection. Keywords can be used instead

keywordsstring[]

List of tags to be associated with the collection. Tags can be used instead

referencesstring[]

List of links to be associated with the collection (e.g ["http://link1", "http://link2", "http://link3"])

custom_fieldsobject

List of key, values pairs to be associated with the collection

doistring

Not applicable for regular users. In an institutional case, make sure your group supports setting DOIs. This setting is applied by figshare via opening a ticket through our support/helpdesk system.

handlestring

Not applicable for regular users. In an institutional case, make sure your group supports setting Handles. This setting is applied by figshare via opening a ticket through our support/helpdesk system.

resource_idstring

Not applicable to regular users. In a publisher case, this is the publisher article id

resource_doistring

Not applicable to regular users. In a publisher case, this is the publisher article DOI.

resource_linkstring

Not applicable to regular users. In a publisher case, this is the publisher article link

resource_titlestring

Not applicable to regular users. In a publisher case, this is the publisher article title.

resource_versioninteger

Not applicable to regular users. In a publisher case, this is the publisher article version

group_idinteger

Not applicable to regular users. This field is reserved to institutions/publishers with access to assign to specific groups

fieldsobject

Institutions with item-type based metadata only: all metadata fields keyed by underlying field name (e.g. title, description, keywords, publisher, funding_list). When present, the fields object is the authoritative source for all metadata; top-level metadata keys are ignored. categories inside fields is a list of objects, each identified by either an id (integer) or a source_id (string); entries may be mixed. Unresolved source_id values are reported in the response warnings array.

Example request

{
  "title": "Test collection title",
  "description": "Test description of article",
  "articles": [
    2000001,
    2000005
  ],
  "authors": [
    {
      "name": "John Doe"
    },
    {
      "id": 20005
    }
  ],
  "categories": [
    1,
    10,
    11
  ],
  "categories_by_source_id": [
    "300204",
    "400207"
  ],
  "tags": [
    "tag1",
    "tag2"
  ],
  "keywords": [
    "tag1",
    "tag2"
  ],
  "references": [
    "http://figshare.com",
    "http://api.figshare.com"
  ],
  "related_materials": [
    {
      "id": 10432,
      "identifier": "10.6084/m9.figshare.1407024",
      "identifier_type": "DOI",
      "relation": "IsSupplementTo",
      "title": "Figshare for institutions brochure",
      "is_linkout": false
    }
  ],
  "custom_fields": {
    "defined_key": "value for it"
  },
  "custom_fields_list": [
    {
      "name": "key"
    }
  ],
  "timeline": {
    "firstOnline": "2015-12-31",
    "publisherPublication": "2015-12-31",
    "publisherAcceptance": "2015-12-31"
  },
  "fields": {
    "title": "My Collection",
    "description": "Collection description",
    "keywords": [
      "keyword1"
    ],
    "publisher": "Springer Nature",
    "categories": [
      {
        "id": 69
      },
      {
        "source_id": "3001"
      }
    ]
  }
}

Response

Created

entity_idinteger required

Figshare ID of the entity

locationstring url required

Url for entity

warningsstring[] required

Issues encountered during the operation

Example response

{
  "entity_id": 33334444
}