Page tree

We have updated our API Terms of Service. Please review the entire terms before continuing to use the API. Your use of the API means you accept and agree to the updated API Terms of Service found here:

Skip to end of metadata
Go to start of metadata


Version 5 of the API is currently under development.  On 2/15/18, we released an alpha developer preview of API v5. This is a very early release involving only the Animals endpoint.

This API will change in the coming months.  We would greatly appreciate your feedback and ideas for improvement.  However, perform development at your own risk.  We would expect changes to be relatively minor, but there's no guarantee.

Changes and improvements of note

  1. Closely follows the JSON API specification.  v2 was a completely custom and non-standard request and response structure.
  2. Uses industry standard HTTP verbs/methods (GET, PUT, etc) and endpoint URLs.  v2 used one URL and everything was a POST.
  3. API Key is accepted only on Authorization header.  In v2 the API Key was taken from the URL.
  4. Multiple sort values using +/- are supported.  In v2 only one sort field was supported with asc/desc.
  5. Random sort now available.  In v2 random was not available.
  6. Distance filter is it's own properties in POST body and supports either miles or kilometers.  In v2 the radius filter was included with any other filters.
  7. Related objects can be included in the response body but separate (eg., Organization along with Animals).  In v2 related object fields were either mixed with the requested object or an additional request to the API was necessary.
  8. Some fields are considered meta and returned separately from the other properties (see the meta Option).  In v2 all fields were the same, even if they were meta.
  9. Endpoint URLs can include view names to automatically add filters.  In v2 filters could only be added in the POST body.

Swagger definition available

You can download an early draft of our Swagger definition for the public API animals endpoint:

To open the definition go to the Swagger Editor and click File > Import URL and paste the URL above.

Postman collection available

Our Postman collection is currently out of date.  We're working to update it as soon as possible.

We also have a public Postman collection available to help you with examples.

Common questions

Question: When will this version of the API be available in production?

We don't have any ETA for production release yet.  We are hoping that it will be in production by mid-2018.

Question: Will the current APIs (v2 and the REST API) be deprecated?

Yes, we expect to discontinue use of the current APIs as some time after v5 goes live.  We will provide plenty of notice beforehand.  We expect to have multiple APIs running in production for a year or more.

  • No labels