Flow API: types, fields, statuses and publishing

SENSEVER

The official Sensever channel: guides and API documentation for Chat, Requests, Flow, Studio, bots and messaging channels.

約 26 分で読めます

Flow API: types, fields, statuses and publishing

Flow's data model is described by definitions: object types, fields, relations between types, the status process (lifecycle) and constraints. Definitions are versioned: you edit a draft, validate it and publish it. New objects are created on the current schema version; publishing moves existing objects to it automatically if the changes are safe, and on an explicit command if they are not. This article describes how to read and change definitions through the API.

The API address, authentication and the error format are described in Flow API: basics. For the same in the interface, see Flow: object types and fields and Flow: statuses and the process editor.

Reading definitions requires permission to read the type's schema; changing them requires permission to manage the schema (schema.manage). An API key needs "read and write" access to make changes.

Methods

Types and fields

Method

Request

What it does

List types

GET /object-types

The workspace's types by key; include_archived=true includes archived ones

Create a type

POST /object-types

A new type, ready to use right away

Get a type

GET /object-types/{type}

The type and the list of its schema versions

Rename a type

PATCH /object-types/{type}

Change the name, the plural name or the icon

Delete a type

DELETE /object-types/{type}

Delete a type that nothing uses

Archive a type

POST /object-types/{type}/archive

Hide the type and forbid new objects

Add a field

POST /object-types/{type}/fields

A new field of the type

Create a schema draft

POST /object-types/{type}/schema-versions

The draft is a copy of the current version

Get a schema version

GET /schema-versions/{id}

The version with its fields

Update a draft

PATCH /schema-versions/{id}

Add, configure and remove fields

Publish a schema

POST /schema-versions/{id}/publish

Validate, make the version current and migrate objects if the changes are safe

Object migration plan

GET /object-types/{type}/schema-migration

Objects on old schema versions and what prevents migrating them

Migrate objects

POST /object-types/{type}/schema-migration

Move objects of all old versions to the current one, including on unsafe changes

Field tags

GET /object-types/{type}/fields/{field}/tags

Tags already used in a tags field — for suggestions

Enable subtasks

POST /object-types/{type}/subtasks

A "parent — subtasks" relation of the type with itself, plus its fields

{type} in the path is the type key or ID.

Presets and templates

Method

Request

What it does

Type presets

GET /type-presets

Ready-made type descriptions for the "New type" form

Create a type from a preset

POST /type-presets/{key}/apply

A type with all its fields, process, views and rules

Download a template

GET /templates/file

A type or the whole workspace as a template file

Create a type from a file

POST /templates/file/apply

A type from a downloaded template file

Relations, process, constraints

Method

Request

What it does

Relation types

GET /relation-types

All relation types; object_type= returns only the relations of one object type

Create a relation type

POST /relation-types

A relation between two object types

Type process

GET /object-types/{type}/lifecycle

The process, all its statuses and versions

Create a process draft

POST /object-types/{type}/lifecycle/versions

A new draft or the type's first process

Get a process version

GET /lifecycle-versions/{id}

Statuses and the transition graph

Update a process draft

PATCH /lifecycle-versions/{id}

Replace the statuses and the graph

Publish a process

POST /lifecycle-versions/{id}/publish

Validate and make the version current

Type constraints

GET /object-types/{type}/constraints

Rules that forbid operations

Create a constraint

POST /object-types/{type}/constraints

A new constraint or a draft of an existing one

Get a constraint version

GET /constraint-versions/{id}

The constraint version

Update a constraint draft

PATCH /constraint-versions/{id}

Edit the draft

Publish a constraint

POST /constraint-versions/{id}/publish

Validate and put into effect

Enable or disable

PATCH /constraints/{id}

{"enabled": false} — the constraint is not checked

Object types

POST /object-types:

{"key": "invoice", "name": "Invoice", "plural_name": "Invoices", "icon": null}

Field

Type

Required

Description

key

key

Yes

Machine name: lowercase Latin letters, digits and _, starts with a letter, up to 64 characters

name

string

Yes

Name, 1–200 characters

plural_name

string

Yes

Plural name

icon

string or null

No

Icon, up to 200 characters

