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}. All requests must be made using HTTPS.
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 https://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