---
pageClass: page-reference
---
# Relations
> What data is linked to what other data. Allows you to assign authors to articles, products to sales, and whatever
> other structures you can think of. [Learn more about Relationships](/concepts/relationships/).
[[toc]]
---
## The Relation Object
`id` **integer**\
Primary key of the relation.
`many_collection` **string**\
Collection on the "many" side of the relation.
`many_field` **string**\
Field on the "many" side of the relation.
`one_collection` **string**\
Collection on the "one" side of the relation.
`one_field` **string**\
Field on the "one" side of the relation.
`one_collection_field` **string**\
In Many-to-Any type fields, this holds the field in the many collection that holds the name of the "one" collection.
`one_allowed_collections` **string**\
In Many-to-Any type fields, this holds a csv of collection names the user is allowed to use through the m2a relation.
`junction_field` **string**\
For Many-to-Many type fields, this holds the name of the field that "links" a many-to-one to a one-to-many, creating a many-to-many.
```json
{
"id": 13,
"many_collection": "articles",
"many_field": "featured_image",
"one_collection": "directus_files",
"one_field": null,
"one_collection_field": null,
"one_allowed_collections": null,
"junction_field": null
}
```
---
## List relations
List all relations that exist in Directus.
::: tip Permissions
The data returned in this endpoint will be filtered based on the user's permissions. For example, relations that apply
to a collection that the current user doesn't have access to are stripped out.
:::
### Query Parameters
Supports all [global query parameters](/reference/api/query).
### Returns
An array of up to [limit](/reference/api/query/#limit) [relation objects](#the-relation-object). If no items are
available, data will be an empty array.
### REST API
```
GET /relations
```
### GraphQL
```graphql
type Query {
relations: [directus_relations]
}
```
##### Example
```graphql
query {
relations {
id
many_collection
one_collection
}
}
```
---
## Retrieve a relation
List an existing relation by primary key.
### Query Parameters
Supports all [global query parameters](/reference/api/query).
### Returns
Returns the requested [relation object](#the-relation-object).
### REST API
```
GET /relations/:id
```
##### Example
```
GET /relations/15
```
### GraphQL
```graphql
type Query {
relations_by_id(id: ID!): directus_relations
}
```
##### Example
```graphql
query {
relations_by_id(id: 15) {
id
many_collection
one_collection
}
}
```
---
## Create a Relation
Create a new relation.
### Query Parameters
Supports all [global query parameters](/reference/api/query).
### Request Body
A partial [relation object](#the-relation-object).
### Returns
Returns the [relation object](#the-relation-object) for the created relation.
### REST API
```
POST /relations
```
##### Example
```json
// POST /relations
{
"many_collection": "articles",
"many_field": "featured_image",
"one_collection": "directus_files"
}
```
### GraphQL
```graphql
type Mutation {
create_relations_item(data: create_directus_relations_input!): directus_relations
}
```
##### Example
```graphql
mutation {
create_relations_item(
data: { many_collection: "articles", many_field: "featured_image", one_collection: "directus_files" }
) {
id
many_collection
one_collection
}
}
```
---
## Create Multiple Relations
Create multiple new relations.
### Query Parameters
Supports all [global query parameters](/reference/api/query).
### Request Body
An array of partial [relation objects](#the-relation-object).
### Returns
Returns the [relation objects](#the-relation-object) for the created relations.
### REST API
```
POST /relations
```
##### Example
```json
// POST /relations
[
{
"many_collection": "articles",
"many_field": "featured_image",
"one_collection": "directus_files"
},
{
"many_collection": "articles",
"many_field": "category",
"one_collection": "categories"
}
]
```
### GraphQL
```graphql
type Mutation {
create_relations_items(data: [create_directus_relations_input!]!): [directus_relations]
}
```
##### Example
```graphql
mutation {
create_relations_items(
data: [
{ many_collection: "articles", many_field: "featured_image", one_collection: "directus_files" }
{ many_collection: "articles", many_field: "category", one_collection: "categories" }
]
) {
id
many_collection
one_collection
}
}
```
---
## Update a Relation
Update an existing relation.
### Query Parameters
Supports all [global query parameters](/reference/api/query).
### Request Body
A partial [relation object](#the-relation-object).
### Returns
Returns the [relation object](#the-relation-object) for the created relation.
### REST API
```
PATCH /relations/:id
```
##### Example
```json
// PATCH /relations/15
{
"one_field": "articles"
}
```
### GraphQL
```graphql
type Mutation {
update_relations_item(id: ID!, data: update_directus_relations_input!): directus_relations
}
```
##### Example
```graphql
mutation {
update_relations_item(id: 15, data: { one_field: "articles" }) {
id
many_collection
one_collection
}
}
```
---
## Delete a Relation
Delete an existing relation.
### Returns
Empty body.
### REST API
```
DELETE /relations/:id
```
##### Example
```
DELETE /relations/15
```
### GraphQL
```graphql
type Mutation {
delete_relations_item(id: ID!): delete_one
}
```
##### Example
```graphql
mutation {
delete_relations_item(id: 15) {
id
}
}
```
---
## Delete Multiple Relations
Delete multiple existing relations.
### Request Body
An array of relation primary keys.
### Returns
Empty body.
### REST API
```
DELETE /relations
```
##### Example
```json
// DELETE /relations
[15, 251, 810]
```
### GraphQL
```graphql
type Mutation {
delete_relations_items(ids: [ID!]!): delete_many
}
```
##### Example
```graphql
mutation {
delete_relations_items(ids: [15, 251, 810]) {
ids
}
}
```
---