Deveo API v1

This is the home of stable Deveo RESTful API documentation. There are also two other API versions documented - deprecated v0 and experimental v2.

On these pages you'll find everything you need to know about the Deveo REST APIs. These give you access to all the data Deveo stores, and you will be able to build any clients and integrations you need.

This page introduces the general concepts used throughout all Deveo APIs, from authentication to the calling conventions and the error codes. To get information about specific types of data, use the navigation on the right.

API version

By default, all requests to Deveo APIs use the latest version, however, we recommend you to explicitly request the wanted version via the Accept header.

Accept: application/vnd.deveo.v1

API stability

Deveo APIs follow semantic versioning but only the major version number is used. Bug fixes and backwards compatible changes can be added to the same major version. Major Deveo releases may deprecate older version of APIs and introduce a new version, e.g.

Authentication

All requests (except login/logout) require the following set of keys to be present:

If you don't know your Company key and Account key, you can acquire them by authenticating with your company ID, login (email or user ID) and password:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.deveo.v1" \
  -d '{"company": "acme", "login": "chuck@norris.com", "password": "ChuckN0rr!5" }' \
  https://app.deveo.com/api/account/sessions

You will find the account_key, company_key and details of the account (that is either User, Collaborator, Project bot, or Company bot) and company in the response:

{
  "api_status": 201,
  "api_timestamp": "2014-12-02T12:26:01Z",
  "account_key": "ab187f75aa6322eff512bfe8ef97b292",
  "company_key": "553ae10f609b0a0d8ac9ebcceefb8d21",
  "account": {
    ...
  },
  "company": {
    ...
  }
}

You can use this same mechanism to implement Deveo authentication into your own tools and scripts: Prompt the user for their company, login (email or user ID) and password, and then execute the authentication request on their behalf. Then you can execute any other requests for them by using their account key and company key.

Finally, to logout the user permanently, you can invalidate the account_key with:

curl -X DELETE \
  -H "Accept: application/vnd.deveo.v1" \
  https://app.deveo.com/api/account/sessions/ab187f75aa6322eff512bfe8ef97b292

Authorization

Authorization is always done before you attempt to do anything via our APIs. However, sometimes you end up in a situation where you would like to know beforehand what you or the current user of your application has privileges to do in Deveo, e.g. to build a better user experience by hiding specific UI components and whatnot.

Luckily, Deveo has just what you need to accomplish this; we call them privileges. To read the privileges for a collection of objects or for a specific object is trivial and nearly all of our endpoints support the behavior. Basically all you need to do is to append one query parameter, namely privileges, to your RESTful requests and you're done.

Please note that the response for a collection of objects and for a specific object slightly differs. This is due to the fact that there isn't a point in asking whether or not one could update or delete a collection of objects, as such operations are always done against a specific object. To clear it up, we've provided you with some examples, you'll find them below.

Can I create and/or read projects in my company?

curl -X GET \
  -H "Accept: application/vnd.deveo.v1" \
  -H "Authorization: deveo company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
  https://app.deveo.com/api/projects?privileges
{
  "api_status": 200,
  "api_timestamp": "2014-01-10T08:05:03Z",
  "create": true,
  "read": true
}

Can I read, update, and/or delete the "platform" project in my company?

curl -X GET \
  -H "Accept: application/vnd.deveo.v1" \
  -H "Authorization: deveo company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
  https://app.deveo.com/api/projects/platform?privileges
{
  "api_status": 200,
  "api_timestamp": "2014-01-10T08:05:03Z",
  "read": true,
  "update": true,
  "delete": true
}

Can I create and/or read project bots of the "platform" project in my company?

curl -X GET \
  -H "Accept: application/vnd.deveo.v1" \
  -H "Authorization: deveo company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
  https://app.deveo.com/api/projects/platform/project_bots?privileges
{
  "api_status": 200,
  "api_timestamp": "2014-01-10T08:05:03Z",
  "create": true,
  "read": true
}

Can I read, update, and/or delete the "platform-jenkins" project bot of the "platform" project in my company?

