---
description: REST and GraphQL API documentation on using Shares in Directus
readTime: 5 min read
pageClass: page-reference
---

# 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.

```json
{
	"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

<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
<template #rest>

`GET /shares`

`SEARCH /shares`

If using SEARCH you can provide a [query object](/reference/query) as the body of your request.

[Learn more about SEARCH ->](/reference/introduction#search-http-method)

</template>
<template #graphql>

POST /graphql/system

```graphql
type Query {
	shares: [directus_shares]
}
```

</template>
<template #sdk>

```js
import { createDirectus, rest, readShares } from '@directus/sdk';

const client = createDirectus('directus_project_url').with(rest());

const result = await client.request(readShares(query_object));
```

</template>
</SnippetToggler>

#### Query Parameters

Supports all [global query parameters](/reference/query).

### Response

An array of up to [limit](/reference/query#limit) [share objects](#the-share-object). If no items are available, data
will be an empty array.

### Example

<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
<template #rest>

`GET /shares`

`SEARCH /shares`

</template>
<template #graphql>

`POST /graphql/system`

```graphql
query {
	shares {
		id
		name
		collection
		item
	}
}
```

</template>
<template #sdk>

```js
import { createDirectus, rest, readShares } from '@directus/sdk';

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

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

</template>
</SnippetToggler>

## Retrieve a Share

List an existing share by primary key.

<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
<template #rest>

`GET /shares/:id`

</template>
<template #graphql>

`POST /graphql/system`

```graphql
type Query {
	shares_by_id(id: ID!): directus_shares
}
```

</template>
<template #sdk>

```js
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));
```

</template>
</SnippetToggler>

#### Query Parameters

Supports all [global query parameters](/reference/query).

### Response

