Introduction

Welcome to the Quuu API. The API allows you to pull aspects of the Quuu experience into your own integration such as Categories, User suggestions, Links and more.

All data via the Quuu API is provided via RESTful means and is provided in the JSON format. There are no plans currently to provide the data in a XML format.

Authentication

Quuu uses keys to allow access to the API. You can register a new application by contacting us.

Non oAuth endpoints

For any endpoints that require non user specific data, Quuu requires that your application specific API key be provided on all request regardless of method as a Bearer Token in the Header. This will look like the following:

Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Please note that the API Key is different from a User Token and only API Keys which are application specific will be accepted.

Initialising oAuth Flow and connecting as a user

For endpoints that require oAuth Authentication, You will need to take a user through the authentication flow. This will allow them to authorise your application to read data about their account.

To start, You will need to send your users to the oAuth URL. This page can be configured as per your integration settings in the developer portal.

Redirect your user to the following URL to begin oAuth, replacing <app-id> with your application specific ID.

https://app.quuu.co/oauth/<app-id>/

If the user accepts the authorization, The user will redirected to your callback url as specified in your integration settings. A GET parameter will be passed with this URL with the key of code. The value of which will be an exchange token you can use to generate a user-token with using the Exchange oAuth Code endpoint.

Once the Exchange token has been swapped for a User Token, Quuu requires that this be provided on all request regardless of method as a Bearer Token in the Header. This will look like the following:

Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Exchange oAuth Code

curl --request POST \
  --url https://api.quuu.co/v1/auth/exchange/ \
  --header 'Accept: */*' \
  --header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  --header 'Cache-Control: no-cache' \
  --header 'Connection: keep-alive' \
  --form code=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

<?php
$postfields = array(
    'code' => 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',           
);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.quuu.co/v1/auth/exchange/');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 10);
curl_setopt($ch, CURLOPT_POST, count($postfields));
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($postfields));
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    "Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
));

$result = curl_exec($ch);
curl_close($ch);
$response = json_decode($result);

var data = new FormData();
data.append("code", "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx");

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.quuu.co/v1/auth/exchange/");
xhr.setRequestHeader("Authorization", "Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx");
xhr.setRequestHeader("Accept", "*/*");
xhr.setRequestHeader("Cache-Control", "no-cache");
xhr.setRequestHeader("Connection", "keep-alive");
xhr.send(data);

Should authentication be successful, the following will be returned:

{
    "success": true,
    "token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

This endpoint swaps an exchange token with a user token. This user token may be used as means of authentication with endpoints that require user tokens over api key based authentication. Data must be provided as POST form-data

HTTPS Request

POST https://api.quuu.co/v1/auth/exchange/

Authentication

The bearer token provided must be the Application specific API Key

Query Parameters

Parameter	Required	Description
code	true	The exchange code provided by the oAuth flow

Opengraph

Crawl URL

curl --request POST \
  --url https://api.quuu.co/v1/opengraph/crawl/ \
  --header 'Accept: */*' \
  --header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  --header 'Cache-Control: no-cache' \
  --header 'Connection: keep-alive' \
  --form Url=https://quuupromote.co

<?php
$postfields = array(
    'Url' => 'https://quuupromote.co',           
);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.quuu.co/v1/opengraph/crawl');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 10);
curl_setopt($ch, CURLOPT_POST, count($postfields));
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($postfields));
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    "Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
));

$result = curl_exec($ch);
curl_close($ch);
$response = json_decode($result);

var data = new FormData();
data.append("Url", "https://quuupromote.co");

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.quuu.co/v1/opengraph/crawl/");
xhr.setRequestHeader("Authorization", "Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx");
xhr.setRequestHeader("Accept", "*/*");
xhr.setRequestHeader("Cache-Control", "no-cache");
xhr.setRequestHeader("Connection", "keep-alive");
xhr.send(data);

Should authentication be successful, the following will be returned:

{
    "success": true,
    "data": {
        "title": "Quuu Promote - Promote your blog to real people via real people",
        "description": "Supercharge your blog promotion by using Quuu Promote. It drives engagement and traffic to your content automatically. ",
        "image": "https://quuupromote.co//platform/api/images/opengraph.png"
    }
}

This endpoint retrives data about a URL such as a thumbnail, title and description. This is useful for retrieving opengraph information. Data must be provided as POST form-data

HTTPS Request

POST https://api.quuu.co/v1/opengraph/crawl/

Authentication

The bearer token provided must be the Application specific API Key

Query Parameters

Parameter	Required	Description
Url	true	The Url of the website you want to crawl

Categories

Get all categories

curl --request GET \
  --url https://api.quuu.co/v1/categories/get \
  --header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  --header 'Cache-Control: no-cache' \
  --header 'Connection: keep-alive'

<?php


$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.quuu.co/v1/categories/get",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "Cache-Control: no-cache",
    "Connection: keep-alive",
  ),
));
$response = curl_exec($curl);
curl_close($ch);
$response = json_decode($result);

var data = null;
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
  if (this.readyState === 4) {
    console.log(this.responseText);
  }
});
xhr.open("GET", "https://api.quuu.co/v1/categories/get");
xhr.setRequestHeader("Authorization", "Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx");
xhr.setRequestHeader("Cache-Control", "no-cache");
xhr.setRequestHeader("Connection", "keep-alive");
xhr.send(data);

Should authentication be successful, the following will be returned:

{
    "success": true,
    "categories": [
        {
            "id": 367,
            "name": "3D Printing",
            "published_at": "2016-11-07 10:57:13"
        },
        {
            "id": 152,
            "name": "Accountancy",
            "published_at": "2016-03-22 09:41:39"
        },
        ...
    ]
}

This endpoint retrives all category names, and category id's that are published on Quuu and Quuu Promote

HTTPS Request

GET https://api.quuu.co/v1/categories/get/

Authentication

The bearer token provided must be the Application specific API Key

Get Category Links

curl --request GET \
  --url https://api.quuu.co/v1/categories/107/links/get?limit=10 \
  --header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  --header 'Cache-Control: no-cache' \
  --header 'Connection: keep-alive'

<?php


$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.quuu.co/v1/categories/107/links/get?limit=10",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "Cache-Control: no-cache",
    "Connection: keep-alive",
  ),
));
$response = curl_exec($curl);
curl_close($ch);
$response = json_decode($result);

var data = null;
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
  if (this.readyState === 4) {
    console.log(this.responseText);
  }
});
xhr.open("GET", "https://api.quuu.co/v1/categories/107/links/get?limit=10");
xhr.setRequestHeader("Authorization", "Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx");
xhr.setRequestHeader("Cache-Control", "no-cache");
xhr.setRequestHeader("Connection", "keep-alive");
xhr.send(data);

Should authentication be successful, the following will be returned:

{
    "success": true,
    "data": {
        "id": 107,
        "name": "Coffee",
        "published_at": "2016-02-04 11:04:27",
        "links": {
            "0": {
                "id": 243040,
                "url": "https://app.quuu.co/r/nraolal",
                "text": {
                    "long": "​With this complete guide to ​portable coffee makers you'll be armed with the all the information you need about how to choose a portable coffee maker and more! https://app.quuu.co/r/bgglbor",
                    "short": "With this complete guide to ​portable coffee makers you'll be armed with the all the information you need about how to choose a portable coffee maker and more! \n\nhttps://app.quuu.co/r/bgglbor via @ExploreHeroic #coffee"
                },
                "image": "https://heroic-adventures.com/wp-content/uploads/2019/04/Best-Portable-Coffee-Makers-2019-1024x512.jpg",
                "published_at": "2019-07-16 07:43:06",
                "expires_at": "2019-08-15 07:43:06"
            },
            ...
        }
    }
}

This endpoint retrives up to 100 published, live links from a given category.

HTTPS Request

GET https://api.quuu.co/v1/categories/get/

Authentication

The bearer token provided must be the Application specific API Key

Query Parameters

Parameter	Required	Description
limit	false	The number of links to return, Minimum 1, Maximum 100. If no limit is provided the default will be 10.

User

Get today's suggestions

curl --request GET \
  --url https://api.quuu.co/v1/user/suggestions/get \
  --header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  --header 'Cache-Control: no-cache' \
  --header 'Connection: keep-alive'

<?php


$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.quuu.co/v1/user/suggestions/get",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "Cache-Control: no-cache",
    "Connection: keep-alive",
  ),
));
$response = curl_exec($curl);
curl_close($ch);
$response = json_decode($result);

var data = null;
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
  if (this.readyState === 4) {
    console.log(this.responseText);
  }
});
xhr.open("GET", "https://api.quuu.co/v1/user/suggestions/get");
xhr.setRequestHeader("Authorization", "Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx");
xhr.setRequestHeader("Cache-Control", "no-cache");
xhr.setRequestHeader("Connection", "keep-alive");
xhr.send(data);

Should authentication be successful, the following will be returned:

{
    "success": true,
    "suggestions": {
        "0": {
            "link": {
                "category_id": 281,
                "text": {
                    "long": "There are a lot of myths people believe and mistakes they are making that stop them from growing their Instagram accounts.\r\nThis post shows you 21 Instagram marketing mistakes you should avoid if you want to get more followers and turn them into life-long fans. \r\nhttps://app.quuu.co/r/pnyrr-l",
                    "short": "Want to get more followers on #Instagram? Don’t make these 21 Mistakes https://app.quuu.co/r/pnyrr-l via @jan_orsula"
                },
                "url": "https://app.quuu.co/r/bgnrpbr",
                "published_at": "2019-07-16 07:43:07"
            },
            "profile": {
                "service_name": "quuu_co",
                "service": "twitter",
                "service_avatar": "https://pbs.twimg.com/profile_/platform/api/images/970043043557597184/ENVLjzIM.jpg",
                "created_at": "2019-01-10 13:29:07"
            },
            "created_at": "2019-07-23 02:29:20"
        },
        ...
    }
}

This endpoint retrives the authenticated user's suggestions for today

HTTPS Request

GET https://api.quuu.co/v1/user/suggestions/get

Authentication

The bearer token provided must be the User specific token retrieved via oAuth

Errors

An example of an error can be seen below:

{
    "success": false,
    "reason": "No category could be found for the provided Category ID.",
    "status": 400
}

If you run into an error whilst accessing the Quuu API the success boolean will be returned as a false. When this happens, a reason key will be provided and will indicate in plain english what the problem is. In the majority of error states, the status key will indicate the header response code. This will give a further indicator of the problem. All possible error status codes can be found below

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong.
403	Forbidden -- This API is for the Quuu Cruu only
404	Not Found -- This API endpoint does not exist
405	Method Not Allowed -- You tried to access this API endpoint using an invalid method. (eg using POST on a GET endpoint)
429	Too Many Requests -- You've hit your resource limits for the Quuu API. Please slow down!
500	Internal Server Error -- We ran into an issue, Send your request code over to us so we can get it patched up!
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.