NAV
curl Ruby Node.js

Introduction

# API endpoint:
'https://www.narro.co/api/v1'
# API endpoint:
'https://www.narro.co/api/v1'
// API endpoint:
'https://www.narro.co/api/v1'

Welcome to the Narro API documentation! You can use our API to access articles and readings, as well as submit them on behalf of customers.

The Narro API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website’s client-side code). JSON is returned by all API responses, including errors, although our API libraries convert responses to appropriate language-specific objects.

This API documentation is openly hosted on GitHub, which means you can contribute or edit by submitting a pull request.

Authentication

require 'uri'
require 'net/http'

url = URI("https://www.narro.co/api/v1")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Bearer <access_token>'

response = http.request(request)
puts response.read_body
var request = require("request");

var options = {
    method: 'GET',
    url: 'https://www.narro.co/api/v1',
    headers: {
        authorization: 'Bearer <access_token>'
    }
};

request(options, function (error, response, body) {
    if (error) throw new Error(error);
    console.log(body);
});
curl --request GET \
    --url https://www.narro.co/api/v1 \
    --header 'authorization: Bearer <access_token>'

Narro API clients use the OAuth2 flow to request an access token. Clients then use access tokens to access the API on behalf of Narro accounts. You can register a new Narro API client/application, view your applications, and generate credentials at our developer portal.

Narro expects the Bearer access token to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer <access_token>

If you would like to view an example application/server implementing the OAuth2 flow with Narro’s API, we have provided an example in our platform_samples repository.

Account

Retrieve Account Details

require 'uri'
require 'net/http'

url = URI("https://www.narro.co/api/v1/account")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer <access_token>'

response = http.request(request)
puts response.read_body
var request = require("request");

var options = {
    method: 'GET',
    url: 'https://www.narro.co/api/v1/account',
    headers: {
        authorization: 'Bearer <access_token>',
        accept: 'application/json'
    }
};

request(options, function (error, response, body) {
    if (error) throw new Error(error);
    console.log(body);
});
curl --request GET \
    --url https://www.narro.co/api/v1/account\
    --header 'accept: application/json' \
    --header 'authorization: Bearer <access_token>'

Example response:

{
    "confirmed": true,
    "created": "2015-12-02T02:11:53.250Z",
    "email": "[email protected]",
    "id": "accountid123456789",
    "image": "",
    "modified": "2016-02-28T20:18:24.349Z",
    "pro": true,
    "vanity": "vanity123",
    "rate": 1,
    "voices": [
        {
            "gender": "Male",
            "language": "en-US",
            "name": "Joey"
        },
        {
            "gender": "Female",
            "language": "en-US",
            "name": "Ava"
        }
    ]
}

Retrieves the details of the authenticating user’s account.

See an example request in many languages.

HTTP Request

GET https://www.narro.co/api/v1/account

Attributes

Name Type Description
confirmed boolean Indicated whether the account has been confirmed via email
created timestamp Creation date, formatted to ISO datetime
email string Account’s recorded email address
id string Unique ID for this account resource
image string Optional image used in account’s public podcast syndication
modified timestamp Date of last modification, formatted to ISO datetime
pro boolean Indicates whether the account is Pro-level
vanity string Unique ID used for the account’s public podcast URL
voices array Chosen voices to be used for readings under this account
rate number Chosen rate for readings under this account

Articles

Retrieve an Article

require 'uri'
require 'net/http'

url = URI("https://www.narro.co/api/v1/articles/56ca50f7c1dac403006bb309")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer <access_token>'

response = http.request(request)
puts response.read_body
var request = require("request");

var options = {
    method: 'GET',
    url: 'https://www.narro.co/api/v1/articles/56ca50f7c1dac403006bb309',
    headers: {
        authorization: 'Bearer <access_token>',
        accept: 'application/json'
    }
};

request(options, function (error, response, body) {
    if (error) throw new Error(error);
    console.log(body);
});
curl --request GET \
    --url https://www.narro.co/api/v1/articles/56ca50f7c1dac403006bb309 \
    --header 'accept: application/json' \
    --header 'authorization: Bearer <access_token>'

Example response:

