directus/docs/reference/system/flows.md

description, readTime, pageClass

description	readTime	pageClass
REST and GraphQL API documentation on the Flows collection in Directus.	5 min read	page-reference

Flows

Flows enable custom, event-driven data processing and task automation within Directus.

The Flow Object

id uuid
Primary key of the flow.

name string
Name for the flow.

icon string
Icon displayed in the Admin App for the flow.

color string
Color of the icon displayed in the Admin App for the flow.

note text
Short description displayed in the Admin App.

status string
Current status of the flow. One of active, inactive. Defaults to active when not specified.

trigger string
Type of trigger for the flow. One of hook, webhook, operation, schedule, manual.

options json
Options of the selected trigger for the flow.

accountability string
The permission used during the flow. One of $public, $trigger, $full, or UUID of a role.

date_created timestamp
Timestamp in ISO8601 when the flow was created.

user_created many-to-one
The user who created the flow. Many-to-one to users.

operation string
UUID of the operation connected to the trigger in the flow.

{
	"id": "2fab3b9d-0543-4b87-8a30-3c5ee66fedf1",
	"name": "My Flow",
	"icon": "bolt",
	"color": "#112233",
	"note": "Note for my flow",
	"status": "active",
	"trigger": "manual",
	"accountability": "$trigger",
	"date_created": "2022-05-11T13:14:52Z",
	"user_created": "12e62fd0-29c7-4fd3-b3d3-c7a39933e8af",
	"operation": "92e82998-e421-412f-a513-13701e83e4ce"
}

List Flows

List all flows that exist in Directus.

Request

GET /flows

SEARCH /flows

POST /graphql/system

type Query {
	flows: [directus_flows]
}

import { createDirectus } from '@directus/sdk';
import { rest, readFlows } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(readFlows(query));

Learn more about SEARCH ->

Query Parameters

Supports all global query parameters.

Response

An array of up to limit flow objects. If no items are available, data will be an empty array.

Example

GET /flows

SEARCH /flows

POST /graphql/system

query {
	flows {
		id
		name
		status
	}
}

import { createDirectus } from '@directus/sdk';
import { rest, readFlows } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	readFlows({
		fields: ['*'],
	})
);

Retrieve a flow

List an existing flow by primary key.

Request

GET /flows/:id

POST /graphql/system

type Query {
	flows_by_id(id: ID!): directus_flows
}

import { createDirectus } from '@directus/sdk';
import { rest, readFlow } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(readFlow('flow_id', query));

Query Parameters

Supports all global query parameters.

Response

Returns the requested flow object.

Example

GET /flows/2fc325fb-299b-4d20-a9e7-a34349dee8b2

POST /graphql/system

query {
	flows_by_id(id: "2fc325fb-299b-4d20-a9e7-a34349dee8b2") {
		id
		name
		status
	}
}

import { createDirectus } from '@directus/sdk';
import { rest, readFlow } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	readFlow('4c01419e-0797-4f43-b95e-cbaebd2ac118', {
		fields: ['*'],
	})
);

Create a Flow

Create a new flow.

Request

POST /flows

{
	"flow_object_field_1": "value_1",
	"flow_object_field_2": "value_2",
	"flow_object_field_3": "value_3"
}

POST /graphql/system

type Mutation {
	create_flows_item(data: create_directus_flows_input!): directus_flows
}

import { createDirectus } from '@directus/sdk';
import { rest, createFlow } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	createFlow({
		flow_field_1: 'value_1',
		flow_field_2: 'value_2',
	})
);

Query Parameters

Supports all global query parameters.

Request Body

A partial flow object.

Response

Returns the flow object for the created flow.

Example

POST /flows

{
	"name": "My Flow",
	"status": "active",
	"trigger": "manual"
}

POST /graphql/system

mutation {
	create_flows_item(data: { name: "My Flow", status: "active", trigger: "manual" }) {
		id
		name
		status
	}
}

