This document describes v1 of the Copyto API.
The Copyto API enables developers to interact with the Copyto web site programmatically via simple HTTP 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 userbookmark/save
- Save a bookmark to the user's accountbookmark/delete
- Delete a bookmark from the user's accountlabel
- Get labels of the userlabel/create
- Create a labellabel/delete
- Delete a labellabel/add
- Add a label to a bookmarklabel/remove
- Remove a label from a bookmarklabel/rename
- Rename a labelsearch
- Search bookmarks of the userFor 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
.
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.
info
- Information about the list
bookmark_count
- Number of bookmarks available for the current listmax_records
- Requested maximum number of bookmarkspage
- Requested page numberbookmarks
- Bookmarks of the user in bookmark typelabels
- Labels of the user in label typebookmark_id
- Numeric id of the bookmarktitle
- Title of the bookmarkdescription
- Description of the bookmarkoriginal_url
- Original url of the bookmarkurl
- Private url of the bookmark on Copytolabels
- Labels of the bookmark in label typethumbnail
- Url of the thumbnail for the bookmarkdate
- Unix time stamp in UTC for the bookmark save actionlabel_id
- Numeric id of the labellabel_name
- Name of the labelAuthentication is required for all API requests. Copyto supports HTTP Basic Auth with a special password called a remote key.
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.
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.
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
pairsubscription-ended
- User's subscription to Copyto endedtoo-many-requests
- Request limit for bookmark/save
exceededunknown-request
- Unknown request_method
unknown-action
- Unknown request_action
REQUEST_METHOD-REQUEST_ACTION-failed
- request_action
of request_method
failedREQUEST_METHOD-REQUEST_ACTION-success
- request_action
of request_method
is successfulARG-required
- Missing parameter in the requestno-bookmarks
- User has no bookmarksno-labels
- User has no labelsno-such-bookmark-or-label
- Label or bookmark does not existlabel-already-exists
- Bookmark already contains this labelAuthentication is required for reading data from Copyto.
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
.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
.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.
Authentication is required for writing data to Copyto.
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.
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.
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.
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.
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.
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.
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.