Contents

Introduction

The Cram API provides a simple RESTful interface with lightweight JSON-formatted responses to use many of the Cram website features. This document provides information to developers on how to integrate with the Cram 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 sign up for a developer API Key. The key identifies your application to the Cram web service, and is used to track overall call usage.

Authentication

Cram 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://Cram.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.
User Authorizes Your Application

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.Cram.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.Cram.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.Cram.com/v2/search/sets?qstr=accounting

METHOD URI DESCRIPTION
GET /search/sets Search for all flashcard sets.
PARAMETERS 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 withoutimages 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.Cram.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.Cram.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.Cram.com/v2/sets/145

METHOD URI DESCRIPTION
GET /sets/:SETID Retrieve information on a particular set id.
PARAMETERS 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": "Examen 3: Micología Médica", "asunto": "Exámenes", "descripción": "Exámenes para mi", "url": "http://www.cram.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://fce-studymode.netdna-ssl.com/images/upload-flashcards/front/34/1/40614559_m.jpg",     "image_url": "http://fce-studymode.netdna-ssl.com/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": "Equipo de Basketball",     "image_front": "http://fce-studymode.netdna-ssl.com/images/upload-flashcards/front/34/1/40614559_m.jpg",     "image_url": "http://fce-studymode.netdna-ssl.com/images/upload-flashcards/front/34/1/40614559_m.jpg",     "image_hint": "http://fce-studymode.netdna-ssl.com/images/upload-flashcards/front/34/1/40614559_m.jpg",     "last_modified": "2012-09-26 15:30:42" } ] }]
{ "error":"invalid_request", "error_description":"Su búsqueda no trajo resultados. Por favor, trate de nuevo con un tema o palabra diferente." }
{ "error":"invalid_client", "error_description":"Las credenciales de los clientes son inválidas" }
curl -H "Authorization: Bearer c9da44d5662d8d10c40495357633e8c5e24b4851" -i -X GET https://api.Cram.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.Cram.com/v2/sets?id=145,225,2175839

METHOD URI DESCRIPTION
GET /sets View multiple sets at once.
PARAMETERS OPTIONAL DESCRIPTION
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": "Examen 3: Micología Médica",       "subject": "Exámenes",       "description": "Exámenes para mi",       "url": "http://www.cram.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://fce-studymode.netdna-ssl.com/images/upload-flashcards/front/34/1/40614559_m.jpg",           "image_url": "http://fce-studymode.netdna-ssl.com/images/upload-flashcards/front/34/1/40614559_m.jpg",           "image_hint": "http://fce-studymode.netdna-ssl.com/images/upload-flashcards/front/34/1/40614559_m.jpg",           "last_modified": "2012-09-26 15:30:42"        },           "card_id": "235",           "front": "Houston",           "back": "Cohetes",           "hint": "Equipo de Basketball",           "image_front": null,           "image_url": null,           "image_hint": null,           "last_modified": "2012-09-26 15:30:42"         }                ] }, {       "set_id": "100",       "user_id": "34",       "title": "Examen 3: Micología Médica",       "subject": "Exams",       "description": "Exámenes para mi",       "url": "http://www.cram.com/cards/Exam-3-Medical-Mycology-2188349",       "card_count": "113",       "lang_front": "en",       "lang_back": "es",       "lang_hint": "es",       "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://fce-studymode.netdna-ssl.com/images/upload-flashcards/front/34/1/40614559_m.jpg",           "image_url": "http://fce-studymode.netdna-ssl.com/images/upload-flashcards/front/34/1/40614559_m.jpg",           "image_hint": "http://fce-studymode.netdna-ssl.com/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": "Equipo de Basquetball",           "image_front": "http://fce-studymode.netdna-ssl.com/images/upload-flashcards/front/34/1/40614559_m.jpg",           "image_url": "http://fce-studymode.netdna-ssl.com/images/upload-flashcards/front/34/1/40614559_m.jpg",           "image_hint": "http://fce-studymode.netdna-ssl.com/images/upload-flashcards/front/34/1/40614559_m.jpg",           "last_modified": "2012-09-26 15:30:42"         }                ]   } ] Si no se devuelve coincidencias de Ids o fechas modificadas. { "error":"invalid_request", "error_description":"Su búsqueda no produjo resultados. Por favor, intente nuevamente con una búsqueda diferente." }

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.Cram.com/v2/users/doug