A type is created ready to use: schema version 1 is published immediately, with only the built-in properties (title, status, assignee, dates). You can create objects, a process, constraints and automations right away. The response contains draft_version_id — a draft of version 2 for the type's own fields.

The response is the type:

Field

Description

id, key, name, plural_name, icon

Identity and names

system_key

Key of the system type from a template, or null

current_schema_version_id

The current published schema version — new objects are created on it

draft_version_id

The only schema draft, or null

lifecycle_definition_id

The type's process, or null

archived, archived_at

Archive

created_at, updated_at

Timestamps

GET /object-types/{type} also returns schema_versions — the schema versions, newest first: id, version, status, field_count, based_on_version_id, created_at, published_at.

Renaming a type

PATCH /object-types/{type} changes the type's name. Requires the schema.manage permission. Pass at least one field:

Field

Type

Description

name

string

Name, 1–200 characters

plural_name

string

Plural name, 1–200 characters

icon

string or null

Icon, up to 200 characters

curl -s -X PATCH https://flow.sensever.com/v1/object-types/task \
  -H "Authorization: Bearer $FLOW_KEY" -H "X-Workspace-Id: $WORKSPACE_ID" \
  -H "Content-Type: application/json" -H "Idempotency-Key: rename-task-1" \
  -d '{"name": "Purchase", "plural_name": "Purchases"}'

The response is the whole type. The key, objects, schema versions, views, automations and relations don't change: a type's key never changes after creation. Any other field in the body (key, system_key and so on) returns 422 VALIDATION_FAILED on that field. An archived type returns 409 OBJECT_TYPE_ARCHIVED. The base task type of the personal Main workspace cannot be renamed: 422 VALIDATION_FAILED, details.reason = system_type. The request supports Idempotency-Key.

POST /object-types/{type}/archive hides the type from navigation and forbids new objects; objects and history remain. Repeating it is safe.

DELETE /object-types/{type} deletes the type with all its versions and fields, as long as nothing uses it. System types and types referenced by objects or other definitions (process, views, constraints, automations, relation types, indexes) cannot be deleted: 422 with the reason type_in_use. Archive such a type instead. The response is {"deleted": true}.

Type presets

A preset is a ready-made type description for the "New type" form: fields, status process, views, actions, automations, reminders, processes and dashboards. The available presets are tasks ("Tasks"), purchases ("Purchases") and it_tasks ("IT tasks" — together with the "Sprint" type).

GET /type-presets?locale=ru returns the presets in form order. Requires permission to read the schema.

{
  "items": [
    {
      "key": "purchases",
      "name": "Purchases",
      "description": "Purchase requests: supplier, quantity, amount, invoice and due date…",
      "type": {"key": "purchase", "name": "Purchase", "plural_name": "Purchases", "icon": "shopping-cart"},
      "creates": {
        "object_types": [{"key": "purchase", "name": "Purchase", "plural_name": "Purchases", "icon": "shopping-cart", "fields": ["What to buy", "Quantity", "Supplier", "Amount"], "states": ["Request", "Pending approval", "Ordered"]}],
        "views": ["Board", "All purchases", "Pending approval"], "automations": ["Start approval"], "reminder_rules": ["…"], "processes": ["…"], "dashboards": ["…"]
      }
    }
  ]
}
  • locale — the language of names: ru (default), az, bn, de, en, es, fr, hi, id, it, ja, kk, ko, nl, pl, pt, th, tr, uk, uz, vi, zh.

  • type.key and the keys in creates.object_types are the ones the type would get in this workspace right now: a taken key gets the suffix _2, _3…

  • creates — what will be created: the names of each type's fields and statuses, and of the views, automations, reminders, processes and dashboards.

POST /type-presets/{key}/apply creates the preset's types with all their contents in a single transaction: an error at any step rolls everything back. The body is optional:

Field

Type

Description

type_name

string or null

Name of the main type, up to 200 characters; null — from the preset

plural_name

string or null

Plural name

key

string or null

Key of the main type; a taken key returns 422 VALIDATION_FAILED with the code key_exists. null — the suggested key

locale

string or null

Language of names

timezone

string or null

IANA time zone for reminders; null — the time zone of the workspace's business calendar