{
    "active": true,
    "audio": {
        "length": 77.635918,
        "url": "https://s3.amazonaws.com/nareta-articles/accounts/540cc8cb48e3e80200000001/145669484056d366369ba562.mp3",
        "voice": "Ava",
        "rate": 1
    },
    "created": "2016-02-28T21:27:18.724Z",
    "description": "Narro is the simple way to listen to the web - a text to speech podcast app. Narro will take your bookmarked articles and read them back to you as a podcast.",
    "favicon": "https://www.narro.co/images/favicon.png",
    "id": "56d36633b40e600300583bfb",
    "image": "http://www.narro.co/images/narro.png",
    "language": "en-US",
    "links": [
        {
            "href": "https://www.narro.co/contact",
            "text": "contact us"
        }
    ],
    "location": "https://www.narro.co/article/56d36633b40e600300583bfb",
    "preview": false,
    "title": "My Optional, Custom Title",
    "url": "https://www.narro.co/faq",
    "via": "api"
}

Retrieves the details of an article that has previously been created. Supply the unique article ID that was returned from your previous request, and Narro will return the corresponding article information. A subset of this information is returned when creating or listing the article.

See an example request in many languages.

HTTP Request

GET https://www.narro.co/api/v1/articles/<ID>

URL Parameters

Parameter Description
ID The ID of the article to retrieve

Attributes

Name Type Description
active boolean Indicates whether this article is available in the user’s podcast feed
audio.url string URL to the article’s audio MP3 file
audio.length number Length of article MP3, in seconds
audio.rate number Reading rate of article, expressed in ratio to ‘normal’
audio.voice string Voice used to read article
created timestamp ISO-formatted creation datetime
description string Extracted article description
favicon string Path to the article’s publisher’s favicon (Absent for plain-text readings)
id string Unique ID for this article resource
image string If found during extraction, an image representing the article
language string Detected language of this article
links array Extracted links from the article text, each comprising an href string and text sring (Absent for plain-text readings)
location string Location of this article within Narro’s site
preview boolean Indicates whether this article was read in “preview” mode, which truncates the reading
title string Extracted or provided article title
url string The original URL provided for this article
via string The source through which the article was submitted to Narro

List All Articles

require 'uri'
require 'net/http'

url = URI("https://www.narro.co/api/v1/articles?limit=1")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer <access_token>'

response = http.request(request)
puts response.read_body
var request = require("request");

var options = {
    method: 'GET',
    url: 'https://www.narro.co/api/v1/articles',
    qs: {
        limit: '1'
    },
    headers: {
        authorization: 'Bearer <access_token>',
        accept: 'application/json'
    }
};

request(options, function (error, response, body) {
    if (error) throw new Error(error);
    console.log(body);
});
curl --request GET \
    --url 'https://www.narro.co/api/v1/articles?limit=1' \
    --header 'accept: application/json' \
    --header 'authorization: Bearer <access_token>'

Example response:

{
    "data": [
        {
            "active": true,
            "audio": {
                "length": 77.635918,
                "url": "https://s3.amazonaws.com/nareta-articles/accounts/540cc8cb48e3e80200000001/145669484056d366369ba562.mp3",
                "voice": "Ava",
                "rate": 1
            },
            "created": "2016-02-28T21:27:18.724Z",
            "description": "Narro is the simple way to listen to the web - a text to speech podcast app. Narro will take your bookmarked articles and read them back to you as a podcast.",
            "favicon": "https://www.narro.co/images/favicon.png",
            "id": "56d36633b40e600300583bfb",
            "image": "http://www.narro.co/images/narro.png",
            "language": "en-US",
            "links": [],
            "location": "https://www.narro.co/article/56d36633b40e600300583bfb",
            "preview": false,
            "title": "My Optional, Custom Title",
            "url": "https://www.narro.co/faq",
            "via": "api"
        }
    ],
    "meta": {
        "next": "/api/v1/articles?limit=1&skip=1"
    }
}

Returns a list of articles previously created by the user. The articles are returned in sorted order, with the most recent articles appearing first.

See an example request in many languages.

HTTP Request

GET https://www.narro.co/api/v1/articles

Query Parameters

Parameter Default Description
limit 20 If specified, resulting dataset will be limited to count.
skip 0 If specified, resulting dataset will skip first records.

Article Submission

require 'uri'
require 'net/http'

url = URI("https://www.narro.co/api/v1/articles")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["accept"] = 'application/json'
request["content-type"] = 'application/json'
request["authorization"] = 'Bearer <access_token>'
request.body = "{\"url\": \"https://www.narro.co/faq\", \"title\": \"My Optional, Custom Title\"}"

