Actions

You can execute CRUD actions over Directus' WebSockets interface.

::callout{icon="material-symbols:info-outline"} GraphQL
The GraphQL Subscriptions specification does not support CRUD actions. This guide is only suitable for WebSockets connections not using GraphQL. ::

Read Items

{
	"type": "items",
	"action": "read",
	"collection": "your_collection_name",
	"id": "single_item_id"
}

In return, you will receive a message with the specified item:

{
	"type": "items",
	"data": {
		// ...
	}
}

Read Multiple Items

Instead of using an id property, you can use an ids property with an array of item IDs you'd like to return, or omit it to return all items in the specified collection. When returning multiple items, data will be an array of objects.

Create Items

{
	"type": "items",
	"action": "create",
	"collection": "your_collection_name",
	"data": {
		// ...
	}
}

In return, you will receive a message with the newly-created item:

{
	"type": "items",
	"data": {
		// ...
	}
}

Create Multiple Items

Instead of using an object as the value of data, you can provide an array of objects to create multiple items at once. The returned payload will also contain an array.

Update Items

{
	"type": "items",
	"action": "update",
	"collection": "your_collection_name",
	"id": "single_item_id",
	"data": {
		// ...
	}
}

Regardless of how many items are updated, the data in the returned object will always be an array.

{
	"type": "subscription",
	"event": "update",
	"data": [
		// ...
	]
}

Update Multiple Items

Instead of using an id property, you can use an ids property with an array of item IDs to update multiple items at a time.

Delete Items

{
	"type": "items",
	"action": "delete",
	"collection": "your_collection_name",
	"id": "single_item_id"
}

Regardless of how many items are updated, the data in the returned data will always be an array containing all IDs from deleted items:

{
	"type": "items",
	"event": "delete",
	"data": ["single_item_id", "single_item_id_2"]
}

Delete Multiple Items

Instead of using an id property, you can use an ids property with an array of item IDs to delete multiple items at a time.

You can also use delete items based on a provided query property. To delete all items, provide an empty query object.

Operations With Queries

For non-delete operations, all fields that the user has access to are returned by default. You can add an optional query property along with any of the global query parameters to change the returned data.

When running a delete operation, the items matching the query property will be deleted.

Use UIDs To Better Understand Responses

All messages sent over WebSockets can optionally include a uid property with an arbitrary string and will be echoed in the response. This allows you to identify which request a given response is related to. For example:

{
	"type": "items",
	"action": "read",
	"collection": "your_collection_name",
	"query": {
		"sort": "date_created"
	},
	"uid": "sorted_latest_first"
}

The response will include the same uid:

{
	"type": "items",
	"data": {
		// ...
	},
	"uid": "sorted_latest_first"
}