directus/docs/reference/system/utilities.md

description, readTime, pageClass

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

Utilities

Utilities are the various helper endpoints located within the API.

Generate a Hash

Generate a hash for a given string.

Request

POST /utils/hash/generate

{
	"string": "hash"
}

POST /graphql/system

type Mutation {
	utils_hash_generate(string: String!): String
}

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

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

const result = await client.request(generateHash('string'));

Request Body

string Required
String to hash.

Response

Hashed string.

Example

POST /utils/hash/generate

{
	"string": "Hello World!"
}

mutation {
	utils_hash_generate(string: "Hello World!")
}

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

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

const result = await client.request(generateHash('test string to hash'));

Verify a Hash

Verify a string with a hash.

Request

POST /utils/hash/verify

{
	"string": "test_string",
	"hash": "hash"
}

POST /graphql/system

type Mutation {
	utils_hash_verify(hash: String!, string: String!): Boolean
}

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

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

const result = await client.request(verifyHash('string_to_verify', 'hash'));

Request Body

string Required
Source string.

hash Required
Hash you want to verify against.

Response

Boolean.

Example

POST /utils/hash/verify

{
	"string": "Hello World!",
	"hash": "$arg...fEfM"
}

POST /graphql/system

mutation {
	utils_hash_verify(hash: "$arg...fEfM", string: "Hello World!")
}

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

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

const result = await client.request(
	verifyHash(
		'test_string',
		'$argon2id$v=19$m=65536,t=3,p=4$c81PPca80cdIbclXlL1PFg$+EKJsuXlkleP2wFGsEmA7Xu56wEqVKHeDXRrTLIAoJg'
	)
);

Manually Sort Items in Collection

If a collection has a sort field, this util can be used to move items in that manual order.

Request

POST /utils/sort/articles

{
	"item": "id_item_to_move",
	"to": "id_item_moving_to"
}

POST /graphql/system

type Mutation {
	utils_sort(collection: String!, item: ID!, to: ID!): Boolean
}

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

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

const result = await client.request(utilitySort('collection_name', 'id_item_to_move', 'id_item_moving_to'));

Request Body

item Required
Primary key of the item you're moving in the collection.

to Required
Primary key of the item you're moving the source item too.

Response

Empty body.

Example

POST /utils/sort/articles

{
	"item": 16,
	"to": 51
}

POST /graphql/system

mutation {
	utils_sort(collection: "articles", item: 16, to: 51)
}

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

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

const result = await client.request(utilitySort('things', '2', '4'));

Import Data from File

Import multiple records from a JSON or CSV file into a collection.

Request

POST /utils/import/:collection

Body must be formatted as a multipart/form-data with a file property.

// Not currently available in GraphQL

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

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

const formData = new FormData();
formData.append('file', raw_file);

const result = await client.request(utilsImport(formData));

The import endpoint expects the file structure to match the export query parameter. For JSON, this is an array of objects, where every object is an item. For CSV, the first line has to be the columns header.

Request Body

Send the file in a multipart/form-data request. See Upload a File for more information.

Response

Empty body.

Export Data to a File

Export a larger data set to a file in the File Library

Request

POST /utils/export/:collection

{
	"query": {
		"filter": {
			"status": {
				"_eq": "published"
			}
		}
	},
	"file": {
		"folder": "34e95c19-cc50-42f2-83c8-b97616ac2390"
	}
}

// Not currently available in GraphQL

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

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

const result = await client.request(
	utilsExport(
		'collection_name',
		'file_format',
		{
			query_type: {
				field: {
					query_operation: 'value',
				},
			},
		},
		{
			file: {
				file_field: 'value',
			},
		}
	)
);

Query Parameters

Doesn't use any query parameters.

Request Body

format Required
What file format to save the export to. One of csv, json, xml, yaml.

query Required
The query object to use for the export. Supports the global query parameters.

file File Object
Partial file object to tweak where / how the export file is saved.

Response

Empty body

Example

POST /utils/export/articles

{
	"query": {
		"filter": {
			"status": {
				"_eq": "published"
			}
		}
	},
	"file": {
		"folder": "34e95c19-cc50-42f2-83c8-b97616ac2390"
	}
}

// Not currently available in GraphQL

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

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

const result = await client.request(
	utilsExport(
		'articles',
		'json',
		{
			filter: {
				status: {
					_eq: 'published',
				},
			},
		},
		{
			file: {
				folder: '34e95c19-cc50-42f2-83c8-b97616ac2390',
			},
		}
	)
);

Clear the Internal Cache

Resets both the data and schema cache of Directus. This endpoint is only available to admin users.

POST /utils/cache/clear

POST /graphql/system

mutation {
	utils_cache_clear
}

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

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

const result = await client.request(clearCache());

Returns

Empty body