The response is 201: preset, locale, object_type (id, key, name, plural_name of the main type), object_types — all created types, the main one first, and applied — the completed steps. Keys of the other types, relations and processes get a suffix if they clash. The preset's automations and processes act on behalf of the workspace's "Automations" service member. Requires the schema.manage, view.manage, automation.manage and process.manage permissions — the owner and admins have them.

Template as a file

You can save your own type or the whole workspace as a file and use it to create a type in another workspace or a new workspace. The server doesn't store the files, and there is no shared template list.

GET /templates/file?kind=type&object_type=purchase downloads a template:

  • kind=type (default) — a single published type; object_type is its key or ID (required). The file includes fields, the status process, constraints, shared views, actions, automations, reminders, processes, relations of the type with itself and shared dashboards with its views;

  • kind=workspace — all published types of the workspace, processes without a type and shared dashboards.

The file contains no data: no objects, files, comments, members, personal views or dashboards. References to people are replaced with roles or the object's assignee; automations that call a webhook are left out of the file. The response:

{
  "file": {"format": "sensever-flow-template", "version": 1, "kind": "type", "name": "Purchases", "definition": {}},
  "skipped": [{"kind": "automation", "name": "Send to ERP", "object_type": "purchase", "reason": "webhook"}],
  "skipped_total": 1
}

Save file as is — that is the template. skipped lists what was left out: webhook, instance_reference (a reference to a person, an object or a custom role), outside_template, unpublished, disabled.

POST /templates/file/apply creates a type from the file in the current workspace — the same way as a preset:

{"file": {"format": "sensever-flow-template", "version": 1, "kind": "type", "name": "Purchases", "definition": {}}, "key": null, "type_name": null}

Besides file, you can pass type_name, plural_name, key and timezone, as with a preset. The response is 201: object_type, object_types and applied — the number of completed steps by kind. File errors return 422 VALIDATION_FAILED with the code invalid_file (not a template file), wrong_kind (a workspace file) or invalid_definition (a corrupted description); a description larger than 256 KB returns 422 LIMIT_EXCEEDED.

A workspace file is applied when creating a workspace: POST /workspaces with the template_file field instead of template (see Flow API: workspace, access and notifications). Names are taken from the file without translation.

Both methods require the schema.manage permission; applying also requires the permissions for each step, as with a preset.

Fields

A field is a stable entity of a type with a fixed key and data type. Field settings (label, required flag, options) live in schema versions.

Adding a field takes two steps:

  1. POST /object-types/{type}/fields creates the field: {"key": "amount", "data_type": "money"}. The response is 201 with the field id.

  2. PATCH /schema-versions/{draft} adds the field to the draft and configures it; then the draft is published.

Request field

Type

Required

Description

key

key

Yes

Field key within the type

data_type

string

Yes

Data type; cannot be changed after creation

relation_type

string

For relation

Relation type key or ID

relation_side

from or to

For relation

Which side of the relation the field represents

Data types

data_type

Value

Settings in config

string

String up to 1 KB

max_length

text

Text up to 100 KB

max_length

number

Number

min, max

integer

Integer

min, max (integers)

money

{"amount": "10.00", "currency": "EUR"}

scale — decimal places, 0–6, 2 by default; currencies — a list of ISO 4217 codes

boolean

true / false

—

date

YYYY-MM-DD

—

datetime

RFC 3339 time

—

enum

Option key

options — a required list of options

multi_enum

List of option keys

options, max_items

principal

Member UUID

—

multi_principal

List of member UUIDs

max_items

relation

Relation; the value is changed through the object's relations

—

json

Any JSON up to 64 KB

—

checklist

Checklist: a list of up to 100 items {id, text, done, done_by, done_at, rev}

—

tags

Tags: a list of up to 20 strings of 1–50 characters, no case-insensitive duplicates

max_items — 1 to 20

options is a non-empty list of up to 1000 options: strings or objects {"key": "high", "label": "High"}. Keys are unique, up to 255 bytes. max_items is 1 to 1000 (up to 20 for tags). Unknown config keys are stored as is — these are interface settings. Settings are validated on publishing.

How checklist and tags values are written and how to change individual checklist items is described in Flow API: objects, transitions and relations. Conditions on them are described in Flow API: query language and search.

Fields with a special meaning

Some Flow features recognize fields by key:

Key

Data type

Where it's used

due_date or due_at

date / datetime

