forio Toggle navigation

Project API

The Project API provides create, read, update, and delete (CRUD) capabilities for projects on the Epicenter platform.

Every Epicenter author can work with personal projects (either through the Epicenter interface, or through the Project API using their own user access token).

Epicenter authors who belong to a team collaborate to develop projects. Any team member can work with team projects (either through the Epicenter interface, or through the Project API using their project access token).

The Project API supports the following HTTP methods:

POST: Creating a Project

Use the Project API POST method to create a new project.

Method: POST

URI: /v2/project

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

Body: JSON object with project record details.

  • Required information:

    • account: The account id under which this project is being created. This is the Team ID (for team projects) or User ID (for personal projects).
    • id: The short name and unique identifier for this project. (In the Epicenter user interface, this is called Project ID.) Can contain lowercase letters, numbers, hyphens, and underscores only.
    • name: The longer, descriptive name of this project. (In the Epicenter user interface, this is called Project Name.)

  • Optional information:

    • url: A copy of the id for this project. Used as a segment of url for accessing the project, for example, forio.com/app/{account id}/{project url}/.
      • This is automatically populated with the same content as the id and does not need to be passed in.
    • access: Determines the project access.
      • Valid values are public, private, and authenticated. (However, authenticated is only valid if the account associated with this project has a type of team.)
      • Defaults to private.
    • modelType: Records the kind of model associated with this project.
      • Valid values are julia, vensim, python, r, simlang, none.
      • Defaults to none.
    • modelSessionTimeout: The number of seconds until the underlying session is closed. (In the Epicenter user interface, this is set in the project settings.)
      • Defaults to 1800 (30 minutes).
    • multiplayer: Boolean, marks whether this project is for a multiplayer world.
    • pushChannelEnabled: Whether the Channel API is available for this project to use.
      • Defaults to false. Can only be true for team projects.
    • pushChannelAuthorizationRequired: Whether the Channel API requires credentials.
      • Defaults to false. If true, client subscriptions to the push channel are rejected if an appropriate userName and authorization are not provided.
    • multiplayerSelfAssign: Whether both end users and facilitators, or only facilitators, can create worlds and assign end users to worlds for groups in this project.
      • Defaults to false, meaning only facilitators can create worlds and assign end users to them. If true, end users also have this permission.

Return Status:

  • 201: Successfully created project
  • 403: Project cannot be created because the number of projects already created this account is greater than the number of projects allowed for this account's subscription plan. (Under currently defined subscription plans, there is only a limit the number of authenticated projects.)

Return Body: A JSON object with the project record just created.

Example:

curl -X POST 'https://api.forio.com/v2/project' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \
    --data '{"account": "acme-simulations", "id": "supply-chain-game", "name": "The Supply Chain Game"}'

Example Response:

{
  "created": "2017-01-09T23:47:47.626Z",
  "lastModified": "2017-01-09T23:47:47.628Z",
  "access": "private",
  "modelType": "none",
  "id": "supply-chain-game",
  "account": "acme-simulations",
  "name": "The Supply Chain Game",
  "url": "newproj",
  "filePath": "newproj",
  "pushChannelEnabled": false,
  "pushChannelAuthorizationRequired": true,
  "multiplayer": false,
  "multiplayerSelfAssign": false,
  "modelSessionTimeout": 1800,
  "runCount": 0
}

Notes:

  • In the header, the Access Token is the user access token for a user (for personal projects) or team member (for team projects).
  • The account (Team ID or User ID) and id (Project ID) in the request body cannot be updated after project creation. The name and the optional fields in the request body can be updated later, either through the Project API or by updating the project settings.
  • The created and lastModified fields are in ISO 8601 format.
  • In addition to the return status code and response body, successfully creating a new project also creates model and interface top-level directories on the Epicenter backend servers. Users of the Epicenter user interface can immediately add files and folders here.

GET: Viewing Details about Projects

You can retrieve details about any project using the Project API GET method.

Retrieving Details about One Project

Method: GET

