SG Ground Truth

PUT /schema/<Type>/fields/<field>

put_schema_type_fields_field

Changes a field's properties. A body changing data_type is a 200 that does nothing, so read the field back rather than trusting the status code.

API

Params

part value
properties a list of {property_name, value}, the same shape the create takes. Required and not empty. Several are applied together or not at all (probe 121)
project_id in the JSON body or the query. Required when visible is among the properties, and scopes only visible (probe 115)

Sample requests

A rename, which works:

r = c.put("/schema/Version/fields/sg_my_field",
          json={"properties": [{"property_name": "name", "value": "Renamed"}]})

A type change, which does not:

r = c.put("/schema/Version/fields/sg_zzprobe_040_revive", json={"data_type": "number"})
print(r.status_code)
# 200
c.get("/schema/Version/fields/sg_zzprobe_040_revive").json()["data"]["data_type"]["value"]
# 'text', unchanged

Response codes

status when
200 accepted, which is not the same as applied. The body is the whole field
400 code 104 The 'visible' property requires a project to be updated.
400 code 105 The Project with the given project_id does not exist.
400 invalid property '<name>', followed by the valid property names for that field
400 Request Parameters invalid. with value must be filled for a null, "" or [] value, on description and name as on the rest
400 invalid/missing '<property>' value string for a description or name of spaces alone
400 'default_value' not in valid_values on a list or status_list
400 invalid/missing 'status_list' string for a status code the site does not have, the valid codes in source.status
400 invalid/missing entity for a valid_types name that is no entity type, every type in source.entity_type
404 Field '<Type>.<field>' does not exist., for a retired field and an unused name alike (probe 119)
500 code 105 does not support updating 'unique'. on a text field
500 code 105 API schema_field_update() RuntimeError: User doesn't have permission to configure Field properties. for an Artist (probe 132)
500 code 100 Shotgun Server Error for a valid_types name in the wrong case, "shot". The field is retired by it (probe 121)

Edge cases

  • data_type is immutable and the API does not say so. The write answers 200 and the value is unchanged. This is the sharpest case of the general rule that a 200 from this API proves the request parsed, not that it happened.
  • A property the update does not take is a 400 that lists the ones it does. For hidden_values on a status field the list was name, visible, description, summary_default, default_value, valid_values, custom_metadata, with or without project_id (probe 114). hidden_values cannot be written over REST.
  • A top-level key the call does not take is ignored when properties is present: {"unique": true, "properties": [...]} is a 200 that applies the properties and leaves unique alone (probe 116).
  • Which properties a field takes depends on its data_type, and the field says so: each one reads editable: true in GET /schema/<Type>/fields/<field>. Probe 116 has the table.
  • One refused property refuses the request: the others are not applied. valid_values and default_value sent together are checked against each other, in either order (probe 121).
  • Changing an entity field's valid_types creates a field on each type added and retires the one on each type removed. A retired name stays taken (probe 121).
  • Renaming changes the display name only. The programmatic name is fixed at creation, and a rename does not free the old one for reuse.

Every entry on this site is the output of a probe in probes/. The corpus is generated by running those probes against a live Flow Production Tracking site, not written from memory.

Not affiliated with or endorsed by Autodesk. Flow Production Tracking is their product; this is an independent record of how its REST API answers.