Fleet

Fleet Object

Field	Type	Description
id	snowflake	the fleet's id
organisation_id	snowflake	the id of the organisation the fleet belongs to
code	string	a short code for the fleet (max 12 characters)
name	string	the fleet's name (max 200 characters)
description	string	a description for the fleet
color	string	the fleet's color as a hex string
root_system_id	?snowflake	the id of the root system linked to the fleet

Fleet Subscription User Object

A subscription that notifies a user about changes to work items assigned to a fleet, optionally filtered by work item type and location.

Field	Type	Description
fleet_id	snowflake	the id of the fleet to subscribe to
user	user object	the subscribed user (see Object or Id)
is_sync	boolean	whether to sync all open work items to the user's device
location	?location object	the location filter for subscriptions (see Object or Id)
work_item_type	?work item type object	the work item type filter for subscriptions (see Object or Id)

Fleet Share Object

A share of a fleet with another user, optionally scoped to a specific work item type and organisation.

Field	Type	Description
id	snowflake	the fleet share's id
fleet	fleet object	the shared fleet
user	user object	the user the fleet is shared with
organisation	?organisation object	the organisation to share the fleet with (optional)
work_item_type	?work item type object	the work item type to scope the share to (optional)
shared_by	user object	the user who created the share
status	fleet share status	the current status of the share
scope	string	the scope of the share
share_to_users_organisation	boolean	whether the share is directed to the user's organisation
shared_at	ISO8601 timestamp	when the share was created

Fleet Share Status

Value	Description
pending	the share is awaiting acceptance or rejection
accepted	the share has been accepted by the recipient
rejected	the share has been rejected by the recipient
revoked	the share has been revoked by the sharer

List Fleets

GET /organisations/{organisation.id}/fleets

Returns an array of fleet objects for the organisation. Requires membership in the organisation.

Error Responses

Status Code	Description
400	Bad request (organisation does not exist)
403	Forbidden (user is not a member of the organisation)

Create Fleet

POST /organisations/{organisation.id}/fleets

Creates a new fleet in the organisation. Requires the MANAGE_FLEETS permission.

JSON Params

Field	Type	Description	Default
code	?string	the fleet's code (max 12 characters)
name	?string	the fleet's name (max 200 characters)	new fleet
description	?string	the fleet's description
colour	?string	the fleet's colour as a hex string
root_system_id	?snowflake	the id of the root system to link to the fleet

Error Responses

Status Code	Description
400	Bad request (organisation does not exist)
403	Forbidden (user lacks the MANAGE_FLEETS permission)

Get Fleet

GET /api/fleets/{id}

Returns the fleet object for the given fleet id. Requires membership in an organisation that owns the fleet, or an accepted fleet share from such an organisation.

Error Responses

Status Code	Description
404	Not found (fleet does not exist)
403	Forbidden (user cannot view the fleet)

Update Fleet

PATCH /api/fleets/{id}

Updates a fleet. Requires the MANAGE_FLEETS permission for the organisation that owns the fleet. Only the fields provided will be updated.

JSON Params

Field	Type	Description
code	?string	the fleet's code (max 12 characters)
name	?string	the fleet's name (max 200 characters)
description	?string	the fleet's description
colour	?string	the fleet's colour as a hex string
root_system_id	?snowflake	the id of the root system to link to the fleet

Error Responses

Status Code	Description
404	Not found (fleet does not exist)
403	Forbidden (user lacks the MANAGE_FLEETS permission)

Subscribe to Fleet Work Items

POST /api/fleets/{id}/subscribe

Creates or updates a fleet subscription user for the current user. Subscribes the user to notifications for work items assigned to the fleet, optionally filtered by work item type and location. Requires membership in an organisation that owns the fleet, or an accepted fleet share.

JSON Params

Field	Type	Description
work_item_type_id	?snowflake	the id of the work item type to filter by (optional)
location_id	?snowflake	the id of the location to filter by (optional)

Error Responses

Status Code	Description
404	Not found (fleet does not exist)
404	Not found (work item type does not exist)
404	Not found (location does not exist)
403	Forbidden (user cannot view the fleet)

Unsubscribe from Fleet Work Items

POST /api/fleets/{id}/unsubscribe