curl -X GET \
  -H "Accept: application/vnd.deveo.v1" \
  -H "Authorization: deveo company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
  https://app.deveo.com/api/projects/platform/project_bots/platform-jenkins?privileges
{
  "api_status": 200,
  "api_timestamp": "2014-01-10T08:05:03Z",
  "read": true,
  "update": true,
  "delete": true
}

Can I create and/or read ssh keys of the "platform-jenkins" project bot of the "platform" project in my company?

curl -X GET \
  -H "Accept: application/vnd.deveo.v1" \
  -H "Authorization: deveo company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
  https://app.deveo.com/api/projects/platform/project_bots/platform-jenkins/ssh_keys?privileges
{
  "api_status": 200,
  "api_timestamp": "2014-01-10T08:05:03Z",
  "create": true,
  "read": true
}

Can I read, update, and/or delete the ssh key with id "4ead939eec4c207358000005" of the "platform-jenkins" project bot of the "platform" project in my company?

curl -X GET \
  -H "Accept: application/vnd.deveo.v1" \
  -H "Authorization: deveo company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
  https://app.deveo.com/api/projects/platform/project_bots/platform-jenkins/ssh_keys/4ead939eec4c207358000005?privileges
{
  "api_status": 200,
  "api_timestamp": "2014-01-10T08:05:03Z",
  "read": true,
  "update": true,
  "delete": true
}

Data objects

Here are the data objects you can access through the Deveo APIs, and the operations you can execute on them.

Each object, whatever its type, has an id attribute, which is its identifier and unique within the object type. That identifier can be used to refer to the object in other contexts.

Object Create Show List Update Destroy
Attachment
Branch
Bookmark
Code Review
Collaborator
Comment
Commit
Company
Company Bot
Event
Group
Group Member
Hook
Hook Service
License
Milestone
Password Recovery
Project
Project Bot
Project Collaborator
Project Group
Project Member
Project User
Repository
SSH Key
Tag
Task
User

HTTP methods

The API endpoints are used with the following HTTP methods:

Parameter nesting

All API endpoints support both nested and non-nested request parameters for POST and PUT requests. What this means is that you can do

curl -X POST \
  -H "Accept: application/vnd.deveo.v1" \
  -H "Authorization: deveo company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
  -H "Content-Type: application/json" \
  -d '{ "id": "norris", "email": "norris@deveo.com" }' \
  https://app.deveo.com/api/users

instead of

curl -X POST \
  -H "Accept: application/vnd.deveo.v1" \
  -H "Authorization: deveo company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
  -H "Content-Type: application/json" \
  -d '{ "user": { "id": "norris", "email": "norris@deveo.com" } }' \
  https://app.deveo.com/api/users

While the latter example still works, consider the non-nested form the official one for v1.

Attribute types

The data objects may have attributes with the following types:

boolean

true

string

"Åbo Akademi"

integer

11

timestamp

A timestamp in the ISO-8601 format (always UTC). Milliseconds are not included.

"2007-11-20-T22:19:17Z"

array

A list of other values.

[
  "Chuck Norris",
  "Clark Kent"
]

object

Another, nested API object.

{
  id: "norris",
  first_name: "Chuck",
  ...
}

Common attributes

Every API object has the following attributes:

api_status

The HTTP status code that describes the response status for this specific object.

When handling only one object, this is always the same as the status code in the HTTP header. However, with multiple objects each one might have a different status code. For instance, there may be a situation where half of a batch of objects could not be created.

api_status: 422

api_timestamp

The point in time when the response was created. As the state of the API objects can change, this timestamps each request so you know how recent the information is.

Note that with heavy requests, the returned objects might have API timestamps that differ from each other.

api_timestamp: "2012-01-22T22:11:11Z"

Most of the API objects have the following attributes:

created_at

The point in time when the object was created.

created_at: "2012-01-22T22:11:11Z"

updated_at

The point in time when the object was last updated.

updated_at: "2012-01-22T22:11:11Z"

Custom attributes

Some of the API objects allow storing custom attributes within the object using the properties attribute.

"properties": {
  "string": "value",
  "array": [
    1,
    2,
    3
  ],
  "object": {
    "nested": "value"
  }
}

Attributes in deactivated objects

When you delete an object in Deveo, it will usually be a "soft delete", where the object is not actually physically deleted, just deactivated. (Notable exceptions to this rule are project users, project groups, groups, group members, hooks and SSH keys).

