Playwire™ API Reference

Request Index

Video List

The first task you might want to accomplish with the Playwire™ API is to get a list of your videos. This is done with the index action:

GET http://www.playwire.com/api/v1/videos/index.xml?token=YOURTOKENHERE

By default this returns the first 12 videos, ordered by the creation date in descending order, meaning the newest video is first. Each video element in the returned list will have an ID, name, thumbnail URL, category ID, category name, time created, and number of views. This abbreviated list of fields should be enough to show a list of videos. More details about the videos can be gotten with the show video action below.

Required Parameters

  • token

Optional Parameters

  • q - A string query parameter which will return videos which have this string in their name or tags.
  • sort - A string parameter which defines the sort order. Options are title to sort by the video name, created_at to sort by creation time, and total_views to sort by views. All these can have _desc appended to sort in descending order. The default is created_at_desc.
  • count - A number parameter indicating the number of videos to show per request. The maximum is 200. The default is 12.
  • page - A number parameter indicating the "page" of videos which should be shown. This relates to the count parameter above. For example with a count of 10, page 2 shows videos 11-20. The default is 1. Any page number below 1 will just return page 1. Any page number above the maximum page for the given count will return an empty list of videos.

Successful Result

<videos type="array">
<video>
    <category_id type="integer">16</category_id>
    <created_at type="datetime">2010-12-03T19:40:24-05:00</created_at>
    <id type="integer">1254</id>
    <name>Super Street Fighter IV Arcade</name>
    <thumb_url>http://playwire.videos.s3.amazonaws.com/343/thumb-20101203-1254.jpg</thumb_url>
    <total_views type="integer">0</total_views>
    <category_name>Games</category_name>
  </video>
  <video>
    <category_id type="integer">24</category_id>
    <created_at type="datetime">2010-12-03T18:46:39-05:00</created_at>
    <id type="integer">1253</id>
    <name>World of Warcraft: Cataclysm - World Reborn</name>
    <thumb_url>http://playwire.videos.s3.amazonaws.com/343/thumb-20101203-1253.jpg</thumb_url>
    <total_views type="integer">0</total_views>
    <category_name>Animation</category_name>
  </video>
  [...10 more videos...]
</videos>

Possible Errors

  • General Generic Error for server problems
  • General Access Denied Error for invalid token

Video Count

When getting the index of videos it is useful to know the total number of videos. For example this can be used to generate links for additional pages of videos if needed. The count of videos can be gotten with the count action:

GET http://www.playwire.com/api/v1/videos/count.xml?token=YOURTOKENHERE

This is a very simple action which just returns a number.

Required Parameters

  • token

No Optional Parameters

Successful Result

<result>
  <count type="integer">943</count>
</result>

Possible Errors

  • General Generic Error for server problems
  • General Access Denied Error for invalid token

Video Sandbox List

Another list of videos which you may be interested in getting with the API is Sandbox videos. This is done with the sandbox action:

GET http://www.playwire.com/api/v1/videos/sandbox.xml?token=YOURTOKENHERE

By default this returns the first 12 videos in the sandbox, ordered by the creation date in descending order, meaning the newest video is first. Each video in the list will have the same fields as those in the video index action above.

Required Parameters

  • token

Optional Parameters

  • q - A string query parameter which will return videos which have this string in their name or tags.
  • sort - A string parameter which defines the sort order. Options are title to sort by the video name, created_at to sort by creation time, and total_views to sort by views. All these can have _desc appended to sort in descending order. The default is created_at_desc.
  • count - A number parameter indicating the number of videos to show per request. The maximum is 200. The default is 12.
  • page - A number parameter indicating the "page" of videos which should be shown. This relates to the count parameter above. For example with a count of 10, page 2 shows videos 11-20. The default is 1. Any page number below 1 will just return page 1. Any page number above the maximum page for the given count will return an empty list of videos.
  • category_id - A number parameter indicating that only sandbox videos in that category should be returned. A mapping of category names to ids can be gotten with the video category action described below.

Successful Result

<videos type="array">
 <video>
    <category_id type="integer">17</category_id>
    <created_at type="datetime">2011-01-10T14:26:02-05:00</created_at>
    <id type="integer">1263</id>
    <name>Playwire Intro</name>
    <thumb_url>http://playwire.videos.stage.s3.amazonaws.com/1568/thumb-20110110-1263_0000.png</thumb_url>
    <total_views type="integer">0</total_views>
    <category_name>Technology</category_name>
  </video>
  <video>
    <category_id type="integer">16</category_id>
    <created_at type="datetime">2010-12-28T08:00:07-05:00</created_at>
    <id type="integer">1257</id>
    <name>Seven Tree: The Passageway</name>
    <thumb_url nil="true"></thumb_url>
    <total_views type="integer">0</total_views>
    <category_name>Games</category_name>
  </video>
 [...10 more videos...]
