Items

API ▸ Endpoints

Overview

Items belong to a collection, can optionally belong to another item (a stack), and have many comments and reactions.

List items
Create an item
Get an item
List item tags
Update an item
Update multiple items
Delete an item
Copy items

List items

Endpoint

GET https://api.dropmark.com/v1/items

Query String Params

Name	Type	Desc
`collection_id`	`Integer`	Filter items to this collection
`owned`	`Boolean`	Filter items to those owned by current user
`owner_id`	`Integer`	Filter items to those owned by this user
`parent_id`	`Integer`	ID of parent item
`ll`	`String`	Filter by latitude/longitude (`lat,long`)
`radius`	`Number`	Maximum distance (in meters) from `ll`
`page`	`Integer`	Current page
`per_page`	`Integer`	Number of items to return
`q`	`String`	Filter items to those matching this search query
`tags`	`Array`	Filter items to those with these tags
`type`	`String`	Filter items to this type: `image`, `video`, `audio`, `link`, `text`, `other`, `stack`
`not_type`	`String`	Don’t include items of this type: `image`, `video`, `audio`, `link`, `text`, `other`, `stack`

Response

Status: 200 OK
X-Total-Count: 53

[
  {
    "id": 100,
    "collection_id": 1337,
    "user_id": 1,
    "parent_id": null,
    "name": "Example item",
    "description": null,
    "content": "Hello world",
    "link": "",
    "preview": null,
    "thumbnail": null,
    "shareable": null,
    "size": 0,
    "sort": 5,
    "type": "text",
    "mime": "text/plain",
    "latitude": null,
    "longitude": null,
    "created_at": "2016-08-16T15:35:16Z",
    "updated_at": "2016-08-16T19:35:29Z",
    "deleted_at": null,
    "reactions_total_count": 0,
    "user_name": "Jane Doe",
    "user_email": "jane@example.com",
    "user_plan": "pro",
    "url": "http://demo.dropmark.com/1337/100",
    "short_url": "http://dpmk.com/i/QMSMSFwznJ",
    "thumbnails": {},
    "reactions": [],
    "is_url": false,
    "comments": [],
    "tags": [],
    "metadata": []
  }
]

Create an item

Endpoint

POST https://api.dropmark.com/v1/collections/:collection_id/items

Input

Name	Type	Desc
`type`	`String`	Item type: `image`, `video`, `audio`, `link`, `text`, `other`, `stack` (required)
`content`	`String`	Content varies based on the item’s `type`. Can be a URL, plain text, or file (required unless `type` is `stack`, see examples below)
`description`	`String`	Item description
`items`	`Array`	ID’s of stack children
`latitude`	`Number`	Latitude of item
`longitude`	`Number`	Longitude of item
`link`	`String`	Original source URL
`metadata`	`Object`	Metadata keys/values
`name`	`String`	Item title
`parent_id`	`Integer`	ID of parent item
`prevent_duplicate`	`Boolean`	Set to `true` to check for an identical link item
`shareable`	`Boolean`	Set to `true` to make the item publicly visible, even if its collection is private
`sort`	`Integer`	Position of this item within the collection
`tags`*	`Array`	Item tags
`thumbnail`	`String`	Item thumbnail URL or Base64 image

* Available for accounts on a paid plan only

Examples

Dropmark supports a range of item types and these item types dictate what you’ll want to send in as the value for content. Below are some examples of different items and their corresponding content value.

Link example:

{
  "content": "http://example.com"
}

File example:

{
  "content": File()
}

Stack example:

{
  "name": "Example stack"
}

Text example:

{
  "name": "Example item",
  "content": "Hello world"
}

Response

Status: 201 Created

{
  "id": 100,
  "collection_id": 1337,
  "user_id": 1,
  "parent_id": null,
  "name": "Example item",
  "description": null,
  "content": "Hello world",
  "link": "",
  "preview": null,
  "thumbnail": null,
  "shareable": null,
  "size": 0,
  "sort": 5,
  "type": "text",
  "mime": "text/plain",
  "latitude": null,
  "longitude": null,
  "created_at": "2016-08-16T15:35:16Z",
  "updated_at": "2016-08-16T19:35:29Z",
  "deleted_at": null,
  "reactions_total_count": 0,
  "user_name": "Jane Doe",
  "user_email": "jane@example.com",
  "user_plan": "pro",
  "url": "http://demo.dropmark.com/1337/100",
  "short_url": "http://dpmk.com/i/QMSMSFwznJ",
  "thumbnails": {},
  "reactions": [],
  "is_url": false,
  "comments": [],
  "tags": [],
  "metadata": []
}

Get an item

Endpoint

GET https://api.dropmark.com/v1/items/:item_id

Query String Params

Name	Type	Desc
`include`	`Array`	Additional objects available to include in response: `items`, `parent`, `siblings`, `stack_items`
`items_page`	`Integer`	Current children items page
`items_per_page`	`Integer`	Number of children items to return
`items_type`	`String`	Filter returned children items to this type: `image`, `video`, `audio`, `link`, `text`, `other`, `stack`
`items_not_type`	`String`	Don’t include children items of this type: `image`, `video`, `audio`, `link`, `text`, `other`, `stack`

Response

Status: 200 OK

