NAV Navbar
Logo
javascript shell json java

Introduction

Hitask is an online task and project management software. With Hitask you can share tasks and projects with your team, add multi-user comments, track time, attach files, produce reports and much more.

API Endpoint URL

API endpoint is https://hitask.com/api/{method} where {method} is the name of API method.

Authentication

This API is SSL/HTTPS only.

All methods require authentication. Authentication achieved through User.authenticate which returns session id. Your application have to provide the session id with every request. There are two ways of doing this:

Rate limiting

We only allow a certain number of requests per client per minute. If you exceed this limit you will have to wait before your next request is processed.

API Key

To authorize, use this code:


# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
  -H "Authorization: "

Make sure to replace your_key with your API key.

To access the API you need to have API Key. API Key is a unique identifier assigned to you. To get your Key simply go into your Hitask account settings page. You will be asked to provide the name of your integration/app. You are required to provide your API Key as a parameter for some methods, for example API Key is required when you authenticate user session: User.authenticate

Authorization: your_key

User

Operations related to current user’s account: authenticate, sign up, etc.

Authenticate


{
    "api_key" : myapikey;
    login : john;
    password : XXXXXXXXX;
}

Will produce the response:

{
    id : 12345678;
    level : 300;
    "session_id" : "e0f93451-5ad6-4550-b991-efb0ce1e271b";
}

Input parameters:

Response values:

Sign out

End current session

Input parameters: * session_id: session token

User Account information

Example response:

{
    businessId : 123,
    businessLevel : 100,
    email : "name@email.com",
    emailConfirmed : "name@email.com",
    id : 123,
    isOnline : 1,
    level : 0,
    login : "john",
    firstName : "Mick",
    lastName : "Johnson",
    pictureSource: 1000,
    pictureHash: "4b0c75c8-14cc-4d9b2-80aa-b49f5cf62daf"
}

Response fields:

Field Type Description
id long Globally unique primary identifier for a user. This is an integer, but it is recommended to handle it as String to avoid limitations with the way JavaScript integers are expressed.
accountType String User’s account type: TEAM_BASIC, TEAM_BUSINESS, PERSONAL_FREE, PERSONAL_PREMIUM
login String user login id
firstName String user’s First Name
lastName String user’s Last Name
emailConfirmed String Email address that was confirmed by the user. (By clicking confirmaiton link sent to this email address.)
email String Email address that user entered but not confirmed.
businessId Integer unique identifier of user’s Team Business account, if applicable
businessLevel Integer Membership level of user in Business account
pictureHash String Unique avatar identifier that should be used in order to build user avatar URL
pictureSource Integer Type of user avatar: See below

Type of user avatar

Update User Account information

Input parameters: * firstname: First Name * lastname: Last Name * email: e-mail address. If email address is different from previously stored, an email message with address confirmation will be sent

Update User Avatar

Example response:

{"hash":"4b0c75c8-14cc-49b2-80aa-b49f5cf62daf"}

Input parameters: * picture: Picture data * x: (Optional) X coordinate of top left corner of square that will be used to crop the picture (x, y and width must be specified to crop the picture) * y: (Optional) Y coordinate of top left corner of square that will be used to crop the picture (x, y and width must be specified to crop the picture) * width: (Optional) Width of square that will be used to crop the picture (x, y and width must be specified to crop the picture)

Restrictions: * max picture size is 1MB * allowed picture formats: “gif”, “jpeg”, “jpg”, “png”

Error codes: * HTTP 400 and code 32: picture upload failed, retry required * HTTP 400 and code 34: crop parameters are invalid * HTTP 400 and code 6: uploaded data is not a valid picture * HTTP 400 and code 5: picture format is not valid * HTTP 400 and code 25: picture exceeded maximum allowed size

Response:

JSON object with one property “hash”: unique picture identifier.

Delete User Avatar

Input parameters: * returninfo: (optional) if “true” then full account info will be returned as described in GET /user

Get User Preferences

Example response:

{
    "notify_app_item_deleted": "true",
    "notify_app_item_completed": "true",
    "ttstart": "06:00",
    "first_day_of_week": "1",
    "comment_order": "1",
    "notify_app": "true",
    "default_new_item_use_last": "true",
    "show_confirmation_complete": "true",
    "notify_app_item_tags": "true",
    "notify_web": "true",
    "default_sharing_permission_auto": "[{\"principal\":16686710,\"level\":100}]",
    "default_new_item_sharing_permission": "[{\"principal\":18556710,\"level\":100}]",
    "show_issue_sequence_id": "false",
    "notify_web_item_participant": "true",
    "desktopNotifyState": "0",
    "notify_email": "true",
    "time_zone": "Europe/Paris",
    "language": "en",
    "default_sharing_permission_last": "[{\"level\":100,\"principal\":\"18556710\"}]",
    "notify_web_item_attachment": "true",
    "main_assign_user": "186905",
    "notify_app_item_comment": "true",
    "notify_email_item_tags": "true",
    "enable_time_tracking": "false",
    "notify_app_item_participant": "true",
    "default_sharing_permission": "50",
    "notify_email_item_modify": "true",
    "notify_web_item_completed": "true",
    "notify_web_item_priority": "true",
    "default_shared_1": "false",
    "notify_web_item_comment": "true",
    "default_shared_0": "true",
    "time_format": "24",
    "notify_email_item_reminder": "true",
    "notify_email_item_priority": "true",
    "default_assign_user": "0",
    "sub_task_complete_affect_parent": "false",
    "notify_email_item_attachment": "true",
    "duplicate_with_files": "false",
    "notify_email_item_participant": "true",
    "daily_summary_email_6": "true",
    "daily_summary_email_7": "true",
    "daily_summary_email_4": "true",
    "daily_summary_email_5": "true",
    "daily_summary_email_2": "true",
    "daily_summary_email_3": "true",
    "daily_summary_email_1": "true",
    "bigCalendarMode": "month",
    "daily_summary_email_": "true",
    "override_parent_permission_with_last_used": "false",
    "notify_web_item_modify": "true",
    "notify_app_item_attachment": "true",
    "notify_email_item_comment": "true",
    "notify_web_item_tags": "true",
    "notify_email_item_completed": "true",
    "date_format": "d-m-y",
    "notify_email_item_deleted": "true",
    "taskfilter": "0",
    "notify_web_item_deleted": "true",
    "notify_app_item_priority": "true",
    "notify_app_item_assigned": "true",
    "notify_web_item_assigned": "true",
    "notify_email_item_assigned": "true",
    "default_shared": "false",
    "item.action.combobutton.last-used": "DELETE",
    "notify_app_item_modify": "true",
}

Set User Preferences

Request body contain dictionary of key-value pairs

Example request body:

{
notify_app_item_deleted: "true"
}

Team

1. Get Team account information

Will produce the response:

{
    "domainName": "doman",
    "title": "Development Team",
    "licensesNumber": 15,
    "licensesUsed": 12,
    "storageQuota": 7500,
    "storageUsed": 157,
    "storageQuotaFormatted": "7.50GB",
    "storageUsedFormatted": "157MB",
    "expirationDate": "2016-10-17T00:00:00.000+00:00",
    "emailInbox": "2187b87d0bsds2dd9fe@hitask.com"}

Response

Description
domainName subdomain name e.g. comapny.hitask.com
title Team name
licensesNumber number of user licenses
licensesUsed number of used user licenses
storageQuota file storage space available (integer)
storageUsed file storage space used (integer)
storageQuotaFormatted file storage space available as humnan readable string
storageUsedFormatted file storage space available as humnan readable string
expirationDate Account expiration date for TRIAL or Next billing date for TEAM BUSINESS
emailInbox Unique email address used to create tasks for team by email

Team members and team properties

2. Get list of team members

3. Invite to join team account

Parameters

Parameter Type Description
email string Valid email address. Required
name string Full name. First name and last name separated by space. e.g. “Firstname Lastname”

Response codes

HTTP code API Error code Description
200 Invited,added
400 5 bad request, email address invalid
412 16 Already a member, (this email address is already member of Team)
412 79 User already invited in this team
400 12 User licenses exceeded

4. Remove team member

Removes team member or invited user

Parameters

