\ifdefined\HCode
\begin{html}
<a id="api-section"></a>
\end{html}
\fi

%% Macros to avoid repeating the same text.

\newcommand{\categoryDescription}{%
  Categories are a controlled vocabulary and can be used to make the collection
  findable in the categorical overviews.  The \t{string} values expected here
  can be found under the \code{uuid} property with a call to \code{/v2/categories}.
  For more details, see section \refer{sec:v2-categories}.}

\newcommand{\customFieldsDescription}{%
  An \t{Object} where each key is a field name and each value is the
  corresponding value. Allowed values are: \t{contributors},
  \t{data\_link}, \t{derived\_from}, \t{format}, \t{geolocation},
  \t{language}, \t{latitude}, \t{longitude}, \t{organizations},
  \t{publisher}, \t{same\_as}, \t{time\_coverage}.}

\newcommand{\customFieldsListDescription}{%
  Each \t{Object} should have two keys: \t{name} and \t{value}. For
  allowed keys, see \t{custom\_fields}.}

\chapter{Application Programming Interface}

  The application programming interface (API) provided by \t{djehuty} allows
  for automating tasks otherwise done through the user interface.  In addition
  to automation, the API can also be used to gather additional information,
  like statistics on Git repositories.

  Throughout this chapter we provide examples for using the API using \t{curl} and \t{jq}.
  Another way of seeing the API in action is to use the developer tools in a web
  browser while performing the desired action using the web user interface.