</videos>

Possible Errors

  • General Generic Error for server problems
  • General Access Denied Error for invalid token

Video Sandbox Count

Like the video count above you can also get the count of sandbox videos. This can be gotten with the sandbox_count action:

GET http://www.playwire.com/api/v1/videos/sandbox_count.xml?token=YOURTOKENHERE

This is a very simple action which just returns a number.

Required Parameters

  • token

No Optional Parameters

Successful Result

<result>
  <count type="integer">918</count>
</result>

Possible Errors

  • General Generic Error for server problems
  • General Access Denied Error for invalid token

Show User Video

To get details for a video owned by the API user's publisher, you can use the show video action:

GET http://www.playwire.com/api/v1/videos/show/VIDEO_ID_HERE.xml?token=YOURTOKENHERE

This will return an XML representation of the video, including JavaScript and HTML which can be used to embed the video into a web page. If there is no such video ID or if the video is not owned by the API user's publisher, an error will be returned.

Required Parameters

  • id - The video ID, which should be part of the URL as shown above.
  • token

No Optional Parameters

Successful Result

<video>
  <aspect_ratio>letterbox</aspect_ratio>
  <auto_start type="boolean">false</auto_start>
  <category_id type="integer">8</category_id>
  <created_at type="datetime">2010-12-03T19:40:24-05:00</created_at>
  <description>Japanese, but perhaps new characters via DLC?</description>
  <featured type="boolean" nil="true"></featured>
  <hd_url nil="true"></hd_url>
  <height type="integer">354</height>
  <id type="integer">1254</id>
  <name>Super Street Fighter IV Arcade</name>
  <show_video_watermark type="boolean">true</show_video_watermark>
  <status>ready</status>
  <thumb_url>http://playwire.videos.s3.amazonaws.com/343/thumb-20101203-1254.jpg</thumb_url>
  <total_bandwidth type="integer">0</total_bandwidth>
  <total_views type="integer">0</total_views>
  <updated_at type="datetime">2011-03-02T15:11:46-05:00</updated_at>
  <use_age_gate type="boolean">false</use_age_gate>
  <video_url>http://playwire.videos.s3.amazonaws.com/343/video-20101203-1254.flv</video_url>
  <width type="integer">630</width>
  <category_name></category_name>
  <public type="boolean">false</public>
  <js_embed_code>&lt;script src='http://cdn.test.playwire.com/343/embed/1254.js'&gt;&lt;/script&gt;</js_embed_code>
  <embed_code>&lt;object classid=&quot;clsid:D27CDB6E-AE6D-11cf-96B8-444553540000&quot; width=&quot;630&quot; height=&quot;354&quot; id=&quot;playwire_player_1254&quot; name=&quot;playwire_player_1254&quot;&gt;
&lt;param name=&quot;movie&quot; value=&quot;http://cdn.test.playwire.com/bolt.swf&quot;&gt;
&lt;param name=&quot;wmode&quot; value=&quot;transparent&quot;&gt;
&lt;param name=&quot;allowfullscreen&quot; value=&quot;true&quot;&gt;
&lt;param name=&quot;allowscriptaccess&quot; value=&quot;always&quot;&gt;
&lt;param name=&quot;flashvars&quot; value=&quot;configuration=http://cdn.test.playwire.com/343/embed/1254.xml&quot;&gt;
&lt;embed id=&quot;playwire_player_1254&quot; name=&quot;playwire_player_1254&quot; src=&quot;http://cdn.test.playwire.com/bolt.swf&quot; wmode=&quot;transparent&quot; width=&quot;630&quot; height=&quot;354&quot; allowscriptaccess=&quot;always&quot; allowfullscreen=&quot;true&quot; flashvars=&quot;configuration=http://cdn.test.playwire.com/343/embed/1254.xml&quot;&gt;
&lt;/embed&gt;
&lt;/object&gt;
</embed_code>
  <tags type="array">
    <tag>
      <id type="integer">545</id>
      <name>Super Street Fighter IV</name>
    </tag>
    <tag>
      <id type="integer">22</id>
      <name>xbox 360</name>
    </tag>
    <tag>
      <id type="integer">7</id>
      <name>ps3</name>
    </tag>
    <tag>
      <id type="integer">302</id>
      <name>DLC</name>
    </tag>
    <tag>
      <id type="integer">10</id>
      <name>capcom</name>
    </tag>
  </tags>
</video>

