## Template fields

`GET /v1/bizproc-templates/fields`

Returns the field schema of a business process template: the type of each field, whether it is writable, and whether it is required on creation. The response describes the schema and does not query the contents of the templates in your Bitrix24 account.

## Examples

The schema can be read 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](/docs/keys-auth#passing-the-key).

### curl — authorization key

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

### JavaScript — authorization key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/bizproc-templates/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

| Field | Type | Description |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data.fields` | object | Field schema: the key is the field name, the value is its description |
| `data.fields.<field>.type` | string | Value type: `number`, `string`, `array`, `datetime`, `boolean` |
| `data.fields.<field>.readonly` | boolean | `true` — the field is filled by the system and is not passed in write requests |
| `data.fields.<field>.required` | boolean | Present only for fields that are required on creation |
| `data.batch` | array | Entity operations available in [`POST /v1/batch`](/docs/batch) |

Schema composition:

| Field | Type | RO | Description |
|------|-----|:--:|---------|
| `id` | number | RO | Template identifier |
| `moduleId` | string | | Module the template is bound to: `lists`, `crm`, `disk`, `bizproc` |
| `entity` | string | | Document object inside the module, for example `BizprocDocument` |
| `documentType` | array | | Document type as three elements — module, object, type |
| `templateData` | array | | Template file — file name and base64 content. Required on creation, never returned in read responses |
| `autoExecute` | number | | Auto-start condition: `0` — no auto-start, `1` — on document creation, `2` — on change, `3` — on creation and change |
| `name` | string | | Template name |
| `description` | string | | Template description |
| `modified` | datetime | RO | Date of the last change |
| `isModified` | boolean | RO | Whether the template was edited after the file was uploaded |
| `userId` | number | | Author of the last change. List: `GET /v1/users` |

## Response example

```json
{
  "success": true,
  "data": {
    "fields": {
      "id": { "type": "number", "readonly": true },
      "moduleId": { "type": "string", "readonly": false },
      "entity": { "type": "string", "readonly": false },
      "documentType": { "type": "array", "readonly": false },
      "templateData": { "type": "array", "readonly": false, "required": true },
      "autoExecute": { "type": "number", "readonly": false },
      "name": { "type": "string", "readonly": false },
      "description": { "type": "string", "readonly": false },
      "modified": { "type": "datetime", "readonly": true },
      "isModified": { "type": "boolean", "readonly": true },
      "userId": { "type": "number", "readonly": false }
    },
    "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-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 |
|------|-----|----------|
| 403 | `OAUTH_REQUIRED` | The request was sent with an API key. The schema is available only to an authorization key |
| 401 | `TOKEN_MISSING` | Authorization key without the `Authorization: Bearer` header |
| 401 | `WRONG_AUTH_SCHEME` | The authorization key was sent in the `Authorization: Bearer` header. The key goes in `X-Api-Key`, while `Authorization: Bearer` carries the session token |
| 401 | `INVALID_SESSION` | The session token has expired or is invalid — authorize again |
| 403 | `SCOPE_DENIED` | The key lacks the `bizproc` scope |

Full list of common API errors — [Errors](/docs/errors).

## Known specifics

**A `readonly: false` mark does not mean the field can be changed.** An update applies only `name`, `description`, `autoExecute`, and `templateData` — see [Update a template](./update.md). The other fields without a `readonly` mark — `moduleId`, `entity`, `documentType`, `userId` — are set when the file is uploaded, and a request to change them returns `200` with no effect.

**The absence of a `readonly` mark does not mean the field can be read.** `templateData` has `readonly: false`, but the field is not returned — neither in the list nor through `select` — it is write-only.

**The `required: true` mark is set on `templateData` only, although an upload requires three fields.** The schema reflects the check performed on the Vibecode side: without `templateData` the request is rejected immediately with the `MISSING_REQUIRED_FIELDS` code. A missing `name` or `documentType` passes that check and is rejected one step later, with the `BITRIX_ERROR` code. The full list of required upload fields is on the [Upload a template](./create.md) page.

## See also

- [Template list](/docs/entities/bizproc-templates/list)
- [Upload a template](/docs/entities/bizproc-templates/create)
- [Update a template](/docs/entities/bizproc-templates/update)
- [Delete a template](/docs/entities/bizproc-templates/delete)
- [Keys and authorization](/docs/keys-auth)