import { createDirectus } from '@directus/sdk';
import { rest, createFlow } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	createFlow({
		name: 'Email on article published',
		trigger: 'operation',
	})
);

Create Multiple Flows

Create multiple new flows.

Request

POST /flows

[
	{
		"flow_1_field_1": "value_1",
		"flow_1_field_2": "value_2",
		"flow_1_field_3": "value_3"
	},
	{
		"flow_2_field_1": "value_4",
		"flow_2_field_2": "value_5",
		"flow_2_field_3": "value_6"
	}
]

POST /graphql/system

type Mutation {
	create_flows_items(data: [create_directus_flows_input!]!): [directus_flows]
}

import { createDirectus } from '@directus/sdk';
import { rest, createFlows } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	createFlows([
		{
			flow_1_field_1: 'value_1',
			flow_1_field_2: 'value_2',
		},
		{
			flow_2_field_1: 'value_3',
			flow_2_field_2: 'value_4',
		},
	])
);

Query Parameters

Supports all global query parameters.

Request Body

An array of partial flow objects.

Response

Returns the flow object for the created flow.

Example

POST /flows

[
	{
		"name": "My Flow",
		"status": "active",
		"trigger": "manual"
	},
	{
		"name": "Another Flow",
		"status": "active",
		"trigger": "webhook"
	}
]

POST /graphql/system

mutation {
	create_flows_items(
		data: [
			{ name: "My Flow", status: "active", trigger: "manual" }
			{ name: "Another Flow", status: "active", trigger: "webhook" }
		]
	) {
		id
		name
		status
	}
}

import { createDirectus } from '@directus/sdk';
import { rest, createFlows } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	createFlows([
		{
			name: 'Email on article published',
			trigger: 'operation',
		},
		{
			name: 'Archive articles after 12 months',
			trigger: 'schedule',
		},
	])
);

Update a Flow

Update an existing flow.

Request

PATCH /flows/:id

{
	"flow_object_field": "value_1"
}

POST /graphql/system

type Mutation {
	update_flows_item(id: ID!, data: update_directus_flows_input): directus_flows
}

import { createDirectus } from '@directus/sdk';
import { rest, updateFlow } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	updateFlow('flow_id', {
		flow_field: 'value',
	})
);

Query Parameters

Supports all global query parameters.

Request Body

A partial flow object.

Response

Returns the flow object for the updated flow.

Example

PATCH /flows/2fc325fb-299b-4d20-a9e7-a34349dee8b2

{
	"name": "My Updated Flow"
}

POST /graphql/system

mutation {
	update_flows_item(id: "2fc325fb-299b-4d20-a9e7-a34349dee8b2", data: { name: "My Updated Flow" }) {
		id
		name
	}
}

import { createDirectus } from '@directus/sdk';
import { rest, updateFlow } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	updateFlow('53e623bd-cbeb-405d-8201-158af7e3ac83', {
		status: 'inactive',
	})
);

Update Multiple Flows

Update multiple existing flows.

Request

PATCH /flows

{
	"keys": ["flow_1_key", "flow_2_key"],
	"data": {
		"flow_object_field": "value_1"
	}
}

POST /graphql/system

type Mutation {
	update_flows_items(ids: [ID!]!, data: update_directus_flows_input): [directus_flows]
}

import { createDirectus } from '@directus/sdk';
import { rest, updateFlows } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	updateFlows(['flow_1_id', 'flow_2_id'], {
		flow_field: 'value',
	})
);

Query Parameters

Supports all global query parameters.

Request Body

keys Required
Array of primary keys of the flows you'd like to update.

data Required
Any of the flow object's properties.

Response

Returns the flow objects for the updated flows.

Example

PATCH /flows

{
	"keys": ["3f2facab-7f05-4ee8-a7a3-d8b9c634a1fc", "7259bfa8-3786-45c6-8c08-cc688e7ba229"],
	"data": {
		"status": "inactive"
	}
}

POST /graphql/system

