About this API

This API is RESTful. It uses HTTP verbs in an expressive way like GET, DELETE, POST, PUT which will respectively GET, DELETE, create or upload data respectively.

This API uses JSON. It’s very easy to parse in most programming languages.

This API is described by Swagger. This makes it easy to auto generate clients in many languages and very easy to explore experimentally in our API console. This interactive console is linked in the API tab in the “Company Admin” section of your account.

This API uses OAuth 2.0 to manage authentication. Every request must be made with an OAuth 2.0 access token in the HTTP request headers. Please see our Authentication Guide

This API is evolving quickly. To see the complete list of methods with available options, please see our API explorer, available in the “Company Admin” section of your account.

This API is versioned and supported. As we make breaking changes we’ll create new methods and attempt to maintain compatibility for the old versions for some period of time. It’s important that your integration is “living” and updated frequently to match the evolution of the product. This is key for a successful and meaningful integration.

Available Methods

Some methods may not be appropriate to your type of account.

Some customers have their workspaces organized by hierarchical “accounts” while others have them organized by “workspace group.” To find out more about this distinction, please contact our support department.

Identifiers

You may be looking for a given record’s ID. Here, we use the term “hash.” For example, on the User model, the field “userHash” is the ID. You will use this to add users to spaces, subscribe users to documents, etc.

Paging

The JSON response of a query contains a “links” structure where the endpoint to first/last/previous/next page is presented when applicable. You can page through the results by simply visiting the desired endpoint returned from each query.

A “link” structure usually looks like this:

links {
  first: /v1/tasks?paging=first
  last: /v1/tasks?paging=last
  previous: /v1/tasks?paging=prev&paginationhash=xxxxxxx
  next: /v1/tasks?paging=next&paginationhash=yyyyyyy
}

By default, each query returns 25 items. You can override this by specifying the “limit” query parameter. For instance: /v1/tasks?limit=5.

If you don’t specify any pagination option (“paging” parameter) you will get the first page.

If your query contains sorting/filtering parameters they will be included in the urls as well.

When your response doesn’t contain first & previous urls it means you are on the first page and there’s no previous record. Similarly, if you don’t see next & last page you are on the last page and there are no additional items.

Sorting

You can sort the results by including a sorter parameter in the query. For instance, you’d like to sort all the tasks by their priority in ascending order:

/v1/tasks?sort=priority

If you want to sort in descending order simply prefixing the field name with a “-“ sign:

/v1/tasks?sort=-priority

If you try to sort a non-existing field or a field that doesn’t support sorting you will get a 400 bad request: /v1/tasks?sort=-firstname will give you “Invalid sorter(s): firstname”.

The Description column of the sorting parameter lists all available sortable fields for that endpoint.

Filtering

Endpoints with a filter parameter listed in the API Explorer allow users to narrow their results. The anatomy of a filter parameter’s value consists of the filter’s name, operator and value:

Filter: tags="Tag A"

URI: /v1/workspaces/allFiles?filter=tags%3D%22Tag%20A%22

Notice the value portion of a filter parameter must be URL encoded. In the example above, tags is the filter’s name, = (URL encoded to %3D) is the operator, and Tag A is the value. This will return only file models tagged with Tag A. Values for string-type fields must be encapsulated by double quotation marks.

To filter by multiple fields or multiple values of the same fields, append more filters with <space + ‘AND’ + space> such as:

Filter: tags="Tag A" AND tags="Tag B" AND status="Draft"

URI: /v1/workspaces/xxx/allFiles?filter=tags%3D%22Tag%20A%22%20AND%20tags%3D%22Tag%20B%22%20AND%20status%3D%22Draft%22

The example above will filter for items that have tags of Tag A and Tag B and with a status of Draft.

String type fields support = and startsWith operators. Note that startsWith only works for “tags” filter on /search/tags API for now.

Date type fields support = > < >= <= operators.

Filter: date<"2016-12-31" AND date>"2016-01-01"

URI: /v1/times?filter=date%3C%222016-12-31%22%20AND%20date%3E%222016-01-01%22

Here, only time records with a date between January 1, 2016 and December 31, 2016 are returned. All date values must be in ISO-8601 format and encapsulated by double quotation marks. See Operators Per Field Type for a list of available operators per field type and their usage.

Filter order does not matter since only AND relation between filters are supported. As a result, a filter of date<"2016-12-31" AND date>"2016-01-01" will return the same data as date>"2016-01-01" AND date<"2016-12-31".

URI: /v1/times?filter=date%3C%222016-12-31%22%20AND%20date%3E%222016-01-01%22
URI: /v1/times?filter=date%3E%222016-01-01%22%20AND%20date%3C%222016-12-31%22

Boolean type fields accept only true or false as valid values. They should not be double quoted. Passing in values other than true or false will result in an Invalid Request error.

Numeric type fields support = > < >= <= operators and the values should not be double quoted.

As in sorting, attempting to filter on a non-existing or unsupported field will result in a 400 bad request. The Description column for the filter parameter lists all available filterable fields for that endpoint.

Operators Per Field Type

String or ID

Boolean

Date

Status Codes

Edge, being a RESTful service, supports the following HTTP status codes. If a specific endpoint returns codes that are not listed here they would be described on the API document page.

200 OK 201 Created 204 No Content - Indicating a known resource is successfully updated. For instance, a 204 from POST /v1/files/{fileId}/lock indicating file {fileId} is locked successfully. a 204 from DELETE /v1/times/{timeId} indicating time entry {fileId} is deleted successfully.

400 Bad Request 401 Unauthorized 403 Forbidden - Trying to access a resource without permission. 404 Not Found 409 Conflict

500 Internal Server Error - Something unexpected happens in Edge. 503 Service Unavailable - Requested resource is currently unavailable.