-
Notifications
You must be signed in to change notification settings - Fork 4
NirvanaHQ API
All requests happen over an HTTPS connection to the base url "https://api.nirvanahq.com". Most application logic seems to take place in the client. This means that if you want to implement a client you will need to implement validation, rules and logic around things like scheduled tasks yourself.
HTTP verbs are used appropriately in that GET requests fetch data and POST requests write data.
The following parameters are common to all requests:
- api - "rest" for form encoded single entities, "json" for json encoded batch requests
- requestid - A UUID unique to the request. The JS library simply generates a random one each request.
- clienttime - Unix time representation (seconds since Unix epoch) of time on the client.
- authtoken - An MD5 token that is retrieved at authentication.
- appid - A string representing the application making the request.
- appversion - A string representing the version of the application making the request.
There are only three primary types of data in the NirvanaHQ API:
- user - Data about the current user.
- task - A task or project (they share the same data structure).
- tag - A tag, area, context or contact (the share the same data structure).
Of these types of data, the API ( to the best of my knowledge ) can only write tasks and tags; user data is managed by account.nirvanahq.com which we'll get to later.
It should also be noted that most (not all) fields have a modify time counterpart in the structure itself. This is denoted by the field name prefixed by an underscore. For example, "username" has a counterpart "_username" in the user data structure that represents when the username was last changed. These fields have not been documented for clarity.
| Field | Type | Purpose |
|---|---|---|
| id | integer | User ID |
| n1sunset | unixtime | Unknown |
| maxprojects | integer | Max project count (Unknown if enforced) |
| maxareas | integer | Max area count. (Unknown if enforced) |
| maxlogbook | integer | Max logbook entries (Unknown if enforced) |
| version | integer | Presumed version of user data |
| username | string | Username |
| password | md5 | Unsalted MD5 of password |
| gmtoffset | integer | GMT (UTC?) offset in hours |
| firstname | string | First name |
| lastname | string | Last name |
| emailaddress | Email address | |
| inmailaddress | string | Unknown |
| pokememon | integer | Poke me monday? |
| pokemetue | integer | Poke me tuesday? |
| pokemewed | integer | Poke me wednesday? |
| pokemethu | integer | Poke me thursday? |
| pokemefri | integer | Poke me friday? |
| pokemesat | integer | Poke me saturday? |
| pokemesun | integer | Poke me sunday? |
| lastwritebyuseron | unixtime | Last write by user |
| lastactivityon | unixtime | Last activity by user (appears unused) |
| createdon | unixtime | User creation date |
| lastpaymentdate | unixtime | Last payment date (appears unused) |
| nextpaymentdate | unixtime | Next payment date (appears unused) |
| intrialperiod | boolean | In trial period (appears unused) |
| trialenddate | unixtime | Trial end date (appears unused) |
| incompperiod | boolean | Unknown |
| compenddate | unixtime | Unknown |
| ingraceperiod | boolean | In grace period (appears unused) |
| graceenddate | unixtime | Grace period end date (appears unused) |
| issuspended | boolean | User is suspended |
| Field | Type | Purpose |
|---|---|---|
| id | uuid | Unique identifier of task |
| type | integer | Type of task (0 = Task, 1 = Project) |
| ps | boolean | Is project sequential (0 if task is parallel, 1 if sequential) |
| state | integer | Action state (0 = Inbox, 1 = Next, 2 = Waiting, 3 = Scheduled, 4 = Someday, 5 = Later, 6 = Trashed, 7 = Logged, 8 = Deleted, 9 = Recurring, 11 = Active project ) |
| parentid | uuid | Parent project UUID |
| seq | integer | Order of task / project in project list |
| seqt | unixtime | Time task is focused (0 for not focused) |
| seqp | unixtime | Order of task in task list |
| name | string | Name of task / project |
| tags | string | Comma delimited list of tags |
| etime | integer | Minutes task requires (whoa nelly = 600) |
| energy | integer | Energy / effort for task / project |
| waitingfor | string | Name of contact task / project is waiting for |
| startdate | string | Start date of task / project in YYYYMMDD |
| duedate | string | Due date of task / project in YYYYMMDD |
| recurring | jsonstring | "{"paused":false,"freq":"daily","interval":1,"nextdate":"20120807","hasduedate":0}" |
| note | string | Contents of task / project note |
| completed | unixtime | Date of completion |
| cancelled | boolean | Cancelled? |
| deleted | unixtime | Date of deleted |
| updated | unixtime | Date of last update |
| Field | Type | Purpose |
|---|---|---|
| key | string | Tag name |
| type | integer | Tag type (0 = Tag, 1 = Area, 2 = Context, 3 = Contact) |
| Email of contact (blank for others) | ||
| color | string | Colour to use in displaying tag |
| meta | string | Unknown |
| deleted | unxitime | Time tag was deleted (0 for not deleted) |
Both search and rapid entry are handled in-browser by the web app. There are presently no known API methods to handle these.