API

The Plancake API makes it easy for developers to interact with their tasks and make new and interesting applications.
Please, let us know once you develop an application, so that we may list it on our Services section.

The current version of the API is 5.



Requirements - API key

We made the Plancake API as simple-to-use as possible because we want to encourage as many developers as possible to write awesome applications for Plancake and to share their achievements with us.
The requirements for starting with the development are:

During your development, you will be assisted by the Head of Development, so that you can get an answer to any of your questions, and any issue that may arise will be resolved quickly and without the frustration that sometimes comes when using an API.

If you have Plancake installed on your server, you don't need to contact us to have an API Key - you can use it straightaway - you just need to add a record in the pc_api_app table (the api_key can be 43e907a39d890d45c5effcd9b281e357f7ac16a2, the api_secret can be rNZsYVuyQldivY5v and the user_id is your id in the pc_user table).

get your API key and start developing on Plancake

 

Overview

The Plancake API consists of a set of callable methods. The arguments and responses for each method are listed in the Methods section.

To perform an action using the Plancake API, send a request which includes a method and some parameters to a specific URL. A response will then be sent back to you.

About the request:

About the response:

Error codes

If an error occurs while trying to serve your request, you will get back something like this: {"error":23} Here is the list of the possible general error codes:

Signing requests

Each request needs to include an extra parameter (at the end of it) carrying the signature of the request. That is needed to make sure the application using the API is really the one it claims to be (through the API key parameter).

Following is the process to obtain the signature to append to the request.

Let's suppose we want to sign this request:

http://www.plancake.com/api.php/getLists/?token=kjer39jhewjh9349Rj49dhj34sjRS43jEdf&list_id=20&sort_by=date&filter=completed
  1. Sort your parameters by key name (excluding the token), so that: list_id=20 sort_by=date filter=completed api_ver=5 becomes: api_ver=5 filter=completed list_id=20 sort_by=date
  2. Construct a string with all key/value pairs concatenated together: api_ver5filtercompletedlist_id20sort_bydate
  3. Append the API secret to the previous string (let's suppose the secret is XXXXXXXXXXXXXXXX): api_ver5filtercompletedlist_id20sort_bydateXXXXXXXXXXXXXXXX
  4. Prepend the name of the method you are invoking (i.e. getTasks)): getTasksapi_ver5filtercompletedlist_id20sort_bydateXXXXXXXXXXXXXXXX
  5. Calculate the MD5 hash of this string: md5('getTasksapi_ver5filtercompletedlist_id20sort_bydateXXXXXXXXXXXXXXXX') -> a790cf44a87838b7bf039a8b742640d9
  6. a790cf44a87838b7bf039a8b742640d9 is the sig parameter you need to append to that example request
The full request would be (check the end of it):
http://www.plancake.com/api.php/getLists/?token=kjer39jhewjh9349Rj49dhj34sjRS43jEdf&list_id=20&sort_by=date&filter=completed&api_ver=5&sig=a790cf44a87838b7bf039a8b742640d9

Authentication

The authentication process is all about getting a token from the system via the getToken method.

You will need to include that token to all the following requests (together with the signature). That means the getToken request is the first you need to do, right at the start of the communication between your application and Plancake.

API Kits

Thanks to the API kits, you will be able to use the Plancake API without worrying about authentication protocols and signing requests; you will just need to call regular methods (i.e. gestLists()) and use the return values that would be regular arrays, collections or objects. Feel free to port the API kit to other languages. In that case, please, let us know so that we can add them to this listing. For doing that, you can start having a look at the packages already available and do almost a "direct translation".

Rate Limiting for personal API key

Each key is allowed to make 200 requests and consume 700 KB of download bandwidth per hour.
If you cache your data properly, this should be more than enough for your application. Particularly, you should not request a new token for every request but you should cache it and use it until you get an invalid token error (a token lasts 6 hours).

