لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/apps/endpoints.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

App management

Manage the OAuth applications of a Bitrix24 account: create, read, update, delete, and publish to the catalog. Switch methods in the tabs — each has its own parameters, response fields, and error codes.

Base URL: https://vibecode.bitrix24.com/v1 | Authorization: X-Api-Key | Scope for publishing: placement

List applications

GET /v1/apps

Returns the Bitrix24 account applications registered by the current API key, with pagination.

Parameters

Parameter Type Required Default Description
Parameterpage (query) Typenumber RequiredNo Default1 DescriptionPage number, from 1. A value below 1 or non-numeric is replaced with 1
Parameterlimit (query) Typenumber RequiredNo Default50 DescriptionPage size. Maximum 200. A value of 0, negative, or non-numeric is replaced with 50

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/apps?page=1&limit=50" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/apps?page=1&limit=50" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/apps?page=1&limit=50', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data, total } = await res.json()
console.log(`Applications: ${total}`, data)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/apps?page=1&limit=50', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data, total } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionArray of applications
Fielddata[].id Typestring DescriptionApplication identifier
Fielddata[].title Typestring DescriptionName
Fielddata[].description Typestring | null DescriptionDescription
Fielddata[].scopes Typestring[] DescriptionBitrix24 scopes assigned to the application key
Fielddata[].handlerUrl Typestring DescriptionHandler address on the platform side. Details — Applications
Fielddata[].appUrl Typestring | null DescriptionApplication address on Black Hole. Before publishing — null
Fielddata[].redirectUris Typestring[] DescriptionAllowed OAuth return addresses
Fielddata[].bitrixClientId Typestring | null DescriptionOAuth client identifier in the Bitrix24 account
Fielddata[].prefix Typestring DescriptionApplication key prefix
Fielddata[].suffix Typestring DescriptionLast characters of the application key
Fielddata[].authorId Typestring DescriptionApplication author identifier
Fielddata[].authorBitrixUserId Typeinteger | null DescriptionBitrix24 employee id of whoever created the app — the same identifier id carries in GET /v1/users. null when the id is unknown
Fielddata[].authorBitrixUserIdSource Typestring | null DescriptionWhere the id came from: member — the author's confirmed membership of the account, snapshot — a value captured when the app was created, null — no id
Fielddata[].portalId Typestring DescriptionBitrix24 portal identifier
Fielddata[].createdAt Typestring DescriptionCreation date, ISO 8601
Fielddata[].updatedAt Typestring DescriptionModification date, ISO 8601
Fielddata[].placements Typestring[] DescriptionBound placements. Before publishing — empty array
Fielddata[].catalogStatus Typestring DescriptionCatalog status: PRIVATE / PUBLISHED / UNPUBLISHED. The reliable publication signal
Fielddata[].publishedAt Typestring | null DescriptionPublication date, ISO 8601. null if the application was never published
Fielddata[].placementResizeEnabled Typeboolean DescriptionWhether the placement iframe height is fitted to the application content. Defaults to false. How to enable it — PATCH /v1/apps/:id
Fielddata[].mobile Typeboolean DescriptionThe "Supports BitrixMobile" flag sent to the Bitrix24 account at registration. For applications created before the field existed — false. Set only at creation — Create an application
Fielddata[].hosting Typestring DescriptionWhere the app runs: platform — on a platform server linked to the app or owned by this Bitrix24 account, or on that server's verified own domain, or the app has no address at all, platform-orphan — an address on a platform subdomain with no live server behind it, external — any other address, including a platform server of another Bitrix24 account. Computed on every read
Fielddata[].externalHost Typestring | null DescriptionHost name from appUrl (punycode) for external, otherwise null. An external row can also carry null when the address has no host: the string does not parse as a URL or its scheme has no host
Fielddata[].externalRegistrable Typestring | null DescriptionRegistrable domain of the host by the public suffix list, private suffixes included: example.co.uk for shop.example.co.uk, the whole address for an IP address. null whenever externalHost is null
Fieldtotal Typenumber DescriptionTotal number of Bitrix24 account applications available to the key
Fieldpage Typenumber DescriptionCurrent page
Fieldlimit Typenumber DescriptionApplied page size

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": "11a2b3c4-d5e6-47f8-9012-3a4b5c6d7e8f",
      "title": "Contact center connector",
      "description": null,
      "scopes": ["crm", "imopenlines", "imconnector", "placement"],
      "handlerUrl": "https://vibecode.bitrix24.com/v1/bitrix-handler",
      "appUrl": null,
      "redirectUris": [
        "https://vibecode.bitrix24.com/oauth/complete",
        "http://localhost"
      ],
      "bitrixClientId": "local.6b2c3d4e5f6a70.33334444",
      "prefix": "vibe_app_local_6b2",
      "suffix": "4444",
      "authorId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "authorBitrixUserId": 42,
      "authorBitrixUserIdSource": "member",
      "portalId": "8b1f0e2a-3c4d-5e6f-7a8b-9c0d1e2f3a4b",
      "createdAt": "2026-06-04T08:52:57.583Z",
      "updatedAt": "2026-06-04T08:52:57.583Z",
      "placements": [],
      "catalogStatus": "PRIVATE",
      "publishedAt": null,
      "placementResizeEnabled": false,
      "mobile": false,
      "hosting": "platform",
      "externalHost": null,
      "externalRegistrable": null
    },
    {
      "id": "22b3c4d5-e6f7-48a9-0123-4b5c6d7e8f90",
      "title": "Sales dashboard",
      "description": null,
      "scopes": ["crm", "user", "placement"],
      "handlerUrl": "https://vibecode.bitrix24.com/v1/bitrix-handler",
      "appUrl": "https://app-abc12345.vibecode.bitrix24.com",
      "redirectUris": [
        "https://vibecode.bitrix24.com/oauth/complete",
        "http://localhost"
      ],
      "bitrixClientId": "local.5a1b2c3d4e5f60.11112222",
      "prefix": "vibe_app_local_5a1",
      "suffix": "2222",
      "authorId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "authorBitrixUserId": null,
      "authorBitrixUserIdSource": null,
      "portalId": "8b1f0e2a-3c4d-5e6f-7a8b-9c0d1e2f3a4b",
      "createdAt": "2026-05-13T11:31:53.810Z",
      "updatedAt": "2026-05-13T11:35:12.204Z",
      "placements": ["CRM_DEAL_DETAIL_TAB"],
      "catalogStatus": "PUBLISHED",
      "publishedAt": "2026-05-13T11:35:12.204Z",
      "placementResizeEnabled": true,
      "mobile": false,
      "hosting": "platform",
      "externalHost": null,
      "externalRegistrable": null
    }
  ],
  "total": 2,
  "page": 1,
  "limit": 50
}

