Directus Docs

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

# The Relation Object

# id integer

Unique identifier for the relation.

# collection_many string

Collection that has the field that holds the foreign key.

# field_many string

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

# collection_one string

Collection on the one side of the relationship.

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

# List the Relations

List the relations.

# Parameters

# project required

The project you're targetting.

# Query

# fields optional

Control what fields are being returned in the object. Learn more

# limit optional

A limit on the number of objects that are returned. Default is 200. Learn more

# offset optional

How many items to skip when fetching data. Default is 0. Learn more

# page optional

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

# sort optional

How to sort the returned items. Learn more

# single optional

Return the result as if it was a single item. Useful for selecting a single item based on filters and search queries. Will force limit to be 1. Learn more

# filter optional

Select items in collection by given conditions. Learn more

# q optional

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

# meta optional

What metadata to return in the response. Learn more

# Returns

Returns an array of relation objects.

Endpoint
   GET /:project/relations
Response
{
  "data": [
    {
      "id": 1,
      "collection_many": "directus_activity",
      "field_many": "action_by",
      "collection_one": "directus_users",
      "field_one": null,
      "junction_field": null
    },
    { ... },
    { ... }
  ]
}

# Retrieve a Relation

Retrieve a single relation by unique identifier.

# Parameters

# project required

The project you're targetting.

# id required

Unique identifier of the item.

# Query

# fields optional

Control what fields are being returned in the object. Learn more

# meta optional

What metadata to return in the response. Learn more

# Returns

Returns the relation object for the given unique identifier.

Endpoint
   GET /:project/relations/:id
Response
{
  "data": {
    "id": 1,
    "collection_many": "directus_activity",
    "field_many": "action_by",
    "collection_one": "directus_users",
    "field_one": null,
    "junction_field": null
  }
}

# Create a Relation

Create a new relation.

# Parameters

# project required

The project you're targetting.

# Attributes

# collection_many required

Collection that has the field that holds the foreign key.

# field_many required

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

# collection_one optional

Collection on the one side of the relationship.

# field_one optional

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

# junction_field optional

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

# Query

# fields optional

Control what fields are being returned in the object. Learn more

# meta optional

What metadata to return in the response. Learn more

# Returns

Returns the relation object for the relation that was just created.

Endpoint
  POST /:project/relations
Request
{
  "collection_many": "articles",
  "field_many": "author",
  "collection_one": "authors",
  "field_one": "books"
}
Response
{
  "data": {
    "id": 15,
    "collection_many": "articles",
    "field_many": "author",
    "collection_one": "authors",
    "field_one": "books",
    "junction_field": null
  }
}

# Update a Relation

Update an existing relation

# Parameters

# project required

The project you're targetting.

# id required

Unique identifier of the item.

# Attributes

# collection_many optional

Collection that has the field that holds the foreign key.

# field_many optional

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

# collection_one optional

Collection on the one side of the relationship.

# field_one optional

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

# junction_field optional

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

# Query

# fields optional

Control what fields are being returned in the object. Learn more

# meta optional

What metadata to return in the response. Learn more

# Returns

Returns the relation object for the relation that was just updated.

Endpoint
 PATCH /:project/relations/:id
Request
{
  "field_one": "books"
}
Response
{
  "data": {
    "id": 15,
    "collection_many": "articles",
    "field_many": "author",
    "collection_one": "authors",
    "field_one": "books",
    "junction_field": null
  }
}

# Delete a Relation

Delete an existing relation.

# Parameters

# project required

The project you're targetting.

# id required

Unique identifier of the item.

# Returns

Returns an empty body with HTTP status 204

Endpoint
DELETE /:project/relations/:id

← Revisions →