[
  {
    "id": 100,
    "collection_id": 1337,
    "user_id": 1,
    "parent_id": null,
    "name": "Example item",
    "description": null,
    "content": "Hello world",
    "link": "",
    "preview": null,
    "thumbnail": null,
    "shareable": null,
    "size": 0,
    "sort": 5,
    "type": "text",
    "mime": "text/plain",
    "latitude": null,
    "longitude": null,
    "created_at": "2016-08-16T15:35:16Z",
    "updated_at": "2016-08-16T19:35:29Z",
    "deleted_at": null,
    "reactions_total_count": 0,
    "user_name": "Jane Doe",
    "user_email": "jane@example.com",
    "user_plan": "pro",
    "url": "http://demo.dropmark.com/1337/100",
    "short_url": "http://dpmk.com/i/QMSMSFwznJ",
    "thumbnails": {},
    "reactions": [],
    "is_url": false,
    "comments": [],
    "tags": [],
    "metadata": []
  }
]

List item tags

Endpoint

GET https://api.dropmark.com/v1/items/:item_id/tags

Response

Status: 200 OK

[
  {
    "id": 1,
    "name": "clever"
  }
]

Update an item

Endpoint

PUT https://api.dropmark.com/v1/items/:item_id

Input

Name	Type	Desc
`type`	`String`	Item type: `image`, `video`, `audio`, `link`, `text`, `other`, `stack`
`content`	`String`	Content varies based on the item’s `type`. Can be a URL or plain text
`description`	`String`	Item description
`items`	`Array`	ID’s of stack children
`latitude`	`Number`	Latitude of item
`longitude`	`Number`	Longitude of item
`link`	`String`	Original source URL
`metadata`	`Object`	Metadata keys/values
`name`	`String`	Item title
`parent_id`	`Integer`	ID of parent item
`prevent_duplicate`	`Boolean`	Set to `true` to check for an identical link item
`shareable`	`Boolean`	Set to `true` to make the item publicly visible, even if its collection is private
`sort`	`Integer`	Position of this item within the collection
`tags`*	`Array`	Item tags
`thumbnail`	`String`	Item thumbnail URL or Base64 image

* Available for accounts on a paid plan only

Example

{
  "name": "Example item",
  "content": "Hello world"
}

Response

Status: 200 OK

{
  "id": 100,
  "collection_id": 1337,
  "user_id": 1,
  "parent_id": null,
  "name": "Example item",
  "description": null,
  "content": "Hello world",
  "link": "",
  "preview": null,
  "thumbnail": null,
  "shareable": null,
  "size": 0,
  "sort": 5,
  "type": "text",
  "mime": "text/plain",
  "latitude": null,
  "longitude": null,
  "created_at": "2016-08-16T15:35:16Z",
  "updated_at": "2016-08-16T19:35:29Z",
  "deleted_at": null,
  "reactions_total_count": 0,
  "user_name": "Jane Doe",
  "user_email": "jane@example.com",
  "user_plan": "pro",
  "url": "http://demo.dropmark.com/1337/100",
  "short_url": "http://dpmk.com/i/QMSMSFwznJ",
  "thumbnails": {},
  "reactions": [],
  "is_url": false,
  "comments": [],
  "tags": [],
  "metadata": []
}

Update multiple items

Endpoint

PUT https://api.dropmark.com/v1/items

Input

Name	Type	Desc
`items`	`array`	Item ID’s (required)
`collection_id`	`Integer`	Collection ID for items to be moved into

Example

{
  "items": [100],
  "collection_id": 1337
}

Response

Status: 200 OK

Delete an item

Endpoint

DELETE https://api.dropmark.com/v1/items/:item_id

Input

Name	Type	Desc
`delete_items`	`boolean`	Set as `true` when deleting a stack to also delete child items (default: `false`)

Example

{
  "delete_items": true
}

Response

Status: 200 OK

{
  "code": "deleted",
  "message": "Item deleted"
}

Copy items

Creates a copy of the items, including tags and metadata. Comments and annotations are not copied.

Endpoint

PUT https://api.dropmark.com/v1/items/copy

Input

Name	Type	Desc
`items`	`array`	Item ID’s (required)
`collection_id`	`Integer`	Collection ID for items to be copied into. Leave blank to copy item into current collection

Example

{
  "items": [99]
}

Response

Status: 201 Created

[
  {
    "id": 100,
    "collection_id": 1337,
    "user_id": 1,
    "parent_id": null,
    "name": "Example item",
    "description": null,
    "content": "Hello world",
    "link": "",
    "preview": null,
    "thumbnail": null,
    "shareable": null,
    "size": 0,
    "sort": 5,
    "type": "text",
    "mime": "text/plain",
    "latitude": null,
    "longitude": null,
    "created_at": "2016-08-16T15:35:16Z",
    "updated_at": "2016-08-16T19:35:29Z",
    "deleted_at": null,
    "reactions_total_count": 0,
    "user_name": "Jane Doe",
    "user_email": "jane@example.com",
    "user_plan": "pro",
    "url": "http://demo.dropmark.com/1337/100",
    "short_url": "http://dpmk.com/i/QMSMSFwznJ",
    "thumbnails": {},
    "reactions": [],
    "is_url": false,
    "comments": [],
    "tags": [],
    "metadata": []
  }
]