Awasu API

While Awasu has long had a basic API, it was extensively upgraded as part of the 2.4.2 release. The API allows external users and programs to get information out of Awasu and control some of its features.

The services offered are grouped into the following categories:

Service calls can always be made from the same computer that Awasu is running on and if you are using the Pro Edition, from other computers as well (*).

(*)For remote access, the network interface and port to accept requests on must first be configured in the Advanced tab of the Program Options.

 

Security

Basic security is implemented to prevent people from surreptitiously accessing your Awasu e.g. to find out what channels you are subscribed to, or add items to your workpads.

Service calls must include a special token in each request. This token can be changed in the Advanced page of the Program Options dialog, or removed if you want to disable this feature. For example, if the user had set their API token to be foobar, then the following call would fail with a "Missing HTTP API token" error:

http://localhost:2604/channels/subscribe?url=http://awasu.com/news.xml
and the correct call would be:
http://localhost:2604/channels/subscribe?token=foobar&url=http://awasu.com/news.xml

 

Templated response files

The response returned by each service call is generated from a template file stored in the Resources/API sub-directory under the Awasu installation directory. New formats can be supported by creating a file with a new extension, then specifying the new format in the HTTP request e.g.

http://localhost:2604/reports/list?format=xyz
will return a response generated from a file called reports-list.xyz.

Channel operations

$/channels/list
Returns information about your channels.
Parameters:
idComma-separated list of channel ID's.
Use * to return all channels.
name (n)Comma-separated list of channel names.
Use * to return all channels. Enable the regex switch to use regular expressions.
filterComma-separated list of channel filter names.
Enable the regex switch to use regular expressions.
regex (re)Flags if channel names and channel filter names should be interpreted as regular expressions (off by default).
Special characters such as , and & can be hex-encoded e.g. \x2C or \x26 respectively).
folderIdComma-separated list of channel folder ID's.
folderNameComma-separated list of channel folder names.
subFoldersFlags if channels in sub-folders of a targeted folder should be returned (off by default).
Only applies to the folderId and folderName parameters.
verbose (v) Flags if verbose information should be returned about each channel (off by default).
format (f)Format to return the results in (xml|json|opml).
The default format is xml.
quietFlags if a quiet response (HTTP 204) should be returned (off by default).
A "HTTP 204 No Response" will cause most browsers to stay on the current page, allowing links to be clicked with no visible effect.
outputFile (of)File to store the response in.
This parameter refers to a file on the machine that Awasu is running on. It is intended for use by calls made via the awasu:// protocol since there is no other way to return a response.
tokenAPI token.
This parameter must match what has been configured in the Advanced page of Awasu's Program Options.
$/channels/get
Returns the summary page for a channel.
Any combination of channel ID, name and/or filter(s) may be specified, but only one channel must match.
Parameters:
idComma-separated list of channel ID's.
Use * to return all channels.
name (n)Comma-separated list of channel names.
Use * to return all channels. Enable the regex switch to use regular expressions.
filterComma-separated list of channel filter names.
Enable the regex switch to use regular expressions.
regex (re)Flags if channel names and channel filter names should be interpreted as regular expressions (off by default).
Special characters such as , and & can be hex-encoded e.g. \x2C or \x26 respectively).
showFeedItemsMode (sfim) Controls which feed items will be shown (default|all|unread|new).
feedItemDescriptionFormat (fidf) Controls the presentation of feed item content (default|full|excerpt|plainText).
quietFlags if a quiet response (HTTP 204) should be returned (off by default).
A "HTTP 204 No Response" will cause most browsers to stay on the current page, allowing links to be clicked with no visible effect.
outputFile (of)File to store the response in.
This parameter refers to a file on the machine that Awasu is running on. It is intended for use by calls made via the awasu:// protocol since there is no other way to return a response.
tokenAPI token.
This parameter must match what has been configured in the Advanced page of Awasu's Program Options.
$/channels/open
Opens one or more channels in Awasu.
Parameters:
idComma-separated list of channel ID's.
Use * to open all channels.
name (n)Comma-separated list of channel names.
Use * to open all channels. Enable the regex switch to use regular expressions.
filterComma-separated list of channel filter names.
Enable the regex switch to use regular expressions.
regex (re)Flags if channel names and channel filter names should be interpreted as regular expressions (off by default).
Special characters such as , and & can be hex-encoded e.g. \x2C or \x26 respectively).
folderIdComma-separated list of channel folder ID's.
folderNameComma-separated list of channel folder names.
subFoldersFlags if channels in sub-folders of a targeted folder should be returned (off by default).
Only applies to the folderId and folderName parameters.
format (f)Format to return the results in (xml|json).
The default format is xml.
quietFlags if a quiet response (HTTP 204) should be returned (on by default).
A "HTTP 204 No Response" will cause most browsers to stay on the current page, allowing links to be clicked with no visible effect.
outputFile (of)File to store the response in.
This parameter refers to a file on the machine that Awasu is running on. It is intended for use by calls made via the awasu:// protocol since there is no other way to return a response.
tokenAPI token.
This parameter must match what has been configured in the Advanced page of Awasu's Program Options.
$/channels/subscribe
Starts the Channel Wizard.
Parameters:
url (u) Feed URL to preload.
format (f)Format to return the results in (xml|json).
The default format is xml.
quietFlags if a quiet response (HTTP 204) should be returned (on by default).
A "HTTP 204 No Response" will cause most browsers to stay on the current page, allowing links to be clicked with no visible effect.
outputFile (of)File to store the response in.
This parameter refers to a file on the machine that Awasu is running on. It is intended for use by calls made via the awasu:// protocol since there is no other way to return a response.
tokenAPI token.
This parameter must match what has been configured in the Advanced page of Awasu's Program Options.
$/channels/import
Starts the Import from dialog.
Parameters:
url (u) The URL of the import file.
type (t) The format being used to import channels. Currently only OPML is supported.
The default format is opml.
format (f)Format to return the results in (xml|json).
The default format is xml.
quietFlags if a quiet response (HTTP 204) should be returned (on by default).
A "HTTP 204 No Response" will cause most browsers to stay on the current page, allowing links to be clicked with no visible effect.
outputFile (of)File to store the response in.
This parameter refers to a file on the machine that Awasu is running on. It is intended for use by calls made via the awasu:// protocol since there is no other way to return a response.
tokenAPI token.
This parameter must match what has been configured in the Advanced page of Awasu's Program Options.
$/channels/folders/list
Returns information about your My Channels folders.
Parameters:
format (f)Format to return the results in (xml|json).
The default format is xml.
quietFlags if a quiet response (HTTP 204) should be returned (on by default).
A "HTTP 204 No Response" will cause most browsers to stay on the current page, allowing links to be clicked with no visible effect.
outputFile (of)File to store the response in.
This parameter refers to a file on the machine that Awasu is running on. It is intended for use by calls made via the awasu:// protocol since there is no other way to return a response.
tokenAPI token.
This parameter must match what has been configured in the Advanced page of Awasu's Program Options.
$/channels/filters/list
Returns information about your channel filters.
Parameters:
verbose (v) Flags if verbose information should be returned about each channel filter (off by default).
format (f)Format to return the results in (xml|json).
The default format is xml.
quietFlags if a quiet response (HTTP 204) should be returned (on by default).
A "HTTP 204 No Response" will cause most browsers to stay on the current page, allowing links to be clicked with no visible effect.
outputFile (of)File to store the response in.
This parameter refers to a file on the machine that Awasu is running on. It is intended for use by calls made via the awasu:// protocol since there is no other way to return a response.
tokenAPI token.
This parameter must match what has been configured in the Advanced page of Awasu's Program Options.

Feed item operations