response = http.request(request)
puts response.read_body
var request = require("request");

var options = { method: 'POST',
    url: 'https://www.narro.co/api/v1/articles',
    headers: {
        authorization: 'Bearer <access_token>',
        'content-type': 'application/json',
        accept: 'application/json'
    },
    body: {
        url: 'https://www.narro.co/faq',
        title: 'My Optional, Custom Title'
    },
    json: true
};

request(options, function (error, response, body) {
    if (error) throw new Error(error);
    console.log(body);
});
curl --request POST \
    --url https://www.narro.co/api/v1/articles \
    --header 'accept: application/json' \
    --header 'authorization: Bearer <access_token>' \
    --header 'content-type: application/json' \
    --data '{"url": "https://www.narro.co/faq", "title": "My Optional, Custom Title"}'

Example response:

{
    "data": [
        {
            "active": true,
            "audio": {
                "url": null
            },
            "created": "2016-02-28T21:27:15.409Z",
            "description": "Narro is the simple way to listen to the web - a text to speech podcast app. Narro will take your bookmarked articles and read them back to you as a podcast.",
            "favicon": "https://www.narro.co/images/favicon.png",
            "id": "56d36633b40e600300583bfb",
            "image": "http://www.narro.co/images/narro.png",
            "language": "en-US",
            "links": [],
            "location": "https://www.narro.co/article/56d36633b40e600300583bfb",
            "preview": false,
            "title": "My Optional, Custom Title",
            "url": "https://www.narro.co/faq",
            "via": "api"
        }
    ],
    "meta": {}
}

Create an article for any web page that you would like to hear! The article must be located at a publicly accessible URL. The article text will be automatically extracted, and read in the voice (or one of the voices in a selected rotation) selected by the user. The written language of the article will be automatically detected by sample, and an appropriate voice will be selected if the language is not native to the user.

See an example article request in many languages. See an example plain-text request in many languages.

HTTP Request

POST https://www.narro.co/api/v1/articles

Body Parameters

Parameter Type Description
url string The publicly accessible URL for content to be read. This field is required unless text is specified.
title string If specified, this string will be used as the title of the resulting article.
text string If specified, this field’s value will be read. This will override any content residing at the url. Please choose to pass either url or text.

Search

Search Articles

require 'uri'
require 'net/http'

url = URI("https://www.narro.co/api/v1/search/articles?limit=2&term=Trump")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer <access_token>'

response = http.request(request)
puts response.read_body
var request = require("request");

var options = {
    method: 'GET',
    url: 'https://www.narro.co/api/v1/search/articles?limit=2&term=Trump',
    headers: {
        authorization: 'Bearer <access_token>',
        accept: 'application/json'
    }
};

request(options, function (error, response, body) {
    if (error) throw new Error(error);
    console.log(body);
});
curl --request GET \
    --url https://www.narro.co/api/v1/search/articles?limit=2&term=Trump\
    --header 'accept: application/json' \
    --header 'authorization: Bearer <access_token>'

Example response:

{
    "data": [
        {
            "active": true,
            "audio": {
                "length": 332.956735,
                "url": "https://s3.amazonaws.com/nareta-articles/audio/540cc8cb48e3e80200000001/30460753-b4b5-468d-8a4d-dabcb384dc1a.mp3",
                "voice": "Salli",
                "rate": 1
            },
            "created": "2016-02-23T17:31:11.925Z",
            "description": "By Miranda Popkey \u00a0 \u00a0\n\u00a0\u00a0\nCyclone Winston, the second most powerful storm ever recorded in the South Pacific, made landfall in Fiji with 40-foot waves ...",
            "id": "56cc9751750df10300610bf7",
            "image": null,
            "language": "en-US",
            "links": [],
            "location": "https://www.narro.co/article/56cc9751750df10300610bf7",
            "preview": false,
            "title": "Email Fwd: Harper's Weekly Review",
            "url": "https://www.narro.co/article/56cc9751750df10300610bf7",
            "via": "email"
        },
        {
            "active": true,
            "audio": {
                "length": 65.201633,
                "url": "https://s3.amazonaws.com/nareta-articles/audio/540cc8cb48e3e80200000001/89a7eac8-9363-44ea-9624-0b107b4fe221.mp3",
                "voice": "Salli",
                "rate": 1
            },
            "created": "2016-02-11T20:10:43.653Z",
            "description": "by Brent Simmons\nIt Will Be Trump\nThe South Carolina primary is where the establishment fixes the errors of Iowa and New Hampshire. It's Lee Atwater's...",
            "id": "56bceac153625e03007f0172",
            "image": null,
            "language": "en-US",
            "links": [],
            "location": "https://www.narro.co/article/56bceac153625e03007f0172",
            "preview": false,
            "title": "It Will Be Trump",
            "url": "http://inessential.com/2016/02/11/it_will_be_trump",
            "via": "feed"
        }
    ],
    "meta": {
        "term": "Trump"
    }
}