Removes a fleet subscription user for the current user. Unsubscribes the user from notifications for work items assigned to the fleet. Requires membership in an organisation that owns the fleet, or an accepted fleet share.

JSON Params

Field	Type	Description
work_item_type_id	?snowflake	the id of the work item type to unsubscribe from (optional)
location_id	?snowflake	the id of the location to unsubscribe from (optional)

Error Responses

Status Code	Description
400	Bad request (subscription does not exist)
404	Not found (fleet does not exist)
404	Not found (work item type does not exist)
404	Not found (location does not exist)
403	Forbidden (user cannot view the fleet)

Create Fleet Share

POST /api/fleets/{id}/shares

Creates a fleet share inviting another user to view the fleet. The share can be scoped to a specific work item type and/or organisation. Requires the SHARE_FLEETS permission for the organisation that owns the fleet. If a work item type is specified, also requires the SHARE_WORKITEMS permission for the organisation that owns the work item type.

JSON Params

Field	Type	Description
user_id	snowflake	the id of the user to share with
organisation_id	?snowflake	the id of the organisation to share with (optional; must be an organisation the recipient belongs to)
work_item_type_id	?snowflake	the id of the work item type to scope the share to (optional)
scope	string	the scope of the share

Error Responses

Status Code	Description
400	Bad request (work item type not assignable to fleet)
400	Bad request (organisation not found)
403	Forbidden (user lacks the SHARE_FLEETS permission)
403	Forbidden (user lacks the SHARE_WORKITEMS permission)
403	Forbidden (recipient does not share an organisation with sharer)
404	Not found (fleet does not exist)
404	Not found (user does not exist)

Accept Fleet Share

POST /api/fleets/{id}/shares/{shareId}/accept

Accepts a pending fleet share. If the share specifies an organisation, the fleet will be added to that organisation (requires the MANAGE_FLEETS permission for the organisation). Returns the updated fleet share object.

Error Responses

Status Code	Description
400	Bad request (share or fleet does not exist, or share is not pending)

Reject Fleet Share

POST /api/fleets/{id}/shares/{shareId}/reject

Rejects a pending fleet share. The share status is set to Rejected.

Error Responses

Status Code	Description
400	Bad request (share or fleet does not exist, or share is not pending)

Remove Fleet Share

DELETE /api/fleets/{id}/shares/{shareId}

Removes a fleet share. The share status is set to Revoked. If the fleet was shared to an organisation and no other active shares exist for the same fleet and organisation, the fleet is removed from that organisation. Requires the SHARE_FLEETS permission for the organisation that owns the fleet.

Error Responses

Status Code	Description
400	Bad request (share does not exist)
403	Forbidden (user lacks the SHARE_FLEETS permission)
404	Not found (fleet does not exist)

List Fleet Shares

GET /api/fleets/{id}/shares

Returns an array of fleet share objects for the fleet. Includes shares with a status of Accepted or less. Each share includes the fleet, user, organisation, work item type, and shared-by user. Requires the SHARE_FLEETS permission for the organisation that owns the fleet.

Error Responses

Status Code	Description
403	Forbidden (user lacks the SHARE_FLEETS permission)
404	Not found (fleet does not exist)

List Organisation Fleet Shares

GET /organisations/{organisation.id}/fleets/{fleet.id}/shares

Returns an array of fleet share objects for a fleet within the organisation. Includes only accepted shares that are scoped to the organisation.

Error Responses

Status Code	Description
400	Bad request (organisation does not exist)
400	Bad request (fleet share does not exist)

List Fleet Assets

GET /fleets/{fleet.id}/assets

Returns an array of asset objects for the fleet.

Parameters

Field	Type	Description
type	?snowflake	the type of asset to return
root	?boolean	when set to true, only the root assets will be returned
active	?boolean	when set to true, only active assets will be returned

List Fleet Work Item Logs

GET /api/fleets/{id}/logs

Returns an array of work item log objects for work items assigned to the fleet. Logs are ordered by creation date (newest first). Requires membership in the organisation that owns the fleet.

Query Parameters

Field	Type	Description	Default
limit	?integer	maximum number of logs to return	50
start	?integer	number of logs to skip (pagination offset)	0
logged_at	?string	filter by log date/time using OData comparison operators	null

Error Responses

Status Code	Description
404	Not found (fleet does not exist)
403	Forbidden (user is not a member of the organisation)