$/feedItems/open
Opens one or more feed items in Awasu.
Parameters:
idComma-separated list of feed item ID's.
format (f)Format to return the results in (xml|json).
The default format is xml.
quietFlags if a quiet response (HTTP 204) should be returned (on by default).
A "HTTP 204 No Response" will cause most browsers to stay on the current page, allowing links to be clicked with no visible effect.
outputFile (of)File to store the response in.
This parameter refers to a file on the machine that Awasu is running on. It is intended for use by calls made via the awasu:// protocol since there is no other way to return a response.
tokenAPI token.
This parameter must match what has been configured in the Advanced page of Awasu's Program Options.
$/feedItems/update
Updates one or more feed items.
Parameters:
idComma-separated list of feed item ID's.
read (r) Flags if items should be marked as read or unread.
format (f)Format to return the results in (xml|json).
The default format is xml.
quietFlags if a quiet response (HTTP 204) should be returned (on by default).
A "HTTP 204 No Response" will cause most browsers to stay on the current page, allowing links to be clicked with no visible effect.
outputFile (of)File to store the response in.
This parameter refers to a file on the machine that Awasu is running on. It is intended for use by calls made via the awasu:// protocol since there is no other way to return a response.
tokenAPI token.
This parameter must match what has been configured in the Advanced page of Awasu's Program Options.

Channel report operations

$/reports/list
Returns information about your reports.
Parameters:
idComma-separated list of report ID's.
Use * to return all reports.
name (n)Comma-separated list of report names.
Use * to return all reports. Enable the regex switch to use regular expressions.
regex (re)Flags if report names should be interpreted as regular expressions (off by default).
Special characters such as , and & can be hex-encoded e.g. \x2C or \x26 respectively).
verbose (v) Flags if verbose information should be returned about each report (off by default).
format (f)Format to return the results in (xml|json).
The default format is xml.
quietFlags if a quiet response (HTTP 204) should be returned (off by default).
A "HTTP 204 No Response" will cause most browsers to stay on the current page, allowing links to be clicked with no visible effect.
outputFile (of)File to store the response in.
This parameter refers to a file on the machine that Awasu is running on. It is intended for use by calls made via the awasu:// protocol since there is no other way to return a response.
tokenAPI token.
This parameter must match what has been configured in the Advanced page of Awasu's Program Options.
$/reports/run
Runs one or more channel reports.
Parameters:
idComma-separated list of report ID's.
Use * to run all reports.
name (n)Comma-separated list of report names.
Use * to run all reports. Enable the regex switch to use regular expressions.
regex (re)Flags if report names should be interpreted as regular expressions (off by default).
Special characters such as , and & can be hex-encoded e.g. \x2C or \x26 respectively).
format (f)Format to return the results in (xml|json).
The default format is xml.
quietFlags if a quiet response (HTTP 204) should be returned (on by default).
A "HTTP 204 No Response" will cause most browsers to stay on the current page, allowing links to be clicked with no visible effect.
outputFile (of)File to store the response in.
This parameter refers to a file on the machine that Awasu is running on. It is intended for use by calls made via the awasu:// protocol since there is no other way to return a response.
tokenAPI token.
This parameter must match what has been configured in the Advanced page of Awasu's Program Options.
$/reports/get
Run a channel report and return the results.
Any combination of report ID and/or name may be specified, but only one report must match.
Parameters:
idComma-separated list of report ID's.
Use * to run all reports.
name (n)Comma-separated list of report names.
Use * to run all reports. Enable the regex switch to use regular expressions.
regex (re)Flags if report names should be interpreted as regular expressions (off by default).
Special characters such as , and & can be hex-encoded e.g. \x2C or \x26 respectively).
contentType (ct) MIME type to return the response as.
Awasu will attempt to auto-detect HTML, XML and plain-text responses but the returned MIME type can be configured here.
quietFlags if a quiet response (HTTP 204) should be returned (on by default).
A "HTTP 204 No Response" will cause most browsers to stay on the current page, allowing links to be clicked with no visible effect.
outputFile (of)File to store the response in.
This parameter refers to a file on the machine that Awasu is running on. It is intended for use by calls made via the awasu:// protocol since there is no other way to return a response.
tokenAPI token.
This parameter must match what has been configured in the Advanced page of Awasu's Program Options.

