Unit API API Reference

API provides access to user data

API Endpoint
https://api.unit.ms
Response Content-Types: application/json
Schemes: https
Version: 1.0.0

Authentication

oauth

authorizationUrl
https://api.unit.ms/v1/auth/oauth2/authorize
flow
implicit

Api

Api

Returns current API version

GET /api/version

Client MUST keep version of API what is was written for. If minor or major version was updated - client should offer to update it (if new version is available).

200 OK

Current API version

Response Example (200 OK) 
"string"
Api

Method for API testing

GET /api/test

Test API calls using this method

foo

Parameter with any value

type
string
in
query
200 OK
TestResponse

Response with given value

400 Bad Request
Error
  • foo_is_empty
Response Example (200 OK) 
{
  "foo": "string"
}
Response Example (400 Bad Request) 
{
  "error": "string"
}

Announcement

Announcement

Get last service announcement preview

GET /announcements/last/preview

Method returns short preview of last service announcement

200 OK
AnnouncementPreview

Announcement preview

401 Unauthorized
  • account_deleted
  • access_token_is_empty
  • access_token_not_valid
Response Example (200 OK) 
{
  "id": "integer",
  "title": "string",
  "background_color": "string",
  "text_color": "string",
  "url": "string",
  "published_at": "string (date-time)"
}
oauth basic

Url

Url

Get information about URL

GET /url/preview

Returns detailed information about URL, including title, preview image, etc.

url

target URL

type
string
in
query
200 OK
UrlPreview

URL info

400 Bad Request
Error
  • url_is_empty
  • url_not_valid
401 Unauthorized
Error
  • account_deleted
  • access_token_is_empty
  • access_token_not_valid
404 Not Found
Error
  • unable_to_load_url
Response Example (200 OK) 
{
  "id": "integer",
  "title": "string",
  "url": "string",
  "display_url": "string",
  "image": {
    "id": "integer (int32)",
    "url": "string",
    "width": "integer (int32)",
    "height": "integer (int32)",
    "size": "integer (int64)",
    "mime_type": "string"
  }
}
Response Example (400 Bad Request) 
{
  "error": "string"
}
Response Example (401 Unauthorized) 
{
  "error": "string"
}
Response Example (404 Not Found) 
{
  "error": "string"
}
oauth basic
Url

Get archived (gzip) web page

GET /url/archive

Returns web page by given URL as a single HTML file with inlined resources (css, images), File is packed in gzip. Field id from response should be used in URLElement.archive_file_id to attach archive to element. Archiving is available currently for html pages only.

url

target URL

type
string
in
query
200 OK
File

Archive file

400 Bad Request
Error
  • url_is_empty
  • url_not_valid
401 Unauthorized
Error
  • account_deleted
  • access_token_is_empty
  • access_token_not_valid
404 Not Found
Error
  • unable_to_load_url
Response Example (200 OK) 
{
  "id": "integer (int32)",
  "url": "string",
  "name": "string",
  "size": "integer (int64)",
  "mime_type": "string"
}
Response Example (400 Bad Request) 
{
  "error": "string"
}
Response Example (401 Unauthorized) 
{
  "error": "string"
}
Response Example (404 Not Found) 
{
  "error": "string"
}
oauth basic

Location

Location

Get venues around given location

GET /locations/venues

Returns array of found venues no further than 200m from given coordinates

lat

latitude

type
number (double)
in
query
lng

longitude

type
number (double)
in
query
query

search query

type
string
in
query
200 OK
Venue

Venues

400 Bad Request
Error
  • latitude_not_valid
  • longitude_not_valid
  • query_too_long
401 Unauthorized
Error
  • account_deleted
  • access_token_is_empty
  • access_token_not_valid
Response Example (200 OK) 
[
  {
    "name": "string",
    "lat": "number (double)",
    "lng": "number (double)",
    "address": "string"
  }
]
Response Example (400 Bad Request) 
{
  "error": "string"
}
Response Example (401 Unauthorized) 
{
  "error": "string"
}
oauth basic

User

User

Create a new user

POST /users

Creates a new user in terms of Unit API. Before using this method you should create user and at least one credential in Auth API.

credential_id

Auth credential ID

type
integer (int32)
in
formData
email

Email

type
string (6 to 100 chars)
in
formData
lang

Lang code. See https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes

type
string (2 to 2 chars)
in
formData
name

Имя (никнейм)

type
string (2 to 40 chars)
in
formData
timezone

Timezone, Europe/Moscow. Full list see here https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

type
string (1 to 32 chars)
in
formData
country_code

Country code [ISO 3166] in lower case. See https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2

type
string (2 to 2 chars)
in
formData
200 OK
RegistrationResult

Success registration result

400 Bad Request
Error
  • email_not_valid
  • lang_not_valid
  • name_too_short
  • name_too_long
  • name_not_valid
  • timezone_not_valid
  • country_code_not_valid
403 Forbidden
Error
  • email_already_registered
429 Too Many Requests
Error
  • too_many_requests
Response Example (200 OK) 
{
  "user": {
    "id": "integer",
    "name": "string",
    "email": "string",
    "timezone": "string",
    "country_code": "string",
    "lang": "string",
    "created_at": "string (date-time)",
    "updated_at": "string (date-time)",
    "is_deleted": "boolean",
    "deleted_at": "string (date-time)",
    "terminated_at": "string (date-time)",
    "is_email_verified": "boolean",
    "is_active": "boolean",
    "privilege": "string",
    "accounting": {
      "storage_limit": "number (integer)",
      "elements_limit": "integer",
      "plan": "string",
      "currency": "string",
      "active_since": "string (date-time)",
      "active_till": "string (date-time)",
      "renewal_period_months": "integer",
      "last_charged_at": "string (date-time)",
      "next_charge_at": "string (date-time)"
    }
  },
  "confirmation_hash": "string"
}
Response Example (400 Bad Request) 
{
  "error": "string"
}
Response Example (403 Forbidden) 
{
  "error": "string"
}
Response Example (429 Too Many Requests) 
{
  "error": "string"
}
User

