Awasu HTTP API

The Awasu HTTP API allows external users and programs to get information out of Awasu. 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 (if access has been enabled).

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
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 the file called reports-list.xyz.

Standard parameters

All services accept the following parameters:

format (f)Format to return the results in.
quietFlags if a quiet response (HTTP 204) should be returned.
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 operations

$/channels/list
Returns a list of channels and information about each one.
Parameters:
idComma-separated list of channel ID's.
Use * to return all channels.
name (n)Comma-separated list of channel names (PCRE regular expressions).
Use * to return all channels. Special characters such as , and & can be hex-encoded e.g. \x2C or \x26 respectively.
filterComma-separated list of channel filter names (PCRE regular expressions).
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 (PCRE regular expressions).
Special characters such as , and & can be hex-encoded e.g. \x2C or \x26 respectively.
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/open
Opens one or more channels.
Parameters:
idComma-separated list of channel ID's.
Use * to open all channels.
name (n)Comma-separated list of channel names (PCRE regular expressions).
Use * to open all channels. Special characters such as , and & can be hex-encoded e.g. \x2C or \x26 respectively.
filterComma-separated list of channel filter names (PCRE regular expressions).
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 (PCRE regular expressions).
Special characters such as , and & can be hex-encoded e.g. \x2C or \x26 respectively.
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 the 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 the 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.
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 a list of reports and information about each one.
Parameters:
idComma-separated list of report ID's.
Use * to return all reports.
name (n)Comma-separated list of report names (PCRE regular expressions).
Use * to return all reports. 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 (PCRE regular expressions).
Use * to run all reports. 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.

Workpad operations

$/workpads/list
Returns a list of workpads and information about each one.
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 (PCRE regular expressions).
Use * to return all workpads or @ for the default workpad. 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 (PCRE regular expressions).
Use @ for the default workpad. 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 (PCRE regular expressions).
Use * to clear all workpads or @ for the default workpad. 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 through in the 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 (PCRE regular expressions).
Use * to add to all workpads or @ for the default workpad. 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.

Other 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 main Awasu 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.