Create a Field
This endpoint creates a new field on an existing collection.
Endpoint
[POST]
/collections/{collection_slug}/fieldsPermissions
This endpoint requires a token with the admin ability.
Path Parameters
| Name | Required | Description |
|---|---|---|
collection_slug | Yes | The slug of the target collection. |
Headers
| Name | Required | Description |
|---|---|---|
Accept | Yes | Specifies the response content type. Must be application/json. |
Authorization | Yes | Required. Must be a Bearer token with admin scope. |
project-id | Yes | The unique identifier for the project. |
Body Parameters
| Name | Type | Required | Description |
|---|---|---|---|
type | string | Yes | The field type (e.g., text, number, richtext, boolean, date, media, relation, select, longtext, group, etc.). Max 60 characters. |
label | string | Yes | The display label for the field. Max 60 characters. |
name | string | Yes | The field identifier in kebab-case (e.g., my-field). Must be unique within the collection and parent scope. Max 60 characters. |
description | string | No | A description or help text for the field. |
placeholder | string | No | Placeholder text for the field input. |
options | object | No | Field-specific options. |
validations | object | No | Validation rules for the field. |
parent_field_id | integer | No | The internal ID of a group field to nest this field under. |
Group Fields
When creating a field of type group, the options.repeatable property is required:
{
"type": "group",
"label": "SEO",
"name": "seo",
"options": { "repeatable": false }
}Validation Rules
Validations are passed as an object. Common validation rules include:
{
"validations": {
"required": { "status": true, "message": "This field is required" },
"unique": { "status": true, "message": "This value must be unique" },
"char_limit": { "status": true, "min": 1, "max": 255 }
}
}Example Requests
const collectionSlug = 'blog-posts';
// Create a simple text field
axios.post(`https://your-domain.com/api/collections/${collectionSlug}/fields`, {
type: 'text',
label: 'Title',
name: 'title',
placeholder: 'Enter a title',
validations: {
required: { status: true, message: 'Title is required' }
}
}, {
headers: {
'Accept': 'application/json',
'Authorization': 'Bearer YOUR_API_TOKEN',
'project-id': 'YOUR_PROJECT_UUID'
}
});use Illuminate\Support\Facades\Http;
$collectionSlug = 'blog-posts';
$response = Http::withToken('YOUR_API_TOKEN')->withHeaders([
'Accept' => 'application/json',
'project-id' => 'YOUR_PROJECT_UUID'
])->post("https://your-domain.com/api/collections/{$collectionSlug}/fields", [
'type' => 'text',
'label' => 'Title',
'name' => 'title',
'placeholder' => 'Enter a title',
'validations' => [
'required' => ['status' => true, 'message' => 'Title is required']
]
]);curl -X POST "https://your-domain.com/api/collections/blog-posts/fields" \
-H "Accept: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "project-id: YOUR_PROJECT_UUID" \
-H "Content-Type: application/json" \
-d '{
"type": "text",
"label": "Title",
"name": "title",
"placeholder": "Enter a title",
"validations": {
"required": { "status": true, "message": "Title is required" }
}
}'Responses
201: Created
Returns the newly created field object.
{
"uuid": "a1b2c3d4-0001-0000-0000-000000000001",
"type": "text",
"label": "Title",
"name": "title",
"description": null,
"placeholder": "Enter a title",
"options": [],
"validations": {
"required": { "status": true, "message": "Title is required" }
},
"order": 1,
"parent_field_id": null,
"created_at": "2026-02-10T10:00:00.000000Z",
"updated_at": "2026-02-10T10:00:00.000000Z"
}403: Forbidden
Returned if the API token does not have the admin ability.
{
"message": "API token doesn't have the right abilities!"
}404: Not Found
Returned if the collection with the specified slug does not exist.
{
"message": "Collection not found."
}422: Unprocessable Entity
Returned for validation errors, such as a duplicate field name.
{
"message": "The name has already been taken.",
"errors": {
"name": [
"The name has already been taken."
]
}
}