\section{Published datasets}

  The \t{v2} API was designed by Figshare\footnote{\dhref{https://figshare.com}}.
  \t{djehuty} implements a backward-compatible version of it, with the
  following differences:
  \begin{enumerate}
    \item{The \t{id} property is superseded by the \t{uuid} property.}
    \item{Error handling is done through precise HTTP error codes,
        rather than always returning \t{400} on a usage error.}
  \end{enumerate}

  Unless specified otherwise, the HTTP \t{Content-Type} to interact
  with the API is \t{application/json}.  In the case an API call returns
  information, don't forget to set the HTTP \t{Accept} header appropriately.

\subsection{\t{/v2/articles} (\t{GET})}
\label{sec:v2-articles}

  This API endpoint can be used to retrieve a list of published datasets.
  Passing (one of) the following parameters will filter or sort the list of
  datasets:

\begin{tabularx}{\textwidth}{*{2}{!{\VRule[-1pt]}l}!{\VRule[-1pt]}X}
  \headrow
  \textbf{Parameter}   & \textbf{Required} & \textbf{Description}\\
  \t{order}            & Optional & Field to use for sorting.\\
  \t{order\_direction} & Optional & Can be either \code{asc} or \code{desc}.\\
  \t{institution}      & Optional & The institution identifier to filter on.\\
  \t{published\_since} & Optional & When set, datasets published before this
                                    timestamp are dropped from the results.\\
  \t{modified\_since}  & Optional & When set, only datasets modified after
                                    this timestamp are shown from the results.\\
  \t{group}            & Optional & The group identifier to filter on.\\
  \t{resource\_doi}    & Optional & The DOI of the associated journal publication.
                                    When set, only returns datasets associated
                                    with this DOI.\\
  \t{item\_type}       & Optional & Either \code{3} for datasets or \code{9}
                                    for software.\\
  \t{doi}              & Optional & The DOI of the dataset to search for.\\
  \t{handle}           & Optional & Unused.\\
  \t{page}             & Optional & The page number used in combination with
                                    \t{page\_size}.\\
  \t{page\_size}       & Optional & The number of datasets per page.  Used
                                    in combination with \t{page}.\\
  \t{limit}            & Optional & The maximum number of datasets to output.
                                    Used together with \t{offset}.\\
  \t{offset}           & Optional & The number of datasets to skip in the
                                    output.  Used together with \t{limit}.
\end{tabularx}

  Example usage:
\begin{lstlisting}[language=bash]
curl "(@*\djehutybaseurl{}*@)/v2/articles?limit=100&published_since=2024-07-25" | jq
\end{lstlisting}

  Output of the example:
\begin{lstlisting}[language=JSON]
[ /* Example output has been shortened. */
  {
    "id": null,
    "uuid": "4f8a9423-83fc-4263-9bb7-2aa83d73865d",
    "title": "Measurement data of a Low Speed Field Test of Tractor Se...",
    "doi": "10.4121/4f8a9423-83fc-4263-9bb7-2aa83d73865d.v1",
    "handle": null,
    "url": "(@*\djehutybaseurl{}*@)/v2/articles/4f8a...865d",
    "published_date": "2024-07-26T10:39:57",
    "thumb": null,
    "defined_type": 3,
    "defined_type_name": "dataset",
    "group_id": 28589,
    "url_private_api": "(@*\djehutybaseurl{}*@)/v2/account/articles/4f8a...865d",
    "url_public_api": "(@*\djehutybaseurl{}*@)/v2/articles/4f8a...865d",
    "url_private_html": "(@*\djehutybaseurl{}*@)/my/datasets/4f8a...865d/edit",
    "url_public_html": "(@*\djehutybaseurl{}*@)/datasets/4f8a...865d/1",
    ...
  }
]
\end{lstlisting}

\subsection{\t{/v2/articles/search} (\t{POST})}

  In addition to the parameters of section \refer{sec:v2-articles}, the
  following parameters can be used.

\begin{tabularx}{\textwidth}{*{2}{!{\VRule[-1pt]}l}!{\VRule[-1pt]}X}
  \headrow
  \textbf{Parameter}   & \textbf{Required} & \textbf{Description}\\
  \t{search\_for}      & Optional & The terms to search for.
\end{tabularx}

  Example usage:
\begin{lstlisting}[language=bash]
curl --request POST \
     --header "Content-Type: application/json"\
     --data '{ "search_for": "djehuty" }'\
     (@*\djehutybaseurl{}*@)/v2/articles/search | jq
\end{lstlisting}

  Output of the example:
\begin{lstlisting}[language=JSON]
[ /* Example output has been shortened. */
  {
    "id": null,
    "uuid": "342efadc-66f8-4e9b-9d27-da7b28b849d2",
    "title": "Source code of the 4TU.ResearchData repository",
    "doi": "10.4121/342efadc-66f8-4e9b-9d27-da7b28b849d2.v1",
    "handle": null,
    "url": "(@*\djehutybaseurl{}*@)/v2/articles/342e...49d2",
    "published_date": "2023-03-20T11:29:10",
    "thumb": null,
    "defined_type": 9,
    "defined_type_name": "software",
    "group_id": 28586,
    "url_private_api": "(@*\djehutybaseurl{}*@)/v2/account/articles/342e...49d2",
    "url_public_api": "(@*\djehutybaseurl{}*@)/v2/articles/342e...49d2",
    "url_private_html": "(@*\djehutybaseurl{}*@)/my/datasets/342e...49d2/edit",
    "url_public_html": "(@*\djehutybaseurl{}*@)/datasets/342e...49d2/1",
    ...
  }
]
\end{lstlisting}

\subsection{\t{/v2/articles/<dataset-id>} (\t{GET})}
\label{sec:v2-articles-dataset-id}

  This API endpoint can be used to retrieve detailed metadata for the dataset
  identified by \code{dataset-id}.

  Example usage:
\begin{lstlisting}[language=bash]
curl (@*\djehutybaseurl{}*@)/v2/articles/342efadc-66f8-4e9b-9d27-da7b28b849d2 | jq
\end{lstlisting}

  Output of the example:
\begin{lstlisting}[language=JSON]
{ /* Example output has been shortened. */
  "files": ...,
  "custom_fields": ...,
  "authors": ...,
  "description": "<p>This dataset contains the source code of the 4TU...",
  "license": ...,
  "tags": ...,
  "categories": ...,
  "references": ...,
  "id": null,
  "uuid": "342efadc-66f8-4e9b-9d27-da7b28b849d2",
  "title": "Source code of the 4TU.ResearchData repository",
  "doi": "10.4121/342efadc-66f8-4e9b-9d27-da7b28b849d2.v1",
  "url": "(@*\djehutybaseurl{}*@)/v2/articles/342e...49d2",
  "published_date": "2023-03-20T11:29:10",
  "timeline": ...,
  ...
}
\end{lstlisting}

\subsection{\t{/v2/articles/<dataset-id>/versions} (\t{GET})}

  This API endpoint can be used to retrieve a list of versions for the dataset
  identified by \code{dataset-id}.

  Example usage:
\begin{lstlisting}[language=bash]
curl (@*\djehutybaseurl{}*@)/v2/articles/342efadc-66f8-4e9b-9d27-da7b28b849d2/versions | jq
\end{lstlisting}

  Output of the example:
\begin{lstlisting}[language=JSON]
[
  {
    "version": 1,
    "url": "(@*\djehutybaseurl{}*@)/v2/articles/342e...49d2/versions/1"
  }
]
\end{lstlisting}

\subsection{\t{/v2/articles/<dataset-id>/versions/<version>} (\t{GET})}

  This API endpoint can be used to retrieve detailed metadata of the version
  \code{version} for the dataset identified by \code{dataset-id}.

  Example usage:
\begin{lstlisting}[language=bash]
curl (@*\djehutybaseurl{}*@)/v2/articles/342e...49d2/versions/1 | jq
\end{lstlisting}

  The output of the example is identical to the example output of section
  \refer{sec:v2-articles-dataset-id}.

\subsection{\t{/v2/articles/<dataset-id>/versions/<version>/embargo} (\t{GET})}

  This API endpoint can be used to retrieve embargo information of the version
  \code{version} for the dataset identified by \code{dataset-id}.

  Example usage:
\begin{lstlisting}[language=bash]
curl (@*\djehutybaseurl{}*@)/v2/articles/c127...8fd7/versions/2/embargo | jq
\end{lstlisting}

  Output of the example:
\begin{lstlisting}[language=JSON]
{
  "is_embargoed": true,
  "embargo_date": "2039-06-30",
  "embargo_type": "article",
  "embargo_title": "Under embargo",
  "embargo_reason": "<p>Need consent to publish the data</p>",
  "embargo_options": []
}
\end{lstlisting}


%\subsection{\t{/v2/articles/<dataset-id>}/versions/<version>/confidentiality (\t{GET})}
%\subsection{\t{/v2/articles/<dataset-id>}/versions/<version>/update\_thumb}
\subsection{\t{/v2/articles/<dataset-id>/files} (\t{GET})}

  This API endpoint can be used to retrieve the list of files associated with
  the dataset identified by \code{dataset-id}.

  Example usage:
\begin{lstlisting}[language=bash]
curl (@*\djehutybaseurl{}*@)/v2/articles/342efadc-66f8-4e9b-9d27-da7b28b849d2/files
\end{lstlisting}

  Output of the example:
\begin{lstlisting}[language=JSON]
[ /* Example output has been shortened. */
  {
    "id": null,
    "uuid": "d3e1c325-7fa9-4cb9-884e-0b9cd2059292",
    "name": "djehuty-0.0.1.tar.gz",
    "size": 3713709,
    "is_link_only": false,
    "is_incomplete": false,
    "download_url": "(@*\djehutybaseurl{}*@)/file/342e...49d2/d3e1...9292",
    "supplied_md5": null,
    "computed_md5": "910e9b0f79a0af548f59b3d8a56c3bf4"
  }
]
\end{lstlisting}

\subsection{\t{/v2/articles/<dataset-id>/files/<file-id>} (\t{GET})}

  This API endpoint can be used to retrieve all metadata of the file
  identified by \code{file-id} associated with the dataset identified
  by \code{dataset-id}.

  Example usage:
\begin{lstlisting}[language=bash]
curl (@*\djehutybaseurl{}*@)/v2/articles/342e...49d2/files/d3e1...9292 | jq
\end{lstlisting}

  Output of the example:
\begin{lstlisting}[language=JSON]
{ /* Example output has been shortened. */
  "id": null,
  "uuid": "d3e1c325-7fa9-4cb9-884e-0b9cd2059292",
  "name": "djehuty-0.0.1.tar.gz",
  "size": 3713709,
  "is_link_only": false,
  "is_incomplete": false,
  "download_url": "(@*\djehutybaseurl{}*@)/file/342e...49d2/d3e1...9292",
  "supplied_md5": null,
  "computed_md5": "910e9b0f79a0af548f59b3d8a56c3bf4"
}
\end{lstlisting}

\section{Published collections}

\subsection{\t{/v2/collections} (\t{GET})}
\label{sec:v2-collections}

  This API endpoint can be used to retrieve a list of collections published
  in the data repository.

  The following parameters can be used:

\begin{tabularx}{\textwidth}{*{2}{!{\VRule[-1pt]}l}!{\VRule[-1pt]}X}
  \headrow
  \textbf{Parameter}   & \textbf{Required} & \textbf{Description}\\
  \t{order}            & Optional & Field to use for sorting.\\
  \t{order\_direction} & Optional & Can be either \code{asc} or \code{desc}.\\
  \t{institution}      & Optional & The institution identifier to filter on.\\
  \t{published\_since} & Optional & When set, collections published before this
                                    timestamp are dropped from the results.\\
  \t{modified\_since}  & Optional & When set, only collections modified after
                                    this timestamp are shown from the results.\\
  \t{group}            & Optional & The group identifier to filter on.\\
  \t{resource\_doi}    & Optional & The DOI of the associated journal publication.
                                    When set, only returns collections associated
                                    with this DOI.\\
  \t{doi}              & Optional & The DOI of the collection to search for.\\
  \t{handle}           & Optional & Unused.\\
  \t{page}             & Optional & The page number used in combination with
                                    \t{page\_size}.\\
  \t{page\_size}       & Optional & The number of collections per page.  Used
                                    in combination with \t{page}.\\
  \t{limit}            & Optional & The maximum number of collections to output.
                                    Used together with \t{offset}.\\
  \t{offset}           & Optional & The number of collections to skip in the
                                    output.  Used together with \t{limit}.
\end{tabularx}

  Example usage:
\begin{lstlisting}[language=bash]
curl "(@*\djehutybaseurl{}*@)/v2/collections?limit=100&published_since=2024-07-25" | jq
\end{lstlisting}

Output of the example:
\begin{lstlisting}[language=JSON]
[ /* Example output has been shortened. */
  {
    "id": null,
    "uuid": "0fe9ab80-6e6a-4087-a509-ce09dddfa3d9",
    "title": "PhD research 'Untangling the complexity of local water ...'",
    "doi": "10.4121/0fe9ab80-6e6a-4087-a509-ce09dddfa3d9.v1",
    "handle": "",
    "url": "(@*\djehutybaseurl{}*@)/v2/collections/0fe9...fa3d9",
    "timeline": {
      "posted": "2024-08-13T14:09:52",
      "firstOnline": "2024-08-13T14:09:51",
      ...
    },
    "published_date": "2024-08-13T14:09:52"
  },
  ...
]
\end{lstlisting}

\subsection{\t{/v2/collections/search} (\t{POST})}

  This API endpoint can be used to search for collections published in
  the data repository.

  In addition to the parameters of section \refer{sec:v2-collections}, the
  following parameters can be used.

\begin{tabularx}{\textwidth}{*{2}{!{\VRule[-1pt]}l}!{\VRule[-1pt]}X}
  \headrow
  \textbf{Parameter}   & \textbf{Required} & \textbf{Description}\\
  \t{search\_for}      & Optional          & The terms to search for.
\end{tabularx}

  Example usage:
\begin{lstlisting}[language=bash]
curl --request POST \
     --header "Content-Type: application/json"\
     --data '{ "search_for": "wingtips" }'\
     (@*\djehutybaseurl{}*@)/v2/collections/search | jq
\end{lstlisting}

  Output of the example:
\begin{lstlisting}[language=JSON]
[  /* Example output has been shortened. */
  {
    "id": 6070238,
    "uuid": "3dfc4ef2-7f79-4d33-81a7-9c6ae09a2782",
    "title": "Flared Folding Wingtips - TU Delft",
    "doi": "10.4121/c.6070238.v1",
    "handle": "",
    "url": "(@*\djehutybaseurl{}*@)/v2/collections/3dfc...2782",
    "timeline": {
      "posted": "2023-04-05T15:05:04",
      "firstOnline": "2023-04-05T15:05:03",
      ...
    },
    "published_date": "2023-04-05T15:05:04"
  },
  ...
]
\end{lstlisting}

\subsection{\t{/v2/collections/<collection-id>} (\t{GET})}

  This API endpoint can be used to retrieve detailed metadata for the collection
  identified by \code{collection-id}.

  Example usage:
\begin{lstlisting}[language=bash]
curl (@*\djehutybaseurl{}*@)/v2/collections/3dfc4ef2-7f79-4d33-81a7-9c6ae09a2782 | jq
\end{lstlisting}

  Output of the example:
\begin{lstlisting}[language=JSON]
{ /* Example output has been shortened. */
  "version": 3,
  ...
  "description": "<p>This collection contains the results of the work ...",
  "categories": [ ... ],
  "references": [],
  "tags": [ ... ],
  "created_date": "2024-08-08T15:48:55",
  "modified_date": "2024-08-12T11:24:39",
  "id": 6070238,
  "uuid": "3dfc4ef2-7f79-4d33-81a7-9c6ae09a2782",
  "title": "Flared Folding Wingtips - TU Delft",
  "doi": "10.4121/c.6070238.v3",
  "published_date": "2024-08-12T11:24:40",
  "timeline": ...
  ...
}
\end{lstlisting}

\subsection{\t{/v2/collections/<collection-id>/versions} (\t{GET})}

  This API endpoint can be used to retrieve a list of versions for the collection
  identified by \code{collection-id}.

  Example usage:
\begin{lstlisting}[language=bash]
curl (@*\djehutybaseurl{}*@)/v2/collections/3dfc4ef2-7f79-4d33-81a7-9c6ae09a2782/versions | jq
\end{lstlisting}

  Output of the example:
\begin{lstlisting}[language=JSON]
[ /* Example output has been shortened. */
  {
    "version": 3,
    "url": "(@*\djehutybaseurl{}*@)/v2/collections/3dfc...2782/versions/3"
  },
  {
    "version": 2,
    "url": "(@*\djehutybaseurl{}*@)/v2/collections/3dfc...2782/versions/2"
  },
  {
    "version": 1,
    "url": "(@*\djehutybaseurl{}*@)/v2/collections/3dfc...2782/versions/1"
  }
]
\end{lstlisting}

\subsection{\t{/v2/collections/<collection-id>/versions/<version>} (\t{GET})}

  This API endpoint can be used to retrieve detailed metadata of the version
  \code{version} for the collection identified by \code{collection-id}.

  Example usage:
\begin{lstlisting}[language=bash]
curl (@*\djehutybaseurl{}*@)/v2/collections/3dfc...2782/versions/2 | jq
\end{lstlisting}

  Output of the example:
\begin{lstlisting}[language=JSON]
{ /* Example output has been shortened. */
  "version": 2,
  ...
  "description": "<p>This collection contains the results of the work ...",
  "categories": [ ... ],
  "references": [],
  "tags": [ ... ],
  "references": [],
  "tags": [ ... ],
  "authors": [ ... ],
  "created_date": "2023-04-05T15:07:35",
  "modified_date": "2023-05-26T15:19:11",
  "id": 6070238,
  "uuid": "3dfc4ef2-7f79-4d33-81a7-9c6ae09a2782",
  "title": "Flared Folding Wingtips - TU Delft",
  "doi": "10.4121/c.6070238.v2",
  ...
}
\end{lstlisting}

\subsection{\t{/v2/collections/<collection-id>/articles} (\t{GET})}

  This API endpoint can be used to retrieve the list of datasets in the
  collection identified by \code{collection-id}.

  Example usage:
\begin{lstlisting}[language=bash]
curl (@*\djehutybaseurl{}*@)/v2/collections/3dfc...2782/articles | jq
\end{lstlisting}

  Output of the example:
\begin{lstlisting}[language=JSON]
[ /* Example output has been shortened. */
  {
    "id": 20222334,
    "uuid": "c5fde4a2-798a-456e-b793-cf64e486c0e8",
    "title": "E001 - Stiffness and Hinge Release Study (October 2021) ...",
    "doi": "10.4121/20222334.v2",
    "published_date": "2023-05-31T08:57:54",
    "defined_type": 3,
    "defined_type_name": "dataset",
    "group_id": 28586,
    "timeline": {
      "posted": "2023-05-31T08:57:54",
      "firstOnline": "2023-05-26T15:08:09",
      "revision": null
    },
    "resource_title": "Effect of Wing Stiffness and Folding Wingtip ...",
    "resource_doi": "https://doi.org/10.2514/1.C037108"
  },
  {
    "id": null,
    "uuid": "984090ea-26fd-4809-8dac-f41367bf8916",
    "title": "M001 - GVT Data and Nastran models (August 2024) ...",
    "doi": "10.4121/984090ea-26fd-4809-8dac-f41367bf8916.v1",
    "published_date": "2024-08-12T11:21:47",
    "defined_type": 3,
    "defined_type_name": "dataset",
    "group_id": 28586,
    "timeline": {
      "posted": "2024-08-12T11:21:47",
      "firstOnline": "2024-08-12T11:21:46",
      "revision": null
    },
    "resource_title": "Effect of Wing Stiffness and Folding Wingtip ...",
    "resource_doi": "https://doi.org/10.2514/1.C037108"
  }
]
\end{lstlisting}

\section{Categories}

\subsection{\t{/v2/categories} (\t{GET})}
\label{sec:v2-categories}

  Each dataset and collection is categorized using a controlled vocabulary
  of categories.  This API endpoint provides those categories.

  Example usage:
\begin{lstlisting}[language=bash]
curl (@*\djehutybaseurl{}*@)/v2/categories | jq
\end{lstlisting}

  Output of the example:
\begin{lstlisting}[language=JSON]
[ /* Example output has been shortened. */
  {
    "id": 13622,
    "uuid": "01fddd41-68d2-4e28-9d9c-18347847e7d1",
    "title": "Mining and Extraction of Energy Resources",
    "parent_id": 13620,
    "parent_uuid": "6e5bdc69-96db-41e4-ac0b-18812b46c49c",
    "path": "",
    "source_id": null,
    "taxonomy_id": null
  },
  {
    "id": 13443,
    "uuid": "026f555c-2826-4a83-97ff-0f230fb54ddb",
    "title": "Livestock Raising",
    "parent_id": 13440,
    "parent_uuid": "45a8c849-ab59-4302-af79-09b8c0677df8",
    "path": "",
    "source_id": null,
    "taxonomy_id": null
  },
  ...
]
\end{lstlisting}

\section{Licences}

\subsection{\t{/v2/licenses} (\t{GET})}
\label{sec:v2-licenses}

  Publishing a dataset involves communicating under which conditions it can be
  re-used.  The licenses under which you can publish a dataset can be found with
  this API endpoint.

  Example usage:
\begin{lstlisting}[language=bash]
curl (@*\djehutybaseurl{}*@)/v2/licenses | jq
\end{lstlisting}

  Output of the example:
\begin{lstlisting}[language=JSON]
[ /* Example output has been shortened. */
  {
    "value": 1,
    "name": "CC BY 4.0",
    "url": "https://creativecommons.org/licenses/by/4.0/",
    "type": "data"
  },
  {
    "value": 10,
    "name": "CC BY-NC 4.0",
    "url": "https://creativecommons.org/licenses/by-nc/4.0/",
    "type": "data"
  },
  ...
]
\end{lstlisting}

\section{Account properties}

  The interaction with the \t{v2} private interface API requires an API token.
  Such a token can be obtained from the dashboard page after logging in.  This
  token can then be passed along in the \t{Authorization} HTTP header as:
\begin{lstlisting}
Authorization: token YOUR_TOKEN_HERE
\end{lstlisting}

\subsection{\t{/v2/account} (\t{GET})}

  This API endpoint can be used to retrieve information about the account
  identified with the API token.

  Example usage:
\begin{lstlisting}[language=bash]
curl --header "Authorization: token YOUR_TOKEN_HERE" \
     (@*\djehutybaseurl{}*@)/v2/account | jq
\end{lstlisting}

  Output of the example:
\begin{lstlisting}[language=JSON]
{ /* Example output has been shortened. */
  "id": null,
  "uuid": "df7c0e54-b988-42b1-a815-308513d2f269",
  "is_active": true,
  "is_public": false,
  ...
}
\end{lstlisting}

\section{Authors}

\subsection{\t{/v2/account/authors/search} (\t{POST})}

  This API endpoint can be used to search for authors known to the data
  repository.

  Example usage:
\begin{lstlisting}[language=bash]
curl --request POST \
     --header "Authorization: token YOUR_TOKEN_HERE" \
     --data '{ "search": "John Doe" }' \
     (@*\djehutybaseurl{}*@)/v2/account/authors/search | jq
\end{lstlisting}

  Output of the example:
\begin{lstlisting}[language=JSON]
[ /* This example output has been shortened. */
  {
    "full_name": "John Doe Jr",
    "uuid": "08f4d496-67b5-4b7c-b2d2-923458d1f450",
    "orcid_id": "",
    ...
  },
  {
    "full_name": "John Doe",
    "uuid": "6815031c-21dc-4873-93c9-f6539da482ce",
    "orcid_id": "",
    ...
  }
]
\end{lstlisting}

\subsection{\t{/v2/account/authors/<author-id>} (\t{GET})}

  This API endpoint returns a detailed author record for the author identified
  by \code{author-id}.

  Example usage:
\begin{lstlisting}[language=bash]
curl --header "Authorization: token YOUR_TOKEN_HERE" \
     (@*\djehutybaseurl{}*@)/v2/account/authors/5c75...94aa | jq
\end{lstlisting}

  Output of the example:
\begin{lstlisting}[language=JSON]
{ /* This example output has been shortened. */
  "first_name": "Roel",
  "full_name": "Roel Janssen",
  "uuid": "5c752155-60ff-41d7-9b88-b7112afc94aa",
  "last_name": "Janssen",
  "orcid_id": "0000-0003-4324-5350",
  ...
}
\end{lstlisting}

\section{Creating and editing datasets}

\subsection{\t{/v2/account/articles} (\t{GET})}

  This API endpoint lists the draft datasets of the account to which the
  authorization token belongs.

  The following parameters can be used:

\begin{tabularx}{\textwidth}{*{2}{!{\VRule[-1pt]}l}!{\VRule[-1pt]}X}
  \headrow
  \textbf{Parameter}   & \textbf{Required} & \textbf{Description}\\
  \t{page}             & Optional & The page number used in combination with
                                    \t{page\_size}.\\
  \t{page\_size}       & Optional & The number of datasets per page.  Used
                                    in combination with \t{page}.\\
  \t{limit}            & Optional & The maximum number of datasets to output.
                                    Used together with \t{offset}.\\
  \t{offset}           & Optional & The number of datasets to skip in the
                                    output.  Used together with \t{limit}.
\end{tabularx}

  Example usage:
\begin{lstlisting}[language=bash]
curl --header "Authorization: token YOUR_TOKEN_HERE" \
     (@*\djehutybaseurl{}*@)/v2/account/articles | jq
\end{lstlisting}

  Output of the example:
\begin{lstlisting}[language=JSON]
{ /* Example output has been shortened. */
  "id": null,
  "uuid": "6ddd7a31-8ad8-4c20-95a3-e68fe716fa42",
  "title": "Example draft dataset",
  "doi": null,
  "handle": null,
  "url": "(@*\djehutybaseurl{}*@)/v2/articles/6ddd7a31-8ad8-4c20-95a3-e68fe716fa42",
  "published_date": null,
  ...
}
\end{lstlisting}

\subsection{\t{/v2/account/articles} (\t{POST})}

  This API endpoint can be used to create a new dataset.

  The following parameters can be used:

\begin{tabularx}{\textwidth}{*{2}{!{\VRule[-1pt]}l}!{\VRule[-1pt]}X}
  \headrow
  \textbf{Parameter} & \textbf{Data type}   & \textbf{Description}\\
  \t{title}          & \t{string}           & The title of the dataset.\\
  \t{description}    & \t{string}           & A description of the dataset.\\
  \t{tags}           & list of \t{string}s  & Keywords to enhance the
                                              findability of the dataset. Instead
                                              of using the key \code{tags}, you
                                              may also use the key
                                              \code{keywords}.\\
  \t{keywords}       & list of \t{string}s  & See \t{tags}.\\
  \t{references}     & list of \t{string}s  & URLs to resources referring to
                                              this dataset, or resources that
                                              this dataset refers to.\\
  \t{categories}     & list of \t{string}s  & \categoryDescription\\
  \t{authors}        & list of author records & \\
  \t{defined\_type}  & \t{string}           & One of: \t{figure},
                                              \t{online resource},
                                              \t{preprint}, \t{book},
                                              \t{conference contribution},
                                              \t{media}, \t{dataset},
                                              \t{poster},
                                              \t{journal contribution},
                                              \t{presentation},
                                              \t{thesis} or \t{software}.\\
  \t{funding}        & \t{string}           & One-liner to cite funding.\\
  \t{funding\_list}  & list of funding records & \\
  \t{license}        & \t{integer}          & Licences communicate under which
                                              conditions the dataset can be
                                              re-used.  The \t{integer} value
                                              to submit here can be found as
                                              the \t{value} property in a call
                                              to \code{/v2/licences}. For more
                                              details, see section
                                              \refer{sec:v2-licenses}.\\
  \t{language}       & \t{string}           & An ISO 639-1 language code.\\
  \t{doi}            & \t{string}           & Do not use this field as a DOI
                                              will be automatically assigned
                                              upon publication..\\
  \t{handle}         & \t{string}           & Do not use this field as it is
                                              deprecated.\\
  \t{resource\_doi}  & \t{string}           & The URL of the DOI of an
                                              associated peer-reviewed
                                              journal publication.\\
  \t{resource\_title} & \t{string}          & The title of the associated
                                              peer-reviewed journal
                                              publication.\\
  %\t{group\_id}      & \t{integer}          & \\
  \t{publisher}      & \t{string}           & The name of the data repository
                                              publishing the dataset.\\
  \t{custom\_fields} & list of key-value pairs & \customFieldsDescription\\
  \t{custom\_fields\_list} & list of \t{Objects} & \customFieldsListDescription\\
  \t{timeline}       &                      & Do not use this field because it
                                              will be automatically populated
                                              during the publication process.
\end{tabularx}

  Example usage:
\begin{lstlisting}[language=bash]
curl --header "Authorization: token YOUR_TOKEN_HERE" \
     --header "Content-Type: application/json" \
     --data '{ "title": "Example dataset" }' \
     (@*\djehutybaseurl{}*@)/v2/account/articles | jq
\end{lstlisting}

  Output of the example:
\begin{lstlisting}[language=JSON]
{ /* The UUID in this example has been shortened. */
  "location": "(@*\djehutybaseurl{}*@)/v2/account/articles/d7b3...995b1",
  "warnings": []
}
\end{lstlisting}

\subsection{\t{/v2/account/articles/<dataset-id>} (\t{GET})}

  This API endpoint lists details of the dataset identified by \code{dataset-id}.

  Example usage:
\begin{lstlisting}[language=bash]
curl --header "Authorization: token YOUR_TOKEN_HERE" \
     (@*\djehutybaseurl{}*@)/v2/account/articles/d7b3daa5-45e2-47b0-9910-0f7fa6a995b1 | jq
\end{lstlisting}

  Output of the example:
\begin{lstlisting}[language=JSON]
{ /* Example output has been shortened. */
  "files": [],
  "authors": [],
  "id": null,
  "uuid": "637e9a3b-3e6d-4810-bc8d-f15ab1d6a4d7",
  "title": "Example dataset",
  ...
}
\end{lstlisting}

\subsection{\t{/v2/account/articles/<dataset-id>} (\t{PUT})}

  This API endpoint can be used to update the metadata of the dataset
  identified by \code{dataset-id}.

  The following parameters can be used:

\begin{tabularx}{\textwidth}{*{2}{!{\VRule[-1pt]}l}!{\VRule[-1pt]}X}
  \headrow
  \textbf{Parameter}   & \textbf{Required} & \textbf{Description}\\
  \t{title}          & \t{string}           & The title of the dataset.\\
  \t{description}    & \t{string}           & A description of the dataset.\\
  \t{resource\_doi}  & \t{string}           & The URL of the DOI of an
                                              associated peer-reviewed
                                              journal publication.\\
  \t{resource\_title} & \t{string}          & The title of the associated
                                              peer-reviewed journal
                                              publication.\\
  \t{license}        & \t{integer}          & Licences communicate under which
                                              conditions the dataset can be
                                              re-used.  The \t{integer} value
                                              to submit here can be found as
                                              the \t{value} property in a call
                                              to \code{/v2/licences}. For more
                                              details, see section
                                              \refer{sec:v2-licenses}.\\
  \t{group\_id}      & \t{integer}          & \\
  \t{time\_coverage} & \t{string}           & Free-text field to describe the
                                              time coverage of the dataset.\\
  \t{publisher}      & \t{string}           & The name of the data repository
                                              publishing the dataset.\\
  \t{language}       & \t{string}           & An ISO 639-1 language code.\\
  \t{contributors}   & \t{string}           & Free-text field to indicate
                                              contributors to the dataset
                                              other than direct authors.\\
  \t{license\_remarks} & \t{string}         & Free-text field to clarify
                                              licensing details.\\
  \t{geolocation}    & \t{string}           & Free-text field to specify a
                                              location.\\
  \t{longitude}      & \t{string}           & The longitude coordinate of the
                                              location.\\
  \t{latitude}       & \t{string}           & The latitude coordinate of the
                                              location.\\
  \t{format}         & \t{string}           & Free-text field to indicate the
                                              data format(s) used in the
                                              dataset.\\
  \t{data\_link}     & \t{string}           & URL to where the data can be
                                              found.  This is only applicable
                                              when data is not directly
                                              uploaded.\\
  \t{derived\_from}  & \t{string}           & DOI or URL of a dataset from
                                              which this dataset is derived
                                              from.\\
  \t{same\_as}       & \t{string}           & DOI or URL of the dataset that
                                              is the same as this one.\\
  \t{organizations}  & \t{string}           & Free-text field to specify
                                              organizations that contributed
                                              or are associated with the
                                              dataset.\\
  \t{is\_embargoed}  & \t{boolean}          & Set to \code{true} when the
                                              dataset is under embargo.\\
  \t{embargo\_options} & \t{Object}         & An \t{Object} with an \t{id}
                                              property that can have either
                                              the integer value \t{1000} to
                                              indicate the dataset has no
                                              end-date for the embargo or the
                                              integer value \t{1001} to indicate
                                              that the dataset is permanently
                                              closed-access.\\
  \t{embargo\_until\_date} & \t{string}     & A date indicator for when the
                                              dataset will be available
                                              publically.\\
  \t{embargo\_type}  & \t{string}           & Either \t{file} for files-only
                                              embargo or \t{article} to also
                                              hide the metadata, except for the
                                              title and authors of the dataset.\\
  \t{embargo\_title} & \t{string}           & Title of the embargo.\\
  \t{embargo\_reason} & \t{string}          & Reason for the embargo.\\
  \t{is\_metadata\_record} & \t{boolean}    & Set to \t{true} when no data is
                                              associated with this dataset.\\
  \t{metadata\_reason} & \t{string}         & Reason why the dataset is
                                              metadata-only.\\
  \t{eula}           & \t{string}           & An End-User-License-Agreement.\\
  \t{defined\_type}  & \t{string}           & Either \t{software} to indicate
                                              the dataset is software or
                                              \t{dataset} to indicate the
                                              dataset is data (not software).\\
  \t{git\_repository\_name} & \t{string}    & Title of the Git repository (for
                                              software datasets only).  This is
                                              a djehuty-extension to the
                                              original API specification.\\
  \t{git\_code\_hosting\_url} & \t{string}  & Link to the code hosting platform
                                              (e.g. Gitlab, or any other).  This
                                              is a djehuty-extension to the
                                              original API specification.\\
  \t{agreed\_to\_deposit\_agreement} & \t{boolean} & Set to \t{true} when you
                                              agree to the repository's deposit
                                              agreement.  This is a
                                              djehuty-extension to the original
                                              API specification.\\
  \t{agreed\_to\_publish} & \t{boolean}     & Set to \t{true} to indicate the
                                              dataset may be published.  This
                                              is a djehuty-extension to the
                                              original API specification.\\
  \t{categories}     & list of \t{string}s  & \categoryDescription
\end{tabularx}

  Example usage:
\begin{lstlisting}[language=bash]
curl --verbose --request PUT \
     --header "Authorization: token YOUR_TOKEN_HERE" \
     --data '{ "title": "Updated title" }'
     (@*\djehutybaseurl{}*@)/v2/account/articles/d7b3daa5-45e2-47b0-9910-0f7fa6a995b1 | jq
\end{lstlisting}

  HTTP response of the example:
\begin{lstlisting}
HTTP/1.1 205 RESET CONTENT
\end{lstlisting}

\subsection{\t{/v2/account/articles/<dataset-id>} (\t{DELETE})}

  This API endpoint can be used to delete a draft dataset.

  Example usage:
\begin{lstlisting}[language=bash]
curl --verbose --request DELETE \
     --header "Authorization: token YOUR_TOKEN_HERE" \
     (@*\djehutybaseurl{}*@)/v2/account/articles/d7b3daa5-45e2-47b0-9910-0f7fa6a995b1
\end{lstlisting}

  HTTP response of the example:
\begin{lstlisting}
HTTP/1.1 204 NO CONTENT
\end{lstlisting}

\subsection{\t{/v2/account/articles/<dataset-id>/authors} (\t{GET})}
\label{sec:api-v2-articles-authors}

  This API endpoint lists the authors of the dataset identified by \code{dataset-id}.
  The following URL parameters can be used:

\begin{tabularx}{\textwidth}{*{2}{!{\VRule[-1pt]}l}!{\VRule[-1pt]}X}
  \headrow
  \textbf{Parameter}   & \textbf{Required} & \textbf{Description}\\
  \t{order}            & Optional & Field to use for sorting.\\
  \t{order\_direction} & Optional & Can be either \code{asc} or \code{desc}.\\
  \t{limit}            & Optional & The maximum number of datasets to output.
                                    Used together with \t{offset}.
\end{tabularx}

  Example usage:
\begin{lstlisting}[language=bash]
curl --header "Authorization: token YOUR_TOKEN_HERE" \
     (@*\djehutybaseurl{}*@)/v2/account/articles/d7b3daa5-45e2-47b0-9910-0f7fa6a995b1 | jq
\end{lstlisting}

  Output of the example:
\begin{lstlisting}[language=JSON]
[
  {
    "id": null,
    "uuid": "08f4d496-67b5-4b7c-b2d2-923458d1f450",
    "full_name": "John Doe Jr",
    "is_active": false,
    "url_name": null,
    "orcid_id": ""
  },
  {
    "id": null,
    "uuid": "6815031c-21dc-4873-93c9-f6539da482ce",
    "full_name": "John Doe",
    "is_active": false,
    "url_name": null,
    "orcid_id": ""
  }
]
\end{lstlisting}

\subsection{\t{/v2/account/articles/<dataset-id>/authors} (\t{POST})}
\label{sec:api-v2-articles-authors-post}

  This API endpoint can be used to append authors to the dataset identified
  by \code{dataset-id}.

  Example usage:
\begin{lstlisting}[language=bash]
curl --request POST \
     --header "Authorization: token YOUR_TOKEN_HERE" \
     --header "Content-Type: application/json" \
     --data '{ "authors": [{ "name": "John Doe" }]}' \
     (@*\djehutybaseurl{}*@)/v2/account/articles/d7b3daa5-45e2-47b0-9910-0f7fa6a995b1/authors
curl --request POST \
     --header "Authorization: token YOUR_TOKEN_HERE" \
     --header "Content-Type: application/json" \
     --data '{ "authors": [{ "name": "John Doe Jr" }]}' \
     (@*\djehutybaseurl{}*@)/v2/account/articles/d7b3daa5-45e2-47b0-9910-0f7fa6a995b1/authors
\end{lstlisting}

  The following is an example of the output of the HTTP \texttt{POST} calls:
\begin{lstlisting}
HTTP/1.1 205 RESET CONTENT
\end{lstlisting}

  An example of the output of the HTTP \texttt{GET} call can be found in
  \refer{sec:api-v2-articles-authors}.

\subsection{\t{/v2/account/articles/<dataset-id>/authors} (\t{PUT})}

  In contrast to \refer{sec:api-v2-articles-authors-post}, this API endpoint
  can be used to \textbf{overwrite} the list of authors of the dataset identified
  by \code{dataset-id}.

  Example usage:
\begin{lstlisting}[language=bash]
curl --request PUT \
     --header "Authorization: token YOUR_TOKEN_HERE" \
     --header "Content-Type: application/json" \
     --data '{ "authors": [{ "name": "John Doe" }]}' \
     (@*\djehutybaseurl{}*@)/v2/account/articles/d7b3daa5-45e2-47b0-9910-0f7fa6a995b1/authors

curl --request PUT \
     --header "Authorization: token YOUR_TOKEN_HERE" \
     --header "Content-Type: application/json" \
     --data '{ "authors": [{ "name": "John Doe Jr" }]}' \
     (@*\djehutybaseurl{}*@)/v2/account/articles/d7b3daa5-45e2-47b0-9910-0f7fa6a995b1/authors

curl --header "Authorization: token YOUR_TOKEN_HERE" \
     (@*\djehutybaseurl{}*@)/v2/account/articles/d7b3daa5-45e2-47b0-9910-0f7fa6a995b1 | jq
\end{lstlisting}

  Output of the example:
\begin{lstlisting}[language=JSON]
[
  {
    "id": null,
    "uuid": "61751fe3-53a1-477f-a46f-e534cbd0b618",
    "full_name": "John Doe Jr",
    "is_active": false,
    "url_name": null,
    "orcid_id": ""
  },
]
\end{lstlisting}

\subsection{\t{/v2/account/articles/<dataset-id>/authors/<author-id>} (\t{DELETE})}

  This API endpoint can be used to delete an author's association with a dataset.

  Example usage:
\begin{lstlisting}[language=bash]
curl --request DELETE \
     --header "Authorization: token YOUR_TOKEN_HERE" \
     (@*\djehutybaseurl{}*@)/v2/account/articles/d7b3...995b1/authors/6175...0b618
\end{lstlisting}

  HTTP response of the example:
\begin{lstlisting}
HTTP/1.1 204 NO CONTENT
\end{lstlisting}

\subsection{\t{/v2/account/articles/<dataset-id>/funding} (\t{GET})}

  This API endpoint lists the funding of the dataset identified by \code{dataset-id}.

  Example usage:
\begin{lstlisting}[language=bash]
curl --header "Authorization: token YOUR_TOKEN_HERE" \
     (@*\djehutybaseurl{}*@)/v2/account/articles/d7b3...95b1/funding | jq
\end{lstlisting}

  Output of the example:
\begin{lstlisting}[language=JSON]
[
  {
    "id": null,
    "uuid": "6f605fe1-e87a-43f5-8b67-70ebe3f9b868",
    "title": "Example cases fund",
    "grant_code": "EXA-001",
    "funder_name": "Example",
    "is_user_defined": null,
    "url": "https://example.exa"
  }
]
\end{lstlisting}

\subsection{\t{/v2/account/articles/<dataset-id>/funding} (\t{POST})}
\label{sec:api-v2-articles-funding-post}

  This API endpoint can be used to append funders to the dataset identified
  by \code{dataset-id}.

  Example usage:
\begin{lstlisting}[language=bash]
curl --verbose --request POST \
     --header "Authorization: token YOUR_TOKEN_HERE" \
     --header "Content-Type: application/json" \
     --data '{ "funders": [{ "title": "Example cases fund", \
                             "grant_code": "EXA-001", \
                             "funder_name": "Example", \
                             "url": "https://example.exa" }]}' \
     (@*\djehutybaseurl{}*@)/v2/account/articles/d7b3daa5-45e2-47b0-9910-0f7fa6a995b1/funding
\end{lstlisting}

  HTTP response of the example:
\begin{lstlisting}
HTTP/1.1 205 RESET CONTENT
\end{lstlisting}

\subsection{\t{/v2/account/articles/<dataset-id>/funding} (\t{PUT})}

  In contrast to \refer{sec:api-v2-articles-funding-post}, this API endpoint
  can be used to \textbf{overwrite} the list of funders of the dataset
  identified by \code{dataset-id}.

\begin{lstlisting}[language=bash]
curl --verbose --request PUT \
     --header "Authorization: token YOUR_TOKEN_HERE" \
     --header "Content-Type: application/json" \
     --data '{ "funders": [{ "title": "Example cases fund",
                             "grant_code": "EXA-001",
                             "funder_name": "Example",
                             "url": "https://example.exa" }]}' \
     (@*\djehutybaseurl{}*@)/v2/account/articles/d7b3daa5-45e2-47b0-9910-0f7fa6a995b1/funding