Possible Errors

  • General Generic Error for server problems
  • General Access Denied Error for invalid token or for videos that do no belong to the user's publisher
  • General Record Not Found Error for an invalid video ID

Show Sandbox Video

To get details for a video in the video sandbox, you can use the sandbox video profile action:

GET http://www.playwire.com/api/v1/videos/sandbox/VIDEO_ID_HERE.xml?token=YOURTOKENHERE

This will return an XML representation of the video, including JavaScript and HTML which can be used to embed the video into a web page. Since this is a sandbox video, less fields are provided than are provided in the show video action above. If there is no such video ID, an error will be returned.

Required Parameters

  • id - The video ID, which should be part of the URL as shown above.
  • token

No Optional Parameters

Successful Result

<video>
  <category_id type="integer">8</category_id>
  <created_at type="datetime">2010-11-29T14:24:21-05:00</created_at>
  <description>Description</description>
  <id type="integer">1228</id>
  <name>FFXI Heroes of Abyssea Trailer</name>
  <thumb_url>http://playwire.videos.s3.amazonaws.com/343/thumb-20101129-1228.jpg</thumb_url>
  <total_views type="integer">50</total_views>
  <category_name></category_name>
  <public type="boolean">true</public>
  <js_embed_code>&lt;script src='http://cdn.test.playwire.com/343/embed/1228.js'&gt;&lt;/script&gt;</js_embed_code>
  <embed_code>&lt;object classid=&quot;clsid:D27CDB6E-AE6D-11cf-96B8-444553540000&quot; width=&quot;630&quot; height=&quot;354&quot; id=&quot;playwire_player_1228&quot; name=&quot;playwire_player_1228&quot;&gt;
&lt;param name=&quot;movie&quot; value=&quot;http://cdn.test.playwire.com/bolt.swf&quot;&gt;
&lt;param name=&quot;wmode&quot; value=&quot;transparent&quot;&gt;
&lt;param name=&quot;allowfullscreen&quot; value=&quot;true&quot;&gt;
&lt;param name=&quot;allowscriptaccess&quot; value=&quot;always&quot;&gt;
&lt;param name=&quot;flashvars&quot; value=&quot;configuration=http://cdn.test.playwire.com/343/embed/1228.xml&quot;&gt;
&lt;embed id=&quot;playwire_player_1228&quot; name=&quot;playwire_player_1228&quot; src=&quot;http://cdn.test.playwire.com/bolt.swf&quot; wmode=&quot;transparent&quot; width=&quot;630&quot; height=&quot;354&quot; allowscriptaccess=&quot;always&quot; allowfullscreen=&quot;true&quot; flashvars=&quot;configuration=http://cdn.test.playwire.com/343/embed/1228.xml&quot;&gt;
&lt;/embed&gt;
&lt;/object&gt;
</embed_code>
  <tags type="array">
    <tag>
      <id type="integer">529</id>
      <name>Final Fantasy XI</name>
    </tag>
    <tag>
      <id type="integer">530</id>
      <name>SquareEnix</name>
    </tag>
    <tag>
      <id type="integer">26</id>
      <name>mmo</name>
    </tag>
  </tags>
</video>

Possible Errors

  • General Generic Error for server problems
  • General Access Denied Error for invalid token or for videos that do no belong to the user's publisher and are not in the sandbox
  • General Record Not Found Error for an invalid video ID

New Video Defaults

When uploading new videos there are certain default values which can be prefilled in an upload form. This allows API users to mimic the behavior of the Playwire video upload form. Default values can be gotten with the new action:

GET http://www.playwire.com/api/v1/videos/new.xml?token=YOURTOKENHERE

This will return the fields which have default values for a new video.

Required Parameters

  • token

No Optional Parameters

Successful Result

<video>
  <aspect_ratio>letterbox</aspect_ratio>
  <auto_start type="boolean">false</auto_start>
  <height type="integer">354</height>
  <show_video_watermark type="boolean">true</show_video_watermark>
  <use_age_gate type="boolean" nil="true"></use_age_gate>
  <width type="integer">630</width>
</video>

Possible Errors

  • General Generic Error for server problems
  • General Access Denied Error for invalid token

Upload New Video

Videos can be uploaded with the API, but only using a URL of the source video. Currently uploading a file is not supported by the API. All video parameter names are in the format video[name]. Video uploading is done by posting to the create action:

POST http://www.playwire.com/api/v1/videos/create.xml

This will return the new video if it was successfully created, and will return an error in any case that the video could not be created.

Required Parameters

  • token
  • video[name] - The video's name.
  • video[source_url] - The URL for the source video to be used when creating this video.

