For AI agents: markdown of this page — /docs-content-en/entities/bizproc-robots/fields.md documentation index — /llms.txt

Automation rule fields

GET /v1/bizproc-robots/fields

Returns the field schema of an automation rule: the type of each field, whether it is writable, whether it is required for registration, its label and its description. The response describes the schema and does not query the automation rules registered in your Bitrix24 account.

Examples

The schema can be read only with an authorization key — both examples send an authorization key and the Authorization: Bearer header. The session token is issued by OAuth authorization, is valid for 24 hours, and cannot be renewed — Passing the key.

curl — OAuth application

Terminal 
curl -X GET "https://vibecode.bitrix24.com/v1/bizproc-robots/fields" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/bizproc-robots/fields', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data } = await res.json()
console.log(Object.keys(data.fields))

Response fields

The label and description field captions are returned in English. Request headers do not switch the language.

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.fields Typeobject DescriptionField schema: the key is the field name, the value is its description
Fielddata.fields.<name>.type Typestring DescriptionValue type: string, number, object, array
Fielddata.fields.<name>.readonly Typeboolean Descriptiontrue — the field is filled in by the system and is not passed in write requests
Fielddata.fields.<name>.required Typeboolean DescriptionPresent only on fields that are required for registration
Fielddata.fields.<name>.label Typestring DescriptionShort field label
Fielddata.fields.<name>.description Typestring DescriptionExtended field description
Fielddata.batch Typearray DescriptionEntity operations available in POST /v1/batch

Schema composition:

Field Type RO Required Description
Fieldcode Typestring RO Requiredyes DescriptionUnique automation rule code. Serves as the identifier in update and delete paths
Fieldhandler Typestring RO Requiredyes DescriptionAutomation rule handler URL
Fieldname Typestring RO Requiredyes DescriptionAutomation rule name
Fielddescription Typestring RO Requiredno DescriptionAutomation rule description
FieldauthUserId Typenumber RO Requiredno DescriptionThe user whose token is passed to the app when the automation rule is called. List: GET /v1/users
FielduseSubscription Typestring RO Requiredno DescriptionWhether to wait for the app's response before the process continues: Y or N
Fieldproperties Typeobject RO Requiredno DescriptionAutomation rule input parameters
FieldreturnProperties Typeobject RO Requiredno DescriptionAutomation rule output parameters
FielddocumentType Typearray RO Requiredno DescriptionThe document type the automation rule applies to — an array of three elements: module, object, type. Valid combinations: Register an automation rule
Fieldfilter Typeobject RO Requiredno DescriptionINCLUDE and EXCLUDE rules by document type
FieldusePlacement Typestring RO Requiredno DescriptionWhether to open the automation rule settings in a slider panel: Y or N
FieldplacementHandler Typestring RO Requiredno DescriptionURL of the settings slider panel

Response example

JSON 
{
  "success": true,
  "data": {
    "fields": {
      "code": {
        "type": "string",
        "readonly": false,
        "required": true,
        "label": "Code",
        "description": "Unique robot code. Used as the identifier in update and delete paths."
      },
      "handler": {
        "type": "string",
        "readonly": false,
        "required": true,
        "label": "Handler URL",
        "description": "URL of the robot handler."
      },
      "name": {
        "type": "string",
        "readonly": false,
        "required": true,
        "label": "Name",
        "description": "Robot name."
      },
      "description": {
        "type": "string",
        "readonly": false,
        "label": "Description",
        "description": "Robot description."
      },
      "authUserId": {
        "type": "number",
        "readonly": false,
        "label": "Auth user ID",
        "description": "User whose token is passed to the app on invocation. List via GET /v1/users."
      },
      "useSubscription": {
        "type": "string",
        "readonly": false,
        "label": "Use subscription",
        "description": "Whether to wait for the app's response before continuing the process: Y or N."
      },
      "properties": {
        "type": "object",
        "readonly": false,
        "label": "Properties",
        "description": "Robot input parameters."
      },
      "returnProperties": {
        "type": "object",
        "readonly": false,
        "label": "Return properties",
        "description": "Robot output parameters."
      },
      "documentType": {
        "type": "array",
        "readonly": false,
        "label": "Document type",
        "description": "Document type the robot applies to."
      },
      "filter": {
        "type": "object",
        "readonly": false,
        "label": "Filter",
        "description": "INCLUDE and EXCLUDE rules by document type."
      },
      "usePlacement": {
        "type": "string",
        "readonly": false,
        "label": "Use placement",
        "description": "Open robot settings in a slide-out panel: Y or N."
      },
      "placementHandler": {
        "type": "string",
        "readonly": false,
        "label": "Placement handler",
        "description": "URL of the settings slide-out panel."
      }
    },
    "batch": ["create", "update", "delete"]
  }
}

Error response example

403 — the request was sent with an API key:

JSON 
{
  "success": false,
  "error": {
    "code": "OAUTH_REQUIRED",
    "message": "bizproc-robots require an OAuth app key (vibe_app_*) with an Authorization: Bearer session — a personal vibe_api_* key lacks the per-user OAuth context Bitrix24 needs for these methods. Create an OAuth app (POST /v1/apps) and retry with its key. On this 403 switch keys — do NOT delete or recreate the app (that discards anything already registered under it, e.g. a bizproc robot you just registered)."
  }
}

Errors

HTTP Code Description
HTTP403 CodeOAUTH_REQUIRED DescriptionThe request was sent with an API key. The schema is available only to an authorization key
HTTP401 CodeTOKEN_MISSING DescriptionAuthorization key without the Authorization: Bearer header
HTTP401 CodeWRONG_AUTH_SCHEME DescriptionThe authorization key was sent in the Authorization: Bearer header. The key goes in X-Api-Key, while Authorization: Bearer carries the session token
HTTP401 CodeINVALID_SESSION DescriptionThe session token has expired or is invalid — authorize again
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the bizproc scope
HTTP429 CodeRATE_LIMITED DescriptionRate limit exceeded: 300 requests per minute per portal, all API keys of the portal share one limit. The exact value arrives in the x-ratelimit-limit header (the cap is divided across replicas). Retry after the delay in the Retry-After header

The full list of common API errors — Errors.

Known specifics

The schema is the same for automation rules and activities. Both entities are described by the same set of twelve fields — only their meaning differs.

See also