RESTful API

Getting started

Welcome to oneheap API documentation.

Use our RESTful API to build own applications based on the oneheap webservice.

Entries

Production API entry. This is the current live environment of oneheap.

https://oneheap.com/service/v1/Api/Rest/    

the API version v1 is still beta and not final yet.

Requests

Every oneheap resource has a unique request path.

There are two main kinds of elements you are able to access via the RESTful API. Collections and Items. Collections can contain multiple items. The entry path of a collection is its name for example Notes/ for the notes collection. If you want to access an item inside a collection you have to use the collection name and the item id e.g. Notes/1234/.

Arguments

Additional you have to pass arguments to specified resources. For example data to create an item or pass filter or sorting arguments. The oneheap RESTful API only understand JSON, so you have to pass the arguments in the correct format.

The a sample authentication request using cURL.

curl \
    'https://oneheap.com/service/v1/Api/Rest/Authentications/' \
    -H 'Auth-Method: token' \
    -X POST \
    --data '{"email":"j.doe@example.com","password":"secret"}'

Here an example to fetch notes and pass sorting via GET arguments. You see the q argument which contains the query arguments as a JSON string.

curl -G
    'https://oneheap.com/service/v1/Api/Rest/Notes/' \
    -H 'Auth-Method: token' \
    -H 'Auth-Token: U8rFTrEjI8..v37sMG7pgR' \
    -d 'q={"limit":{"offset":0,"limit":1},"sort":{"modified/created":"desc"}}'

Responses

Any API response has the same basic structure. A HTTP compatible response code and an array of response objects. There is also a total count of response objects without paging.

{
    "code":200,
    "count": 469,
    "objects":[{
        "property": "value",
        "property": "value",
        "property": "value"
    }]
}

On errors a message and an array of request fields which maybe cause this problem will returned too.

{
    "code": 400,
    "message": "Invalid \"email\" parameter.",
    "fields": [ "email" ]
}

Request rate limit

Depending on your license the number of API requests per hour is limited. When the request rate limit is reached you will recieve an 429 Too Many Requests HTTP response. Every API response contains your current request rate state.

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9993
X-Ratelimit-Reset: 2015-02-26T11:02:40+0000

Workflow

Most API requests require an authentication token. To get an authentication token you have to authenticate yourself or your user first.

Request: POST Authentications/

{
    "email": "j.doe@example.com",
    "password": "secret"
}

Response:

{
    "code":200,
    "objects":[{
        ...
        "token":"U8rFTrEjI8..v37sMG7pgR"
        ...
    }]
}

Now you have to send the authentication token in the HTTP-Header with every API request you perform.

Auth-Method: token
Auth-Token: U8rFTrEjI8..v37sMG7pgR

Currently the authentication token will expire after a certain time. After expiration you will receive a 410 Gone HTTP response on any request.

