# VSELF API for collections

#### Getting started

VSELF API provides all the functionality of the NFT collection toolkit for NEAR-compatible version. It consists of RESTful view requests, which retrieve information from the NEAR contract, and call requests, which can make some changes or mint tokens. 

Most call requests are used for collection management. These requests are almost always available for the collection owner only. *<mark style="background-color:purple;">The only call request available for everyone is the claim reward request.</mark>* All other call requests will fail in case of a non-owner call. The view requests are available to call for everyone. The view requests are free, the call requests are paid. Learn more about payment management [here](https://vself-project.gitbook.io/vself-project-documentation/nft-collection-toolkit/payment). &#x20;

API requests are done over HTTPS. The input and output formats for most API requests are JSON. The API is hosted [here](https://vself-prod.web.app/api/). All the requests require the developer API key as one of the parameters, which is managed using [Pagoda Console](https://console.pagoda.co/apis?tab=enhancedApi#/paths/NFT-contract_account_id---token_id/get). The requests with invalid API key will fail. There is a limitation for non-view requests the same user is able to make per minute.

In the next step, we will implement VSELF DID as a developer API key and sign all requests using the JWS scheme.

#### Error codes

<mark style="color:red;">10</mark> - no response&#x20;

<mark style="color:red;">30</mark> - wrong input &#x20;

<mark style="color:red;">31</mark> - invalid NEAR ID

<mark style="color:red;">32</mark> - collection is not found&#x20;

<mark style="color:red;">33</mark> - reward isn't found

<mark style="color:red;">60</mark> - collection is unavailable&#x20;

<mark style="color:red;">61</mark> - collection wasn't started

<mark style="color:red;">62</mark> - collection was expired&#x20;

<mark style="color:red;">63</mark> - reward was claimed

<mark style="color:red;">70</mark> - insufficient funds of deposit&#x20;

<mark style="color:red;">80</mark> - no access rights&#x20;

#### Endpoints

* <mark style="background-color:purple;">Start collection:</mark> saves collection data\
  Input: name, description, start date, end date, list of rewards, collection settings\
  Each reward consists of: name, description, link to the source image, reward code, list of hashtags\
  [Collection settings](https://vself-project.gitbook.io/vself-project-documentation/nft-collection-toolkit/collection-settings) consists of the following settings: sign in requirement, reward transfer-ability, reward limitation, collection business status, collection publicity\
  Output: collection id\
  Catch: 30, 70
* <mark style="background-color:purple;">Stop collection:</mark> stops collection immediately \
  Input: collection id\
  Output: -\
  Catch: 30, 32, 60, 61, 62, 70, 80\ <mark style="background-color:purple;">Modify collection date:</mark> modify the time period of the collection availability \
  Input: collection id, new start date, new end date\
  Output: -\
  Catch: 30, 32, 60, 70, 80
* <mark style="background-color:purple;">Add collection rewards:</mark> adds new reward to the existing collection\
  Input: collection id, list of new rewards\
  Each reward consists of: name, description, link to the source image, reward code, list of hashtags\
  Output: -\
  Catch: 30, 32, 60, 62, 70, 80
* <mark style="background-color:purple;">Remove collection rewards:</mark> removes chosen rewards from the existing collection\
  Input: collection id, list of new rewards\
  Each reward consists of: name, description, link to the source image, reward code, list of hashtags\
  Output: -\
  Catch: 30, 32, 60, 62, 70, 80
* <mark style="background-color:purple;">Modify collection settings:</mark> manages collection settings, new settings won't be implemented for the achieved rewards  \
  Input: collection id, new settings\
  Output: -\
  Catch: 30, 32, 60, 62, 70, 80
* <mark style="background-color:purple;">Claim reward:</mark> mints reward for user\
  Input: NEAR id, collection id, reward code\
  Output: reward\
  Catch: 30, 31, 32, 33, 60, 61, 62, 63, 70, 80
* <mark style="background-color:purple;">Send reward:</mark> mints reward for all users from list or community\
  Input: list of the NEAR ids (community id), reward code\
  Output: 30, 31, 32, 33, 60, 61, 62, 63, 70, 80
* <mark style="background-color:purple;">Set up achievement:</mark> add private reward and set up requirements for achieving it  \
  Input: activity config (learn more [here](https://vself-project.gitbook.io/vself-project-documentation/provenance-traction#achievements-inside-the-single-collection)), reward\
  Output: 30, 32, 60, 62, 70, 80
* <mark style="background-color:purple;">Ongoing collections (View):</mark> returns list of available collections \
  Input: -\
  Output: list of collection ids\
  Catch: -
* <mark style="background-color:purple;">Collection data (View):</mark> returns full information about the collection\
  Input: collection id\
  Output: collection\
  Catch: 30, 32
* <mark style="background-color:purple;">Collection reward data (View):</mark> returns full information about the reward\
  Input: collection id, reward code\
  Output: reward\
  Catch: 30, 32, 33
* <mark style="background-color:purple;">Owner collections (View):</mark> returns all collections created by chosen user\
  Input: NEAR id\
  Output: list of collection ids\
  Catch: 30, 31
* <mark style="background-color:purple;">Collection owner (View):</mark> returns owner of the chosen collection\
  Input: collection id\
  Output: NEAR id\
  Catch: 30, 32
* <mark style="background-color:purple;">Collection general stats (View):</mark> returns all the claim logs from collection \
  Input: collection id\
  Output: list of check ins \
  Each check in consists of: NEAR id, reward code, timestamp (UTC)\
  Catch: 30, 32
* <mark style="background-color:purple;">Collection participants (View):</mark> returns all the unique users claimed rewards\
  Input: collection id\
  Output: list of NEAR ids\
  Catch: 30, 32
* <mark style="background-color:purple;">Collection activity logs (View):</mark>  returns activity of user \
  Input: collection id, NEAR id\
  Output: [activity config ](https://vself-project.gitbook.io/vself-project-documentation/provenance-traction#achievements-inside-the-single-collection)\
  Catch: 30, 31, 32
* <mark style="background-color:purple;">Collection active users (View):</mark> returns users with activity satisfies activity config\
  Input:[ activity config](https://vself-project.gitbook.io/vself-project-documentation/provenance-traction#achievements-inside-the-single-collection), collection id\
  Output: list of NEAR ids\
  Catch: 30, 32


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://vself-project.gitbook.io/vself-project-documentation/nft-collection-toolkit/vself-api-for-collections.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.