Get user's public profile

GET /users/public-profile/{username}

Returns user's public profile by username or email. Public profile contains only public information that could be shown for everyone.

username

username or email

type
string
in
path
200 OK
PublicUserInfo

Public profile

404 Not Found
Error
  • user_not_found
Response Example (200 OK) 
{
  "id": "integer",
  "name": "string",
  "privilege": "string"
}
Response Example (404 Not Found) 
{
  "error": "string"
}
User

Get full user info

GET /users/self

Returns full user info about current signed in user

200 OK
User

User info

401 Unauthorized
Error
  • account_deleted
  • access_token_is_empty
  • access_token_not_valid
Response Example (200 OK) 
{
  "id": "integer",
  "name": "string",
  "email": "string",
  "timezone": "string",
  "country_code": "string",
  "lang": "string",
  "created_at": "string (date-time)",
  "updated_at": "string (date-time)",
  "is_deleted": "boolean",
  "deleted_at": "string (date-time)",
  "terminated_at": "string (date-time)",
  "is_email_verified": "boolean",
  "is_active": "boolean",
  "privilege": "string",
  "accounting": {
    "storage_limit": "number (integer)",
    "elements_limit": "integer",
    "plan": "string",
    "currency": "string",
    "active_since": "string (date-time)",
    "active_till": "string (date-time)",
    "renewal_period_months": "integer",
    "last_charged_at": "string (date-time)",
    "next_charge_at": "string (date-time)"
  }
}
Response Example (401 Unauthorized) 
{
  "error": "string"
}
oauth basic
User

Delete user account

DELETE /users/self

Marks user account as deactivated and revokes all user sessions. User account will be recovered in next 30 days, after that all data will be physically deleted.

200 OK

True if success

401 Unauthorized
Error
  • account_deleted
  • access_token_is_empty
  • access_token_not_valid
Response Example (200 OK) 
"boolean"
Response Example (401 Unauthorized) 
{
  "error": "string"
}
oauth basic
User

Log out user

POST /users/self/logout

Marks access token as deleted.

200 OK

Log out result

401 Unauthorized
Error
  • account_deleted
  • access_token_is_empty
  • access_token_not_valid
Response Example (200 OK) 
"boolean"
Response Example (401 Unauthorized) 
{
  "error": "string"
}
oauth basic
User

Recover deleted user

POST /users/self/recover

Make user account active again. Account could be recovered during 30 days after deletion.

200 OK

Recovered successfully.

400 Bad Request
Error
  • account_is_active
401 Unauthorized
Error
  • account_deleted
  • access_token_is_empty
  • access_token_not_valid
Response Example (200 OK) 
"boolean"
Response Example (400 Bad Request) 
{
  "error": "string"
}
Response Example (401 Unauthorized) 
{
  "error": "string"
}
oauth basic

Element

Element

Get root Unit

GET /elements/root

Returns root unit. Method should be used by web client. Other clients MUST fetch it during initial syncronization.

200 OK
UnitElement

Unit element

400 Bad Request
  • element_not_found
401 Unauthorized
Error
  • account_deleted
  • access_token_is_empty
  • access_token_not_valid
Response Example (200 OK) 
{
  "title": "string",
  "elements_order": [
    "string"
  ],
  "reminder": "string (date-time)",
  "due_date": "string (date)",
  "is_important": "boolean",
  "color": "string",
  "is_active": "boolean",
  "tags": [
    {
      "name": "string"
    }
  ],
  "sharing_options": {
    "is_public": "boolean",
    "recipients": [
      {
        "username": "string",
        "privilege": "string"
      }
    ]
  },
  "type": "string",
  "guid": "string",
  "usn": "integer (int32)",
  "local_id": "string"
}
Response Example (401 Unauthorized) 
{
  "error": "string"
}
oauth basic
Element

Get element children

GET /elements/{guid}/children

Returns list of children for given guid. Method is publicly available: data will be returned in two cases: if user is authenticated, and he is an owner of the element, or if element or one of its parents is public

guid

Unit GUID

type
string
in
path
200 OK
Element

Elements list

400 Bad Request
Error
  • guid_not_valid
404 Not Found
Error
  • element_not_found
Response Example (200 OK) 
[
  {
    "type": "string",
    "guid": "string",
    "usn": "integer (int32)",
    "local_id": "string"
  }
]
Response Example (400 Bad Request) 
{
  "error": "string"
}
Response Example (404 Not Found) 
{
  "error": "string"
}
Element

Get element parents

GET /elements/{guid}/parents

Returns list of parents for given guid in order from last to first. If user is authenticated, and he is an owner of the requested element - all parents will be returned. If user is NOT authenticated - all parents up to last public element will be returned

guid

Unit GUID

type
string
in
path
200 OK
Element

Elements list

400 Bad Request
Error
  • guid_not_valid
404 Not Found
Error
  • element_not_found
Response Example (200 OK) 
[
  {
    "type": "string",
    "guid": "string",
    "usn": "integer (int32)",
    "local_id": "string"
  }
]
Response Example (400 Bad Request) 
{
  "error": "string"
}
Response Example (404 Not Found) 
{
  "error": "string"
}
Element

Get elements

GET /elements

Returns list of elements by filters

tree

Return elements as tree

type
string
in
query
tag

Filter elements by tag

type
string
in
query
200 OK
Element

Elements array

400 Bad Request
Error
  • bad_request
401 Unauthorized
Error
  • account_deleted
  • access_token_is_empty
  • access_token_not_valid
Response Example (200 OK) 
{
  "type": "string",
  "guid": "string",
  "usn": "integer (int32)",
  "local_id": "string"
}
Response Example (400 Bad Request) 
{
  "error": "string"
}
Response Example (401 Unauthorized) 
{
  "error": "string"
}
Element

Save batch of elements

POST /elements

Response will contain array of updated elements with filled guid and usn (or updated for new elements)

Array of elements that should be inserted/updated. Client MUST provide consistent tree for update.

Element
Request Example
[
  {
    "type": "string",
    "guid": "string",
    "usn": "integer (int32)",
    "local_id": "string"
  }
]
200 OK
ElementBatchSaveResult

Array of updated elements

400 Bad Request
ErrorElementBatchSave
  • bad_request

Element errors Common errors

  • guid_not_valid
  • guid_is_empty
  • usn_is_empty
  • element_not_found
  • element_type_mismatch
  • element_detached
  • local_id_duplicated
  • child_exists_in_multiple_units
  • previous_parent_is_missing
  • element_is_missing
  • update_on_deleted_element
  • element_type_not_valid
  • expires_at_is_empty
  • trashed_from_is_empty
  • element_has_updates

Unit element errors

  • title_is_empty
  • title_too_long
  • system_unit_modification_not_valid
  • home_unit_not_found
  • trash_unit_not_found
  • too_many_elements
  • elements_order_has_excess_entries
  • elements_order_has_invalid_entries
  • color_not_valid
  • sharing_privilege_not_valid
  • tags_not_valid
  • too_many_tags

Toggle element errors

  • title_is_empty
  • title_too_long
  • too_many_elements
  • elements_order_has_invalid_entries

Text element errors

  • content_is_empty
  • content_too_long
  • unknown_list_type
  • is_checked_attribute_missed
  • is_checked_attribute_excess
  • unknown_header_type
  • list_type_attribute_excess

URL element errors

  • url_not_valid
  • url_too_long
  • url_title_too_long
  • image_not_found

Image element errors

  • image_not_found

File element errors

  • file_not_found

Audio element errors

  • audio_not_found

Video element errors

  • video_not_found
401 Unauthorized
Error
  • account_deleted
  • access_token_is_empty
  • access_token_not_valid
426 Upgrade Required
ErrorElementBatchSave
  • update_required
507 Insufficient Storage
Error
  • elements_quota_reached
Response Example (200 OK) 
{
  "max_usn": "integer (int32)",
  "elements": [
    {
      "guid": "string",
      "usn": "integer (int32)",
      "local_id": "string"
    }
  ],
  "deleted_elements": [
    "string"
  ]
}
Response Example (400 Bad Request) 
{
  "error": "string",
  "elements": [
    {
      "guid": "string",
      "local_id": "string",
      "error": "string"
    }
  ]
}
Response Example (401 Unauthorized) 
{
  "error": "string"
}
Response Example (426 Upgrade Required) 
{
  "error": "string",
  "elements": [
    {
      "guid": "string",
      "local_id": "string",
      "error": "string"
    }
  ]
}
Response Example (507 Insufficient Storage) 
{
  "error": "string"
}
oauth basic
Element

Get element

GET /elements/{guid}

Returns element data. Method is publicly available: element will be returned in two cases: if user is authenticated, and he is an owner of the element, or if element or one of its parents is public

guid

Element GUID

type
string
in
path
200 OK
Element

Element

400 Bad Request
Error
  • guid_not_valid
404 Not Found
Error
  • element_not_found
Response Example (200 OK) 
{
  "type": "string",
  "guid": "string",
  "usn": "integer (int32)",
  "local_id": "string"
}
Response Example (400 Bad Request) 
{
  "error": "string"
}
Response Example (404 Not Found) 
{
  "error": "string"
}
Element

Append batch of elements

POST /elements/{guid}

Response will contain array of updated elemets as in /elements

Array of elements to append

Element
guid

Element GUID

type
string
in
path
Request Example
[
  {
    "type": "string",
    "guid": "string",
    "usn": "integer (int32)",
    "local_id": "string"
  }
]
200 OK
ElementBatchSaveResult

Array of updated elements

400 Bad Request
ErrorElementBatchSave

Errors the same as for POST /elements

401 Unauthorized
Error
  • account_deleted
  • access_token_is_empty
  • access_token_not_valid
404 Not Found
Error
  • unit_not_found
409 Conflict
Error
  • change_not_consistent
Response Example (200 OK) 
{
  "max_usn": "integer (int32)",
  "elements": [
    {
      "guid": "string",
      "usn": "integer (int32)",
      "local_id": "string"
    }
  ],
  "deleted_elements": [
    "string"
  ]
}
Response Example (400 Bad Request) 
{
  "error": "string",
  "elements": [
    {
      "guid": "string",
      "local_id": "string",
      "error": "string"
    }
  ]
}
Response Example (401 Unauthorized) 
{
  "error": "string"
}
Response Example (404 Not Found) 
{
  "error": "string"
}
Response Example (409 Conflict) 
{
  "error": "string"
}
oauth basic
Element

Delete element

DELETE /elements/{guid}

Marks element as deleted

guid

Element GUID

type
string
in
path
200 OK
ElementBranchDeleteResult

Operation result

401 Unauthorized
Error
  • account_deleted
  • access_token_is_empty
  • access_token_not_valid
403 Forbidden
Error
  • root_unit_deletion_not_allowed
404 Not Found
Error
  • element_not_found
Response Example (200 OK) 
{
  "parent": {
    "guid": "string",
    "usn": "integer (int32)",
    "local_id": "string"
  },
  "deleted_elements": [
    "string"
  ]
}
Response Example (401 Unauthorized) 
{
  "error": "string"
}
Response Example (403 Forbidden) 
{
  "error": "string"
}
Response Example (404 Not Found) 
{
  "error": "string"
}
oauth basic
Element

Upload audio to element

POST /elements/{guid}/audio

Max file size - 50MB.
Allowed MIME-type:

  • audio/mp4
  • audio/aac
  • audio/mpeg
  • audio/m4a
guid

Element GUID

type
string
in
path
content

File binary contents

type
file (binary)
in
formData
200 OK
AudioElement

Updated audio element

400 Bad Request
Error
  • file_is_empty
  • element_not_found
401 Unauthorized
Error
  • account_deleted
  • access_token_is_empty
  • access_token_not_valid
413 Request Entity Too Large
Error
  • max_file_size_exceeded
415 Unsupported Media Type
Error
  • bad_file_type
507 Insufficient Storage
Error
  • quota_reached
Response Example (200 OK) 
{
  "title": "string",
  "artist": "string",
  "duration": "integer (int32)",
  "file_id": "integer (int32)",
  "file": {
    "id": "integer (int32)",
    "url": "string",
    "name": "string",
    "size": "integer (int64)",
    "mime_type": "string"
  },
  "type": "string",
  "guid": "string",
  "usn": "integer (int32)",
  "local_id": "string"
}
Response Example (400 Bad Request) 
{
  "error": "string"
}
Response Example (401 Unauthorized) 
{
  "error": "string"
}
Response Example (413 Request Entity Too Large) 
{
  "error": "string"
}
Response Example (415 Unsupported Media Type) 
{
  "error": "string"
}
Response Example (507 Insufficient Storage) 
{
  "error": "string"
}
oauth basic
Element

Upload video to element

POST /elements/{guid}/video

Max file size - 500MB.
Allowed MIME-type:

  • video/3gpp
  • video/3gpp2
  • video/h261
  • video/h263
  • video/h264
  • video/jpeg
  • video/jpm
  • video/mj2
  • video/mp2t
  • video/mp4
  • video/mpeg
  • video/ogg
  • video/quicktime
  • video/vnd.dece.hd
  • video/vnd.dece.mobile
  • video/vnd.dece.pd
  • video/vnd.dece.sd
  • video/vnd.dece.video
  • video/vnd.dvb.file
  • video/vnd.fvt
  • video/vnd.mpegurl
  • video/vnd.ms-playready.media.pyv
  • video/vnd.uvvu.mp4
  • video/vnd.vivo
  • video/webm
  • video/x-f4v
  • video/x-fli
  • video/x-flv
  • video/x-m4v
  • video/x-matroska
  • video/x-mng
  • video/x-ms-asf
  • video/x-ms-vob
  • video/x-ms-wm
  • video/x-ms-wmv
  • video/x-ms-wmx
  • video/x-ms-wvx
  • video/x-msvideo
  • video/x-sgi-movie
  • video/x-smv
guid

Element GUID

type
string
in
path
content

File binary contents

type
file (binary)
in
formData
200 OK
VideoElement

Updated video element

400 Bad Request
Error
  • file_is_empty
  • element_not_found
401 Unauthorized
Error
  • account_deleted
  • access_token_is_empty
  • access_token_not_valid
413 Request Entity Too Large
Error
  • max_file_size_exceeded
415 Unsupported Media Type
Error
  • bad_file_type
507 Insufficient Storage
Error
  • quota_reached
Response Example (200 OK) 
{
  "title": "string",
  "file_id": "integer (int32)",
  "file": {
    "id": "integer (int32)",
    "url": "string",
    "name": "string",
    "size": "integer (int64)",
    "mime_type": "string"
  },
  "type": "string",
  "guid": "string",
  "usn": "integer (int32)",
  "local_id": "string"
}
Response Example (400 Bad Request) 
{
  "error": "string"
}
Response Example (401 Unauthorized) 
{
  "error": "string"
}
Response Example (413 Request Entity Too Large) 
{
  "error": "string"
}
Response Example (415 Unsupported Media Type) 
{
  "error": "string"
}
Response Example (507 Insufficient Storage) 
{
  "error": "string"
}
oauth basic
Element

Upload image to element

POST /elements/{guid}/image

Max file size - 50MB.
Allowed MIME-type:

  • image/gif
  • image/jpeg
  • image/png
guid

Element GUID

type
string
in
path
content

File binary contents

type
file (binary)
in
formData
200 OK
ImageElement

Updated image element

400 Bad Request
Error
  • file_is_empty
  • element_not_found
401 Unauthorized
Error
  • account_deleted
  • access_token_is_empty
  • access_token_not_valid
413 Request Entity Too Large
Error
  • max_file_size_exceeded
415 Unsupported Media Type
Error
  • bad_file_type
507 Insufficient Storage
Error
  • quota_reached
Response Example (200 OK) 
{
  "image_id": "integer (int32)",
  "image": {
    "id": "integer (int32)",
    "url": "string",
    "width": "integer (int32)",
    "height": "integer (int32)",
    "size": "integer (int64)",
    "mime_type": "string"
  },
  "type": "string",
  "guid": "string",
  "usn": "integer (int32)",
  "local_id": "string"
}
Response Example (400 Bad Request) 
{
  "error": "string"
}
Response Example (401 Unauthorized) 
{
  "error": "string"
}
Response Example (413 Request Entity Too Large) 
{
  "error": "string"
}
Response Example (415 Unsupported Media Type) 
{
  "error": "string"
}
Response Example (507 Insufficient Storage) 
{
  "error": "string"
}
oauth basic
Element

Upload file to element

POST /elements/{guid}/file

Max file size - 1GB

guid

Element GUID

type
string
in
path
content

File binary contents

type
file (binary)
in
formData
200 OK
FileElement

Updated file element

400 Bad Request
Error
  • file_is_empty
  • element_not_found
401 Unauthorized
Error
  • account_deleted
  • access_token_is_empty
  • access_token_not_valid
413 Request Entity Too Large
Error
  • max_file_size_exceeded
507 Insufficient Storage
Error
  • quota_reached
Response Example (200 OK) 
{
  "title": "string",
  "file_id": "integer (int32)",
  "file": {
    "id": "integer (int32)",
    "url": "string",
    "name": "string",
    "size": "integer (int64)",
    "mime_type": "string"
  },
  "type": "string",
  "guid": "string",
  "usn": "integer (int32)",
  "local_id": "string"
}
Response Example (400 Bad Request) 
{
  "error": "string"
}
Response Example (401 Unauthorized) 
{
  "error": "string"
}
Response Example (413 Request Entity Too Large) 
{
  "error": "string"
}
Response Example (507 Insufficient Storage) 
{
  "error": "string"
}
oauth basic
Element

Upload url archive to element

POST /elements/{guid}/url_archive

Max url archive size - 100MB

guid

Element GUID

type
string
in
path
content

URL archive in webarchive format

type
file (binary)
in
formData
200 OK
URLElement

Updated URL element

400 Bad Request
Error
  • file_is_empty
  • element_not_found
401 Unauthorized
Error
  • account_deleted
  • access_token_is_empty
  • access_token_not_valid
413 Request Entity Too Large
Error
  • max_file_size_exceeded
507 Insufficient Storage
Error
  • quota_reached
Response Example (200 OK)
Response Example (400 Bad Request) 
{
  "error": "string"
}
Response Example (401 Unauthorized) 
{
  "error": "string"
}
Response Example (413 Request Entity Too Large) 
{
  "error": "string"
}
Response Example (507 Insufficient Storage) 
{
  "error": "string"
}
oauth basic
Element

Search elements

GET /search/elements

Fulltext search for all kinds of elements

200 OK
SearchResult

Search results

400 Bad Request
  • query_too_short
  • query_too_long
401 Unauthorized
Error
  • account_deleted
  • access_token_is_empty
  • access_token_not_valid
Response Example (200 OK) 
{
  "matches_total": "integer",
  "matches_presented": "integer",
  "match_groups": [
    {
      "type": "string",
      "matches_total": "integer",
      "matches": [
        {
          "element": {
            "type": "string",
            "guid": "string",
            "usn": "integer (int32)",
            "local_id": "string"
          },
          "parent": {
            "type": "string",
            "guid": "string",
            "usn": "integer (int32)",
            "local_id": "string"
          }
        }
      ]
    }
  ]
}
Response Example (401 Unauthorized) 
{
  "error": "string"
}
oauth basic

Sync

Sync

Information about account syncronization state"

GET /sync/state

API syncrinization is stateless. Each client after sync keeps max USN and could continue syncronization starting from this USN. This method returns current state of account to compare it with client's state.

200 OK
SyncState

Account syncronization state

401 Unauthorized
Error
  • account_deleted
  • access_token_is_empty
  • access_token_not_valid
Response Example (200 OK) 
{
  "current_time": "string (date-time)",
  "full_sync_time": "string (date-time)",
  "max_usn": "integer (int32)",
  "service_usage": {
    "storage_used": "number (integer)",
    "elements_number": "integer"
  }
}
Response Example (401 Unauthorized) 
{
  "error": "string"
}
oauth basic
Sync

Get chunk with data for syncronization

GET /sync/chunk

Returns chunk with data for syncronization: created and updated elements and GUID list of deleted objects

after_usn

USN that was last during previous syncronization. By default after_usn=0

type
integer
in
query
limit

Max num of changes that will be returned. Max value of limit is 100. By default limit=10

type
integer
in
query
skip_deleted

Deleted elements will not be returned. Helpful if you just need to fetch all data

type
boolean
in
query
200 OK
SyncChunk

List of account changes starting with after_usn. This changes should be applied to local client's DB

400 Bad Request
Error
  • after_usn_not_valid
  • limit_not_valid
401 Unauthorized
Error
  • account_deleted
  • access_token_is_empty
  • access_token_not_valid
Response Example (200 OK) 
{
  "current_time": "string (date-time)",
  "chunk_max_usn": "integer (int32)",
  "max_usn": "integer (int32)",
  "elements": [
    {
      "type": "string",
      "guid": "string",
      "usn": "integer (int32)",
      "local_id": "string"
    }
  ],
  "deleted_elements": [
    "string"
  ]
}
Response Example (400 Bad Request) 
{
  "error": "string"
}
Response Example (401 Unauthorized) 
{
  "error": "string"
}
oauth basic

Application

Application

Redirect to application

GET /application/redirect

Redirects user to Unit app or shows minimal landing page

202 Accepted

Current device couldn't be accepted, just show landing page

302 Found

Redirect to app

Payment

Payment

Register AppStore receipt

POST /payments/appstore

Method validates AppStore receipt and if receipt is valid - registers all payments, charged by this receipt

200 OK
ReceiptRegistrationResult

Receipt is valid and registered. User's plan updated successfully.

400 Bad Request
Error
  • receipt_is_empty
  • price_is_empty
  • price_format_is_invalid
  • currency_is_empty
  • currency_format_is_invalid
401 Unauthorized
Error
  • account_deleted
  • access_token_is_empty
  • access_token_not_valid
402 Payment Required
ReceiptRegistrationResult

Receipt is invalid.

Response Example (200 OK) 
{
  "success": "boolean",
  "appstore_code": "integer",
  "appstore_code_description": "string",
  "product_id": "string",
  "accounting": {
    "storage_limit": "number (integer)",
    "elements_limit": "integer",
    "plan": "string",
    "currency": "string",
    "active_since": "string (date-time)",
    "active_till": "string (date-time)",
    "renewal_period_months": "integer",
    "last_charged_at": "string (date-time)",
    "next_charge_at": "string (date-time)"
  }
}
Response Example (400 Bad Request) 
{
  "error": "string"
}
Response Example (401 Unauthorized) 
{
  "error": "string"
}
Response Example (402 Payment Required) 
{
  "success": "boolean",
  "appstore_code": "integer",
  "appstore_code_description": "string",
  "product_id": "string",
  "accounting": {
    "storage_limit": "number (integer)",
    "elements_limit": "integer",
    "plan": "string",
    "currency": "string",
    "active_since": "string (date-time)",
    "active_till": "string (date-time)",
    "renewal_period_months": "integer",
    "last_charged_at": "string (date-time)",
    "next_charge_at": "string (date-time)"
  }
}
oauth payments_appstore

Tag

Tag

Register AppStore receipt

GET /tags

Returns list of user tags

200 OK

List of user tags

401 Unauthorized
Error
  • account_deleted
  • access_token_is_empty
  • access_token_not_valid
Response Example (401 Unauthorized) 
{
  "error": "string"
}
oauth basic

Schema Definitions

