GET /:project/fields
# Fields
Fields are individual pieces of content within an item. They are mapped to columns in the database.
# 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.
# default_value value
The default value for the field. Used when a specific value is not provided during item creation. The default value's type should be consistent with the type attribute.
# 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.
# 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.
{
"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.
GET /:project/fields/:collection
{
"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.
GET /:project/fields/:collection/:field
{
"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.
# default_value optional
The default value for the field. Used when a specific value is not provided during item creation. The default value's type should be consistent with the type attribute.
# 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.
POST /:project/fields/:collection
{
"field": "test",
"type": "string",
"datatype": "VARCHAR",
"length": 255,
"interface": "text-input"
}
{
"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.
# default_value optional
The default value for the field. Used when a specific value is not provided during item creation. The default value's type should be consistent with the type attribute.
# 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.
PATCH /:project/fields/:collection/:field
{
"note": "Enter the title here."
}
{
"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.
DANGER
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
DELETE /:project/fields/:collection/:field
← Extensions Folders →