The Fusion Online API is built on HTTP and follows REST principles. It uses HTTP response codes to indicate errors and it accepts and returns JSON in the HTTP body.

The API is OpenAPI 3.0 compliant. You can find detailed information about the OpenAPI specification on the Swagger website.

The API uses the same domain and subdomain as your Fusion browser application. For example, you would use the following URL to retrieve a list of tasks via the API https://{yourcompany}.fusiononline.app/api/v1/tasks (where {yourcompany} is replaced with the subdomain for your Fusion account).

The OpenAPI API specification for Fusion Online should be downloaded directly from the Fusion application in order for the server URL to match your subdomain. See the Swagger UI section below for more information on how to download the OpenAPI specification and how to try the API with your live data using the Swagger UI browser interface.

OpenAPI Tools

You can use the Fusion API with any HTTP/REST library. There are also several open-source OpenAPI code generators that can create client SDKs from the Fusion OpenAPI specification, like swagger-codegen and OpenAPI Generator.

.NET SDK

We provide a Fusion .NET SDK, which includes a sample Visual Studio 2022 solution and .NET Fusion API libraries.

• ProChain.Fusion.Sdk.Api folder contains the .NET libraries needed to use the Fusion API from a .NET application.
• ProChain.Fusion.Sdk.Examples folder contains a Visual Studio 2022 sample solution.

CSV Download Tool

The Fusion CSV Download Tool is a command-line executable that connects to the Fusion API and allows you to download data in CSV format.

Fusion Online provides a Swagger UI page that can be used to test the API with your live data. You can also download the OpenAPI specification from the Swagger UI page with the correct server URL already configured. Contact support@prochain.com to get the unique web address for your Swagger UI page.

The Swagger UI will indicate which API endpoints require authorization with a padlock icon displayed to the right of the endpoint name. Use the POST /session endpoint to login to Fusion with a valid username/password. This endpoint will respond with a JWT string in the token field. Copy the token value and click on the Authorize button at the top of the Swagger UI page. You will then put Bearer {token} in the value field inside the dialog box, where {token} is replaced with the full token value that was received in the login response.

Bearer Authentication

The Fusion Online API uses a bearer token for authentication. The token uses the JSON Web Token (JWT) format. The token should be submitted in the Authorization header with every API request that requires authorization. The correct format for the Authorization header value is Bearer {token}, where {token} is replaced with the correct JWT.

To create a JWT token, you first need to generate an API key in Fusion Online, which requires System Administrator access. Once the API key is created, you can use it with the POST /session/api-key endpoint to obtain a JWT access token for authentication. The access token is valid for 15 minutes. Along with the access token, a refresh token is also returned, which can be used to request a new access token. The refresh token remains valid for the duration specified in the Idle Session Timeout option on the System Options page in Fusion Online.

Windows Authentication

On-premise Fusion Online customers can choose to use Windows Authentication instead of a username/password to create the bearer token. Because Windows Authentication makes use of the 401 HTTP response code when requesting authentication, the API will responsd with a 460 HTTP response code when a request is made to an endpoint that requires authorization and the token is missing or invalid. This only applies to on-premise Fusion installations. For cloud customers, the API will respond with a standard 401.

If you wish to authenticate using Windows Authentication, you will need to use POST /session/windows to generate the bearer token, and you will need to use a library or platform that supports the Windows Authentication negotiation with the web server.

The Fusion API uses common HTTP verbs to define operations on resources or collections.

• GET is used to retrieve a representation of a resource or a collection of resources.
• DELETE is used to delete existing resources.
• POST is used to create a new resource. The Fusion API also uses POST to create asynchronous jobs and to perform a bulk update of resources.
• PUT is used to update a resource. This verb is used when submitting the entire representation of a resource for update.
• PATCH is used to update a resource. This verb is used when submitting a partial representation of a resource for update.

PATCH Requests

PATCH requests allow the API consumer to update a partial resource. The Fusion API uses a simple approach to handling PATCH requests, with the use of specific PATCH schemas that are distinct from the GET resource schemas.

