Developer's API Documentation : Outlines
Overview
The Outline section of Toodledo gives you a way to organize your ideas by breaking them down into a hierarchical structure.
Jump To:
Outline Datatypes
There are a number of fields that can be set or retrieved when working with outlines. Here is a description of these fields.
- id : The server id number for this outline. This will be a hexadecimal string of 24-36 characters.
- title : A string for the name of the outline. Up to 100 characters.
- keywords : A comma separated string of keywords or tags, up to 200 characters. Keywords are used to organize, sort and search for outlines.
- note : A string for a longer note about this outline. Up to 2000 characters.
- modified : A GMT unix timestamp for when the outline was last modified.
- added : A GMT unix timestamp for when the outline was added.
- hidden : A boolean (0 or 1) that indicates if the outline is set to hide checked nodes.
- version : An integer indicating which version or revision this outline is on. Each time it is edited, this number will increment by one. It is used for conflict resolution when editing outlines simultaneously on two separate clients.
- ref : This field is only used for adding an outline to ensure that the same outline is not added twice. Set this to a reference to your local copy's id number or create a unique identifier for it.
- nodes : The outline data, which contains the following fields:
- count : The number of nodes in the outline.
- updated_at : A GMT unix timestamp indicating the last time the nodes were modified.
- children : A hierarchal collection of node elements.
Each node element will contain the following fields:
- id : The server id number for this node. It is a 16 digit integer.
- parent_id : The id number of this node's parent, if it has one.
- content : The text for this node. A string up to 150 characters.
- position : An integer that represents this node's order within its parent. A node with position 1 is at the top (within its parent).
- collapsed : A boolean (0 or 1) that indicates if this node is toggled closed.
- checked : A boolean (0 or 1) that indicates if this node is checked.
- children : A collection of additional nodes that are children of this node.
- updated_at : A GMT unix timestamp that indicates when this node was last modified.
Retrieving Outlines
The "outlines/get.php" API call will return a list of the outlines that match your search parameters. You can access this via GET or POST. The following search parameters may be used to limit the returned outlines. To make sync go as efficiently as possible you should request the minimum amount of data that you need. Usually, this means using the "after" field in this call to request only those outlines that have changed since your last sync. You should look at the "lastedit_outline" timestamp, returned from Account Info, to determine if any changes have happened on the server before you fetch anything. In the vast majority of cases, when syncing, nothing will have changed on the server and you won't even need to do anything.
- before : A GMT unix timestamp. Used to find outlines with a modified date and time before this date and time.
- after : A GMT unix timestamp. Used to find outlines with a modified date and time after this date and time.
- id : The id number of the outlines that you want to fetch. This is useful if you already know the id number and only need to fetch the one outlines.
- start : The number of records that you want to skip before printing results. Use this in combination with "num" if you want to paginate your results. The default value is 0.
- num : The number of records to go through until output is stopped. Use this in combination with "start" if you want to paginate your results. The default and max value is 1000.
http://api.toodledo.com/3/outlines/get.php?access_token=yourtoken&after=1234567890
This returns a list of outlines in the JSON format, like this.
[{"id":"52ab6aa8c725c1ac008b46c4","outline":{"children":[{"id":"1386965673672251","parent_id":null,"content":"Node #1","position":1,
"collapsed":false,"checked":false,"children":[{"id":"1386965687788571","parent_id":"1386965673672251","content":"A Child Node",
"position":1,"collapsed":false,"checked":false,"children":[],"updated_at":1386965691}],"updated_at":1386965687}],"count":2,
"updated_at":1386965691},"hidden":false,"title":"My Outline","added":1386965672,"modified":1386965691,"version":2,
"note":"A helpful note","keywords":"keyword1, keyword2"}]
You can also specify xml as the output format for any API calls.
http://api.toodledo.com/3/outlines/get.php?access_token=yourtoken&after=1234567890&f=xml
<outlines> <outline> <id>52ab6aa8c725c1ac008b46c4</id> <hidden>0</hidden> <title>My Outline</title> <added>1386965672</added> <modified>1386965691</modified> <version>2</version> <note>A helpful note</note> <keywords>keyword1, keyword2</keywords> <nodes> <children> <node> <id>1386965673672251</id> <parent_id/> <content>Node #1</content> <position>1</position> <collapsed>0</collapsed> <checked>0</checked> <children> <node> <id>1386965687788571</id> <parent_id>1386965673672251</parent_id> <content>A Child Node</content> <position>1</position> <collapsed>0</collapsed> <checked>0</checked> <children/> <updated_at>1386965691</updated_at> </node> </children> <updated_at>1386965687</updated_at> </node> </children> <count>2</count> <updated_at>1386965691</updated_at> </nodes> </outline> </outlines>
Adding Outlines
You can add up to 50 outlines at a time by making a POST to the "outlines/add.php" API call.
Outlines are added by creating a JSON object (example below) and submitting a POST with the field name "outlines" to the API. Be sure to encode the data properly for transfer via a URL (symbols replaced with their %XX equivalent and spaces encoded as +). Each element in the array will be an outline object. You only need to set the fields that you want to set, although "title" and "ref" are required. For efficiency, you should try to send only the fields that you are setting.
The "ref" field is a special field that you can use to pass through an id number to aid in matching things up after a sync. It is also used to ensure that the same outline is not added multiple times, so make sure you send a unique identifier as the "ref" for each new outline.
http://api.toodledo.com/3/outlines/add.php
access_token=yourtoken
outlines=[{"title":"New%20Outline","ref":"123456"}]
If the action was successful the added outlines will be returned in the same order in which they were added. If there were any errors on individual outlines, they will be output inline with the returned outlines, so you can determine which action failed.
[{"id":"52ab6f31f143149217ef5d3a","added":1386966833,"modified":1386966833,"title":"New Outline",
"outline":{"children":[]},"version":1,"ref":"123456","note":null,"keywords":null,"hidden":false}]
You can also specify xml as the output format for any API calls.
http://api.toodledo.com/3/outlines/add.php
access_token=yourtoken
f=xml
outlines=[{"title":"New%20Outline","ref":"123456"}]
<outlines> <outline> <id>52ab70f7f143149317ef5d38</id> <hidden>0</hidden> <title>New Outline</title> <added>1386967287</added> <modified>1386967287</modified> <version>1</version> <note></note> <keywords></keywords> <nodes> <children></children> </nodes> </outline> </outlines>
Editing Outlines
You can edit up to 50 outlines at a time by making a POST to the "outlines/edit.php" API call with the "outlines" field set to an array of outlines to edit. For each outline edited, the "id" and "version" field are required, and the following fields are optional: title, keywords, note, hidden, outline.
Outlines are edited by creating a JSON object (example below) and submitting a POST to the API. Be sure to encode the data properly for transfer via a URL (symbols replaced with their %XX equivalent and spaces encoded as +). Each element in the array will be an outline object.
http://api.toodledo.com/3/outlines/edit.php
access_token=yourtoken
outlines=[{"id":"52ab70f7f143149317ef5d38","title":"Edited%20Outline","version":"2"}]
If the action was successful the edited outlines will be returned. If there were any errors on individual outlines, they will be output inline with the returned outlines, so you can determine which action failed.
[{"id":"52ab70f7f143149317ef5d38","added":1386967287,"modified":1386967954,"title":"Edited Outline",
"outline":{"children":[]},"version":3,"note":"","keywords":"","hidden":false}]
You can also specify xml as the output format for any API calls.
http://api.toodledo.com/3/outlines/edit.php
access_token=yourtoken
f=xml
outlines=[{"id":"52ab70f7f143149317ef5d38","title":"Edited%20Outline","version":"2"}]
<outlines> <outline> <id>52ab70f7f143149317ef5d38</id> <hidden>0</hidden> <title>Edited Outline</title> <added>1386967287</added> <modified>1386967586</modified> <version>3</version> <note></note> <keywords></keywords> <nodes> <children></children> </nodes> </outline>
Deleting Outlines
The "/outlines/delete.php" API call will allow you to permanently delete up to 50 outlines at a time. You can access this via POST.
Outlines are deleted by submitting a JSON encoded array of ids to the API.
http://api.toodledo.com/3/outlines/delete.php access_token=yourtoken outlines=["1234abc"%2C"1235def"]
If the action was successful the deleted outline's id numbers will be returned. If there were any errors on individual outlines, they will be output inline with the returned ids, so you can determine which action failed.
[{"id":"1234abc"},{"errorCode":805,"errorDesc":"Invalid ID number","ref":"1235def"}]
You can also specify xml as the output format for any API calls.
http://api.toodledo.com/3/outlines/delete.php access_token=yourtoken f=xml outlines=["1234abc"%2C"1235def"]
<deleted> <id>1234abc</id> <error id="805" ref="1235def">Invalid ID number</error> </deleted>
Get Deleted Outlines
The "/outlines/deleted.php" API call will enable you to detect when an outline was deleted on Toodledo so you can also delete the outline from your application. You can access this via GET or POST.
- after : A GMT unix timestamp. Used to find outlines with a deletion date and time after this date and time.
http://api.toodledo.com/3/outlines/deleted.php&access_token=yourtoken&after=1234567890
This returns a list of id numbers and datetime stamps.
[{"id":"5238ca9af14314cf4c4f5fa4","deleted":1386199410},{"id":"52a7706df143142d7aef5d30","deleted":1386705006}]
You can also specify xml as the output format for any API calls.
http://api.toodledo.com/3/outlines/deleted.php?access_token=yourtoken&after=1234567890&f=xml
<deleted> <outline> <id>5238ca9af14314cf4c4f5fa4</id> <deleted>1386199410</deleted> </outline> <outline> <id>52a7706df143142d7aef5d30</id> <deleted>1386705006</deleted> </outline> </deleted>
Error Codes
Any of the API calls can return error messages. Here is a list of the error messages that you may receive from the outlines API endpoints. If there was an error when editing or deleting a outline, the id number that you attempted to edit will be included in the error's "ref" field for your reference.
- 801 : Outline had no title
- 802 : Only 50 outlines can be added/edited/deleted at a time.
- 803 : Max outlines reached
- 804 : Empty id
- 805 : Invalid outline
- 806 : Nothing was added/edited
- 807 : Invalid outline id
- 808 : Max nodes reached
- 809 : Outline already added
- 811 : Malformed request
- 812 : Reference was empty
- 813 : Invalid outline format
- 814 : Editing wrong version
Examples:
JSON:
{"errorCode":801,"errorDesc":"Your outline must have a name","ref":"1234abc"}
XML: <error id="801" ref="1234abc">Your outline must have a name</error>