{% extends "docs/base.html" %} {% load pygmentize %} {% load static from staticfiles %} {% block title %}Vosae API Documentation{% endblock %} {% block meta_property_og_title %}Vosae API Documentation{% endblock %} {% block meta_property_twitter_title %}Vosae API Documentation{% endblock %} {% block resource %}

Vosae API

Summary

Welcome to the Vosae API documentation. This documentation describes the resources of Vosae's RESTful API. You must have a basic understanding of the principles of REST.

This is the same API used by the Vosae web application, so what we can do is also accomplishable by anyone.

The REST API is designed to give developers a convenient way to access all the data from Vosae.

If you experience any problems, have feature requests, a wrapper/implementation of the API, or anything else, please contact us (support@vosae.com), feedback and improvements are always welcome.


Quick start

Important The API is completely private. You have to be authenticated to make requests.


All requests MUST:

  1. Be in HTTPS
  2. Be authenticated
  3. Have the X-Tenant header set
  4. Contain the API version



Authentication

To be authenticated on the Vosae API backend you have to generate an API Key. It's very easy, and you can do it on the Vosae web app (Settings > Api Keys). Create a new application with a name and click Generate API Key. We'll give you the key just once and we can't recover it. If you lose the key your only choice is to Revoke the key an generate a new one.

Example:
Create api key



X-Tenant

In addition to the authentication, you need to provide the vosae tenant (eg. the organization) you want to use. You need to pass the header X-Tenant to each request to the Vosae API.
The only exception is for the Tenant endpoint. Through this endpoint you can list all tenants that the user has access to. The X-Tenant header value is the Tenant slug.



Rate Limiting

We limit requests to 4,000 per hour per user. You can check the returned HTTP headers of any API response to see your current status:

HTTP/1.1 200 OK
    Status: 200 OK
    X-RateLimit-Limit: 4000
    X-RateLimit-Remaining: 3983


Errors

The Vosae API uses conventional HTTP response codes to indicate success or failure of an API request. Which means, codes in the 2xx range indicate a success, codes in the 4xx range indicate an error, and codes in the 5xx range indicate an error on Vosae's servers.



First request

The whole API access is over HTTPS, and available through https://app.vosae.com/api/v1/.


The API supports:

Content-Type

Instead of providing the format in the uri we recommand to use the Content-Type header.

Important All requests must follow this layout:

curl --header "Authorization: ApiKey {user_email}:{user_apikey}" --header "X-Tenant: {tenant}" https://app.vosae.com/api/v1/{endpoint}



Example:

curl --header "Authorization: ApiKey maxime@naeka.fr:1234567890abcdefghijklmop" --header "X-Tenant: naeka" https://app.vosae.com/api/v1/tenant/

{{ sample_json|pygmentize:'json'|safe }}

{% endblock %}