Asset API

The Epicenter Asset API allows you to store assets — resources or files of any kind — used by a project with a scope that is specific to project, group, or end user.

Assets are used with team projects. One common use case is having end users in a group or in a multiplayer world upload data — videos created during game play, profile pictures for customizing their experience, etc. — as part of playing through the project.

Resources created using the Asset API are scoped:

Project assets are writable only by team members, that is, Epicenter authors.
Group assets are writable by facilitators of that group, as well as team members (Epicenter authors).
User assets are writable by the specific end user, and by the facilitator of the group.
All assets are readable by anyone with the exact URI.

The maximum file size is 100M.

The Asset API supports the following methods:

POST: Creating an asset
- Using encoded data
- Using an HTML form
GET: Viewing an asset
- Viewing a specific asset
- Listing all assets in a specific scope
PUT: Replacing an asset
- Using encoded data
- Using an HTML form
DELETE: Removing an asset

POST: Creating an Asset

You can create an asset specific to a project, group, or end user.

Additionally, you can create an asset in one of two ways:

Use a Content-Type of application/json and pass the base64-encoded data in the body of your request.
Use a Content-Type of multipart/form-data and reference the file. Because this type of request still requires an Authorization header, this is typically done using JavaScript to intercept an HTML form submission and add the appropriate header.

Creating an Asset Using Encoded Data

Method: POST

URI:

For a project asset: /v2/asset/project/{account id}/{project id}/{file name}
For a group asset: /v2/asset/group/{account id}/{project id}/{group name}/{file name}
For a user asset: /v2/asset/user/{account id}/{project id}/{group name}/{user id}/{file name}

Headers:

Authorization: Bearer{token}
Content-Type: application/json

Request Body: A JSON object with the file data and metadata, including:

encoding: Either HEX or BASE_64. Required.
data: The encoded data for the file. Required.
contentType: A string with the content type (mime type) of the file. Optional but recommended.

Return Status:

204: Successful creation of asset.
413: Request entity too large: returned if the asset is greater than 100MB.

Return Body: None.

Example:

// creating a project asset

curl -X POST \
    'https://api.forio.com/v2/asset/project/acme-simulations/supply-chain-game/test.txt' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \
    --header 'Content-Type: application/json' \
    --data '{ "encoding": "BASE_64", "data": "VGhpcyBpcyBhIHRlc3QgZmlsZS4=" }'

Example Response:

None.

Notes:

In the URI, the account id is the Team ID (for team projects) or User ID (for personal projects).
In the URI, the project id is the Project ID
In the URI, the group name is the name of the group, listed under [Project Name] > Groups.
In the URI, the user id is the unique identifier of the user record. (If you only have the user name or email address, you can query the User API to find the id.)
In the URI, the file name is the name of the file or resource you are creating. It should include any extension, and can include / if you want to create a nested structure of assets.
In the header, the token can be a user access token or project access token:
- For a project asset, use the project access token.
- For a group asset, use the project access token, the user access token of a member of the group, or the user access token of a team member.
- For a user asset, use the project access token, the user access token of the end user, or the user access token of a team member.
In the example, the value of the data in the request body is the the string "This is a test file.", having been encoded into Base 64.
Project assets are writable only by team members, that is, Epicenter authors.
Group assets are writable by facilitators of that group, as well as team members (Epicenter authors).
User assets are writable by the specific end user referenced in the URI, and by the facilitator of the group.

Creating an Asset Using Multipart/Form-Data

Method: POST

URI:

For a project asset: /v2/asset/project/{account id}/{project id}
For a group asset: /v2/asset/group/{account id}/{project id}/{group name}
For a user asset: /v2/asset/user/{account id}/{project id}/{group name}/{user id}
For all assets: the {file name} can optionally be added to the end of the URI. If not provided, the file name is taken from the Content-Disposition header.

Headers:

Authorization: Bearer{token}
Content-Type: multipart/form-data

Request Body:

Content-Disposition: form-data; filename="{file name}"
Content-Type: {mime type}
The body of the file (e.g. from HTML form)

Return Status:

204: Successful creation of asset.
413: Request entity too large: returned if the asset is greater than 100MB.

Return Body: None.

Example:

To send content from multipart/form-data, create an HTML form with an <input type="file"> element, then intercept the submission and construct a request. This way, you can add in the Authorization header. (In this example, the Content-Type: multipart/form-data header is automatically added to the request by jQuery.)

<!-- HTML -->
<form action="" id="upload-file">
    <input id="file" type="file">
    <button type="submit">Send</button>
</form>

<!-- JavaScript -->
$('#upload-file').on('submit', function (e) {
    e.preventDefault();
    var data = new FormData();
    var inputControl = $('#file')[0];
    data.append('file', inputControl.files[0]);

    $.ajax({
        type: 'POST',
        url: 'https://api.forio.com/v2/asset/project/acme-simulations/supply-chain-game',
        processData: false,
        contentType: false,
        data: data,
        headers: { 'Authorization': 'Bearer ' + token }
    });
});