If you go behind those limits, any further requests will generate an error message until the requests and bandwidth per hour drop below the limits.

Plancake reserves the right to impose stricter rate limiting for some applications if we think those are using disproportionate amount of our resources because of bad design decisions.

Changelog

Methods

Method getToken

This is the first step for starting the communication with the Plancake platform. The token you get at this stage must be included to all following requests.
You should request this method over HTTPS.

A token is valid for 6 hours only.
When the token becomes invalid, you will get an error as a response. At that point, you can call this method again.

You don't need to deal with this method if you use one of our API kits.

parameters
  • token (required) - empty, just for consistency with the other methods
  • api_key (required) - the key to identify your application - you can find it on your Settings page
  • api_ver (required) - the version the client is intending to use - the current one is 5
  • user_key (required) - the identifier to identify your account - you can find it on your Settings page
  • user_email (optional) - ignore it if you are using a personal API key
  • user_pwd (optional) - ignore it if you are using a personal API key
  • extra_info (optional) - any extra info we want to submit while requesting a token (i.e.: version of the client application)
  • sig (required) - the signature
return
  • token - the token
  • api_ver - API version
request example
http://www.plancake.com/api.php/getToken/?token=&api_key=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&api_ver=5&sig=1234567890ABCDEF1234567890ABCDEF
response example
{"token":"kjer39jhewjh9349Rj49dhj34sjRS43jEdf","api_ver":"1"}

Method getServerTime

parameters
  • token (required)
  • api_ver (required) - the version the client is intending to use - the current one is 5
  • sig (required) - the signature
return
  • time - the current UNIX timestamp on the server
request example
http://www.plancake.com/api.php/getToken/?token=o0OieR4To0OieR4To0OieR4To0OieR4T&api_ver=5&sig=1234567890ABCDEF1234567890ABCDEF
response example
{"time":"1234567890"}

Method getUserSettings

parameters
  • token (required)
  • api_ver (required) - the version the client is intending to use - the current one is 5
  • sig (required) - the signature
return
  • timezone - described by a few parameters:
    • description
    • offset - in minutes from UTC
    • dst - whether the country observe DST
  • date_format - it can be either m-d-Y, d-m-Y or Y-m-d
  • time_format - it can be either 0 or 1 for 5:00pm or 17:00 respectively
  • dst_active - whether DST is active in the user's settings
  • week_start - it can be either 0 or 1 for Sunday or Monday respectively
  • lang - 2-char string representing the language the user has selected on Plancake Settings (i.e.: it)
  • client_lang_string - the language string coming from the client request (i.e.: en-GB,en)
  • is_premium - whether the user is a Premium
  • email - the email address of the user
request example
http://www.plancake.com/api.php/getUserSettings/?token=kjer39jhewjh9349Rj49dhj34sjRS43jEdf&api_ver=5&sig=1234567890ABCDEF1234567890ABCDEF
response example
{"timezone":{"description":"(00:00) GMT: Dublin, Edinburgh, Lisbon, London","offset":0,"dst":1},"date_format":"d-m-Y","time_format":1,"dst_active":1,"week_start":1,"lang":"it","client_lang_string":"it-IT,it"}

Method getLists

Returns the set of all the lists sorted the way they are on the Web interface.
The Inbox is first, the Todo list is second and then the rest.
parameters
  • token (required)
  • api_ver (required) - the version the client is intending to use - the current one is 5
  • from_ts (optional) - to return only the lists created or edited since this timestamp
  • to_ts (optional) - to return only the lists created or edited till this timestamp
  • sig (required) - the signature
return
The set of lists. For each list, these keys are returned:
  • id - this integer value can be very big
  • name
  • sort_order - Inbox and Todo lists have 0 as sort_order, the user lists should be displayed in ascenting sort order
  • is_inbox - whether the list is the Inbox (the other default list, the Todo list will be the one where is_inbox=0 and sort_order=0)
  • is_header - whether the list is a header
  • updated_at
  • created_at
