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 |
| 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 |
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 |
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. |