\end{lstlisting}

  HTTP response of the example:
\begin{lstlisting}
HTTP/1.1 205 RESET CONTENT
\end{lstlisting}

\subsection{\t{/v2/account/articles/<dataset-id>/funding/<funding-id>} (\t{DELETE})}

  This API endpoint can be used to delete an funder's association with a dataset.

  Example usage:
\begin{lstlisting}[language=bash]
curl --request DELETE \
     --header "Authorization: token YOUR_TOKEN_HERE" \
     (@*\djehutybaseurl{}*@)/v2/account/articles/d7b3...995b1/funding/d50e...7500
\end{lstlisting}

  HTTP response of the example:
\begin{lstlisting}
HTTP/1.1 204 NO CONTENT
\end{lstlisting}

\subsection{\t{/v2/account/articles/<dataset-id>/categories} (\t{GET})}

  This API endpoint lists the categories of the dataset identified by \code{dataset-id}.
  The identifiers for the categories can be found by using the API endpoint
  described at \refer{sec:v2-categories}.

  Example usage:
\begin{lstlisting}[language=bash]
curl --header "Authorization: token YOUR_TOKEN_HERE" \
     (@*\djehutybaseurl{}*@)/v2/account/articles/d7b3...95b1/categories | jq
\end{lstlisting}

  Output of the example:
