# Overview
Build and integrate tools and applications to help members manage their bookmarks on Raindrop.io
This is the official documentation for Raindrop.io API. A reference to the functionality our public API provides with detailed description of each API endpoint, parameters, and examples.
Please note that you must [register your application](https://app.raindrop.io/settings/integrations) and authenticate with OAuth when making requests. Before doing so, be sure to read our [Terms & Guidelines](/terms) to learn how the API may be used.
### Format
API endpoints accept arguments either as url-encoded values for non-POST requests or as json-encoded objects encoded in POST request body with `Content-Type: application/json` header.
Where possible, the API strives to use appropriate HTTP verbs for each action.
| Verb | Description |
| ------ | ---------------------------------------------------------- |
| GET | Used for retrieving resources. |
| POST | Used for creating resources. |
| PUT | Used for updating resources, or performing custom actions. |
| DELETE | Used for deleting resources. |
This API relies on standard HTTP response codes to indicate operation result. The table below is a simple reference about the most used status codes:
| Status code | Description |
| ----------: | -------------------------------------------------------------------------------------------------------------------------------- |
| 200 | The request was processed successfully. |
| 204 | The request was processed successfully without any data to return. |
| 4xx | The request was processed with an error and should not be retried unmodified as they won’t be processed any different by an API. |
| 5xx | The request failed due to a server error, it’s safe to retry later. |
All `200 OK` responses have the `Content-type: application/json` and contain a JSON-encoded representation of one or more objects.
Payload of POST requests has to be JSON-encoded and accompanied with `Content-Type: application/json` header.
### Timestamps
All timestamps are returned in ISO 8601 format:
```bash
YYYY-MM-DDTHH:MM:SSZ
```
### Rate Limiting
For requests using OAuth, you can make up to 120 requests per minute per authenticated user.
The headers tell you everything you need to know about your current rate limit status:
| Header name | Description |
| ------------------- | --------------------------------------------------------------------------------- |
| X-RateLimit-Limit | The maximum number of requests that the consumer is permitted to make per minute. |
| RateLimit-Remaining | The number of requests remaining in the current rate limit window. |
| X-RateLimit-Reset | The time at which the current rate limit window resets in UTC epoch seconds. |
Once you go over the rate limit you will receive an error response:
```http
HTTP/1.1 429 Too Many Requests
Status: 429 Too Many Requests
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1392321600
```
### CORS
The API supports Cross Origin Resource Sharing (CORS) for AJAX requests. You can read the [CORS W3C recommendation](https://www.w3.org/TR/cors/), or [this intro](http://code.google.com/p/html5security/wiki/CrossOriginRequestSecurity) from the HTML 5 Security Guide.
Here’s a sample request sent from a browser hitting `http://example.com`:
```http
HTTP/1.1 200 OK
Access-Control-Allow-Origin: http://example.com
Access-Control-Expose-Headers: ETag, Content-Type, Accept, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
Access-Control-Allow-Credentials: true
```
# Terms & Guidelines
### How may I use the API?
#### DO
I encourage you to build applications that **extend** Raindrop.io to platforms beyond the web and offer services that Raindrop.io does not.
#### DON’T
Don’t build what I'm building. I invested a lot of time, money and hard work in Raindrop.io. I rely on Raindrop.io for income. As such, do not build an application, website, product, or business that attempts to harm, or replace Raindrop.io, website, or services.
In particular, do not use the API, or any Raindrop.io data, to build the following:
* A website that replicates or replaces raindrop.io
I'll do the best to communicate fair use of the Raindrop.io API in this space and others, but the onus is on you to contact me and inquire whether your use of the API is permitted.
### Commercial Use
You are free to use the Raindrop.io API for commercial use, provided that you abide by these terms and do not build an application or business that attempts to harm, compete with or replace Raindrop.io, our website, or our services.
### Be Gentle
Don’t overburden our servers. We’ve published some specifics with regard to rate limiting, but we reserve the right to determine abuse or excessive usage of the API and throttle or block any service accordingly. Attempts to circumvent rate limiting, such as leveraging multiple applications or generating bogus user accounts, are strictly prohibited.
### Termination
Raindrop.io can refuse API access at any time for any reason. This is not a card we hope to play often, but it’s impossible to anticipate every situation. We reserve the right to decline any request for API usage and block access to the API.
### Liability
Raindrop.io is not liable for any direct, indirect, incidental, special, consequential or exemplary damages arising from your use of the API. These include, but are not limited to, damages for loss of profits, goodwill, use, data or other intangible losses, resulting from your API usage or third-party products that access data via the API.
Your use of the Raindrop.io API is at your own discretion and risk, and you will be solely responsible for any damage that results its use, including, but not limited to, any damage to computer systems or loss of data incurred by you, your users, or your customers.
### Terms Can Change
Raindrop.io reserves the right to update and change these terms at any time without notice.
# Authentication
In order to make authorized calls to Raindrop.io API, you must do the following:
* [x] [Register your application](https://app.raindrop.io/settings/integrations)
* [x] [Obtain access token](/v1/authentication/token)
# Obtain access token
External applications could obtain a user authorized API token via the OAuth2 protocol. Before getting started, developers need to create their applications in [App Management Console](https://app.raindrop.io/settings/integrations) and configure a valid OAuth redirect URL. A registered Raindrop.io application is assigned a unique `Client ID` and `Client Secret` which are needed for the OAuth2 flow.
This procedure is comprised of several steps, which will be described below.
{% hint style="info" %}
If you just want to test your application, or do not plan to access any data except yours account you don't need to make all of those steps.
Just go to [App Management Console](https://app.raindrop.io/settings/integrations) and open your application settings. Copy **Test token** and use it as described in [**Make authorized calls**](/v1/authentication/calls)**.**
{% endhint %}
## Step 1: The authorization request
`GET` `https://raindrop.io/oauth/authorize`
Direct the user to our authorization URL with specified request parameters.\
— If the user is not logged in, they will be asked to log in\
— The user will be asked if he would like to grant your application access to his Raindrop.io data
#### Query Parameters
| Name | Type | Description |
| -------------- | ------ | --------------------------------------------------------------- |
| redirect\_uri | string | Redirect URL configured in your application setting |
| client\_id | string | The unique Client ID of the Raindrop.io app that you registered |
| response\_type | string | Should be always `code` |
{% tabs %}
{% tab title="307 Check details in Step 2" %}
```
```
{% endtab %}
{% endtabs %}
Here example CURL request:
```bash
curl "https://api.raindrop.io/v1/oauth/authorize?response_type=code&client_id=5e1c382cf6f48c0211359083&redirect_uri=https:%2F%2Foauthdebugger.com%2Fdebug"
```
## Step 2: The redirection to your application site
When the user grants your authorization request, the user will be redirected to the redirect URL configured in your application setting. The redirect request will come with query parameter attached: `code` .
The `code` parameter contains the authorization code that you will use to exchange for an access token.
In case of error redirect request will come with `error` query parameter:
| Error | Description |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------- |
| access\_denied | When the user denies your authorization request |
| invalid\_application\_status | When your application exceeds the maximum token limit or when your application is being suspended due to abuse |
## Step 3: The token exchange
`POST` `https://raindrop.io/oauth/access_token`
Once you have the authorization `code`, you can exchange it for the `access_token` by doing a `POST` request with all required body parameters as JSON:
#### Headers
| Name | Type | Description |
| ------------ | ------ | ---------------- |
| Content-Type | string | application/json |
#### Request Body
| Name | Type | Description |
| -------------- | ------ | --------------------------------------------------------------- |
| grant\_type | string | **authorization\_code** |
| code | string | Code that you received in step 2 |
| client\_id | string | The unique Client ID of the Raindrop.io app that you registered |
| client\_secret | string | Client secret |
| redirect\_uri | string | Same `redirect_uri` from step 1 |
{% tabs %}
{% tab title="200 " %}
```javascript
{
"access_token": "ae261404-11r4-47c0-bce3-e18a423da828",
"refresh_token": "c8080368-fad2-4a3f-b2c9-71d3z85011vb",
"expires": 1209599768, //in miliseconds, deprecated
"expires_in": 1209599, //in seconds, use this instead!!!
"token_type": "Bearer"
}
```
{% endtab %}
{% tab title="400 Occurs when code parameter is invalid" %}
```javascript
{"error": "bad_authorization_code"}
```
{% endtab %}
{% endtabs %}
Here an example CURL request:
```bash
curl -X "POST" "https://raindrop.io/oauth/access_token" \
-H 'Content-Type: application/json' \
-d $'{
"code": "c8983220-1cca-4626-a19d-801a6aae003c",
"client_id": "5e1c589cf6f48c0211311383",
"redirect_uri": "https://oauthdebugger.com/debug",
"client_secret": "c3363988-9d27-4bc6-a0ae-d126ce78dc09",
"grant_type": "authorization_code"
}'
```
## ♻️ The access token refresh
`POST` `https://raindrop.io/oauth/access_token`
For security reasons access tokens (except "test tokens") will **expire after two weeks**. In this case you should request the new one, by calling `POST` request with body parameters (JSON):
#### Headers
| Name | Type | Description |
| ------------ | ------ | ---------------- |
| Content-Type | string | application/json |
#### Request Body
| Name | Type | Description |
| -------------- | ------ | ---------------------------------------------------- |
| client\_id | string | The unique Client ID of your app that you registered |
| client\_secret | string | Client secret of your app |
| grant\_type | string | **refresh\_token** |
| refresh\_token | string | Refresh token that you get in step 3 |
{% tabs %}
{% tab title="200 " %}
```javascript
{
"access_token": "ae261404-18r4-47c0-bce3-e18a423da898",
"refresh_token": "c8080368-fad2-4a9f-b2c9-73d3z850111b",
"expires": 1209599768, //in miliseconds, deprecated
"expires_in": 1209599, //in seconds, use this instead!!!
"token_type": "Bearer"
}
```
{% endtab %}
{% endtabs %}
# Make authorized calls
Build something great
Once you have received an **access\_token**, include it in all API calls in [authorization header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization) with value `Bearer access_token`
```http
Authorization: Bearer ae261404-11r4-47c0-bce3-e18a423da828
```
# Collections
### Fields
| Field | Type | Description |
| ---------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| \_id | `Integer` | The id of the collection. |
| access | `Object` | |
| access.level | `Integer` |
read only access (equal to public=true)
collaborator with read only access
collaborator with write only access
owner
|
| access.draggable | `Boolean` | Does it possible to change parent of this collection? |
| collaborators | `Object` |
When this object is present, means that collections is shared. Content of this object is private and not very useful. All sharing API methods described here
|
| color | `String` | Primary color of collection cover as `HEX` |
| count | `Integer` | Count of raindrops in collection |
| cover | `Array` |
Collection cover URL. This array always have one item due to legacy reasons
|
| created | `String` | When collection is created |
| expanded | `Boolean` | Whether the collection’s sub-collections are expanded |
| lastUpdate | `String` | When collection is updated |
| parent | `Object` | |
| parent.$id | `Integer` | The id of the parent collection. Not specified for root collections |
| public | `Boolean` | Collection and raindrops that it contains will be accessible without authentication by public link |
| sort | `Integer` | The order of collection (descending). Defines the position of the collection among all the collections with the same `parent.$id` |
| title | `String` | Name of the collection |
| user | `Object` | |
| user.$id | `Integer` | Owner ID |
| view | `String` |
View style of collection, can be:
list (default)
simple
grid
masonry Pinterest like grid
|
{% hint style="warning" %}
Our API response could contain **other fields**, not described above. It's **unsafe to use** them in your integration! They could be removed or renamed at any time.
{% endhint %}
### System collections
Every user have several system non-removable collections. They are not contained in any API responses.
| \_id | Description |
| ------- | ------------------------- |
| **-1** | "**Unsorted**" collection |
| **-99** | "**Trash**" collection |
# Collection methods
## Get root collections
`GET` `https://api.raindrop.io/rest/v1/collections`
Returns JSON-encoded array containing all root collections
{% tabs %}
{% tab title="200 " %}
```javascript
{
"result": true,
"items": [
{
"_id": 8492393,
"access": {
"level": 4,
"draggable": true
},
"collaborators": {
"$id": "5dc1759a0e123be5f2654b6f"
},
"color": "#0c797d",
"count": 16,
"cover": [
"https://up.raindrop.io/collection/thumbs/849/239/3/333ce18769311113836cf93a223a14a3.png"
],
"created": "2019-10-09T11:49:53.518Z",
"expanded": false,
"lastUpdate": "2019-11-27T17:51:19.085Z",
"public": false,
"sort": 8492393,
"title": "Development",
"user": {
"$id": 32
},
"view": "list"
}
]
}
```
{% endtab %}
{% endtabs %}
## Get child collections
`GET` `https://api.raindrop.io/rest/v1/collections/childrens`
Returns JSON-encoded array containing all nested collections (that have positive `parent.$id`)
{% tabs %}
{% tab title="200 " %}
```javascript
{
"result": true,
"items": [
{
"_id": 8492393,
"access": {
"level": 4,
"draggable": true
},
"collaborators": {
"$id": "5dc1759a0e123be5f2654b6f"
},
"color": "#0c797d",
"count": 16,
"cover": [
"https://up.raindrop.io/collection/thumbs/849/239/3/333ce18769311113836cf93a223a14a3.png"
],
"created": "2019-10-09T11:49:53.518Z",
"expanded": false,
"lastUpdate": "2019-11-27T17:51:19.085Z",
"parent": { "$id": 1111 },
"public": false,
"sort": 8492393,
"title": "Development",
"user": {
"$id": 32
},
"view": "list"
}
]
}
```
{% endtab %}
{% endtabs %}
## Get collection
`GET` `https://api.raindrop.io/rest/v1/collection/{id}`
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ------------- |
| id | number | Collection ID |
{% tabs %}
{% tab title="200 " %}
```javascript
{
"result": true,
"item": {
"_id": 8492393,
"access": {
"for": 32,
"level": 4,
"root": true,
"draggable": true
},
"author": true,
"collaborators": {
"$id": "5dc1759a0e123be5f2654b6f"
},
"color": "#0c797d",
"count": 16,
"cover": [
"https://up.raindrop.io/collection/thumbs/849/239/3/333ce18769311113836cf93a223a14a3.png"
],
"created": "2019-10-09T11:49:53.518Z",
"expanded": false,
"lastUpdate": "2019-11-27T17:51:19.085Z",
"public": false,
"sort": 8492393,
"title": "Development",
"user": {
"$id": 32
},
"view": "list"
}
}
```
{% endtab %}
{% endtabs %}
## Create collection
`POST` `https://api.raindrop.io/rest/v1/collection`
Create a new collection
#### Request Body
| Name | Type | Description |
| ---------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- |
| view | string | More details in "Fields" |
| title | string | Name of the collection |
| sort | number | The order of collection (descending). Defines the position of the collection among all the collections with the same `parent.$id` |
| public | boolean | Collection and raindrops that it contains will be accessible without authentication? |
| parent.$id | integer | The ID of parent collection. Empty for root collections |
| cover | array | Collection cover url |
{% tabs %}
{% tab title="200 " %}
```javascript
{
"result": true,
"item": {
...
}
}
```
{% endtab %}
{% tab title="400 Incorrect 'view' field value" %}
```javascript
{
"result": false,
"error": "view",
"errorMessage": "Collection validation failed: view: `bla` is not a valid enum value for path `view`."
}
```
{% endtab %}
{% endtabs %}
## Update collection
`PUT` `https://api.raindrop.io/rest/v1/collection/{id}`
Update an existing collection
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ---------------------- |
| id | number | Existing collection id |
#### Request Body
| Name | Type | Description |
| ---------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- |
| expanded | boolean | Whether the collection\`s sub-collections are expanded |
| view | string | More details in "Fields" |
| title | string | Name of the collection |
| sort | number | The order of collection (descending). Defines the position of the collection among all the collections with the same `parent.$id` |
| public | boolean | Collection and raindrops that it contains will be accessible without authentication? |
| parent.$id | integer | The ID of parent collection. Empty for root collections |
| cover | array | Collection cover url |
{% tabs %}
{% tab title="200 " %}
```javascript
{
"result": true,
"item": {
...
}
}
```
{% endtab %}
{% endtabs %}
## Upload cover
`PUT` `https://api.raindrop.io/rest/v1/collection/{id}/cover`
It's possible to upload cover from desktop. PNG, GIF and JPEG supported
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ---------------------- |
| id | string | Existing collection ID |
#### Headers
| Name | Type | Description |
| ------------ | ------ | ------------------- |
| Content-Type | string | multipart/form-data |
#### Request Body
| Name | Type | Description |
| ----- | ------ | ----------- |
| cover | object | File |
{% tabs %}
{% tab title="200 " %}
```javascript
{
"result": true,
"item": {
...
}
}
```
{% endtab %}
{% endtabs %}
## Remove collection
`DELETE` `https://api.raindrop.io/rest/v1/collection/{id}`
Remove an existing collection and all its descendants.\
Raindrops will be moved to "Trash" collection
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ---------------------- |
| id | number | Existing collection ID |
{% tabs %}
{% tab title="200 " %}
```javascript
{
"result": true
}
```
{% endtab %}
{% endtabs %}
## Remove multiple collections
`DELETE` `https://api.raindrop.io/rest/v1/collections`
Remove multiple collections at once.\
Nested collections are ignored (include ID's in `ids` array to remove them)
#### Request Body
| Name | Type | Description |
| ---- | ----- | ---------------------- |
| ids | array | Array of collection ID |
{% tabs %}
{% tab title="200 " %}
```
```
{% endtab %}
{% endtabs %}
## Reorder all collections
`PUT` `https://api.raindrop.io/rest/v1/collections`
Updates order of all collections
#### Request Body
| Name | Type | Description |
| ---- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| sort | string |
Change order of all collections. Possible values: "title" - sort alphabetically ascending "-title" - sort alphabetically descending "-count" - sort by raindrops count descending
|
{% tabs %}
{% tab title="200 " %}
```javascript
{
"result": true
}
```
{% endtab %}
{% endtabs %}
## Merge collections
`PUT` `https://api.raindrop.io/rest/v1/collections/merge`
Merge multiple collections
#### Request Body
| Name | Type | Description |
| ---- | ------ | ---------------------------------------------------------- |
| to | number | Collection ID where listed collection `ids` will be merged |
| ids | array | Collection ID's |
{% tabs %}
{% tab title="200 " %}
```
```
{% endtab %}
{% endtabs %}
## Remove all empty collections
`PUT` `https://api.raindrop.io/rest/v1/collections/clean`
{% tabs %}
{% tab title="200 " %}
```javascript
{
"result": true,
"count": 3
}
```
{% endtab %}
{% endtabs %}
## Empty Trash
`DELETE` `https://api.raindrop.io/rest/v1/collection/-99`
{% tabs %}
{% tab title="200 " %}
```javascript
{
"result": true
}
```
{% endtab %}
{% endtabs %}
## Get system collections count
`GET` `https://api.raindrop.io/rest/v1/user/stats`
{% tabs %}
{% tab title="200 " %}
```javascript
{
"items": [
{
"_id": 0,
"count": 1570
},
{
"_id": -1,
"count": 34
},
{
"_id": -99,
"count": 543
}
],
"meta": {
"pro": true,
"_id": 32,
"changedBookmarksDate": "2020-02-11T11:23:43.143Z",
"duplicates": {
"count": 3
},
"broken": {
"count": 31
}
},
"result": true
}
```
{% endtab %}
{% endtabs %}
# Nested structure
### Overview
If you look into Raindrop UI you will notice a sidebar in left corner, where collections are located. Collections itself divided by groups. Groups useful to create separate sets of collections, for example "Home", "Work", etc.
`Groups` array is a single place where user **root** collection list and order is persisted. Why just not to save order position inside collection item itself? Because collections can be shared and they group and order can vary from user to user.
So to fully recreate sidebar like in our app you need to make 3 separate API calls (sorry, will be improved in future API updates):
#### 1. [Get user object](/v1/user/authenticated#get-user)
It contains `groups` array with exact collection ID's. Typically this array looks like this:
```javascript
{
"groups": [
{
"title": "Home",
"hidden": false,
"sort": 0,
"collections": [
8364483,
8364403,
66
]
},
{
"title": "Work",
"hidden": false,
"sort": 1,
"collections": [
8492393
]
}
]
}
```
{% hint style="warning" %}
Collection ID's listed below is just first level of collections structure! To create full tree of nested collections you need to get child items separately.
{% endhint %}
To get name, count, icon and other info about collections, make those two separate calls:
#### 2. [Get root collections](/v1/collections/methods#get-root-collections)
Sort order of root collections persisted in `groups[].collections` array
#### 3. [Get child collections](/v1/collections/methods#get-child-collections)
Sort order of child collections persisted in collection itself in `sort` field
# Sharing
Collection can be shared with other users, which are then called collaborators, and this section describes the different commands that are related to sharing.
### Collaborators
Every user who shares at least one collection with another user, has a collaborators record in the API response. The record contains a restricted subset of user-specific fields.
| Field | Description |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| \_id | User ID of the collaborator |
| email |
Email of the collaborator
Empty when authorized user have read-only access
|
| email\_MD5 | MD5 hash of collaborator email. Useful for using with Gravatar for example |
| fullName | Full name of the collaborator |
| role |
Access level:
member have write access and can invite more users
viewer read-only access
|
## Share collection
`POST` `https://api.raindrop.io/rest/v1/collection/{id}/sharing`
Share collection with another user(s). As result invitation(s) will be send to specified email(s) with link to join collection.
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ---------------------- |
| id | number | Existing collection ID |
#### Request Body
| Name | Type | Description |
| ------ | ------ | --------------------------------------------------------------------------------------------------------------------- |
| role | string |
Access level. Possible values: member viewer
|
| emails | array |
The user email(s) with whom to share the project. Maximum 10
|
{% tabs %}
{% tab title="200 " %}
```javascript
{
"result": true,
"emails": [
"some@user.com",
"other@user.com"
]
}
```
{% endtab %}
{% tab title="400 " %}
```javascript
//'emails' array is empty
{
"result": false,
"errorMessage": "no emails"
}
//'emails' array larger than 10
{
"result": false,
"errorMessage": "you cant send more than 10 invites at once"
}
```
{% endtab %}
{% tab title="403 " %}
```javascript
//When user have more than 100 pending invitations:
{
"result": false,
"errorMessage": "you have too many pending invitations, you will be banned if you continue send more"
}
//User doesn't have enought permissions to invite more people
{
"result": false,
"errorMessage": "you dont have permissions to invite more people"
}
```
{% endtab %}
{% endtabs %}
## Get collaborators list of collection
`GET` `https://api.raindrop.io/rest/v1/collection/{id}/sharing`
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ---------------------- |
| id | number | Existing collection ID |
{% tabs %}
{% tab title="200 " %}
```javascript
{
"items": [
{
"_id": 373381,
"email": "some@mail.com",
"email_MD5": "e12bda18ca265d3f3e30d247adea2549",
"fullName": "Jakie Future",
"registered": "2019-08-18T17:01:43.664Z",
"role": "viewer"
}
],
"result": true
}
```
{% endtab %}
{% endtabs %}
## Unshare or leave collection
`DELETE` `https://api.raindrop.io/rest/v1/collection/{id}/sharing`
There two possible results of calling this method, depends on who authenticated user is:\
\- **Owner**: collection will be unshared and all collaborators will be removed\
\- **Member or viewer**: authenticated user will be removed from collaborators list
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ---------------------- |
| id | number | Existing collection ID |
{% tabs %}
{% tab title="200 " %}
```javascript
{
"result": true
}
```
{% endtab %}
{% endtabs %}
## Change access level of collaborator
`PUT` `https://api.raindrop.io/rest/v1/collection/{id}/sharing/{userId}`
#### Path Parameters
| Name | Type | Description |
| ------ | ------ | ----------------------- |
| userId | number | User ID of collaborator |
| id | number | Existing collection ID |
#### Request Body
| Name | Type | Description |
| ---- | ------ | ---------------------------- |
| role | string | **`member`** or **`viewer`** |
{% tabs %}
{% tab title="200 " %}
```javascript
{
"result": true
}
```
{% endtab %}
{% endtabs %}
## Delete a collaborator
`DELETE` `https://api.raindrop.io/rest/v1/collection/{id}/sharing/{userId}`
Remove an user from shared collection
#### Path Parameters
| Name | Type | Description |
| ------ | ------ | ----------------------- |
| userId | number | User ID of collaborator |
| id | number | Existing collection ID |
{% tabs %}
{% tab title="200 " %}
```javascript
{
"result": true
}
```
{% endtab %}
{% endtabs %}
## Accept an invitation
`POST` `https://api.raindrop.io/rest/v1/collection/{id}/join`
Accept an invitation to join a shared collection
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ---------------------- |
| id | number | Existing collection ID |
#### Request Body
| Name | Type | Description |
| ----- | ------ | ----------------------- |
| token | string | Secret token from email |
{% tabs %}
{% tab title="200 " %}
```javascript
{
"result": true,
"role": "member"
}
```
{% endtab %}
{% tab title="403 " %}
```javascript
//Incorrect token
{
"result": false,
"error": "CollaboratorsIncorrectToken",
"errorMessage": "Incorrect or expired token"
}
//Collection no more exists
{
"result": false,
"error": "CollaboratorsNoCollection",
"errorMessage": "Shared collection not found or removed"
}
{
"result": false,
"error": "CollaboratorsAlready",
"errorMessage": "You already owner of this collection"
}
```
{% endtab %}
{% endtabs %}
# Covers/icons
In your app you could easily make icon/cover selector from more than 10 000 icons
## Search for cover
`GET` `https://api.raindrop.io/rest/v1/collections/covers/{text}`
Search for specific cover (icon)
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | --------------------- |
| text | string | For example "pokemon" |
{% tabs %}
{% tab title="200 " %}
```javascript
{
"items": [
{
"title": "Icons8",
"icons": [
{
"png": "https://rd-icons-icons8.gumlet.com/color/5x/mystic-pokemon.png?fill-color=transparent"
}
]
},
{
"title": "Iconfinder",
"icons": [
{
"png": "https://cdn4.iconfinder.com/data/icons/pokemon-go/512/Pokemon_Go-01-128.png",
"svg": "https://api.iconfinder.com/v2/icons/1320040/formats/svg/1760420/download"
}
]
}
],
"result": true
}
```
{% endtab %}
{% endtabs %}
## Featured covers
`GET` `https://api.raindrop.io/rest/v1/collections/covers`
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ----------- |
| | string | |
{% tabs %}
{% tab title="200 " %}
```javascript
{
"items": [
{
"title": "Colors circle",
"icons": [
{
"png": "https://up.raindrop.io/collection/templates/colors/ios1.png"
}
]
},
{
"title": "Hockey",
"icons": [
{
"png": "https://up.raindrop.io/collection/templates/hockey-18/12i.png"
}
]
}
]
}
```
{% endtab %}
{% endtabs %}
# Raindrops
We call bookmarks (or items) as "raindrops"
### Main fields
| Field | Type | Description |
| -------------- | --------------- | --------------------------------------------------------------------------------- |
| \_id | `Integer` | Unique identifier |
| collection | `Object` | |
| collection.$id | `Integer` | Collection that the raindrop resides in |
| cover | `String` | Raindrop cover URL |
| created | `String` | Creation date |
| domain | `String` |
Hostname of a link. Files always have raindrop.io hostname
|
| excerpt | `String` | Description; max length: 10000 |
| note | `String` | Note; max length: 10000 |
| lastUpdate | `String` | Update date |
| link | `String` | URL |
| media | `Array