Skip Navigation

Warpwire Data API

Warpwire's technology runs on its own RESTful API.

This guide is intended for software developers and IT administrators who want to provide deep systems integration with Warpwire. It provides general information on the programmatic creation of objects via the REST API, data conventions, and integrating and merging with existing datasets. Understanding the basic Warpwire conventions will help you provide an optimal integration experience for your users.

This document is divided into sections that reflect each of the external data management layers that Warpwire provides. Warpwire leverages web standards for API communication, uses SSL for all data transmission and encryption, and provides access control levels for every API call.

Warpwire also integrates with an organization's Single Sign-On (SSO) system to provide both user authentication and authorization. Specifics regarding SSO integration are provided in additional specification guides and are outside the scope of this document. Warpwire uses a REST-ful style interface utilizing both REST nouns and verbs.

Data API: Conventions

Warpwire uses a few simple conventions throughout the entire API to ensure that operations are both consistent and predictable. There are a few API calls that deviate from these conventions — these deviations are explicitly noted. The following section lists the Warpwire nomenclature that is used throughout this document:

UUID — All objects are automatically assigned a Universally Unique Identifier (UUID). It is through this value that all objects are accessed. A UUID is guaranteed to be unique for every object within an organization and is analogous to a primary key.

Collection — A set of objects is stored in a collection. A collection can store both objects and additional collections. A collection is also commonly referred to as a "Media Library" in other end user documentation, however these terms are synonymous. Access control and permissions are managed on a collection basis where every item within a collection maintains the same permissions (see Permission section). If an object does not exist within a specified collection a 404 Not Found response is returned (see HTTP Response Codes for additional information).

If object A is a member of two different collections, C1 and C2, there is no guarantee that object A's permissions will be the same in both C1 and C2. However, you are guaranteed that every object within C1 and C2 will have the same base permissions.

UUID Specification — All UUIDs provided are assigned by the API upon object creation and follow the RFC 4122 version 5 specifications. All UUID's are in hexadecimal format and follow the pattern {8}-{4}-{4}-{4}-{16}, with dashes being optional. Most API GET request returns the object UUID as a response parameter.

Authentication Tokens — A token is expected to be supplied as a header request for every API call that is not public. If you make a private API call and do not provide an Authorization: OAuth header and accompanying token, the request will fail and return 401 Not Authorized. Please note that all tokens have expirations and must either be renewed or re-issued upon session expiration, user sign out, or token invalidation.

Data API: API Format

Most API calls follow this convention:

{ACTION}/c/{COLLECTION_UUID}/o/{OBJECT_UUID}

All requests that are non-public expect an Authorization: OAuth header. The API returns all data as an 8-bit UTF JSON encoded string. It is suggested that you also ensure that all input data is encoded in UTF-8 format to ensure maximum data consistency. Below is an example of a typical POST command using CURL.

curl https://api.example.com/api/describe/c/ABCDEF-1234-CDEF-5678-ABCDEF0123456789/o/CCCBBB-1234-CDEF-5678-ABCDEF0123456789/ -H 'Authorization: OAuth c4eFFFwnmnGIbud1Bxyyzmg4yHmD9D92DJhlWNIib' -X POST -d "title=My+first+title" –v

Data API: REST Conventions

Warpwire utilizes most of the HTTP methods including GET, POST, PUT, DELETE, OPTIONS, and HEAD. For clients that do not support a specific method such as DELETE or PUT, you should use the POST method and include a POST data variable named "_METHOD" with the value being the type of method in question (see the example below). Alternatively, you can also use the X-HTTP-Method-Override header directive to specify the missing method. Warpwire recommends that you use the CURL library as it supports the entire set of HTTP methods.

HTTP/1.1 {URL} POST

<input type="hidden" name="_METHOD" value="DELETE">

Warpwire uses the HTTP methods as follows:

GET — Returns JSON-encoded data for the supplied URL. The GET method expects the URL to include both the complete path for the resource and the identifying resource information (e.g. collection UUID). The GET command will always return a JSON-encoded object or the empty set if no data is returned. It also returns a corresponding HTTP response code that indicates the status of the transaction (i.e. 200 OK indicates a successful request and 400 Bad Request indicates a malformed request). Please see the HTTP Response Codes section for more information.

PUT — Used to create a new object. This method will return a HTTP 201 Created response upon the successful creation of a resource. Additionally, if the user does not have permission to issue the PUT call for a particular collection, the call will return a HTTP 403 Forbidden header. Please note that since you cannot manually assign a universally unique identifier for an object, re-issuing a PUT request will result in the creation of a new object.

POST — Used to update any existing object. This method will return a HTTP 202 Accepted response upon the successful modification of a resource. The POST command expects the URL to only contain information necessary to access the resource, such as the collection UUID and object UUID. All other parameters must be specified in the POST data fields. Note that some parameters can only be issued via the initial PUT request and cannot be changed via a POST request. If the user does not have permission to issue the POST command for a particular collection, the method will return a HTTP 403 Forbidden response.

DELETE — Removes a resource. This method will return a HTTP 200 OK response upon the successful deletion of a resource. The DELETE method is not available for most API calls. If the user does not have permission to issue the DELETE command for a particular collection, the method will return a HTTP 403 Forbidden response.

OPTIONS — Return 200 OK for most calls that issue this request. This call is used in conjunction with all pre-flight Cross-origin resource sharing (CORS) calls. If you are using the API via CURL (or other command line tools) it is not necessary to supply the OPTIONS call. For time consuming operations such as uploading, the OPTIONS method will return proper response information that should be used to determine if the operation should proceed (e.g. the user is not currently authenticated to perform the request). If you are calling the API via AJAX requests within a web browser, you must comply with all CORS requirements. Therefore, you must ensure that the server making the requests has been added to the allowed list of servers that may perform a Access-Control-Allow-Origin request.

