User Tools

Site Tools


api

InoReader official API

Preamble

The api is basically a clone of Google Reader's unofficial API. As much as we hate to blindly copy it, we have to so we can be compatible with current clients. The API is pretty much documented on the above link, but not everything will be implemented here. I will document only the implemented part with some notes where applicable.

If you are an App developer and have current integration with Google Reader, all you have to do is change www.google.com to www.inoreader.com and your app should work straight away. Please write to me (jacketbgbgATgmail.com) if you have any issues with integration.

Authentication

We support the GoogleLogin method for authentication, but we do not issue the SID and LSID parameters. Here is an example request:

curl https://www.inoreader.com/accounts/ClientLogin -d Email=username -d Passwd=password --verbose

Here is the full response:

> POST /accounts/ClientLogin HTTP/1.1
> User-Agent: curl/7.19.7 (x86_64-redhat-linux-gnu) libcurl/7.19.7 NSS/3.14.0.0 zlib/1.2.3 libidn/1.18 libssh2/1.4.2
> Host: www.inoreader.com
> Accept: */*
> Content-Length: 27
> Content-Type: application/x-www-form-urlencoded
>
< HTTP/1.1 200 OK
< Date: Wed, 03 Jul 2013 10:21:42 GMT
< Server: Apache
< X-Powered-By: PHP/5.4.16
< X-Mod-Pagespeed: 1.5.27.2-2912
< Vary: Accept-Encoding,User-Agent
< Cache-Control: max-age=0, no-cache
< Content-Length: 269
< Connection: close
< Content-Type: text/html; charset=UTF-8
<
SID=null
LSID=null
Auth=G2UlCa...Fx

The Auth tokens will expire after 30 days of inactivity

If you send a wrong username and/or password, you will get an error 401:

> POST /accounts/ClientLogin HTTP/1.1
> User-Agent: curl/7.19.7 (x86_64-redhat-linux-gnu) libcurl/7.19.7 NSS/3.14.0.0 zlib/1.2.3 libidn/1.18 libssh2/1.4.2
> Host: www.inoreader.com
> Accept: */*
> Content-Length: 28
> Content-Type: application/x-www-form-urlencoded
>
< HTTP/1.1 401 Authorization Required
< Date: Wed, 03 Jul 2013 10:28:41 GMT
< Server: Apache
< X-Powered-By: PHP/5.4.16
< Vary: Accept-Encoding,User-Agent
< Content-Length: 24
< Connection: close
< Content-Type: text/html; charset=UTF-8
<
Error=BadAuthentication

If our backend is unreachable for some reason, you will get an error 503 response:

> POST /accounts/ClientLogin HTTP/1.1
> User-Agent: curl/7.19.7 (x86_64-redhat-linux-gnu) libcurl/7.19.7 NSS/3.14.0.0 zlib/1.2.3 libidn/1.18 libssh2/1.4.2
> Host: www.inoreader.com
> Accept: */*
> Content-Length: 27
> Content-Type: application/x-www-form-urlencoded
>
< HTTP/1.1 503 Service Temporarily Unavailable
< Date: Wed, 03 Jul 2013 11:01:32 GMT
< Server: Apache
< X-Powered-By: PHP/5.4.16
< Vary: Accept-Encoding,User-Agent
< Content-Length: 0
< Connection: close
< Content-Type: text/html; charset=UTF-8

After you get get the token, you must store it and include it in all subsequent requests to the API:

Authorization: GoogleLogin auth=G2UlCa...Fx

Token

This method is added for compatibility reasons. You can request a token to make requests to the API without issuing the Authorization header, but instead appending it as a parameter &T=token. If your application never used this type of authorization, there is no need to do it now, just stick with the Authorization header.

Hint: The API just prints back the Auth token.

Request:

curl https://www.inoreader.com/reader/api/0/token -H "Authorization: GoogleLogin auth=1...0" --verbose

Response:

> GET /reader/api/0/token HTTP/1.1
> User-Agent: curl/7.19.7 (x86_64-redhat-linux-gnu) libcurl/7.19.7 NSS/3.14.0.0 zlib/1.2.3 libidn/1.18 libssh2/1.4.2
> Host: www.inoreader.com
> Accept: */*
> Authorization: GoogleLogin auth=1...0
>
< HTTP/1.1 200 OK
< Date: Wed, 03 Jul 2013 13:05:02 GMT
< Server: Apache
< X-Powered-By: PHP/5.4.16
< X-Mod-Pagespeed: 1.5.27.2-2912
< Vary: Accept-Encoding,User-Agent
< Cache-Control: max-age=0, no-cache
< Content-Length: 33
< Connection: close
< Content-Type: text/html; charset=UTF-8
<
1...0

