Codebase API Documentation

API Documentation

Codebase offers a powerful API allowing you to easily work with all the data stored in your account.

We'd suggest reading the information below before you start exploring the rest of the API as it contains important information which you may find useful.

Reading the documentation

We've split the documentation into sections based on the various objects available in Codebase. Each section includes information about all the available requests you can make as well as information about the object which should be sent.

When referencing the API URLs table, any variable with a yellow background should be replaced with the appropriate permalink or ID.

Authenticating & Accessing the API

Each user is provided a API key which can be located from the 'Settings > My Profile' page of the Codebase interface. This is a 40 character string which you must use along with your username to authenticate to the API. All API requests should be sent with HTTP Basic authentication with your account name, username & API key. Your HTTP Basic username should be crafted in the format of {account_name}/{username}. If you have SSL enabled on your account, you may make requests using the HTTPS protocol.

Requests should also send an Accept: application/xml and Content-type: application/xml header. All requests to the API should be in XML and all responses received will be returned as XML.

All request should be sent to the Codebase API domain at http(s)://api3.codebasehq.com along with the paths provided in this documentation.

You can see our adding & editing data examples for information about to create and update objects in Codebase using the API.

HTTP Status Codes

When sending requests to Codebase, you should check the HTTP status code returned to ensure the request was successful. The table below shows an example of what should usually be expected.

On Success On Failure
Finding a specific record 200 OK Requested record will be returned 404 Not Found No data will be returned
Finding a collection of records 200 OK Collection requested will be returned in an array 200 OK No data will be returned
Creating a new record 201 Created New record will be returned with a location header to the new object 422 Unprocessable Entity An array of error messages will be returned
Making changes to an existing record 200 OK No data will be returned 422 Unprocessable Entity An array of error messages will be returned
Deleting a record 200 OK No data will be returned 409 Conflict If the record has dependencies which block the deletion.

Other status codes you may receive will include:

  • 406 Not Acceptable - the HTTP verb supplied is not suitable for this action OR the action is not available using the API at this time.
  • 403 Forbidden - current user does not have access to requested resource