Contents
Need to create your developer account? Sign up as a Developer
Introduction
The Flashcard Exchange API provides a simple RESTful interface with lightweight JSON-formatted responses to use many of the Flashcard Exchange website features. This document provides information to developers on how to integrate with the Flashcard Exchange API to search, create and modify flashcard sets and users.
API Basics
Before you can use our API you must sign up for an account and then register for a developer API Key. The key identifies your application to the Flashcard Exchange web service, and is used to track overall call usage.
Authentication
Flashcard Exchange requires that the OAuth 2.0 user flow to be implemented before any authenticated calls can be made on behalf of the user. However, sets with the access level set to public can be accessed by just providing the client_id.
Authentication Flow
User Authorization Process
Your application will first redirect to our authorization page, where the user will be asked to confirm access for the application requesting access. If the user accepts permission access, an authorization token will be created and redirected to the provided request_uri or the URI that was provided during the Client API signup with the authorize token. The Response Type must be set to “code”.
An example URL you'd redirect the user to: http://flashcardexchange.com/oauth2/authorize/?client_id=CLIENT_ID&scope=<read|read_write|read_write_delete>&state=123& redirect_uri=REDIRECT_URI&response_type=code
| Request Parameter | Description |
|---|---|
| client_id | Required. This is the Client ID value provided in your dashboard. |
| redirect_uri | Optional. A URI to which we should redirect the user. If provided, this value should match what you have provided when setting up your application account. See "about redirect URIs” for details. |
| state |
Optional. A random string generated by you. You send us this value, we’ll reply with this value, and you verify that the value we
send back matches the value you sent. You must send and verify this value in order to prevent Cross Site Request Forgery CSRF attacks. |
| scope | Required. The permission level set for the requested authorization. Possible values: read, read_write, read_write_delete. |
| response_type | Required. Possible value: code. |
If the user authorizes your application, our server will redirect the user to the provided redirect
URI (or the redirect URI registered, if you didn't provide one). The code your app receives will only last
for 60 seconds. An example of the response looks like:
HTTP/1.1 302 Found
Location: YOUR_URL/?code=GENERATED_CODE&state=YOUR_STATE
User Denies Your Application
If the user denies access to your application, our server will redirect the user to your URI with error="access_denied" as the query parameter. For example:
HTTP/1.1 302 Found
Location: YOUR_URL/?error=access_denied&error_description=The+user+denied+access+to+your+application
Turning Authorize Token into Access Token
After receiving the authorize token, your application is now ready to request an access token.
To request an access token, you must make a POST request with the below information to: https://api.flashcardexchange.com/oauth2/token/
| Parameter | Description |
|---|---|
| code | Required. This should be a posted parameter. It should be the authorize token you received from post back url from User Authorization Process. |
| grant_type | Required. Possible value: authorization_code. |
| Basic Authentication |
Required. You should use HTTP Basic Access Authentication
to provide your API Key and Secret Key. Make sure your API Key and Secret Key are separated by a colon and the entire value is base64-encoded.
Header: Authorization: Basic <BASE64-encoded[CLIENTID:SECRET_KEY]> |
If the call is successful we will return a JSON encoded result containing the access token as follows:
| RESPONSE |
|---|
|
{
"access_token":"0d927a3c8c1860bc05e1097d5a12a3663bbxxxxx",
"expires_in":"600",
"token_type":"bearer",
"user_id":"5",
"user_name":"madstudier",
"scope":"read read_write read_write_delete",
"refresh_token":"9a52ab390c14007a86514839c31b9bc58f616cf1"
}
{ "error":"invalid_client", "error_description":"Client id was not found in the headers or body" } { "error":"invalid_request", "error_description":"Invalid grant_type parameter or parameter missing" } { "error":"invalid_request", "error_description":"Missing parameter. \"code\" is required" } { "error":"invalid_grant", "error_description":"Refresh token doesn't exist or is invalid for the client" } |
| Parameter | Description |
|---|---|
| access_token | The access token for this user. |
| expires_in | The duration of time in seconds this access token is valid. |
| token_type | -- |
| user_name | The user name of the user who authorized your application. |
| scope | The scope set in User Authorization Process. |
| refresh_token | Refresh token to use to retrieve a new access token when access token expires or become invalid. |
Refreshing Access Token by using Refresh Token
As we described, the refresh_token is used when the access_token is not valid or expires.
To make a request for a new access token, you can either make a GET or POST request with the below information to:
https://api.flashcardexchange.com/oauth2/token
| Parameter | Description |
|---|---|
| refresh_token | Required. This request token was returned during the process of Turning Access Token into Authorize Token. |
| grant_type | Required. Possible value: refresh_token. |
| Basic Authentication |
Optional, but you must pass Basic Authentication or client_id and client_secret. You should use
HTTP Basic Access Authentication
to provide your API Key and Secret Key. Make sure your API Key and Secret Key are separated by a colon and the entire
value is base64-encoded. Header: Authorization: Basic <BASE64-encoded[CLIENTID:SECRET_KEY]> |
| client_id | Optional, but you must pass Basic Authentication or client_id and client_secret. The client id provided when setting up application account. |
| client_secret | Optional, but you must pass either Basic Authentication or client_id and client_secret. The client secret provided when setting up application account. |
| scope | Required. The permission level set for the requested authorization. Possible values: read, read_write, read_write_delete. |
Example token request (GET):
GET /oauth2/token HTTP/1.1
Host: minus.com
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
grant_type=refresh_token&client_id=8c1930fddec2e70a9a6791c1fb2b82&client_secret=e80eae9fe98d431f5e642714695d7c&
scope=read&refresh_token=20ad15128b
If the call is successful we will return a JSON encoded result similar to retrieving access token (See Section Turning Authorize Token into Access Token for possible response):
| RESPONSE |
|---|
|
{
"access_token":"0d927a3c8c1860bc05e1097d5a12a3663bbxxxxx",
"expires_in":"600",
"token_type":"bearer",
"user_id":"5",
"user_name":"madstudier",
"scope":"read read_write read_write_delete",
"refresh_token":"3c111d06a935651f7602811d7db5bccdf3be86f6"
} { "error":"invalid_client", "error_description":"Client id was not found in the headers or body" } { "error":"invalid_request", "error_description":"Invalid grant_type parameter or parameter missing" } { "error":"invalid_grant", "error_description":"Refresh token doesn't exist or is invalid for the client" } { "error":"invalid_scope", "error_description":"An unsupported scope was requested." } |
| RESPONSE EXAMPLES INDICATING TO REFRESH TOKEN |
|---|
| { "error":"invalid_grant", "error_description":"The access token provided is invalid.","scope":["read"] } |
Making Calls
After obtaining an access token, API calls can be made by adding an Authorization header to all requests as follows.
| Header |
|---|
| Authorization: Bearer ACCESS_TOKEN |
Retrieving Sets
Sets with the access level set to public can be accessed by just providing the client_id. Request’s made with a user authenticated token, will search both private sets accessible to the user and public sets.
Searching for a Set by Given Term
curl -H "Authorization: Bearer bacea761b6021d1ce39a805d3c0c8ab9a64db0ac" -X GET https://api.flashcardexchange.com/v2/search/sets?qstr=accounting
| METHOD | URI | DESCRIPTION |
|---|---|---|
| GET | /search/sets | Search for all flashcard sets. |
| PARAMS | OPTIONAL | TYPE | DESCRIPTION |
|---|---|---|---|
| qstr | Y|N - At least qstr and/or card must be passed. | string | Searches against the title, description and subject. |
| card | Y|N - At least qstr and/or card must be passed. | string | Searches against cards only. |
| image_filter | Y | Values: 0, 1, empty |
Returns sets with images only if value is set to 1, If value is set to 0, only sets without
images will return. If omitted, sets with and without images will be returned.
Default value: 1 |
| sortby | Y | string |
Currently only "most_studied", "highest_rated", best_match and "most_recent" are supported.
Default value: most_studied |
| modified_since | Y | unix-timestamp | need info? |
| page | Y | int | Default page is 1. |
| limit | Y | int | This is the number of results you would like to return per page |
| RESPONSE |
|---|
|
{
"total_matches": 200,
"page": 1,
"results": [
{
"set_id": "100",
"user_id": "34",
"user_name": "Daisy",
"title": "Exam 3: Medical Mycology",
"subject": "Exams",
"url": "http://www.flashcardexchange.com/cards/Exam-3-Medical-Mycology-2188349",
“score”: 2.6
“views”: 1000
“has_image”: 1
"created": "2012-09-26 13:17:50",
"last_modified": "2012-09-26 13:17:50",
"card_count": 113,
"access": "public"
},
{
"set_id": "101",
"user_id": "4",
"user_name": "Dizzy",
"title": "Exam 3: Medical Mycology 2",
"url": "http://www.flashcardexchange.com/cards/Exam-3-Medical-Mycology-2188349 2",
“score”: 2.6
“has_image”: 1
"created": 1316989231,
"last_modified": 1316989111,
"card_count": 14,
"access": "public"
}
]
}
{ "error":"invalid_request", "error_description":"Incorrect Parameters. Must contain one of the following:(qstr|card)" } { "error":"invalid_client", "error_description":"The client credentials are invalid" } |
Viewing a Particular SetID By Set Id
curl -H "Authorization: Bearer 24e1a70bcaef1c4194c39120f87482e7bd3279d9" -X GET https://api.flashcardexchange.com/v2/sets/145
| METHOD | URI | DESCRIPTION |
|---|---|---|
| GET | /sets/:SETID | Retrieve information on a particular set id. |
| Params | Optional | Description |
|---|---|---|
| modified_since | Y - unix timestamp | If no card in the set was modified after the modified_since value, a 304 response code will be returned. |
| RESPONSE |
|---|
|
[{
"set_id": "100",
"user_id": "34",
"title": "Exam 3: Medical Mycology",
"subject": "Exams",
"description": "Exams for me",
"url": "http://www.flashcardexchange.com/cards/Exam-3-Medical-Mycology-2188349",
"card_count": "113",
"lang_front": "en",
"lang_back": "es",
"lang_hint": "es",
"score": "2.5",
"views": "1000",
"has_image": "1",
"created": "2012-09-26 15:30:42",
"last_modified": "2012-09-26 15:30:42",
"access": "public",
“cards”: [
{
"card_id": "344",
"front": "Los angeles",
"back": "Lakers",
"hint": "Basketball team",
"image_front": "http://d3cgb598vs7bfg.cloudfront.net/images/upload-flashcards/front/34/1/40614559_m.jpg",
"image_url": "http://d3cgb598vs7bfg.cloudfront.net/images/upload-flashcards/front/34/1/40614559_m.jpg",
"image_hint": null,
"last_modified": "2012-09-26 15:30:42"
},
{
"card_id": "234",
"front": "Houston",
"back": "Rockets",
"hint": "Basketball team",
"image_front": "http://d3cgb598vs7bfg.cloudfront.net/images/upload-flashcards/front/34/1/40614559_m.jpg",
"image_url": "http://d3cgb598vs7bfg.cloudfront.net/images/upload-flashcards/front/34/1/40614559_m.jpg",
"image_hint": "http://d3cgb598vs7bfg.cloudfront.net/images/upload-flashcards/front/34/1/40614559_m.jpg",
"last_modified": "2012-09-26 15:30:42"
}
]
}]
{ "error":"invalid_request", "error_description":"No results matched your query. Please try again with a different search term and/or parameter." } { "error":"invalid_client", "error_description":"The client credentials are invalid" } |
| curl -H "Authorization: Bearer c9da44d5662d8d10c40495357633e8c5e24b4851" -i -X GET https://api.flashcardexchange.com/v2/sets/145?modified_since=1241223810 |
View Multiple Sets at Once by Set Ids
curl -H "Authorization: Bearer c9da44d5662d8d10c40495357633e8c5e24b4851" -i -X GET https://api.flashcardexchange.com/v2/sets?id=145,225,2175839
| METHOD | URI | DESCRIPTION |
|---|---|---|
| GET | /sets | View multiple sets at once. |
| Params | Optional | |
|---|---|---|
| id | N - string | List of ids should be separated by a comma. ie, id=72,1123423,112,35... |
| modified_since | Y | If no card in the set was modified after the modified_since value, a 304 response code will be returned. |
| RESPONSE |
|---|
| [ { "set_id": "100", "user_id": "34", "title": "Exam 3: Medical Mycology", "subject": "Exams", "description": "Exams for me", "url": "http://www.flashcardexchange.com/cards/Exam-3-Medical-Mycology-2188349", "card_count": "113", "lang_front": "en", "lang_back": "es", "lang_hint": "es", "score": null, "views": null, "has_image": "1", "created": "2012-09-26 15:30:42", "last_modified": "2012-09-26 15:30:42", "access": "public", “cards”: [ { "card_id": "234", "front": "Houston", "back": "Rockets", "hint": "Basketball team", "image_front": "http://d3cgb598vs7bfg.cloudfront.net/images/upload-flashcards/front/34/1/40614559_m.jpg", "image_url": "http://d3cgb598vs7bfg.cloudfront.net/images/upload-flashcards/front/34/1/40614559_m.jpg", "image_hint": "http://d3cgb598vs7bfg.cloudfront.net/images/upload-flashcards/front/34/1/40614559_m.jpg", "last_modified": "2012-09-26 15:30:42" }, "card_id": "235", "front": "Houston", "back": "Rockets", "hint": "Basketball team", "image_front": null, "image_url": null, "image_hint": null, "last_modified": "2012-09-26 15:30:42" } ] }, { "set_id": "100", "user_id": "34", "title": "Exam 3: Medical Mycology", "subject": "Exams", "description": "Exams for me", "url": "http://www.flashcardexchange.com/cards/Exam-3-Medical-Mycology-2188349", "card_count": "113", "lang_front": "en", "lang_back": "es", "lang_hint": "es", "score": null, "views": null, "has_image": "1", "created": "2012-09-26 15:30:42", "last_modified": "2012-09-26 15:30:42", "access": "public", “cards”: [ { "card_id": "234", "front": "Houston", "back": "Rockets", "hint": null, "image_front": "http://d3cgb598vs7bfg.cloudfront.net/images/upload-flashcards/front/34/1/40614559_m.jpg", "image_url": "http://d3cgb598vs7bfg.cloudfront.net/images/upload-flashcards/front/34/1/40614559_m.jpg", "image_hint": "http://d3cgb598vs7bfg.cloudfront.net/images/upload-flashcards/front/34/1/40614559_m.jpg", "last_modified": "2012-09-26 15:30:42" }, "card_id": "235", "front": "Houston", "back": "Rockets", "hint": "Basketball team", "image_front": "http://d3cgb598vs7bfg.cloudfront.net/images/upload-flashcards/front/34/1/40614559_m.jpg", "image_url": "http://d3cgb598vs7bfg.cloudfront.net/images/upload-flashcards/front/34/1/40614559_m.jpg", "image_hint": "http://d3cgb598vs7bfg.cloudfront.net/images/upload-flashcards/front/34/1/40614559_m.jpg", "last_modified": "2012-09-26 15:30:42" } ] } ] If no id matches or modified dates doesn’t return. { "error":"invalid_request", "error_description":"No results matched your query. Please try again with a different search term and\/or parameter." } |
Retrieving User Data
Retrieve a User Profile
Note that the user_id is returned during the retrieval of the access token.
curl -H "Authorization: Bearer bacea761b6021d1ce39a805d3c0c8ab9a64db0ac" -X GET https://api.flashcardexchange.com/v2/users/doug
| METHOD | URI | DESCRIPTION |
|---|---|---|
| GET | /users/:USERNAME | Retrieve a user profile. |
| Params | Optional | |
|---|---|---|
| modified_since | Y - unix timestamp | Will only return sets, favorites and studied sets after the modified_since parameter. |
| RESPONSE |
|---|
|
{
"username": "d908233545",
"date_joined": "2005-04-12 12:06:32",
"sets": [
{
"set_id": "100",
"title": "Exam 3: Medical Mycology",
"subject": "Exams",
"description": "Exams for me",
"url": "http://www.flashcardexchange.com/cards/Exam-3-Medical-Mycology-2188349",
"card_count": "113",
"lang_front": "en",
"lang_back": "es",
"lang_hint": "es",
"score": "2.5",
"views": "1000",
"has_image": "1",
"created": "2012-09-26 15:30:42",
"last_modified": "2012-09-26 15:30:42",
"access": "public"
}
],
"favorites": {
"sets": [
{
"set_id": "100",
"title": "Exam 3: Medical Mycology",
"subject": "Exams",
"description": "Exams for me",
"url": "http://www.flashcardexchange.com/cards/Exam-3-Medical-Mycology-2188349",
"card_count": "113",
"lang_front": "en",
"lang_back": "es",
"lang_hint": "es",
"score": "2.5",
"views": "1000",
"has_image": "1",
"created": "2012-09-26 15:30:42",
"last_modified": "2012-09-26 15:30:42",
"access": "public",
},
{
"set_id": "100",
"title": "Exam 3: Medical Mycology",
"subject": "Exams",
"description": "Exams for me",
"url": "http://www.flashcardexchange.com/cards/Exam-3-Medical-Mycology-2188349",
"card_count": "113",
"lang_front": "en",
"lang_back": "es",
"lang_hint": "es",
"score": "2.5",
"views": "1000",
"has_image": "1",
"created": "2012-09-26 15:30:42",
"last_modified": "2012-09-26 15:30:42",
"access": "public",
}
],
"total": 2
},
"studied": {
"sets": [
{
"set_id": "100",
"title": "Exam 3: Medical Mycology",
"subject": "Exams",
"description": "Exams for me",
"url": "http://www.flashcardexchange.com/cards/Exam-3-Medical-Mycology-2188349",
"card_count": "113",
"lang_front": "en",
"lang_back": "es",
"lang_hint": "es",
"score": null,
"views": null,
"has_image": "1",
"created": "2012-09-26 15:30:42",
"last_modified": "2012-09-26 15:30:42",
"access": "public",
"type": "Memorize",
"time_studied": "1348616626"
}
],
"total": 2
}
} |
| {"error":"invalid_request","error_description":"Access token is must be present for request."} |
| {"error":"invalid_request","error_description":"Invalid user_name."} |
Retrieve a User’s List of Favorites
You can retrieve public favorite sets of any user by making a GET request to /v2/users/:username/favorites using any authorization token. To retrieve also private sets from a user the authorization token you are using must match the username you are requesting.
Example usage: curl -H "Authorization: Bearer bacea761b6021d1ce39a805d3c0c8ab9a64db0ac" -X GET https://api.flashcardexchange.com/v2/users/doug/favorites
| METHOD | URI | DESCRIPTION |
|---|---|---|
| GET | /users/:USERNAME/favorites | Retrieve the user’s list of favorites sets. |
| Params | Optional | |
|---|---|---|
| modified_since | Y - unix timestamp | Will only return favorites modified_since parameter (applied only for logged in users). |
| RESPONSE |
|---|
| { "username": "d908233545", "date_joined": "2005-04-12 12:06:32", "favorites": { "sets": [ { "set_id": "2189219", "title": "SSCP Access Controls.db", "subject": "access controlsdb sscp", "url": "http://www.flashcardexchange.com/SSCP-Access-Controlsdb-2189219", "card_count": "44", "lang_front": "en", "lang_back": "es", "lang_hint": "es", "score": null, "views": "28", "has_image": "0", "created": "2012-05-08 00:00:00", "last_modified": "2012-09-26 13:17:50", "access": "public", "cards": [ { "card_id": "57010523", "front": "What are the two aspects of access control?", "back": "prevent unauthorized access and to control authorized access", "hint": "Access", "image_front": "http://d3cgb598vs7bfg.cloudfront.net/images/upload-flashcards/front/34/1/40614559_m.jpg", "image_url": "http://d3cgb598vs7bfg.cloudfront.net/images/upload-flashcards/front/34/1/40614559_m.jpg", "image_hint": "http://d3cgb598vs7bfg.cloudfront.net/images/upload-flashcards/front/34/1/40614559_m.jpg", "last_modified": "2012-09-26 15:30:42" }, { "card_id": "57010524", "front": "What are the three objectives of data protection?", "back": "confidentiality, integrity, and availability", "hint": null, "image_front": null, "image_url": null, "image_hint": null, "last_modified": "2012-09-26 15:30:42" }, { "card_id": "57010525", "front": "What are the three elements in protecting integrity?", "back": "authenticity, non-repudiation, and accountability", "hint": "Hint text", "image_front": null, "image_url": null, "image_hint": "http://d3cgb598vs7bfg.cloudfront.net/images/upload-flashcards/front/34/1/40614559_m.jpg", "last_modified": "2012-09-26 15:30:42" }, ] }, { "set_id": "2189469", "title": "ch 12 vocab", "subject": "fda", "url": "http://www.flashcardexchange.com/ch-12-vocab-2189469", "card_count": "30", "lang_front": "en", "lang_back": "es", "lang_hint": "es", "score": null, "views": null, "has_image": "0", "created": "2012-05-09 00:00:00", "last_modified": "2012-09-25 20:57:59", "access": "public", "cards": [ { "card_id": "57016418", "front": "cause", "back": "cause", "hint": "hint text", "image_front": null, "image_url": null, "image_hint": null, "last_modified": "2012-09-26 15:30:42" }, { "card_id": "57016419", "front": "coexister", "back": "to coexist", "hint": "hint text", "image_front": "http://d3cgb598vs7bfg.cloudfront.net/images/upload-flashcards/front/34/1/40614559_m.jpg", "image_url": "http://d3cgb598vs7bfg.cloudfront.net/images/upload-flashcards/front/34/1/40614559_m.jpg", "image_hint": "http://d3cgb598vs7bfg.cloudfront.net/images/upload-flashcards/front/34/1/40614559_m.jpg", "last_modified": "2012-09-26 15:30:42" }, { "card_id": "57016420", "front": "un consensus", "back": "consensus", "hint": "hint text", "image_front": null, "image_url": null, "image_hint": null, "last_modified": "2012-09-26 15:30:42" }, ] } ], "total": 2 } } |
| {"username":"d908233545","date_joined":"2005-04-12 12:06:32"} |
| {"error":"invalid_request","error_description":"Access token is must be present for request."} |
Retrieve a User’s List of Studied Sets
You can retrieve public studied sets of any user by making a GET request to /v2/users/:username/studied using any authorization token. To retrieve also
private sets from a user the authorization token you are using must match the username you are requesting.
Example usage:
curl -H "Authorization: Bearer bacea761b6021d1ce39a805d3c0c8ab9a64db0ac" -X GET https://api.flashcardexchange.com/v2/users/doug/studied
| METHOD | URI | DESCRIPTION |
|---|---|---|
| GET | /users/:USERNAME/studied | Retrieve the user’s list of studied tests. |
| Params | Optional | |
|---|---|---|
| modified_since | Y - unix timestamp | Will only return sets studied after the modified_since parameter. |
| RESPONSE |
|---|
| { "username": "d908233545", "date_joined": "2005-04-12 12:06:32", "studied": { "sets": [ { "set_id": "2192638", "title": "Flash Card Test", "subject": "Yoga", "url": "http://www.flashcardexchange.com/mytestingflashcards-2192638", "card_count": "3", "lang_front": "en", "lang_hint": "es", "score": "0", "views": "2", "has_image": "0", "created": "2012-09-26 15:30:42", "last_modified": "2012-09-26 16:09:37", "access": "public", "cards": [ { "card_id": "57020640", "front": "Example 1 Front", "back": "Example 1 Back", "hint": "hint text", "image_front": null, "image_url": null, "image_hint": "http://d3cgb598vs7bfg.cloudfront.net/images/upload-flashcards/front/34/1/40614559_m.jpg", "last_modified": "2012-09-26 15:30:42" }, ], "type": "Memorize", "time_studied": "1348693783" }, { "set_id": "2186371", "title": "Calm Spirit: Herbs 3 Dr Qi", "subject": "3 calm dr herbs qi spirit:", "url": "http://www.flashcardexchange.com/Calm-Spirit-Herbs-3-Dr-Qi-2186371", "card_count": "12", "lang_front": "33", "lang_back": "33", "lang_hint": "33", "score": "3.5", "views": "84", "has_image": "0", "created": "2012-05-06 00:00:00", "last_modified": "2012-09-26 17:34:15", "access": "public", "cards": [ { "card_id": "56936141", "front": "Ci Shi", "back": "Must decoct 30 minutes early & Heavy dosage 15-30g:Magnetic Stone: 1- calm spirit: epilepsy due to KD def: 2- subdue LV Yang 3- improve hearing and vision; KD/LV def. 4: calms wheezing: helps KD grasp QI", "hint": "Hint", "image_front": null, "image_url": null, "image_hint": null, "last_modified": "2012-09-26 15:30:42" }, { "card_id": "56936142", "front": "Hu Po (Amber) or Xue Po if red", "back": "1: Calms spirit 2- moves blood and dissipates statis 3: promotoes urination Small dosage; DON’T DECOCT will get sticky can create blood clots: C/I= Yin def heat", "hint": null, "image_front": null, "image_url": null, "image_hint": null, "last_modified": "2012-09-26 15:30:42" }, { "card_id": "56936143", "front": "Long Gu (Dragon Bone)", "back": "1- calms spirit 2- subdue LV Yang 3- Bind Leaking- esp for excessive sweating and night sweats : Used Raw for spirit & cooked for leakage: C/I= Damp heat or ext pathogen because stops sweating and retains pathogen", "hint": "hint", "image_front": null, "image_url": null, "image_hint": null, "last_modified": "2012-09-26 15:30:42" }, ], "type": "Memorize", "time_studied": "1348616626" } ], "total": 2 } } |
| {"username":"k1828183555","date_joined":"2001-11-13 19:54:05"} |
| {"error":"invalid_request","error_description":"Invalid user_name."} |
| {"error":"invalid_request","error_description":"Access token is must be present for request."} |
Retrieve all of the Users Sets
You can retrieve public sets of any user by making a GET request to /v2/users/:username/sets using any authorization token. To retrieve also
private sets from a user the authorization token you are using must match the username you are requesting.
Example usage:
curl -H "Authorization: Bearer 6c37a5231fcaf5149386b55663b9be5f56d7533c" -X GET https://api.flashcardexchange.com/v2/users/doug/sets
| METHOD | URI | DESCRIPTION |
|---|---|---|
| GET | /users/:USERNAME/sets | retrieve user’s list of sets |
| Params | Optional | |
|---|---|---|
| modified_since | Y - unix timestamp | Will only return sets created after the modified_since parameter (applied only for logged in users). |
| RESPONSE |
|---|
| { "username": "d908233545", "date_joined": "2005-04-12 12:06:32", "sets": [ { "set_id": "2192700", "title": "asdf", "subject": "Asdf yoga", "url": "http://www.flashcardexchange.com/asdf-2192700", "card_count": "3", "lang_front": "en", "lang_back": "en", "lang_hint": "en", "score": "0", "views": "1", "has_image": "0", "created": "2012-09-26 18:14:31", "last_modified": "2012-09-26 18:14:33", "access": "public", "cards": [ { "card_id": "56936143", "front": "sdf", "back": "asdf", "hint": null, "image_front": null, "image_url": null, "image_hint": null, "last_modified": "2012-09-26 15:30:42" }, { "set_id": "2192700", "card_id": "57020680", "front": "asdf", "back": "adsf", "hint": "hint", "image_front": null "image_url": null "image_hint": null }, { "set_id": "2192700", "card_id": "57020681", "front": "sdfaseee", "back": "asdfasdfadf", "hint": "hint", "image_front": null "image_url": null "image_hint": null } ] }, { "set_id": "2192638", "title": "My$Testing&Flashcards", "subject": "Yoga", "url": "http://www.flashcardexchange.com/mytestingflashcards-2192638", "card_count": "3", "lang_front": "33", "lang_back": "33", "lang_hint": "33", "score": "0", "views": "2", "has_image": "0", "created": "2012-09-26 15:30:42", "last_modified": "2012-09-26 16:09:37", "access": "public", "cards": [ { "set_id": "2192638", "card_id": "57020640", "front": "Dougness", "back": "Dougnessity", "hint": "hint", "image_front": null "image_url": null "image_hint": null }, { "set_id": "2192638", "card_id": "57020641", "front": "Dougnity", "back": "Dougnitissity", "hint": "hint", "image_front": null "image_url": null "image_hint": null }, { "set_id": "2192638", "card_id": "57020642", "front": "Douged", "back": "Just Douged Out", "hint": null, "image_front": null "image_url": null "image_hint": null } ] } ] } |
| {"username":"k1828183555","date_joined":"2001-11-13 19:54:05"} |
| {"error":"invalid_request","error_description":"Invalid user_name."} |
| {"error":"invalid_request","error_description":"Access token is must be present for request."} |
Creating Sets with Cards for Given User
Uploading Images
- The form encoding of the POST request must be multipart/form-data.
- All images uploaded to our server are resized and stored with a maximum of 1024 pixels on the longest side. To reduce upload times for your users you should consider resizing images before they are submitted to us.
- The maximum size per image is 5Mb.
- The total size of all images in a single request must be less than 20Mb.
- The only allowed extensions are: jpg, jpeg, gif, png.
- Requires read_write scoped access token.
curl -H "Authorization: Bearer edb3ff9a77ab4ad6eda8cb65a3f9a23a2fadfbe3" -i -X POST -F "image_data[]=@/Users/dougngo/Downloads/logo4.jpeg" -F "image_data[]=@/Users/dougngo/Downloads/rotatetrans.png" https://api.flashcardexchange.com/v2/images
| METHOD | URI | DESCRIPTION |
|---|---|---|
| POST | /images | Upload images to Flashcard exchange. |
| PARAMETER | OPTIONAL - TYPE | DESCRIPTION |
|---|---|---|
| image_data[] | N - array | required parameter |
| RESPONSE |
|---|
| { "images": [ { "id":"lqylpQ==", "url":"http://d3cgb598vs7bfg.cloudfront.net/images/upload-flashcards/5/trans_test.png }, { "id":"lqylpg==", "url":"http://d3cgb598vs7bfg.cloudfront.net/images/upload-flashcards/5/trans.png" } ] } |
| {"error":"invalid_scope","error_description":"The request requires higher privileges than provided by the access token.","scope":["read_write"]} |
| {"error":"invalid_grant","error_description":"The access token provided is invalid.","scope":["read_write"]} |
| {"error":"invalid_request","error_description":"Incorrect Parameters. Must contain the image_data[] array parameter"} |
Adding a New set
curl -H "Authorization: Bearer 733398975bbc6892adbaf511fb241ea918350329" -i -X POST -F "title=New title set" -F "description=defining new title set example" -F "back[]=second modified" -F "front[]=this is another front" -F "front[]=front" -F "hint[]=hint for the first card" -F "hint[]=hint for the second card" -F "lang_back=en" -F "lang_front=es" -F "subject[]=herbs" -F "subject[]=accounting" -F "back[]=this is another back" -F "front[]=third card" -F "back[]=last card" -F "image_id[]=lqylpQ==" -F "front_image_id[]=lqylpQ==" -F "hint_image_id[]=lqylpQ==" https://api.flashcardexchange.com/v2/sets
PermissionsCreating a set requires a read_write_delete scoped access token authorized by a user.
| METHOD | URI | DESCRIPTION |
|---|---|---|
| POST | /sets | Creates a flashcard set. |
| PARAMETER | OPTIONAL - TYPE | DESCRIPTION |
|---|---|---|
| title | N - string | Title of the set. |
| subject[] | Y- array | Array of one or more subjects. |
| description | Y- string | A text description of the set. |
| front[] | N - array | Array containing the information for the front side of the cards. Array size must be atleast 3 or more |
| back[] | N - array | Array containing the information for the back side of the cards. Array size must be atleast 3.
Note: The front[] and back[] arrays must contain an equal number of elements. |
| hint[] | Y - array | Array containing the information for the hint side of the cards. Hints will be assigned in the order of the array. |
| lang_front | Y - string | Language code of the front of the cards. Default language will be set to English(“en”) if none is specified. |
| lang_back | Y - string | Language code of the back of the cards. Default language will be set to English(“en”) if none is specified. |
| lang_hint | Y - string | Language code of the hint of the cards. Default language will be set to English(“en”) if none is specified. |
| image_id[] | Y - array | Array of image_id’s. Images will be assigned to the back card in the order of the array.
Note: image_id are returned from the uploading an image process |
| front_image_id[] | Y - array | Array of front_image_id’s. Images will be assigned to the front card in the order of the array.
Note: IDs of images are returned from the uploading an image process |
| hint_image_id[] | Y - array | Array of hint_image_id’s. Images will be assigned to the hint side of a card in the order of the array.
Note: IDs of images are returned from the uploading an image process |
| access | Y - public or private | default will be set to public |
| RESPONSE Error |
|---|
| {"error":"invalid_request","error_description":"Incorrect Parameters. Must contain one or all of the following:(title|front|back)"}" {"error":"invalid_request","error_description":"Incorrect Parameters. Parameter count of front and back are different OR number of cards must be equal or greater than 3"}" {"error":"invalid_request","error_description":"Incorrect Parameters. front or back must be array type such as front[] or back[]"} {"error":"invalid_request","error_description":"Incorrect Parameters. subject must be array type such as subject[]"}" {"error":"invalid_request","error_description":"Access token is not set for specified user."} |
| RESPONSE Success |
|---|
|
{
"status":1,
"set_id":"2190918",
"message":"Set successfully inserted with set_id:2190918",
"url":"http://www.flashcardexchange.com\/cards\/new-title-set-1348019594",
"card_count":3
cards
{
"0": "57021984",
"1": "57021985",
"2": "57021986",
}
{ "status":1, "set_id":"2192721", "message":"Set successfully inserted with set_id:2192721", "url":"http://www.flashcardexchange.com\/cards\/apilogtesting-2192721", "card_count":3 cards { "0": "57021987", "1": "57021988", "2": "57021989", } } |
Manipulating Sets and Cards
Add a Card to an Existing Set
curl -H "Authorization: Bearer 6c37a5231fcaf5149386b55663b9be5f56d7533c" -i -X POST -F "front=first" -F "back=second" -F "hint=hint text" -F "front_image_id=lqyl2==" -F "hint_image_id=lqyl2==" https://api.flashcardexchange.com/v2/sets/2189691/cards
| METHOD | URI | DESCRIPTION |
|---|---|---|
| POST | /sets/:ID/cards | Add card to an existing set. |
| PARAMETER | OPTIONAL - TYPE | DESCRIPTION |
|---|---|---|
| front | N - string | Text for front of the card. |
| back | N - string | Text for the back of the card. |
| hint | Y - string | Text for the hint side of the card. |
| image_id | Y - string | Image_id from image upload process. |
| front_image_id | Y - string | Image id for the front side of the card. |
| hint_image_id | Y - string | Image id for the hint side of the card. |
| RESPONSE |
|---|
|
{
"message":"Successfully inserted card_id:57016981 to set_id:2189691",
"set_id":"2189691",
"card_id":"57016981"
}
{"error":"invalid_request","error_description":"Incorrect Parameters. Must contain one or all of the following:(set_id|front|back)"}" |
Modify an Existing Set
curl -H "Authorization: Bearer 6c37a5231fcaf5149386b55663b9be5f56d7533c" -i -X PUT -F "title=New title set" -F "description=defining new title set example" -F "back=second modified" -F lang_front=es https://api.flashcardexchange.com/v2/sets/145
| METHOD | URI | DESCRIPTION |
|---|---|---|
| PUT | /sets/:ID/ | Modify data to an existing set. |
| Parameter | Type | Description |
|---|---|---|
| title | string | The title of the set. |
| description | string | The description of the set. |
| subject[] | array | an array type subject. For mutliple subjects, set subject[]=first subject, subject[]=second subject |
| access | string: public|private | Set permission levels for the set. |
| lang_front | string | Language code. Please see link for list of possible codes. |
| lang_back | string | Language code. Please see link for list of possible codes. |
| lang_hint | string | Language code. Please see link for list of possible codes. |
| RESPONSE |
|---|
|
{"status":1,"message":"Set ID:145 was successfully updated"}
{"status":2,"message":"No Records Affected"} {"error":"invalid_request","error_description":"Error in modifying set id:2192765"} |
Update a Single Card in a Set
curl -H "Authorization: Bearer 6c37a5231fcaf5149386b55663b9be5f56d7533c" -i -X PUT -F "front=first modified" -F "back=second modified" -F "hint=hint text" -F "image_id=lqyl2==" -F "image_front_id=lqyl2==" -F "image_hint_id=lqyl2==" https://api.flashcardexchange.com/v2/sets/2189691/cards/57
| METHOD | URI | DESCRIPTION |
|---|---|---|
| PUT | /sets/:ID/cards/CARD_ID | Modify data to an existing set. |
| PARAMETER | OPTIONAL - TYPE | DESCRIPTION |
|---|---|---|
| front | N - string | Text for the front side of the card. |
| back | N - string | Text for the back side of the card. |
| hint | Y - string | Text for the hint side of the card. |
| image_id | Y - string | Image_id from image upload process. |
| front_image_id | Y - string | Image id for the front side of the card. |
| hint_image_id | Y - string | Image id for the hint side of the card. |
| RESPONSE |
|---|
|
{
"status":1,
"message":"Card ID:57020853 was successfully updated"
}
{ "status":2,"message":"No Records Affected" } {"error":"invalid_request","error_description":"Incorrect Parameters. Must contain one or all of the following:(id|set_id|front|back)"} {"error":"invalid_request","error_description":"Incorrect Parameters. Must contain one or all of the following:(id)"} |
Manipulating User Data
Add a Favorite Set to User
curl -H "Authorization: Bearer bacea761b6021d1ce39a805d3c0c8ab9a64db0ac" -i -X PUT https://api.flashcardexchange.com/v2/users/5/favorites/145
| METHOD | URI | DESCRIPTION |
|---|---|---|
| PUT | /users/:USER_ID/favorites/SET_ID | Adds SET_ID as a favorite flashcard set for USER_ID. |
| RESPONSE |
|---|
|
{
"status":0,
"message":"Set id:145 has not been added"
}
{ "status":1, "message":"Set id:2186371 has been added to user:d908233545" } { "error":"invalid_request", "error_description":"Access token is not valid for specified user." } |
DELETE COMMANDS
Delete API calls will requires a read_write_delete scoped access token authorized by the creator of the set. A 400 response code will be returned if the user has not granted access to delete his or her items.
Delete a Favorite Set from User Profile
curl -H "Authorization: Bearer bacea761b6021d1ce39a805d3c0c8ab9a64db0ac" -i -X DELETE https://api.flashcardexchange.com/v2/users/5/favorites/145
| METHOD | URI | DESCRIPTION |
|---|---|---|
| DELETE | /users/:USER_ID/favorites/SET_ID | Removes SET_ID as a favorite flashcard set for USER_ID. |
| RESPONSE |
|---|
|
{
"status":1,
"message":"Set id:145 has been deleted"
}
{"status":1,"message":"Set id:2186371 has been deleted for user:d908233545"} {"status":0,"message":"Set id:2186371 has not been deleted for user:d908233545"} {"error":"invalid_request","error_description":"Access token is not valid for specified user."} |
Delete a Flashcard Set
curl -H "Authorization: Bearer bacea761b6021d1ce39a805d3c0c8ab9a64db0ac" -i -X DELETE https://api.flashcardexchange.com/v2/sets/145
| Method | URI | Description |
|---|---|---|
| DELETE | /sets/SET_ID | Deletes a flashcard set using the SET_ID value. |
| RESPONSE |
|---|
|
{
"status":1,
“message":"Set Id:145 was successfully deleted"
}
{"status":2,"message":"Set ID:2186371 was not successfully deleted"} |
Delete an Existing Card
curl -H "Authorization: Bearer bacea761b6021d1ce39a805d3c0c8ab9a64db0ac" -i -X DELETE https://api.flashcardexchange.com/v2/sets/2189691/cards/57016981
| METHOD | URI | DESCRIPTION |
|---|---|---|
| DELETE | /sets/:SET_ID/cards/:CARD_ID | Deletes a single flashcard using the CARD_ID value. |
| RESPONSE |
|---|
|
{
"status":1,
“message":"Card ID:57016981 was successfully deleted"
}
{"status":2,"message":"No Records Affected"} |
