directus/docs/reference/system/presets.md

description, readTime, pageClass

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

Preset

Presets hold the preferences of individual users of the platform. This allows Directus to show and maintain custom item listings and bookmarks for users of the app. Learn more about Presets.

The Preset Object

id uuid
Primary key of the preset.

bookmark string
The title of the bookmark. If this value is null, it's considered a preset instead of a bookmark.

user many-to-one
User this preset applies to. Many-to-one to users.

role many-to-one
Role this preset applies to. Many-to-one to users.

collection string
Collection this preset applies to.

search string
The search query used in the preset.

filters array
The filters used in the preset.

layout string
The layout used in this preset.

layout_query object
The item query used by the layout. This structure is based on the used layout.

layout_options object
The options used by the layout. This structure is based on the used layout.

{
	"id": 39,
	"bookmark": null,
	"user": "410b5772-e63f-4ae6-9ea2-39c3a31bd6ca",
	"role": null,
	"collection": "directus_activity",
	"search": null,
	"filters": [],
	"layout": "tabular",
	"layout_query": {
		"tabular": {
			"sort": "-timestamp",
			"fields": ["action", "collection", "timestamp", "user"],
			"page": 1
		}
	},
	"layout_options": {
		"tabular": {
			"widths": {
				"action": 100,
				"collection": 210,
				"timestamp": 240,
				"user": 240
			}
		}
	}
}

List Presets

List all presets that exist in Directus.

::: tip Permissions

The data returned in this endpoint will be filtered based on the user's permissions. For example, presets for a role other than the current user's role won't be returned.

:::

Request

GET /presets

SEARCH /presets

POST /graphql/system

type Query {
	presets: [directus_presets]
}

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

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

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

Learn more about SEARCH ->

Query Parameters

Supports all global query parameters.

Response

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

Example

GET /presets

SEARCH /presets

POST /graphql/system

query {
	presets {
		id
		user
	}
}

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

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

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

Retrieve a preset

List an existing preset by primary key.

Request

GET /presets/:id

POST /graphql/system

type Query {
	presets_by_id(id: ID!): directus_presets
}

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

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

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

Query Parameters

Supports all global query parameters.

Response

Returns the requested preset object.

Example

GET /presets/42

POST /graphql/system

query {
	presets_by_id(id: 42) {
		id
		user
	}
}

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

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

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

Create a Preset

Create a new preset.

Request

POST /presets

{
	"preset_field_1": "value_1",
	"preset_field_2": "value_2",
	"preset_field_3": "value_3"
}

POST /graphql/system

type Mutation {
	create_presets_item(data: create_directus_presets_input!): directus_presets
}

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

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

const result = await client.request(
	createPreset({
		preset_field_1: 'value_1',
		preset_field_2: 'value_2',
	})
);

Query Parameters

Supports all global query parameters.

Request Body

A partial preset object.

Response

Returns the preset object for the created preset.

Example

POST /presets

{
	"user": "410b5772-e63f-4ae6-9ea2-39c3a31bd6ca",
	"layout": "cards",
	"search": "Directus"
}

POST /graphql/system

mutation {
	create_presets_item(data: { user: "410b5772-e63f-4ae6-9ea2-39c3a31bd6ca", layout: "cards", search: "Directus" }) {
		id
		user
	}
}

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

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

const result = await client.request(
	createPreset({
		collection: 'articles',
		layout: 'kanban',
	})
);

Create Multiple Presets

Create multiple new presets.

Request

POST /presets

[
	{
		"preset_1_field_1": "value_1",
		"preset_1_field_2": "value_2",
		"preset_1_field_3": "value_3"
	},
	{
		"preset_2_field_1": "value_1",
		"preset_2_field_2": "value_2",
		"preset_2_field_3": "value_3"
	}
]

POST /graphql/system

type Mutation {
	create_presets_items(data: [create_directus_presets_input!]!): [directus_presets]
}

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

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

