For AI agents: markdown of this page — /docs-content-en/feed/posts/list.md documentation index — /llms.txt

List posts

GET /v1/posts

Returns Bitrix24 Feed posts accessible to the current API key, in a normalized form: keys in camelCase, flags as booleans, numeric fields as numbers.

Parameters

Parameter Type Required Default Description
limit (query) number no 50 Number of posts in the response. Allowed range 1..50. A value greater than 50 returns 400 INVALID_LIMIT. A value within the range trims the output to the specified number
offset (query) number no 0 Offset for pagination. A non-negative integer

Pagination. A page contains up to 50 posts. To fetch the next batch, pass the meta.nextOffset value from the previous response into offset. The meta.nextOffset field is present only when there is a next page. If it is absent, there are no more posts.

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/posts?limit=3" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/posts?limit=3" \
  -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/posts?limit=3', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data, meta } = await res.json()
console.log(`Posts: ${data.length} of ${meta.total}`)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/posts?limit=3', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data, meta } = await res.json()

Response fields

Field Type Description
success boolean Always true on success
data array Array of posts
data[].id number Post ID. Used in the PATCH /v1/posts/:id path and in the post URL
data[].blogId number ID of the blog the post belongs to
data[].publishStatus string Publish status (P — published)
data[].title string Post title
data[].detailText string Post text
data[].authorId number Author ID. List: GET /v1/users
data[].enableComments boolean Whether comments on the post are allowed
data[].numComments string Number of comments as a string (e.g. "2")
data[].code string | null Symbolic code of the post
data[].micro boolean Micro-post (without a title)
data[].datePublish string Publish date (ISO 8601 with timezone)
data[].categoryId number[] Post category/tag IDs. Always an array: [] — no categories, [11] — one, [5, 7, 9] — several
data[].hasSocnetAll boolean Post is addressed to all employees
data[].hasTags boolean | null The post has tags
data[].hasImages boolean | null The post has images
data[].hasProps boolean | null The post has properties
meta.total number Total number of posts accessible to the key
meta.pageSize number Page size — always 50
meta.requestedLimit number Value of the passed limit. Present only if the parameter was passed
meta.nextOffset number Offset of the next page. Present only if there is a next page — pass it into offset of the next request

Response example

The response contains only the fields listed above — Bitrix24 internal and custom fields (UF_*, FILES, etc.) are not returned.

JSON 
{
  "success": true,
  "data": [
    {
      "id": 293,
      "blogId": 1,
      "publishStatus": "P",
      "title": "Announcement",
      "detailText": "Announcement text for employees",
      "authorId": 1,
      "enableComments": true,
      "numComments": "0",
      "code": null,
      "micro": true,
      "datePublish": "2026-05-29T11:47:37+00:00",
      "categoryId": [],
      "hasSocnetAll": false,
      "hasTags": false,
      "hasImages": false,
      "hasProps": false
    },
    {
      "id": 215,
      "blogId": 1,
      "publishStatus": "P",
      "title": "Survey",
      "detailText": "Survey text",
      "authorId": 1,
      "enableComments": true,
      "numComments": "3",
      "code": null,
      "micro": true,
      "datePublish": "2025-08-13T10:46:10+00:00",
      "categoryId": [5, 7, 9],
      "hasSocnetAll": true,
      "hasTags": true,
      "hasImages": false,
      "hasProps": true
    }
  ],
  "meta": {
    "total": 89,
    "pageSize": 50,
    "requestedLimit": 3,
    "nextOffset": 50
  }
}

Error response example

400 — limit out of range 1..50:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_LIMIT",
    "message": "The page size is fixed at 50 records — a larger `limit` cannot be honoured. Omit `limit` (or pass any value ≤ 50) and paginate via the returned `meta.nextOffset`."
  }
}

Errors

HTTP Code Description
400 INVALID_LIMIT limit is not a positive integer or is greater than 50
400 INVALID_OFFSET offset is negative or not an integer
401 TOKEN_MISSING The API key has no access tokens configured
403 SCOPE_DENIED The API key lacks the log scope
422 BITRIX_ERROR Bitrix24 returned an error while fetching posts
502 BITRIX_UNAVAILABLE Bitrix24 is unavailable

The full list of common API errors — Errors.

Known specifics

  • numComments comes as a string. The number of comments is represented as a string ("2"), not a number — cast it to a number on the client side if you need calculations.
  • categoryId is always an array of numbers. The field holds the list of the post's category/tag IDs: [] when there are none, [11] for one, [5, 7, 9] for several. The type is uniform regardless of how many categories a post has (never a bare number or string).
  • hasProps can be null, not only true or false. For a post without properties created via the API, hasProps comes back null. A client that checks for properties with a strict comparison against true or false must also account for the null value. The hasTags and hasImages fields return true or false on the posts checked.

See also