Error response example

401 — the X-Api-Key header was not passed:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key required. Pass via X-Api-Key header."
  }
}

Errors

HTTP Code Description
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not passed
HTTP401 CodeINVALID_API_KEY DescriptionThe key is not recognized — no such key exists on the platform

Full list of common API errors — Errors.

Known specifics

  • The system companion bot application and deleted applications are not included in the list.
  • By default the response contains no more than 50 applications — this is a boundary, not an error. Compare total with the length of data to determine whether applications remain beyond the page, and request the next one via page if needed.
  • The authorBitrixUserId field is the Bitrix24 employee id of whoever created the app, and the same identifier the id field of GET /v1/users returns. An employee card link is built as https://<account-domain>/company/personal/user/<authorBitrixUserId>/. The authorId field stays a Vibecode platform user identifier and never goes into such a link.
  • This response does not return the author's name. Fetch it by authorBitrixUserId through GET /v1/users, where the user permission gates access to it.
  • Read authorBitrixUserIdSource before you build a link. On member the id comes from the author's confirmed membership of the account and the link points at them. On snapshot the id comes from a value captured when the app was created: that is best-effort, and on an app whose owner has changed the id may point at a different employee. A registry that must not be wrong should link only on member.
  • Both fields are empty together: authorBitrixUserIdSource: null always comes with authorBitrixUserId: null. An empty id is a normal state, not an error — for some apps the author's id is unknown.
  • On self-hosted accounts and on accounts with microservice credentials the snapshot value is never returned: there the captured value has no identity-confirmed origin, so the id is either member or empty.
  • The member value does not promise the employee still works at the company: the link may lead to a disabled or deleted Bitrix24 profile.

See also