Due date: "All objects" as a calendar, "By section", calendar subscription, the due filter in POST /me/objects/query. If the type has both, due_date is used

start_date or start_at

date / datetime

Start: the object is shown in the calendar and the subscription as a "start — due date" bar. If both exist, start_date is used

priority

enum

"By section": a type with a process that has a status of the done category, and with a due date or priority field, counts as a task

The tasks workspace template and the tasks type preset already contain the start_date, due_date and priority fields.

Field tags

GET /object-types/{type}/fields/{field}/tags?q=urg&limit=20 returns the tags of a tags field that are already set on objects of the type — for suggestions while typing:

{"items": [{"tag": "urgent", "count": 12}, {"tag": "customer", "count": 5}]}
  • Most frequent tags first; count is the number of non-archived objects of the type that you can read and that have this tag.

  • q is part of a tag, case-insensitive, up to 50 characters; limit is 1–100, 20 by default.

  • Only objects you are allowed to read are counted. A field without read permission returns 403 FIELD_NOT_READABLE; a field of another data type returns 422 VALIDATION_FAILED.

Subtasks

POST /object-types/{type}/subtasks is the "Enable subtasks" button in the type settings. A single call creates a relation type of the type with itself (many_to_one, acyclic, on_delete: unlink), the "Parent task" (parent) and "Subtasks" (subtasks) fields and, if the type has a process, the parent_open_subtasks constraint: a parent cannot be moved to a status of the done category while it has open subtasks. The body is optional: {"locale": "ru"} sets the language of the field labels. Taken keys get the suffix _2, _3…

Requires the schema.manage permission. The response is 200: created, relation_type, parent_field, children_field, draft, schema_version, constraint. If there is no schema draft, the fields are published right away as a new version; if there is a draft, they are added to it (draft: true), and you need to publish it. A type that already has subtasks enabled is returned unchanged with created: false. Subtask counters and details are described in Flow API: subtasks, checklists and recurrence.

Schema versions

A type has at most one schema draft. POST /object-types/{type}/schema-versions creates a draft — a copy of the current published version. If a draft already exists, you get 422 VALIDATION_FAILED with the reason draft_exists: take it from the type's draft_version_id.

PATCH /schema-versions/{id} changes the draft:

{
  "fields": [
    {
      "key": "amount",
      "label": "Amount",
      "description": "Invoice amount including VAT",
      "config": {"currencies": ["EUR", "USD"]},
      "is_required": true,
      "is_readonly": false,
      "position": 20
    },
    {
      "key": "priority",
      "label": "Priority",
      "config": {"options": [{"key": "low", "label": "Low"}, {"key": "high", "label": "High"}]},
      "default_value": "low"
    }
  ],
  "remove": ["legacy_code"]
}

fields item field

Type

Required

Description

key or field_id

string / UUID

One of the two

Which field is being configured

label

string

Yes

Label, 1–200 characters

description

string or null

No

Hint, up to 2000 characters

config

object

No

Settings for the data type

default_value

value

No

Default value; null — none

is_required

boolean

No

Required field

is_readonly

boolean

No

Read-only: editing the field is rejected with 422 FIELD_READONLY

position

integer

No

Order, 0–1,000,000

remove lists the keys or IDs of fields to remove from the draft. fields and remove together take up to 1000 items. A published version cannot be changed: 409 DEFINITION_IMMUTABLE.

POST /schema-versions/{id}/publish validates the draft and makes it the current version for new objects. All validation errors come back at once: 422 DEFINITION_INVALID with details.errors[]:

{
  "error": {
    "code": "DEFINITION_INVALID",
    "message": "…",
    "request_id": "…",
    "details": {
      "errors": [
        {"code": "invalid_config", "path": "fields.priority.config.options", "message": "options must be a non-empty list of options (up to 1000)"}
      ]
    }
  }
}

path is the location of the error in the definition; expression errors also include offset, line and column.

Objects on an old version

Each object stores its schema version (schema_version_id) and shows the fields of that version. After publishing, Flow compares each old published version that still has objects with the new one.

