Welcome to the Fluid REST API Reference.
Representational State Transfer (REST) APIs are service endpoints that support sets of HTTP operations (methods), which provide create, retrieve, update, or delete access to the service's resources. This article walks you through:
- The basic components of a REST API request/response pair.
- Overviews of creating and sending a REST request, and handling the response.
You can use Fluids API to build scripts and applications that automate processes, integrate with Fluid, and extend Fluid. For example, you could use the API to triage Action RAG statuses, projects and boards.
Each REST API endpoint is documented individually, and the endpoints are categorized by the resource that they primarily affect. For example, you can find endpoints relating to action under the Action folder in "REST Api endpoint for Actions"
We strongly encourage testing your code/scripts against your Sandbox environment and not directly against Production. If you don't currently have a Sandbox environment please contact your Fluid client success representative.
Developer online Open API documentation can be found at https://organisation.fluid.work/docs
See the end of this article for a Postman collection that can be imported and used for test/development purposes.
TABLE OF CONTENTS
- Components of a REST API request/response pair
- Elements of a REST API Request
- HTTP method
- Path
- Headers
- Content types
- Authentication
- Parameters
- Create the request
- Assemble the request
- Process the response
- Response Headers
- Paging Responses
- Postman Request/Response
- Further Reading
Components of a REST API request/response pair
A REST API request/response pair can be separated into five components:
1. The request URI, in the following form: VERB https://{organisation}.fluid.work/rest/api/{resource}?version={version}
- organisation: Your organization or server you're sending the request to. They are structured as follows:
- resource path: The resource path is as follows: /rest/api/{resource}. For example /rest/api/action.
- version: Every API request should include a version to avoid having your app or service break as APIs evolve. versions are in the following format: {major}.{minor}[-{stage}[.{resource-version}]], for example:
- version=3.0
- version=3.1-preview
- version=3.0-preview.1
2. HTTP request message header fields:
- A required HTTP method (also known as an operation or verb), which tells the service what type of operation you are requesting. Fluid REST APIs support GET, HEAD, PUT, POST, and PATCH methods.
- Optional additional header fields, as required by the specified URI and HTTP method. For example, an Authorization header that provides a bearer token containing client authorization information for the request.
3. Optional HTTP request message body fields, to support the URI and HTTP operation. For example, POST operations contain MIME-encoded objects that are passed as complex parameters.
- For POST or PUT operations, the MIME-encoding type for the body should be specified in the Content-type request header as well. Some services require you to use a specific MIME type, such as application/json.
4. HTTP response message header fields:
- An HTTP status code, ranging from 2xx success codes to 4xx or 5xx error codes. Alternatively, a service-defined status code may be returned, as indicated in the API documentation.
- Optional additional header fields, as required to support the request's response, such as a Content-type response header.
5. Optional HTTP response message body fields:
MIME-encoded response objects may be returned in the HTTP response body, such as a response from a GET method that is returning data. Typically, these objects are returned in a structured format such as JSON, as indicated by the Content-type response header. Note for the purposes of the Fluid REST API responses are always returned in JSON format, irrespective of the Content-type set.
Elements of a REST API Request
Every request to the REST API includes an HTTP method and a path. Depending on the REST API endpoint, you might also need to specify request headers, authentication information, query parameters, or body parameters.
The REST API reference documentation describes the HTTP method, path, and parameters for every endpoint. It also displays example requests and responses for each endpoint. For more information, see the REST reference documentation.
HTTP method
The HTTP method of an endpoint defines the type of action it performs on a given resource. Some common HTTP methods are GET, POST, DELETE, and PATCH. The REST API reference documentation provides the HTTP method for every endpoint.
For example, the HTTP method for the "List repository issues" endpoint is GET."
Where possible, the Fluid REST API strives to use an appropriate HTTP method for each action.
GET: Used for retrieving resources.
POST: Used for creating resources.
PUT: Used for replacing resources or collections of resources.
DELETE: Used for deleting resources.
Path
Each endpoint has a path. The REST API reference documentation gives the path for every endpoint. For example, the path to get a specific action for a specific ID, the endpoint is http://organisation.fluid.work/rest/api/action/{id}.
The curly brackets {} in a path denote path parameters that you need to specify. Path parameters modify the endpoint path and are required in your request.
Headers
Headers provide extra information about the request and the desired response. Following are some examples of headers that you can use in your requests to the Fluid REST API. For an example of a request that uses headers, see "Making a request."
Content types
Content types specify the format of the data you want to consume from the API. Content types are specific to resources, allowing them to change independently and support formats that other resources don't. Fluid uses content type application/json.
Authentication
All endpoints require authentication.
Parameters
Many API methods require or allow you to send additional information in parameters in your request. There are a few different types of parameters: Path parameters, body parameters, and query parameters.
Path parameters
Path parameters modify the endpoint path. These parameters are required in your request. For more information, see "Path."
Body parameters
Body parameters allow you to pass additional data to the API. These parameters can be optional or required, depending on the endpoint. For example, a body parameter may allow you to specify an issue title when creating a new issue, or specify certain settings when enabling or disabling a feature. The documentation for each Fluid REST API endpoint will describe the body parameters that it supports.
For example, the "Create an Action" endpoint requires that you specify a title for the new Action in your request. It also allows you to optionally specify other information, such as text to put in the Action description, users to assign to the new Action etc.
Query parameters
Query parameters allow you to control what data is returned for a request. These parameters are usually optional. The documentation for each Fluid REST API endpoint will describe any query parameters that it supports.
Create the request
Authenticate
The Fluid REST API currently only supports basic authentication with a username and PAT token. See the KB article Creating a Personal Access Token for more information on how to generate a PAT token.
About PATs
A personal access token contains your security credentials for Fluid. A PAT identifies you, your accessible organizations, and scopes of access. As such, they're as critical as passwords, so you should treat them the same way.
Assemble the request
For Fluid, instances are of the format {organisation}.fluid.work/, so the pattern looks like this:
VERB https://organisation.fluid.work/rest/api/{resource}?version={version}
For example, here's how to get a list of my actions in Fluid.
curl --user username:pattoken --location 'http://organisation.fluid.work/rest/api/action?version=3.0'
If you wish to provide the personal access token through an HTTP header, you must first convert it to a Base64 string (the following example shows how to convert to Base64 using C#). (Certain tools like Postman applies a Base64 encoding by default. If you are trying the API via such tools, Base64 encoding of the PAT is not required) The resulting string can then be provided as an HTTP header in the format:
Authorization: Basic BASE64PATSTRING
Here it is in C# using the [HttpClient class](/previous-versions/visualstudio/hh193681(v=vs.118).
public static async void GetActions()
{
try
{
var personalaccesstoken = "PAT_FROM_WEBSITE";
using (HttpClient client = new HttpClient())
{
client.DefaultRequestHeaders.Accept.Add(
new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic",
Convert.ToBase64String(
System.Text.ASCIIEncoding.ASCII.GetBytes(
string.Format("{0}:{1}", "", personalaccesstoken))));
using (HttpResponseMessage response = await client.GetAsync(
"https://client.fluid.work/rest/api/action"))
{
response.EnsureSuccessStatusCode();
string responseBody = await response.Content.ReadAsStringAsync();
Console.WriteLine(responseBody);
}
}
}
catch (Exception ex)
{
Console.WriteLine(ex.ToString());
}
}
Process the response
You should get a response like this.
[
{
"fields": {
"assignee": [
{
"id": 603,
"guid": "f1cb6467-0262-4539-9148-7b869defd817",
"name": "David Burt",
"userName": "david.burt",
"email": "dump18@fluidbsg.com"
}
],
"attachmentCount": 0,
"author": {
"id": 603,
"guid": "f1cb6467-0262-4539-9148-7b869defd817",
"name": "David Burt",
"userName": "david.burt",
"email": "dump18@fluidbsg.com"
},
"businessValue": 0,
"chatCount": 0,
"createDate": "2024-01-19T11:57:15.0000000",
"description": "Description 1",
"dueDate": null,
"endDate": null,
"impediment": 0,
"isOwner": true,
"modifiedBy": {
"id": 603,
"guid": "f1cb6467-0262-4539-9148-7b869defd817",
"name": "David Burt",
"userName": "david.burt",
"email": "dump18@fluidbsg.com"
},
"modifiedDate": "2024-01-19T11:57:15.0000000",
"owners": [
{
"id": 603,
"guid": "f1cb6467-0262-4539-9148-7b869defd817",
"name": "David Burt",
"userName": "david.burt",
"email": "dump18@fluidbsg.com"
}
],
"priority": "Medium",
"principalGuid": "f1cb6467-0262-4539-9148-7b869defd817",
"ragStatus": "Green",
"startDate": null,
"status": "Request",
"statusCode": 4,
"taskType": "Task",
"title": "Title 1"
},
"id": 4317,
"guid": "00d8b850-6b78-4c1f-95c1-7818606d0bb2",
"url": "https://organisation.fluid.work/rest/api/action/4317"
},
{
"fields": {
"assignee": [
{
"id": 603,
"guid": "f1cb6467-0262-4539-9148-7b869defd817",
"name": "David Burt",
"userName": "david.burt",
"email": "dump18@fluidbsg.com"
}
],
"attachmentCount": 0,
"author": {
"id": 603,
"guid": "f1cb6467-0262-4539-9148-7b869defd817",
"name": "David Burt",
"userName": "david.burt",
"email": "dump18@fluidbsg.com"
},
"businessValue": 0,
"chatCount": 0,
"createDate": "2023-10-13T18:50:01.0000000",
"description": "Description 2",
"dueDate": null,
"endDate": null,
"impediment": 0,
"isOwner": true,
"modifiedBy": {
"id": 603,
"guid": "f1cb6467-0262-4539-9148-7b869defd817",
"name": "David Burt",
"userName": "david.burt",
"email": "dump18@fluidbsg.com"
},
"modifiedDate": "2023-10-13T18:50:01.0000000",
"owners": [
{
"id": 603,
"guid": "f1cb6467-0262-4539-9148-7b869defd817",
"name": "David Burt",
"userName": "david.burt",
"email": "dump18@fluidbsg.com"
}
],
"priority": "Medium",
"principalGuid": "f1cb6467-0262-4539-9148-7b869defd817",
"ragStatus": "Green",
"startDate": "2023-10-04T00:00:00.0000000",
"status": "Request",
"statusCode": 4,
"taskType": "Task",
"title": "Title 2"
},
"id": 4206,
"guid": "0d0fcfb6-b1d9-41b0-8264-b29ace60df63",
"url": "https://organisation.fluid.work/rest/api/action/4206"
}
]Response Headers
| Name | Type | Description |
| RateLimit-Limit | int | Max rate limit of requests allowed |
| RateLimit-Remaining | int | Remaining capacity of requests allowed |
| RateLimit-Reset | string | Next date time for refresh of capacity |
| Item-Count | int | Current number of items returned in this API response. |
| Total-Count | int | Total count of items that form this API response, for calls that return more than the max value of 50 items, this count is the total number of items that are apart of this response. |
Paging Responses
Some API calls will return a list of response JSON objects, Actions for example can return a list of Actions. The maximum number of items to return in a response is 50. To get the full list of response you will need to make multiple REST API requests to get the next page of results.
The two HTTP response headers Item-Count and Total-Count mentioned above will contain values that you can use to pass in to subsequent HTTP requests as query values for parameters "skip" and "take".
If for example if Total-Count = 150, and Item-Count = 50, then the total number of response objects is 150, current number of items returned is 50.
To get the next page of results, set query parameters ?skip=50, ?take=50. This will skip the first 50 results that have already been returned and will return the next set of results, and take the next 50 results. If you do not specify a value a take query parameter, the default max value of 50 is applied internally..
The Http response header Total-Count will still show 150, but Item-Count is now 100.
Repeat this process to get the next page of results, set query parameters ?skip=100. This will skip the first 100 results that have already been returned and will return the next set of results, up to the max value of 50.
The Http response header Total-Count will still show 150, Item-Count is now 150. and the response list response is empty. indicating all results have now been returned.
Postman Request/Response
Attached below is a Postman collection file that can be used to import a sample set of request/response tests that can be used to verify the API. Download the attached file and import into Postman.
Authentication
You will need to update the Authorization details as per below in Postman, select Type as Basic Auth, and enter the username of the account you will be using to access the API, and the password should be the PAT token for that account. See Creating a Personal Access Token for more details.
You should use the username and token values as returned by the Creating a Personal Access Token process and not the base64 token.
Variables
For the baseUrl variable, you should update this as per your Fluid organisation URL
Further Reading
Was this article helpful?
That’s Great!
Thank you for your feedback
Sorry! We couldn't be helpful
Thank you for your feedback
Feedback sent
We appreciate your effort and will try to fix the article