\begin{lstlisting}[language=JSON]
[
  {
    "id": 13558,
    "uuid": "8f27eb44-0a63-4496-ba6d-e3cbf4efa6c7",
    "title": "Other Earth Sciences",
    "parent_id": 13551,
    "parent_uuid": "dd4dbaaf-0610-4d8d-8b07-e1eeb32dd11c",
    "path": "",
    "source_id": null,
    "taxonomy_id": null
  },
  {
    "id": 13551,
    "uuid": "dd4dbaaf-0610-4d8d-8b07-e1eeb32dd11c",
    "title": "Earth Sciences",
    "parent_id": null,
    "parent_uuid": null,
    "path": "",
    "source_id": null,
    "taxonomy_id": null
  }
]
\end{lstlisting}

\subsection{\t{/v2/account/articles/<dataset-id>/categories} (\t{POST})}
\label{sec:api-v2-articles-categories-post}

  This API endpoint can be used to append categories to the dataset identified
  by \code{dataset-id}.

  Example usage:
\begin{lstlisting}[language=bash]
curl --verbose --request POST \
     --header "Authorization: token YOUR_TOKEN_HERE" \
     --header "Content-Type: application/json" \
     --data '{ "categories": [13551, 13558]}' \
     (@*\djehutybaseurl{}*@)/v2/account/articles/d7b3...995b1/categories
