Skip to content

Set a team's default override

PUT
/fields/{id}/default-overrides/{team_id}

Sets the upload default one team uses for this field instead of the field’s own default. Requires the fields.admin or system.admin capability, granted globally; you don’t need to belong to the team.

The body is a complete default, checked the same way as the field’s own default_value: against the field’s type and, for vocabulary fields, against the field’s current terms, where only active terms are accepted. Only asset fields can have upload defaults, and the team must exist and not be deleted. Setting an override again replaces the earlier one.

When an asset is created, the override is used if the uploader belongs directly to this team and to no other team that overrides the same field; with two or more such teams, the field’s own default is used instead. The asset’s own team plays no part. Overrides apply only to active fields, only on asset types the field applies to, and never replace a value the asset already has. If the override can’t be filled in, for example uploading_team for someone in more than one team, the field gets no default at all; the field’s own default isn’t used instead. Later changes to the field’s terms aren’t checked against stored overrides.

id
required
string format: uuid

The field definition’s id.

team_id
required
string format: uuid

The team’s id.

An upload default: either a fixed value (literal) or a value the server fills in when the asset is created (context). It is never a formula.

For a literal, set only the value_* member the field’s type uses; setting another member is refused with 400. On select, multi_select and tree fields the slugs must be active terms of the field. Upload defaults suit values chosen in advance; values read from the file come from metadata extraction instead.

object
kind
required

literal for a fixed value, context for one the server fills in when the asset is created.

string
Allowed values: literal context
value_text

The literal value for text, longtext, rich_text, select and tree fields. For select and tree, an active slug.

string
nullable
value_num

The literal value for number and boolean fields. A boolean is 1 or 0.

number
nullable
value_date

The literal value for date and datetime fields.

string format: date-time
nullable
value_options

The literal value for multi_select fields: active slugs.

Array<string>
nullable
value_ref

The literal value for reference fields: an asset id.

string format: uuid
nullable
context

Required when kind is context, and not allowed otherwise. The server fills in the value when the asset is created:

  • uploading_user: the uploader’s full name from their account, or their username if no full name is set. Use it on text fields.
  • uploading_team: the name of the uploader’s team. Use it on text fields. Skipped when the uploader belongs to no team or to more than one.
  • current_date: the creation time, for date and datetime fields. A date field gets the day (UTC), a datetime field the exact time.

These three are the only choices.

string
Allowed values: uploading_user uploading_team current_date

The stored override.

One team’s override of a field’s upload default.

object
field_id
required

The field definition’s id.

string format: uuid
team_id
required

The team’s id.

string format: uuid
team_slug
required

The team’s slug.

string
team_name
required

The team’s name.

string
default_value
required

An upload default: either a fixed value (literal) or a value the server fills in when the asset is created (context). It is never a formula.

For a literal, set only the value_* member the field’s type uses; setting another member is refused with 400. On select, multi_select and tree fields the slugs must be active terms of the field. Upload defaults suit values chosen in advance; values read from the file come from metadata extraction instead.

object
kind
required

literal for a fixed value, context for one the server fills in when the asset is created.

string
Allowed values: literal context
value_text

The literal value for text, longtext, rich_text, select and tree fields. For select and tree, an active slug.

string
nullable
value_num

The literal value for number and boolean fields. A boolean is 1 or 0.

number
nullable
value_date

The literal value for date and datetime fields.

string format: date-time
nullable
value_options

The literal value for multi_select fields: active slugs.

Array<string>
nullable
value_ref

The literal value for reference fields: an asset id.

string format: uuid
nullable
context

Required when kind is context, and not allowed otherwise. The server fills in the value when the asset is created:

  • uploading_user: the uploader’s full name from their account, or their username if no full name is set. Use it on text fields.
  • uploading_team: the name of the uploader’s team. Use it on text fields. Skipped when the uploader belongs to no team or to more than one.
  • current_date: the creation time, for date and datetime fields. A date field gets the day (UTC), a datetime field the exact time.

These three are the only choices.

string
Allowed values: uploading_user uploading_team current_date
created_at
required

When the override was first set. Setting it again keeps this time.

string format: date-time
updated_at
required

When the override was last set.

string format: date-time
updated_by_user_ref

The account that last set the override.

integer format: int64
nullable

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed