Shares
Shares are a way to publicly share an otherwise private item.
The Share Object
id uuid
Primary key of the share.
name string
Custom (optional) name for the share.
collection many-to-one
Collection in which the current item is shared. Many-to-one to Collections.
item string
Primary key of the item that's shared.
role many-to-one
Share of which the share will inherit the permissions.
password hash
Optional password that's required to view this shared item.
user_created many-to-one
Reference to the user who created this share. Many-to-one to Users.
date_created timestamp
When the share was created.
date_start timestamp
Optional timestamp that controls from what date/time the shared item can be viewed.
date_end timestamp
Optional timestamp that controls until what date/time the shared item can be viewed.
times_used number
The number of times the shared item has been viewed.
max_uses number
The maximum number of times the shared item can be viewed.
{
"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
}{
"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
}List Shares
List all shares that exist in Directus.
Request
Query Parameters
Supports all global query parameters.
Response
An array of up to limit share objects. If no items are available, data will be an empty array.
Example
Retrieve a Share
List an existing share by primary key.
Query Parameters
Supports all global query parameters.
Response
Returns the requested share object.
Example
Create a Share
Create a new share.
Request
Query Parameters
Supports all global query parameters.
Request Body
A partial share object.
Response
Returns the share object for the created share.
Example
Create Multiple Shares
Create multiple new shares.
Request
Query Parameters
Supports all global query parameters.
Request Body
An array of partial share objects.
Response
Returns the share objects for the created shares.
Example
Update a Share
Update an existing share.
Request
Query Parameters
Supports all global query parameters.
Request Body
A partial share object.
Response
Returns the share object for the updated share.
Example
Update Multiple Shares
Update multiple existing shares.
Request
Query Parameters
Supports all global query parameters.
Request Body
keys Required
Array of primary keys of the shares you'd like to update.
data Required
Any of the share object's properties.
Response
Returns the share objects for the updated shares.
Example
Delete a Share
Delete an existing share.
Request
Response
Empty body.
Example
Delete Multiple Shares
Delete multiple existing shares.
Request
Request Body
An array of share primary keys
Response
Empty body.
Example
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
Request Body
share Required
Primary key of the share you're authenticating against.
password string
Password for the share, if one is configured.
mode
Whether to retrieve the refresh token in the JSON response, or in a httpOnly cookie. One of json, cookie or session. Defaults to json.
Response
access_token string
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't be returned in the JSON.
expires integer
How long before the access token will expire. Value is in milliseconds.
refresh_token string
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't be returned in the JSON.
Example
Send a Share by Email
Sends an email to the provided email addresses with a link to the share.
Request
Request Body
share Required
Primary key of the share you're inviting people to.
emails array
Array of email strings to send the share link to.
Response
Empty body.
Example
Get Share Public Info
Allows unauthenticated users to retrieve information about the share.
Response
The share objects for the given UUID, if it's still valid.