Resources

  • Move item into archive

    entry

    POST /Archives/

    arguments

    Type Name Description Example
    string id id of object to move into archive
  • Update task

    entry

    POST /Tasks/:id/

    arguments

    Type Name Description Example
    string name note name
    string description note description
    string body note body
    string location location string
    integer progress progress 0..100
    string completed completed date 2015-02-26T11:02:40+0000
    string dateBegin task begin 2015-02-26T11:02:40+0000
    string dateEnd task end
    integer priotity task priority 0..100
    string boxId box id to store note in
    string image note image data:image/png;base64,iVBORw0KGg...Jggg==
    array tags array of tag names
  • Create task item assignment

    entry

    POST /Tasks/:id/Assignments/

    arguments

    Type Name Description Example
    array userIds array of user ids to assign to task
    string mode assign mode "add|set"
    string comment assignment comment
  • Create progress tracking

    entry

    POST /Tasks/:id/Trackings/

    arguments

    Type Name Description Example
    string action action start|stop
  • Add follower

    entry

    POST /Tasks/:id/Follower/

    arguments

    Type Name Description Example
    string userId user id
  • Set task permissions

    entry

    POST /Tasks/:id/Permissions/

    arguments

    Type Name Description Example
    array permissions permissions data
  • Create or add child task

    entry

    POST /Tasks/:id/Tasks

  • Add attachment

    entry

    POST /Tasks/:id/Files/

    arguments

    Type Name Description Example
    array files files [ "data:image/png;base64,iVBORw0KGg...Jggg==" ]
    array fileIds array of file object id to change sorting order
  • Add style

    entry

    POST /Tasks/:id/Styles/

    arguments

    Type Name Description Example
    string userId user id 1234|null
    string color color #FFFFFF
    string backgroundColor backgroundColor
    boolean recursive recurive for child items
  • Add comment

    entry

    POST /Tasks/:id/Comments/

    arguments

    Type Name Description Example
    string name comment title
    string body comment body
  • Add additional reminder

    entry

    POST /Tasks/:id/Reminders/

    arguments

    Type Name Description Example
    string date reminder date 2015-02-26T11:02:40+0000
    string type reminder type "fixed|diff"
    string description reminder description
  • Create error reporting

    entry

    POST /Errors/

    arguments

    Type Name Description Example
    string name error name
    string description error description
    string data error data
  • Create QAs

    Create new Q&A support request.

    entry

    POST /Qas/

    arguments

    Type Name Description Example
    string title title
    string body body
  • Create encryption key

    not implemented yet

    entry

    POST /Keys/

    arguments

    Type Name Description Example
    string name name
    string description description
    string public public encryption key
    string private private encryption key
  • Purchase subscription

    entry

    POST /Subscriptions/

    arguments

    Type Name Description Example
    string paymentType payment type paypal
    string licenseId license object id to purchase
    string returnUrl success return URL
  • Create import

    entry

    POST /Imports/

    arguments

    Type Name Description Example
    string data import data
    string type import type "json|xml|ical"
    string boxId id of box to import items into
  • Update file

    entry

    POST /Files/:id/

    arguments

    Type Name Description Example
    string name file name
    string description file description
    string filename original file name
    string data file data
    string boxId box id to store file in
    array tags array of tag names
  • Add follower

    entry

    POST /Files/:id/Follower/

    arguments

    Type Name Description Example
    string userId user id
  • Set file permissions

    entry

    POST /Files/:id/Permissions/

    arguments

    Type Name Description Example
    array permissions permissions data
  • Add attachment

    entry

    POST /Files/:id/Files/

    arguments

    Type Name Description Example
    string name file name
    string description file description
    string data file data data:image/png;base64,iVBORw0KGg...Jggg==
  • Add style

    entry

    POST /Files/:id/Styles/

    arguments

    Type Name Description Example
    string userId user id 1234|null
    string color color "#FFFFFF"
    string backgroundColor backgroundColor
    boolean recursive recurive for child items
  • Add comment

    entry

    POST /Files/:id/Comments/

    arguments

    Type Name Description Example
    string name comment title
    string body comment body
  • Update day

    entry

    POST /Days/:id/

    arguments

    Type Name Description Example
    string name day name
    string description day description
    string date day date 2015-02-26T11:02:40+0000
    string boxId box id to store day in
    string image day image data:image/png;base64,iVBORw0KGg...Jggg==
    array tags array of tag names
  • Add follower

    entry

    POST /Days/:id/Follower/

    arguments

    Type Name Description Example
    string userId user id
  • Set day permissions

    entry

    POST /Days/:id/Permissions/

    arguments

    Type Name Description Example
    array permissions permissions data
  • Add attachment

    entry

    POST /Days/:id/Files/

    arguments

    Type Name Description Example
    array files files [ "data:image/png;base64,iVBORw0KGg...Jggg==" ]
    array fileIds array of file object id to change sorting order
  • Add style

    entry

    POST /Days/:id/Styles/

    arguments

    Type Name Description Example
    string userId user id 1234|null
    string color color "#FFFFFF"
    string backgroundColor backgroundColor
    boolean recursive recurive for child items
  • Add comment

    entry

    POST /Days/:id/Comments/

    arguments

    Type Name Description Example
    string name comment title
    string body comment body
  • Create group

    entry

    POST /Group/

    arguments

    Type Name Description Example
    string name group name
    string description group description
    string image group image data:image/png;base64,iVBORw0KGg...Jggg==
    array tags array of tag names
  • Register user

    entry

    POST /Users/

    arguments

    Type Name Description Example
    string email email address
    string password password
    string successUrl success redirection URL for activation link
    string errorUrl error redirection URL for activation link
    string firstName first name
    string lastName last name
    string alias user alias
    string signature user signature
    string image user profile image data:image/png;base64,iVBORw0KGg...Jggg==
    string invitationToken optional invitation token
    array settings settings
  • Create sticky

    entry

    POST /Stickies/

    arguments

    Type Name Description Example
    string name sticky name
    string body sticky body
    string parentId id of object to stick sticky onto
    string color sticky note color #FFFFFF
  • Create day

    entry

    POST /Days/

    arguments

    Type Name Description Example
    string name day name
    string description day description
    string date day date 2015-02-26T11:02:40+0000
    array tags array of tag names
  • Update comment

    entry

    POST /Comments/:id/

    arguments

    Type Name Description Example
    string name comment title
    string body comment body
  • Add attachment

    entry

    POST /Comments/:id/Files/

    arguments

    Type Name Description Example
    array files files [ "data:image/png;base64,iVBORw0KGg...Jggg==" ]
    array fileIds array of file object id to change sorting order
  • Reply comment

    entry

    POST /Comments/:id/Comments/

    arguments

    Type Name Description Example
    string name comment title
    string body comment body
  • Notify user about an item

    entry

    POST /Notifications/

    arguments

    Type Name Description Example
    string itemId item object id
    string recipientId id of user to notify
    string comment notification comment
  • Set item permissions

    entry

    POST /Permissions/

    arguments

    Type Name Description Example
    string item item to set permission for
    boolean recursive set permissions recursive
    string mode "add", "remove" or "set"
    string permissions permissions data [{"type":1,"access":[1,2],"id":"1234"}]
  • Advanced search

    entry

    POST /Searches/

    arguments

    Type Name Description Example
    string parentId parent object id
    string parentType parent object type
    boolean archived archived
    array ids object ids to fetch
    array excludeIds array of ids to exclude from search
    string ownerId owner id
    array types array of item types to fetch [ "task", "note" ]
    array progress progress range
    boolean completed completed
    string boxId box id
    array date date range [ "2015-02-26T11:00:00+0000", "2015-02-27T15:30:00+0000" ] or null
    string search search query
    boolean follow follow
    boolean favorite search for favorite items
    string asign assign search query
    array tags array of tags
  • Create note

    entry

    POST /Notes/

    arguments

    Type Name Description Example
    string name note name
    string description note description
    string body note body
    string boxId box id to store note in
    string image note image data:image/png;base64,iVBORw0KGg...Jggg==
    array tags array of tag names
  • Create appointment

    entry

    POST /Appointments/

    arguments

    Type Name Description Example
    string name appointment name
    string description appointment description
    string location location string
    integer progress progress 0..100
    string dateBegin appointment begin 2015-02-26T11:02:40+0000
    string dateEnd appointment end
    string boxId box id to store appointment in
    integer priority appointment priority 0..100
    string reminder appointment reminder 2015-02-26T11:02:40+0000
    string image appointment image data:image/png;base64,iVBORw0KGg...Jggg==
    array tags array of tag names
  • Set new password

    entry

    POST /Passwords/

    arguments

    Type Name Description Example
    string token reset security token
    string password password
  • Update public

    entry

    POST /Publics/:id/

    arguments

    Type Name Description Example
    string name public name
    string description public description
    string expire public expiration date
  • Add item to favorites

    entry

    POST /Favorites/

    arguments

    Type Name Description Example
    string itemId id of item object to add to favorites
  • Create task

    entry

    POST /Tasks/

    arguments

    Type Name Description Example
    string name task name
    string description task description
    string body task body
    string location location string
    integer progress progress 0..100
    string dateBegin task begin 2015-02-26T11:02:40+0000
    string dateEnd task end
    string boxId box id to store task in
    integer priority task priority 0..100
    string reminder task reminder 2015-02-26T11:02:40+0000
    string image task image data:image/png;base64,iVBORw0KGg...Jggg==
    array tags array of tag names
  • Update note

    entry

    POST /Notes/:id/

    arguments

    Type Name Description Example
    string name note name
    string description note description
    string body note body
    string boxId box id to store note in
    string image note image data:image/png;base64,iVBORw0KGg...Jggg==
    array tags array of tag names
  • Add follower

    entry

    POST /Notes/:id/Follower/

    arguments

    Type Name Description Example
    string userId user id
  • Set note permissions

    entry

    POST /Notes/:id/Permissions/

    arguments

    Type Name Description Example
    array permissions permissions data
  • Add attachment

    entry

    POST /Notes/:id/Files/

    arguments

    Type Name Description Example
    array files files [ "data:image/png;base64,iVBORw0KGg...Jggg==" ]
    array fileIds array of file object id to change sorting order
  • Add style

    entry

    POST /Notes/:id/Styles/

    arguments

    Type Name Description Example
    string userId user id 1234|null
    string color color "#FFFFFF"
    string backgroundColor backgroundColor
    boolean recursive recurive for child items
  • Add comment

    entry

    POST /Notes/:id/Comments/

    arguments

    Type Name Description Example
    string name comment title
    string body comment body
  • Update hint

    entry

    POST /Hints/:id/

    arguments

    Type Name Description Example
    boolean read read
  • Create box

    entry

    POST /Boxes/

    arguments

    Type Name Description Example
    string name box name
    string description box description
    string image box image data:image/png;base64,iVBORw0KGg...Jggg==
    array tags array of tag names
  • Update box

    entry

    POST /Boxes/:id/

    arguments

    Type Name Description Example
    string name box name
    string description box description
    string image box image data:image/png;base64,iVBORw0KGg...Jggg==
    array tags array of tag names
  • Add follower

    entry

    POST /Boxes/:id/Follower/

    arguments

    Type Name Description Example
    string userId user id
  • Set box permissions

    entry

    POST /Boxes/:id/Permissions/

    arguments

    Type Name Description Example
    array permissions permissions data
  • Add style

    entry

    POST /Boxes/:id/Styles/

    arguments

    Type Name Description Example
    string userId user id 1234|null
    string color color "#FFFFFF"
    string backgroundColor backgroundColor
    boolean recursive recurive for child items
  • Add comment

    entry

    POST /Boxes/:id/Comments/

    arguments

    Type Name Description Example
    string name comment title
    string body comment body
  • Update user

    entry

    POST /Users/:id/

    arguments

    Type Name Description Example
    string password password
    string firstName first name
    string lastName last name
    string alias alias
    string signature signature
    string image profile image
    array settings settings
  • Invite new team member

    not implemented yet

    entry

    POST /Users/:id/Users/

  • Add user to known

    entry

    /Users/:id/Knowns/

    arguments

    Type Name Description Example
    string user email address or id of user to add to knowns
    string token invitation token to accept knowns invitation
    string message knowns invitation message
  • Add encryption keys

    entry

    /Users/:id/Crypts/

    arguments

    Type Name Description Example
    string public public encryption key
    string pricate private decryption key
  • Create file

    entry

    POST /Files/

    arguments

    Type Name Description Example
    string name file name
    string description file description
    string filename original file name
    string data file data
    string boxId box id to store file in
    array permissions item permissions [{"type": 1, "access": 2, "objectId": "534..b02"}]
    array tags array of tag names
  • Update appointment

    entry

    POST /Appointments/:id/

    arguments

    Type Name Description Example
    string name task name
    string description task description
    string location location string
    integer progress progress 0..100
    string dateBegin task begin 2015-02-26T11:02:40+0000
    string dateEnd task end
    string boxId box id to store task in
    integer priority task priority 0..100
    string image task image data:image/png;base64,iVBORw0KGg...Jggg==
    array tags array of tag names
  • Add/invite user to appointment

    entry

    POST /Appointments/:id/Users/

    arguments

    Type Name Description Example
    array userIds user ids
    string state invitation state yes|no|maybe
    string comment comment
  • Add follower

    entry

    POST /Appointments/:id/Follower/

    arguments

    Type Name Description Example
    string userId user id
  • Set appointment permissions

    entry

    POST /Appointments/:id/Permissions/

    arguments

    Type Name Description Example
    array permissions permissions data
  • Add attachment

    entry

    POST /Appointments/:id/Files/

    arguments

    Type Name Description Example
    array files files [ "data:image/png;base64,iVBORw0KGg...Jggg==" ]
    array fileIds array of file object id to change sorting order
  • Add style

    entry

    POST /Appointments/:id/Styles/

    arguments

    Type Name Description Example
    string userId user id 1234|null
    string color color #FFFFFF
    string backgroundColor backgroundColor
    boolean recursive recurive for child items
  • Add comment

    entry

    POST /Appointments/:id/Comments/

    arguments

    Type Name Description Example
    string name comment title
    string body comment body
  • Add additional reminder

    entry

    POST /Appointments/:id/Reminders/

    arguments

    Type Name Description Example
    string date reminder date 2015-02-26T11:02:40+0000
    string description reminder description
  • Create authentication

    note

    also known as login

    entry

    POST /Authentications/

    arguments

    Type Name Description Example
    string email authentication email
    string password authentication password
  • Create an item export

    entry

    POST /Exports/

    arguments

    Type Name Description Example
    object query export query
    string type export type "json|xml|ical"
  • Update group

    entry

    POST /Groups/:id/

    arguments

    Type Name Description Example
    string name group name
    string description group description
    string image group image data:image/png;base64,iVBORw0KGg...Jggg==
    array tags array of tag names
  • Add users to group

    entry

    POST /Groups/:id/Users/

    arguments

    Type Name Description Example
    array userIds array of user ids
  • Update sticky

    entry

    POST /Stickies/:id/

    arguments

    Type Name Description Example
    string name sticky name
    string body sticky body
    string color sticky note color #FFFFFF
  • Create comment

    entry

    POST /Comments/

    arguments

    Type Name Description Example
    string name comment title
    string body comment body
    string targetId id of item to comment or id of comment to reply
  • Delete task

    entry

    DELETE /Tasks/:id/

  • Separate child task from parent.

    entry

    DELETE /Tasks/:id/Tasks/:id/

  • Remove attachment

    Remove attachment from task item.

    entry

    DELETE /Tasks/:id/Files/:id/

  • Remove task user assignments

    entry

    DELETE /Tasks/:id/Assignments/

  • Delete reminder

    entry

    DELETE /Tasks/:id/Reminders/:id/

  • Remove task user assignment

    entry

    DELETE /Tasks/:id/Assignments/:id/

  • Remove follower

    entry

    DELETE /Tasks/:id/Follower/:id/

  • Remove task reminders

    entry

    DELETE /Tasks/:id/Reminders/

  • Remove item from favorites

    entry

    DELETE /Favorites/:id/

  • Delete file

    entry

    DELETE /Files/:id/

  • Delete day

    entry

    DELETE /Days/:id/

  • Delete comment

    entry

    DELETE /Comments/:id/

  • Remove attachment

    Remove attachment from comment.

    entry

    DELETE /Comments/:id/Files/:id/

  • Restore item from archive

    entry

    DELETE /Archives/:id/

  • Initiate password reset workflow

    entry

    DELETE /Passwords/

  • Delete public

    entry

    DELETE /Publics/:id/

  • Delete note

    entry

    DELETE /Notes/:id/

  • Remove attachment

    Remove attachment from note item.

    entry

    DELETE /Notes/:id/Files/:id/

  • Remove follower

    entry

    DELETE /Notes/:id/Follower/:id/

  • Delete hint

    entry

    DELETE /Hints/:id/

  • Delete box

    entry

    DELETE /Boxes/:id/

  • Delete user

    entry

    DELETE /Users/:id/

  • Remove user from knowns

    entry

    DELETE /Users/:id/Knowns/:id/

  • Remove task from user

    entry

    DELETE /Users/:id/Tasks/:id/

  • Delete notification

    entry

    DELETE /Notifications/:id/

  • Delete appointment

    entry

    DELETE /Appointments/:id/

  • Remove attachment

    Remove attachment from appointment item.

    entry

    DELETE /Appointments/:id/Files/:id/

  • Delete reminder

    entry

    DELETE /Appointments/:id/Reminders/:id/

  • Remove appointment invitation

    entry

    DELETE /Appointments/:id/Users/:id/

  • Remove follower

    entry

    DELETE /Appointments/:id/Follower/:id/

  • Remove appointment reminders

    entry

    DELETE /Appointments/:id/Reminders/

  • Delete authentication

    note

    also known as logout

    entry

    DELETE /Authentications/

  • Delete group

    entry

    DELETE /Groups/:id/

  • Remove user from group

    entry

    DELETE /Groups/:id/Users/:id/

  • Delete sticky

    entry

    DELETE /Stickies/:id/

  • Cancel subscription

    not implemented yet

    entry

    DELETE /Subscriptions/:id/

  • Get task

    entry

    GET /Tasks/:id/

  • Get crypt keys

    entry

    GET /Tasks/:id/Keys

  • Get child tasks

    entry

    GET /Tasks/:id/Tasks/

  • Get crypt keys

    entry

    GET /Keys/

  • Get file

    entry

    GET /Files/:id/

  • Get day

    entry

    GET /Days/:id/

  • Get groups

    entry

    GET /Groups/

    arguments

    Type Name Description Example
    array id array of group ids
    string ownerId owner id
    string search search query
  • Get users

    entry

    GET /Users/

    arguments

    Type Name Description Example
    string search search query
    string parentId parent user id
    array excludeIds array of excluded ids
    boolean known fetch known users
  • Get licenses

    entry

    GET /Licenses/

    arguments

    Type Name Description Example
    string interval license interval
  • Get comment

    entry

    GET /Tasks/:id/

  • Get notifications

    entry

    GET /Notifications/

    arguments

    Type Name Description Example
    array id array of note ids
    string ownerId owner id
    string search search query
  • Get notes

    entry

    GET /Notes/

    arguments

    Type Name Description Example
    array id array of note ids
    string ownerId owner id
    string search search query
  • Get invitation

    entry

    GET /Invitations/:id/

  • Get appointments

    entry

    GET /Appointments/

    arguments

    Type Name Description Example
    array id array of appointment ids
    string ownerId owner id
    string search search query
  • Get public

    entry

    GET /Publics/:id/

  • Get tasks

    entry

    GET /Tasks/

    arguments

    Type Name Description Example
    array id array of note ids
    string ownerId owner id
    string search search query
    array progress progress range [0,99]
    array priority priority range
    string workerIds assigned worker ids
  • Get note

    entry

    GET /Notes/:id/

  • Get crypt keys

    entry

    GET /Notes/:id/Keys

  • Get boxes

    entry

    GET /Boxes/

    arguments

    Type Name Description Example
    array id array of box ids
    string ownerId owner id
    srring search search query
  • Get box

    entry

    GET /Boxes/:id/

  • Get box stats

    Receive box statistics like total number, progress or completed items and more

    entry

    GET /Boxes/:id/Stats/

  • Get user

    entry

    GET /Users/:id/

  • Get user stats

    Receive user statistics like number of items, notifications, assigned items and more.

    entry

    GET /Users/:id/Stats/

  • Get notification

    entry

    GET /Notifications/:id/

  • Get appointment

    entry

    GET /Appointments/:id/

  • Get crypt keys

    entry

    GET /Appointments/:id/Keys

  • Get group

    entry

    GET /Groups/:id/

  • Get group users

    entry

    GET /Groups/:id/Users/

  • Get application statistics

    entry

    GET /Statistics/

  • Get sticky

    entry

    GET /Stickies/:id/

  • Get hints

    entry

    GET /Hints/

    arguments

    Type Name Description Example
    array id array of hint ids
    string ownerId owner id
    string search search query
  • Get publics

    entry

    GET /Publics/

    arguments

    Type Name Description Example
    array id array of note ids
    string search search query