\end{lstlisting}

  HTTP response of the example:
\begin{lstlisting}
HTTP/1.1 205 RESET CONTENT
\end{lstlisting}

\subsection{\t{/v2/account/articles/<dataset-id>/categories} (\t{PUT})}

  In contrast to \refer{sec:api-v2-articles-categories-post}, this API endpoint
  can be used to \textbf{overwrite} the list of categories of the dataset identified
  by \code{dataset-id}.

  Example usage:
\begin{lstlisting}[language=bash]
curl --verbose --request POST \
     --header "Authorization: token YOUR_TOKEN_HERE" \
     --header "Content-Type: application/json" \
     --data '{ "categories": ["dd4dbaaf-0610-4d8d-8b07-e1eeb32dd11c"]}' \
     (@*\djehutybaseurl{}*@)/v2/account/articles/d7b3...995b1/categories
\end{lstlisting}

  HTTP response of the example:
\begin{lstlisting}
HTTP/1.1 205 RESET CONTENT
\end{lstlisting}

\subsection{\t{/v2/account/articles/<dataset-id>/categories/<category-id>} (\t{DELETE})}

  This API endpoint can be used to delete a category's association with a dataset.
  The \code{category-id} can be either the \code{uuid} or the \code{id} property.

  Example usage:
\begin{lstlisting}[language=bash]
curl --request DELETE \
     --header "Authorization: token YOUR_TOKEN_HERE" \
     (@*\djehutybaseurl{}*@)/v2/account/articles/d7b3...995b1/categories/5c61...b668
\end{lstlisting}

  HTTP response of the example:
\begin{lstlisting}
HTTP/1.1 204 NO CONTENT
\end{lstlisting}

\subsection{\t{/v2/account/articles/<dataset-id>/embargo} (\t{GET})}

  This API endpoint lists the embargo status of the dataset identified by \code{dataset-id}.

  Example usage:
\begin{lstlisting}[language=bash]
curl --header "Authorization: token YOUR_TOKEN_HERE" \
     (@*\djehutybaseurl{}*@)/v2/account/articles/d7b3...995b1/embargo | jq
\end{lstlisting}

  Output of the example:
\begin{lstlisting}[language=JSON]
{
  "is_embargoed": false,
  "embargo_date": null,
  "embargo_type": "file",
  "embargo_title": "",
  "embargo_reason": "",
  "embargo_options": []
}
\end{lstlisting}

\subsection{\t{/v2/account/articles/<dataset-id>/embargo} (\t{DELETE})}

  This API endpoint can be used to remove an embargo on the dataset
  identified by \code{dataset-id}.

  Example usage:
\begin{lstlisting}[language=bash]
curl --verbose --request DELETE \
     --header "Authorization: token YOUR_TOKEN_HERE" \
     (@*\djehutybaseurl{}*@)/v2/account/articles/d7b3d...995b1/embargo
\end{lstlisting}

  HTTP response of the example:
\begin{lstlisting}
HTTP/1.1 204 NO CONTENT
\end{lstlisting}

\subsection{\t{/v2/account/articles/<dataset-id>/files} (\t{GET})}

  This API endpoint lists files associated with the dataset identified by
  \code{dataset-id}.

  Example usage:
\begin{lstlisting}[language=bash]
curl --header "Authorization: token YOUR_TOKEN_HERE" \
     (@*\djehutybaseurl{}*@)/v2/account/articles/d7b3...995b1/files | jq
\end{lstlisting}

  Output of the example:
\begin{lstlisting}[language=JSON]
[ /* Example output has been shortened. */
  {
    "id": null,
    "uuid": "d112d0cd-bc15-4f8e-9013-930750fc017a",
    "name": "README.md",
    "size": 3696,
    "is_link_only": false,
    "is_incomplete": false,
    "download_url": "https://next.data.4tu.nl/file/d7b3...995b1/d112...c017a",
    "supplied_md5": null,
    "computed_md5": "c5b36584a0d62d28e9bf9e6892d9ebac"
  }
]
\end{lstlisting}

\subsection{\t{/v2/account/articles/<dataset-id>/files} (\t{DELETE})}

  \NoteBox{
    This API endpoint is a djehuty extension to the original specification.
  }

  This API endpoint can be used to delete all files associated with the
  dataset identified by \code{dataset-id}.

  Example usage:
