Copyto API Documentation

This document describes v1 of the Copyto API.

Table of Contents

• Summary
• Core Concepts
  • Requests
  • Registering your application
  • Data formats
  • Response types
  • Authentication
  • Rate limiting
  • Return codes
• Reading data from Copyto
  • /bookmark - Read bookmarks
  • /search - Search bookmarks
  • /label - Read labels
• Writing data to Copyto
  • /bookmark
    • /save - Save a bookmark
    • /delete - Delete a bookmark
  • /label
    • /create - Create a label
    • /delete - Delete a label
    • /add - Add a label to a bookmark
    • /remove - Remove a label from a bookmark
    • /rename - Rename a label

Summary

The Copyto API enables developers to interact with the Copyto web site programmatically via simple HTTP requests.

Core Concepts

Requests

All API requests are of the form https://api.copyto.co/request_method/[request_action]. Requests need to be for an authenticated user and from a registered application.

These are the API calls we currently support:

• bookmark - Get bookmarks of the user
• bookmark/save - Save a bookmark to the user's account
• bookmark/delete - Delete a bookmark from the user's account
• label - Get labels of the user
• label/create - Create a label
• label/delete - Delete a label
• label/add - Add a label to a bookmark
• label/remove - Remove a label from a bookmark
• label/rename - Rename a label
• search - Search bookmarks of the user

Registering your application

For all requests the Copyto API supports, the request should contain a valid api_key parameter obtained upon registering your application to Copyto Applications.

Requests from the application is monitored using this api_key.

Data formats

The Copyto API supports JSON output format. Dates are in unix time stamp format in UTC.

All read and write requests can be either HTTP GET or POST methods. However write requests are preferred to use POST and read requests are preferred to use GET method.

Response types

Bookmark List

• info - Information about the list
  • bookmark_count - Number of bookmarks available for the current list
  • max_records - Requested maximum number of bookmarks
  • page - Requested page number
• bookmarks - Bookmarks of the user in bookmark type

Label List

• labels - Labels of the user in label type

Bookmark

• bookmark_id - Numeric id of the bookmark
• title - Title of the bookmark
• description - Description of the bookmark
• original_url - Original url of the bookmark
• url - Private url of the bookmark on Copyto
• labels - Labels of the bookmark in label type
• thumbnail - Url of the thumbnail for the bookmark
• date - Unix time stamp in UTC for the bookmark save action

Label

• label_id - Numeric id of the label
• label_name - Name of the label

Authentication

Authentication is required for all API requests. Copyto supports HTTP Basic Auth with a special password called a remote key.

HTTP Basic Auth / Remote Keys

All Copyto users have a Remote Key to provide third party applications access to their Copyto account. A Copyto Remote Key is just like a password, except that it is only used for third party applications, so it only provides access to the functionality defined by the API. Users can easily reset it if a third party application abuses the API.

You can authenticate with Remote Keys using HTTP Basic Authentication. The username should be the user's username, and the password should be the user's Remote Key. You can direct users to https://copyto.co/remotekey to get their remote key if they have not memorized it.

Rate limiting

Bookmark save requests using bookmark/save API are limited to one request per 10 seconds for a remote_key/api_key pair. Requests other than bookmark/save will remain unlimited.

Return codes

Copyto returns appropriate HTTP status codes for API requests. In addition to the HTTP status code, Copyto includes extra information in the response body. Responses have a single property, returnCode, a program-readable string describing the status, e.g.:

{"returnCode":"bookmark_id-required"}

Return codes for the current version of the API:

• unauthorized-application - Unrecognized api_key
• unauthorized - Unrecognized username and remote_key pair
• subscription-ended - User's subscription to Copyto ended
• too-many-requests - Request limit for bookmark/save exceeded
• unknown-request - Unknown request_method
• unknown-action - Unknown request_action
• REQUEST_METHOD-REQUEST_ACTION-failed - request_action of request_method failed
• REQUEST_METHOD-REQUEST_ACTION-success - request_action of request_method is successful
• ARG-required - Missing parameter in the request
• no-bookmarks - User has no bookmarks
• no-labels - User has no labels
• no-such-bookmark-or-label - Label or bookmark does not exist
• label-already-exists - Bookmark already contains this label

Reading data from Copyto

Authentication is required for reading data from Copyto.

/bookmark - Read bookmarks

Fetch bookmarks of the user:

https://api.copyto.co/bookmark

Example using curl:

curl -u "username:remote_key" -d "api_key=YOUR_API_KEY" \
     https://api.copyto.co/bookmark

The response is a bookmark list upon success or the returnCode upon failure.

Optional arguments:

