Voat API Documentation

You need to generate an Api Key for all v1 api calls (v1 api is any Api that has /api/v1/ as the path root).

Navigate to /apikeys to generate keys for your usage.

Once you have created your api key you need to add this key to the request header of every call.

    Voat-ApiKey: {your_public_api_key_here}

Open Authentication 2.0 is now fully supported. You have two choices to authenticate:

1. You can use full OAuth 2.0 by redirecting a client to our system for authentication using OAuth2.0 at the endpoint /oauth/authorize
2. You can access a token directly by providing all information to the endpoint /oauth/token * Please note, you can only authenticate directly using the account that owns the Voat Api Key.

Issue a post to /oauth/token endpoint with the following information:

    POST https://api.voat.co/oauth/token
    Content-Type: application/x-www-form-urlencoded
    Voat-ApiKey: {your_public_api_key_here}
    ==============================================
    Body:
    grant_type=password&username={username}&password={password}&client_id={public_api_key}&client_secret={private_api_key}

If the api key is valid and the username and password are correct you will receive a response similar to the following:

    {
    "access_token":"GbHN7QMzQRVpmqn1...",
    "token_type":"bearer",
    "expires_in":1295999,
    "userName":"{username}",
    ".issued":"Thu, 23 Apr 2015 00:26:02 GMT",
    ".expires":"Fri, 08 May 2015 00:26:02 GMT"
    }

You take the access_token value and assign it to a Header value for any api calls that require Auth. It is suggested you store it on the client (preferably in session durable storage as token expiration is typically extended).

    GET https://api.voat.co/api/v1/u/username/info
    Voat-ApiKey: {your_public_api_key_here}
    Authorization: Bearer {access_token_here}

After you recieve an access_token you can call the API. It is important that you change the request slighty from the token request. The API expects JSON data, while the token request expect FORM data.

Set the Content-Type header to application/json and ensure you are sending JSON encoded data in the body of requests that require data. See example below:

    POST https://api.voat.co/api/v1/v/subverse
    Content-Type: application/json
    Voat-ApiKey: {your_public_api_key_here}
    Authorization: Bearer {access_token_here}
    ==============================================
    Body:
    {"title":"This is my title","content":"This is my content"}

Some small things can cause the server to reject your request or error out attempting to process it. These are the most common issues new users have when using the API for the first time.

Not setting the Content-Type header to application/json

    Content-Type: application/json

Not sending JSON encoded data

JSON (Expected Format):

    {"title":"This is my title","content":"This is my content"}

FORM (Many client libraries default to encoding data in this format):

    title=This+is+my+title&content=This+is+my+content

Incorrectly setting the Authorization Header

The word Bearer is case sensitive and has be be followed by a single whitespace character before the access_token is appended.

    Authorization: Bearer {access_token_here}

For comment and submission endpoints you can include any querystrings specified in the SearchOptions object to manipulate your search request.

See definition of SearchOptions object: SearchOptions model.

The Voat API returns the same error structure that you should be prepared to handle in your app. Below are high level error statuses:

General Error Structure

{
    success: false, //all errors return false.
    error: {
        type: "NotFound", //the type of error that occured
        message: "Subverse 'IJustMakeUpStuff' does not exist." //a message describing error
    }
}

Here is a simple illustration of how you can handle Api responses taking into account errors.

    //*** THIS IS PSEUDO CODE ***
    /*

    This assumes MakeApiCall ignores the HttpStatus code of the call.
    You can check the HttpStatus also as this Api returns relevent
    status codes for every call. For example a "NotFound" error response
    will also include a 404 Http response code.
    */
    var response = MakeApiCall();

    if (response.success){
        //successfull call
        if (response.data != null && response.data.length > 0){
            //you have data in the response - loop it
        }
        ...

    } else {

        //error happened - lets see what kind of error it is
        var errorType = response.error.type;
        var errorMsg = response.error.message;
        switch (errorType){
            case "ApiThrottleLimit":
                //do something
                break;
            case "ApiRestricted":
                //do something
                break;
            case "NotFound":
                //submission/comment/user/etc wasn't found for request
                break;
            default:
                //do something
        }
        ...
    }

API Throttle Error

If your app crosses the throttle policy limit you will receive this response.

{
    success: false,
    error: {
        type: "ApiThrottleLimit",
        message: "{throttle_limit_error_message_here}"
    }
}

Invalid API Key

If there is any problems with your API Key you will recieve an "ApiKey" response.

{
    success: false,
    error: {
        type: "ApiKey",
        message: "Api key is missing or invalid"
    }
}

API Disabled / Restricted Error

If the API is put into a read-only or disabled state you will recieve an "ApiRestricted" response. Catch this in your app to deal with a temporarily limited API.

{
    success: false,
    error: {
        type: "ApiRestricted",
        message: "The Api is currently disabled."
    }
}

{
    success: false,
    error: {
        type: "ApiRestricted",
        message: "The Api is currently limited and does not have 'Write' permissions."
    }
}

Coming soon.

Default throttle policy for all API calls is: perSecond: 1, perMinute: 20, perHour: 200, perDay: 1500, perWeek: 3000.