Workpad operations

$/workpads/list
Returns information about your workpads.
Parameters:
idComma-separated list of workpad ID's.
Use * to return all workpads or @ for the default workpad.
name (n)Comma-separated list of workpad names.
Use * to return all workpads or @ for the default workpad. Enable the regex switch to use regular expressions.
regex (re)Flags if workpad names should be interpreted as regular expressions (off by default).
Special characters such as , and & can be hex-encoded e.g. \x2C or \x26 respectively).
items (i) Flags if the feed items contained in each workpad should also be returned (off by default).
format (f)Format to return the results in (xml|json).
The default format is xml.
quietFlags if a quiet response (HTTP 204) should be returned (off by default).
A "HTTP 204 No Response" will cause most browsers to stay on the current page, allowing links to be clicked with no visible effect.
outputFile (of)File to store the response in.
This parameter refers to a file on the machine that Awasu is running on. It is intended for use by calls made via the awasu:// protocol since there is no other way to return a response.
tokenAPI token.
This parameter must match what has been configured in the Advanced page of Awasu's Program Options.
$/workpads/feed
Returns the items in a workpad as a feed.
Parameters:
idWorkpad ID.
Use @ for the default workpad.
name (n)Workpad name.
Use @ for the default workpad. Enable the regex switch to use regular expressions.
regex (re)Flags if workpad names should be interpreted as regular expressions (off by default).
Special characters such as , and & can be hex-encoded e.g. \x2C or \x26 respectively).
notes Flags if the user's notes for each workpad item should be included (off by default).
format (f)Format to return the results in. Currently only XML is supported.
The default format is xml.
quietFlags if a quiet response (HTTP 204) should be returned (off by default).
A "HTTP 204 No Response" will cause most browsers to stay on the current page, allowing links to be clicked with no visible effect.
outputFile (of)File to store the response in.
This parameter refers to a file on the machine that Awasu is running on. It is intended for use by calls made via the awasu:// protocol since there is no other way to return a response.
tokenAPI token.
This parameter must match what has been configured in the Advanced page of Awasu's Program Options.
$/workpads/clear
Clears one or more workpads.
Parameters:
idComma-separated list of workpad ID's.
Use * to clear all workpads or @ for the default workpad.
name (n)Comma-separated list of workpad names.
Use * to clear all workpads or @ for the default workpad. Enable the regex switch to use regular expressions.
regex (re)Flags if workpad names should be interpreted as regular expressions (off by default).
Special characters such as , and & can be hex-encoded e.g. \x2C or \x26 respectively).
format (f)Format to return the results in (xml|json).
The default format is xml.
quietFlags if a quiet response (HTTP 204) should be returned (on by default).
A "HTTP 204 No Response" will cause most browsers to stay on the current page, allowing links to be clicked with no visible effect.
outputFile (of)File to store the response in.
This parameter refers to a file on the machine that Awasu is running on. It is intended for use by calls made via the awasu:// protocol since there is no other way to return a response.
tokenAPI token.
This parameter must match what has been configured in the Advanced page of Awasu's Program Options.
$/workpads/addItem
Adds a feed item to one or more workpads.
If this request is sent as an HTTP POST, user notes can be passed in as post data.
Parameters:
idComma-separated list of workpad ID's.
Use * to add to all workpads or @ for the default workpad.
name (n)Comma-separated list of workpad names.
Use * to add to all workpads or @ for the default workpad. Enable the regex switch to use regular expressions.
regex (re)Flags if workpad names should be interpreted as regular expressions (off by default).
Special characters such as , and & can be hex-encoded e.g. \x2C or \x26 respectively).
url (u) URL of the new feed item.
title (t) Title of the new feed item (optional).
format (f)Format to return the results in (xml|json).
The default format is xml.
quietFlags if a quiet response (HTTP 204) should be returned (on by default).
A "HTTP 204 No Response" will cause most browsers to stay on the current page, allowing links to be clicked with no visible effect.
outputFile (of)File to store the response in.
This parameter refers to a file on the machine that Awasu is running on. It is intended for use by calls made via the awasu:// protocol since there is no other way to return a response.
tokenAPI token.
This parameter must match what has been configured in the Advanced page of Awasu's Program Options.