Data API: Describe

Describe is the most basic and important Warpwire API call. You can think of a describe API call as a mobile phone's address book that provides basic metadata and routing information for a contact. The describe call is public and does not require any user authentication (nor the need to supply the Authorization: OAuth header). However, a public request will only a return a limited subset of data about an object while an authenticated call will return the complete record.

GET Method:

/api/describe/c/[collection_uuid]/o/[object_uuid]/

Request — The GET request must be in the following format.

Attribute Description
collection_uuid (required) A valid collection UUID resource.
object_uuid (required) A valid object UUID resource.

Response — For any GET request the following information can be returned in a JSON formatted object.

Attribute Description
type A textual version of the type of resource. This could include "catalog", "video", "audio", "file", etc.
title The title of the resource. A title may be blank or can be up to 255 characters in length.
images An array of images that accompany the object. Please note that the images array may be an empty set.
images.thumbnail A 128x128 pixel image of the resource (if available).
images.square A 512x512 pixel image of the resource (if available).
images.large A 1280x760 pixel image of the resource (if available).
public Should this resource be available to the public? The values can include either "true" or "false". Default value is "false".
metadata An array of metadata associated with the object. This could include additional information such as duration, or the empty set.
description Textual description of the object. This may be blank.
properties An array of properties that accompany the object. This could be an empty set.
uuid The universally unique identifier of the object.
userId Identifier of user who created the resource. This information is not informative without performing an additional user API call.
authenticated Indicates if the current user is authenticated. Value is either "true" or "false".
permLink A permanent shortened URL that a user can access the resource.
created An Epoch timestamp of the date the object was created.
modified An Epoch timestamp of the date the object was modified.

PUT Method:

/api/describe/c/[collection_uuid]/o/0/

Request — Adds an object to an existing collection. Any parameter not specified in the URL above must be submitted as a PUT data field. For any PUT request the following information may be provided.

Attribute Description
collection_uuid (required) A valid collection UUID resource. If the resource is 0 a new collection will be created.
type (required) A textual version of the type of resource. This could include "catalog", "video", "audio", "file", etc.
title The title of the resource. A title may be blank or can be up to 255 characters in length.
public Should this resource be available to the public? The values can include either "true" or "false". Default value is "false".
description Textual description of the object. This may be blank.
duration The duration of the media object in seconds.

Response — The following response is returned for the PUT request as a JSON encoded object.

Attribute Description
uuid The universally unique identifier of the object.

POST Method:

/api/describe/c/[collection_uuid]/o/[object_uuid]/

Request — Updates an object. Any parameter not specified in the URL above must be submitted as a POST data field. For any POST request the following information can be provided.

Attribute Description
collection_uuid (required) A valid collection UUID resource.
object_uuid (required) A valid object UUID resource.
type (required) A textual version of the type of resource. This could include "catalog", "video", "audio", "file", etc.
title The title of the resource. A title may be blank or can be up to 255 characters in length.
public Should this resource be available to the public? The values can include either "true" or "false". Default value is "false".
description Textual description of the object. This may be blank.
duration The duration of the media object in seconds.

Response — The following response is returned for the POST request as a JSON encoded object.

Attribute Description
uuid The universally unique identifier of the object.

Data API: User

The user API call is used to get information about a particular user. The user API call requires user authentication and is not public. Additionally, based on the user’s permission level, a subset of information regarding the user may be returned.

GET Method:

/api/user/c/[collection_uuid]/o/[user_id]/

Request — For any GET request the following information must be provided.

Attribute Description
collection_uuid (required) A valid collection UUID resource.
user_id (required) A valid user identifier. If this value is 0, it will return the user information for the currently authenticated user.

Response — For any GET request the following information can be returned.

Attribute Description
firstName123 The requested user’s first name.
lastName123 The requested user’s last name.
userId12 The requested user’s identifier.
uniqueId12 The requested user's SSO unique identifier.
{parameters} Additional parameters that are stored about the user.

1 — Provided to the currently authenticated user if they are making a self request
2 — Provided to the an administrator of a collection the userId is a member
3 — Provided to all authenticated and authorized users

POST Method:

/api/user/c/[collection_uuid]/o/[user_id]/

Request — Updates a user. For any POST request the following information can be provided.

Attribute Description
collection_uuid (required) A valid collection UUID resource.
user_id (required) The requested user’s identifier. If this value is 0, the uniqueId POST data field is required.
firstName The requested user’s first name.
lastName The requested user’s last name.
uniqueId (conditional) The requested user’s SSO unique identifier. Required if the user_id field is 0.

Response — For any POST request the following information is provided.

Attribute Description
userId The user identifier.

Data API: Group

The group API call returns information regarding groups. The group API call requires authentication.

GET Method:

/api/group/q/[QUERY]/

Request — This will search all existing groups for the submitted query. For any GET request the following information can be provided.

Attribute Description
query (required) What will be used to search users or groups and return matching ones.
type A valid item type. Can be either 'user' or 'group'. If no type is specified, it will default to 'group.'

Response — For any GET request the following information can be returned. This call will return an array of objects that contain the properties specified below, or the empty set.

Attribute Description
object_id The object identifier associated with the result. This is Warpwire's internal unique reference.
name The name associated with the result.
type The type associated with the result, this will either be 'user' or 'group.'

GET Method:

/api/group/u/[UNIQUE_ID]/

Request — If you know the unique_id of the group, this call will retrive information about the group. For any GET request the following information must be provided.

Attribute Description
unique_id (required) The query will return information about the group that matches the provided unique_id, if it exists.

Response — For any GET request the following information can be returned. This call will return an array of objects that contain the properties specified below, or the empty set.

Attribute Description
objectId The object identifier associated with the result. This is Warpwire's internal unique reference.
uniqueId The unique identifier used by your organization to identify groups.
name The name associated with the unique id.
externalProviderId The external provider id is generally a secondary identifier from an external system (like an LMS).
link Returns the Warpwire URL of the Media Library associated with the group.