request example
http://www.plancake.com/api.php/getLists/?token=kjer39jhewjh9349Rj49dhj34sjRS43jEdf&from_ts=1234562890&to_ts=1234567899&api_ver=5&sig=1234567890ABCDEF1234567890ABCDEF
response example
{"lists":[{"id":3344,"name":"Inbox","sort_order":0,"is_inbox":1,"is_header":0,"updated_at":1234567890,"created_at":1234567890},{"id":3345,"name":"Todo","sort_order":0,"is_inbox":0,"is_header":0,"updated_at":1234567890,"created_at":1234567890},{"id":3390,"name":"waiting for","sort_order":1,"is_inbox":0,"is_header":0,"updated_at":1234567890,"created_at":1234567890}]}

Method getDeletedLists

This can be useful during synchronization (in that case, to call before getLists).
parameters
  • token (required)
  • api_ver (required) - the version the client is intending to use - the current one is 5
  • from_ts (required) - timestamp to retrieve the deleted lists since (i.e.: the latest synchronization timestamp)
  • to_ts (required) - timestamp to retrieve the deleted lists till (i.e.: the latest synchronization timestamp)
  • sig (required) - the signature
return
  • list_ids - list of deleted list IDs
request example
http://www.plancake.com/api.php/getDeletedLists/?token=kjer39jhewjh9349Rj49dhj34sjRS43jEdf&from_ts=1234561890&to_ts=1234567899&api_ver=5&sig=1234567890ABCDEF1234567890ABCDEF
response example
{"list_ids":[43,234,3454,48530]}

Method getTags

parameters
  • token (required)
  • api_ver (required) - the version the client is intending to use - the current one is 5
  • from_ts (optional) - to return only the tags created or edited since this timestamp
  • to_ts (optional) - to return only the tags created or edited till this timestamp
  • sig (required) - the signature
return
The set of tags. For each tag, these keys are returned:
  • id - this integer value can be very big
  • name
  • sort_order - tags returned in ascending order
request example
http://www.plancake.com/api.php/getTags/?token=kjer39jhewjh9349Rj49dhj34sjRS43jEdf&from_ts=1234561890&to_ts=1234567899&api_ver=5&sig=1234567890ABCDEF1234567890ABCDEF
response example
{"tags":[{"id":45356,"name":"home","sort_order":1},{"id":545356,"name":"computer","sort_order":2}]}

Method getDeletedTags

This can be useful during synchronization (in that case, to call before getTags).
parameters
  • token (required)
  • api_ver (required) - the version the client is intending to use - the current one is 5
  • from_ts (required) - timestamp to retrieve the deleted tags since (i.e.: the latest synchronization timestamp)
  • to_ts (required) - timestamp to retrieve the deleted tags till (i.e.: the latest synchronization timestamp)
  • sig (required) - the signature
return
  • tag_ids - list of deleted tag IDs
request example
http://www.plancake.com/api.php/getDeletedTags/?token=kjer39jhewjh9349Rj49dhj34sjRS43jEdf&from_ts=1234561890&to_ts=1234567899&api_ver=5&sig=1234567890ABCDEF1234567890ABCDEF
response example
{"tag_ids":[43,234,3454,48530]}

Method getRepetitionOptions

Returns all the available repetition options you can associate with a repetitive task.
This entries are not very likely to change and, anyway, we will try to preserve back-compatibility.

In the Plancake internal representation, each repetitive task is linked to one of these options via its repetition_id field (see the getTasks method).
For example, a task that repeats every 2 weeks will be associated with the repetition option with id=12 and whose label is every [select later] weeks. The repetition_param for this task has to be 2.
To display the correct repetition string for the task you just need to replace the [select later] bit of the label with 2.