\begin{lstlisting}[language=bash]
curl --request DELETE \
     --header "Authorization: token YOUR_TOKEN_HERE" \
     --header "Content-Type: application/json" \
     --data '{ "remove_all": true }' \
     (@*\djehutybaseurl{}*@)/v2/account/articles/d7b3...995b1/files
\end{lstlisting}

  HTTP response of the example:
\begin{lstlisting}
HTTP/1.1 204 NO CONTENT
\end{lstlisting}

\subsection{\t{/v2/account/articles/<dataset-id>/files/<file-id>} (\t{GET})}

  This API endpoint lists files associated with the dataset identified by
  \code{dataset-id}.

  Example usage:
\begin{lstlisting}[language=bash]
curl --header "Authorization: token YOUR_TOKEN_HERE" \
     (@*\djehutybaseurl{}*@)/v2/account/articles/d7b3...995b1/files | jq
\end{lstlisting}

  Output of the example:
\begin{lstlisting}[language=JSON]
[ /* Example output has been shortened. */
  {
    "id": null,
    "uuid": "d112d0cd-bc15-4f8e-9013-930750fc017a",
    "name": "README.md",
    "size": 3696,
    "is_link_only": false,
    "is_incomplete": false,
    "download_url": "https://next.data.4tu.nl/file/d7b3...995b1/d112...c017a",
    "supplied_md5": null,
    "computed_md5": "c5b36584a0d62d28e9bf9e6892d9ebac"
  }
]
\end{lstlisting}

\subsection{\t{/v2/account/articles/<dataset-id>/private\_links} (\t{GET})}

  This API endpoint lists the private links associated with the dataset
  identified by \code{dataset-id}.

  Example usage:
\begin{lstlisting}[language=bash]
curl --header "Authorization: token YOUR_TOKEN_HERE" \
     (@*\djehutybaseurl{}*@)/v2/account/articles/d7b3...995b1/private_links | jq
\end{lstlisting}

  Output of the example:
\begin{lstlisting}[language=JSON]
[
  {
    "id": "8G2f...IJP0",
    "is_active": true,
    "expires_date": "2032-01-01T00:00:00"
  },
  {
    "id": "Hb0a...diitg",
    "is_active": true,
    "expires_date": "2026-01-01T00:00:00"
  }
]
\end{lstlisting}

\subsection{\t{/v2/account/articles/<dataset-id>/private\_links} (\t{POST})}

  This API endpoint can be used to append a private link to the dataset
  identified by \code{dataset-id}.

  Example usage:
\begin{lstlisting}[language=bash]
curl --request POST \
     --header "Authorization: token YOUR_TOKEN_HERE" \
     --data '{ "expires_date": "2032-01-01", "read_only": false }' \
     (@*\djehutybaseurl{}*@)/v2/account/articles/d7b3...995b1/private_links | jq
\end{lstlisting}

  output of the example:
\begin{lstlisting}[language=JSON]
{ /* Example output has been shortened. */
  "location": "(@*\djehutybaseurl{}*@)/private_datasets/8G2fk..."
}
\end{lstlisting}

\subsection{\t{/v2/account/articles/<dataset-id>/private\_links/<link-id>} (\t{GET})}

  This API endpoint can be used to view the details of a private link for
  the dataset identified by \code{dataset-id}.

  Example usage:
\begin{lstlisting}[language=bash]
curl --header "Authorization: token YOUR_TOKEN_HERE" \
     (@*\djehutybaseurl{}*@)/v2/account/articles/d7b3...995b1/private_links/8G2fk... | jq
\end{lstlisting}

  Output of the example:
\begin{lstlisting}[language=JSON]
[
  {
    "id": "8G2f...IJP0",
    "is_active": true,
    "expires_date": "2032-01-01T00:00:00"
  }
]
\end{lstlisting}

\subsection{\t{/v2/account/articles/<dataset-id>/private\_links/<link-id>} (\t{PUT})}

  This API endpoint can be used to update the expiry date of a private link
  and whether the private link is active or not for the dataset identified
  by \code{dataset-id}.

  Example usage:
\begin{lstlisting}[language=bash]
curl --request PUT \
     --header "Authorization: token YOUR_TOKEN_HERE" \
     --data '{ "expires_date": "2034-01-01", "is_active": true }' \
     (@*\djehutybaseurl{}*@)/v2/account/articles/d7b3...995b1/private_links/8G2fk... | jq
\end{lstlisting}

  Output of the example:
\begin{lstlisting}[language=JSON]
{ /* Example output has been shortened. */
  "location": "(@*\djehutybaseurl{}*@)/private_datasets/8G2fk..."
}
\end{lstlisting}

\subsection{\t{/v2/account/articles/<dataset-id>/private\_links/<link-id>} (\t{DELETE})}

  This API endpoint can be used to remove a private link for the dataset identified
  by \code{dataset-id}.

  Example usage:
\begin{lstlisting}[language=bash]
curl --request DELETE \
     --header "Authorization: token YOUR_TOKEN_HERE" \
     (@*\djehutybaseurl{}*@)/v2/account/articles/d7b3...995b1/private_links/8G2fk...
\end{lstlisting}

  HTTP response of the example:
\begin{lstlisting}
HTTP/1.1 204 NO CONTENT
\end{lstlisting}

\subsection{\t{/v2/account/articles/<dataset-id>/reserve\_doi} (\t{POST})}

  This API endpoint can be used to obtain the DOI before the dataset is
  published and the DOI is activated.

  Example usage:
\begin{lstlisting}[language=bash]
curl --request POST \
     --header "Authorization: token YOUR_TOKEN_HERE" \
     (@*\djehutybaseurl{}*@)/v2/account/articles/d7b3...995b1/reserve_doi | jq
\end{lstlisting}

  Output of the example:
\begin{lstlisting}[language=JSON]
{
  "doi": "10.5074/d7b3daa5-45e2-47b0-9910-0f7fa6a995b1"
}
\end{lstlisting}

\subsection{\t{/v2/account/articles/<dataset-id>/publish} (\t{POST})}

  This API endpoint can be used to publish the dataset identified by
  \code{dataset-id}.

  \NoteBox{
    Only users with the ``review'' privilege can succesfully
    use this API call.
  }

  Example usage:
\begin{lstlisting}[language=bash]
curl --request POST \
     --header "Authorization: token YOUR_TOKEN_HERE" \
     (@*\djehutybaseurl{}*@)/v2/account/articles/d7b3...995b1/publish | jq
\end{lstlisting}

  HTTP response of the example:
\begin{lstlisting}
HTTP/1.1 201 CREATED
\end{lstlisting}

  Output of the example:
\begin{lstlisting}[language=JSON]
{ /* Example output has been shortened. */
  "location": "(@*\djehutybaseurl{}*@)/review/published/9ce6...3976"
}
\end{lstlisting}

\section{Creating and editing collections}

\subsection{\t{/v2/account/collections} (\t{GET})}

  This API endpoint lists the draft collections of the account to which the
  authorization token belongs.

  The following parameters can be used:

\begin{tabularx}{\textwidth}{*{2}{!{\VRule[-1pt]}l}!{\VRule[-1pt]}X}
  \headrow
  \textbf{Parameter}   & \textbf{Required} & \textbf{Description}\\
  \t{page}             & Optional & The page number used in combination with
                                    \t{page\_size}.\\
  \t{page\_size}       & Optional & The number of datasets per page.  Used
                                    in combination with \t{page}.\\
  \t{limit}            & Optional & The maximum number of datasets to output.
                                    Used together with \t{offset}.\\
  \t{offset}           & Optional & The number of datasets to skip in the
                                    output.  Used together with \t{limit}.\\
  \t{order}            & Optional & Field to use for sorting.\\
  \t{order\_direction} & Optional & Can be either \code{asc} or \code{desc}.
\end{tabularx}

  Example usage:
\begin{lstlisting}[language=bash]
curl --header "Authorization: token YOUR_TOKEN_HERE" \
     (@*\djehutybaseurl{}*@)/v2/account/collections | jq
\end{lstlisting}

  Output of the example:
\begin{lstlisting}[language=JSON]
[ /* This example output has been shortened. */
  {
    "id": null,
    "uuid": "fc03a4c3-cba4-4a88-a8a6-eb38924eeb6d",
    "title": "Test collection",
    "doi": null,
    "handle": "",
    "url": "(@*\djehutybaseurl{}*@)/v2/collections/fc03...eb6d",
    "published_date": null,
    ...
  }
]
\end{lstlisting}

\subsection{\t{/v2/account/collections} (\t{POST})}

  This API endpoint can be used to create a new collection.

  The following parameters can be used:

\begin{tabularx}{\textwidth}{*{2}{!{\VRule[-1pt]}l}!{\VRule[-1pt]}X}
  \headrow
  \textbf{Parameter} & \textbf{Data type}   & \textbf{Description}\\
  \t{title}          & \t{string}           & The title of the collection.\\
  \t{description}    & \t{string}           & A description of the collection.\\
  \t{tags}           & list of \t{string}s  & Keywords to enhance the
                                              findability of the collection. Instead
                                              of using the key \code{tags}, you
                                              may also use the key
                                              \code{keywords}.\\
  \t{references}     & list of \t{string}s  & URLs to resources referring to
                                              this collection, or resources that
                                              this collection refers to.\\
  \t{categories}     & list of \t{string}s  & \categoryDescription\\
  \t{authors}        & list of author records & \\
  \t{funding}        & \t{string}           & One-liner to cite funding.\\
  \t{funding\_list}  & list of funding records & \\
  \t{license}        & \t{integer}          & Licences communicate under which
                                              conditions the collection can be
                                              re-used.  The \t{integer} value
                                              to submit here can be found as
                                              the \t{value} property in a call
                                              to \code{/v2/licences}. For more
                                              details, see section
                                              \refer{sec:v2-licenses}.\\
  %\t{language}       & \t{string}           & \\
  \t{doi}            & \t{string}           & Do not use this field as a DOI
                                              will be automatically assigned
                                              upon publication..\\
  \t{handle}         & \t{string}           & Do not use this field as it is
                                              deprecated.\\
  \t{resource\_doi}  & \t{string}           & The URL of the DOI of an
                                              associated peer-reviewed
                                              journal publication.\\
  \t{resource\_title} & \t{string}          & The title of the associated
                                              peer-reviewed journal
                                              publication.\\
  %\t{group_id}       & \t{integer}          & \\
  \t{custom\_fields} & \t{Object}           & \customFieldsDescription\\
  \t{custom\_fields\_list} & list of \t{Objects} & \customFieldsListDescription\\
  \t{timeline}       &                      & Do not use this field because it
                                              will be automatically populated
                                              during the publication process.\\
  \t{articles}       & list of strings or integers & The articles to include
                                              in the collection.