Parameter Type Description
id integer member user id

Response codes

HTTP code API Error code Description
200 member removed
404 1 member not found
400 4 “id” parameter is mandatory

5. Resend invitation

In case user did not receive email invitation use this method to re-send invitation again

Parameters

Parameter Type Description
email string Valid email address. Required

Response codes

HTTP code API Error code Description
200 Invited,added
400 5 bad request, email address invalid
412 16 Already a member, (this email address is already member of Team)
400 12 User licenses exceeded

Item

Operations with items: tasks, events, projects, notes, files.

Field Type Example Description
id long 123000 Globally unique item Identifier
guid String (UDID) 123456abcdef Globally unique item Identifier used for public sharing
user_id long 123000 user id of owner, user who created this item
title String (512) My Task title
short_name String (8) APIDOCS Short name of project. Accepted by projects only. Restrictions: 8 characters length maximum, latin letters and digits.
issue_id String APIDOCS-17 Unique reference identifier for tasks and projects.
completed int 0 Indication if this item is completed
color int 0 Color tag (index of predefined colors) used for items (tasks, events, notes, ..). Onde of these colors: [no color, ‘#FB7E6E’, ‘#F8B957’, ‘#F3DF5B’, ‘#C2D95B’, ‘#6CB4FF’, ‘#CAA4DF’, ‘#B8B8B8’]
color_value Strng #5e93c3 Color value used for projects. Default: #5e93c3
One of these colors: [‘#5e93c3’, ‘#fc2f6a’, ‘#fd9426’, ‘#fecb2e’, ‘#55ce2e’, ‘#cb77df’, ‘#a18460’]
category int 1 Category (or type) of item: 0:project 1: task 2:event 4: note 5:file
message String (5000) Hello Item description text
parent long 0 Unique id of parent item. Default: 0. 0 means item is not child of another item and not inside of project
recurring int 0 0: not recurring, 1: daily, 2: weekly, 3: monthly, 4: yearly
assigneeId long 0 Assignee, primary responsible person. User id of user whom item is assigned to
participants comma separated list of user identifiers 322,413 array of user id for this item participants
start_date Date 2012-03-15T19:00:00.000+10:00 Start date and time for this item. Default:null.
is_all_day int 0 Indicator that this item is “all day” event. Only date without time should be used from start/end date field..
alerts JSON array of JSON objects See “Alerts” below
shared int 0 0: Item is private. 1: item is shared, visile to team memebrs (Business account feature)
time_last_update Date 2012-03-15T19:00:00.000+10:00 Timestamp when this item was last changed (updated).
time_create Date 2012-03-15T19:00:00.000+10:00 Timestamp when this item was created.
starred int 0 If item is marked as starred, 1 or 0
time_track int 0 1/0 flag to specify if time tracking is enabled for htis item. Default:0.
time_est float 0 Time estimated for this item, in hours. Used in time tracking calculations.Optional.
time_spent float 0 Total time spent recorded for this item.
priority int 20000 Arbitrary priority. 10000-19999:low, 20000-29999:normal, 30000:high. Default: 20000 (normal)
tags comma separated list of tags “work”,“home” array or tags added to item
instances array[item_instance] [] array of instances for recurring item. at PUT/POST requests this field is ignored by the server.
location object {"longitude":123.1234567,"latitude":-4.0987654321,"address":"qwe"} Map that contains long/lat coordinates and address
unread number or null 0 Item is “unread” for this user. It was created or modified by someone else
permissions JSON array See “Permissions” below

Alerts structure

    {
        "id":900,
        "timeType":4,
        "time":5,
        "timeSpecified":"2016-08-31T11:00:00.000+04:00",
        "repeat":2,
        "repeatInterval":5,
        "sound":true,
        "alert":true,
        "email":true,
        "push":true
    }
Field Type Example Description
id long 900 optional: if id is not specified then new alert will be created, or existing updated otherwise
timeType long 4 mandatory; possible values: 1 - specified time, 2 - days before, 3 - hours before, 4 - minutes before
time long 5 mandatory if timeType in [2, 3, 4]
timeSpecified date “2016-08-31T11:00:00.000+04:00” mandatory if timeType=1, format is same as for start_date and end_date of item object
repeat long 2 optional: how many times reminder should be repeated
repeatInterval long 5 optional: repeat interval in minutes
sound boolean true optional: play sound
alert boolean true optional: display notification in desktop/browser version of application
email boolean true optional: send email
push boolean true optional: send push notification to mobile device

To Create/Update/Delete reminders:

[
    {"timeType":4,"time":0,"repeat":1,
    "repeatInterval":0,"sound":true,"alert":true,
    "email":true,"push":true},
    {"timeType":4,"time":5,"repeat":1,
    "repeatInterval":0,"sound":true,"alert":true,"email":true,
    "push":true},
    {"timeType":3,"time":1,"repeat":1,
    "repeatInterval":0,"sound":true,"alert":true,"email":true,
    "push":true},
    {"timeType":1,"timeSpecified":"2016-08-31T11:00:00.000+04:00",
    "repeat":1,"repeatInterval":0,"sound":true,"alert":true,
    "email":true,"push":true}
]

Alert object description:

Permissions

Permission is defined by a level integer value.

Level Description Title displayed in client Sub-title (description) displayed in client app
0/none Not visible to user. Server does not return this item in user’s items Not visible
10 User can see item in list. Item sub-items and file attachments. Item history. View
20 User can add comments to item View and Comment See in their lists, View details, Add comments
30 User can add attachments. Can add sub-items, If project- can create new items in project Add sub-tasks and attachments , “Create tasks in project”
40 User can assign/reassign “Assign”
50 User can Complete, Log time. Transition to another status (future) Complete and Assign Complete, reassign to another Team member, Attach documents, Add sub-tasks, Log time.
60 User can modify all properties (except Sharing permissions) Modify Modify item except its Sharing permissions
70 Can change sharing permissions (can add level 70 but not remove) “Share with others”
80 User can archive item
100 User can delete item Everything Modify, Change sharing, Delete, Archive

Unread value

Unread What it means Relationship to item
0 or null Item is read (default)
1 Comment added User is participant or assignee or creator. Comment added by someone else
2 Modified, sub-item added Assignee, participant, creator
3 New item Assignee, participant, creator

1. Get array of items

This method will return array of all items: tasks, events, files including projects. It returns X-Cursor HTTP header. Cursor is a unix timestamp (in milliseconds) of server response. Example: 1478802464. It equals to timestamp of latest modified returned item.

[{"id":3361634,"user_id":184743,"title":"event 5724 1","completed":false,"color":0,"color_value":"#2AAEF5","category":2,"message":null,"parent":0,"recurring":0,"recurring_interval":1,"recurring_end_date":"2017-08-26T15:56:46.820+04:00","time_last_update":"2016-08-26T18:04:04.340+04:00","time_create":"2016-08-26T18:04:04.340+04:00","start_date":"2016-08-27T00:00:00.000+04:00","end_date":null,"due_date":null,"is_all_day":true,"shared":true,"reminder_enabled":null,"reminder_time":null,"reminder_time_type":null,"starred":false,"time_track":false,"time_est":0,"time_spent":0,"priority":21720,"last_comment_id":null,"last_comment":null,"last_comment_user_id":null,"last_comment_create_datetime":null,"guid":"9769a9f9-726c-4ec8-a920-be16193c26a6","parentGuid":null,"assignee":0,"tags":null,"version":1,"instances":null,"participants":null,"publish_url":null,"location":null,"alerts":null,"unread":null,"short_name":null,"issue_id":"164","permission":100,"permissions":[{"level":100,"principal":"184743"}],"previews":null,"last_transition_time":null,"last_transition_user":null}

1.2 Get delta update of items

Returns list of items that were changed or added since specified date. It returns X-Cursor HTTP header. Cursor is a unix timestamp (in milliseconds) of server response. Example: 1478802464. It equals to timestamp of latest modified returned item. Deprecated. Use /item/delta/{delta} instead.

1.3 Get delta update of items

Returns list of items that were changed or added since specified delta. Delta is is a unix timestamp (in milliseconds) fetched from header X-Cursor. It returns X-Cursor HTTP header. Cursor is a unix timestamp (in milliseconds) of server response. Example: 1478802464. It equals to timestamp of latest modified returned item.

[{"id":3361634,"changed":false},{"id":3362490,"changed":false},{"id":3362767,"changed":false},{"id":3362336,"changed":false},{"id":3362771,"user_id":184743,"title":"delta api","completed":false,"color":0,"color_value":"#2AAEF5","category":1,"parent":0,"recurring":0,"recurring_interval":1,"recurring_end_date":"2017-11-14T12:25:29.964+04:00","time_last_update":"2016-11-14T13:36:57.539+04:00","time_create":"2016-11-14T13:36:19.429+04:00","shared":true,"starred":true,"time_track":false,"time_est":0,"time_spent":0,"priority":21760,"guid":"2141ab89-48ee-47b0-878e-c9ad304397b4","assignee":0,"version":2,"changed":true,"issue_id":"632","permission":100,"permissions":[{"level":60,"principal":"184769"},{"level":60,"principal":"184775"},{"level":100,"principal":"184743"}]}]

2. Create Item

2.1 Upload file

Mandatory params:

Param Type Description
session_id text User session.
file binary Content of file to upload.

Optional params:

Param Type Description
parent_id number Parent item identifier.

Response fields:

Field Type Description
id long Globally unique primary identifier for a file item.

3. Update Item

Response codes for Create and Update

HTTP code API Error code Description
200 Created/updated
400 73 Unable to add {principal X} because project/parent item is not shared with {principal X}.
400 74 {principal X} permission can not be {modified/added/removed} because it will conflict with parent {permission X} permissions.
400 75 {user X} can not be {assignee/participant} because they don’t have access to project {project name}.
400 76 Owner {owner name} is not allowed to change own permission.
400 77 Permission {principal X} downgrade to {permission X} is not allowed because parent has {permission Y} for this principal.
400 78 Cannot remove {assignee/participant} {user name} permission.
400 80 Short name already used.

4. Delete

Parameters: * {id}: unique id of item.

User performing delete request must have sufficient rights to delete this object

Possible HTTP return responses:

5. History

5.1 Retrieve item history including comments:

5.2 Add comment

Parameters: id: item id, message: comment body text

5.3 Delete comment

6. Archive

6.1 Archive item

Moves item to Archive

Parameters: * id or guid: id or guid of item to archive.

User performing request must have sufficient rights to archive specified item.

Possible HTTP return responses:

6.2. Restore item from archive

Parameters: * id or guid: id or guid of item to restore.

User performing request must have sufficient rights to restore specified item.

Possible HTTP return responses:

6.3. Restore copy of item from archive

Parameters: * id or guid: id or guid of item which copy to restore.

User performing request must have sufficient rights to restore specified item.

Possible HTTP return responses:

7. Multiple items operations

7.1 Delete multiple items

Parameters: * id: comma separated list of item identifiers (example: id=1,2,3).

User performing request must have sufficient rights to delete specified items. No error will be rised and item delete request simply ignored if user does not have rights to delete specific item.

Possible HTTP return responses:

7.2 Archive multiple items

Parameters: * id: comma separated list of item identifiers (example: id=1,2,3).

User performing request must have sufficient rights to archive specified items. No error will be rised and item archive request simply ignored if user does not have rights to archive specific item.

Possible HTTP return responses:

Tag

Operations with tags: add, remove, list tags

1. Get list of tags

Example response

[{"name":"privatetag","shared":false,"id":388730},{"name":"tag","shared":true,"id":388728},{"name":"тег","shared":true,"id":388729}]

Mandatory params:

Param Type Description
session_id text User session.

Response fields:

Field Type Description
id long Globally unique primary identifier for a tag.
name text Name of the tag.
shared boolean Indicates if tag linked to shared item or private item for current user.

Response codes

HTTP code API Error code Description
200 Returns array of tags.
400 4 API session is required.

2. Add tag

Example response

{"name":"new tag from api","shared":false,"id":388731}

Mandatory params:

Param Type Description
session_id text User session.
name text Name of the new tag.
item_id long Identifer of item.

Response fields:

Field Type Description
id long Globally unique primary identifier for a tag.
name text Name of the tag.
shared boolean Indicates if tag linked to shared item or private item for current user.

Response codes

HTTP code API Error code Description
200 Returns created tag.
400 4 Tag name is required.
400 4 Item ID is required.
404 1 Item not found.
403 3 No enough permissions to modify item.

3. Update tag

Example response

{"name":"update tag from api","shared":false,"id":388731}

Mandatory params:

Param Type Description
session_id text User session.
name text New name of the tag.
id long Identifer of tag (param is part of the URL).

Response fields:

Field Type Description
id long Globally unique primary identifier for a tag.
name text Name of the tag.
shared boolean Indicates if tag linked to shared item or private item for current user.

Response codes

HTTP code API Error code Description
200 Returns updated tag.
400 4 Tag name is required.
404 1 Tag not found.
403 3 No enough permissions to modify tag because no enough permissions to modify respective item.

4. Delete

Example response

{"response_status":0}

Mandatory params:

Param Type Description
id long Identifer of tag (param is part of the URL).

Response codes

HTTP code API Error code Description
200 Tag deleted.
404 1 Tag not found.
403 3 No enough permissions to delete shared tag.

Groups

Operations with user groups. Organize team and contacts into groups.

Get list of groups

Example response

[
{
id: "q9xsalg4tc7hrbaddh56fxg1ekuqrci39g8i2y7krmwa2qny8s5",
name: "Everyone",
code: "EVERYONE",
color: "#FFFFFF",
members: [
1866247,
1861630,
1866033,
1286619
],
type: 1
}
]

Response fields:

Field Type Description
id long Globally unique primary identifier
name String Group name
type int Group special type. If =1 then this is “Everyone” group containing all team members.

Add Group

Only user level Administrator can create group

parameters:

Update group

Update group. Only user level Administrator can update group

parameters:

Delete Group

Only user level Administrator can create group. This does not delete contacts. only group is deleted.

parameter:

Add Contact to Group

Add contact to the group

Only user level Administrator can add contact to the group

Remove Contact from a Group

Remove contact form the group

Only user level Administrator can add remove contact form the group.

Contact

Operations with user’s contacts: add, remove, list contacts

Get list of user’s contacts

Parameters

Parameter Type Description
includeSelf 1 or 0 Include current user.

Example response

{
email: "user@email.com"
emailConfirmed: "user@email.com"
firstName: "John"
id: 123
isOnline: false
lastName: "Jackson"
level: 100
login: "john"
pictureHash: "267744510460b6ec63453483f725252"
subscription: "BOTH"
}

Response fields:

Field Type Description
id long Globally unique primary identifier for a contact.
accountType String User’s account type: TEAM_BASIC, TEAM_BUSINESS, PERSONAL_FREE, PERSONAL_PREMIUM
login String user login id
firstName String user’s First Name
lastName String user’s Last Name
emailConfirmed String Email address that was confirmed by the user. (By clicking confirmaiton link sent to this email address.)
email String Email address that user entered but not confirmed. Do not send emails to this address as it may not be confirmed.
pictureHash String Unique address of user’s avatar picture.
To display the picture following URL composition should be used:
[http|https]://htiask.com/avatar/[pictureHash].[pixel size].gif
where pixel size is one of 16,40,64,80
subscription String Designates if contact request is sent or receved or if relationship is established.
Can be one of: FROM, TO, BOTH.
BOTH means contact relationship is established. FROM means request from this contact is received. TO means request was sent and we’re waiting for user to accept. SELF means this is the current user.

Add contact

Delete

Invite

Approve invitation

Add contact to Business account

Remove contact from Business account

Error handling

You need to check HTTP status in case there’s an error. Basic rule is to check that code is not 200. If it’s not 200 then expanded error code and error message will be in Json data.

When response statux is not 200 OK. The response contains Json date in format:

{
 "error_message" : "This is an error message";
 "response_status" : 1;
}

The API uses the following HTTP error codes:

Error Code Meaning
400 Bad Request –
401 Unauthorized – Your API key is wrong or unauthorized
403 Forbidden – The requested is forbidden
404 Not Found – The specified item could not be foun
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again later.