• max_records=number - Return no more records than the specified number, e.g., max_records=50. Default value is 10 and maximum value is 50.
• page=number - Return the specified page number, e.g., page=10. Pagination is based on the max_records.
• order=order - Return results sorted by order. Value can be one of time_asc, time_desc, title_asc or title_desc.
• label_id=label_id - Return bookmarks with the specified label_id, e.g., label_id=10.

/search - Search bookmarks

Fetch search results containing given keyword(s):

https://api.copyto.co/search

Required arguments:

• q=keyword(s) - Return bookmarks containing the specified keyword(s), e.g., q=copyto.

Example using curl:

curl -u "username:remote_key" -d "api_key=YOUR_API_KEY&q=copyto" \
     https://api.copyto.co/search

The response is a bookmark list upon success or the returnCode upon failure.

Optional arguments:

• max_records=number - Return no more records than the specified number, e.g., max_records=50. Default value is 10 and maximum value is 50.
• page=number - Return the specified page number, e.g., page=10. Pagination is based on the max_records.
• label_id=label_id - Return bookmarks with the specified label_id, e.g., label_id=10.

/label - Read labels

Fetch labels of the user:

https://api.copyto.co/label

Example using curl:

curl -u "username:remote_key" -d "api_key=YOUR_API_KEY" \
     https://api.copyto.co/label

The response is a label list upon success or the returnCode upon failure.

Writing data to Copyto

Authentication is required for writing data to Copyto.

/bookmark/save - Save a bookmark

Save a bookmark for the user:

https://api.copyto.co/bookmark/save

Required arguments:

• url=url - url to save, e.g., url=https://copyto.co.

Example using curl:

curl -u "username:remote_key" -d "api_key=YOUR_API_KEY&url=https://copyto.co/" \
     https://api.copyto.co/bookmark/save

The response is the newly saved bookmark upon success or the returnCode upon failure.

/bookmark/delete - Delete a bookmark

Delete a bookmark of the user:

https://api.copyto.co/bookmark/delete

Required arguments:

• bookmark_id=id - id of the bookmark to delete, e.g., booknark_id=1.

Example using curl:

curl -u "username:remote_key" -d "api_key=YOUR_API_KEY&bookmark_id=1" \
     https://api.copyto.co/bookmark/delete

The response is the returnCode according to the result.

/label/create - Create a label

Create a label for the user:

https://api.copyto.co/label/create

Required arguments:

• label_name=name - name of the label to create, e.g., label_name=label1.

Example using curl:

curl -u "username:remote_key" -d "api_key=YOUR_API_KEY&label_name=label1" \
     https://api.copyto.co/label/create

The response is the newly saved label upon success or the returnCode upon failure.

/label/delete - Delete a label

Delete a label of the user:

https://api.copyto.co/label/delete

Required arguments:

• label_id=id - id of the label to delete, e.g., label_id=1.

Example using curl:

curl -u "username:remote_key" -d "api_key=YOUR_API_KEY&label_id=1" \
     https://api.copyto.co/label/delete

The response is the returnCode according to the result.

/label/add - Add a label to a bookmark

Add a label to a bookmark of the user:

https://api.copyto.co/label/add

Required arguments:

• label_id=id - id of the label to add, e.g., label_id=1.
• bookmark_id=id - id of the bookmark to add the label to, e.g., bookmark_id=1.

Example using curl:

curl -u "username:remote_key" -d "api_key=YOUR_API_KEY&label_id=1&bookmark_id=1" \
     https://api.copyto.co/label/add

The response is the returnCode according to the result.

/label/remove - Remove a label from a bookmark

Remove a label from a bookmark of the user:

https://api.copyto.co/label/remove

Required arguments:

• label_id=id - id of the label to remove, e.g., label_id=1.
• bookmark_id=id - id of the bookmark to remove the label from, e.g., bookmark_id=1.

Example using curl:

curl -u "username:remote_key" -d "api_key=YOUR_API_KEY&label_id=1&bookmark_id=1" \
     https://api.copyto.co/label/remove

The response is the returnCode according to the result.

/label/rename - Rename a label

Rename a label of the user:

https://api.copyto.co/label/rename

Required arguments:

• label_id=id - id of the label to rename, e.g., label_id=1.
• label_name=name - name to rename current label name with, e.g., label_name=label+new.

Example using curl:

curl -u "username:remote_key" -d "api_key=YOUR_API_KEY&label_id=1&label_name=label+new" \
     https://api.copyto.co/label/rename

The response is the returnCode according to the result.

Copyto.co ©      About    Blog    Twitter    Discussion    API    How-to    Applications    Contact    Terms