Given a search term, retrieve the authenticating user’s articles containing that term. A search term can be any combination of words extracted from the article body.

See an example request in many languages.

HTTP Request

GET https://www.narro.co/api/v1/search/articles?limit=2&term=Trump

Query Parameters

Parameter Default Description
term Required in query string, resulting articles will contain this set of terms in their body text.
limit 20 If specified, resulting dataset will be limited to count.
skip 0 If specified, resulting dataset will skip first records.

Article to Fit

Find a Fitting Article

require 'uri'
require 'net/http'

url = URI("https://www.narro.co/api/v1/fit?time=60&topic=Trump")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer <access_token>'

response = http.request(request)
puts response.read_body
var request = require("request");

var options = {
    method: 'GET',
    url: 'https://www.narro.co/api/v1/fit?time=60&topic=Trump',
    headers: {
        authorization: 'Bearer <access_token>',
        accept: 'application/json'
    }
};

request(options, function (error, response, body) {
    if (error) throw new Error(error);
    console.log(body);
});
curl --request GET \
    --url https://www.narro.co/api/v1/fit?time=60&topic=Trump\
    --header 'accept: application/json' \
    --header 'authorization: Bearer <access_token>'

Example response:

{
    "data": [
        {
            "active": true,
            "audio": {
                "length": 60.944333,
                "url": "https://s3.amazonaws.com/nareta-articles/audio/55af0a83157eed030000011e/61e7b167-b3f9-4d21-b2b2-2f184242b5cc.mp3",
                "voice": "Brian",
                "rate": 1
            },
            "created": "2015-08-06T14:51:26.342Z",
            "description": "In The Wall Street Journal, Joe Queenan says Donald Trump clearly works for Hillary. When Clinton wins, Trump gets to install luxury condos in the Washington Monument.",
            "favicon": null,
            "id": "55c3746e8f828f030000008b",
            "image": "http://si.wsj.net/public/resources/images/BN-JQ873_queena_D_20150731124328.jpg",
            "language": "Brian",
            "links": [],
            "location": "https://www.narro.co/article/55c3746e8f828f030000008b",
            "title": "Clearly, the Donald Works for Hillary",
            "url": "http://www.wsj.com/articles/clearly-the-donald-works-for-hillary-1438382894",
            "via": "web"

        }
    ],
    "meta": {
        "search": {
            "mp3Length": {
                "$gte": 55,
                "$lte": 65
            },
            "topics.stem": [
                "trump"
            ]
        }
    }
}

Given a topic and/or time, retrieve articles to fit. A topic can be any combination of words extracted from the article body. A time can be any integer, in seconds.

See an example request in many languages.

HTTP Request

GET https://www.narro.co/api/v1/fit?time=60&topic=Trump

Query Parameters

Parameter Default Description
topic Resulting articles will contain this topic in their body text.
time 60 In seconds. If specified, resulting articles will have a listening time +/- 5 seconds of this time.

Errors

Example error response:

{
    "errors": [
        {
            "message": "Invalid URL provided."
        }
    ]
}

When possible, the Narro API will return an errors array if your request produced an error. Each object in the array will have, at minimum, a message field. A data array will not be returned on erroneous requests.

The Narro API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request is malformed
401 Unauthorized – Your API key is incorrect or absent
403 Forbidden – The resouce requested is not accessible by general API consumers
404 Not Found – The specified resource could not be found
405 Method Not Allowed – You tried to access a resouce with an invalid method
406 Not Acceptable – You requested a format that isn’t json
410 Gone – The resouce requested has been removed from our servers
429 Too Many Requests – Slow down!
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.