The only case in which getting a repetition string is not that easy is in the case of the repetition on many weekdays (id:34, label:repeat weekly on some weekdays [select later], special: selected_wkdays).
In that case, the repetition_param is the decimal representation of a binary number you can get as follows.
Let's suppose a task repeats on Mondays, Thursdays and Fridays.

SundayMondayTuesdayWednesdayThursdayFridaySaturday
0100110
The binary representation is 100110, which correspond to 38 in decimal base.
That means that task is going to have repetition_id=34 and repetition_param=38.
N.B.: the first element of the table has to be always Sunday, regardless the user setting of the first day of the week.

parameters
  • token (required)
  • api_ver (required) - the version the client is intending to use - the current one is 5
  • from_ts (optional) - to return only the entries created or edited since this timestamp
  • to_ts (optional) - to return only the entries created or edited till this timestamp
  • sig (required) - the signature
return
Returns a collection of object. Each object has got these keys:
  • id
  • label - the description to show on the UI (i.e.: a combo box, as for the Web interface)
  • special - whether this option must be treated in a special way - it is usually blank
  • needs_param - whether the expression needs a numerical parameter (every Sunday does not need it but every [select later] weeks does)
  • is_param_cardinal - in the case the item needs a parameter, will it be cardinal (1, 2, 3, ... as in every 3 weeks) or not (1st, 2nd, 3th, ... as in every month on the 4th Sunday)?
  • min_param - the minimum value of the parameter (0 if not applicable)
  • max_param - the maximum value of the parameter (0 if not applicable)
  • ical_rrule_template - the corresponding Ical Rrule where the parameter, if any, is replaced by an X (i.e.: FREQ=WEEKLY;BYDAY=X)
  • sort_order - lower sort order should be on top
  • has_divider_below - whether it makes sense to add a divider after this item (as for the combo box on the Web interface)
request example
http://www.plancake.com/api.php/getRepetitionOptions/?token=kjer39jhewjh9349Rj49dhj34sjRS43jEdf&api_ver=5&sig=1234567890ABCDEF1234567890ABCDEF
response example
{"repetitions":[{"id":1,"label":"every Sunday","needs_param":0,"is_param_cardinal":0,"min_param":0,"max_param":0,"ical_rrule_template":"FREQ=WEEKLY;BYDAY=SU","sort_order":1,"has_divider_below":0},{"id":16,"label":"every [select later] years","needs_param":1,"is_param_cardinal":1,"min_param":1,"max_param":30,"ical_rrule_template":"FREQ=YEARLY;INTERVAL=X","sort_order":16,"has_divider_below":1}]}

Method getTasks

This is a very flexible method. Depending on the optional input you may pass, the result can have different meanings.
What does stay the same is the type of the result which is a collection of tasks (it could be just one if you pass task_id).

In general, tasks with due date are returned first (sorted by due date, closest due dates first) and then tasks without due date (higher sort order should be on top, that is tasks should be displayed in descending sort order).

