Fields

Fields are individual pieces of content within an item. They are mapped to columns in the database.

Endpoints
   GET /:project/fields
   GET /:project/fields/:collection
   GET /:project/fields/:collection/:field
  POST /:project/fields/:collection
 PATCH /:project/fields/:collection/:field
DELETE /:project/fields/:collection/:field

The Field Object

Attributes

collection string

Unique name of the collection this field is in.

field string

Unique name of the field. Field name is unique within the collection.

datatype string

SQL datatype of the column that corresponds to this field.

unique boolean

If the value of this field should be unique within the collection.

primary_key boolean

If this field is the primary key of the collection.

auto_increment boolean

If the value in this field is auto incremented. Only applies to integer type fields.

note string

A user provided note for the field. Will be rendered alongside the interface on the edit page.

signed boolean

If the value is signed or not. Only applies to integer type fields.

id integer

Unique identifier for the field in the directus_fields collection.

type string

Directus specific data type. Used to cast values in the API.

sort integer

Sort order of this field on the edit page of the admin app.

interface string

What interface is used in the admin app to edit the value for this field.

hidden_detail boolean

If this field should be hidden from the item detail (edit) page.

hidden_browse boolean

If this field should be hidden from the item browse (listing) page.

required boolean

If this field requires a value.

options object

Options for the interface that's used. This format is based on the individual interface.

locked boolean

If the field can be altered by the end user. Directus system fields have this value set to true.

translation key/value

Key value pair of <locale>: <translation> that allows the user to change the displayed name of the field in the admin app.

readonly boolean

Prevents the user from editing the value in the field.

width string

Width of the field on the edit form. One of half, half-left, half-right, full, fill.

validation regex

User provided regex that will be used in the API to validate incoming values. It uses the PHP flavor of RegEX.

group integer

What field group this field is part of.

length integer

Length of the field. Will be used in SQL to set the length property of the colummn.

Collection object
{
  "collection": "about_us",
  "field": "id",
  "datatype": "INT",
  "unique": false,
  "primary_key": true,
  "auto_increment": true,
  "default_value": null,
  "note": "",
  "signed": false,
  "id": 167,
  "type": "integer",
  "sort": 1,
  "interface": "primary-key",
  "hidden_detail": true,
  "hidden_browse": true,
  "required": true,
  "options": null,
  "locked": 0,
  "translation": null,
  "readonly": false,
  "width": null,
  "validation": null,
  "group": null,
  "length": "10"
}

List Fields

Returns a list of the fields available in the project.

Parameters

project required

The project you're targetting.

Query

limit optional

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

sort optional

How to sort the returned items. Learn more

Returns

An object with a data property that contains an array field objects for the available fields. This array also contains the Directus system fields and is never empty.

Endpoint
GET /:project/fields
Response
{
  "data": [
  	{
      "collection": "about_us",
      "field": "id",
      "datatype": "INT",
      "unique": false,
      "primary_key": true,
      "auto_increment": true,
      "default_value": null,
      "note": "",
      "signed": false,
      "id": 167,
      "type": "integer",
      "sort": 1,
      "interface": "primary-key",
      "hidden_detail": true,
      "hidden_browse": true,
      "required": true,
      "options": null,
      "locked": 0,
      "translation": null,
      "readonly": false,
      "width": null,
      "validation": null,
      "group": null,
      "length": "10"
    },
    { ... },
    { ... }
  ]
}

List Fields in Collection

Returns a list of the fields available in the given collection.

Parameters

project required

The project you're targetting.

collection required

Unique identifier of the collection the item resides in.

Query

sort optional

How to sort the returned items. Learn more

Returns

An object with a data property that contains an array of field objects for available fields.

Endpoint
GET /:project/fields/:collection
Response
{
  "data": [
    {
      "collection": "about_us",
      "field": "id",
      "datatype": "INT",
      "unique": false,
      "primary_key": true,
      "auto_increment": true,
      "default_value": null,
      "note": "",
      "signed": false,
      "id": 167,
      "type": "integer",
      "sort": 1,
      "interface": "primary-key",
      "hidden_detail": true,
      "hidden_browse": true,
      "required": true,
      "options": null,
      "locked": 0,
      "translation": null,
      "readonly": false,
      "width": null,
      "validation": null,
      "group": null,
      "length": "10"
    },
    { ... },
    { ... }
  ]
}

Retrieve a Field

Retrieves the details of a single field in a given collection.

Parameters

project required

The project you're targetting.

collection required

Unique identifier of the collection the item resides in.

field required

The unique name of the field.

Query

No query parameters available.

Returns

Returns a field object.

Endpoint
GET /:project/fields/:collection/:field
Response
{
  "data": {
    "collection": "about_us",
    "field": "id",
    "datatype": "INT",
    "unique": false,
    "primary_key": true,
    "auto_increment": true,
    "default_value": null,
    "note": "",
    "signed": false,
    "id": 167,
    "type": "integer",
    "sort": 1,
    "interface": "primary-key",
    "hidden_detail": true,
    "hidden_browse": true,
    "required": true,
    "options": null,
    "locked": 0,
    "translation": null,
    "readonly": false,
    "width": null,
    "validation": null,
    "group": null,
    "length": "10"
  }
}

Create a Field

Create a new field in a given collection.

Parameters

project required

The project you're targetting.

collection required

Unique identifier of the collection the item resides in.

Attributes

field required

Unique name of the field. Field name is unique within the collection.

datatype required

SQL datatype of the column that corresponds to this field.

unique optional

If the value of this field should be unique within the collection.

primary_key optional

If this field is the primary key of the collection.

auto_increment optional

If the value in this field is auto incremented. Only applies to integer type fields.

note optional

A user provided note for the field. Will be rendered alongside the interface on the edit page.

signed optional

If the value is signed or not. Only applies to integer type fields.

type required

Directus specific data type. Used to cast values in the API.

sort optional

Sort order of this field on the edit page of the admin app.

interface optional

What interface is used in the admin app to edit the value for this field.

hidden_detail optional

If this field should be hidden from the item detail (edit) page.

hidden_browse optional

If this field should be hidden from the item browse (listing) page.

required optional

If this field requires a value.

options optional

Options for the interface that's used. This format is based on the individual interface.

locked optional

If the field can be altered by the end user. Directus system fields have this value set to true.

translation optional/value

Key value pair of <locale>: <translation> that allows the user to change the displayed name of the field in the admin app.

readonly optional

Prevents the user from editing the value in the field.

width optional

Width of the field on the edit form. One of half, half-left, half-right, full, fill.

validation optional

User provided regex that will be used in the API to validate incoming values.

group optional

What field group this field is part of.

length required

Length of the field. Will be used in SQL to set the length property of the colummn. Requirement of this attribute depends on the provided datatype.

Query

No query parameters available.

Returns

Returns a field object for the newly created field.

Endpoint
  POST /:project/fields/:collection
Request body
{
  "field": "test",
  "type": "string",
  "datatype": "VARCHAR",
  "length": 255,
  "interface": "text-input"
}
Response
{
  "data": {
    "collection": "about_us",
    "field": "title",
    "datatype": "VARCHAR",
    "unique": false,
    "primary_key": false,
    "auto_increment": false,
    "default_value": null,
    "note": null,
    "signed": true,
    "id": 895,
    "type": "string",
    "sort": 0,
    "interface": "text-input",
    "hidden_detail": false,
    "hidden_browse": false,
    "required": false,
    "options": null,
    "locked": false,
    "translation": null,
    "readonly": false,
    "width": null,
    "validation": null,
    "group": null,
    "length": "255"
  }
}

Update a Field

Update an existing field.

WARNING

You can't update a field's name.

Parameters

project required

The project you're targetting.

collection required

Unique identifier of the collection the item resides in.

field required

The unique name of the field.

Attributes

datatype optional

SQL datatype of the column that corresponds to this field.

unique optional

If the value of this field should be unique within the collection.

primary_key optional

If this field is the primary key of the collection.

auto_increment optional

If the value in this field is auto incremented. Only applies to integer type fields.

note optional

A user provided note for the field. Will be rendered alongside the interface on the edit page.

signed optional

If the value is signed or not. Only applies to integer type fields.

type optional

Directus specific data type. Used to cast values in the API.

sort optional

Sort order of this field on the edit page of the admin app.

interface optional

What interface is used in the admin app to edit the value for this field.

hidden_detail optional

If this field should be hidden from the item detail (edit) page.

hidden_browse optional

If this field should be hidden from the item browse (listing) page.

required optional

If this field requires a value.

options optional

Options for the interface that's used. This format is based on the individual interface.

locked optional

If the field can be altered by the end user. Directus system fields have this value set to true.

translation optional/value

Key value pair of <locale>: <translation> that allows the user to change the displayed name of the field in the admin app.

readonly optional

Prevents the user from editing the value in the field.

width optional

Width of the field on the edit form. One of half, half-left, half-right, full, fill.

validation optional

User provided regex that will be used in the API to validate incoming values.

group optional

What field group this field is part of.

length optional

Length of the field. Will be used in SQL to set the length property of the colummn. Requirement of this attribute depends on the provided datatype.

datatype

Be careful when updating the datatype. You could corrupt the data in the items. Be sure to make a backup of the database if you're not sure of what you're doing.

Query

No query parameters available.

Returns

Returns the field object for the updated field.

Endpoint
 PATCH /:project/fields/:collection/:field
Request body
{
  "note": "Enter the title here."
}
Response
{
  "data": {
    "collection": "about_us",
    "field": "title",
    "datatype": "VARCHAR",
    "unique": false,
    "primary_key": false,
    "auto_increment": false,
    "default_value": null,
    "note": "Enter the title here",
    "signed": true,
    "id": 895,
    "type": "string",
    "sort": 0,
    "interface": "text-input",
    "hidden_detail": false,
    "hidden_browse": false,
    "required": false,
    "options": null,
    "locked": false,
    "translation": null,
    "readonly": false,
    "width": null,
    "validation": null,
    "group": null,
    "length": "255"
  }
}

Delete a Field

Delete an existing field.

WARNING

This will delete the whole field, including the values within. Proceed with caution.

Parameters

project required

The project you're targetting.

collection required

Unique identifier of the collection the item resides in.

field required

The unique name of the field.

Returns

Returns an empty body with HTTP status 204

Endpoint
DELETE /:project/fields/:collection/:field