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

Template search

POST /v1/bizproc-templates/search

Selects business process templates that match the specified conditions and returns them as a list. Unlike the template list, this method takes the selection conditions in the request body, so a complex filter does not have to fit into the query string.

Request fields (body)

Field Type Default Description
Fieldfilter Typeobject Default— DescriptionFiltering by the fields of GET /v1/bizproc-templates/fields.
Filtering syntax. Example: { "entity": "CCrmDocumentLead" }.
The values of moduleId and entity are the first two elements of documentType, listed in Upload a template
Fieldselect Typestring[] Default— DescriptionFields in the response: id, moduleId, entity, documentType, autoExecute, name, description, modified, isModified, userId. Without select, the full declared field set is returned
Fieldorder Typeobject Default— DescriptionSorting. Example: { "id": "desc" }
Fieldlimit Typenumber Default50 DescriptionNumber of records in the response, up to 5000. Zero does not mean "no limit" — it is ignored. The response contains 50 records and the LIMIT_ZERO_IGNORED warning
Fieldoffset Typenumber Default0 DescriptionOffset from the start of the selection
FieldautoWindow Typeboolean Defaulttrue DescriptionSplit the selection into weekly windows when the filter covers a modified range wider than 14 days. false disables the split

Examples

Templates can be searched only with an authorization key — both examples send the 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 POST "https://vibecode.bitrix24.com/v1/bizproc-templates/search" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "moduleId": "crm" },
    "select": ["id", "name", "entity", "autoExecute"],
    "order": { "id": "desc" },
    "limit": 3
  }'

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/bizproc-templates/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { moduleId: 'crm' },
    select: ['id', 'name', 'entity', 'autoExecute'],
    order: { id: 'desc' },
    limit: 3,
  }),
})

const { success, data, meta } = await res.json()
console.log(`Templates found: ${meta.total}`)

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionArray of templates. The fields of each element are defined by select. For the full schema, see Template fields. The templateData template file is not returned in responses
Fieldmeta.total Typenumber DescriptionNumber of templates matching the filter
Fieldmeta.hasMore Typeboolean DescriptionWhether there are records beyond limit
Fieldmeta.durationMs Typenumber DescriptionRequest duration in milliseconds
Fieldmeta.warnings Typearray DescriptionWarnings about how the request was parsed. Each one is an object with the code, field, and message fields, for example an unknown field name in select with the UNKNOWN_SELECT_FIELD code
Fieldmeta.autoWindowed Typeboolean Descriptiontrue if the selection was split into time windows
Fieldmeta.windowCount Typenumber DescriptionNumber of windows the date range was split into. Returned when autoWindowed is true
Fieldmeta.batchWaves Typenumber DescriptionNumber of parallel request waves used when splitting into windows

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": 1237,
      "name": "Contract approval",
      "entity": "CCrmDocumentDeal",
      "autoExecute": 1
    },
    {
      "id": 1153,
      "name": "Purchase request",
      "entity": "CCrmDocumentDeal",
      "autoExecute": 0
    },
    {
      "id": 1143,
      "name": "Inquiry processing",
      "entity": "CCrmDocumentLead",
      "autoExecute": 0
    }
  ],
  "meta": {
    "total": 18,
    "hasMore": true,
    "durationMs": 113
  }
}

Error response example

403 — the request was sent with an API key:

JSON 
{
  "success": false,
  "error": {
    "code": "OAUTH_REQUIRED",
    "message": "bizproc-templates 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
HTTP400 CodeINVALID_FILTER_OPERATOR DescriptionAn unknown operator in the filter. The message lists the supported operators
HTTP400 CodeINVALID_FILTER_OPERATOR DescriptionA logical key $or or $and in the filter. An OR condition is expressed with the $in operator for one field or with parallel requests through POST /v1/batch, an AND condition with sibling keys of one filter
HTTP400 CodeUNSTABLE_OFFSET_PAGINATION Descriptionoffset greater than zero together with a date-range filter wider than 14 days. Two different retrieval algorithms produce inconsistent results, so the request is rejected. Fetch everything in a single request with limit up to 5000, or pass autoWindow: false with sorting by id, or split the date range into parts yourself
HTTP403 CodeOAUTH_REQUIRED DescriptionThe request was sent with an API key. Templates can be searched only with 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
HTTP409 CodeBIZPROC_MODULE_NOT_ENABLED DescriptionBusiness Processes are not available on the account: the module is not included in the plan, or it is switched off in account settings. Ask an account administrator to enable Business Processes — until then, retrying returns the same error
HTTP429 CodeRATE_LIMITED DescriptionRate limit exceeded: 300 requests per minute per portal. All API keys of the portal share one limit. The current limit is returned in the x-ratelimit-limit header. Retry after the delay in the Retry-After header

For the full list of common API errors, see Errors.

Known specifics

The identifier must be listed in select explicitly. id is not added to the selected fields — if it is needed for a later update or delete, include it in select yourself.

When the selection is split into windows, meta.total counts only the windows that were read. A modified range filter wider than 14 days reads the selection in weekly windows and stops once it has collected limit records: meta.total then carries the count from the windows already read, which is lower than the full count. The exact count comes from a request with autoWindow: false or from reading the whole selection in one request with limit up to 5000.

An unknown field name does not interrupt the request. In filter the result set is not narrowed, in order the sort order does not change, in select the field is absent from the records, and a warning with the UNKNOWN_SELECT_FIELD code is returned in meta.warnings. Check field names against the schema at GET /v1/bizproc-templates/fields.

See also