\end{tabularx}

  Example usage:
\begin{lstlisting}[language=bash]
curl --header "Authorization: token YOUR_TOKEN_HERE" \
     --header "Content-Type: application/json" \
     --data '{ "title": "Example collection" }' \
     (@*\djehutybaseurl{}*@)/v2/account/collections | jq
\end{lstlisting}

  Output of the example:
\begin{lstlisting}[language=JSON]
{
  "location": "(@*\djehutybaseurl{}*@)/v2/account/collections/08b7...cfa8",
  "warnings": []
}
\end{lstlisting}

\subsection{\t{/v2/account/collections/<collection-id>} (\t{GET})}
\label{sec:v2-collections-collection-id}

  This API endpoint lists details of the collection identified by \code{collection-id}.

  Example usage:
\begin{lstlisting}[language=bash]
curl --header "Authorization: token YOUR_TOKEN_HERE" \
     (@*\djehutybaseurl{}*@)/v2/account/collections/08b7...cfa8 | jq
\end{lstlisting}

  Output of the example:
\begin{lstlisting}[language=JSON]
{ /* Example output has been shortened. */
  "articles_count": 0,
  "authors": [],
  "id": null,
  "uuid": "08b702d6-98a0-4081-9445-5aeae720cfa8",
  "title": "Example collection",
  ...
}
\end{lstlisting}

\subsection{\t{/v2/account/collections/<collection-id>} (\t{PUT})}

  This API endpoint can be used to update the metadata of the collection
  identified by \code{collection-id}.

  The following parameters can be used:

\begin{tabularx}{\textwidth}{*{3}{!{\VRule[-1pt]}l}!{\VRule[-1pt]}X}
  \headrow
  \textbf{Parameter} & \textbf{Data type} & \textbf{Required} & \textbf{Description}\\
  \t{title}          & \t{string}    & Yes  & The title of the collection.\\
  \t{description}    & \t{string}    & No   & A description of the collection.\\
  \t{resource\_doi}  & \t{string}    & No   & The URL of the DOI of an
                                              associated peer-reviewed
                                              journal publication.\\
  \t{resource\_title} & \t{string}   & No   & The title of the associated
                                              peer-reviewed journal
                                              publication.\\
  \t{group\_id}      & \t{integer}   & No   & \\
  \t{time\_coverage} & \t{string}    & No   & Free-text field to describe the
                                              time coverage of the collection.\\
  \t{publisher}      & \t{string}    & No   & The name of the data repository
                                              publishing the collection.\\
  \t{language}       & \t{string}    & No   & An ISO 639-1 language code.\\
  \t{contributors}   & \t{string}    & No   & Free-text field to indicate
                                              contributors to the collection
                                              other than direct authors.\\
  \t{geolocation}    & \t{string}    & No   & Free-text field to specify a
                                              location.\\
  \t{longitude}      & \t{string}    & No   & The longitude coordinate of the
                                              location.\\
  \t{latitude}       & \t{string}    & No   & The latitude coordinate of the
                                              location.\\
  \t{organizations}  & \t{string}    & No   & Free-text field to specify
                                              organizations that contributed
                                              or are associated with the
                                              collection.\\
  \t{categories}     & list of \t{string}s & No & \categoryDescription
\end{tabularx}

  Example usage:
\begin{lstlisting}[language=bash]
curl --verbose --request PUT \
     --header "Authorization: token YOUR_TOKEN_HERE" \
     --header "Content-Type: application/json" \
     --data '{ "title": "Updated title" }' \
     (@*\djehutybaseurl{}*@)/v2/account/collections/08b702d6-98a0-4081-9445-5aeae720cfa8 | jq
\end{lstlisting}

  HTTP response of the example:
\begin{lstlisting}
HTTP/1.1 205 RESET CONTENT
\end{lstlisting}

\subsection{\t{/v2/account/collections/<collection-id>} (\t{DELETE})}

  This API endpoint can be used to delete a draft collection.

  Example usage:
\begin{lstlisting}[language=bash]
curl --verbose --request DELETE \
     --header "Authorization: token YOUR_TOKEN_HERE" \
     (@*\djehutybaseurl{}*@)/v2/account/collections/08b702d6-98a0-4081-9445-5aeae720cfa8
\end{lstlisting}

  HTTP response of the example:
\begin{lstlisting}
HTTP/1.1 204 NO CONTENT
\end{lstlisting}

\subsection{\t{/v2/account/collections/search} (\t{POST})}

  This API call searches for collections, including drafts created
  by the account performing the search.

  Example usage:
\begin{lstlisting}[language=bash]
curl --request POST \
     --header "Authorization: token YOUR_TOKEN_HERE" \
     --header "Content-Type: application/json" \
     --data '{ "search_for": "Example" }' \
     (@*\djehutybaseurl{}*@)/v2/account/collections/search | jq
\end{lstlisting}

  Output of the example:
\begin{lstlisting}[language=JSON]
[ /* Example output has been shortened. */
  {
    "id": null,
    "uuid": "08b702d6-98a0-4081-9445-5aeae720cfa8",
    "title": "Example collection",
    "url": (@*\djehutybaseurl{}*@)/v2/collections/08b7...cfa8
    ...
  }
]
\end{lstlisting}

\subsection{\t{/v2/account/collections/<collection-id>/authors} (\t{GET})}
\label{sec:api-v2-collections-authors}

  Similar to \refer{sec:api-v2-articles-authors}, this API endpoint lists the
  authors of the collection identified by \code{collection-id}.
  The following URL parameters can be used:

\begin{tabularx}{\textwidth}{*{2}{!{\VRule[-1pt]}l}!{\VRule[-1pt]}X}
  \headrow
  \textbf{Parameter}   & \textbf{Required} & \textbf{Description}\\
  \t{order}            & Optional & Field to use for sorting.\\
  \t{order\_direction} & Optional & Can be either \code{asc} or \code{desc}.\\
  \t{limit}            & Optional & The maximum number of datasets to output.
                                    Used together with \t{offset}.
\end{tabularx}

  Example usage:
\begin{lstlisting}[language=bash]
curl --header "Authorization: token YOUR_TOKEN_HERE" \
     (@*\djehutybaseurl{}*@)/v2/account/collections/3760c457-d4f3-4d58-8b94-af089a97a9b4 | jq
\end{lstlisting}

  Output of the example:
\begin{lstlisting}[language=JSON]
[
  {
    "id": null,
    "uuid": "08f4d496-67b5-4b7c-b2d2-923458d1f450",
    "full_name": "John Doe Jr",
    "is_active": false,
    "url_name": null,
    "orcid_id": ""
  },
  {
    "id": null,
    "uuid": "6815031c-21dc-4873-93c9-f6539da482ce",
    "full_name": "John Doe",
    "is_active": false,
    "url_name": null,
    "orcid_id": ""
  }
]
\end{lstlisting}

\subsection{\t{/v2/account/collections/<collection-id>/authors} (\t{POST})}
\label{sec:api-v2-collections-authors-post}

  Similar to \refer{sec:api-v2-articles-authors-post}, this API endpoint can
  be used to append authors to the collection identified by \code{collection-id}.

  Example usage:
\begin{lstlisting}[language=bash]
curl --request POST \
     --header "Authorization: token YOUR_TOKEN_HERE" \
     --header "Content-Type: application/json" \
     --data '{ "authors": [{ "name": "John Doe" }]}' \
     (@*\djehutybaseurl{}*@)/v2/account/collections/3760c457-d4f3-4d58-8b94-af089a97a9b4/authors
curl --request POST \
     --header "Authorization: token YOUR_TOKEN_HERE" \
     --header "Content-Type: application/json" \
     --data '{ "authors": [{ "name": "John Doe Jr" }]}' \
     (@*\djehutybaseurl{}*@)/v2/account/collections/3760c457-d4f3-4d58-8b94-af089a97a9b4/authors
\end{lstlisting}

  The following is an example of the output of the HTTP \texttt{POST} calls:
\begin{lstlisting}
HTTP/1.1 205 RESET CONTENT
\end{lstlisting}

  An example of the output of the HTTP \texttt{GET} call can be found in
  \refer{sec:api-v2-collections-authors}.

\subsection{\t{/v2/account/collections/<collection-id>/authors} (\t{PUT})}

  In contrast to \refer{sec:api-v2-collections-authors-post}, this API endpoint
  can be used to \textbf{overwrite} the list of authors of the collection identified
  by \code{collection-id}.

  Example usage:
\begin{lstlisting}[language=bash]
curl --request PUT \
     --header "Authorization: token YOUR_TOKEN_HERE" \
     --header "Content-Type: application/json" \
     --data '{ "authors": [{ "name": "John Doe" }]}' \
     (@*\djehutybaseurl{}*@)/v2/account/collections/3760c457-d4f3-4d58-8b94-af089a97a9b4/authors

curl --request PUT \
     --header "Authorization: token YOUR_TOKEN_HERE" \
     --header "Content-Type: application/json" \
     --data '{ "authors": [{ "name": "John Doe Jr" }]}' \
     (@*\djehutybaseurl{}*@)/v2/account/collections/3760c457-d4f3-4d58-8b94-af089a97a9b4/authors

curl --header "Authorization: token YOUR_TOKEN_HERE" \
     (@*\djehutybaseurl{}*@)/v2/account/collections/3760c457-d4f3-4d58-8b94-af089a97a9b4/authors | jq
\end{lstlisting}

  Output of the example:
\begin{lstlisting}[language=JSON]
[
  {
    "id": null,
    "uuid": "61751fe3-53a1-477f-a46f-e534cbd0b618",
    "full_name": "John Doe Jr",
    "is_active": false,
    "url_name": null,
    "orcid_id": ""
  },
]
\end{lstlisting}

\subsection{\t{/v2/account/collections/<collection-id>/authors/<author-id>} (\t{DELETE})}

  This API endpoint can be used to delete an author's association with a collection.

  Example usage:
\begin{lstlisting}[language=bash]
curl --request DELETE \
     --header "Authorization: token YOUR_TOKEN_HERE" \
     (@*\djehutybaseurl{}*@)/v2/account/collections/fc03...eb6d//authors/5c75...94aa