Safe changes — objects are migrated automatically. In the same transaction as the publish, a schema_migration background operation starts for each such version on behalf of the publisher. Safe changes are: new optional fields and relation fields, new required fields with a default value (objects get that value), labels, descriptions, order, is_readonly, default_value, indexes, new enum/multi_enum options and currencies, widened config limits. The type's earlier unfinished migrations are cancelled on publishing: they were heading to the previous version.

Unsafe changes — objects stay on their version until explicitly migrated:

code

What changed

field_removed

The field is missing from the new version

required_field_added

A new required field without default_value

field_made_required

An optional field became required

type_changed

The key has a different data type or a different field

enum_options_removed

Options were removed; details.options (up to 5) and details.options_total

config_narrowed

A limit was narrowed: details.key is max_length, max_items, min, max, scale or currencies

The POST /schema-versions/{id}/publish response is the schema version with an extra migration field (the migration plan, or null if no objects are on old versions). With Prefer: return=minimal, the migration field is present in the compact response too. The plan (SchemaMigrationPlan):

{
  "object_type_id": "…",
  "current_version_id": "…",
  "current_version": 4,
  "stale_objects": 130,
  "migrating_objects": 120,
  "pending_objects": 10,
  "started_operation_ids": ["…"],
  "versions": [
    {"version_id": "…", "version": 3, "objects": 120, "safe": true, "changes": [], "changes_total": 0,
     "operation_id": "…", "operation_status": "queued"},
    {"version_id": "…", "version": 1, "objects": 10, "safe": false,
     "changes": [{"code": "field_removed", "field_key": "legacy_code", "label": "Old code"}],
     "changes_total": 1, "operation_id": null, "operation_status": null}
  ],
  "versions_total": 2
}
  • stale_objects — all objects on old versions; migrating_objects — those on versions currently being migrated to the current one; pending_objects — the rest, which only an explicit command migrates.

  • versions — newest versions first, no more than 10 (versions_total is the full count); each version lists no more than 10 changes (changes_total is the full count), and label is truncated to 80 characters.

  • started_operation_ids — operations started by this call. Track an operation's progress with GET /operations/{id}.