• PATCH request schema property names will match equivalent property names in the GET schema for the same resource.
• All PATCH request schema properties are nullable.
• Omitting a property or setting the property to a null value means that it will not be updated.

• 200 Success The success response schema for the resource is returned.

• 204 - Success No Content The request was successfully fulfilled and no additional response is returned.

• 400 - Invalid Request This response code is returned for missing or invalid parameters. Validation errors will be returned with this response code. The API returns a standard response schema for this return code.

• 401 - Unauthorized Request - CLOUD ONLY. This response code is returned for any endpoint that requires authorization if the token in the authorization header is missing or invalid.

• 403 - Permission Denied This response code is returned if the user does not have permission to update or view the resource. The API returns a standard response schema for this return code.

• 404 - Resource Not Found This response code is returned if the requested resource does not exist.

• 429 - Too Many Requests (Rate Limit Exceeded) - This status code indicates that the client has exceeded the allowed number of requests in a given timeframe. Refer to the Rate Limits section for details on request frequency constraints and guidance on how to avoid this limit.

• 460 - Unauthorized Request - ON-PREMISE ONLY. We use a special response code for on-premise Fusion installations because the 401 interferes with Windows Authentication in the browser.

• 500 - Server Error This response code is used for all unexpected server errors. If the response is returned by the Fusion app, it will return a standard response schema.

By default, requests to the Fusion Online API are limited to 300 requests per minute. This applies on a per-user (or per-API key) basis. If you exceed this limit, you will receive a 429 – Too Many Requests response. For on-premise installations, the rate limit can be configured to meet specific requirements.

Rate Limit Headers

The following headers are included in each response to help you monitor and manage your usage:

• X-Ratelimit-Limit The number of requests allowed per minute.

• X-Ratelimit-Remaining The number of requests remaining within the current one-minute window.

• X-Ratelimit-Reset The timestamp (in milliseconds since the Unix epoch) when the current rate limit window will reset.

Use these headers to implement back-off strategies or delay further requests until the quota resets, ensuring you stay within the allowed limits.

The Accept request header should be set to the desired response content type. The Fusion API accepts and returns application/json content in the HTTP body for most endpoints, and this is what you would generally set in the Accept header. Some endpoints will support more than one response content type, and the Fusion API will use the Accept header to determine which one to return.

Many of the GET operations will return paginated results. Pagination is controlled with the use of two query parameters. Use the maxResults query parameter to specifiy the maximum number of resources to be returned. Use the skip parameter to specify whether or not to offset the start of the results.

All paginated responses use the same base schema with the following two properties:

• totalCount specifies the total number of resources that match your request.
• isTotalCountLimited is set to true if the totalCount is limited by Fusion API limits. The Fusion API has a current limit of 3000 resources in a paginated response. For example, if you make a request for tasks, and there are more than 3000 tasks that match your request, the totalCount will be set to 3000 and the isTotalCountLimited will be true to indicate that the response is limited to the first 3000 tasks that match your request.

The Fusion API uses model composition to share common properties across schemas. For some of the more complex data models, the API provides a hierarchy of schemas. For example, a task is represented with the following schemas:

• Task schema is a basic representation of a task, including the task name and the task key.
• TaskInfo schema inherits from Task and contains a lot more information about the task, including project information and duration.
• TaskDetails schema inherits from TaskInfo and contains all of the optional task properties. You can request which properties to return in the TaskDetails with the use of the dataFields query parameter.

Some of the larger schemas, like TaskDetails and ProjectDetails, require you to choose which properties to populate in the response. This allows you to request only the data that you need, thereby reducing application and network load. Use the dataFields query parameter to specify the properties that you need.

The following schemas are controlled by the dataFields query parameter. The data type of the query parameter is an enum that is specific to the schema that is being requested.

• ProjectDetails uses the ProjectDetailsField enum.
• TaskDetails uses the TaskDetailsField enum.
• EndpointDetails uses the EndpointDetailsField enum.