Search operations

$/search/query
Submit a query to Awasu's search engine.
Submit a blank search request in HTML format (i.e. $/search/query?f=html) to get a web page where queries can be submitted from.
Parameters:
query (q)Query string.
format (f)Format to return the results in (xml|json|html).
escapeFlags if special characters in the query string should be auto-escaped.
ageHow old search results may be (days).
locations (l)Where to search (url|title|content).
minScore (ms)Minimum score for search results (0-100).
page (p)Page number (1-based) to return (if results are being paginated).
pageSize (ps)Number of results to show per page.
feedItemDescriptionFormat (fidf)Controls the presentation of feed item content (default|full|excerpt|plainText).

Miscellaneous operations

$/buildInfo
Returns information about the current version of Awasu.
Parameters:
format (f)Format to return the results in (xml|json).
The default format is xml.
quietFlags if a quiet response (HTTP 204) should be returned (off by default).
A "HTTP 204 No Response" will cause most browsers to stay on the current page, allowing links to be clicked with no visible effect.
outputFile (of)File to store the response in.
This parameter refers to a file on the machine that Awasu is running on. It is intended for use by calls made via the awasu:// protocol since there is no other way to return a response.
tokenAPI token.
This parameter must match what has been configured in the Advanced page of Awasu's Program Options.
$/bringToFront
Brings the Awasu main window to the front.
Parameters:
format (f)Format to return the results in (xml|json).
The default format is xml.
quietFlags if a quiet response (HTTP 204) should be returned (on by default).
A "HTTP 204 No Response" will cause most browsers to stay on the current page, allowing links to be clicked with no visible effect.
outputFile (of)File to store the response in.
This parameter refers to a file on the machine that Awasu is running on. It is intended for use by calls made via the awasu:// protocol since there is no other way to return a response.
tokenAPI token.
This parameter must match what has been configured in the Advanced page of Awasu's Program Options.
$/openInDefaultBrowser
Opens a URL in the default browser.
Parameters:
url (u) URL to open.
format (f)Format to return the results in (xml|json).
The default format is xml.
quietFlags if a quiet response (HTTP 204) should be returned (on by default).
A "HTTP 204 No Response" will cause most browsers to stay on the current page, allowing links to be clicked with no visible effect.
outputFile (of)File to store the response in.
This parameter refers to a file on the machine that Awasu is running on. It is intended for use by calls made via the awasu:// protocol since there is no other way to return a response.
tokenAPI token.
This parameter must match what has been configured in the Advanced page of Awasu's Program Options.
$/openUrl
Opens a URL in an Awasu browser tab.
Parameters:
url (u) URL to open.
format (f)Format to return the results in (xml|json).
The default format is xml.
quietFlags if a quiet response (HTTP 204) should be returned (on by default).
A "HTTP 204 No Response" will cause most browsers to stay on the current page, allowing links to be clicked with no visible effect.
outputFile (of)File to store the response in.
This parameter refers to a file on the machine that Awasu is running on. It is intended for use by calls made via the awasu:// protocol since there is no other way to return a response.
tokenAPI token.
This parameter must match what has been configured in the Advanced page of Awasu's Program Options.