Shares
List Shares
List all shares that exist in Directus.
Query Parameters
Control what fields are being returned in the object.
A limit on the number of objects that are returned.
How many items to skip when fetching data.
What metadata to return in the response.
How to sort the returned items. sort is a CSV of fields used to sort the fetched items. Sorting defaults to ascending (ASC) order but a minus sign (-) can be used to reverse this to descending (DESC) order. Fields are prioritized by their order in the CSV. You can also use a ? to sort randomly.
Select items in collection by given conditions.
Filter by items that contain the given search query in one of their fields.
Cursor for use in pagination. Often used in combination with limit.
Responses
Primary key of the share;
Custom (optional) name for the share.
Collection in which the current item is shared. Many-to-one to Collections.
Primary key of the item that's shared.
Role of which the share will inherit the permissions. Many-to-one to shares.
Optional password that's required to view this shared item.
Reference to the user who created this share. Many-to-one to Users.
When the share was created.
Optional timestamp that controls from what date/time the shared item can be viewed.
Optional timestamp that controls until what date/time the shared item can be viewed.
The number of times the shared item has been viewed.
The maximum number of times the shared item can be viewed.
Returns the total item count of the collection you're querying.
Returns the item count of the collection you're querying, taking the current filter/search parameters into account.
GET /shares
import { createDirectus, rest, readShares } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(readShares(query_object));
type Query {
shares: [directus_shares]
}
{
"data": [
{
"id": "3a606c3e-9d4d-4556-b7bb-f00860613da3",
"name": "My Share",
"collection": "articles",
"item": "1",
"role": "2b34fba4-a6cb-49f4-a070-2daee7ac44f0",
"password": "**********",
"user_created": "b13072b7-73e9-4904-89e0-34aaf4403766",
"date_created": "2023-01-25T19:16:49.009Z",
"date_start": "2023-01-26T17:00:00.000Z",
"date_end": "2023-01-28T17:00:00.000Z",
"times_used": 0,
"max_uses": 15
}
],
"meta": {}
}
Create Multiple Shares
Create multiple new shares.
Query Parameters
Control what fields are being returned in the object.
A limit on the number of objects that are returned.
What metadata to return in the response.
How many items to skip when fetching data.
How to sort the returned items. sort is a CSV of fields used to sort the fetched items. Sorting defaults to ascending (ASC) order but a minus sign (-) can be used to reverse this to descending (DESC) order. Fields are prioritized by their order in the CSV. You can also use a ? to sort randomly.
Select items in collection by given conditions.
Filter by items that contain the given search query in one of their fields.
Request Body
Primary key of the share;
Custom (optional) name for the share.
Collection in which the current item is shared. Many-to-one to Collections.
Primary key of the item that's shared.
Role of which the share will inherit the permissions. Many-to-one to shares.
Optional password that's required to view this shared item.
Reference to the user who created this share. Many-to-one to Users.
When the share was created.
Optional timestamp that controls from what date/time the shared item can be viewed.
Optional timestamp that controls until what date/time the shared item can be viewed.
The number of times the shared item has been viewed.
The maximum number of times the shared item can be viewed.
Responses
Primary key of the share;
Custom (optional) name for the share.
Collection in which the current item is shared. Many-to-one to Collections.
Primary key of the item that's shared.
Role of which the share will inherit the permissions. Many-to-one to shares.
Optional password that's required to view this shared item.
Reference to the user who created this share. Many-to-one to Users.
When the share was created.
Optional timestamp that controls from what date/time the shared item can be viewed.
Optional timestamp that controls until what date/time the shared item can be viewed.
The number of times the shared item has been viewed.
The maximum number of times the shared item can be viewed.
Returns the total item count of the collection you're querying.
Returns the item count of the collection you're querying, taking the current filter/search parameters into account.
POST /shares
import { createDirectus, rest, createShare } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(createShares(share_object_array));
type Mutation {
create_shares_items(data: [create_directus_shares_input!]!): [directus_shares]
}
{
"data": [
{
"id": "3a606c3e-9d4d-4556-b7bb-f00860613da3",
"name": "My Share",
"collection": "articles",
"item": "1",
"role": "2b34fba4-a6cb-49f4-a070-2daee7ac44f0",
"password": "**********",
"user_created": "b13072b7-73e9-4904-89e0-34aaf4403766",
"date_created": "2023-01-25T19:16:49.009Z",
"date_start": "2023-01-26T17:00:00.000Z",
"date_end": "2023-01-28T17:00:00.000Z",
"times_used": 0,
"max_uses": 15
}
],
"meta": {}
}
Delete Multiple Shares
Delete multiple existing shares.
Responses
DELETE /shares
import { createDirectus, rest, deleteShares } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(deleteShares(share_id_array));
type Mutation {
delete_shares_items(ids: [ID!]!): delete_many
}
Update Multiple Shares
Update multiple shares at the same time.
Query Parameters
Control what fields are being returned in the object.
A limit on the number of objects that are returned.
What metadata to return in the response.
How many items to skip when fetching data.
How to sort the returned items. sort is a CSV of fields used to sort the fetched items. Sorting defaults to ascending (ASC) order but a minus sign (-) can be used to reverse this to descending (DESC) order. Fields are prioritized by their order in the CSV. You can also use a ? to sort randomly.
Select items in collection by given conditions.
Filter by items that contain the given search query in one of their fields.
Request Body
Primary key of the share;
Custom (optional) name for the share.
Collection in which the current item is shared. Many-to-one to Collections.
Primary key of the item that's shared.
Role of which the share will inherit the permissions. Many-to-one to shares.
Optional password that's required to view this shared item.
Reference to the user who created this share. Many-to-one to Users.
When the share was created.
Optional timestamp that controls from what date/time the shared item can be viewed.
Optional timestamp that controls until what date/time the shared item can be viewed.
The number of times the shared item has been viewed.
The maximum number of times the shared item can be viewed.
Responses
Primary key of the share;
Custom (optional) name for the share.
Collection in which the current item is shared. Many-to-one to Collections.
Primary key of the item that's shared.
Role of which the share will inherit the permissions. Many-to-one to shares.
Optional password that's required to view this shared item.
Reference to the user who created this share. Many-to-one to Users.
When the share was created.
Optional timestamp that controls from what date/time the shared item can be viewed.
Optional timestamp that controls until what date/time the shared item can be viewed.
The number of times the shared item has been viewed.
The maximum number of times the shared item can be viewed.
Returns the total item count of the collection you're querying.
Returns the item count of the collection you're querying, taking the current filter/search parameters into account.
PATCH /shares
import { createDirectus, rest, updateShares } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(updateShares(share_id_array, partial_share_object));
type Mutation {
update_shares_items(ids: [ID!]!, data: update_directus_shares_input): [directus_shares]
}
{
"data": [
{
"id": "3a606c3e-9d4d-4556-b7bb-f00860613da3",
"name": "My Share",
"collection": "articles",
"item": "1",
"role": "2b34fba4-a6cb-49f4-a070-2daee7ac44f0",
"password": "**********",
"user_created": "b13072b7-73e9-4904-89e0-34aaf4403766",
"date_created": "2023-01-25T19:16:49.009Z",
"date_start": "2023-01-26T17:00:00.000Z",
"date_end": "2023-01-28T17:00:00.000Z",
"times_used": 0,
"max_uses": 15
}
],
"meta": {}
}
Create a Share
Create a new share.
Query Parameters
Control what fields are being returned in the object.
What metadata to return in the response.
Request Body
Primary key of the share;
Custom (optional) name for the share.
Collection in which the current item is shared. Many-to-one to Collections.
Primary key of the item that's shared.
Role of which the share will inherit the permissions. Many-to-one to shares.
Optional password that's required to view this shared item.
Reference to the user who created this share. Many-to-one to Users.
When the share was created.
Optional timestamp that controls from what date/time the shared item can be viewed.
Optional timestamp that controls until what date/time the shared item can be viewed.
The number of times the shared item has been viewed.
The maximum number of times the shared item can be viewed.
Responses
Primary key of the share;
Custom (optional) name for the share.
Collection in which the current item is shared. Many-to-one to Collections.
Primary key of the item that's shared.
Role of which the share will inherit the permissions. Many-to-one to shares.
Optional password that's required to view this shared item.
Reference to the user who created this share. Many-to-one to Users.
When the share was created.
Optional timestamp that controls from what date/time the shared item can be viewed.
Optional timestamp that controls until what date/time the shared item can be viewed.
The number of times the shared item has been viewed.
The maximum number of times the shared item can be viewed.
POST /shares
import { createDirectus, rest, createShare } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(createShare(share_object));
type Mutation {
create_shares_item(data: create_directus_shares_input!): directus_shares
}
{
"data": {
"id": "3a606c3e-9d4d-4556-b7bb-f00860613da3",
"name": "My Share",
"collection": "articles",
"item": "1",
"role": "2b34fba4-a6cb-49f4-a070-2daee7ac44f0",
"password": "**********",
"user_created": "b13072b7-73e9-4904-89e0-34aaf4403766",
"date_created": "2023-01-25T19:16:49.009Z",
"date_start": "2023-01-26T17:00:00.000Z",
"date_end": "2023-01-28T17:00:00.000Z",
"times_used": 0,
"max_uses": 15
}
}
Retrieve a Share
List an existing share by primary key.
Query Parameters
Unique identifier of the share.
Control what fields are being returned in the object.
What metadata to return in the response.
Responses
Primary key of the share;
Custom (optional) name for the share.
Collection in which the current item is shared. Many-to-one to Collections.
Primary key of the item that's shared.
Role of which the share will inherit the permissions. Many-to-one to shares.
Optional password that's required to view this shared item.
Reference to the user who created this share. Many-to-one to Users.
When the share was created.
Optional timestamp that controls from what date/time the shared item can be viewed.
Optional timestamp that controls until what date/time the shared item can be viewed.
The number of times the shared item has been viewed.
The maximum number of times the shared item can be viewed.
GET /shares/{id}
import { createDirectus, rest, readShare } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(readShare(share_id, query_object));
type Query {
shares_by_id(id: ID!): directus_shares
}
{
"data": {
"id": "3a606c3e-9d4d-4556-b7bb-f00860613da3",
"name": "My Share",
"collection": "articles",
"item": "1",
"role": "2b34fba4-a6cb-49f4-a070-2daee7ac44f0",
"password": "**********",
"user_created": "b13072b7-73e9-4904-89e0-34aaf4403766",
"date_created": "2023-01-25T19:16:49.009Z",
"date_start": "2023-01-26T17:00:00.000Z",
"date_end": "2023-01-28T17:00:00.000Z",
"times_used": 0,
"max_uses": 15
}
}
Delete a Share
Delete an existing share.
Query Parameters
Unique identifier of the share.
Responses
DELETE /shares/{id}
import { createDirectus, rest, deleteShare } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(deleteShare(share_id));
type Mutation {
delete_shares_item(id: ID!): delete_one
}
Update a Share
Update an existing share.
Query Parameters
Unique identifier of the share.
Control what fields are being returned in the object.
What metadata to return in the response.
Request Body
Primary key of the share;
Custom (optional) name for the share.
Collection in which the current item is shared. Many-to-one to Collections.
Primary key of the item that's shared.
Role of which the share will inherit the permissions. Many-to-one to shares.
Optional password that's required to view this shared item.
Reference to the user who created this share. Many-to-one to Users.
When the share was created.
Optional timestamp that controls from what date/time the shared item can be viewed.
Optional timestamp that controls until what date/time the shared item can be viewed.
The number of times the shared item has been viewed.
The maximum number of times the shared item can be viewed.
Responses
Primary key of the share;
Custom (optional) name for the share.
Collection in which the current item is shared. Many-to-one to Collections.
Primary key of the item that's shared.
Role of which the share will inherit the permissions. Many-to-one to shares.
Optional password that's required to view this shared item.
Reference to the user who created this share. Many-to-one to Users.
When the share was created.
Optional timestamp that controls from what date/time the shared item can be viewed.
Optional timestamp that controls until what date/time the shared item can be viewed.
The number of times the shared item has been viewed.
The maximum number of times the shared item can be viewed.
PATCH /shares/{id}
import { createDirectus, rest, updateShare } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(updateShare(share_id, partial_share_object));
type Mutation {
update_shares_item(id: ID!, data: update_directus_shares_input): directus_shares
}
{
"data": {
"id": "3a606c3e-9d4d-4556-b7bb-f00860613da3",
"name": "My Share",
"collection": "articles",
"item": "1",
"role": "2b34fba4-a6cb-49f4-a070-2daee7ac44f0",
"password": "**********",
"user_created": "b13072b7-73e9-4904-89e0-34aaf4403766",
"date_created": "2023-01-25T19:16:49.009Z",
"date_start": "2023-01-26T17:00:00.000Z",
"date_end": "2023-01-28T17:00:00.000Z",
"times_used": 0,
"max_uses": 15
}
}
Authenticate a Share
Authenticate as a share user. Shares work by returning a token, as it is the case with the regular login endpoint. These tokens are limited to a permissions set that only allows access to the item that was shared, and any relationally linked items that that associated role has access to. This means that all regular endpoints can be used with the token returned by this endpoint.
Request Body
Primary key of the share you're authenticating against.
Password for the share, if one is configured.
Whether to retrieve the refresh token in the JSON response, or in a httpOnly cookie.
Responses
Temporary access token to be used in follow-up requests. Note: if you used session as the mode in the request, the access token won\u0027t be returned in the JSON.
How long before the access token will expire. Value is in milliseconds.
The token that can be used to retrieve a new access token through /auth/refresh. Note: if you used cookie or session as the mode in the request, the refresh token won\u0027t be returned in the JSON.
POST /shares/auth
import { createDirectus, rest, authenticateShare } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(authenticateShare('share_key', 'password'));
// Not currently available in GraphQL
{
"data": {
"access_token": "eyJhbGciOiJI...",
"expires": 900,
"refresh_token": "yuOJkjdPXMd..."
}
}
Get Share Public Info
Allows unauthenticated users to retrieve information about the share.
Query Parameters
Unique identifier of the share.
Responses
Primary key of the share;
Custom (optional) name for the share.
Collection in which the current item is shared. Many-to-one to Collections.
Primary key of the item that's shared.
Role of which the share will inherit the permissions. Many-to-one to shares.
Optional password that's required to view this shared item.
Reference to the user who created this share. Many-to-one to Users.
When the share was created.
Optional timestamp that controls from what date/time the shared item can be viewed.
Optional timestamp that controls until what date/time the shared item can be viewed.
The number of times the shared item has been viewed.
The maximum number of times the shared item can be viewed.
GET /shares/info/{id}
import { createDirectus, rest, readShareInfo } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(readShareInfo(share_id));
// Not currently available in GraphQL
{
"data": {
"id": "3a606c3e-9d4d-4556-b7bb-f00860613da3",
"name": "My Share",
"collection": "articles",
"item": "1",
"role": "2b34fba4-a6cb-49f4-a070-2daee7ac44f0",
"password": "**********",
"user_created": "b13072b7-73e9-4904-89e0-34aaf4403766",
"date_created": "2023-01-25T19:16:49.009Z",
"date_start": "2023-01-26T17:00:00.000Z",
"date_end": "2023-01-28T17:00:00.000Z",
"times_used": 0,
"max_uses": 15
}
}