Relations | Directus Docs

List Relations

List all relations that exist in Directus. 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

fields

array

Control what fields are being returned in the object.

limit

integer

A limit on the number of objects that are returned.

offset

integer

How many items to skip when fetching data.

meta

string

What metadata to return in the response.

sort

array

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.

filter

Select items in collection by given conditions.

string

Filter by items that contain the given search query in one of their fields.

page

integer

Cursor for use in pagination. Often used in combination with limit.

Response

Successful request

data

array

GET /relations

Response Example

{
  "data": [
    {
      "id": 1,
      "many_collection": "directus_activity",
      "many_field": "user",
      "one_collection": "directus_users",
      "one_field": null,
      "one_allowed_collections": [],
      "junction_field": null
    }
  ]
}

Create a Relation

Create a new relation.

Query Parameters

fields

array

Control what fields are being returned in the object.

meta

string

What metadata to return in the response.

Request Body

collection_many

string

Collection that has the field that holds the foreign key.

collection_one

string

Collection on the one side of the relationship.

field_many

string

Foreign key. Field that holds the primary key of the related collection.

field_one

string

Alias column that serves as the one side of the relationship.

junction_field

string

Field on the junction table that holds the primary key of the related collection.

Response

Successful request

data

object

POST /relations

Response Example

{
  "data": {
    "id": 1,
    "many_collection": "directus_activity",
    "many_field": "user",
    "one_collection": "directus_users",
    "one_field": null,
    "one_allowed_collections": [],
    "junction_field": null
  }
}

Retrieve a Relation

Retrieve a single relation by unique identifier.

Query Parameters

integer

Identifier for the object.

fields

array

Control what fields are being returned in the object.

meta

string

What metadata to return in the response.

Response

Successful request

data

object

GET /relations/{id}

Response Example

{
  "data": {
    "id": 1,
    "many_collection": "directus_activity",
    "many_field": "user",
    "one_collection": "directus_users",
    "one_field": null,
    "one_allowed_collections": [],
    "junction_field": null
  }
}

Delete a Relation

Delete an existing relation.

Query Parameters

integer

Identifier for the object.

DELETE /relations/{id}

Update a Relation

Update an existing relation.

Query Parameters

integer

Identifier for the object.

fields

array

Control what fields are being returned in the object.

meta

string

What metadata to return in the response.

Request Body

collection_many

string

Collection that has the field that holds the foreign key.

collection_one

string

Collection on the one side of the relationship.

field_many

string

Foreign key. Field that holds the primary key of the related collection.

field_one

string

Alias column that serves as the one side of the relationship.

junction_field

string

Field on the junction table that holds the primary key of the related collection.

Response

Successful request

data

object

PATCH /relations/{id}

Response Example

{
  "data": {
    "id": 1,
    "many_collection": "directus_activity",
    "many_field": "user",
    "one_collection": "directus_users",
    "one_field": null,
    "one_allowed_collections": [],
    "junction_field": null
  }
}