The purpose of this document is to define the protocol for the CinchCast Web Service that the client application will interact with via HTTP PUT & GET requests to post new Cinch audio recordings, login users, etc.

The HTTP requests will include the following header fields:

User-Agent: [device_type]/[app_version] [deviceId]
     (i.e.: iPhone/1.0 21790f560098113a8b6492407791cea0cb204719)
btr-method: [web service method name for the call being made] 
      (i.e.: CreateNewUserAccount, GetAlbumsForCinchFeed, etc.)

The body of the HTTP request will use the following format, with unique command xml based on the command type being requested:

<BlogTalkRadioRequest command=”[name of the command being requested]”
			    deviceId=”[unique identifier for current client device]”
			    sequence=”[unique sequence number from client]”>
	<sessionId>
		[the session id for the currently logged in user, or empty if there is not 
		 a logged in user ]
	</sessionId>
	<accountId>
		[the account id for the currently logged in user, or empty if there is not
		 a logged in user ]
	</accountId>

	[specific command xml]

</BlogTalkRadioRequest>

If a user is currently logged in, the client application will include the accountId and sessionId with the requests as documented above so that the web service can make determinations based on the current user account. If there is not a currently logged in user then the <accountId> and <sessionId> tags will be omitted.

The responses from the server will use the following format, with unique command xml based on the command type that was requested:

<BlogTalkRadioResponse command=”[name of the command that was requested]”
   			     sequence=”[unique sequence number from client request]”>
	<success>
		[1 or 0 depending on whether the command was successful or not]
	</success>
	<Errors>
		<error>
			<code></code>
			<message>
			[any error message to display to the user if this command failed]
			</message>
		</error>
		...
	</Errors>

	[specific command xml]

</BlogTalkRadioResponse>

Every user account that is created starts out with a single Cinch Feed. A Cinch Feed can contain Cinch Recordings as well as child Cinch Feeds that can be referred to as Albums.

Users can post recordings to their Cinch Feed(s) and/or create Albums underneath their Cinch Feed(s). Each Album can be specified as public or private.

Searching can be used to search for Cinch Feeds that match a search criteria, or specific Cinch Recordings that match a search criteria.

The specific command types and their xml are defined below:

Request:

<BlogTalkRadioRequest command=”CreateNewUserAccount”
			    deviceId=”[unique identifier for client device ]”
			    sequence=”[unique sequence number from client]”>
	<CreateNewUserAccount>
		<UserAccount>	

			[1 of the following 3 options will be present:

				<BlogTalkRadioLogin> if the user enters a username and 
						password to create a new CinchCast account.

				<FacebookLogin> if the user has chosen to use their Facebook
						login credentials to create the new account

				<TwitterLogin> if the user has chosen to use their Twitter
						login credentials to create the new account ]

			<BlogTalkRadioLogin>
				<username>[username for new user account]</username>
				<password>[Base64 encoded password for new account]</password>
				<title> [title for the Cinch Feed for this user] </title>
				<email> [optional email address for this user account] </email>
				<avatarImage>
					[true or false, based on whether the client wants to 
                    upload an avatar image for this account or not]
				</avatarImage>
			</BlogTalkRadioLogin>

			<FacebookLogin>
				<userId>
					[Facebook User ID as returned from the Facebook API]
				</userId>
				<sessionSecret>
					[session secret that can be used to interact with the 
					 Facebook API on this user’s behalf]
				</sessionSecret>
				<sessionKey>
					[session key that can be used to interact with the 
					 Facebook API on this user’s behalf]
				</sessionKey>
			</FacebookLogin>
				
			<TwitterLogin>
				<token>
					[token as part of OAuth authentication that was returned 
                    from the Twitter API for this user]
				</token>
				<tokenSecret>
					[token secret as part of OAuth authentication that was 
					 returned from the Twitter API for this user]
				</tokenSecret>
			</TwitterLogin>
		</UserAccount>
	</CreateNewUserAccount>
</BlogTalkRadioRequest>

Response:

<BlogTalkRadioResponse command="CreateNewUserAccount"
   			     sequence=”[unique sequence number from client request]” >
	<success>
		[1 or 0 depending on whether the account was created or not]
	</success>
	<Errors>
		[any error message to display to the user if creating the account failed
		(i.e. username already being used, etc.)]
	</Errors>
	<accountId>[unique identifier for the new account]</accountId>
	<sessionId>
		[unique session identifier for this now logged in user (for verification with 
 		 all of the calls on the web service end)]
	</sessionId>
	<CinchFeed> [the primary cinch feed for this new user account]
		<feedName>[the name of the Cinch Feed to display]</feedName>
		<feedURL>[the url for this Cinch Feed]</feedURL>
		<feedDescription>
			[optional description of this Cinch Feed]
		</feedDescription>
		<editable>
			[true or false, depending on whether the user can edit this feed 
			 (delete recordings from it)]
		</editable>
		<public>
			[true or false, reflecting whether this feed is public or 
			 private]
		</public>
		<parentFeedURL>[the url of this feeds parent if applicable]</parentFeedURL>
    		<userIsSubscribed>
			[true or false, reflecting whether this user subscribed to this feed]
		<userIsSubscribed>
	</CinchFeed>
	<avatarURL>
		[url that the client can use to post the user’s avatar image to as defined in 
        the “Posting Images & Recordings to the Web Server” section at the end of 
		 this document]
	</avatarURL>
 </BlogTalkRadioResponse>

Request:

<BlogTalkRadioRequest command=”LoginUser”
			    deviceId=”[unique identifier for current client device]”
			    sequence=”[unique sequence number from client]” >
	<LoginUser>

		[1 of the following 3 options will be present:

			<BlogTalkRadioLogin> if we have a username and 
					password to login this user to a CinchCast account.

			<FacebookLogin> if the user has chosen to use their Facebook account 
					login credentials.

			<TwitterLogin> if the user has chosen to use their Twitter account 
					login credentials. ]

		<BlogTalkRadioLogin>
			<username>[username for the user account]</username>
			<password>[Base64 encoded password for the user account]</password>
		</BlogTalkRadioLogin>

		<FacebookLogin>
			<userId>[Facebook User ID as returned from the Facebook API]</userId>
			<sessionSecret>
				[session secret that can be used to interact with the 
				 Facebook API on this user’s behalf]
			</sessionSecret>
			<sessionKey>
				[session key that can be used to interact with the 
				 Facebook API on this user’s behalf]
			</sessionKey>
		</FacebookLogin>
				
		<TwitterLogin>
			<token>
				[token as part of OAuth authentication that was returned
                from the Twitter API for this user]
			</token>
			<tokenSecret>
				[token secret as part of OAuth authentication that was 
				 returned from the Twitter API for this user]
			</tokenSecret>
		</TwitterLogin>
	</LoginUser>
</BlogTalkRadioRequest>

Response:

<BlogTalkRadioResponse command=”LoginUser”
  			     sequence=”[unique sequence number from client request]” >
	<success>[1 or 0]</success>
	<Errors></Errors>
	<accountId>
		[account id for the user account that is now logged in if login was 
		successful]
	</accountId>
	<sessionId>
		[the session id for this now logged in user if the login was successful
	</sessionId>
	<UserAccount>
		<accountId>[account id for the user account]</accountId>
    		<username>[username for the user account logging in]</username>
		<email> [optional email address for this user account] </email>
		<avatarImageURL>
			[optional URL for the avatar image for this user account]
		</avatarImageURL>

	</UserAccount>
	<CinchFeed> [the primary cinch feed for this user account]
		<feedName>[the name of the Cinch Feed to display]</feedName>
		<feedURL>[the url for this Cinch Feed]</feedURL>
		<feedDescription>
			[optional description of this Cinch Feed]
		</feedDescription>
		<editable>
			[true or false, depending on whether the user can edit this feed 
			 (delete recordings from it)]
		</editable>
		<public>
			[true or false, reflecting whether this feed is public or 
			 private]
		</public>
		<parentFeedURL>[the url of this feeds parent if applicable]</parentFeedURL>
    		<userIsSubscribed>
			[true or false, reflecting whether this user subscribed to this feed]
		</userIsSubscribed>
	</CinchFeed>
</BlogTalkRadioResponse>

Request:

<BlogTalkRadioRequest command=”ModifyUserAccount”
			    deviceId=”[unique identifier for current client device]”
			    sequence=”[unique sequence number from client]”>
	<ModifyUserAccount>
		<sessionId>[the session id for the user that is logged in ]</sessionId>
		<accountId>[the account id for the user that is logged in ]</accountId>
		<UserAccount>
			[ if the user is changing the password for a CinchCast user 
			  account, then the <username>, <currentPassword> and <newPassword>
			  blocks will be included to change the username/password combination
			  for the account ]
			<username>[optional username for the user account]</username>
			<currentPassword>
				[optional current Base64 encoded password for the user account]
			</currentPassword>
			<newPassword>
				[optional new Base64 encoded password for this user account]
			</newPassword>
			
			[ the <email> and/or <avatarImage> blocks will be included if the 
			  user chooses to change their email address and/or avatar image for 
			  the account (whether it is a CinchCast account, Facebook linked
			  account or Twitter linked account) ]
			<email> [optional new email address for this user account] </email>
			<avatarImage>
				[true or false, based on whether the client wants to upload an 
				 avatar image for this account or not]
			</avatarImage>
		</UserAccount>
	</ModifyUserAccount>
</BlogTalkRadioRequest>

Response:

<BlogTalkRadioResponse command=”ModifyUserAccount”
			     sequence=”[unique sequence number from client]”>
	<success>[1 or 0]</success>
	<Errors></Errors>
	<avatarURL>
		[url that the client can use to post the user’s avatar image to as defined in
        the “Posting Images to the Web Server” section at the end of 
		 this document]
	</avatarURL>
</BlogTalkRadioResponse>

This call will be made to create what is needed on the server for a new audio recording. The server will return the new recording id, image id and thumbnail image id, as well as the locations to post image file(s) to. This call will precede the client actually posting the image file(s). If there is an image associated with this recording that will be uploaded, the client will create a smaller, thumbnail version of it which will be used when displaying multiple recordings in a list to save network bandwidth.

See the “Posting Images to the Web Server” section at the end of this document for documentation on how the actual image file(s) and recording file(s) are uploaded to the server.

Request:

<BlogTalkRadioRequest command=”CreateNewCinchRecording”
			    deviceId=”[unique identifier for current client device]”
			    sequence=”[unique sequence number from client]”>
	<CreateNewCinchRecording>
		<sessionId>[the session id for the user that is logged in ]</sessionId>
		<accountId>[the account id for the user that is logged in ]</accountId>
		<CinchRecording>
			<includeImage> 
				[true or false based on whether the new recording will have an 
				image associated with it ] 
			</includeImage>
			<name> [name of recording ]</name>
			<duration> [duration in milliseconds ]</duration>
			<gps> 
				[gps string that defines the location that the 
				recording was made at ] 
			</gps>
			<dateRecorded> 
				[date string that defines when the recording was made in GMT] 
			</dateRecorded>
			<description> 
				[optional description for this cinch recording ]
			</description>
			<tags> [optional list of extra meta data content ]
				<tag> [value] </tag>
				<tag> [value] </tag>
				...
			</tags>
			<feedURL>
				[the url for the Cinch Feed or Album to post this recording to]
			</feedURL>
               <recordingURL>
                         [the url for the recording].  Must be an mp3 file.
                  </recordingURL>
			[ optional - if the user wants to post this recording to their 
					 Facebook feed ]
			<postToFacebook>
				
				<userId>
					[Facebook User ID as returned from the Facebook API]
				</userId>
				<sessionSecret>
					[session secret that can be used to interact with the 
					 Facebook API on this user’s behalf]
				</sessionSecret>
				<sessionKey>
					[session key that can be used to interact with the 
					 Facebook API on this user’s behalf]
				</sessionKey>
			<postToFacebook>

			[ optional - if the user wants to post this recording to their 
					 Twitter feed ]
			<postToTwitter>
				<token>
					[token as part of OAuth authentication that was returned
                    from the Twitter API for this user]
				</token>
				<tokenSecret>
					[token secret as part of OAuth authentication that was 
					 returned from the Twitter API for this user]
				</tokenSecret>
			<postToTwitter>

		</CinchRecording>
	</CreateNewCinchRecording>
</BlogTalkRadioRequest>

Response:

<BlogTalkRadioResponse command="CreateNewCinchRecording"
 			     sequence=”[unique sequence number from client request]” >
	<success>[1 or 0]</success>
	<Errors></Errors>
	<CinchRecording>
		<recordingId>
			 [the unique identifier for the new recording] 
		</recordingId>	
		<imageId> 
			[optional - the unique identifier for the recording image 
			 (if an image is included with this recording ] 
		</imageId>
		<imageURL> 
			[optional - URL that the client can post the image file to.  See 
			 the “Posting Images to the Web Server” section at the end 
			 of this document for documentation on how the client will upload the 
			 image file. ]
		</imageURL>
		<thumbnailImageId> 
			[optional - the unique identifier for the smaller, thumbnail version
			 of the recording image (if an image is included with this recording) ] 
		</thumbnailImageId>
		<thumbnailImageURL> 
			[optional - URL that the client can post the thumbnail image file to.
			 See the “Posting Images to the Web Server” section at the 
			 end of this document for documentation on how the client will upload 
			 the thumbnail image file.] 
		</thumbnailImageURL>
	</CinchRecording>
</BlogTalkRadioResponse>

This call will be made to create what is needed on the server for a new text only cinch. The server will return the new recording id, image id and thumbnail image id, as well as the locations to post the image file(s) to. This call will precede the client actually posting the image file(s). If there is an image associated with this recording that will be uploaded, the client will create a smaller, thumbnail version of it which will be used when displaying multiple recordings in a list to save network bandwidth.

See the “Posting Images to the Web Server” section at the end of this document for documentation on how the actual image file(s) are uploaded to the server.

Request:

<BlogTalkRadioRequest command=”CreateNewCinchRecording”
			    deviceId=”[unique identifier for current client device]”
			    sequence=”[unique sequence number from client]”>
	<CreateNewCinchRecording>
		<sessionId>[the session id for the user that is logged in ]</sessionId>
		<accountId>[the account id for the user that is logged in ]</accountId>
		<CinchRecording>
			<includeImage> 
				[true or false based on whether the new recording will have an 
				image associated with it ] 
			</includeImage>
			<name> [name of recording ]</name>
			<duration> [duration in milliseconds ]</duration>
			<gps> 
				[gps string that defines the location that the 
				recording was made at ] 
			</gps>
			<dateRecorded> 
				[date string that defines when the recording was made in GMT] 
			</dateRecorded>
			<description> 
				[optional description for this cinch recording ]
			</description>
			<tags> [optional list of extra meta data content ]
				<tag> [value] </tag>
				<tag> [value] </tag>
				...
			</tags>
			<feedURL>
				[the url for the Cinch Feed or Album to post this recording to]
			</feedURL>

			[ optional - if the user wants to post this recording to their 
					 Facebook feed ]
			<postToFacebook>
				
				<userId>
					[Facebook User ID as returned from the Facebook API]
				</userId>
				<sessionSecret>
					[session secret that can be used to interact with the 
					 Facebook API on this user’s behalf]
				</sessionSecret>
				<sessionKey>
					[session key that can be used to interact with the 
					 Facebook API on this user’s behalf]
				</sessionKey>
			<postToFacebook>

			[ optional - if the user wants to post this recording to their 
					 Twitter feed ]
			<postToTwitter>
				<token>
					[token as part of OAuth authentication that was 
                    returned from the Twitter API for this user]
				</token>
				<tokenSecret>
					[token secret as part of OAuth authentication that was 
					 returned from the Twitter API for this user]
				</tokenSecret>
			<postToTwitter>

		</CinchRecording>
	</CreateNewCinchRecording>
</BlogTalkRadioRequest>

Response:

<BlogTalkRadioResponse command="CreateNewCinchRecording"
 			     sequence=”[unique sequence number from client request]” >
	<success>[1 or 0]</success>
	<Errors></Errors>
	<CinchRecording>
		<recordingId>
			 [the unique identifier for the new recording] 
		</recordingId>	
		<recordingURL> 
			[the URL that the client can post the recording file to.  See the 
			 “Posting Images & Recordings to the Web Server” section at the end of 
			 this document for documentation on how the client will upload the 
			 audio recording file. ] 
		</recordingURL>
		<imageId> 
			[optional - the unique identifier for the recording image 
			 (if an image is included with this recording ] 
		</imageId>
		<imageURL> 
			[optional - URL that the client can post the image file to.  See 
			 the “Posting Images & Recordings to the Web Server” section at the end 
			 of this document for documentation on how the client will upload the 
			 image file. ]
		</imageURL>
		<thumbnailImageId> 
			[optional - the unique identifier for the smaller, thumbnail version
			 of the recording image (if an image is included with this recording) ] 
		</thumbnailImageId>
		<thumbnailImageURL> 
			[optional - URL that the client can post the thumbnail image file to.
			 See the “Posting Images & Recordings to the Web Server” section at the 
			 end of this document for documentation on how the client will upload 
			 the thumbnail image file.] 
		</thumbnailImageURL>
	</CinchRecording>
</BlogTalkRadioResponse>

Publish a cinch to Facebook or Twitter

Request:

<BlogTalkRadioRequest command=”ShareCinchRecording”
			    deviceId=”[unique identifier for current client device]”
			    sequence=”[unique sequence number from client]”>
	<ShareCinchRecording>
		<sessionId>[the session id for the user that is logged in]</sessionId>
		<accountId>[the account id for the user that is logged in]</accountId>
		<CinchRecording>
			<recordingId>[the id of the recording you want to publish]
			</recordingId>

			[ optional - if the user wants to post this recording to their 
					 Facebook feed ]
			<postToFacebook>
				
				<userId>
					[Facebook User ID as returned from the Facebook API]
				</userId>
				<sessionSecret>
					[session secret that can be used to interact with the 
					 Facebook API on this user’s behalf]
				</sessionSecret>
				<sessionKey>
					[session key that can be used to interact with the 
					 Facebook API on this user’s behalf]
				</sessionKey>
			<postToFacebook>

			[ optional - if the user wants to post this recording to their 
					 Twitter feed ]
			<postToTwitter>
				<token>
[token as part of OAuth authentication that was returned from the Twitter API for this user]
				</token>
				<tokenSecret>
					[token secret as part of OAuth authentication that was 
					 returned from the Twitter API for this user]
				</tokenSecret>
			<postToTwitter>

		</CinchRecording>
	</ShareCinchRecording>
</BlogTalkRadioRequest>

Response:

<BlogTalkRadioResponse command="CreateNewCinchRecording"
 			     sequence=”[unique sequence number from client request]” >
	<success>[1 or 0]</success>
	<Errors></Errors>
</BlogTalkRadioResponse>

Request:

<BlogTalkRadioRequest command=”GetAlbumsForCinchFeed”
			    deviceId=”[unique identifier for current client device]”
			    sequence=”[unique sequence number from client]]”>
	<GetAlbumsForCinchFeed>
		<sessionId></sessionId>
		<accountId></accountId>
		<feedURL>[the url for the Cinch Feed to get albums for]</feedURL>
		<offset>
			[the offset into the set of albums for this feed to start 
              returning albums from]
		</offset>
		<count>[the number of albums to return ]</count>
	</GetAlbumsForCinchFeed>
</BlogTalkRadioRequest>

Response:

<BlogTalkRadioResponse command=”GetAlbumsForCinchFeed”
 			     sequence=”[unique sequence number from client request]”>
	<success>[1 or 0]</success>
	<Errors></Errors>
	<totalCount>
		[the total number of albums for this feed]
	</totalCount>
	<CinchFeeds>
		[the list of child “Album” Cinch Feeds for this Feed based on the 
		 offset and count requested]

		<CinchFeed>
			<feedName>[the name of the Cinch Album Feed to display]</feedName>
			<feedURL>[the url for this Cinch Album Feed]</feedURL>
			<feedDescription>
				[optional description of this Cinch Album Feed]
			</feedDescription>
			<editable>
				[true or false, depending on whether the user can edit this feed 
				 (delete recordings from it)]
			</editable>
			<public>
				[true or false, reflecting whether this feed is public or 
				 private]
			</public>
			<parentFeedURL>
				[the url of this feeds parent if applicable]
			</parentFeedURL>
    			<userIsSubscribed>
[true or false, reflecting whether this user subscribed to this feed]
			</userIsSubscribed>
		</CinchFeed>
		<CinchFeed>
			...
		</CinchFeed>
		...
	</CinchFeeds>
</BlogTalkRadioResponse>

Request:

<BlogTalkRadioRequest command=”CreateCinchFeedAlbum”
			    deviceId=”[unique identifier for current client device]”
			    sequence=”[unique sequence number from client]”>
	<CreateCinchFeedAlbum>
		<sessionId></sessionId>
		<accountId></accountId>
		<feedURL>[url of the Cinch Feed to create the child album feed for]</feedURL>
		<CinchFeed>
			<feedName>[the name of the new Cinch Album Feed to create]</feedName>
			<feedDescription>
				[optional description for this new Cinch Album Feed]
			</feedDescription>
			<public>
				[true or false, depending on whether this album should be 
				 public or private]
			</public>
		</CinchFeed>
	</CreateCinchFeedAlbum>
</BlogTalkRadioRequest>

Response:

<BlogTalkRadioResponse command=”CreateCinchFeedAlbum”
			     sequence=”[unique sequence number from client request]” >
	<success>[1 or 0]</success>
	<Errors></Errors>
	<CinchFeed>
		<feedName>[the name of the new Cinch Album Feed]</feedName>
		<feedURL>[the url for this new Cinch Album Feed]</feedURL>
		<feedDescription>
			[optional description for this new Cinch Album Feed]
		</feedDescription>
		<editable>
			[true or false, depending on whether the user can edit this feed 
			 (delete recordings from it)]
		</editable>
		<public>
			[true or false, depending on whether this album should be 
			public or private]
		</public>
		<parentFeedURL>
			 [the url of this feeds parent if applicable]
		</parentFeedURL>
    		<userIsSubscribed>
			[true or false, reflecting whether this user subscribed to this feed]
		</userIsSubscribed>
	</CinchFeed>
</BlogTalkRadioResponse>

Request:

<BlogTalkRadioRequest command=”ModifyCinchFeed”
			    deviceId=”[unique identifier for current client device]”
			    sequence=”[unique sequence number from client]”>
	<ModifyCinchFeed>
		<sessionId>[the session id for the user that is logged in ]</sessionId>
		<accountId>[the account id for the user that is logged in ]</accountId>
		<CinchFeed>
			<feedURL>[the url for the Cinch Feed to modify]</feedURL>
			<feedName>[the new name of the Cinch Album Feed]</feedName>
			<feedDescription>
				[optional description for this Cinch Album Feed]
			</feedDescription>
			<public>
				[true or false, depending on whether this feed should be 
				 public or private]
			</public>
		</CinchFeed>
	</ModifyCinchFeed>	
</BlogTalkRadioRequest>

Response:

<BlogTalkRadioResponse command=”ModifyCinchFeed”
			     sequence=”[unique sequence number from client]”>
	<success>[1 or 0]</success>
	<error></error>
</BlogTalkRadioResponse>

Request:

<BlogTalkRadioRequest command=”GetSubscribedCinchFeeds”
			    deviceId=”[unique identifier for current client device]”
			    sequence=”[unique sequence number from client]”>
	<GetSubscribedCinchFeeds>
		<sessionId></sessionId>
		<accountId></accountId>
		<offset>
			[the offset into the set of feeds for this user account to
             start returning feeds from]
		</offset>
		<count>
			[the number of feeds to return]
		</count>
	</GetSubscribedCinchFeeds>
</BlogTalkRadioRequest>

Response:

<BlogTalkRadioResponse command=”GetSubscribedCinchFeeds”
			     sequence=”[unique sequence number from client request]” >
	<success>[1 or 0]</success>
	<Errors></Errors>
	<totalCount>
		[the total number of feeds that the current user account is subscribed to]
	</totalCount>
	<CinchFeeds>
		[the list of Cinch feeds that the current user is subscribed to based
         on the offset and count requested]
            <CinchFeed>
			<feedName>[the name of the Cinch Feed to display]</feedName>
			<feedURL>[the url for this Cinch Feed]</feedURL>
			<feedDescription>
				[optional description of this Cinch Feed]
			</feedDescription>
			<editable>
		[true or false, depending on whether the user can edit this feed 
				 (delete recordings from it)]
			</editable>
			<public>
		[true or false, reflecting whether this feed is public or private]
			</public>
			<parentFeedURL>
				[the URL for the parent Cinch feed if this feed is a “child” 
				 album feed of a parent Cinch feed]
			</parentFeedURL>
			<parentFeedURL>
			 [the url of this feeds parent if applicable]
			</parentFeedURL>
    			<userIsSubscribed>
[true or false, reflecting whether this user subscribed to this feed]
			</userIsSubscribed>
		</CinchFeed>
		<CinchFeed>
			...
		</CinchFeed>
		...
	</CinchFeeds>
</BlogTalkRadioResponse>

Request:

<BlogTalkRadioRequest command=”SearchForCinchFeeds”
			    deviceId=”[unique identifier for current client device]”
			    sequence=”[unique sequence number from client]” >
	<SearchForCinchFeeds>
		<sessionId></sessionId>
		<accountId></accountId>
		<query>[the keyword(s) query to search for]</query>
		<offset>
			[the offset into the result set for this search query to
             start returning results from]
		</offset>
		<count>
			[the number of results to return]
		</count>
	</SearchForCinchFeeds>
</BlogTalkRadioRequest>

Response:

<BlogTalkRadioResponse command=”SearchForCinchFeeds”
			     sequence=”[unique sequence number from client request]” >
	<success>[1 or 0]</success>
	<Errors></Errors>
	<totalCount>
		[the total number of feeds for the current search query]
	</totalCount>
	<CinchFeeds>
		[the list of Cinch Feeds for the current query based on the 
 		 offset and count requested]
		<CinchFeed>
			<feedName>[the name of the Cinch Feed to display]</feedName>
			<feedURL>[the url for this Cinch Feed]</feedURL>
			<feedDescription>
				[the optional description for this Cinch Feed]
			</feedDescription>
			<editable>
		[true or false, depending on whether the user can edit this feed 
				 (delete recordings from it)]
			</editable>
			<public>
		[true or false, reflecting whether this feed is public or private]
			</public>
			<parentFeedURL>
				[the URL for the parent Cinch feed if this feed is a “child” 
				 album feed of a parent Cinch feed]
			</parentFeedURL>
			<userIsSubscribed>
[true or false, reflecting whether this user subscribed to this feed]
			</userIsSubscribed>
		</CinchFeed>
		<CinchFeed>
			...
		</CinchFeed>
		...
	</CinchFeeds>
</BlogTalkRadioResponse>

Request:

<BlogTalkRadioRequest command=”SearchForCinchRecordings”
			    deviceId=”[unique identifier for current client device]”
			    sequence=”[unique sequence number from client]” >
	<SearchForCinchRecordings>
		<sessionId></sessionId>
		<accountId></accountId>
		<query>[the keyword(s) query to search for]</query>
		<offset>
			[the offset into the result set for this search query to
             start returning results from]
		</offset>
		<count>
			[the number of results to return]
		</count>
	</SearchForCinchRecordings>
</BlogTalkRadioRequest>

Response:

<BlogTalkRadioResponse command=”SearchForCinchRecordings”
			     sequence=”[unique sequence number from client request]” >
	<success>[1 or 0]</success>
	<Errors></Errors>
	<totalCount>
		[the total number of results for the current search query]
	</totalCount>
	<CinchRecordings>
		<CinchRecording>
			<UserAccount>
				<accountId>
[the account id for the currently logged in user, or empty if there is not a logged in user ]
				</accountId>
				<username>[username for the user account]</username>
				<email>[optional email address for this user account]</email>
				<avatarImageURL> 
[optional URL for the avatar image for this user account]
				</avatarImageURL>
			</UserAccount>
			<name> [name of recording]</name>
			<duration> [duration in milliseconds]</duration>
			<gps> 
				[gps string that defines the location that the 
				recording was made at] 
			</gps>
			<dateRecorded> 
				[date string that defines when the recording was made] 
			</dateRecorded>
			<description> 
				[optional description for this cinch recording ]
			</description>
			<tags> [optional list of  extra meta data content ]
				<tag> [value] </tag>
				<tag> [value] </tag>
				...
			</tags>
			<recordingId>
				 [the unique identifier for this recording] 
			</recordingId>	
			<recordingURL> 
				[the URL for the audio file for this recording] 
			</recordingURL>
			<imageId> 
				[optional - the unique identifier for the optional 
				full sized image for the recording] 
			</imageId>
			<imageURL> 
				[optional - the URL for the full sized image file for this 
				recording] 
			</imageURL>
			<thumbnailImageId> 
				[optional - the unique identifier for the thumbnail image for 
				the recording.  This thumbnail image will be smaller than the 
				full screen image for the recording.  Actual size TBD based on 
				the user interface design, but it will most likely be approx. 
				75 pixels x 75 pixels] 
			</thumbnailImageId>
			<thumbnailImageURL> 
				[optional - the URL for the thumbnail image file for 
				this recording] 
			</thumbnailImageURL>
			<feedURL>[the url for the Cinch Feed for this recording]</feedURL>
			<editable>
[true or false, depending on whether the user can edit this feed (delete recordings from it)]
			</editable>
		</CinchRecording>
		...
	</CinchRecordings>	
</BlogTalkRadioResponse>

Request:

<BlogTalkRadioRequest command=”GetRecordingsForCinchFeed”
			    deviceId=”[unique identifier for current client device]”
			    sequence=”[unique sequence number from client]” >
	<GetRecordingsForCinchFeed>
		<sessionId></sessionId>
		<accountId></accountId>
		<feedURL>[the URL of the Cinch feed to return recordings for]</feedURL>
		<offset>
			[the offset into the set of recordings for this feed 
            to start returning recordings from]
		</offset>
		<count> [the number of recordings to return]</count>
	</GetRecordingsForCinchFeed>
</BlogTalkRadioRequest>

Response:

<BlogTalkRadioResponse command=”GetRecordingsForCinchFeed”
			     sequence=”[unique sequence number from client request]” >
	<success>[1 or 0]</success>
	<Errors></Errors>
	<totalCount>[the total number of recordings for the Cinch feed]</totalCount>
	<CinchRecordings>
		[the list of Cinch Recordings for the current feed based on the 
		 offset and count requested]
		<CinchRecording>
			<UserAccount>
				<accountId>
[the account id for the currently logged in user, or empty if there is not a logged in user ]
				</accountId>
				<username>[username for the user account]</username>
				<email>[optional email address for this user account]</email>
				<avatarImageURL> 
[optional URL for the avatar image for this user account]
				</avatarImageURL>
			</UserAccount>
			<name> [name of recording]</name>
			<duration> [duration in milliseconds]</duration>
			<gps> 
				[gps string that defines the location that the 
				recording was made at] 
			</gps>
			<dateRecorded> 
				[date string that defines when the recording was made] 
			</dateRecorded>
			<description> 
				[optional description for this cinch recording ]
			</description>
			<tags> [optional list of  extra meta data content ]
				<tag> [value] </tag>
				<tag> [value] </tag>
				...
			</tags>
			<recordingId>
				 [the unique identifier for this recording] 
			</recordingId>	
			<recordingURL> 
				[the URL for the audio file for this recording] 
			</recordingURL>
			<imageId> 
				[optional - the unique identifier for the optional 
				full sized image for the recording] 
			</imageId>
			<imageURL> 
				[optional - the URL for the full sized image file for this 
				recording] 
			</imageURL>
			<thumbnailImageId> 
				[optional - the unique identifier for the thumbnail image for 
				the recording.  This thumbnail image will be smaller than the 
				full screen image for the recording.  Actual size TBD based on 
				the user interface design, but it will most likely be approx. 
				75 pixels x 75 pixels] 
			</thumbnailImageId>
			<thumbnailImageURL> 
				[optional - the URL for the thumbnail image file for 
				this recording] 
			</thumbnailImageURL>
			<feedURL>[the url for the Cinch Feed for this recording]</feedURL>
			<editable>
[true or false, depending on whether the user can edit this feed (delete recordings from it)]
			</editable>
		</CinchRecording>
		<CinchRecording>
			...
		</CinchRecording>
		...
	</CinchRecordings>
</BlogTalkRadioResponse>

Request:

<BlogTalkRadioRequest command=”SubscribeToCinchFeed”
			    deviceId=”[unique identifier for current client device]”
			    sequence=”[unique sequence number from client]” >
	<SubscribeToCinchFeed>
		<sessionId></sessionId>
		<accountId></accountId>
		<feedURL>[the URL of the Cinch feed to subscribe to]</feedURL>
	</SubscribeToCinchFeed>
</BlogTalkRadioRequest>

Response:

<BlogTalkRadioResponse command=”SubscribeToCinchFeed”
			     sequence=”[unique sequence number from client request]” >
	<success>[1 or 0]</success>
	<Errors></Errors>
</BlogTalkRadioResponse>

Request:

<BlogTalkRadioRequest command=” UnsubscribeFromCinchFeed”
			    deviceId=”[unique identifier for current client device]”
			    sequence=”[unique sequence number from client]” >
	<UnsubscribeFromCinchFeed>
		<sessionId></sessionId>
		<accountId></accountId>
		<feedURL>[the URL of the Cinch feed to subscribe to]</feedURL>
	</UnsubscribeFromCinchFeed>
</BlogTalkRadioRequest>

Response:

<BlogTalkRadioResponse command=”UnsubscribeFromCinchFeed”
			     sequence=”[unique sequence number from client request]” >
	<success>[1 or 0]</success>
	<Errors></Errors>
</BlogTalkRadioResponse>

Request:

<BlogTalkRadioRequest command=”GetUserAuthorizationForFeed”
			    deviceId=”[unique identifier for current client device]”
			    sequence=”[unique sequence number from client]” >
	<GetUserAuthorizationForFeed>
		<sessionId></sessionId>
		<accountId></accountId>
		<feedURL>[the URL of the Cinch feed to check authorization for]</feedURL>
	</GetUserAuthorizationForFeed>
</BlogTalkRadioRequest>

Response:

<BlogTalkRadioResponse command=”GetUserAuthorizationForFeed”
			     sequence=”[unique sequence number from client request]” >
	<success>[1 or 0 based on whether the call was successful]</success>
	<Errors></Errors>
	<authorized>
		[1 or 0, depending on whether the user has access to the feed or not]
	</authorized>
</BlogTalkRadioResponse>

Request:

<BlogTalkRadioRequest command=”DeleteCinchRecordings”
			    deviceId=”[unique identifier for current client device]” 
			    sequence=”[unique sequence number from client]” >
	<DeleteCinchRecordings>
		<sessionId></sessionId>
		<accountId></accountId>
		<recordingIDs>
			[list of recording ids to delete]
			<recordingId>[identifier for a recording to delete]</recordingId>
			<recordingId>[identifier for a recording to delete]</recordingId>
			...
		</recordingIDs>
	</DeleteCinchRecordings>
</BlogTalkRadioRequest>

Response:

<BlogTalkRadioResponse command=”DeleteCinchRecordings”
			     sequence=”[unique sequence number from client request]” >
	<success>[1 or 0]</success>
	<Errors></Errors>
</BlogTalkRadioResponse>

Request:

<BlogTalkRadioRequest command=”DeleteCinchFeedAlbum”
			    deviceId=”[unique identifier for current client device]” 
			    sequence=”[unique sequence number from client]” >
	<DeleteCinchFeedAlbum>
		<sessionId></sessionId>
		<accountId></accountId>
		<feedURL>[the URL of the Cinch feed album to delete]</feedURL>
	</DeleteCinchFeedAlbum>
</BlogTalkRadioRequest>

Response:

<BlogTalkRadioResponse command=”DeleteCinchFeedAlbum”
			     sequence=”[unique sequence number from client request]” >
	<success>[1 or 0]</success>
	<Errors></Errors>
</BlogTalkRadioResponse>

Request:

<BlogTalkRadioRequest command=”GetPublicCinchRecordings”
			    deviceId=”[unique identifier for current client device]”
			    sequence=”[unique sequence number from client]” >
	<GetPublicCinchRecordings>
		<sessionId></sessionId>
		<accountId></accountId>
		<offset>
			[the offset into the result set for this search query 
            to start returning results from]
		</offset>
		<count>
			[the number of results to return]
		</count>
	</GetPublicCinchRecordings>
</BlogTalkRadioRequest>

Response:

<BlogTalkRadioResponse command=”GetPublicCinchRecordings”
			     sequence=”[unique sequence number from client request]” >
	<success>[1 or 0]</success>
	<Errors></Errors>
	<CinchRecordings>
		<CinchRecording>
			<UserAccount>
				<accountId>
[the account id for the currently logged in user, or empty if there is not a logged in user ]
				</accountId>
				<username>[username for the user account]</username>
				<email>[optional email address for this user account]</email>
				<avatarImageURL> 
[optional URL for the avatar image for this user account]
				</avatarImageURL>
			</UserAccount>
			<name> [name of recording]</name>
			<duration> [duration in milliseconds]</duration>
			<gps> 
				[gps string that defines the location that the 
				recording was made at] 
			</gps>
			<dateRecorded> 
				[date string that defines when the recording was made] 
			</dateRecorded>
			<description> 
				[optional description for this cinch recording ]
			</description>
			<tags> [optional list of  extra meta data content ]
				<tag> [value] </tag>
				<tag> [value] </tag>
				...
			</tags>
			<recordingId>
				 [the unique identifier for this recording] 
			</recordingId>	
			<recordingURL> 
				[the URL for the audio file for this recording] 
			</recordingURL>
			<imageId> 
				[optional - the unique identifier for the optional 
				full sized image for the recording] 
			</imageId>
			<imageURL> 
				[optional - the URL for the full sized image file for this 
				recording] 
			</imageURL>
			<thumbnailImageId> 
				[optional - the unique identifier for the thumbnail image for 
				the recording.  This thumbnail image will be smaller than the 
				full screen image for the recording.  Actual size TBD based on 
				the user interface design, but it will most likely be approx. 
				75 pixels x 75 pixels] 
			</thumbnailImageId>
			<thumbnailImageURL> 
				[optional - the URL for the thumbnail image file for 
				this recording] 
			</thumbnailImageURL>
			<feedURL>[the url for the Cinch Feed for this recording]</feedURL>
			<editable>
[true or false, depending on whether the user can edit this feed (delete recordings from it)]
			</editable>
		</CinchRecording>
		...
	</CinchRecordings>
	
</BlogTalkRadioResponse>

This is called when the user is browsing CinchCast audio content within an application and stops listening to an audio stream before the end of the stream so that we can start playing from the “last listened to” location the next time the user starts listening to the same stream.

Request:

<BlogTalkRadioRequest command=”SetStreamPositionForUser”
			    deviceId=”[unique identifier for current client device]”
			    sequence=”[unique sequence number from client]” >
	<SetStreamPositionForUser>
		<sessionId></sessionId>
		<accountId></accountId>
		<streamURL>
			[the URL of the CinchCast audio stream that we are 
            setting the position for]
		</streamURL>
		<streamPosition>
			[stream position in milliseconds that the user stopped listening at]
		</streamPosition>
	</SetStreamPositionForUser>
</BlogTalkRadioRequest>

Response:

<BlogTalkRadioResponse command=”SetStreamPositionForUser”
			     sequence=”[unique sequence number from client request]” >
	<success>[1 or 0]</success>
	<Errors></Errors>
</BlogTalkRadioResponse>

This is called when the user is browsing CinchCast audio content within an application to retrieve the last location within an audio stream that a user was listening to.

Request:

<BlogTalkRadioRequest command=”GetStreamPositionForUser”
			    deviceId=”[unique identifier for current client device]”
			    sequence=”[unique sequence number from client]” >
	<GetStreamPositionForUser>
		<sessionId></sessionId>
		<accountId></accountId>
		<streamURL>
			[the URL of the CinchCast audio stream that we are 
            getting the position for]
		</streamURL>
	</GetStreamPositionForUser>
</BlogTalkRadioRequest>

Response:

<BlogTalkRadioResponse command=”GetStreamPositionForUser”
			     sequence=”[unique sequence number from client request]” >
	<success>[1 or 0]</success>
	<Errors></Errors>
	<streamPosition>
			[stream position in milliseconds that the user stopped listening at]
	</streamPosition>
</BlogTalkRadioResponse>

Request:

<BlogTalkRadioRequest command=”ForgotPassword”
			    deviceId=”[unique identifier for current client device]” 
			    sequence=”[unique sequence number from client]” >
	<ForgotPassword>
		<UserAccount>
			<username>[users user name]</username>
			<email>
[users email address this must match the to the username we have on file]
			</email>
		</UserAccount>
	</ForgotPassword>
</BlogTalkRadioRequest>

Response:

<BlogTalkRadioResponse command=”ForgotPassword”
			     sequence=”[unique sequence number from client request]” >
	<success>[1 or 0]</success>
	<Errors></Errors>
</BlogTalkRadioResponse>

Request:

<BlogTalkRadioRequest command=”ModifyPassword”
			    deviceId=”[unique identifier for current client device]” 
			    sequence=”[unique sequence number from client]” >
	<ModifyPassword>
		<username>[webservice username]</username>
		<newUsername>[optional webservice new username]</newUsername>
		<currentPassword>[webservice current password]</currentPassword>
		<newPassword>[optional webservice new password] </newPassword>
	</ModifyPassword>
</BlogTalkRadioRequest>

Response:

<BlogTalkRadioResponse command=”ModifyPassword”
			     sequence=”[unique sequence number from client request]” >
	<success>[1 or 0]</success>
	<Errors></Errors>
</BlogTalkRadioResponse>

The client will break up images and audio recording files into packets that it will post to the web server via HTTP PUT calls. The header fields should identify what the data being posted is for and information on the packet that is being posted. The body of the HTML request should be the packet’s actual data.

The final packet being posted should include “btr-is-last-packet:true” as one of the header fields so that the web server can recognize that the client is done posting all of the data and can compile the information and make it available for download.

The HTTP header when posting an image or audio recording to the web server should include the following fields:

Back to Top

• User-Agent: [device_type]/[app_version] [deviceId] (same information described at top of this document)
• btr-method: PostUserAvatarImage
• btr-account-id: [identifier returned from web service identifying the user account that this image is for]
• btr-packet-number: [the image packet number being posted as part of this HTTP PUT]
• btr-is-last-packet: [true or false depending on whether this is the last packet for the image or not]
• btr-packet-size: [the size of this packet’s image data (in bytes) included in the body of this HTTP PUT]
• btr-total-data-size: [the overall size of the entire image data in bytes (all packets)]

Back to Top

• User-Agent: [device_type]/[app_version] [deviceId] (same information described at top of this document)
• btr-method: PostRecordingImage
• btr-recording-id: [identifier returned from web service identifying the recording that this image is for]
• btr-image-id: [identifier returned from web service identifying this image]
• btr-packet-number: [the image packet number being posted as part of this HTTP PUT]
• btr-is-last-packet: [true or false depending on whether this is the last packet for the image or not]
• btr-packet-size: [the size of this packet’s image data (in bytes) included in the body of this HTTP PUT]
• btr-total-data-size: [the overall size of the entire image data in bytes (all packets)]

Back to Top