Kaiten API

KaitenDevelopers

rest external webhooks webhooks scim user metadata imports addons

Update custom directory

PATCH

https://example.kaiten.ru/api/latest/company/custom-directories/{directory_id}

This endpoint is currently under active development. Parameters, attributes, and response formats are subject to change. Custom directories API is in beta and may change.

Updates directory attributes and/or fields. If `fields` is provided, it should contain the full fields list; omitted fields are soft-deleted (condition=removed). To choose a display field, set `is_display=true` for exactly one field in the list.

Requires custom-properties management permission. Send expected_field_ids together with fields to detect a changed field list (HTTP 409, code 16). This is not a general version check. Changing a field's type or a non-empty select/catalog/directory-link binding is rejected with HTTP 400, code 15, when the field has record values. The response contains fields and author.

Path parameters

Name	Type	Reference
directory_idrequired	string	Directory ID

Headers

Name	Value
Content-Type	application/json

Attributes

schema

{
 "$schema": "http://json-schema.org/draft-06/schema",
 "type": "object",
 "properties": {
  "name": {
   "type": "string",
   "minLength": 1,
   "maxLength": 256,
   "description": "Custom directory name"
  },
  "description": {
   "oneOf": [
    {
     "type": "null",
     "description": "No description"
    },
    {
     "type": "string",
     "description": "Custom directory description"
    }
   ]
  },
  "condition": {
   "enum": [
    "active",
    "inactive",
    "removed"
   ],
   "description": "Custom directory condition"
  },
  "multi_select": {
   "type": "boolean",
   "description": "Allow selecting multiple directory records in a card's directory custom property"
  },
  "allow_editing": {
   "type": "boolean",
   "description": "When enabled, directory records can be edited from cards without custom properties permission"
  },
  "expected_field_ids": {
   "type": "array",
   "items": {
    "type": "string",
    "format": "uuid"
   },
   "description": "Optional snapshot of all active and inactive field IDs returned when the directory was loaded. Checked only when fields is supplied. A mismatch returns HTTP 409 with code 16; reload before retrying. This checks field membership, not concurrent edits to field attributes."
  },
  "fields": {
   "type": "array",
   "description": "Full active and inactive fields list. Omitted fields are soft-deleted (condition=removed); an empty array removes all fields. Include existing IDs to update fields and omit IDs for new fields. Supply complete field definitions: omitted required/is_display flags become false, bindings become null and sort_order defaults to the array index. Omit fields entirely to leave the schema unchanged.",
   "items": {
    "type": "object",
    "properties": {
     "id": {
      "type": "string",
      "format": "uuid",
      "description": "Field ID (for updating an existing field)"
     },
     "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256,
      "description": "Field name"
     },
     "type": {
      "enum": [
       "string",
       "number",
       "date",
       "email",
       "url",
       "phone",
       "checkbox",
       "select",
       "user",
       "catalog",
       "directory_link",
       "file"
      ],
      "description": "Field type"
     },
     "required": {
      "type": "boolean",
      "description": "Required field flag"
     },
     "is_display": {
      "type": "boolean",
      "description": "Display field flag (only one field should have is_display=true)"
     },
     "sort_order": {
      "type": "integer",
      "minimum": 0,
      "description": "Field position"
     },
     "custom_property_uid": {
      "oneOf": [
       {
        "type": "null",
        "description": "Empty custom property reference"
       },
       {
        "type": "string",
        "format": "uuid",
        "description": "Custom property UID (required for select/user/catalog fields)"
       }
      ]
     },
     "linked_directory_id": {
      "oneOf": [
       {
        "type": "null",
        "description": "Empty linked directory reference"
       },
       {
        "type": "string",
        "format": "uuid",
        "description": "Linked custom directory ID (required for directory_link fields)"
       }
      ]
     }
    }
   }
  }
 }
}

Name	Type	Constraints	Description
name	string	minLength: 1 maxLength: 256	Custom directory name
description	null		No description
description	string		Custom directory description
condition	enum	[active,inactive,removed]	Custom directory condition
multi_select	boolean		Allow selecting multiple directory records in a card's directory custom property
allow_editing	boolean		When enabled, directory records can be edited from cards without custom properties permission
expected_field_ids	array of strings		Optional snapshot of all active and inactive field IDs returned when the directory was loaded. Checked only when fields is supplied. A mismatch returns HTTP 409 with code 16; reload before retrying. This checks field membership, not concurrent edits to field attributes.
fields	array of objects Schema		Full active and inactive fields list. Omitted fields are soft-deleted (condition=removed); an empty array removes all fields. Include existing IDs to update fields and omit IDs for new fields. Supply complete field definitions: omitted required/is_display flags become false, bindings become null and sort_order defaults to the array index. Omit fields entirely to leave the schema unchanged.

Responses

200

Description	Response type	Example
Success	Object	Open

Response Attributes

Name	Type	Description
id	string	Directory ID (UUID)
name	string	Directory name
description	null \| string	Directory description
condition	enum	Directory condition: active \| inactive \| removed
settings	object	Directory settings
fields	array of objects	Directory fields
author	object	Author user object

400

Description	Response type	Example
Validation error	Object	Open

Response Attributes

Name	Type	Description
message	string	Error message
code	integer	Error code (customDirectoryErrorCodes)

409

Description	Response type	Example
The current field ids differ from expected_field_ids. reload the directory before retrying.	Object	Open

A schema has not been defined for this response code.

401

Description	Response type	Example
Invalid token	String	Open

404

Description	Response type	Example
Not found	Object	Open

A schema has not been defined for this response code.

Kaiten

Addons terms of use Personal data processing policy

If you have any questions or need help with integration feel free to write us at support@kaiten.ru

Company domain

Path Parameters

directory_id

Raw Body(json format)

  1  curl --request PATCH \
  2       --url 'https://example.kaiten.ru/api/latest/company/custom-directories/{directory_id}' \
  3       --header 'Accept: application/json' \
  4       --header 'Content-Type: application/json'
  5

Response

ClickTry It!to start a request and see the response here!