<commit_before># Collection endpoints

* **[Public](#public-endpoints)**
  - [list collections](#list-public-collections)
  - [search collections](#search-public-collections)
  - [read collection](#read-public-collection)
  - [list collection articles](#list-collection-public-articles)
  - [list public collection versions](#list-public-collection-versions)
  - [read public collection version](#read-public-collection-version)


* **[Private](#private-endpoints)**
  - [list own collections](#list-own-collections)
  - [create new collection](#create-a-new-collection)
  - [read own collection](#read-own-collection)
  - [update collection](#update-collection)
  - [delete own private collection](#delete-own-private-collection)
  - [reserve doi for collection](#reserve-doi-for-collection)
  - [publish collection](#publish-collection)
  - [collection authors](#collection-authors-subsection)
    - [list authors](#list-authors)
    - [associate new authors](#associate-new-authors-with-the-collection)
    - [associate and replace authors](#associate-and-replace-existing-authors-of-this-collection)
    - [de-associate author](#de-associate-author-from-collection)
  - [collection categories](#collection-categories-subsection)
    - [list categories](#list-categories)
    - [associate new categories](#associate-new-categories-with-the-collection)
    - [associate and replace categories](#associate-and-replace-existing-categories-of-this-collection)
    - [de-associate category](#de-associate-category-from-collection)
  - [collection articles](#collection-articles-subsection)
    - [list articles](#list-articles)
    - [associate new articles](#associate-new-articles-with-the-collection)
    - [associate and replace articles](#associate-and-replace-existing-articles-of-this-collection)
    - [de-associate article](#de-associate-article-from-collection)
  - [private links](#collection-private-links-subsection)
    - [list private links](#list-private-links)
    - [create new private link](#create-new-private-link-for-this-collection)
    - [update existing private link](#update-existing-private-link-for-this--collection)
    - [disable/delete private link](#disabledelete-private-link-for-collection)


## Public endpoints

The following _public_ endpoints don't require
authentication/authorization.


===========================
### List public collections

#### Request

    GET /v2/collections

Accepts `pagination`, `sorting`, `filtering` params. See [API feature list](index.md#api-feature-list) for details.

Accepted filters:

|field|type|notes|
|-----|----|-----|
|`institution`|int|only return collections from this institution|
|`group`|int|only return collections from this group|
|`published_since`|date (ISO 8601)|Only collections published after the date|
|`modified_since` |date (ISO 8601)|Only collections published after the date|


Defaults:

|field|value|
|-----|-----|
|`order`|`published_date`|
|`order_direction`|`desc`|
|`page_size`|`10`|


#### Response

* Status: `200 OK`
* Body: List of [CollectionPresenter](presenters/collection.md#collectionpresenter)


#### Errors

Standard [error responses](index.md#errors).


=============================
### Search public collections

#### Request

    POST /v2/collections/search

Search public collections. Accepts `pagination`, `sorting`, `filtering`
and `search` params.  See [API feature list](index.md#api-feature-list) for details.

Filters and defaults are the same as for  the
[list public collections](#list-public-collections)

The response body will use the collection `light` presenter.

#### Response

* status: `200 OK`
* body: List of [CollectionPresenter](presenters/collection.md#collectionpresenter)


#### Errors

Standard [error responses](index.md#errors).


==========================
### Read public collection

#### Request

    GET /v2/collections/{id}


#### Response

The collection `detailed` presenter will be used.

* Status: `200 OK`
* Body: [detailed CollectionPresenter(L1)](presenters/collection.md#collectionpresenterl1)


#### Errors

Standard [error responses](index.md#errors).


===================================
### List collection public articles

#### Request

    GET /v2/collections/{id}/articles

Accepts `pagination` params. See [API feature list](index.md#api-feature-list) for details.

#### Response

* Status: `200 OK`
* Body: A list of [ArticlePresenters](presenters/article.md#articlepresenter)


#### Errors

Standard [error responses](index.md#errors).

===================================
### List public collection versions

#### Request

    GET /v2/collections/{id}/versions

#### Response

* Status: `200 OK`
* Body: List of [CollectionVersionPresenter (light)](presenters/collection.md#collectionversionpresenter)

#### Errors

Standard [error responses](index.md#errors).


===================================
### Read public collection version

    GET /v2/collections/{id}/versions/{version_number}


#### Response
* Status: `200 OK`
* Body: [CollectionPresenter (detailed)](presenters/collection.md#collectionpresenterl1)

#### Errors:

Standard [error responses](index.md#errors).


## Private endpoints

These requests require authorization/authentication. Missing valid auth
will result in 403 and 401 errors.

The attribute **own** means resources owned(created or authored) by the
authenticated account.


==========================
### List _own_ collections

    GET /v2/account/collections

Identical to [list public collections](#list-public-collections)

==========================
### Create a new collection

    POST /v2/account/collections

#### Request

|Name               |Type         |Description                                |
|-------------------|-------------|-------------------------------------------|
|`title`            |`str`        |The title for this collection - `mandatory`|
|`description`      |`str`        |The collection description. In a publisher case, usually this is the resource article description|
|`doi`              |`str`        |Digital Object Identifier|
|`articles`         |`array of int`|List of articles to be associated with the collection (e.g `[1, 4]`)|
|`authors`          |`array of dictionaries {'id':int} or {'name':str}`|List of new authors to be assosciated with the collection. Each element identifies an author by `id` or `name`: `[{"id":1212}, "name":"<NAME>"}]`)|
|`categories`       |`array of int` |List of category ids to be associated with the collection (e.g `[5, 7, 9]`)|
|`tags`             |`array of str` |List of tags to be associated with the collection (e.g `["tag1", "tag2"]`)|
|`references`       |`array of str`   |List of references to be associated with the collection (e.g `["http://figshare.com", "http://figshare.com/articles/browse"]`)|
|`resource_id`      |`str`  |Not applicable to regular users. In a publisher case, this is the publisher article id|
|`resource_doi`     |`str`  |Not applicable to regular users. In a publisher case, this is the publisher article DOI|
|`resource_link`    |`str`  |Not applicable to regular users. In a publisher case, this is the publisher article link|
|`resource_title`   |`str`  |Not applicable to regular users. In a publisher case, this is the publisher article title|
|`resource_version` |`int`  |Not applicable to regular users. In a publisher case, this is the publisher article version|
|`custom_fields`    |`dict` |List of key, values pairs to be associated with the collection. Similar to custom article fields|


#### Response

* Status: `201 Created`
* Headers:
    ```<commit_msg>Private items are sorted by created_date<commit_after># Collection endpoints

* **[Public](#public-endpoints)**
  - [list collections](#list-public-collections)
  - [search collections](#search-public-collections)
  - [read collection](#read-public-collection)
  - [list collection articles](#list-collection-public-articles)
  - [list public collection versions](#list-public-collection-versions)
  - [read public collection version](#read-public-collection-version)


* **[Private](#private-endpoints)**
  - [list own collections](#list-own-collections)
  - [create new collection](#create-a-new-collection)
  - [read own collection](#read-own-collection)
  - [update collection](#update-collection)
  - [delete own private collection](#delete-own-private-collection)
  - [reserve doi for collection](#reserve-doi-for-collection)
  - [publish collection](#publish-collection)
  - [collection authors](#collection-authors-subsection)
    - [list authors](#list-authors)
    - [associate new authors](#associate-new-authors-with-the-collection)
    - [associate and replace authors](#associate-and-replace-existing-authors-of-this-collection)
    - [de-associate author](#de-associate-author-from-collection)
  - [collection categories](#collection-categories-subsection)
    - [list categories](#list-categories)
    - [associate new categories](#associate-new-categories-with-the-collection)
    - [associate and replace categories](#associate-and-replace-existing-categories-of-this-collection)
    - [de-associate category](#de-associate-category-from-collection)
  - [collection articles](#collection-articles-subsection)
    - [list articles](#list-articles)
    - [associate new articles](#associate-new-articles-with-the-collection)
    - [associate and replace articles](#associate-and-replace-existing-articles-of-this-collection)
    - [de-associate article](#de-associate-article-from-collection)
  - [private links](#collection-private-links-subsection)
    - [list private links](#list-private-links)
    - [create new private link](#create-new-private-link-for-this-collection)
    - [update existing private link](#update-existing-private-link-for-this--collection)
    - [disable/delete private link](#disabledelete-private-link-for-collection)


## Public endpoints

The following _public_ endpoints don't require
authentication/authorization.


===========================
### List public collections

#### Request

    GET /v2/collections

Accepts `pagination`, `sorting`, `filtering` params. See [API feature list](index.md#api-feature-list) for details.

Accepted filters:

|field|type|notes|
|-----|----|-----|
|`institution`|int|only return collections from this institution|
|`group`|int|only return collections from this group|
|`published_since`|date (ISO 8601)|Only collections published after the date|
|`modified_since` |date (ISO 8601)|Only collections published after the date|


Defaults:

|field|value|
|-----|-----|
|`order`|`published_date`|
|`order_direction`|`desc`|
|`page_size`|`10`|


#### Response

* Status: `200 OK`
* Body: List of [CollectionPresenter](presenters/collection.md#collectionpresenter)


#### Errors

Standard [error responses](index.md#errors).


=============================
### Search public collections

#### Request

    POST /v2/collections/search

Search public collections. Accepts `pagination`, `sorting`, `filtering`
and `search` params.  See [API feature list](index.md#api-feature-list) for details.

Filters and defaults are the same as for  the
[list public collections](#list-public-collections)

The response body will use the collection `light` presenter.

#### Response

* status: `200 OK`
* body: List of [CollectionPresenter](presenters/collection.md#collectionpresenter)


#### Errors

Standard [error responses](index.md#errors).


==========================
### Read public collection

#### Request

    GET /v2/collections/{id}


#### Response

The collection `detailed` presenter will be used.

* Status: `200 OK`
* Body: [detailed CollectionPresenter(L1)](presenters/collection.md#collectionpresenterl1)


#### Errors

Standard [error responses](index.md#errors).


===================================
### List collection public articles

#### Request

    GET /v2/collections/{id}/articles

Accepts `pagination` params. See [API feature list](index.md#api-feature-list) for details.

#### Response

* Status: `200 OK`
* Body: A list of [ArticlePresenters](presenters/article.md#articlepresenter)


#### Errors

Standard [error responses](index.md#errors).

===================================
### List public collection versions

#### Request

    GET /v2/collections/{id}/versions

#### Response

* Status: `200 OK`
* Body: List of [CollectionVersionPresenter (light)](presenters/collection.md#collectionversionpresenter)

#### Errors

Standard [error responses](index.md#errors).


===================================
### Read public collection version

    GET /v2/collections/{id}/versions/{version_number}


#### Response
* Status: `200 OK`
* Body: [CollectionPresenter (detailed)](presenters/collection.md#collectionpresenterl1)

#### Errors:

Standard [error responses](index.md#errors).


## Private endpoints

These requests require authorization/authentication. Missing valid auth
will result in 403 and 401 errors.

The attribute **own** means resources owned(created or authored) by the
authenticated account.


==========================
### List _own_ collections

    GET /v2/account/collections

Almost identical to [list public collections](#list-public-collections), but default sorting is by `created_date`, not `published_date`.

==========================
### Create a new collection

    POST /v2/account/collections

#### Request

|Name               |Type         |Description                                |
|-------------------|-------------|-------------------------------------------|
|`title`            |`str`        |The title for this collection - `mandatory`|
|`description`      |`str`        |The collection description. In a publisher case, usually this is the resource article description|
|`doi`              |`str`        |Digital Object Identifier|
|`articles`         |`array of int`|List of articles to be associated with the collection (e.g `[1, 4]`)|
|`authors`          |`array of dictionaries {'id':int} or {'name':str}`|List of new authors to be assosciated with the collection. Each element identifies an author by `id` or `name`: `[{"id":1212}, "name":"<NAME>"}]`)|
|`categories`       |`array of int` |List of category ids to be associated with the collection (e.g `[5, 7, 9]`)|
|`tags`             |`array of str` |List of tags to be associated with the collection (e.g `["tag1", "tag2"]`)|
|`references`       |`array of str`   |List of references to be associated with the collection (e.g `["http://figshare.com", "http://figshare.com/articles/browse"]`)|
|`resource_id`      |`str`  |Not applicable to regular users. In a publisher case, this is the publisher article id|
|`resource_doi`     |`str`  |Not applicable to regular users. In a publisher case, this is the publisher article DOI|
|`resource_link`    |`str`  |Not applicable to regular users. In a publisher case, this is the publisher article link|
|`resource_title`   |`str`  |Not applicable to regular users. In a publisher case, this is the publisher article title|
|`resource_version` |`int`  |Not applicable to regular users. In a publisher case, this is the publisher article version|
|`custom_fields`    |`dict` |List of key, values pairs to be associated with the collection. Similar to custom article fields|


#### Response

* Status: `201 Created`
* Headers:
    ```
{'fraction_non_alphanumeric': 0.1740184833191322, 'fraction_numerical': 0.007734154814183654, 'mean_word_length': 4.338698390482855, 'pattern_counts': {'":': 4, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3351698', 'n_tokens_mistral': 4460, 'n_tokens_neox': 4161, 'n_words': 1204}