Example Response: None.

Notes:

In the URI, the account id is the Team ID (for team projects) or User ID (for personal projects).
In the URI, the project id is the Project ID
In the URI, the group name is the name of the group, listed under [Project Name] > Groups.
In the URI, the user id is the unique identifier of the user record. (If you only have the user name or email address, you can query the User API to find the id.)
In the URI, the file name can optionally be added to the end of the URI. If not provided, the file name is taken from the Content-Disposition header.
In the header, the token can be a user access token or project access token:
- For a project asset, use the project access token.
- For a group asset, use the project access token, the user access token of a member of the group, or the user access token of a team member.
- For a user asset, use the project access token, the user access token of the end user, or the user access token of a team member.
Project assets are writable only by team members, that is, Epicenter authors.
Group assets are writable by facilitators of that group, as well as team members (Epicenter authors).
User assets are writable by the specific end user referenced in the URI, and by the facilitator of the group.

GET: Retrieving an Asset

Retrieving a Specific Asset

Method: GET

URI:

For a project asset: /v2/asset/project/{account id}/{project id}/{file name}
For a group asset: /v2/asset/group/{account id}/{project id}/{group name}/{file name}
For an end user asset: /v2/asset/user/{account id}/{project id}/{group name}/{user id}/{file name}

Headers: None.

Request Body: None.

Return Status:

302: Redirect to the server where assets are stored. Most clients (e.g. web browsers, Postman) immediately follow the redirect and return status 200: successful retrieval of asset.

Return Body: The content of the file.

Example:

curl -G \
    'https://api.forio.com/v2/asset/project/acme-simulations/supply-chain-game/test.txt'

Example Response:

This is a test file.

Notes:

In the URI, the account id is the Team ID (for team projects) or User ID (for personal projects).
In the URI, the project id is the Project ID
In the URI, the group name is the name of the group, listed under [Project Name] > Groups.
In the URI, the user id is the unique identifier of the user record. (If you only have the user name or email address, you can query the User API to find the id.)
In the URI, the file name is the name of the file or resource you are creating. It should include any extension, and can include / if you want to create a nested structure of assets.
IMPORTANT: Any asset is readable by anyone with the exact URI. Do NOT include an Authorization header in the GET request for a single asset: it is not needed, and the request will error if it is included.

Retrieving a List of Assets

Method: GET

URI:

For a project asset: /v2/asset/project/{account id}/{project id}
For a group asset: /v2/asset/group/{account id}/{project id}/{group name}
For an end user asset: /v2/asset/user/{account id}/{project id}/{group name}/{user id}

Headers:

Authorization: Bearer{token}
Optional: Range: records {i}-{j}

Request Body: None.

Return Status:

200: Successfully retrieved listing of assets in this scope.

Return Body: Array with names of assets in this scope.

Example:

curl -G \
    'https://api.forio.com/v2/asset/project/acme-simulations/supply-chain-game' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \

Example Response:

[ 
  "fileA.txt", 
  "fileB.txt", 
  "fileC.txt"
]

Notes:

In the URI, the account id is the Team ID (for team projects) or User ID (for personal projects).
In the URI, the project id is the Project ID
In the URI, the group name is the name of the group, listed under [Project Name] > Groups.
In the URI, the user id is the unique identifier of the user record. (If you only have the user name or email address, you can query the User API to find the id.)
IMPORTANT: In the URI, do NOT include a trailing /. Doing so means the API continues searching for the next qualifier (e.g. a group, if there is a trailing / after the project id) and cannot find it, so returns a 404 instead of a listing of files in this scope.
IMPORTANT: Note that the Authorization header IS required to list the assets in a particular scope. (Any asset is readable by anyone with the exact URI, see above.)
In the header, the token can be a user access token or project access token:
- For a project asset, use the project access token.
- For a group asset, use the project access token, the user access token of a member of the group, or the user access token of a team member.
- For a user asset, use the project access token, the user access token of the end user, or the user access token of a team member.

PUT: Replacing an Asset

You can replace an existing asset using the PUT method.

Updating an Asset Using Encoded Data

Method: PUT

URI:

For a project asset: /v2/asset/project/{account id}/{project id}/{file name}
For a group asset: /v2/asset/group/{account id}/{project id}/{group name}/{file name}
For a user asset: /v2/asset/user/{account id}/{project id}/{group name}/{user id}/{file name}

Headers:

Authorization: Bearer{token}
Content-Type: application/json

Request Body: A JSON object with the new file data and metadata, including:

encoding: Either HEX or BASE_64. Required.
data: The encoded data for the file. Required.
contentType: A string with the content type (mime type) of the file. Optional but recommended.

Return Status:

204: Successful upate of asset.

Return Body: None.

Example:

// updating a project asset