URI: /v2/project/{account id}/{project id}

Headers: Authorization: Bearer{access token}

Return Status: 200 (successful response)

Return Body: The record (JSON object) for the project.

Example:

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

Example Response:

{
    "id": "supply-chain-game",
    "runCount": 207,
    "lastModified": "2015-02-10T17:01:29.000Z",
    "access": "private",
    "pushChannelEnabled": false,
    "pushChannelAuthorizationRequired": false,
    "multiplayer": false,
    "multiplayerSelfAssign": false,
    "created": "2015-02-10T17:01:29.000Z",
    "account": "acme-simulations",
    "name": "The Supply Chain Game",
    "url": "supply-chain-game",
    "filePath": "supply-chain-game",
    "modelSessionTimeout": 1800,
    "modelType": "none"
}

Notes:

  • In the URI, the Account ID is the Team ID (for team projects) or User ID (for personal projects).
  • In the header, the Access Token can be either the user access token for a user or team member, or the project access token for this project.

Retrieving Details about Multiple Projects

Method: GET

URI:

  • /v2/project/{account id}/
  • /v2/project/{account id}/?{ampersand-separated query parameters}

Headers: Authorization: Bearer{access token}

Return Status: 200 (successful response)

Return Body: An array of project records (JSON objects).

Example:

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

Example Response:

[
    {
        "id": "supply-chain-game",
        "runCount": 207,
        "lastModified": "2015-02-10T17:01:29.000Z",
        "access": "private",
        "pushChannelEnabled": false,
        "pushChannelAuthorizationRequired": false,
        "multiplayer": false,
        "multiplayerSelfAssign": false,
        "created": "2015-02-10T17:01:29.000Z",
        "account": "acme-simulations",
        "name": "The Supply Chain Game",
        "url": "supply-chain-game",
        "filePath": "supply-chain-game",
        "modelSessionTimeout": 1800,
        "modelType": "none"
    },
    //other project records in this account, if any
]

Notes:

  • In the URI, the Account ID is the Team ID (for team projects) or User ID (for personal projects).
  • In the URI, you can query for EXACT match by adding id=, name=, or access= and the string to match. This returns records where the filtered field is exactly equal to the supplied string.
    • For example: https://api.forio.com/v2/project/acme-simulations?access=public.
  • In the URI, you can query for PARTIAL match by adding the query parameter, q, and the substring. This returns records where the substring is a full or partial match to either id or name. Include the query parameter multiple times to return records that include all of the terms (search is "AND").
    • For example: https://api.forio.com/v2/project/acme-simulations?q=supply&q=game.
  • In the URI, you can SORT the results in the array returned by including the query parameters sort and direction (ASC or DESC).
    • For example: https://api.forio.com/v2/project/acme-simulations?q=supply&sort=name&direction=ASC.
  • In the header, the Access Token can be either the user access token for a user or team member, or the project access token for this project.

Paging: Retrieving Many Records at Once

When you use the GET method for an API, your request may return many records at once.

The default page size is 100 (for most APIs) or 1000 (for the Data API). You can limit the number of records returned by adding the Range header.

Method: GET

URI: Any Epicenter API call

Headers: Range: records {i}-{j}

Return Status:

  • 200: Successfully retrieved all records
  • 206: Successfully retrieved the partially complete response, for example if you request records 0-20 and there are 35 records
  • 416: No records are found in a given search range (e.g. Range: records 10-15 when there are only 8 records)

Response Headers:

Whether or not you add the Range header to your request, the response header contains:

Content-Range: records i-j/k

where

  • i is the index of the first record returned
  • j is the index of the last record returned
  • k is the total number of records in the result set, or * if that number is computationally infeasible (for example, because you are querying across multiple projects)