parameters
  • token (required)
  • api_ver (required) - the version the client is intending to use - the current one is 5
  • from_ts (optional) - to return only the tasks created or edited since this timestamp
  • to_ts (optional) - to return only the tasks created or edited till this timestamp
  • task_id (optional) - to return only a specific task - if specified, any other parameter gets ignored
  • list_id (optional) - to return only tasks within a list
  • tag_id (optional) - to return only tasks labelled with a certain tag
  • completed (optional, default 0) - whether to return only the completed tasks or only the non-completed tasks (you can't retrieve both the types in the same request)
  • only_with_due_date (optional, default 0) - whether to return only the tasks with due date
  • only_without_due_date (optional, default 0) - whether to return only the tasks without due date
  • only_due_today_or_tomorrow (optional, default 0) - whether to return only the tasks due today and tomorrow (it returns also overdue tasks)
  • only_starred (optional, default 0)
  • by_date (optional, default '') - if you pass a day in the format yyyy-mm-dd (e.g.: 2011-12-25) only tasks scheduled for that day and the next 6 are returned (including multiple occurrences of recurrent tasks) - if specified, any other parameter gets ignored
  • search_query (optional, default '') - the query to search against (this supersedes any other parameter)
  • sig (required) - the signature
return
The set of tasks. For each task, these keys are returned:
  • id - this integer value can be very big
  • list_id
  • description
  • sort_order higher sort order should be on top
  • is_starred
  • is_header - whether the list is a header
  • due_date - in the yyyy-mm-dd format, if applicable
  • due_time - in the (H)Hmm 24h format (i.e.: 915, 1913), if applicable
  • repetition_id - an integer expressing the internal representation of the task repetition, if applicable - see the getRepetitionOptions method
  • repetition_param - an integer expressing the internal representation of the task repetition, if applicable - see the getRepetitionOptions method
  • repetition_ical_rrule - besides Plancake internal representation of repetitive tasks (expressed by the fields repetition_id and repetition_param) we provide a standard ical rrule expression (i.e.: FREQ=WEEKLY;BYDAY=MO,FR)
  • is_completed
  • is_from_system - whether the task has been sent by the Plancake team
  • attachment_filename - the attachment filename on Amazon S3
  • note - if applicable
  • extra - three-letter abbreviation for the day of the week (e.g.: Sun)
  • tags - comma-separated list of tag IDs, if applicable
  • updated_at
  • created_at
request example
http://www.plancake.com/api.php/getTasks/?token=kjer39jhewjh9349Rj49dhj34sjRS43jEdf&list_id=34244&only_with_due_date=1&completed=0&from_ts=1234561890&to_ts=1234567899&api_ver=5&sig=1234567890ABCDEF1234567890ABCDEF
response example
{"tasks":{"id":3454355,"list_id":94345,"description":"call Jack","sort_order":4,"is_header":0,"is_starred":0,"due_date":"2010-11-23","due_time":"1825","repetition_id":0,"repetition_param":0,"repetition_ical_rrule":"","is_completed":0,"is_from_system":0,"note":"","tags":"45345,45435","updated_at":1234567890,"created_at":1234567890}}

Method getDeletedTasks

This can be useful during synchronization (in that case, to call before getTasks).
parameters
  • token (required)
  • from_ts (required) - timestamp to retrieve the deleted tasks since (i.e.: the latest synchronization timestamp)
  • to_ts (required) - timestamp to retrieve the deleted tasks till (i.e.: the latest synchronization timestamp)
  • api_ver (required) - the version the client is intending to use - the current one is 5
  • sig (required) - the signature
return
  • task_ids - list of deleted task IDs
request example
http://www.plancake.com/api.php/getDeletedTasks/?token=kjer39jhewjh9349Rj49dhj34sjRS43jEdf&from_ts=1234561890&to_ts=1234567899&api_ver=5&sig=1234567890ABCDEF1234567890ABCDEF
response example
{"task_ids":[43,234,3454,48530]}

Method completeTask

parameters
  • token (required)
  • task_id (required)
  • baseline_due_date (optional) - in the yyyy-mm-dd format - if used, the system checks the current due date of the task is not further than this baseline (if provided) before completing the task: if the current due date is further, then the task has been already completed - this is a way to avoid the system to complete a repetitive task twice (causing the due date to be pushed back twice) if the user completes the same task in two different applications by mistake
  • api_ver (required) - the version the client is intending to use - the current one is 5
  • sig (required) - the signature
return
  • task_id - the ID of the task that has been completed
request example
http://www.plancake.com/api.php/completeTask/?token=kjer39jhewjh9349Rj49dhj34sjRS43jEdf&task_id=9830944&api_ver=5&sig=1234567890ABCDEF1234567890ABCDEF
response example
{"task_id":845937}

Method uncompleteTask

parameters
  • token (required)
  • task_id (required)
  • api_ver (required) - the version the client is intending to use - the current one is 5
  • sig (required) - the signature
return
  • task_id - the ID of the task that has been uncompleted
request example
http://www.plancake.com/api.php/uncompleteTask/?token=kjer39jhewjh9349Rj49dhj34sjRS43jEdf&task_id=9830944&api_ver=5&sig=1234567890ABCDEF1234567890ABCDEF
response example
{"task_id":845937}

Method addTask

Be aware the URL you request can't be very long. We recommend you don't request URL's longer than 2KB. If the note you intend to send is very long, consider using the setTaskNote method instead of specifying it with this request.
parameters
  • token (required)
  • descr (required) - the description of the task
  • api_ver (required) - the version the client is intending to use - the current one is 5
  • list_id (optional, default: the ID of the Inbox)
  • is_starred (optional, default 0)
  • is_header (optional, default 0) - whether the list is a header
  • due_date (optional) - in the yyyy-mm-dd format
  • due_time - in the (H)Hmm 24h format (i.e.: 915, 1913)
  • repetition_id (optional) - see the getRepetitionOptions method
  • repetition_param (optional) - see the getRepetitionOptions method
  • repetition_ical_rrule (optional) - rather than using the internal representation of repetitive tasks (via the repetition_id and repetition_param) you can use Ical Rrule (i.e: 'FREQ=WEEKLY;BYDAY=SA')
  • note (optional)
  • tag_ids (optional) - comma-separated list of tag IDs
  • sig (required) - the signature
return
  • task_id - the ID of the task that has been added - this integer value can be very big
request example
http://www.plancake.com/api.php/addTask/?token=kjer39jhewjh9349Rj49dhj34sjRS43jEdf&descr=Call+Jack+to+speak+about+deal&list_id=5&due_date=2010-11-23&due_time=2030&api_ver=5&sig=1234567890ABCDEF1234567890ABCDEF
response example
{"task_id":845937}

Method editTask

Be aware the URL you request can't be very long. We recommend you don't request URL's longer than 2KB. If the note you intend to send is very long, consider using the setTaskNote method instead of specifying it with this request.

The system will change only the fields you specify with this request.

parameters
  • token (required)
  • task_id (required)
  • api_ver (required) - the version the client is intending to use - the current one is 5
  • descr (optional) - the description
  • list_id (optional)
  • is_starred (optional, default 0)
  • is_header (optional) - whether the list is a header
  • due_date (optional) - in the yyyy-mm-dd format
  • due_time - in the (H)Hmm 24h format (i.e.: 915, 1913)
  • repetition_id (optional) - see the getRepetitionOptions method
  • repetition_param (optional) - see the getRepetitionOptions method
  • repetition_ical_rrule (optional) - rather than using the internal representation of repetitive tasks (via the repetition_id and repetition_param) you can use Ical Rrule (i.e: 'FREQ=WEEKLY;BYDAY=SA')
  • note (optional)
  • tag_ids (optional) - comma-separated list of tag IDs
  • sig (required) - the signature
return
  • task_id - the ID of the task that has been edited - this integer value can be very big
request example
http://www.plancake.com/api.php/editTask/?token=kjer39jhewjh9349Rj49dhj34sjRS43jEdf&task_id=3432345&list_id=5&due_date=2010-11-23&due_time=930&api_ver=5&sig=1234567890ABCDEF1234567890ABCDEF
response example
{"task_id":845937}

Method setTaskNote

This is the only method that requires a POST parameter.

It is for when the note for a task is very long and including it in the URL may create problems.

parameters
  • token (required)
  • task_id (required)
  • note (required) - to be sent as POST parameter
  • api_ver (required) - the version the client is intending to use - the current one is 5
  • sig (required) - the signature
return
  • task_id - the ID of the task that has been set the note for
request example
http://www.plancake.com/api.php/setTaskNote/?token=kjer39jhewjh9349Rj49dhj34sjRS43jEdf&task_id=343494554&api_ver=2&sig=1234567890ABCDEF1234567890ABCDEF
response example
{"task_id":845937}

Method deleteTask

parameters
  • token (required)
  • task_id (required)
  • api_ver (required) - the version the client is intending to use - the current one is 5
  • sig (required) - the signature
return
  • task_id - the ID of the task that has been deleted
request example
http://www.plancake.com/api.php/deleteTask/?token=kjer39jhewjh9349Rj49dhj34sjRS43jEdf&task_id=9830944&api_ver=5&sig=1234567890ABCDEF1234567890ABCDEF
response example
{"task_id":845937}

Method sync

This is the method to call when you want to synchronize your local database with the central Plancake database.
parameters
  • token (required)
  • local_changes (required) - set of new objects changed locally (json representation)
  • api_ver (required) - the version the client is intending to use - the current one is 5
  • sig (required) - the signature
return
  • changes - a CSV of keys representing the entities that has changed since the timestamp passed as parameter. The keys are: serverTime, tasks, lists, tags, repetitions, deletedTasks, deletedLists, deletedTags
request example
http://www.plancake.com/api.php/sync/?token=kjer39jhewjh9349Rj49dhj34sjRS43jEdf&local_changes=this_is_json_representation_of_objects&api_ver=5&sig=1234567890ABCDEF1234567890ABCDEF
response example
Too complicated - please dump the response

Method whatHasChanged

Deprecated: please use the sync method instead.
parameters
  • token (required)
  • from_ts (required) - timestamp to retrieve the items since (i.e.: the latest synchronization timestamp)
  • to_ts (required) - timestamp to retrieve the items till (i.e.: the latest synchronization timestamp)
  • api_ver (required) - the version the client is intending to use - the current one is 5
  • sig (required) - the signature
return
  • changed - a CSV of keys representing the entities that has changed since the timestamp passed as parameter. The possible keys are: tasks, lists, tags, repetitions, deletedTasks, deletedLists, deletedTags
request example
http://www.plancake.com/api.php/whatHasChanged/?token=kjer39jhewjh9349Rj49dhj34sjRS43jEdf&from_ts=1234561890&to_ts=1234567899&api_ver=5&sig=1234567890ABCDEF1234567890ABCDEF
response example
{"changed":["lists","deletedTasks","deletedTags"]}

Method voiceMemoRecorder

This is a special method that doesn't require the authentication protocol (using token and signature) as all the other ones - it can be called directly.
It requires HTTPS.
Its endpoint is: https://www.plancake/api.php/voiceMemoRecorder/
It is also special in that its response is just a text line, no JSON. The MIME type of the response is text/html.
parameters
  • api_ver (required) - the version the client is intending to use - the current one is 5
  • api_key (required) -
  • api_secret (required) -
  • user_email (required) - the Plancake email address of the user
  • message -
  • attachment -
As usual, api_key and api_secret will be provided by the Plancake team.
Either message or attachment should be passed.
In your request, you can use either POST or GET (although you should use POST if you send attachment).
return
As already said, the response is plain text, on one line. The response can be one of these 5 strings:
  1. ERROR-0
  2. ERROR-1
  3. ERROR-2
  4. OK
  5. OK-x-y
Some comments on each of the types of response:
  1. returned when an internal error happens, for example, if you don't pass all the mandatory parameters - useful for debugging
  2. returned when the user_email input parameter doesn't exist - this should generate a UI alert as the user probably mistyped their email address
  3. returned when the user on a free plan already used up all the available notes - this too should generate an alert for the user
  4. returned when the note was correctly stored and available for the user
  5. returned when the note was correctly stored and available for the user but there are only a limited number of notes left to record (x is a placeholder for that number, whilst y is their daily allowance)
request example
https://www.plancake/api.php/voiceMemoRecorder/?api_ver=5&api_key=4589urejh34&api_secret=oer03uioerjhER34kjrtFE54Dfs&user_email=inbox_ciccio_4563@plancakebox.com
response example
OK-2