curl -X PUT \
    'https://api.forio.com/v2/asset/project/acme-simulations/supply-chain-game/test.txt' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \
    --header 'Content-Type: application/json' \
    --data '{ "encoding": "BASE_64", "data": "dGhpcyBpcyB0aGUgdXBkYXRlZCB0ZXN0IGZpbGUu" }'

Example Response:

None.

Notes:

In the URI, the account id is the Team ID (for team projects) or User ID (for personal projects).
In the URI, the project id is the Project ID
In the URI, the group name is the name of the group, listed under [Project Name] > Groups.
In the URI, the user id is the unique identifier of the user record. (If you only have the user name or email address, you can query the User API to find the id.)
In the URI, the file name is the name of the file or resource you are creating. It should include any extension, and can include / if you want to create a nested structure of assets.
In the header, the token can be a user access token or project access token:
- For a project asset, use the project access token.
- For a group asset, use the project access token, the user access token of a member of the group, or the user access token of a team member.
- For a user asset, use the project access token, the user access token of the end user, or the user access token of a team member.
Project assets are writable only by team members, that is, Epicenter authors.
Group assets are writable by facilitators of that group, as well as team members (Epicenter authors).
User assets are writable by the specific end user referenced in the URI, and by the facilitator of the group.

Updating an Asset Using Multipart/Form-Data

Method: PUT

URI:

For a project asset: /v2/asset/project/{account id}/{project id}
For a group asset: /v2/asset/group/{account id}/{project id}/{group name}
For a user asset: /v2/asset/user/{account id}/{project id}/{group name}/{user id}

Headers:

Authorization: Bearer{token}
Content-Type: multipart/form-data

Request Body:

Content-Disposition: form-data; filename="{file name}"
Content-Type: {mime type}
The body of the file (e.g. from HTML form)

Return Status:

204: Successful upate of asset.

Return Body: None.

Example:

<!-- HTML -->
<form action="" id="replace-file">
    <input id="file" type="file">
    <button type="submit">Send</button>
</form>

<!-- JavaScript -->
$('#replace-file').on('submit', function (e) {
    e.preventDefault();
    var data = new FormData();
    var inputControl = $('#file')[0];
    data.append('file', inputControl.files[0]);

    $.ajax({
        type: 'PUT',
        url: 'https://api.forio.com/v2/asset/project/acme-simulations/supply-chain-game',
        processData: false,
        contentType: false,
        data: data,
        headers: { 'Authorization': 'Bearer ' + token }
    });
});

Example Response: None.

Notes:

In the URI, the account id is the Team ID (for team projects) or User ID (for personal projects).
In the URI, the project id is the Project ID
In the URI, the group name is the name of the group, listed under [Project Name] > Groups.
In the URI, the user id is the unique identifier of the user record. (If you only have the user name or email address, you can query the User API to find the id.)
In the header, the token can be a user access token or project access token:
- For a project asset, use the project access token.
- For a group asset, use the project access token, the user access token of a member of the group, or the user access token of a team member.
- For a user asset, use the project access token, the user access token of the end user, or the user access token of a team member.
Project assets are writable only by team members, that is, Epicenter authors.
Group assets are writable by facilitators of that group, as well as team members (Epicenter authors).
User assets are writable by the specific end user referenced in the URI, and by the facilitator of the group.

DELETE: Removing an Asset

You can remove an asset using the DELETE method.

Method: DELETE

URI:

For a project asset: /v2/asset/project/{account id}/{project id}/{file name}
For a group asset: /v2/asset/group/{account id}/{project id}/{group name}/{file name}
For a user asset: /v2/asset/user/{account id}/{project id}/{group name}/{user id}/{file name}

Note that you can also use a wildcard "*" instead of a filename to delete all files for that scope, e.g.

For a user asset: /v2/asset/user/{account id}/{project id}/{group name}/{user id}/*

Headers:

Authorization: Bearer{token}

Request Body: None

Return Status:

204: Successfully deleted file.

Return Body: None

Example:

curl -X DELETE \
    https://api.forio.com/v2/asset/project/acme-simulations/supply-chain-game/test.txt' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \

Example Response:

None.

Notes:

In the URI, the account id is the Team ID (for team projects) or User ID (for personal projects).
In the URI, the project id is the Project ID
In the URI, the group name is the name of the group, listed under [Project Name] > Groups.
In the URI, the user id is the unique identifier of the user record. (If you only have the user name or email address, you can query the User API to find the id.)
In the URI, the file name is the name of the file or resource you are creating. It should include any extension, and can include / if you want to create a nested structure of assets.
In the header, the token can be a user access token or project access token:
- For a project asset, use the project access token.
- For a group asset, use the project access token, the user access token of a member of the group, or the user access token of a team member.
- For a user asset, use the project access token, the user access token of the end user, or the user access token of a team member.
Project assets can be deleted only by team members, that is, Epicenter authors.
Group assets can be deleted by anyone with access to the project that is part of this group. This includes all team members (Epicenter authors) and any end users who are members of the group — both facilitators and standard end users.
User assets can be deleted by the specific user referenced in the URI, and by the facilitator of the group.