User: object

id: integer
name: string
email: string
timezone: string
country_code: string
lang: string
created_at: string (date-time)
updated_at: string (date-time)
is_deleted: boolean

Flag that user is deleted

deleted_at: string (date-time)

RFC 3339 full-time. Time when user was deleted. Example: 1988-01-18T01:28:50.52Z

terminated_at: string (date-time)

RFC 3339 full-time. Time when user will be permanently deleted. Example: 1988-01-18T01:28:50.52Z

is_email_verified: boolean

Flag that email is verified

is_active: boolean
privilege: PrivilegeLevel
accounting: Accounting
Example
{
  "id": "integer",
  "name": "string",
  "email": "string",
  "timezone": "string",
  "country_code": "string",
  "lang": "string",
  "created_at": "string (date-time)",
  "updated_at": "string (date-time)",
  "is_deleted": "boolean",
  "deleted_at": "string (date-time)",
  "terminated_at": "string (date-time)",
  "is_email_verified": "boolean",
  "is_active": "boolean",
  "privilege": "string",
  "accounting": {
    "storage_limit": "number (integer)",
    "elements_limit": "integer",
    "plan": "string",
    "currency": "string",
    "active_since": "string (date-time)",
    "active_till": "string (date-time)",
    "renewal_period_months": "integer",
    "last_charged_at": "string (date-time)",
    "next_charge_at": "string (date-time)"
  }
}

Accounting: object

storage_limit: number (integer)

Total available storage for user in megabytes

elements_limit: integer

Max units number for user

plan: string , x ∈ { BASIC , PLUS }

Account plan

currency: string

Plan price currency

active_since: string (date-time)

RFC 3339 full-time. Time since when plan is active. Example: 1988-01-18T01:28:50.52Z

active_till: string (date-time)

RFC 3339 full-time. Time till when plan is active. Example: 1988-01-18T01:28:50.52Z

renewal_period_months: integer

Plan renewal period

last_charged_at: string (date-time)

RFC 3339 full-time. Time when user was charged last time. Example: 1988-01-18T01:28:50.52Z

next_charge_at: string (date-time)

RFC 3339 full-time. Time when user will be charged next time. Example: 1988-01-18T01:28:50.52Z

Example
{
  "storage_limit": "number (integer)",
  "elements_limit": "integer",
  "plan": "string",
  "currency": "string",
  "active_since": "string (date-time)",
  "active_till": "string (date-time)",
  "renewal_period_months": "integer",
  "last_charged_at": "string (date-time)",
  "next_charge_at": "string (date-time)"
}

ServiceUsage: object

Service usage statistics. Used to notify user that some limitations is coming.

storage_used: number (integer)

How much storage user already used

elements_number: integer

Number of active elements in user account

Example
{
  "storage_used": "number (integer)",
  "elements_number": "integer"
}

PublicUserInfo: object

Public info that could be available for everyone

id: integer
name: string
privilege: PrivilegeLevel
Example
{
  "id": "integer",
  "name": "string",
  "privilege": "string"
}

AnnouncementPreview: object

Announcement previews used in popups in mobile app / web to show news and other stuff to user

id: integer
title: string
background_color: string
text_color: string
url: string
published_at: string (date-time)
Example
{
  "id": "integer",
  "title": "string",
  "background_color": "string",
  "text_color": "string",
  "url": "string",
  "published_at": "string (date-time)"
}

RegistrationResult: object

Result of registration operation

user: User
confirmation_hash: string
Example
{
  "user": {
    "id": "integer",
    "name": "string",
    "email": "string",
    "timezone": "string",
    "country_code": "string",
    "lang": "string",
    "created_at": "string (date-time)",
    "updated_at": "string (date-time)",
    "is_deleted": "boolean",
    "deleted_at": "string (date-time)",
    "terminated_at": "string (date-time)",
    "is_email_verified": "boolean",
    "is_active": "boolean",
    "privilege": "string",
    "accounting": {
      "storage_limit": "number (integer)",
      "elements_limit": "integer",
      "plan": "string",
      "currency": "string",
      "active_since": "string (date-time)",
      "active_till": "string (date-time)",
      "renewal_period_months": "integer",
      "last_charged_at": "string (date-time)",
      "next_charge_at": "string (date-time)"
    }
  },
  "confirmation_hash": "string"
}

PrivilegeLevel: string , x ∈ { NORMAL , ADMIN }

Example
"string"

Image: object

id: integer (int32)
url: string
width: integer (int32)
height: integer (int32)
size: integer (int64)

File size in bytes

mime_type: string
Example
{
  "id": "integer (int32)",
  "url": "string",
  "width": "integer (int32)",
  "height": "integer (int32)",
  "size": "integer (int64)",
  "mime_type": "string"
}

File: object

id: integer (int32)
url: string
name: string

Original file name

size: integer (int64)

File size in bytes

mime_type: string
Example
{
  "id": "integer (int32)",
  "url": "string",
  "name": "string",
  "size": "integer (int64)",
  "mime_type": "string"
}

Guid: string

Unique object ID. Must be used for user data sync with API.

Example
"string"

UpdateSequenceNum: integer (int32)

Each data element has an "Update Sequence Number” (USN) that identifies the order in which it was last modified in the account. The USNs within an account start at "1" (for the first object created in the account) and then increase monotonically every time an object is created, modified, or deleted. At any point, the service is capable of ordering the objects in the account using their USN values. To synchronize, a client must only receive the objects that were changed after the last client sync. Besides, USN lets us know that object was updated and notify user about conflicts. If conflict occured client app should answer which version user want to keep.

Example
"integer (int32)"

UpdatedElement: object

Updated element contains guid, usn and local_id if it was given in original request

guid: Guid
usn: UpdateSequenceNum
local_id: string
Example
{
  "guid": "string",
  "usn": "integer (int32)",
  "local_id": "string"
}

Element: object

Abstract element, contains common fields

type: string
guid: Guid
usn: UpdateSequenceNum
local_id: string
Example
{
  "type": "string",
  "guid": "string",
  "usn": "integer (int32)",
  "local_id": "string"
}