Optional Parameters

  • video[description] - The description of the video. The default is nothing.
  • video[height] - The preferred height of the video player when showing this video. The default is the default video height configured for the API user's publisher.
  • video[width] - The preferred width of the video player when showing this video. The default is the default video width configured for the API user's publisher.
  • video[category_id] - The ID of the video category that this video should be under. A list of categories can be gotten with the category index action described below. The default is no category.
  • video[tag_list] - A comma-separated list of tags to be associated with this video. The default is no tags.
  • video[show_video_watermark] - A boolean parameter indicating whether the video player should show your video watermark when playing this video. This parameter should be 1 for true, 0 for false. The default is true.
  • video[public] - A boolean parameter indicating whether this video should show in the video sandbox.
  • video[use_age_gate] - A boolean parameter indicating whether this video should show the age gate, meaning the content is for mature audiences. This parameter should be 1 for true, 0 for false. The default is false.
  • video[auto_start] - A boolean parameter indicating that the video should automatically start when the page is loaded. Turning this on will cause the player to NOT show any ads, so the recommended setting is false. This parameter should be 1 for true, 0 for false. The default is false.

Successful Result

Same as Show User Video

Possible Errors

  • General Generic Error for server problems
  • General Access Denied Error for invalid token or not using a POST request
  • Field Validation Errors for missing name and source_url and other validation problems.

Update Existing Video

Existing videos can be updated with the API. Like video creation, if the video content needs to be updated it must be done by using a URL of the source video. All video parameter names are in the format video[name]. Video updating is done by posting to the update action:

POST http://www.playwire.com/api/v1/videos/update.xml

This will return the new video if it was successfully updated, and will return an error in any case that the video could not be updated.

Required Parameters

  • token

Optional Parameters

  • video[name] - The video's name.
  • video[source_url] - The URL for the source video to be used when updating the video content.
  • video[description] - The description of the video.
  • video[height] - The preferred height of the video player when showing this video.
  • video[width] - The preferred width of the video player when showing this video.
  • video[category_id] - The ID of the video category that this video should be under. A list of categories can be gotten with the category index action described below.
  • video[tag_list] - A comma-separated list of tags to be associated with this video.
  • video[show_video_watermark] - A boolean parameter indicating whether the video player should show your video watermark when playing this video. This parameter should be 1 for true, 0 for false.
  • video[public] - A boolean parameter indicating whether this video should show in the video sandbox.
  • video[use_age_gate] - A boolean parameter indicating whether this video should show the age gate, meaning the content is for mature audiences. This parameter should be 1 for true, 0 for false.
  • video[auto_start] - A boolean parameter indicating that the video should automatically start when the page is loaded. Turning this on will cause the player to NOT show any ads, so the recommended setting is false. This parameter should be 1 for true, 0 for false.

Successful Result

Same as Show User Video, with the updated fields.

Possible Errors

  • General Generic Error for server problems
  • General Access Denied Error for invalid token or not using a POST request or for videos that do no belong to the user's publisher
  • General Record Not Found Error for an invalid video ID
  • Field Validation Errors for missing name and other validation problems.

Delete Video

Videos owned by the API user's publisher can also be deleted using the API. Video deleting is done by posting to the destroy action:

POST http://www.playwire.com/api/v1/videos/destroy/VIDEO_ID_HERE.xml

This will return a message of success if the video could be deleted. If there is no such video ID or if the video is not owned by the API user's publisher, an error will be returned.

Required Parameters

  • id - The video ID, which should be part of the URL as shown above.
  • token

No Optional Parameters

Successful Result

<result>
  <message>Video deleted</message>
</result>

Possible Errors

  • General Generic Error for server problems
  • General Access Denied Error for invalid token or not using a POST request or for videos that do no belong to the user's publisher
  • General Record Not Found Error for an invalid video ID

Video Categories List

When viewing, updating or creating videos, having a mapping between video category ID values and category names can be useful. Getting the list of video categories is done with the category index action:

GET http://www.playwire.com/api/v1/video_categories/index.xml?token=YOURTOKENHERE

This will return a list of categories with each category having an ID and name. You can cache this list and then make use of it to create a drop down list of categories for video detail and uploading pages.

Required Parameters

  • token

No Optional Parameters

Successful Result

<video_categories type="array">
  <video_category>
    <id type="integer">23</id>
    <name>Animal &amp; Outdoors</name>
  </video_category>
  <video_category>
    <id type="integer">24</id>
    <name>Animation</name>
  </video_category>
  <video_category>
    <id type="integer">25</id>
    <name>Auto</name>
  </video_category>
[...more categories...]
</video_categories>

Possible Errors

  • General Generic Error for server problems
  • General Access Denied Error for invalid token