GET /object-types/{type}/schema-migration returns the same plan at any time (requires permission to read or manage the type's schema) — for example, for objects left on old versions from earlier publishes.

POST /object-types/{type}/schema-migration without a body is an explicit migration (schema.manage, supports Idempotency-Key; an archived type returns 409 OBJECT_TYPE_ARCHIVED). For each old version with objects, a schema_migration to the current version starts, including on unsafe changes:

  • fields missing from the current version are removed from the object's data; the previous values remain in the object's history (GET /objects/{id}/history), and webhooks receive object.updated;

  • an object that fails validation against the current version (a missing required value, a removed option, a narrowed limit, a different type) or violates a type rule stays on its version and appears in GET /operations/{id}/errors. Fix it and call the migration again;

  • a version that is already being migrated to the current one is not started again: the response is the same plan with an empty started_operation_ids.

The response is the plan. A version with no objects left is retired (retired, see below). You can also start a schema_migration operation manually through POST /operations — with your own set and unset; see Flow API: views, export, import and background operations.

Relation types

POST /relation-types:

{
  "key": "project",
  "name": "Project",
  "inverse_name": "Tasks",
  "from_type": "task",
  "to_type": "project",
  "cardinality": "many_to_one",
  "on_delete": "restrict",
  "version_bump": "none"
}

Field

Type

Required

Description

key

key

Yes

Relation key

name

string

Yes

Name on the from side

inverse_name

string

Yes

Name on the to side

from_type, to_type

string

Yes

Object type keys or IDs

cardinality

string

Yes

one_to_one, one_to_many, many_to_one, many_to_many

on_delete

string

No

What to do with relations when from is archived: restrict (forbid, the default), cascade (archive the related objects), unlink (break the relation)

version_bump

string

No

Whose version increases when the relation changes: none (default), from, to, both

is_acyclic

boolean

No

Only for a relation of a type with itself: forbids cycles (for example, "blocks")

GET /relation-types returns relation types by key; object_type keeps the relations where this object type is on either side.

Status process

There is one process (lifecycle) per type. It consists of statuses and the transitions between them, and it is versioned too.

Reading

GET /object-types/{type}/lifecycle returns:

  • definition — the process: id, name, current_version_id, draft_version_id;

  • states — all statuses the process has ever had (id, key, category); views and filters refer to their id;

  • versions — versions, newest first.

A type without a process returns 404 NOT_FOUND.

GET /lifecycle-versions/{id} returns a version: states (with name, position, color, is_initial) and graph.

Statuses and categories

A status is described by a key and a category:

{"key": "review", "name": "In review", "category": "in_progress", "color": "#f5a623", "position": 30, "is_initial": false}

Field

Type

Required

Description

key

key

Yes

Status key

category

string

Yes

open, in_progress, done or cancelled

name

string

No

Name; defaults to the key

color

string or null

No

#rrggbb or a color token

position

integer

No

Column order

is_initial

boolean

No

Initial status; publishing requires exactly one

The key and category are the status's permanent identity: a status appears the first time its key is used, and its category never changes after that (422 VALIDATION_FAILED, code state_category_immutable). To change the category, create a new status and move the objects. The category matters: it tells Flow that work is finished (done) or cancelled (cancelled) — filters, completion notifications, reports and SLA rely on it.

Graph

graph holds the transitions and SLAs:

{
  "transitions": [
    {
      "key": "approve",
      "name": "Approve",
      "from": ["review"],
      "to": "approved",
      "guards": [
        {"key": "has_amount", "expr": "data.amount.amount > 0", "code": "AMOUNT_REQUIRED", "message": "The amount must be greater than zero"}
      ],
      "required_fields": ["amount"],
      "form_fields": ["approval_comment"],
      "emit": ["invoice.approved"]
    }
  ],
  "sla": [
    {"key": "review_time", "state": "review", "duration": "PT8H", "business_hours": true}
  ]
}

Transition field

Description

key, name

Transition key and name

from

Statuses the transition can start from

to

The status it leads to

guards

Conditions: an expression expr, plus the refusal code code and text message. The expression language is described in Flow API: automations, reminders and expressions

required_fields

Fields that must be filled in after the transition

form_fields

Fields filled in on the transition form

emit

Custom events: the transition publishes custom.<key>

Who can perform a transition is set by role permissions, not by the graph.

An SLA is a time limit for staying in a status: key, state, duration in ISO 8601 format (P14D, PT8H) and business_hours. With business_hours: true, working time is counted by the workspace's business calendar, and the duration is set only in hours, minutes and seconds (PT8H). Without it, calendar time is counted. For details, see Flow API: reports, SLA and business calendar.

The graph is limited to 256 KB. Unknown fields are stored as is: this is how the interface stores the block layout (layout) and the "from any status" flag (any_from).

Draft and publishing

POST /object-types/{type}/lifecycle/versions with {"name": "Invoice process", "states": […], "graph": {…}} creates a draft. If the type has no process yet, the process itself is created too (the default name is the type name), and the draft gets number 1. If states and graph are not passed, the draft copies the current version. A process has one draft: a second one returns 422 with the reason draft_exists. Up to 200 statuses.

PATCH /lifecycle-versions/{id} replaces states entirely and/or graph; whatever you don't pass stays the same. A published version returns 409 DEFINITION_IMMUTABLE. The draft is checked only for shape; the graph is validated on publishing.

POST /lifecycle-versions/{id}/publish validates and publishes the draft. All errors come back at once: 422 DEFINITION_INVALID with details.errors[]. Non-critical remarks — unreachable statuses, a transition condition that duplicates an active constraint — come in warnings.

Moving objects to a new version

New objects are created on the new process version; existing ones stay on theirs. To move them, use the lifecycle_migration operation:

POST /v1/operations
Idempotency-Key: migrate-invoice-lc-3
{
  "kind": "lifecycle_migration",
  "params": {
    "from_version_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6c10",
    "to_version_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6c11",
    "mapping": {"draft": "new", "checking": "review"}
  }
}

to_version_id defaults to the current version. mapping says where to move objects from statuses that no longer exist: {old_key: new_key}. If there are objects in statuses not covered by the mapping, you get 422 MIGRATION_MAPPING_INCOMPLETE with a details.missing_states[] list. Track the operation's progress with GET /operations/{id}.

Constraints

A constraint forbids an operation on an object if an expression is true. For example, you can't close a deal without an amount — no matter how: through the interface, the API, an import or an automation.

POST /object-types/{type}/constraints:

{
  "key": "amount_required_on_win",
  "name": "Amount is required to win",
  "operations": ["transition"],
  "transition_keys": ["win"],
  "violation_when": "is_empty(data.amount)",
  "error_code": "AMOUNT_REQUIRED",
  "error_message": "Enter the deal amount",
  "priority": 100
}

Field

Type

Required

Description

key

key

Yes

Constraint key

name

string

Yes

Name

operations

array

Yes

When to check: create, update, archive, restore, transition, relation.add, relation.remove

transition_keys

array or null

No

Only with transition: which transitions; null — all

violation_when

string

Yes

Expression, up to 4096 characters; true forbids the operation

error_code

string

Yes

Error code: uppercase letters, digits and _, 3–64 characters

error_message

string

Yes

Text shown to the user

priority

integer

No

Order of checking and output, 100 by default

If there is no constraint with this key, a constraint (enabled) and a draft of version 1 are created. If there is one, a new draft of that constraint is created; there can be only one draft (draft_exists). The draft's shape is checked immediately, the expression on publishing.

POST /constraint-versions/{id}/publish compiles the expression and puts the version into effect immediately; the previous version is retired. Errors return 422 DEFINITION_INVALID. A condition that duplicates a transition condition of the current process ends up in warnings.

PATCH /constraints/{id} with {"enabled": false} turns the constraint check off; true turns it on.

A violation during an operation on an object returns 422 CONSTRAINT_VIOLATION with details.violations[]: constraint_key, code (your error_code) and message.

Retiring old versions

A version's status is draft, published or retired. A published schema or process version is retired (retired) automatically when it is not current and has no objects left: after a successful migration and by a background check once every 24 hours. For a process, only non-archived objects count; for a schema, all objects count, including archived ones. You don't need to, and cannot, retire versions manually.

What this means for integrations:

  • new objects are always created on the current version;

  • an archived object on a retired process version can be restored and stays on that version until migrated;

  • an object on a retired schema version cannot be restored — 409 OBJECT_TYPE_ARCHIVED.

Constraint and automation versions are retired immediately when a new version is published.

Compact responses

Definitions can be large: a schema with hundreds of fields, a process with dozens of transitions. Commands that change them can return a compact result instead of the full definition. This applies to:

Definitions

Commands

Schema

POST /object-types/{type}/schema-versions, PATCH /schema-versions/{id}, POST /schema-versions/{id}/publish

Status process

POST /object-types/{type}/lifecycle/versions, PATCH /lifecycle-versions/{id}, POST /lifecycle-versions/{id}/publish

Views

POST /object-types/{type}/views, PATCH /views/{id}, DELETE /views/{id}

Roles

POST /workspace/roles, PATCH /workspace/roles/{id}, PUT /workspace/roles/{id}/permissions

Automations

POST /object-types/{type}/automations, PATCH /automations/{id}, POST /automations/{id}/versions, PATCH /automation-versions/{id}, POST /automation-versions/{id}/publish

Processes

POST /processes, POST /processes/{key}/versions, PATCH /process-versions/{id}, POST /process-versions/{id}/publish

Pass the Prefer: return=minimal header to get a compact response with the Preference-Applied: return=minimal header:

{
  "representation": "minimal",
  "resource": "schema_version",
  "id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6c20",
  "version": 3,
  "status": "published",
  "href": "/v1/schema-versions/0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6c20"
}
  • resource — schema_version, lifecycle_version, view, automation, automation_version, role, process or process_version. New values may appear.

  • status — draft, published, retired for versions; active, archived for views and processes; enabled, disabled, archived for automations; active for roles.

  • version — null for definitions without a version number (view, automation, role, process).

  • Automations and processes have current_version_id and draft_version_id; their versions have definition_id.

  • For the full definition, call GET href.

Without the header, the server returns the full definition if it is no larger than 64 KB, and otherwise the same compact result, but without Preference-Applied. So when you read a response without Prefer, check the representation field: if it equals minimal, fetch the definition from href. A process publish in compact form also returns the first 50 warnings and their total count, warnings_total.

Prefer is part of the Idempotency-Key fingerprint: a repeat with the same key returns a response of the same shape, and the same key with a different Prefer returns 422 IDEMPOTENCY_KEY_REUSED.

What's next

コメント

著者