const result = await client.request(
	createPresets([
		{
			preset_1_field_1: 'value_1',
			preset_1_field_2: 'value_2',
		},
		{
			preset_2_field_1: 'value_3',
			preset_2_field_2: 'value_4',
		},
	])
);

Query Parameters

Supports all global query parameters.

Request Body

An array of partial preset objects.

Response

Returns the preset object for the created preset.

Example

POST /presets

[
	{
		"collection": "directus_files",
		"user": "410b5772-e63f-4ae6-9ea2-39c3a31bd6ca",
		"layout": "cards",
		"search": "Directus"
	},
	{
		"collection": "articles",
		"user": "410b5772-e63f-4ae6-9ea2-39c3a31bd6ca",
		"layout": "tabular"
	}
]

POST /graphql/system

mutation {
	create_presets_items(
		data: [
			{
				collection: "directus_files"
				user: "410b5772-e63f-4ae6-9ea2-39c3a31bd6ca"
				layout: "cards"
				search: "Directus"
			}
			{ collection: "articles", user: "410b5772-e63f-4ae6-9ea2-39c3a31bd6ca", layout: "tabular" }
		]
	) {
		id
		user
	}
}

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

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

const result = await client.request(
	createPresets([
		{
			collection: 'articles',
			layout: 'kanban',
		},
		{
			collection: 'authors',
			layout: 'tabular',
		},
	])
);

Update a Preset

Update an existing preset.

Request

PATCH /presets/:id

{
	"preset_object_field": "value_1"
}

POST /graphql/system

type Mutation {
	update_presets_item(id: ID!, data: update_directus_presets_input): directus_presets
}

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

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

const result = await client.request(
	updatePreset('preset_id', {
		field: 'value',
	})
);

Query Parameters

Supports all global query parameters.

Request Body

A partial preset object.

Response

Returns the preset object for the updated preset.

Example

PATCH /presets/34

{
	"layout": "tabular"
}

POST /graphql/system

mutation {
	update_presets_item(id: 32, data: { layout: "tabular" }) {
		id
		user
	}
}

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

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

const result = await client.request(
	updatePreset('24', {
		layout: 'tabular',
	})
);

Update Multiple Presets

Update multiple existing presets.

Request

PATCH /presets

{
	"keys": ["preset_1_key", "preset_2_key"],
	"data": {
		"preset_object_field": "value_1"
	}
}

POST /graphql/system

type Mutation {
	update_presets_items(ids: [ID!]!, data: update_directus_presets_input): [directus_presets]
}

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

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

const result = await client.request(
	updatePresets(['preset_1_id', 'preset_2_id'], {
		field: 'value',
	})
);

Query Parameters

Supports all global query parameters.

Request Body

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

data Required
Any of the preset object's properties.

Response

Returns the preset objects for the updated presets.

Example

PATCH /presets

{
	"keys": [15, 64],
	"data": {
		"layout": "tabular"
	}
}

POST /graphql/system

mutation {
	update_presets_items(ids: [15, 64], data: { layout: "tabular" }) {
		id
		user
	}
}

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

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

const result = await client.request(
	updatePresets(['24', '34'], {
		layout: 'tabular',
	})
);

Delete a Preset

Delete an existing preset.

Request

DELETE /presets/:id

POST /graphql/system

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

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

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

const result = await client.request(deletePreset('preset_id'));

Response

Empty body.

Example

DELETE /presets/34

POST /graphql/system

mutation {
	delete_presets_item(id: 32) {
		id
	}
}

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

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

const result = await client.request(deletePreset('24'));

Delete Multiple Presets

Delete multiple existing presets.

Request

DELETE /presets

["preset_1_key", "preset_2_key", "preset_3_key"]

POST /graphql/system

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

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

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

const result = await client.request(deletePreset(['preset_1_id', 'preset_2_id']));

Request Body

An array of preset primary keys

Response

Empty body.

Example

DELETE /presets

[15, 251, 810]

POST /graphql/system

mutation {
	delete_presets_items(ids: [15, 251, 810]) {
		ids
	}
}

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

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

const result = await client.request(deletePreset(['24', '48']));