Skip to main content

API reference

The Shoreline Design API provides a fast, automated way to edit case data and submit that data to the Shoreline Design system to run simulations. Use the Design API to quickly run simulations with small changes to analyze the effects.

This page covers the intended use of the API, how to edit a case JSON file for submission through the API, and how to generate an API token.

note

Full API documentation, with requests, responses, payload examples, and a sandbox playground can be found in your Swagger documentation. If you don't know where it is, ask your CSM rep.

Description​

caution

You need an API key to access the Shoreline Design API. Contact your account admin if you need to generate API tokens. Once you've have access, follow the Generate an API token instructions.

Retrieve a partial case JSON through the Design API, make copies of the JSON, edit the copies, and submit the copies through our API. After your simulation runs complete, you can retrieve the results through the API.

See the intended flow in the diagram below.

The API flow

Output data from the API—-including files stored in S3, simulation registrations in the backend, and post-processed files in the dispatcher—-is deleted after 30 days. The 30-day period begins from the moment you submit a simulation request through the POST /simulations endpoint.

Edit a case JSON​

You must submit a valid partial case JSON for a simulation run to complete successfully. A partial case JSON contains only key case information for submission through the API.

While you can retrieve run status (in progress, completed, or failed) through an API call, the reason for failure is not given in the API response.

When editing a partial case JSON for submission through the API, only edit data in the following sections:

  • vesselList
  • personnelList
  • Under windFarms > infrastructureList > fixable
caution

All parameters in your case JSON must match the case type, either a Construction or O&M case. For example, do not change the fixableType of a WTG from INSTALLATION_TASK (a Design parameter) to CORRECTIVE_MAINTENANCE (an O&M parameter).

Generate an API token​

Contact your account administrator if you require access to the API Clients section of your account's team settings.

  1. Go to your Team settings. The team settings button
  2. Click on API Clients. The API clients tab of the team settings
  3. At the bottom of the table, click New client.
  4. Enter a Name and click the Check (save) icon.
  5. Copy the Identifier and Secret.
  6. Copy the following code and replace {client_id} and {client_secret} with the values from step 5. 
    curl -v https://design.shoreline.no/api/oauth2/token -d "client_id={client_id}&client_secret={client_secret}&grant_type=client_credentials" -H "Content-Type: application/x-www-form-urlencoded"
  7. Copy and paste the code into your terminal and run it.

The response provides an access_token key and value. Extract the value for this key. This is your API token that you can use to authenticate your API requests.