When an object has been deactivated, you are still able to access it through the show endpoint, but you may not modify or restore it. When an object is deactivated, its identifier is renamed. For instance, from norris to norris-1234567.

All deactivated objects have two extra attributes:

deleted_at

Time of the deletion.

deleted_at: "2013-01-18T09:13:55Z"

old_id

Value of the original identifier before deletion.

old_id: "norris"

Error responses

Errors caused by API requests are identifiable by the HTTP status codes that are returned along with the responses. In an error situation, the API response includes the following attributes within the (invalid) API object:

api_status

HTTP status code.

api_status: 404

api_message

HTTP status message.

api_message: "Not Found"

api_errors

Related validation errors, grouped by attribute. See the next section for details.

{
  email: {
    invalid: true,
    conflicts: ["password"]
  },
  password: {
    conflicts: ["email"]
  }
}

Validation errors

When you try to create or update one or more objects and some of them are invalid, the API responds with the HTTP status code 422 Unprocessable Entity. The objects in the response have an api_errors attribute, which includes all the validation errors grouped by attribute.

Different field types may have different kinds of validation errors (see the object-specific references for details):

minimum

The given value is too short (strings), too low (int), or doesn't contain enough objects (arrays). The response contains the minimum value required.

minimum: 10

maximum

The given value is too long (strings), too high (int), or contains too many objects (arrays). The response contains the maximum value required.

maximum: 40

conflicts

The given value cannot be used with one or more of the other given values. In this case, these other attributes are also returned as incompatible. The array contains the names of the conflicting attributes.

conflicts: ["email"]

empty

The value for this attribute cannot be an empty string, 0 or false.

empty: true

invalid

The given value contains the characters that are not allowed, is of invalid type/format, or is otherwise illegal.

invalid: true

reserved

The given value is already in use or reserved for something else.

reserved: true

not_found

The referenced object was not found

not_found: true

locked

The given value can not be changed. Depending on the object type, some other user with different privileges might be able to change the value.

locked: true

Limiting results

The results of all list actions may be limited for purposes of paging or progressive loading. The responses have the following form:

{
  "metadata": {
    "more_results": true,
    "next_offset": 2,
    "count": 2
  },
  "results": [
    {
     "key": "value"
    },
    {
     "key": "value"
    },
  ]
}

The result is an object with two keys:

To limit the returned results of a request, pass the following arguments as query parameters in the request:

limit

Limits the amount of results returned. Use this to speed up the request when you know you don't need more than N results.

offset

Moves the starting point of the returned array from zero to the given number. Use this together with limit to implement pagination or other index-based result grouping.

before

Limits returned data to include only objects that were updated before the given point in time.

after

Limits returned data to include only objects that were updated after the given point in time.

active

By default only active objects are returned from the index endpoint. Use this flag to explicitly request deactivated objects.

Searching

search_term

A search term to look for. Use together with search_fields.

search_fields

Optionally limit the attributes to search, by default all the searchable attributes of the object are used. Use together with search_term. Refer to the object specific references to see the supported searchable attributes.

Sorting results

To sort results, pass the following arguments as query parameters in your request:

sort

The results are ordered naturally based on the value of the given attribute.

order

Sorts the results from low to high or high to low. Use together with order.

Child objects

When requesting objects that may have child objects related to them (for example, Projects may have Repositories), you can combine the fetching of those child objects to a single request. This can be done on several levels: You can count the child objects, get their IDs, or get them in full.

Refer to object-specific documentation for the possible child objects.

count

Count the numbers of child objects the requested object has. Specify the names of the attributes.

repositories: 32,
users: 15

list

List the IDs of child objects the requested object has. Specify the names of the attributes.

repositories: ["amiraali", "luotsi"]

include

Return child objects in full. Specify the names of the attributes.

repositories: [
  {
    id: "amiraali",
    type: "git",
    ...
  },
  ...
]

expand

Return linked objects in full. Specify the names of the attributes.

You can use expand in cases where the default behavior of the API is to specify an ID of a linked object, to expand the id to the linked object's full representation.

subject: {
  id: username,
  email: email@email.com,
  ...
}
Updated on: 11 May 2017