Copyto API Documentation

This document describes v1 of the Copyto API.

Table of Contents

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:

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

Label List

Bookmark

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:

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:

/search - Search bookmarks

Fetch search results containing given keyword(s):

https://api.copyto.co/search

Required arguments:

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:

/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:

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:

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:

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:

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:

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:

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:

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