TextElement:

Simple text element

content: string (up to chars)
list_type: string , x ∈ { BULLETED , NUMERIC , CHECKLIST }
header_type: string , x ∈ { H1 , H2 , H3 }
checked: boolean
Example
{
  "content": "string",
  "list_type": "string",
  "header_type": "string",
  "checked": "boolean",
  "type": "string",
  "guid": "string",
  "usn": "integer (int32)",
  "local_id": "string"
}

DividerElement:

Horizontal divider element

Example
{
  "type": "string",
  "guid": "string",
  "usn": "integer (int32)",
  "local_id": "string"
}

UnitElement:

Unit element is an element that could contain any other elements

title: string (up to chars)
elements_order: object[]

Ordered list of elements GUID's

reminder: string (date-time)

RFC 3339 full-time. Client MUST apply timezone before seting up reminder. Example: 1988-01-18T01:28:50.52Z

due_date: string (date)

RFC 3339 full-date that could be considered as unit deadline. Example: 2016-01-18

is_important: boolean

Unit marked as important

color: string , x ∈ { NONE , RED , ORANGE , YELLOW , GREEN , BLUE , INDIGO , VIOLET }

One of predefined colors. NONE means no color.

is_active: boolean true

Unit cound be marked as done. By default - true"

tags: object[]

Tags list. Max tags num per unit is 100

sharing_options: UnitSharingOptions
Example
{
  "title": "string",
  "elements_order": [
    "string"
  ],
  "reminder": "string (date-time)",
  "due_date": "string (date)",
  "is_important": "boolean",
  "color": "string",
  "is_active": "boolean",
  "tags": [
    {
      "name": "string"
    }
  ],
  "sharing_options": {
    "is_public": "boolean",
    "recipients": [
      {
        "username": "string",
        "privilege": "string"
      }
    ]
  },
  "type": "string",
  "guid": "string",
  "usn": "integer (int32)",
  "local_id": "string"
}

ToggleElement:

Toggle element

title: string (up to chars)
elements_order: object[]

Ordered list of elements GUID's

Example
{
  "title": "string",
  "elements_order": [
    "string"
  ],
  "type": "string",
  "guid": "string",
  "usn": "integer (int32)",
  "local_id": "string"
}

UnitSharingOptions: object

is_public: boolean

If unit is public - it will be accessible for everyone.

recipients: object[]

List of users with which unit is shared. In users accounts will be created LinkedUnit. If list is empty - unit is not shared. Username could be '*', then unit will be shared with everyone who have direct link.

Example
{
  "is_public": "boolean",
  "recipients": [
    {
      "username": "string",
      "privilege": "string"
    }
  ]
}

Tag: object

name: string (1 to 100 chars)
Example
{
  "name": "string"
}

ImageElement:

Image element. For performance purposes client should cache locally two images: for landscape and portrait layouts. Source image must be used only for zoom.

image_id: integer (int32)
image: Image
Example
{
  "image_id": "integer (int32)",
  "image": {
    "id": "integer (int32)",
    "url": "string",
    "width": "integer (int32)",
    "height": "integer (int32)",
    "size": "integer (int64)",
    "mime_type": "string"
  },
  "type": "string",
  "guid": "string",
  "usn": "integer (int32)",
  "local_id": "string"
}

AudioElement:

Audio element

title: string (1 to 250 chars)
artist: string (1 to 250 chars)
duration: integer (int32)
file_id: integer (int32)
file: File
Example
{
  "title": "string",
  "artist": "string",
  "duration": "integer (int32)",
  "file_id": "integer (int32)",
  "file": {
    "id": "integer (int32)",
    "url": "string",
    "name": "string",
    "size": "integer (int64)",
    "mime_type": "string"
  },
  "type": "string",
  "guid": "string",
  "usn": "integer (int32)",
  "local_id": "string"
}

VideoElement:

Video element

title: string (1 to 250 chars)
file_id: integer (int32)
file: File
Example
{
  "title": "string",
  "file_id": "integer (int32)",
  "file": {
    "id": "integer (int32)",
    "url": "string",
    "name": "string",
    "size": "integer (int64)",
    "mime_type": "string"
  },
  "type": "string",
  "guid": "string",
  "usn": "integer (int32)",
  "local_id": "string"
}

FileElement:

File element

title: string (1 to 250 chars)
file_id: integer (int32)
file: File
Example
{
  "title": "string",
  "file_id": "integer (int32)",
  "file": {
    "id": "integer (int32)",
    "url": "string",
    "name": "string",
    "size": "integer (int64)",
    "mime_type": "string"
  },
  "type": "string",
  "guid": "string",
  "usn": "integer (int32)",
  "local_id": "string"
}

UrlElement:

URL element. There are two cases for work with this element: 1) application could ask API for preview before sync. This is the best option. 2) application could create this element with one parameter - url, then preview image and header will be added automatically on API side, USN will be updated and app will receive update with image and header during next sync

url: string
preview_id: integer (int64)
preview: UrlPreview
archive_file_id: integer (int32)
archive_file: File
Example
{
  "url": "string",
  "preview_id": "integer (int64)",
  "preview": {
    "id": "integer",
    "title": "string",
    "url": "string",
    "display_url": "string",
    "image": {
      "id": "integer (int32)",
      "url": "string",
      "width": "integer (int32)",
      "height": "integer (int32)",
      "size": "integer (int64)",
      "mime_type": "string"
    }
  },
  "archive_file_id": "integer (int32)",
  "archive_file": {
    "id": "integer (int32)",
    "url": "string",
    "name": "string",
    "size": "integer (int64)",
    "mime_type": "string"
  },
  "type": "string",
  "guid": "string",
  "usn": "integer (int32)",
  "local_id": "string"
}

LocationElement:

Location element