\end{lstlisting}

  HTTP response of the example:
\begin{lstlisting}
HTTP/1.1 204 NO CONTENT
\end{lstlisting}

\subsection{\t{/v2/account/collections/<collection-id>/categories} (\t{GET})}

  This API endpoint can be used to retrieve the categories associated with
  the collection identified by \code{collection-id}.

  Example usage:
\begin{lstlisting}[language=bash]
curl --header "Authorization: token YOUR_TOKEN_HERE" \
     (@*\djehutybaseurl{}*@)/v2/account/collections/fc03...eb6d/categories | jq
\end{lstlisting}

  Output of the example:
\begin{lstlisting}[language=JSON]
[
  {
    "id": 13376,
    "uuid": "2bdba8f2-5914-4d82-bfe8-c938cccab71f",
    "title": "Agricultural and Veterinary Sciences",
    "parent_id": null,
    "parent_uuid": null,
    "path": "",
    "source_id": null,
    "taxonomy_id": null
  }
]
\end{lstlisting}

\subsection{\t{/v2/account/collections/<collection-id>/categories} (\t{POST})}
\label{sec:api-v2-collections-categories-post}

  Similar to \refer{sec:api-v2-articles-categories-post} this API endpoint can be
  used to append categories to the collection identified by \code{collection-id}.

  Example usage:
\begin{lstlisting}[language=bash]
curl --verbose --request POST \
     --header "Authorization: token YOUR_TOKEN_HERE" \
     --header "Content-Type: application/json" \
     --data '{ "categories": [13551, 13558]}' \
     (@*\djehutybaseurl{}*@)/v2/account/collections/fc03...eb6d/categories
\end{lstlisting}

  HTTP response of the example:
\begin{lstlisting}
HTTP/1.1 205 RESET CONTENT
\end{lstlisting}

\subsection{\t{/v2/account/collections/<collection-id>/categories} (\t{PUT})}

  In contrast to \refer{sec:api-v2-collections-categories-post}, this API endpoint
  can be used to \textbf{overwrite} the list of categories of the collection identified
  by \code{collection-id}.

  Example usage:
\begin{lstlisting}[language=bash]
curl --verbose --request POST \
     --header "Authorization: token YOUR_TOKEN_HERE" \
     --header "Content-Type: application/json" \
     --data '{ "categories": ["dd4dbaaf-0610-4d8d-8b07-e1eeb32dd11c"]}' \
     (@*\djehutybaseurl{}*@)/v2/account/collections/fc03...eb6d/categories
\end{lstlisting}

  HTTP response of the example:
\begin{lstlisting}
HTTP/1.1 205 RESET CONTENT
\end{lstlisting}

\subsection{\t{/v2/account/collections/<collection-id>/categories/<category-id>} (\t{DELETE})}

  This API endpoint can be used to delete a category's association with a collection.
  The \code{category-id} can be either the \code{uuid} or the \code{id} property.

  Example usage:
\begin{lstlisting}[language=bash]
curl --request DELETE \
     --header "Authorization: token YOUR_TOKEN_HERE" \
     (@*\djehutybaseurl{}*@)/v2/account/collections/fc03...eb6d/categories/13558
\end{lstlisting}

  HTTP response of the example:
\begin{lstlisting}
HTTP/1.1 204 NO CONTENT
\end{lstlisting}

\subsection{\t{/v2/account/collections/<collection-id>/articles} (\t{GET})}

  This API endpoint can be used to retrieve the datasets associated with
  the collection identified by \code{collection-id}.

  Example usage:
\begin{lstlisting}[language=bash]
curl --header "Authorization: token YOUR_TOKEN_HERE" \
     (@*\djehutybaseurl{}*@)/v2/account/collections/fc03...eb6d/articles | jq
\end{lstlisting}

  Output of the example:
\begin{lstlisting}[language=JSON]
[ /* This example has been shortened. */
  {
    "id": null,
    "uuid": "8050f9cb-d0b0-4149-bd24-02f13c2410db",
    "doi": "10.4121/8050f9cb-d0b0-4149-bd24-02f13c2410db.v1",
    ...
  },
  {
    "id": 14309234,
    "uuid": "06431360-776c-45c6-bcca-ec898f2870ff",
    "doi": "10.4121/14309234.v1",
    ...
  }
]
\end{lstlisting}

\subsection{\t{/v2/account/collections/<collection-id>/articles} (\t{POST})}
\label{sec:v2-account-collection-articles}
  This API endpoint can be used to append datasets to the collection identified
  by \code{collection-id}.  The API endpoint accepts both the \code{id} property
  and the \code{uuid} property of a dataset as identifier.

\begin{lstlisting}[language=bash]
curl --verbose --request POST \
     --header "Authorization: token YOUR_TOKEN_HERE" \
     --header "Content-Type: application/json" \
     --header "Accept: application/json" \
     --data '{ "articles": ["8050...10db", 14309234 ]}' \
     (@*\djehutybaseurl{}*@)/v2/account/collections/fc03...eb6d/articles
\end{lstlisting}

  HTTP response of the example:
\begin{lstlisting}
HTTP/1.1 205 RESET CONTENT
\end{lstlisting}

\subsection{\t{/v2/account/collections/<collection-id>/articles} (\t{PUT})}

  In contrast to \refer{sec:v2-account-collection-articles}, this API endpoint
  can be used to \textbf{overwrite} the list of datasets associated with a
  collection.

\begin{lstlisting}[language=bash]
curl --verbose --request PUT \
     --header "Authorization: token YOUR_TOKEN_HERE" \
     --header "Content-Type: application/json" \
     --header "Accept: application/json" \
     --data '{ "articles": [ 14309234 ]}' \
     (@*\djehutybaseurl{}*@)/v2/account/collections/fc03...eb6d/articles
\end{lstlisting}

  HTTP response of the example:
\begin{lstlisting}
HTTP/1.1 205 RESET CONTENT
\end{lstlisting}

\subsection{\t{/v2/account/collections/<collection-id>/articles/<dataset-id>} (\t{DELETE})}

  This API endpoint can be used to delete a dataset's association with a collection.
  The \code{dataset-id} can be either the \code{uuid} or the \code{id} property.

  Example usage:
\begin{lstlisting}[language=bash]
curl --request DELETE \
     --header "Authorization: token YOUR_TOKEN_HERE" \
     (@*\djehutybaseurl{}*@)/v2/account/collections/fc03...eb6d/articles/8050...10db
\end{lstlisting}

  HTTP response of the example:
\begin{lstlisting}
HTTP/1.1 204 NO CONTENT
\end{lstlisting}

\subsection{\t{/v2/account/collections/<collection-id>/reserve\_doi} (\t{POST})}

  This API endpoint can be used to obtain the DOI before the collection is
  published and the DOI is activated.

  Example usage:
\begin{lstlisting}[language=bash]
curl --request POST \
     --header "Authorization: token YOUR_TOKEN_HERE" \
     (@*\djehutybaseurl{}*@)/v2/account/collections/fc03...eb6d/reserve_doi | jq
\end{lstlisting}

  Output of the example:
\begin{lstlisting}[language=JSON]
{
  "doi": "10.5074/fc03a4c3-cba4-4a88-a8a6-eb38924eeb6d"
}
\end{lstlisting}

\subsection{\t{/v2/account/collections/<collection-id>/funding} (\t{GET})}

  This API endpoint lists the funding of the collection identified by \code{collection-id}.

  Example usage:
\begin{lstlisting}[language=bash]
curl --header "Authorization: token YOUR_TOKEN_HERE" \
     (@*\djehutybaseurl{}*@)/v2/account/collections/fc03...eb6d/funding | jq
\end{lstlisting}

  Output of the example:
\begin{lstlisting}[language=JSON]
[
  {
    "id": null,
    "uuid": "6f605fe1-e87a-43f5-8b67-70ebe3f9b868",
    "title": "Example cases fund",
    "grant_code": "EXA-001",
    "funder_name": "Example",
    "is_user_defined": null,
    "url": "https://example.exa"
  }
]
\end{lstlisting}

\subsection{\t{/v2/account/collections/<collection-id>/funding} (\t{POST})}
\label{sec:api-v2-collections-funding-post}

  This API endpoint can be used to append funders to the collection identified
  by \code{collection-id}.

  Example usage:
\begin{lstlisting}[language=bash]
curl --verbose --request POST \
     --header "Authorization: token YOUR_TOKEN_HERE" \
     --header "Content-Type: application/json" \
     --data '{ "funders": [{ "title": "Example cases fund", \
                             "grant_code": "EXA-001", \
                             "funder_name": "Example", \
                             "url": "https://example.exa" }]}' \
     (@*\djehutybaseurl{}*@)/v2/account/collections/fc03a4c3-cba4-4a88-a8a6-eb38924eeb6d/funding
\end{lstlisting}

  HTTP response of the example:
\begin{lstlisting}
HTTP/1.1 205 RESET CONTENT
\end{lstlisting}

\subsection{\t{/v2/account/collections/<collection-id>/funding} (\t{PUT})}

  In contrast to \refer{sec:api-v2-collections-funding-post}, this API endpoint
  can be used to \textbf{overwrite} the list of funders of the collection
  identified by \code{collection-id}.

\begin{lstlisting}[language=bash]
curl --verbose --request PUT \
     --header "Authorization: token YOUR_TOKEN_HERE" \
     --header "Content-Type: application/json" \
     --data '{ "funders": [{ "title": "Example cases fund",
                             "grant_code": "EXA-001",
                             "funder_name": "Example",
                             "url": "https://example.exa" }]}' \
     (@*\djehutybaseurl{}*@)/v2/account/collections/fc03a4c3-cba4-4a88-a8a6-eb38924eeb6d/funding
\end{lstlisting}

  HTTP response of the example:
\begin{lstlisting}
HTTP/1.1 205 RESET CONTENT
\end{lstlisting}

\subsection{\t{/v2/account/collections/<collection-id>/funding/<funding-id>} (\t{DELETE})}

  This API endpoint can be used to delete an funder's association with a collection.

  Example usage:
\begin{lstlisting}[language=bash]
curl --request DELETE \
     --header "Authorization: token YOUR_TOKEN_HERE" \
     (@*\djehutybaseurl{}*@)/v2/account/collections/fc03...eb6d/funding/9b43...e6cd
\end{lstlisting}

  HTTP response of the example:
\begin{lstlisting}
HTTP/1.1 204 NO CONTENT
\end{lstlisting}

