Creates a single Action. Can be a user action, or an action linked to a board or other Fluid entity.
TABLE OF CONTENTS
- Create a User Action
- Create an Action on a board workspace
- Create an Action on a board workspace (Sub Board)
- Further Reading
If creating an Action for a board or other Fluid entity The REST API account user needs to have the correct manage permission for the board or Fluid entity If the account does not have manage permissions, a Http Code 403 Forbidden response is returned. OpenAPI documentation can be found at https://organisation.fluid.work/docs where organisation is the name of your organisation.
Create a User Action
HTTP
POST https://organisation.fluid.work/rest/api/action
cURL
curl --user username:patToken --location 'http://organisation.fluid.work/rest/api/action' \ --header 'Content-Type: application/json' \ --data ' { "fields": { "title": "Sample Title", "description": "Sample Description", "status": "Not Started", "taskType": "Task" } }'
with optional parameters
HTTP
POST https://organisation.fluid.work/rest/api/action/?fields={fields}&$expand={$expand}&version=3.0
cURL
curl --user username:patToken --location 'http://organisation.fluid.work/rest/api/action?fields=all&expand=all' \ --header 'Content-Type: application/json' \ --data ' { "fields": { "title": "Sample Title", "description": "Sample Description", "status": "Not Started", "taskType": "Task" } }'
Response
Status code: 200
JSON
{ "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-02-16T14:45:22.0000000", "description": "Sample Description", "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-02-16T14:45:22.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": "Not Started", "statusCode": 4, "taskType": "Task", "title": "Sample Title" }, "id": 4360, "guid": "46522a95-7668-482a-a484-2952174b2430", "url": "https://organisation.fluid.work/rest/api/action/4360" }
URL Parameters
Name | In | Required | Type | Description |
fields | query | false | string | Comma-separated list of requested fields to return in the response |
expand | query | false | string | Expand parameter for Action attributes. Possible options are{"none" "all" "method" "related" "chat" "customAll" "customReportable" "customReadOnly" "subtask" "attachment" "state"} |
version | query | false | string | Version of the API to use. if not set, default latest version will be used. |
Response
Name | Type | Description |
200 OK | Action | successful operation |
400 | string | Bad Request |
401 | string | Not an authorised user, username or token is invalid |
403 | string | Forbidden, user is not permissioned to perform the operation in this particular context |
422 | string | Invalid arguments, request, query or body arguments are invalid |
429 | string | "Too many Requests" see response headers RateLimit-Limit (current rate limit capacity), RateLimit-Remaining (remaining tokens), RateLimit-Reset (time till next refill) |
Response Headers
Name | Type | Description |
RateLimit-Limit | string | Max rate limit of requests allowed |
RateLimit-Remaining | string | Remaining capacity of requests allowed |
RateLimit-Reset | string | Next date time for refresh of capacity |
Create an Action on a board workspace
Creates a single Action on a specified board workspace. More information on board workspaces can be found here
To create an Action on a specific board and backlog, an additional principalGuid property is required on the POST payload. The principalGuid is the unique key that directly identifies the board.
You can use the Board REST API to GET the principalGuid for a board. Rest API endpoint for Boards
An alternate method to locate the guid for a board is by navigating to the board in a browser, and looking at the URL. It should read as http://organisation.fluid.work/Process/Board/7505a102-93fc-4465-a23b-2eb6303f7f71 the value 7505a102-93fc-4465-a23b-2eb6303f7f71 is the principal GUID you should pass as part of the payload.
Actions on a board contain a value for the boardGuid property, when making an API call to GET an Action, setting query parameter fields=all. This boardGuid property can used as the principalGuid of the board.
HTTP
POST https://organisation.fluid.work/rest/api/action
cURL
curl --user username:patToken --location 'http://organisation.fluid.work/rest/api/action' \ --header 'Content-Type: application/json' \ --data ' { "fields": { "principalGuid": "7505a102-93fc-4465-a23b-2eb6303f7f71", "title": "Sample Title", "description": "Sample Description" "status": "Not Started", "taskType": "Task" } }'
with optional parameters
HTTP
POST https://organisation.fluid.work/rest/api/action/?fields={fields}&$expand={$expand}&version=3.0
cURL
curl --user username:patToken --location 'http://localhost:55648/rest/api/action?fields=all&expand=all' \ --header 'Content-Type: application/json' \ --data ' { "fields": { "principalGuid": "7505a102-93fc-4465-a23b-2eb6303f7f71", "title": "Sample Title", "description": "Sample Description" "status": "Not Started", "taskType": "Task" } }'
Response
Status code: 200
JSON
{ "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" }, "boardCategory": 0, "boardId": 0, "boardGuid": "7505a102-93fc-4465-a23b-2eb6303f7f71", "boardTitle": "Bulk edit", "businessValue": 0, "chatCount": 0, "contentType": "Process", "createDate": "2024-02-16T19:20:41.0000000", "description": "Sample Description - Create Action on a Board", "descriptionHtml": "Sample Description - Create Action on a Board", "dueDate": null, "endDate": null, "isClosed": false, "isCalculated": false, "isOwner": true, "modifiedBy": { "id": 603, "guid": "f1cb6467-0262-4539-9148-7b869defd817", "name": "David Burt", "userName": "david.burt", "email": "dump18@fluidbsg.com" }, "modifiedDate": "2024-02-16T19:20:41.0000000", "principalGuid": "7505a102-93fc-4465-a23b-2eb6303f7f71", "shortCode": "BE-105", "startDate": null, "status": "Not Started", "statusCode": 1, "taskType": "Task", "title": "Sample Title - Create Action on a Board", "titleRichText": "Sample Title - Create Action on a Board", "titleHtml": "Sample Title - Create Action on a Board" }, "id": 4433, "methods": [ { "type": "PermaLink", "httpMethod": "GET", "url": "https://organisation.fluid.work/Action/EditFull/12c2e661-270c-43e1-8d05-1218b5842b6c" }, { "type": "Update", "httpMethod": "PUT", "url": "https://organisation.fluid.work/rest/api/action/4433", "description": "Update Action", "payload": { "fields": { "description": "<Description>", "title": "<Title>" }, "customProperties": [] } }, { "type": "Delete", "httpMethod": "DELETE", "url": "https://organisation.fluid.work/rest/api/action/4433" } ], "guid": "12c2e661-270c-43e1-8d05-1218b5842b6c", "url": "https://organisation.fluid.work/rest/api/action/4433" }
Create an Action on a board workspace (Sub Board)
Creates a single Action on a Board workspace and in a specific Sub Board. A board workspace can contain multiple Sub Boards. Each Sub Board has its own unique guid that identifies it, this is referred to as the ParentGuid.
Two additional guids are required, the principalGuid guid of the board workspace, and the parentGuid of the Sub Board itself.
You can use the Board REST API to GET the principalGuid for a board. Rest API endpoint for Boards
An alternate method to locate the guid for a board is by navigating to the Sub Board in a browser, and looking at the URL. It should read as https://organisation.fluid.work/Process/Board/c07hed88-10h0-4hc4-hec5-h57073b8e036/19ef7803-8e9e-4037-a613-0761336e0bcb/58c0kk41-2ekf-41k9-9kc3-27dke10bkadd/
c07hed88-10h0-4hc4-hec5-h57073b8e036 is the principalGuid
58c0kk41-2ekf-41k9-9kc3-27dke10bkadd is the parentGuid
If you do not specify a parentGuid the Action will be created in the backlog of the board workspace
HTTP
POST https://organisation.fluid.work/rest/api/action
cURL
curl --user username:patToken --location 'http://organisation.fluid.work/rest/api/action' \ --header 'Content-Type: application/json' \ --data ' { "fields": { "principalGuid": "c07hed88-10h0-4hc4-hec5-h57073b8e036", "parentGuid": "58c0kk41-2ekf-41k9-9kc3-27dke10bkadd", "title": "Sample Title", "description": "Sample Description" "status": "Not Started", "taskType": "Task" } }'
with optional parameters
HTTP
POST https://organisation.fluid.work/rest/api/action/?fields={fields}&$expand={$expand}&version=3.0
cURL
curl --user username:patToken --location 'http://localhost:55648/rest/api/action?fields=all&expand=all' \ --header 'Content-Type: application/json' \ --data ' { "fields": { "principalGuid": "c07hed88-10h0-4hc4-hec5-h57073b8e036", "parentGuid": "58c0kk41-2ekf-41k9-9kc3-27dke10bkadd", "title": "Sample Title", "description": "Sample Description" "status": "Not Started", "taskType": "Task" } }'
Response
Status code: 200
JSON
{ "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" }, "boardCategory": 0, "boardId": 0, "boardGuid": "7505a102-93fc-4465-a23b-2eb6303f7f71", "boardTitle": "Bulk edit", "businessValue": 0, "chatCount": 0, "contentType": "Process", "createDate": "2024-02-16T19:20:41.0000000", "description": "Sample Description - Create Action on a Board", "descriptionHtml": "Sample Description - Create Action on a Board", "dueDate": null, "endDate": null, "isClosed": false, "isCalculated": false, "isOwner": true, "modifiedBy": { "id": 603, "guid": "f1cb6467-0262-4539-9148-7b869defd817", "name": "David Burt", "userName": "david.burt", "email": "dump18@fluidbsg.com" }, "modifiedDate": "2024-02-16T19:20:41.0000000", "principalGuid": "7505a102-93fc-4465-a23b-2eb6303f7f71", "shortCode": "BE-105", "startDate": null, "status": "Not Started", "statusCode": 1, "taskType": "Task", "title": "Sample Title - Create Action on a Board", "titleRichText": "Sample Title - Create Action on a Board", "titleHtml": "Sample Title - Create Action on a Board" }, "id": 4433, "methods": [ { "type": "PermaLink", "httpMethod": "GET", "url": "https://organisation.fluid.work/Action/EditFull/12c2e661-270c-43e1-8d05-1218b5842b6c" }, { "type": "Update", "httpMethod": "PUT", "url": "https://organisation.fluid.work/rest/api/action/4433", "description": "Update Action", "payload": { "fields": { "description": "<Description>", "title": "<Title>" }, "customProperties": [] } }, { "type": "Delete", "httpMethod": "DELETE", "url": "https://organisation.fluid.work/rest/api/action/4433" } ], "guid": "12c2e661-270c-43e1-8d05-1218b5842b6c", "url": "https://organisation.fluid.work/rest/api/action/4433" }
Definitions
Name | Description |
id | The Id integer, uniquely identifies this particular Action, can be interchangeable with guid, see below |
guid | The guid string, uniquely identifies this particular Action, can be interchangeable with id, see above |
url | The REST GET Url for this Action |
fields | Map of field and values for the Action |
assignee[] | Describes a list of users this action has been assigned to |
author | Describes the user who authored this Action |
modifiedBy | Describes the user who last modified this Action |
owners[] | Describes a list of users this action is owned by |
Expand
Query parameter "expand=all" will expand all the possible response properties listed below that are associated with this entity. "expand=none" to hide all response properties.
CustomProperties[]
Name | Description |
guid | The guid string, uniquely identifies this particular custom property |
dataType | The data type of the value for this Custom Property. eg string, datetime etc |
isAdminLocked | |
isCatalogType | Custom Property is a Catalog Type and is used as part of taxonomy |
isMultiple | Can contain multiple values |
isSubType | |
key | Unique name key that identifies this Custom Property by name |
required | Flag to indicate this Custom Property requires a valid value |
reportable | Flag to indicate this Custom Property is reportable |
readOnly | Flag to indicate value is read only and cannot be changed |
value | The value of this Custom Property |
Methods[]
Properties returned for requested expanded value set on query param "expand=method", methods are helper properties to other REST verb API endpoints that can be used directly.
Name | Description |
type | The type of action this method performs |
httpMethod | HTTP Request Method verb |
url | The REST URL that can be used with the Http Method verb |
description | Description of what this method performs |
payload | Sample payload related to the HTTP Method verb. This payload is typically the minimal payload required to perform the verb method. |
Attachment[]
Properties returned for requested expanded value set on query param "expand=attachment". Checklist properties that are defined as part of this entity.
Name | Description |
Id | The Id integer, uniquely identifies this particular Attachment |
Guid | The guid string, uniquely identifies this particular Attachment |
Title | Title of this Attachment |
ModifiedDate | Timestamp this Attachment was last modified |
Type | Type of this Attachment |
Status | Status of this Attachment |
Filename | Filename of the attachment |
Url | Url to open/view or download this Attachmemt |
ModifiedBy | User that last modified this Attachment |
Chat[]
Properties returned for requested expanded value set on query param "expand=chat", chat are comments/chat conversations that are associated with this entity
Name | Description |
Id | Unique id that represents this chat message |
Content | Text only representation of the content of the chat message |
TopicId | The topic Id/chat room this chat message has been post to |
Display | Html version of the content that is displayed to the user |
Initiator | The user that posted this chat message |
Timestamp | The timestamp when this chat message was posted |
Title | The title of the chat room this chat message was posted to |
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