API

Items

Overview

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

  1. List items
  2. Create an item
  3. Get an item
  4. List item tags
  5. Update an item
  6. Update multiple items
  7. Delete an item
  8. 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

POST 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": []
  }
]