For example, Content-Range: records 0-9/57 or Content-Range: records 20-29/*.

Response Body: An array of records. The array includes only those records indicated in the Content-Range header.

Example:

curl -G \
    'https://api.forio.com/v2/EpicenterAPI' \
    --header 'Range: records i-j'

Notes:

  • If no records are returned, the response body is empty.

  • If you leave off the start index, this is considered an implied start index of 0 rather than an invalid range. The response header includes status code of 200 or 206 depending on the ending index.

  • This use of the Range header is part of the RFC 2616 (see details in Section 14.16 and 14.35).

PATCH: Partially Updating a Project

You can partially update an existing project record (that is, replace one or more fields) using the Project API PATCH method.

Method: PATCH

URI: /v2/project/{account id}/{project id}

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

Body: JSON object with name-value pairs of the fields to update and the values with which to update them. Fields available to change include:

  • name: The longer, descriptive name of this project. (In the Epicenter user interface, this is called Project Name.)
  • access: Determines the project access.
    • Valid values are public, private, and authenticated. (However, authenticated is only valid if the account associated with this project has a type of team.)
  • modelType: Records the kind of model associated with this project.
    • Valid values are julia, vensim, python, r, simlang, none.
  • modelSessionTimeout: The number of seconds until the underlying session is closed. (In the Epicenter user interface, this is set in the project settings.)
  • multiplayer: Boolean, marks whether this project is for a multiplayer world.
  • pushChannelEnabled: Whether the Channel API is available for this project to use. (In the Epicenter user interface, this is set in the project settings.)
  • pushChannelAuthorizationRequired: Whether the Channel API requires credentials. In the Epicenter user interface, this is set in the project settings.)
  • multiplayerSelfAssign: Whether both end users and facilitators, or only facilitators, can create worlds and assign end users to worlds for groups in this project.

Return Status:

  • 200: Successfully updated project

Return Body: A JSON object with the project record just updated.

Example:

curl -X PATCH 'https://api.forio.com/v2/project/acme-simulations/supply-chain-game' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \
    --data '{"modelSessionTimeout": 3600}'

Example Response:

{
    "id": "supply-chain-game",
    "runCount": 207,
    "lastModified": "2015-02-10T17:01:29.000Z",
    "access": "private",
    "pushChannelEnabled": false,
    "pushChannelAuthorizationRequired": false,
    "multiplayer": false,
    "multiplayerSelfAssign": false,
    "created": "2015-02-10T17:01:29.000Z",
    "account": "acme-simulations",
    "name": "The Supply Chain Game",
    "url": "supply-chain-game",
    "filePath": "supply-chain-game",
    "modelSessionTimeout": 1800,
    "modelType": "none"
}

Notes:

  • In the URI, the Account ID is the Team ID (for team projects) or User ID (for personal projects).
  • In the header, the Access Token can be either the user access token for a user or team member, or the project access token for this project.
  • The project's account, id, and created fields cannot be changed. The project's lastModified field cannot be changed directly, but changes automatically when any of the other fields are updated.
  • The created and lastModified fields are in ISO 8601 format.

DELETE: Removing a Project

You can remove a project using the Project API DELETE method.

Method: DELETE

URI: /v2/project/{account id}/{project id}

Headers:

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

Body: none

Return Status:

  • 200: Project successfully removed from account

Return Body:

  • The project record just deleted.

Example:

curl -X DELETE 'https://api.forio.com/v2/project/acme-simulations/sample-project' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \

Example Response:

{
    "id": "sample-project",
    "url": "sample-project",
    "runCount": 0,
    "access": "private",
    "pushChannelEnabled": false,
    "pushChannelAuthorizationRequired": false,
    "multiplayer": false,
    "multiplayerSelfAssign": false,
    "created": "2015-02-10T00:48:16.000Z",
    "name": "Sample Project",
    "account": "acme-simulations",
    "lastModified": "2015-02-10T00:48:21.000Z",
    "filePath": "sample-project",
    "modelSessionTimeout": 1800,
    "modelType": "none"
}

Notes:

  • In the URI, the Account ID is the Team ID (for team projects) or User ID (for personal projects).
  • In the header, the Access Token can be either the user access token for a user or team member, or the project access token for this project.
  • Deleting an account also automatically deletes any projects under that account.