mutation {
	update_flows_items(
		ids: ["3f2facab-7f05-4ee8-a7a3-d8b9c634a1fc", "7259bfa8-3786-45c6-8c08-cc688e7ba229"]
		data: { status: "inactive" }
	) {
		id
		name
		status
	}
}

import { createDirectus } from '@directus/sdk';
import { rest, updateFlows } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	updateFlows(['53e623bd-cbeb-405d-8201-158af7e3ac83', '0ae04fb7-0f4e-4b5d-be2b-a166c4ee16e4'], {
		status: 'inactive',
	})
);

Delete a Flow

Delete an existing flow.

Request

DELETE /flows/:id

POST /graphql/system

type Mutation {
	delete_flows_item(id: ID!): delete_one
}

import { createDirectus } from '@directus/sdk';
import { rest, deleteFlow } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(deleteFlow('flow_id'));

Response

Empty body.

Example

DELETE /flows/12204ee2-2c82-4d9a-b044-2f4842a11dba

POST /graphql/system

mutation {
	delete_flows_item(id: "12204ee2-2c82-4d9a-b044-2f4842a11dba") {
		id
	}
}

import { createDirectus } from '@directus/sdk';
import { rest, deleteFlow } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(deleteFlow('53e623bd-cbeb-405d-8201-158af7e3ac83'));

Delete Multiple Flows

Delete multiple existing flows.

Request

DELETE /flows

["flow_1_key", "flow_2_key", "flow_3_key"]

POST /graphql/system

type Mutation {
	delete_flows_items(ids: [ID!]!): delete_many
}

import { createDirectus } from '@directus/sdk';
import { rest, deleteFlows } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(deleteFlows(['flow_1_id', 'flow_2_id']));

Request Body

An array of flows primary keys

Response

Empty body.

Example

DELETE /flows

["25821236-8c2a-4f89-8fdc-c7d01f35877d", "02b9486e-4273-4fd5-b94b-e18fd923d1ed", "7d62f1e9-a83f-407b-84f8-1c184f014501"]

POST /graphql/system

mutation {
	delete_flows_items(
		ids: [
			"25821236-8c2a-4f89-8fdc-c7d01f35877d"
			"02b9486e-4273-4fd5-b94b-e18fd923d1ed"
			"7d62f1e9-a83f-407b-84f8-1c184f014501"
		]
	) {
		ids
	}
}

import { createDirectus } from '@directus/sdk';
import { rest, deleteFlows } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	deleteFlows(['53e623bd-cbeb-405d-8201-158af7e3ac83', '0ae04fb7-0f4e-4b5d-be2b-a166c4ee16e4'])
);

Flow with GET webhook trigger

Start a flow with GET webhook trigger.

Request

GET /flows/trigger/:flow_uuid

import { createDirectus } from '@directus/sdk';
import { rest, triggerFlow } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	triggerFlow('GET', 'flow_id', {
		fields: '*',
	})
);

Response

Result of the flow, if any.

Example

GET /flows/trigger/202a940b-a00b-47df-b832-369c53f13122 // Payload here

import { createDirectus } from '@directus/sdk';
import { rest, triggerFlow } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	triggerFlow('GET', '90a0fdd5-e760-4b4c-ac22-c14d48d44f26', {
		fields: '*',
	})
);

Flow with POST webhook trigger

Start a flow with POST webhook trigger.

Request

POST /flows/trigger/:flow_uuid

import { createDirectus } from '@directus/sdk';
import { rest, triggerFlow } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	triggerFlow('POST', 'flow_id', {
		field: 'value', // Payload for webhook
	})
);

Request Body

Payload for the POST request.

Response

Result of the flow, if any.

Example

POST /flows/trigger/202a940b-a00b-47df-b832-369c53f13122 // Payload here

import { createDirectus } from '@directus/sdk';
import { rest, triggerFlow } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	triggerFlow('POST', '90a0fdd5-e760-4b4c-ac22-c14d48d44f26', {
		title: 'Created with flows and webhooks',
	})
);