Para agentes de IA: markdown desta página — /docs-content-en/includes.md índice da documentação — /llms.txt

Os artigos da documentação estão disponíveis atualmente em inglês.

Related data (include)

Load related entities together with the primary records in a single request. Instead of making separate calls to fetch a contact, company, or assignee, pass the include parameter — Vibecode returns everything in the _included field.

The include parameter is optional and works in three places:

  • GET /v1/{entity}/{id}?include=... — fetch a single record
  • GET /v1/{entity}?include=... — fetch a list
  • POST /v1/{entity}/search — search (include in the request body as an array of strings)

How to use

List relation names separated by commas:

curl

Terminal 
curl "https://vibecode.bitrix24.com/v1/deals/741?include=contact,company" \
  -H "X-Api-Key: YOUR_API_KEY"

JavaScript

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/deals/741?include=contact,company', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data } = await res.json()

// data._included.contacts — array of deal contacts
// data._included.company  — company (object or null)

Related data appears in the _included field of each record:

JSON 
{
  "success": true,
  "data": {
    "id": 741,
    "title": "Equipment delivery",
    "contactId": 71,
    "companyId": 15,
    "_included": {
      "contacts": [
        {
          "id": 71,
          "name": "John",
          "lastName": "Brown",
          "phone": [{ "VALUE": "+12025550123" }],
          "isPrimary": true,
          "sort": 10
        }
      ],
      "company": {
        "id": 15,
        "title": "Acme LLC",
        "industry": "IT"
      }
    }
  }
}

Two types of relations

One-to-one

The entity has a reference field pointing to the related object (for example, companyId on a contact). The result is a single object or null.

GET /v1/leads/50?include=contact
JSON 
{
  "data": {
    "id": 50,
    "title": "Website request",
    "contactId": 71,
    "_included": {
      "contact": {
        "id": 71,
        "name": "John",
        "lastName": "Brown"
      }
    }
  }
}

If the reference field is empty or equals 0, null is returned:

JSON 
{
  "_included": {
    "contact": null
  }
}

Many-to-many

A relation through an intermediate table. The result is an array of objects with additional relation fields.

GET /v1/deals/741?include=contact
JSON 
{
  "_included": {
    "contacts": [
      {
        "id": 71,
        "name": "John",
        "lastName": "Brown",
        "isPrimary": true,
        "sort": 10,
        "roleId": 0
      },
      {
        "id": 85,
        "name": "Maria",
        "lastName": "Davis",
        "isPrimary": false,
        "sort": 20,
        "roleId": 0
      }
    ]
  }
}

Note: the relation name in the request is contact (singular), while in the response it is contacts (plural). Vibecode automatically pluralizes the name for arrays.

Additional relation fields (isPrimary, sort, roleId) are added to each object — their values come from the intermediate table, not from the entity itself.

curl — list

Terminal 
curl "https://vibecode.bitrix24.com/v1/deals?limit=10&include=company" \
  -H "X-Api-Key: YOUR_API_KEY"

JavaScript — list

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/deals?limit=10&include=company', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data, meta } = await res.json()

for (const deal of data) {
  console.log(deal.title, '—', deal._included.company?.title ?? 'no company')
}
// meta.includeSkipped === true if records > 200

Response:

JSON 
{
  "success": true,
  "data": [
    {
      "id": 741,
      "title": "Equipment delivery",
      "companyId": 15,
      "_included": {
        "company": { "id": 15, "title": "Acme LLC" }
      }
    },
    {
      "id": 742,
      "title": "Tech support",
      "companyId": 15,
      "_included": {
        "company": { "id": 15, "title": "Acme LLC" }
      }
    }
  ],
  "meta": { "total": 150, "hasMore": true }
}

Vibecode deduplicates requests: if several records reference the same company, it is loaded once.

In search, include is passed in the request body as an array.

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/deals/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "stageId": "NEW", "amount": { "$gte": 100000 } },
    "include": ["contact", "company"],
    "limit": 50
  }'
javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/deals/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { stageId: 'NEW', amount: { $gte: 100000 } },
    include: ['contact', 'company'],
    limit: 50,
  }),
})
const { data } = await res.json()

Multiple relations in one request

You can request up to 3 relations at once:

GET /v1/quotes/18?include=deal,contact,company
JSON 
{
  "_included": {
    "deal": { "id": 741, "title": "Equipment delivery" },
    "contact": { "id": 71, "name": "John", "lastName": "Brown" },
    "company": { "id": 15, "title": "Acme LLC" }
  }
}

Limits

Parameter Value
Maximum relations per request 3
Maximum records for include 200

If a list or search returns more than 200 records, include is skipped and a flag is added to meta:

JSON 
{
  "data": [ ... ],
  "meta": {
    "hasMore": true,
    "includeSkipped": true
  }
}

To get related data for large result sets, reduce limit to 200 or less.

Available relations per entity

You can find the available includes for a specific entity via the fields endpoint:

Terminal 
curl "https://vibecode.bitrix24.com/v1/deals/fields" \
  -H "X-Api-Key: YOUR_API_KEY"

The response contains an include field with the list of available relations:

JSON 
{
  "success": true,
  "data": {
    "fields": { ... },
    "include": ["contact", "company"]
  }
}

Available relations depend on the entity. The includes supported by a specific entity are listed in each method's documentation and in the GET /v1/{entity}/fields response (the include field).

Errors

HTTP Code Description
400 INCLUDE_LIMIT_EXCEEDED More than 3 relations requested
400 INVALID_INCLUDE Relation not found. The response contains the list of available relations
403 SCOPE_DENIED The key lacks the scope of the related entity

If an entity has no relations at all (for example, departments), any include returns INVALID_INCLUDE with an empty Available: list.

Scopes

include does not widen what a key may read. Both sides of the relation are checked: the entity you read and the entity the relation pulls in. The two sides do not always require the same scope — responsible on tasks and owner on workgroups read an employee and therefore require user, while catalog on product sections requires catalog. When the second side's scope is missing, the whole request is refused with SCOPE_DENIED, and the message names both the missing scope and the relation that needed it.

Relations that stay within one scope require nothing extra.

Error example:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_INCLUDE",
    "message": "Unknown include 'manager'. Available: contact, company"
  }
}

Scope refusal example:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "Include 'owner' reads users and requires 'user' scope"
  }
}

See also