GET Method:

/api/group/e/[EXTERNAL_PROVIDER_ID]/

Request — This will search all existing groups for the submitted external provider identifier. For any GET request the following information must be provided.

Attribute Description
external_provider_id (required) The query will return information about the group that matches the provided external_provider_id, if it exists.

Response — For any GET request the following information can be returned. This call will return an array of objects that contain the properties specified below, or the empty set.

Attribute Description
objectId The object identifier associated with the result. This is Warpwire's internal unique reference.
uniqueId The unique identifier used by your organization to identify groups.
name The name associated with the unique id.
externalProviderId The external provider id is generally a secondary identifier from an external system (like an LMS).
link Returns the Warpwire URL of the Media Library associated with the group.

POST Method:

/api/group/u/[CURRENT_UNIQUE_ID]/

Request — This will update an existing group record, based on the group's current_unique_id. For any POST request the following information must be provided.

Attribute Description
current_unique_id (required) The current unique indentifier.
objectId The object identifier associated with the current_unique_id. This is Warpwire's internal unique reference.
uniqueId The unique identifier used by your organization to identify groups.
name The name associated with the unique id.
externalProviderId The external provider id is generally a secondary identifier from an external system (like an LMS).
link The Warpwire URL of the Media Library associated with the group.
hidden This is a boolean value. Options are 'true' and 'false.' If 'true', the group will not appear in any search results.

Response — For POST requests a HTTP 202 status code is returned. There is no other information provided in the response.

PUT Method: (creating a group)

/api/group/

Request — This will create a new group. For any PUT request the following information must be provided. Pass the following attibutes in the body of the request.

Attribute Description
objectId The object identifier associated with the current_unique_id. This is Warpwire's internal unique reference.
uniqueId (required) The unique identifier used by your organization to identify groups.
name (required) The name associated iwth the external provider id.
externalProviderId (required if uniqueId is not provided) The external provider id is generally a secondary identifier from an external system (like an LMS).
link The Warpwire URL of the Media Library associated with the group.
hidden This is a boolean value. Options are 'true' and 'false.' If 'true', the group will not appear in any search results.

Response — For PUT requests a HTTP 202 status code is returned. There is no other information provided in the response.

Data API: Metadata

The metadata API call returns information regarding metadata. The metadata API call requires authentication.

GET Method: List all metadata profiles

/api/metadata/

Request — Will return a paginated list of all metadata. This call requires authentication and requires no specified parameters.

Response — The following response is returned for the GET request as a JSON encoded object. The format will be a paginated list of metadata profiles, each with the following attributes:

Attribute Description
id Unique identifier used by Warpwire to track the profile.
name Internal id of the attribute name (for dublin core it'll be dc:subject or itunes:category) should match chosen ontology.
uri User specified link to metadata specification.
local_key Will indicate type of profile: dublin_core or iTunes Podcast or user defined.
creation Date the metadata profile was created.
attribute_count How many attributes the metadata profile contains.

POST Method: Add new metadata profile

/api/metadata/

Request — This call will create a new metadata profile. Must be authenticated as an institutional admin.

Attribute Description
name (required) The name of the metadata profile you are creating. Must be unique. Send this in the body of the request.
active Boolean true/false. If 'True,' the vocabulary term will display in the user interface.
uri User specified link to metadata specification.

Response — This POST request will return: Status 201 "Success created [profile_id]."
[Profile_id] is a unique interger assigned to the profile and will be used in other calls in place of name.

PUT Method: Update existing metadata profile

/api/metadata/[profile_id]/

Request — This call will update a metadata profile. Must be authenticated as an institutional admin.

Attribute Description
profile_id (required) The id of the metadata profile you are updating. Put this in the URL, as above, this is given when you create the profile.
name (required) The name you want to change the profile to. This is a user-specified parameter.
uri User specified link to metadata specification.
active Boolean true/false. If 'True,' the vocabulary term will display in the user interface.

Response — This PUT request will return: Status 202 "Success modified [profile_id]."
[Profile_id] is a unique interger assigned to the profile and will be used in other calls in place of name.

GET Method: Retrieve specific profile

/api/metadata/[profile_id]

Request — This call will return details of a specified metadata profile. Must be authenticated.

Attribute Description
profile_id (required) The id of the metadata profile you are querying. Put this in the URL, as specified above. This is a positive interger identifying the profile. It is given when you create the profile.
limit Optional. Specify the number of objects per page of the response. Must be a positive interger.
page Specify the page of results to return.

Response — This request will return the following attributes for the specified profile:

Attribute Description
profile_id Unique identifier used by Warpwire to track the profile.
name Name of the metadata profile.
uri User specified link to metadata specification.
local_key Will indicate type of profile: dublin_core or iTunes Podcast or user defined.
creation Date the metadata profile was created.
attribute_count How many attributes the metadata profile contains.

GET Method: Retrieve list of attributes for a specific profile

/api/metadata/[profile_id]/attributes/

Request — This call gets a list of all attributes for a specified metadata profile. Must be authenticated.

Attribute Description
profile_id (required) The id of the metadata profile you are querying. Put this in the URL, as specified above. This is a positive interger identifying the profile. It is given when you create the profile.
limit Optional. Specify the number of objects per page of the response. Must be a positive interger.
page Specify the page of results to return.

Response — This request will return a paginated array of information for the specified profile:

Attribute Description
profile_id Unique identifier used by Warpwire to track the profile
name Name of the metadata profile.
uri User specified link to metadata specification.
local_key Will indicate type of profile: dublin_core or iTunes Podcast or user defined.
attributes An array containing fields for each attribute. The 'attributes' arrary contains the following information for each attribute:
attributes.attribute_id Unique identifier used by Warpwire to track the attribute. This is a positive interger.
attributes.name Internal id of the attribute name (for dublin core it'll be dc:subject or itunes:category) should match chosen ontology.
attributes.display External name of profile attribute shown to the end user.
attributes.description Description of the attribute, if present.
attributes.enforced Boolean true/false. Is this vocabulary enforced? An enforced vocabulary requires that the user input for this field match one of the vocabulary items specified in the 'vocabularies' array.
attributes.required Boolean true/false. Must this field be populated? If true, an error will result if metadata is submitted but this field is blank.
attributes.duplicates Boolean true/false. Can more that one copy of this attribute exist? If true, then there can be multiple entries for the attribute. If false, there can only be one. (e.g. Library of Congress allows multiple subjects for books, iTunes Podcasts allow multiple categories)
attributes.vocabularies An arrary containing vocabulary elements, if they exist.

PUT Method: Update existing metadata profile attribute

/api/metadata/[profile_id]/attributes/[attribute_id]

Request — This call will update a metadata profile. Must be authenticated as an institutional admin.

Attribute Description
profile_id (required) The id of the metadata profile you are updating. Put this in the URL, as above, this is given when you create the profile.
attribute_id (required) The id of the metadata profile attribute you are updating. Put this in the URL, as above, this is given when you create the profile.
name (required) internal id of the attribute name (for dublin core it'll be dc:subject or itunes:category) should match chosen ontology.
display External name of profile attribute shown to the end user.
description Description of the metadata attribute.
active Boolean true/false. If 'True,' the vocabulary term will display in the user interface.
enforced Boolean true/false. Is this vocabulary enforced? An enforced vocabulary requires that the user input for this field match one of the vocabulary items specified in the 'vocabularies' array.
duplicates Boolean true/false. Can more that one copy of this attribute exist? If true, then there can be multiple entries for the attribute. If false, there can only be one. (e.g. Library of Congress allows multiple subjects for books, iTunes Podcasts allow multiple categories)
required Boolean true/false. Must this field be populated? If true, an error will result if metadata is submitted but this field is blank.

Response — This PUT request will return: Status 202 "Success modified [attribute_id]."
[Profile_id] and [attribute_id] are unique to the profile and will be used in other calls in place of name.

POST Method: Add new metadata profile attribute

/api/metadata/[profile_id]/attributes/

Request — This call will create a new metadata profile attribute. Must be authenticated as an institutional admin. All of the attributes listed below must be unique.

Attribute Description
name (required) Internal id of the attribute name (for dublin core it'll be dc:subject or itunes:category) should match chosen ontology.
display (required) External name of profile attribute shown to the end user.
enforced (required) Boolean true/false. Is this vocabulary enforced? An enforced vocabulary requires that the user input for this field match one of the vocabulary items specified in the 'vocabularies' array.
duplicates (required) Boolean true/false. Can more that one copy of this attribute exist? If true, then there can be multiple entries for the attribute. If false, there can only be one. (e.g. Library of Congress allows multiple subjects for books, iTunes Podcasts allow multiple categories)
required (required) Boolean true/false. Must this field be populated? If true, an error will result if metadata is submitted but this field is blank.

Response — This Post request will return: Status 201: Created as well as an array displaying the attribute you just created.

GET Method: Get specific metadata profile attribute

/api/metadata/[profile_id]/attributes/[attribute_id]

Request — This call will retrieve a specific metadata profile attribute. Must be authenticated as an admin.

Attribute Description
profile_id (required) The id of the metadata profile you are updating. Put this in the URL, as above, this is given when you create the profile.
attribute_id (required) The id of the metadata profile attribute you are updating. Put this in the URL, as above, this is given when you create the profile
limit Optional. Specify the number of objects per page of the response. Must be a positive interger.
page Specify the page of results to return.

Response — This request will return a paginated array of information for the specified profile:

Attribute Description
attribute_id Unique identifier used by Warpwire to track the attribute. This is a positive interger.
name Internal id of the attribute name (for dublin core it'll be dc:subject or itunes:category) should match chosen ontology.
display External name of profile attribute shown to the end user.
description Description of the attribute, if present.
enforced Boolean true/false. Is this vocabulary enforced? An enforced vocabulary requires that the user input for this field match one of the vocabulary items specified in the 'vocabularies' array.
duplicates Boolean true/false. Can more that one copy of this attribute exist? If true, then there can be multiple entries for the attribute. If false, there can only be one. (e.g. Library of Congress allows multiple subjects for books, iTunes Podcasts allow multiple categories)
required Boolean true/false. Must this field be populated? If true, an error will result if metadata is submitted but this field is blank.

GET Method: List vocabularies for specified attribute

/api/metadata/[profile_id]/attributes/[attribute_id]/vocabualry/

Request — This call will retrieve any vocabularies associated with a specified profile attribute. Must be authenticated as an admin.

Attribute Description
profile_id (required) The id of the metadata profile you are querying. Put this in the URL, as above, this is given when you create the profile.
attribute_id (required) The id of the metadata profile attribute you are querying. Put this in the URL, as above, this is given when you create the profile.

Response — An array listing the following attributes for each item within the vocabulary

Attribute Description
vocabulary_id Unique identifier used by Warpwire to track the vocabulary element. This will be a positive interger.
data User-readbale vocabulary term.
active Boolean true/false. If 'True,' the vocabulary term will display in the user interface.

GET Method: Get information about specific vocabulary item for specified attribute in specified profile.

/api/metadata/[profile_id]/attributes/[attribute_id]/vocabulary/[vocabulary_id]/

Request — This call will return information on the specified vocabulary term You must be authenticated, though you do not need to be an admin user.

Attribute Description
profile_id (required) The id of the metadata profile you are querying. Put this in the URL, as above. This value is given when you create the profile.
attribute_id (required) The id of the metadata profile attribute you are querying. Put this in the URL, as above. This value is given when you create the profile sttribute.
vocabulary_id (required) The id of the vocabulary item you are querying. Put this in the URL, as above. This value is given when you create the vocabulary item.

Response — An array listing the following attributes for each item within the vocabulary

Attribute Description
vocabulary_id Unique identifier used by Warpwire to track the vocabulary element. This will be a positive interger.
data User-readbale vocabulary term.
active Boolean true/false. If 'True,' the vocabulary term will display in the user interface.

POST Method: Add vocabulary term to profile attribute

/api/metadata/[profile_id]/attributes/[attribute_id]/vocabulary/

Request — This call will add a vocabulary term to the specified attribute within a specified profile. You must be authenticated, though you do not need to be an admin user.

Attribute Description
profile_id (required) The id of the metadata profile you are querying. Put this in the URL, as above, this is given when you create the profile.
attribute_id (required) The id of the metadata profile attribute you are querying. Put this in the URL, as above, this is given when you create the profile.
data (required) The vocabulary term you are adding to the attribute.
active Boolean true/false. If 'True,' the vocabulary term will display in the user interface.

Response — This POST request will return: Status 201: Created, along with an array showing the id, data, and active values you just specified.

PUT Method: Modify existing vocabulary term within a specific profile attribute.

/api/metadata/[profile_id]/attributes/[attribute_id]/vocabulary/[vocabulary_id]

Request — This call will update a vocabulary term to the specified attribute within a specified profile. You must be authenticated as an admin user.

Attribute Description
profile_id (required) The id of the metadata profile you are querying. Put this in the URL, as above, this is given when you create the profile.
attribute_id (required) The id of the metadata profile attribute you are querying. Put this in the URL, as above, this is given when you create the profile.
vocabulary_id The id of the vocabulary term for the metadata profile attribute you specified. Put this in the URL, as above, this is given when you create the vocabulary item originally.
data (required) The vocabulary term you are adding to the attribute.

Response — This PUT request will return: Status 202: Modified, along with an array showing the id, data, and active values you just specified.

Data API: Membership

The membership API call returns information regarding group membership. The membership API call requires authentication.

GET Method:

/api/membership/u/[Warpwire_Unique_ID]/

Request — This will retrieve a list of groups associated with the user whose unique ID is provided.

Attribute Description
Warpwire_Unique_ID (required) If you do not already know the Warpwire Unique ID associated with a given user, you can get the Warpwire Unique ID by querying the user with the /api/group/q/[QUERY]/ call (with type set to 'user'). The objectId in the call response is the value you will use for this membership query.

Response — For any GET request the following information can be returned. This call will return an array of objects that contain the properties specified below, or the empty set.

Attribute Description
id The identifier associated with the user. This is Warpwire's internal unique reference.
unique_id The unique identifier used by your organization to identify the user.
creation The creation date of the user.
first_name The first name of the user.
last_name The last name of the user.
groups An array containing all the groups associated with the Warpwire Unique ID.

GET Method:

/api/membership/g/[Warpwire_Group_ID]/

Request — This will retrieve a list of users associated with the group whose unique ID is provided.

Attribute Description
Warpwire_Group_ID (required) If you do not already know the Warpwire Group ID associated with a given group, you can get the Warpwire Group ID by querying the group with the /api/group/q/[QUERY]/ call (with type set to 'group'). The objectId in the call response is the value you will use for this membership query.

Response — For any GET request the following information can be returned. This call will return an array of objects that contain the properties specified below, or the empty set.

Attribute Description
id The identifier associated with the group. This is Warpwire's internal unique reference.
unique_id The unique identifier used by your organization to identify the group.
creation The creation date of the group.
name The name of the group.
users An array containing all the users associated with the Warpwire Group ID.

POST Method:

/api/membership/

Request — This will add a user to a group, based on provided IDs.

Attribute Description
user_id (required) The id associated with the user who is being added to the group.
group_id (required) The id associated with the group who is having a user.

Response — For POST requests a HTTP 201 status code is returned. There is no other information provided in the response.

DELETE Method:

/api/membership/

Request — This will delete a user from a group, based on provided IDs.

Attribute Description
user_id (required) The id associated with the user who is being removed from the group.
group_id (required) The id associated with the group who is having a user removed from it.

Response — For DELETE requests a HTTP 204 status code is returned. There is no other information provided in the response.

Data API: Permission

The permission API call returns information regarding access control levels. The permission API call requires authentication.

GET Method:

/api/permission/c/[collection_uuid]/o/[user_id]/

Request — For any GET request the following information must be provided.

Attribute Description
collection_uuid (required) A valid collection UUID resource.
user_id (required) A valid user identifier. If this value is 0, it will return user information for the entire collection.

Response — For any GET request the following information can be returned. This call will return an array of objects that contain the properties specified below, or the empty set.

Attribute Description
firstName The requested user’s first name.
lastName The requested user’s last name.
userId The requested user’s identifier.
uniqueId The requested user's SSO unique identifier.

PUT Method:

/api/permission/c/[collection_uuid]/o/[user_id]/

Request — Adds a user to a collection. Any parameter not specified in the URL above must be submitted as a PUT data field. For any PUT request the following information can be provided.

Attribute Description
collection_uuid (required) A valid collection UUID resource.
user_id (conditional) The requested user’s identifier. If this value is 0, the uniqueId PUT data field is required.
uniqueId (conditional) The requested user's SSO unique identifier. Required if the user_id is 0.
level The permission level to assign to the user. Possible values are "none", "view", or "admin". Default value is "view".

Response — For PUT requests a HTTP 201 status code is returned. There is no other information provided in the response.

POST Method:

Identical to the PUT Method. See above.

DELETE Method:

/api/permission/c/[collection_uuid]/o/[user_id]/

Request — Removes a user from a collection. For any DELETE request the following information must be provided.

Attribute Description
collection_uuid (required) A valid collection UUID resource.
user_id (required) A valid user identifier.

Response — For DELETE requests a HTTP 200 status code is returned. There is no other information provided in the response.

Data API: Info

The info API call returns information for objects. The info API call requires authentication.

GET Method:

/api/info/c/[collection_uuid]/o/[object_id]/

Request — For any GET request the following information must be provided.

Attribute Description
collection_uuid (required) A valid collection UUID resource.
object_id (required) A valid object UUID resource.

Response — For any GET request the following information can be returned.

Attribute Description
type A textual version of the type of resource. This value will be "info".
owner An array containing information about the owner of the object.
owner.userId The object owner’s user identifier.
owner.firstName The object owner’s first name.
owner.lastName The object owner’s last name.
title The title of the resource. A title may be blank or can be up to 255 characters in length.
description The description of the object. The description may be blank.
created An Epoch timestamp of the date the object was created.
modified An Epoch timestamp of the date the object was modified.
properties An array of properties that accompany the object. This could be an empty set.
uuid The universally unique identifier of the object.
fileType A textual version of the type of file. This could include "catalog", "video", "audio", "file", etc.
duration The duration of the media object in seconds.

POST Method:

/api/info/c/[collection_uuid]/o/[user_id]/

Request — For any GET request the following information must be provided.

Attribute Description
collection_uuid (required) A valid collection UUID resource.
object_id (required) A valid object UUID resource.
title The title of the object. A title may be blank or can be up to 255 characters in length.
description The description of the object. The description may be blank.

Response — For POST requests a HTTP 202 status code is returned. There is no other information provided in the response.

Data API: Embed

The embed API call returns information regarding embedding an object. The embed API call requires authentication.

GET Method:

/api/embed/c/[collection_uuid]/o/[object_id]/

Request — For any GET request the following information must be provided.

Attribute Description
collection_uuid (required) A valid collection UUID resource.
object_id (required) A valid object UUID resource.

Response — For any GET request the following information can be returned.

Attribute Description
type A textual version of the type of resource. This value will be "embed".
properties An array of properties that accompany the object. This could be an empty set.
properties.link URL of object.
properties.iframe Iframe embed code for the object.
properties.script JavaScript embed code for the object.

Data API: Video

The video API call returns information about a video object. The video API call requires authentication.

GET Method:

/api/video/c/[collection_uuid]/o/[object_id]/

Request — For any GET request the following information must be provided.

Attribute Description
collection_uuid (required) A valid collection UUID resource.
object_id (required) A valid object UUID resource.

Response — For any GET request the following information can be returned.

Attribute Description
type A textual version of the type of resource. This value will be "video".
duration The duration in seconds of the asset (if applicable) represented as a positive interger.
files An array with information about each version of the video file. The files array contains the following five items:
files.format The format of the video file. This can include "hls", "smil", or "mp4".
files.url The URL of the video file.
files.label The quality label for the video file, as displayed in the UI (e.g. 360p.)
files.bitrate The video file's bitrate.
files.properties An array of properties for the video file. Please note that the properties array may be an empty set. The array contains the following two items:
files.properties.thumbnail The thumbnail image for the Web Video Text Tracks (VTT) file for the video.
files.properties.captions An array with links to all attaches caption files for the video, as key value pairs of the caption language and the direct link to the caption file.
images An array of images that accompany the object. Please note that the images array may be an empty set. The images array may contain the following items:
images.thumbnail A 128x128 pixel image of the resource (if available).
images.square A 512x512 pixel image of the resource (if available).
images.large A 1280x760 pixel image of the resource (if available).
properties An array of files that accompany the object. Please note that the files array may be an empty set.
uuid The universally unique identifier of the object.

Data API: Authenticate

The authenticate API call returns information regarding authentication of users. The authenticate API call does not require authentication.

GET Method:

/api/authenticate/

Request — For any GET request no further information needs to be provided.

Response — For any GET request the following information is returned.

Attribute Description
type A textual version of the type of resource. This value will be "authenticate".
authenticated Is the current user authenticated? The values can include either "true" or "false". If you do not provide an authenticated user, the result will always be "false".

Data API: Catalog

The catalog API call returns information regarding all objects that exists within a collection. The catalog API call requires authentication.

GET Method:

/api/catalog/c/[collection_uuid]/o/[object_uuid]/

Request — For any GET request the following information must be provided.

Attribute Description
collection_uuid (required) A valid collection UUID resource.
object_uuid (required) A valid object UUID resource.
ts The Epoch timestamp. If provided, only objects that have been updated since the timestamp will be returned. Cannot be 0.
completeRecords The number of complete records to return. If not provided, all returned objects will be complete describe objects.

Response — For any GET request the following information is returned. This call will return an array of objects that contain the properties specified below, or the empty set.

Attribute Description
ts The Epoch timestamp at which the request occurred.
list An array of objects which exhibit the properties below, or the empty set.
type A textual version of the type of resource. This could include "catalog", "video", "audio", "file", etc.
title The title of the resource. A title may be blank or can be up to 255 characters in length.
images An array of images that accompany the object. Please note that the images array may be an empty set.
images.thumbnail A 128x128 pixel image of the resource (if available).
images.square A 512x512 pixel image of the resource (if available).
images.large A 1280x760 pixel image of the resource (if available).
description Textual description of the object. This may be blank.
properties An array of properties that accompany the object. This could be an empty set.
uuid The universally unique identifier of the object.
userId Identifier of user who created the resource. This information is not informative without performing an additional user API call.
authenticated Indicates if the current user is authenticated. Value is either "true" or "false".
created An Epoch timestamp of the date the object was created.
modified An Epoch timestamp of the date the object was modified.

PUT Method:

/api/catalog/c/[collection_uuid]/o/[object_uuid]/

Request — Adds an object to a collection. Any parameter not specified in the URL above must be submitted as a PUT data field. For any PUT request the following information can be provided.

Attribute Description
collection_uuid (required) A valid collection UUID resource.
object_uuid (required) A valid collection or object UUID resource.

Response — For PUT requests a HTTP 201 status code is returned. There is no other information provided in the response.

POST Method:

Identical to the PUT Method. See above.

DELETE Method:

/api/catalog/c/[collection_uuid]/o/[object_uuid]/

Request — Removes an object from a collection. For any DELETE request the following information must be provided.

Attribute Description
collection_uuid (required) A valid collection UUID resource.
object_uuid (required) A valid collection or object UUID resource.

Response — For DELETE requests a HTTP 200 status code is returned. There is no other information provided in the response.

Data API: Contribute

The contribute API call returns information regarding group membership of an object. The contribute API call requires authentication.

GET Method:

/api/contribute/o/[object_id]/

Request — For any GET request the following information must be provided.

Attribute Description
object_id (required) A valid object UUID resource.

Response — For any GET request an array of the following information can be returned.

Attribute Description
uuid The universally unique identifier of the media library.
title The title of the resource. A title may be blank or can be up to 255 characters in length.
member Whether or not the object is a member of the corresponding media library.

Data API: OAuth

The oauth API allows for providers of the external services to interact with the Warpwire OAuth service to invoke an OAuth2 request, whitelist domains, and update configuration information. A more detailed view of the OAuth2 authentication workflow. The following OAuth API calls require using HTTP Basic Authorization using the Oauth2 client key as the username and the client secret as the password.

GET Method:

/api/oauth/whitelist/

Authorization — HTTP basic authorization.

Response — For any GET request the following information can be returned in a JSON formatted object.

list An array of whitelisted domains that are approved for use with the Oauth2 provider.
list[x].id A unique identifier for the whitelist parameters. This id must be used for subsequent oauth API calls.
list[x].url The target URL for the whitelisted domain. If there are no restrictions to the domains that the provider may target, this value will read "Unrestricted."
list[x].created The date and time the whitelist URL was created in ISO-8601 format.
count The number of whitelisted domains available to the provider

POST Method:

/api/oauth/whitelist/

Authorization — HTTP basic authorization.

Request — Creates a new whitelist domain for the Oauth2 provider. The provided whitelist domain must be a valid URI and cannot be a duplicate whitelist domain for the same provider.

Attribute Description
url Whitelist domain for OAuth2 requests to be returned to the provider for further processing.

Response — A successful POST request will return a HTTP 201 response code along with a JSON object confirming the successful creation of the object.

Attribute Description
status The status of the POST request. In most cases this value will return "success."

PUT Method:

/api/oauth/whitelist/

Authorization — HTTP basic authorization.

Request — Updates an existing whitelist domain for the Oauth2 provider. The unique identifier for the existing whitelist domain is required, see GET request above. Additionally, the provided whitelist domain must be a valid URI and cannot be a duplicate whitelist domain for the same provider.

Attribute Description
id The unique identifier for the whitelist domain for the provider. This information may be retrieved by using the whitelist GET API call.
url Whitelist domain for OAuth2 requests to be returned to the provider for further processing.

Response — A successful PUT request will return a HTTP 202 response code along with a JSON object confirming the successful creation of the object.

Attribute Description
status The status of the PUT request. In most cases this value will return "success."

DELETE Method:

/api/oauth/whitelist/

Authorization — HTTP basic authorization.

Request — Removes an existing whitelist domain for the Oauth2 provider. The unique identifier for the existing whitelist domain is required, see GET request above. You may not remove the final domain for a provider, this will result in an error response.

Attribute Description
id The unique identifier for the whitelist domain for the provider. This information may be retrieved by using the whitelist GET API call.

Response — A successful DELETE request will return a HTTP 200 response code along with a JSON object confirming the successful creation of the object.

Attribute Description
status The status of the DELETE request. In most cases this value will return "success."

Data API: OEmbed

The oembed API provides an easy way for you to place certain kinds of media content, including Warpwire videos, on external websites. By accessing a special URL that corresponds to the content that you want to embed, you get detailed information about this content, including an embeddable iframe element.

Please note: The OEmbed standard is separate from the Warpwire API, so you don't need API authentication to use this functionality.

You will need the URL of a video on Warpwire. If you are unsure about where to find the share URL, please visit our Support Guide.

GET Request:

Get an oEmbed response for a video — To get an oEmbed response for a video on Warpwire, send a GET request to the following URL:

https://example.warpwire.com/api/oauth/?url=LINK_URL

NOTE: Be sure to URL encode the LINK_URL value:

https://example.warpwire.com/api/oembed/?url=https%3A%2F%2Fexample.warpwire.com%2Fw%2FAAAAAA%2F&width=480&height=360&format=json

Table 1. URL schemas

The video is... URL scheme
A regular Warpwire video https://example.warpwire.com/w/{video_id}/

Make sure that all parameters are URL encoded. We provide a default width and height settings for all assets, but if you'd like to provide you own default sizes you can use the URL examples below:

GET https://example.warpwire.com/api/oembed/?url=https%3A%2F%2Fexample.warpwire.com%2Fw%2FAAAAAA%2F&width=480&height=360


GET https://example.warpwire.com/api/oembed/?url={video_url}&format=json

Table 2. oEmbed arguments

Argument Description
autoplay Whether to start playback of the video automatically. This feature might not work on all devices. Default value is "false".
cc_enabled You can turn caption on by default. When activated the available caption file will be played. In the case that there are multiple caption available, the player will default to “English”. Default value is "false".
controls Whether to display (true) or hide (false) all interactive elements in the player interface. To start video playback when controls are hidden, set autoplay to true or use our Player API. Default value is "true".
height The height of the video in pixels.
muted Whether to mute playback by default. The user can increase the volume manually. Default value is "false".
share Controls showing the share link on the video so that users can share the link with others. Default value is "true".
title Whether to display the video's title. Default value is "true".
thumbnail_height The height of the thumbnail images for the asset.
thumbnail_width The width of the thumbnail image for the asset.
transcript Show an interactive transcript that plays along with the video if a caption is present.
width The width of the video in pixels.
url The URL of the video on Warpwire. This is a required value.

Under normal circumstances, the response contains various pieces of metadata in JSON format, including the video's embeddable iframe element in the html field.

{ "version": "1.0", "provider_url": "https://example.warpwire.com",
"provider_name": "Warpwire",
"is_public": true,
"duration": 50.25,
"has_caption": true,
"links": {
"caption": [
{
"label": "English", "url": "https://example.warpwire.com/api/caption/AwAAAA/1/vtt/"
}
]
},
"views": 1,
"upload_date": "2020-01-01T00:00:00+00:00",
"description": "An example description",
"author_name": "Jane Smith",
"html": "< iframe width=\"640\" height=\"360\" src=\"https://example.warpwire.com/w/AwAAAA/?audio_only=1&autoplay=1&controls=1\" frameborder=\"0\" allow=\"autoplay; encrypted-media; camera; microphone; picture-in-picture\" allowfullscreen>iframe">,
"height": 360,
"width": 640,
"thumbnail_height": 360,
"thumbnail_width": 640,
"url": "https://example.warpwire.com/w/AwAAAA/?audio_only=1&autoplay=1&controls=1",
"type": "video",
"title": "An example file",
"thumbnail_url": "https://example.warpwire.com/image/large/"
}

NOTE: If you want a response in XML instead of in JSON, substitute format=xml for format=json in the URL.

See Table 3 for descriptions of these fields.

Table 3. oEmbed response fields

Field Description
author_name The owner of the video.
description The description of the video.
duration The duration of the video in seconds.
has_captions (Optional) A Boolean to indicate if the video contains closed captions.
height The height of the video in pixels.
is_public The video is available to the public to watch.
links.captions (Optional) Contains one or more entries including the label and URL for the corresponding caption file for the video. It follows the format: entry.label and entry.url.
html The iframe element for embedding the video.
provider_name The name of the oEmbed provider, which in this case is Warpwire.
provider_url The URL of the oEmbed provider, which in this case is https://warpwire.com/.
thumbnail_height The URL of the video's thumbnail image.
thumbnail_url The URL of the video's thumbnail image.
thumbnail_width The width of the video's thumbnail image.
title The title of the video.
type The type of the oEmbed, which in this case is video.
upload_date The date and time when the video was uploaded.
url The URL of the video.
views (Optional) Number of views of the video.
version The version of the oEmbed spec.
width The width of the video in pixels.

Note: If your video is not public you may receive a slightly different response.

Embed the video

To embed the video, take the unescaped value of the html field, and include it in your HTML page.

<html>
<head>
<title>{page_title}</title>
</head>
<body>
<iframe src=“https://example.warpwire.com/w/{video_id}/” width="{video_width}" height="{video_height}" frameborder="0" title="{video_title}" webkitallowfullscreen mozallowfullscreen allowfullscreen>iframe>
</body>
</html>

Discovering the oEmbed URL

Under normal circumstances, the head section of a video's page on Warpwire includes two link elements: one with type application/json+oembed, and the other with type text/xml+oembed.

<link rel="alternate" type="application/json+oembed" href=“https://example.warpwire.com/api/oembed/?url=https%3A%2F%2Fexample.warpwire.com%2Fw%2FAwAAAA%2F&format=json” title="Warpwire Video">


<link rel="alternate" href=“https://example.warpwire.com/api/oembed/?url=https%3A%2F%2Fexample.warpwire.com%2Fw%2F{video_id}%2F&format=json” type="application/json+oembed" title="{video_title}">


<link rel="alternate" href=“https://example.warpwire.com/api/oembed/?url=https%3A%2F%2Fexample.warpwire.com%2Fw%2F{video_id}%2F&format=xml” type="text/xml+oembed" title="{video_title}">

In these links, the href attribute contains the URL for obtaining the oEmbed response in either JSON or XML format, depending on which one you use. These elements enable you to copy your video's URL and use it anywhere that oEmbed is supported.

Handling errors

Whenever oEmbed isn't working properly and you're sure that the video URL is correct, check the HTTP status code that you get back, and refer to Table 4.

HTTP status code Probable cause
403 Embed permissions are disabled for this video, so you can't embed it.
404 You aren't able to access the video because of privacy or permissions issues, or because the video is still transcoding.

Data API: HTTP Response Codes

All calls to the REST API will always return a standard HTTP 1.1 status code as a response. The status codes that the Warpwire API will return are listed below.

Status Code Description
200 OK. The request is successful.
201 Created. The resource has been successfully created.
202 Accepted. The resource has been successfully modified.
302 Temporarily redirected. The resource has moved and you will need to follow the URL for the updated resource.
400 Bad Request. The API call could not be processed because one or more input parameters are not valid. Please confirm all parameters are correct.
401 Unauthorized. The user needs to authenticate to view a resource. Please direct the user to the authentication endpoint.
403 Forbidden. The user does not have access to the requested resource. They must be added to the appropriate collection or group.
404 Not Found. The resource could not be located or the API method could not be found.
409 Conflict. There is a conflict that prevents an object from being updated or created. The error message should contain additional information.
500 Internal Server Error. These errors are not generated by the API directly and indicate an issue with the server. Please contact Warpwire for an appropriate resolution.
501 Not Implemented. You are requesting an API call that has not yet been implemented. Please use a different method.
503 Service Unavailable. The Warpwire servers are currently unavailable to fulfill your request. Please wait a few moments and try your request again.

View Developer APIs page