API Documentation

This documentation is intended mostly for programmers and advanced users who wish to access Memjogger with their own programs. If you are just looking for help on how to use Memjogger, you should propably start at the main help page.

 

  • 1. Introduction

    Memjogger exposes an API that allows every user of the service to perform most of the actions that are possible through the web interface.

    The API uses HTTP protocol as it's transport layer.

    All examples of API calls included in this documentation uses cURL as a tool for sending HTTP requests. They are in a form of

    cURL command Content of an HTTP request made Content of an HTTP response

    You don't need to know anything about cURL to make use of these examples. cURL commands are here only for your convenience - you can copy & paste them to your console to make those requests by yourself (you will have to substitute the token with your own though).

    Below is a (very) short description of the cURL options used in the documentation:

    • -X - request type (POST, GET etc.)
    • -H - request headers
    • -d - content of a request body

  • 2. Accessing the API

    Memjogger API is accessible by sending HTTP requests to resources under memjogger.com/api.

    For GET requests params are passed in the query string. For other types of requests they are sent in the body of the request in the JSON format.

    All responses are in JSON with few exceptions specified below (like for data export requests).

  • 3. Authentication

    To use the API you must first obtain authentication token by logging in:

    curl -X POST -d '{"email": "my@email.com", "passwd": "mypasswd"}' memjogger.com/api/user/login POST /api/user/login HTTP/1.1 Host: memjogger.com {"email": "my@email.com", "passwd": "mypasswd"} HTTP/1.1 200 OK {"token": "239e2d1739db436be2eb711b688e06d0"}

    The returned token is then used in all subsequent requests as a way of authenticating the sender.

    It can be attached in a query string (for all kinds of requests):

    /api/card/12?token=239e2d1739db436be2eb711b688e06d0

    It can also be passed as a value of an HTTP header X-Memjogger-Token:

    X-Memjogger-Token: 239e2d1739db436be2eb711b688e06d0

    The examples that follows all use the second method.

  • 4. Handling Response

    • 4.1. Response HTTP Codes

      Every API call results in a response with one of the following HTTP status codes:

      • 200 OK - request handled successfully
      • 400 Bad Request - the request body is not in JSON format
      • 401 Unauthorized - missing or invalid authentication token or login credentials
      • 403 Forbidden authenticated user has no permission to perform a given request
      • 404 Not Found - operation on non existing object requested
      • 405 Method Not Allowed - request method not supported by that resource
      • 422 Unprocessable Entity - content of the request is in correct format but is invalid for some other reason
      • 500 Internal Server Error - other error; try to wait for a minute and resend your request

    • 4.2. Application Specific Error Codes

      The response body may contain additional data apropriate for a given request and response type.

      In particular, some error responses (i.e. with status code other than 200) contain errors attribute which is a list of application specific codes indicating reasons the request has failed, e.g.:

      {"errors": ["card_set_already_exists"]}

      More details about application specific error codes and other content of a response body are specified in the next sections of this documentation.

      Requests Requiring Trial or Active Subscription

      Some operations, in order to be performed, require the authenticated user to be during his trial period or to have an active subscription. For those requests, if the user doesn't meet these criteria, the application error code trial_expired or sub_expired will be returned (depending on whether or not he had an active subscription in the past) inside the 403 Forbidden HTTP response.

      Those operations are marked in the documentation as follows:

      [trial or subscription required].

      An example of such an operation would be the creation of a new flashcard set. To learn more about trial period and subscriptions, consult the Free Trial page and the Terms of Service. Those constraints regarding API calls generally match the constraints in functionality of the Memjogger web application specified in the ToS ("the Service").

  • 5. Data Types and Other Conventions

    Date Format

    All dates are send and received in the format of %Y-%m-%d. e.g. 2012-03-01.

  • 6. API Calls

    • 6.1 Flashcard Sets

      Fetch Flashcard Sets
      GET /api/cardset
      Parameters
      client_date
      optional date - date relative to which the value exam_count.old of each flashcard set will be computed (see below); if not specified, the attribute exam_count will not be filled at all
      Request / Response
      curl -X GET -H "X-Memjogger-Token: 239e2d1739db436be2eb711b688e06d0" memjogger.com/api/cardset GET /api/cardset HTTP/1.1 Host: memjogger.com X-Memjogger-Token: 239e2d1739db436be2eb711b688e06d0 HTTP/1.1 200 OK { "card_sets": [ { "id": 1, "name": "Some name", "exam_count": { "2012-03-01": 6, "2012-03-02": 1, "old": 1 } }, { "id": 2, "name": "Some other name", "exam_count": {} } ] }
      card_sets
      an array of flashcard sets
      card_set.exam_count
      • maps dates to a number of repeats scheduled for a given date in this flashcard set
      • keys are of type date or of a special value 'old' which represents aggregated count for all repeats that have been scheduled for a date preceding current date
      • seperate counts for dates older than current date are not sent (they are contained in the aggregate only)
      • See also client_date param in a request description
      Possible Error Codes
      [?]
      invalid_date_format
      Fetch a Single Flashcard Set
      GET /api/cardset/:id
      Parameters
      client_date
      optional date - see: Fetch Flashcard Sets
      Request / Response
      curl -X GET -H "X-Memjogger-Token: 239e2d1739db436be2eb711b688e06d0" memjogger.com/api/cardset/1 GET /api/cardset/1 HTTP/1.1 Host: memjogger.com X-Memjogger-Token: 239e2d1739db436be2eb711b688e06d0 HTTP/1.1 200 OK { "card_set": { "id": 1, "name": "Some name", "exam_count": { "2012-03-01": 6, "2012-03-02": 1, "old": 1 } } }
      card_set.exam_count
      See: Fetch Flashcard Sets
      Possible Error Codes
      [?]

      See: Fetch Flashcard Sets

      Create a Flashcard Set
      [trial or subscription required] POST /api/cardset {"name": "Some name"}
      Parameters
      name
      required string - name of a new flashcard set
      Request / Response
      curl -X POST -H "X-Memjogger-Token: 239e2d1739db436be2eb711b688e06d0" -d '{"name": "Some name"}' memjogger.com/api/cardset POST /api/cardset HTTP/1.1 Host: memjogger.com X-Memjogger-Token: 239e2d1739db436be2eb711b688e06d0 {"name": "Some name"} HTTP/1.1 200 OK {"id": 836}
      id
      id of a created flashcard set
      Possible Error Codes
      [?]
      card_set_name_invalid
      name should be between 1 and 25 characters long
      card_set_already_exists
      name should be unique
      Update a Flashcard Set
      [trial or subscription required] PUT /api/cardset/:id {"name": "Some other name"}
      Parameters
      name
      required string - name of a new flashcard set
      Request / Response
      curl -X PUT -H "X-Memjogger-Token: 239e2d1739db436be2eb711b688e06d0" -d '{"name": "Some name"}' memjogger.com/api/cardset/1 PUT /api/cardset/1 HTTP/1.1 Host: memjogger.com X-Memjogger-Token: 239e2d1739db436be2eb711b688e06d0 {"name": "Some other name"} HTTP/1.1 200 OK
      Possible Error Codes
      [?]

      See: Create a new Flashcard Set

      Delete a Flashcard Set
      [trial or subscription required] DELETE /api/cardset/:id
      Request / Response
      curl -X DELETE -H "X-Memjogger-Token: 239e2d1739db436be2eb711b688e06d0" memjogger.com/api/cardset/1 DELETE /api/cardset/1 HTTP/1.1 Host: memjogger.com X-Memjogger-Token: 239e2d1739db436be2eb711b688e06d0 HTTP/1.1 200 OK

    • 6.1 Flashcards

      Fetch Flashcards From a Flashcard Set
      GET /api/cardset/:id/cards
      Parameters
      l
      optional integer - limit the number of results to l; defaults to 10
      p
      optional integer - pagination page number; defaults to 1
      client_date
      optional date - send only cards that have a repeat scheduled for a give date
      export
      optional string, one of {csv, xml} - return flashcards in a format specified; the response body will contain text in a CSV or XML accordingly (not JSON)
      Request / Response
      curl -X GET -H "X-Memjogger-Token: 239e2d1739db436be2eb711b688e06d0" memjogger.com/api/cardset/1/cards?l=10&p=1 GET api/cardset/1/cards?l=10&p=1 HTTP/1.1 Host: memjogger.com X-Memjogger-Token: 239e2d1739db436be2eb711b688e06d0 HTTP/1.1 200 OK { "cards": [ { "id": 12 "q": "Some question", "a": "Some answer", "next_exam_date": "2012-04-12", "card_set_id": 1 }, { "id": 13 "q": "Some other question", "a": "Some other answer", "next_exam_date": "2012-05-12", "card_set_id": 1 } ], "count": 2, "pcount": 1, "pnum": 1 }
      cards
      array of flashcards
      count
      total number of flashcards in the flashcard set that meets criteria specified in the query
      pcount
      total number of pagination pages available given parameters specified in the query
      pnum
      number of the pagination page returned in this response, i.e. it is the pnum page out of pcount pages
      Possible Error Codes
      [?]
      invalid_date_format
      Fetch a Single Flashcard
      GET /api/card/:id
      Request / Response
      curl -X GET -H "X-Memjogger-Token: 239e2d1739db436be2eb711b688e06d0" memjogger.com/api/card/12 GET /api/card/12 HTTP/1.1 Host: memjogger.com X-Memjogger-Token: 239e2d1739db436be2eb711b688e06d0 HTTP/1.1 200 OK { "card": { "id": 12 "q": "Some question", "a": "Some answer", "next_exam_date": "2012-04-12", "card_set_id": 1 } }
      Create a Flashcard
      [trial or subscription required] POST /api/cardset/:id/cards {"q": "Some question", "a": "Some answer", client_date: "2012-03-10"}
      Parameters
      q
      required string
      a
      required string
      client_date
      optional date - date that the repeats scheduling algorithm should use as a current date in the client time zone; defaults to the current date in the server time zone;

      Note: Although this parameter is optional, the client may be in a different time zone than the server, so using server time zone may lead to some minor inconsistencies. For this reason, in general, you should always send this parameter and set its value to the current date in the client time zone.
      Request / Response
      curl -X POST -H "X-Memjogger-Token: 239e2d1739db436be2eb711b688e06d0" -d '{"q": "Some question", "a": "Some answer", client_date: "2012-03-10"}' memjogger.com/api/cardset/1/cards POST /api/cardset/1/cards HTTP/1.1 Host: memjogger.com X-Memjogger-Token: 239e2d1739db436be2eb711b688e06d0 {"q": "Some question", "a": "Some answer", client_date: "2012-03-10"} HTTP/1.1 200 OK {"id": 836, "next_exam_date": "2012-03-11"}
      id
      id of a created flashcard
      next_exam_date
      date of a next scheduled repeat
      Possible Error Codes
      [?]
      empty_field
      question or answer field missing or empty
      question_too_long
      question field is too long (max is 10000 characters)
      answer_too_long
      answer field is too long (max is 10000 characters)
      Update a Flashcard
      [trial or subscription required] PUT /api/card/:id {"q": "Some other question", "a": "Some other answer"}
      Parameters
      q
      required string
      a
      required string
      Request / Response
      curl -X PUT -H "X-Memjogger-Token: 239e2d1739db436be2eb711b688e06d0" -d '{"q": "Some other question", "a": "Some other answer"}' memjogger.com/api/card/1 PUT /api/card/1 HTTP/1.1 Host: memjogger.com X-Memjogger-Token: 239e2d1739db436be2eb711b688e06d0 {"q": "Some other question", "a": "Some other answer"} HTTP/1.1 200 OK
      Possible Error Codes
      [?]

      See: Create a new Flashcard

      Delete a Flashcard
      [trial or subscription required] DELETE /api/card/:id
      Request / Response
      curl -X DELETE -H "X-Memjogger-Token: 239e2d1739db436be2eb711b688e06d0" memjogger.com/api/card/1 DELETE /api/card/1 HTTP/1.1 Host: memjogger.com X-Memjogger-Token: 239e2d1739db436be2eb711b688e06d0 HTTP/1.1 200 OK
      Mark an Answer
      POST /api/card/:id/mark {"mark": "3", client_date: "2012-03-10"}
      Parameters
      mark
      required on of {0,1,2,3,4,5} - a mark
      client_date
      optional date - date that the repeats scheduling algorithm should use as a current date in the client time zone; defaults to the current date in the server time zone;

      Note: Although this parameter is optional, the client may be in a different time zone than the server, so using server time zone may lead to some minor inconsistencies. For this reason, in general, you should always send this parameter and set its value to the current date in the client time zone.
      Request / Response
      curl -X POST -H "X-Memjogger-Token: 239e2d1739db436be2eb711b688e06d0" -d '{"mark": "3", client_date: "2012-03-10"}' memjogger.com/api/card/1/mark POST /api/card/1/mark HTTP/1.1 Host: memjogger.com X-Memjogger-Token: 239e2d1739db436be2eb711b688e06d0 {"mark": "3", client_date: "2012-03-10"} HTTP/1.1 200 OK {"next_exam_date": "2012-03-20"}
      next_exam_date
      date of a next scheduled repeat
      Possible Error Codes
      [?]
      invalid_mark
      invalid_date_format

  • 7. API Wrappers

    Available wrappers:

More Help

Not using Memjogger yet?

Stay in touch