Returns the requested [share object](#the-share-object).

### Example

<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
<template #rest>

`GET /shares/b4cb3b64-8580-4ad9-a099-eade6da24302`

</template>
<template #graphql>

`POST /graphql/system`

```graphql
query {
	shares_by_id(id: 2) {
		id
		name
		collection
		item
	}
}
```

</template>
<template #sdk>

```js
import { createDirectus, rest, readShare } from '@directus/sdk';

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

const result = await client.request(
	readShare('2f8c03c3-4988-4869-a1b3-318e0a4b9b9d', {
		fields: ['*'],
	})
);
```

</template>
</SnippetToggler>

## Create a Share

Create a new share.

### Request

<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
<template #rest>

`POST /shares`

Provide a [share object](#the-share-object) as the body of your request.

</template>
<template #graphql>

`POST /graphql/system`

```graphql
type Mutation {
	create_shares_item(data: create_directus_shares_input!): directus_shares
}
```

</template>
<template #sdk>

```js
import { createDirectus, rest, createShare } from '@directus/sdk';

const client = createDirectus('directus_project_url').with(rest());

const result = await client.request(createShare(share_object));
```

</template>
</SnippetToggler>

#### Query Parameters

Supports all [global query parameters](/reference/query).

#### Request Body

A partial [share object](#the-share-object).

### Response

Returns the [share object](#the-share-object) for the created share.

### Example

<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
<template #rest>

`POST /shares`

```json
{
	"name": "External Review",
	"collection": "articles",
	"item": "15",
	"max_uses": "5"
}
```

</template>
<template #graphql>

`POST /graphql/system`

```graphql
mutation {
	create_shares_item(data: { name: "External Review", collection: "articles", item: "15", max_uses: "5" }) {
		id
		name
		collection
		item
	}
}
```

</template>
<template #sdk>

```js
import { createDirectus, rest, createShare } from '@directus/sdk';

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

const result = await client.request(
	createShare({
		name: 'External Review',
		collection: 'articles',
		item: '22',
		max_uses: '5',
	})
);
```

</template>
</SnippetToggler>

## Create Multiple Shares

Create multiple new shares.

### Request

<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
<template #rest>

`POST /shares`

Provide an array of [share objects](#the-share-object) as the body of your request.

</template>
<template #graphql>

`POST /graphql/system`

```graphql
type Mutation {
	create_shares_items(data: [create_directus_shares_input!]!): [directus_shares]
}
```

</template>
<template #sdk>

```js
import { createDirectus, rest, createShares } from '@directus/sdk';

const client = createDirectus('directus_project_url').with(rest());

const result = await client.request(createShares(share_object_array));
```

</template>
</SnippetToggler>

#### Query Parameters

Supports all [global query parameters](/reference/query).

#### Request Body

An array of partial [share objects](#the-share-object).

### Response

Returns the [share objects](#the-share-object) for the created shares.

### Example

<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
<template #rest>

`POST /shares`

```json
[
	{
		"name": "External Review",
		"collection": "articles",
		"item": "15",
		"max_uses": "5"
	},
	{
		"name": "Early Access",
		"collection": "games",
		"item": "d50ffd6a-3b33-44a4-b3e6-1f0d1bca1254",
		"password": "EARLYACCESS2023"
	}
]
```

</template>
<template #graphql>

`POST /graphql/system`

```graphql
mutation {
	create_shares_items(
		data: [
			{ name: "External Review", collection: "articles", item: "15", max_uses: "5" }
			{
				name: "Early Access"
				collection: "games"
				item: "d50ffd6a-3b33-44a4-b3e6-1f0d1bca1254"
				password: "EARLYACCESS2023"
			}
		]
	) {
		id
		name
		collection
		item
	}
}
```

</template>
<template #sdk>

```js
import { createDirectus, rest, createShares } from '@directus/sdk';

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

const result = await client.request(
	createShares([
		{
			name: 'External Review',
			collection: 'articles',
			item: '25',
			max_uses: '5',
		},
		{
			name: 'Early Access',
			collection: 'articles',
			item: '26',
			password: 'EARLYACCESS2023',
		},
	])
);
```

</template>
</SnippetToggler>

## Update a Share

Update an existing share.

### Request

<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
<template #rest>

`PATCH /shares/:id`

Provide a partial [share objects](#the-share-object) as the body of your request.

</template>
<template #graphql>

`POST /graphql/system`

```graphql
type Mutation {
	update_shares_item(id: ID!, data: update_directus_shares_input): directus_shares
}
```

</template>
<template #sdk>

```js
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));
```

</template>
</SnippetToggler>

#### Query Parameters

Supports all [global query parameters](/reference/query).

#### Request Body

A partial [share object](#the-share-object).

### Response

Returns the [share object](#the-share-object) for the updated share.

### Example

<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
<template #rest>

`PATCH /shares/c86c2761-65d3-43c3-897f-6f74ad6a5bd7`

```json
{
	"max_uses": "30"
}
```

</template>
<template #graphql>

`POST /graphql/system`

```graphql
mutation {
	update_shares_item(id: "c86c2761-65d3-43c3-897f-6f74ad6a5bd7", data: { icon: "attractions" }) {
		id
		name
		collection
		item
	}
}
```

</template>
<template #sdk>

```js
import { createDirectus, rest, updateShare } from '@directus/sdk';

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

const result = await client.request(
	updateShare('2f8c03c3-4988-4869-a1b3-318e0a4b9b9d', {
		max_uses: 10,
	})
);
```

</template>
</SnippetToggler>

## Update Multiple Shares

Update multiple existing shares.

### Request

<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
<template #rest>

`PATCH /shares`

```json
{
	"keys": share_id_array,
	"data": partial_share_object
}
```

</template>
<template #graphql>

`POST /graphql/system`

```graphql
type Mutation {
	update_shares_items(ids: [ID!]!, data: update_directus_shares_input): [directus_shares]
}
```

</template>
<template #sdk>

```js
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));
```

</template>
</SnippetToggler>

#### Query Parameters

Supports all [global query parameters](/reference/query).

#### Request Body

`keys` **Required**\
Array of primary keys of the shares you'd like to update.

`data` **Required**\
Any of [the share object](#the-share-object)'s properties.

### Response

Returns the [share objects](#the-share-object) for the updated shares.

### Example

<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
<template #rest>

`PATCH /shares`

```json
{
	"keys": ["c86c2761-65d3-43c3-897f-6f74ad6a5bd7", "6fc3d5d3-a37b-4da8-a2f4-ed62ad5abe03"],
	"data": {
		"date_end": "2023-02-14T17:00:00Z"
	}
}
```

</template>
<template #graphql>

`POST /graphql/system`

```graphql
mutation {
	update_shares_items(
		ids: ["c86c2761-65d3-43c3-897f-6f74ad6a5bd7", "6fc3d5d3-a37b-4da8-a2f4-ed62ad5abe03"]
		data: { date_end: "2023-02-14T17:00:00Z" }
	) {
		id
		name
		collection
		item
	}
}
```

</template>
<template #sdk>

```js
import { createDirectus, rest, updateShare } from '@directus/sdk';

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

const result = await client.request(
	updateShares(['2f8c03c3-4988-4869-a1b3-318e0a4b9b9d', '153cdb59-7868-4187-8696-372aa07537f4'], {
		max_uses: 10,
	})
);
```

</template>
</SnippetToggler>

## Delete a Share

Delete an existing share.

### Request

<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
<template #rest>

`DELETE /shares/:id`

</template>
<template #graphql>

`POST /graphql/system`

```graphql
type Mutation {
	delete_shares_item(id: ID!): delete_one
}
```

</template>
<template #sdk>

```js
import { createDirectus, rest, deleteShare } from '@directus/sdk';

const client = createDirectus('directus_project_url').with(rest());

const result = await client.request(deleteShare(share_id));
```

</template>
</SnippetToggler>

### Response

Empty body.

### Example

<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
<template #rest>

`DELETE /shares/c86c2761-65d3-43c3-897f-6f74ad6a5bd7`

</template>
<template #graphql>

`POST /graphql/system`

```graphql
mutation {
	delete_shares_item(id: "c86c2761-65d3-43c3-897f-6f74ad6a5bd7") {
		id
	}
}
```

</template>
<template #sdk>

```js
import { createDirectus, rest, deleteShare } from '@directus/sdk';

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

const result = await client.request(deleteShare('0375bb1d-5cbb-48cf-bfac-476a3440a104'));
```

</template>
</SnippetToggler>

## Delete Multiple Shares

Delete multiple existing shares.

### Request

<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
<template #rest>

`DELETE /shares`

Provide an array of share IDs as the body of your request.

</template>
<template #graphql>

`POST /graphql/system`

```graphql
type Mutation {
	delete_shares_items(ids: [ID!]!): delete_many
}
```

</template>
<template #sdk>

```js
import { createDirectus, rest, deleteShares } from '@directus/sdk';

const client = createDirectus('directus_project_url').with(rest());

const result = await client.request(deleteShares(share_id_array));
```

</template>
</SnippetToggler>

#### Request Body

An array of share primary keys

### Response

Empty body.

### Example

<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
<template #rest>

`DELETE /shares`

```json
["653925a9-970e-487a-bfc0-ab6c96affcdc", "c86c2761-65d3-43c3-897f-6f74ad6a5bd7"]
```

</template>
<template #graphql>

`POST /graphql/system`

```graphql
mutation {
	delete_shares_items(ids: ["653925a9-970e-487a-bfc0-ab6c96affcdc", "c86c2761-65d3-43c3-897f-6f74ad6a5bd7"]) {
		ids
	}
}
```

</template>
<template #sdk>

```js
import { createDirectus, rest, deleteShares } from '@directus/sdk';

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

const result = await client.request(
	deleteShares(['2f8c03c3-4988-4869-a1b3-318e0a4b9b9d', '153cdb59-7868-4187-8696-372aa07537f4'])
);
```

</template>
</SnippetToggler>

## Authenticate a Share

Shares work by publicly giving you an access/refresh token combination (as you would get with the regular /auth/login
endpoints). 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 credentials set returned by this endpoint.

### Request

<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
<template #rest>

`POST /shares/auth`

```json
{
	"share": share_id,
	"password": password
}
```

</template>
<template #graphql>

`// Not currently available in GraphQL`

</template>
<template #sdk>

```js
import { createDirectus, rest, authenticateShare } from '@directus/sdk';

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

const result = await client.request(authenticateShare('share_key', 'password'));
```

</template>
</SnippetToggler>

#### Request Body

`share` **Required**\
Primary key of the share you're authenticating against.

`password` **string**\
Password for the share, if one is configured.

### Response

`access_token` **string**\
Temporary access token to be used in follow-up requests.

`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`](#refresh). Note: if you used `cookie`
as the mode in the request, the refresh token won't be returned in the JSON.

### Example

<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
<template #rest>

`POST /shares/auth`

```json
{
	"share": "61e8a1b6-6eba-438c-91e8-8d912ef655d3",
	"password": "d1r3ct5us"
}
```

</template>
<template #graphql>

`// Not currently available in GraphQL`

</template>
<template #sdk>

```js
import { createDirectus, rest, authenticateShare } from '@directus/sdk';

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

const result = await client.request(authenticateShare('61e8a1b6-6eba-438c-91e8-8d912ef655d3', 'd1r3ct5us'));
```

</template>
</SnippetToggler>

## Send a Share by Email

Sends an email to the provided email addresses with a link to the share.

### Request

<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
<template #rest>

`POST /shares/invite`

```json
{
	"share": share_key,
	"emails": email_address_array
}
```

</template>
<template #graphql>

`// Not currently available in GraphQL`

</template>
<template #sdk>

```js
import { createDirectus, rest, inviteShare } from '@directus/sdk';

const client = createDirectus('directus_project_url').with(rest());

const result = await client.request(inviteShare(share_id, email_address_array));
```

</template>
</SnippetToggler>

#### 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

<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
<template #rest>

`POST /shares/invite`

```json
{
	"share": "653925a9-970e-487a-bfc0-ab6c96affcdc",
	"emails": ["allison@example.com", "mike@example.com"]
}
```

</template>
<template #graphql>

`// Not currently available in GraphQL`

</template>
<template #sdk>

```js
import { createDirectus, rest, inviteShare } from '@directus/sdk';

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

const result = await client.request(
	inviteShare('653925a9-970e-487a-bfc0-ab6c96affcdc', ['allison@example.com', 'mike@example.com'])
);
```

</template>
</SnippetToggler>

## Get Share Public Info

Allows unauthenticated users to retrieve information about the share.

<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
<template #rest>

`GET /shares/info/:id`

</template>
<template #graphql>

`// Not currently available in GraphQL`

</template>
<template #sdk>

```js
import { createDirectus, rest, readShareInfo } from '@directus/sdk';

const client = createDirectus('directus_project_url').with(rest());

const result = await client.request(readShareInfo(share_id));
```

</template>
</SnippetToggler>

### Response

The [share objects](#the-share-object) for the given UUID, if it's still valid.

### Example

<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
<template #rest>

`GET /shares/info/653925a9-970e-487a-bfc0-ab6c96affcdc`

</template>
<template #graphql>

`// Not currently available in GraphQL`

</template>
<template #sdk>

```js
import { createDirectus, rest, readShareInfo } from '@directus/sdk';

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

const result = await client.request(readShareInfo('653925a9-970e-487a-bfc0-ab6c96affcdc'));
```

</template>
</SnippetToggler>