METHOD URI DESCRIPTION
GET /users/:USERNAME Retrieve a user profile.
PARAMETERS OPTIONAL DESCRIPTION
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": "Examen 3: Micología Médica",       "subject": "Examenes",       "descripción": "Exámenes para mi",       "url": "http://www.cram.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": "Examen 3: Micología Médica",       "subject": "Exámenes",       "descripción": "Exámenes para mi",       "url": "http://www.cram.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": "Examen 3: Micología Médica",       "subject": "Exámenes",       "description": "Exámenes para mi",       "url": "http://www.cram.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": "Examen 3: Micología Médica",       "subject": "Exámenes",       "description": "Exámenes para mi",       "url": "http://www.cram.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.Cram.com/v2/users/doug/favorites

METHOD URI DESCRIPTION
GET /users/:USERNAME/favorites Retrieve the user’s list of favorites sets.
PARAMETERS OPTIONAL DESCRIPTION
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.Cram.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://fce-studymode.netdna-ssl.com/images/upload-flashcards/front/34/1/40614559_m.jpg",           "image_url": "http://fce-studymode.netdna-ssl.com/images/upload-flashcards/front/34/1/40614559_m.jpg",           "image_hint": "http://fce-studymode.netdna-ssl.com/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://fce-studymode.netdna-ssl.com/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.Cram.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://fce-studymode.netdna-ssl.com/images/upload-flashcards/front/34/1/40614559_m.jpg",           "image_url": "http://fce-studymode.netdna-ssl.com/images/upload-flashcards/front/34/1/40614559_m.jpg",           "image_hint": "http://fce-studymode.netdna-ssl.com/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.Cram.com/v2/users/doug/studied

METHOD URI DESCRIPTION
GET /users/:USERNAME/studied Retrieve the user’s list of studied tests.
PARAMETERS OPTIONAL DESCRIPTION
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.Cram.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://fce-studymode.netdna-ssl.com/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.Cram.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.Cram.com/v2/users/doug/sets

METHOD URI DESCRIPTION
GET /users/:USERNAME/sets retrieve user’s list of sets
PARAMETERS OPTIONAL DESCRIPTION
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.Cram.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.Cram.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[]=Cram.com/Users/dougngo/Downloads/logo4.jpeg" -F "image_data[]=Cram.com/Users/dougngo/Downloads/rotatetrans.png" https://api.Cram.com/v2/images

METHOD URI DESCRIPTION
POST /images Upload images to Cram.
PARAMETERS OPTIONAL - TYPE DESCRIPTION
image_data[] N - array required parameter
RESPONSE
{ "images": [ {     "id":"lqylpQ==",     "url":"http://fce-studymode.netdna-ssl.com/images/upload-flashcards/5/trans_test.png }, {    "id":"lqylpg==",    "url":"http://fce-studymode.netdna-ssl.com/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.Cram.com/v2/sets

Permissions

Creating a set requires a read_write_delete scoped access token authorized by a user.

METHOD URI DESCRIPTION
POST /sets Creates a flashcard set.
PARAMETERS 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.Cram.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.Cram.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.Cram.com/v2/sets/2189691/cards

METHOD URI DESCRIPTION
POST /sets/:ID/cards Add card to an existing set.
PARAMETERS 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.Cram.com/v2/sets/145

METHOD URI DESCRIPTION
POST /sets/:ID/ Modify data to an existing set.
PARAMETERS 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.Cram.com/v2/sets/2189691/cards/57

METHOD URI DESCRIPTION
POST /sets/:ID/cards/CARD_ID Modify data to an existing set.
PARAMETERS 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
{ "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.Cram.com/v2/users/5/favorites/145

METHOD URI DESCRIPTION
POST /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.Cram.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.Cram.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.Cram.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"}