name: string (up to chars)
address: string (up to chars)
lat: number (double) , { x ∈ ℝ | -90 ≤ x ≤ 90 }
lng: number (double) , { x ∈ ℝ | -180 ≤ x ≤ 180 }
Example
{
  "name": "string",
  "address": "string",
  "lat": "number (double)",
  "lng": "number (double)",
  "type": "string",
  "guid": "string",
  "usn": "integer (int32)",
  "local_id": "string"
}

UrlPreview: object

Information for pretty-printing URLs

id: integer
title: string (up to chars)
url: string
display_url: string
image: Image
Example
{
  "id": "integer",
  "title": "string",
  "url": "string",
  "display_url": "string",
  "image": {
    "id": "integer (int32)",
    "url": "string",
    "width": "integer (int32)",
    "height": "integer (int32)",
    "size": "integer (int64)",
    "mime_type": "string"
  }
}

SharingRecipient: object

Sharing recipient

username: string (1 to 255 chars)

User ID: username or email

privilege: SharedUnitPrivilegeLevel
Example
{
  "username": "string",
  "privilege": "string"
}

SharedUnitPrivilegeLevel: string , x ∈ { READ , READ_WRITE }

Example
"string"

SyncState: object

Account sync state. max_usn contains top USN in user account. After sync client must keep max USN to continue with it on next sync.

current_time: string (date-time)

Current UTC time in RFC 3339 full-time format

full_sync_time: string (date-time)

If last sync was before this date - client must run full sync: remove all local data and read all data from API. By default this date is equals to user registration time and could be changed by service, if happened changes that required full sync (archivation, removing old data, etc.). UTC time in RFC 3339 full-time format

max_usn: UpdateSequenceNum
service_usage: ServiceUsage
Example
{
  "current_time": "string (date-time)",
  "full_sync_time": "string (date-time)",
  "max_usn": "integer (int32)",
  "service_usage": {
    "storage_used": "number (integer)",
    "elements_number": "integer"
  }
}

SyncChunk: object

List of changes: new elements, deleted elements, etc.

current_time: string (date-time)

Current time in RFC 3339 full-time format

chunk_max_usn: UpdateSequenceNum
max_usn: UpdateSequenceNum
elements: object[]
deleted_elements: object[]
Example
{
  "current_time": "string (date-time)",
  "chunk_max_usn": "integer (int32)",
  "max_usn": "integer (int32)",
  "elements": [
    {
      "type": "string",
      "guid": "string",
      "usn": "integer (int32)",
      "local_id": "string"
    }
  ],
  "deleted_elements": [
    "string"
  ]
}

TestResponse: object

foo: string
Example
{
  "foo": "string"
}

Error: object

error: string

Error text code, for example "some_error"

Example
{
  "error": "string"
}

ElementBatchSaveResult: object

Batch save result

max_usn: UpdateSequenceNum
elements: object[]
deleted_elements: object[]
Example
{
  "max_usn": "integer (int32)",
  "elements": [
    {
      "guid": "string",
      "usn": "integer (int32)",
      "local_id": "string"
    }
  ],
  "deleted_elements": [
    "string"
  ]
}

ElementBranchDeleteResult: object

Element branch delete result

parent: UpdatedElement
deleted_elements: object[]
Example
{
  "parent": {
    "guid": "string",
    "usn": "integer (int32)",
    "local_id": "string"
  },
  "deleted_elements": [
    "string"
  ]
}

ErrorElementBatchSave: object

Batch save error

error: string

Error text code, for example "bad_data"

elements: object[]
Example
{
  "error": "string",
  "elements": [
    {
      "guid": "string",
      "local_id": "string",
      "error": "string"
    }
  ]
}

ElementError: object

guid: Guid
local_id: string

Element ID on client side if was given in request

error: string

Error text code, for example "element_detached"

Example
{
  "guid": "string",
  "local_id": "string",
  "error": "string"
}

ReceiptRegistrationResult: object

success: boolean
appstore_code: integer

AppStore validation error code. Empty is success=true

appstore_code_description: string

Error description. Empty is success=true

product_id: string

AppStore product id. Empty is success=false

accounting: Accounting
Example
{
  "success": "boolean",
  "appstore_code": "integer",
  "appstore_code_description": "string",
  "product_id": "string",
  "accounting": {
    "storage_limit": "number (integer)",
    "elements_limit": "integer",
    "plan": "string",
    "currency": "string",
    "active_since": "string (date-time)",
    "active_till": "string (date-time)",
    "renewal_period_months": "integer",
    "last_charged_at": "string (date-time)",
    "next_charge_at": "string (date-time)"
  }
}

SearchResult: object

matches_total: integer
matches_presented: integer
match_groups: object[]
Example
{
  "matches_total": "integer",
  "matches_presented": "integer",
  "match_groups": [
    {
      "type": "string",
      "matches_total": "integer",
      "matches": [
        {
          "element": {
            "type": "string",
            "guid": "string",
            "usn": "integer (int32)",
            "local_id": "string"
          },
          "parent": {
            "type": "string",
            "guid": "string",
            "usn": "integer (int32)",
            "local_id": "string"
          }
        }
      ]
    }
  ]
}

SearchMatchGroup: object

type: string
matches_total: integer
matches: object[]
Example
{
  "type": "string",
  "matches_total": "integer",
  "matches": [
    {
      "element": {
        "type": "string",
        "guid": "string",
        "usn": "integer (int32)",
        "local_id": "string"
      },
      "parent": {
        "type": "string",
        "guid": "string",
        "usn": "integer (int32)",
        "local_id": "string"
      }
    }
  ]
}

SearchMatch: object

element: Element
parent: Element
Example
{
  "element": {
    "type": "string",
    "guid": "string",
    "usn": "integer (int32)",
    "local_id": "string"
  },
  "parent": {
    "type": "string",
    "guid": "string",
    "usn": "integer (int32)",
    "local_id": "string"
  }
}

Venue: object

name: string
lat: number (double)
lng: number (double)
address: string
Example
{
  "name": "string",
  "lat": "number (double)",
  "lng": "number (double)",
  "address": "string"
}
Documentation by Spectacle