User Info

https://www.inoreader.com/reader/api/0/user-info

Response:

{
	userId: "1005921515",
	userName: "Jacket",
	userProfileId: "1005921515",
	userEmail: "jacketbgbg@gmail.com",
	isBloggerUser: false,
	signupTimeSec: 1363850013,
	isMultiLoginEnabled: false
}

OPML Export

https://www.inoreader.com/reader/subscriptions/export

add ?download=1 to force the browser to download the file instead of displaying it.

Import API

This method is not Google Reader compatible

You can import OPML or json files via this method. You should be familiar with file uploads (multipart/form-data). The file name variable should be import_file. It accepts files with extensions zip, gz, xml, opml and json. If you are uploading an archived file, the engine will look for file called “subscriptions.xml” to import subscriptions. json files can be starred.json and shared.json. Those are compatible with the ones from Google Reader takeout archive.

Example:

curl -i -H "Authorization: GoogleLogin auth=1...0" -F import_file=@subscriptions.xml https://www.inoreader.com/reader/subscriptions/import

Successful response:

{
    "status": 1,
    "imported": 62,
    "timeSec": 0
}
  • status is 1 on success or 0 on failure where error_msg will be populated with a user-friendly message.
  • imported is the number of imported subscriptions
  • timeSec is the time in seconds which the import process took.

Error response:

{
    "status": 0,
    "error_msg": "Please upload a file!"
}

Get unread counters

Sample request:

curl https://www.inoreader.com/reader/api/0/unread-count?output=json -H "Authorization: GoogleLogin auth=1...0"

Sample response:

{
max: 1000,
unreadcounts: [
{
id: "user/1005921515/label/Earthquakes",
count: 112,
newestItemTimestampUsec: 1374178911514830
},
{
id: "feed/http://feeds.feedburner.com/JIRABlog",
count: 1,
newestItemTimestampUsec: 1374157904339150
},
{
id: "feed/http://bash.org.pl/rss",
count: 0,
newestItemTimestampUsec: 1373903541541930
},
...........

List of user subscriptions

curl https://www.inoreader.com/reader/api/0/subscription/list -H "Authorization: GoogleLogin auth=1...0"

List of user tags and folders

curl https://www.inoreader.com/reader/api/0/tag/list -H "Authorization: GoogleLogin auth=1...0"

Stream contents

The endpoint is

https://www.inoreader.com/reader/atom

or

https://www.inoreader.com/reader/api/0/stream/contents

Parameters

  • n - Number of items to return (default 20, max 1000)
  • r - Order. By default, it is newest first. You can pass o here to get oldest first
  • ot - Start time (unix timestamp) from which to start to get items. If r=o and the time is older than one month ago, one month ago will be used instead.
  • xt - Exclude Target - You can query all items from a feed that are not flagged as read by setting this to user/-/state/com.google/read
  • it - Include Target - You can query for a certain label with this. Accepted values: user/-/state/com.google/read, user/-/state/com.google/starred, user/-/state/com.google/like.
  • c - Continuation - a string used for continuation process. Each feed return not all items, but only a certain number of items. You'll find in the atom feed (under the name gr:continuation) a string called continuation. Just add that string as argument for this parameter, and you'll retrieve next items.
  • output - if you prefer JSON object pass json here. Note that reader/api/0/stream/contents always returns json object, while reader/atom returns XML by default

For example

https://www.inoreader.com/reader/atom/feed/http://feeds.arstechnica.com/arstechnica/science?n=20&xt=user/-/state/com.google/read?output=json

Will return the newest 20 unread items from Arstechnica feed in JSON format.

JSON Output:

{
    direction: "ltr",
    id: "feed/http://feeds.arstechnica.com/arstechnica/science",
    title: "Reading List",
    description: "",
    self: {
        href: "https://www.inoreader.com/reader/atom/feed/http://feeds.arstechnica.com/arstechnica/science?n=1&xt=user/-/state/com.google/read"
    },
    updated: 1374311011,
    items: [{
        crawlTimeMsec: "1374175437601",
        timestampUsec: "1374175437600550",
        id: "tag:google.com,2005:reader/item/00000000148b9369",
        categories: [
            "user/-/state/com.google/reading-list",
            "user/-/label/Testing"
        ],
        title: "Largest viral genome yet carries 2,300 genes that are new to biology",
        published: "1374174005",
        updated: "1374250392",
        canonical: [{
            href: "http://feeds.arstechnica.com/~r/arstechnica/science/~3/JvoygbfT84Y/story01.htm"
        }],
        alternate: [{
            href: "http://feeds.arstechnica.com/~r/arstechnica/science/~3/JvoygbfT84Y/story01.htm",
            type: "text/html"
        }],
        summary: {
            direction: "ltr",
            content: "...................................."
        },
        author: "John Timmer",
        likingUsers: [],
        comments: [],
        annotations: [],
        origin: {
            streamId: "feed/http://feeds.arstechnica.com/arstechnica/science",
            title: "Ars Technica » Scientific Method",
            htmlUrl: "http://arstechnica.com/"
        }
    }],
    continuation: "fyDdMiFKfs9t"
}

Item IDS

https://www.inoreader.com/reader/api/0/stream/items/ids

You can use the same parameters as for stream contents.

Outputs:

{
    "itemRefs": [{
        "id": "344691561",
        "directStreamIds": [],
        "timestampUsec": "1374562106374370"
    }, {
        "id": "344668222",
        "directStreamIds": [],
        "timestampUsec": "1374561671988760"
    }, {
        "id": "344668225",
        "directStreamIds": [],
        "timestampUsec": "1374561671988750"
    }],
    "continuation": "s_CS32Rz36Ro"
}

A note item IDs formats

Item IDs can be returned in short or long format depending on the API method.

  • Long form: The prefix tag:google.com,2005:reader/item/ followed by the ID as an unsigned base 16 number that is 0-padded so that it's always 16 characters wide.
  • Short form: The ID as a signed base 10 number.

Here's some sample mappings between the two forms:

Long formShort form
tag:google.com,2005:reader/item/00000000148b9369344691561
tag:google.com,2005:reader/item/00000000148b383e344668222
tag:google.com,2005:reader/item/00000000148b3841344668225

You can call the edit methods with both short and long format IDs.

Tags

Rename tag

https://www.inoreader.com/reader/api/0/rename-tag?s=source_name&dest=target_name

Will respond with the string “OK” if the tag is found.

Delete tag

https://www.inoreader.com/reader/api/0/disable-tag?s=tag_name

Will respond with the string “OK” if the tag is found. This will put all subscriptions tagged with this tag in the root of the tree.

Edit tag

This is a bit more complex than the others. Endpoint:

https://www.inoreader.com/reader/api/0/edit-tag

Parameters:

  • a - tag to add
  • r - tag to remove
  • i - item ID. Can accept two types of values, whichever you prefer:
    • tag:google.com,2005:reader/item/1234567890 (The standard way)
    • 1234567890 (shortened ID)

In addition i can be an array of IDs instead of a scalar value, so you can mark tag multiple items at once

Special tags:

  • user/-/state/com.google/read - add this tag to mark the item as read. Remove it to mark as unread. Note that items older than one month or firstitemmsec for the specific subscription (whichever is freshest) cannot be marked as unread.
  • user/-/state/com.google/starred - add this to mark the item as starred (favorite)
  • user/-/state/com.google/broadcast - add this to broadcast (share) this item with your connections in InoReader.
  • user/-/state/com.google/like - add this to like the article.
  • user/-/label/tag_name - add/remove specific user tag. If the tag does not exist it will be created.

Examples:

This will mark two articles as read

https://www.inoreader.com/reader/api/0/edit-tag?a=user/-/state/com.google/read&i=12345678&i=12345679

This will mark two articles as unread

https://www.inoreader.com/reader/api/0/edit-tag?r=user/-/state/com.google/read&i=12345678&i=12345679

Mark all as read

This method marks all items in a given stream as read. Please provide the ts parameter (unix timestamp, generated the last time the list stream was fetched and displayed to the user( so we will not mark as read items that the user never got.

curl https://www.inoreader.com/reader/api/0/mark-all-as-read?s=<stream>&ts=<timestamp> -H "Authorization: GoogleLogin auth=1...0" --verbose

Valid <stream> values:

  • feed/feed_url - a feed url
  • user/-/label/X - folder name X
  • user/-/state/com.google/starred - Favorite articles
  • user/-/state/com.google/broadcast - Broadcasted articles
  • user/-/state/com.google/broadcast-friends - Channels section
  • user/-/state/com.google/reading-list - Everything (careful with that!)

On success the string “OK” with HTTP code 200 is returned. Error 400 is returned in case some parameter is missing or malformed.

s and ts parameters can be send both by POST and GET. ts should be sent in microseconds

Examples:

curl https://www.inoreader.com/reader/api/0/mark-all-as-read?s=feed/http://feeds.arstechnica.com/arstechnica/science&ts=1373407120123456 -H "Authorization: GoogleLogin auth=1...0"
curl https://www.inoreader.com/reader/api/0/mark-all-as-read?user/-/label/Google&ts=1373407120123456 -H "Authorization: GoogleLogin auth=1...0"

Add subscription (feed)

This one is trivial:

https://www.inoreader.com/reader/api/0/subscription/quickadd?quickadd=http://feeds.arstechnica.com/arstechnica/science

Will subscribe the current user to Arstechnica feed. Response JSON:

{
    query: "http://feeds.arstechnica.com/arstechnica/science",
    numResults: 1,
    streamId: "feed/http://arstechnica.com/"
}

numResults will be 0 if the feed is not added for some reason. It will be 1 when feed is added, even if the user is already subscribed.

Edit subscription

This method is used to rename the subscription, add it to a folder, remove it from folder or unsubscribe from it. You can also subscribe and directly rename it and add it to folder via this method.

Endpoint:

https://www.inoreader.com/reader/api/0/subscription/edit

Parameters:

  • ac - Action. Can be edit, subscribe, or unsubscribe.
  • s - Stream id in the form feed/feed_url
  • t - Subscription title. Omit this parameter to keep the title unchanged
  • a - Add subscription to folder/tag.
  • r - Remove subscription from folder/tag.

Example:

https://www.inoreader.com/reader/api/0/subscription/edit?ac=edit&s=feed/http://feeds.arstechnica.com/arstechnica/science&t=Ars&a=user/-/label/weekly

Will change title to Ars and put it in folder weekly.

Preferences list

https://www.inoreader.com/reader/api/0/preference/list

Returns the current subscriptions sorting:

{
	prefs: [
		{
			id: "lhn-prefs",
			value: "{\"subscriptions\":{\"ssa\":true}}"
		}
	]
}

Stream preferences list

https://www.inoreader.com/reader/api/0/preference/stream/list

Currently outputs only subscription and folder custom sort ids:

{
    "streamprefs": {
        "user/1005921515/state/com.google/root": [{
            "id": "subscription-ordering",
            "value": "BEC24025BEBD5A25BEBC2063001C459B0018F45DBEBC6F05BEBD8D55BEBE3252001490BF00152A6A000B633F000004F4000004F5000005ED00002F2C0000A08400003530000004F7000004F8000004F9000005F1000004FC000004FD00001A880026A51D00273E9C00246F840026A4EC0027C05A00275F3D0026BC73BEC008A0BEC06A88BEC1E2F4004244DC00367C4E005AFDFA00611F4800350BD4004DCBB0002F10310041A5B60050E0A80068AADF00367ED200654CCC0051B8B7005149A5005B5EE40036142500573E6400576D67002ADA36002D269F00350B7F0037857E0038FA10003F07F30060D189005A9DF00063C962005D8E67006A1A93006B28B4006C2A24006DD240006DCF44006DCF41006DE4520073868000717B7D007179F00072425300717AB400710C5F00717C37006F3C1C0073885400738859BEC2D61900713B5D00738858006E50B400714BED0073893400717ABB007388570073892700711266"
        }],
        "user/1005921515/label/MIT": [{
            "id": "is-expanded",
            "value": "true"
        }, {
            "id": "subscription-ordering",
            "value": "00005C9F0000425D00005CA100005CA000005CA300005C9E"
        }],
        "user/1005921515/label/Testing": [{
            "id": "is-expanded",
            "value": "true"
        }, {
            "id": "subscription-ordering",
            "value": "0018292200233381002094C100085B3A00007D1E000CAA76000859980000BD680000165D00016D1E001CE9620000BCB30011C20C000154F60001AB4D00127963001F609E0022AA500022C9D000215FEA002267B300064FD7003F4DFC"
        }]
    }
}

Split the string at every 8 characters and match them with the sortids from reader/api/0/subscription/list and reader/api/0/tag/list to do the ordering.

Set stream preferences

POST endpoint:

https://www.inoreader.com/reader/api/0/preference/stream/set

Parameters:

  • s Stream ID
    • user/-/state/com.google/root - This is the root level
    • user/-/label/MIT - Folder named MIT
  • k - Key. Only accepted for now is “subscription-ordering”
  • v - Value. for “subscription-ordering” this is concatenated string from subscriptions and folders sort ids.

Example:

https://www.inoreader.com/reader/api/0/preference/stream/set?k=subscription-ordering&s=user/1005921515/state/com.google/root&v=1DD385251DCE9F251DCD6563001C459B0018F45D1DCDB4051DCED2551DCF7752001490BF0018292200152A6A000B633F000004F4000004F5000005ED00002F2C0000A08400003530000004F7000004F8000004F9000005F1000004FC000004FD00001A880026A51D00273E9C00246F840026A4EC0027C05A00275F3D00233381002094C10026BC731DD14DA000085B3A00007D1E1DD1AF881DD327F4000CAA7600085998004244DC00367C4E0000BD680000165D005AFDFA00016D1E00611F48001CE96200350BD40000BCB3004DCBB00011C20C002F1031000084AD000154F6000084AE0041A5B60001AB4D0050E0A80068AADF0012796300182A60000540F600367ED2001F609E00654CCC0022AA5000151AA700005C9F0022C9D0000538720051B8B70018EFA200215FEA0000425D005149A5000678B500005CA1005B5EE4002267B30036142500005CA000064FD700573E6400005CA300005C9E00576D67002ADA3600044925002D269F00000505000004FE000DBC4D00350B7F000004FF000764640037857E0038FA1000000500003F07F300000501000005030060D189005A9DF0000005040063C96200000506005D8E670000050700000508006A1A9300000509006B28B4006C2A2400000502000035CF006DD240006743F40000050C006DCF440067525D0000050B00675263006DCF410000050A006DE45200675266006752680067526F00675281006752850073868000717B7D007179F00072425300717AB400710C5F00717C37006F3C1C00738854007388591DD41B1900713B5D00738858003F4DFC006E50B400714BED0073893400717ABB007388570073892700711266
api.txt · Last modified: 2013/11/23 21:05 by Jacket