Object Models

Understand the core V2 API objects, including user, page, database, block, list, and error.

Object Models

These are the core shapes returned by V2 endpoints. Endpoint pages may show partial examples, but these models describe the stable object categories.

Core Objects

Object	Description
`user`	A person account visible to the token.
`bot_user`	The integration identity returned by `GET /v2/users/me`.
`page`	A page or database record. Buildin extensions such as folders and mind maps also use `object: "page"`.
`database`	A database with property schema directly on the object.
`block`	A content block with type-specific content under the field named by `type`.
`list`	A paginated response wrapper.
`error`	The unified error response.

`user`

{
  "object": "user",
  "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb",
  "type": "person",
  "name": "Alex Chen",
  "avatar_url": "https://example.com/avatar.png",
  "person": {
    "email": "alex@example.com"
  }
}

Without users.email.read, person.email is null.

`bot_user`

{
  "object": "bot_user",
  "id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
  "name": "My Integration",
  "workspace_id": "99999999-9999-4999-8999-999999999999",
  "workspace_name": "Team Workspace",
  "owner": {
    "object": "user",
    "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb"
  },
  "capabilities": {
    "pages.read": true,
    "pages.write": true,
    "blocks.read": true,
    "blocks.write": true,
    "databases.read": true,
    "databases.write": true,
    "users.read": true,
    "users.email.read": false,
    "search.read": true
  },
  "type": "integration",
  "integration_id": "77777777-7777-4777-8777-777777777777"
}

`page`

{
  "object": "page",
  "id": "11111111-1111-4111-8111-111111111111",
  "page_type": "page",
  "created_time": "2026-04-09T08:00:00.000Z",
  "last_edited_time": "2026-04-09T09:30:00.000Z",
  "created_by": {
    "object": "user",
    "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb"
  },
  "last_edited_by": {
    "object": "user",
    "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb"
  },
  "parent": {
    "type": "page_id",
    "page_id": "55555555-5555-4555-8555-555555555555"
  },
  "in_trash": false,
  "icon": null,
  "cover": null,
  "properties": {
    "title": {
      "id": "title",
      "type": "title",
      "title": [
        {
          "type": "text",
          "text": {
            "content": "Launch Plan",
            "link": null
          },
          "plain_text": "Launch Plan",
          "href": null
        }
      ]
    }
  },
  "url": "https://buildin.ai/docs/11111111-1111-4111-8111-111111111111"
}

in_trash represents soft-delete state.
icon and cover can be null.
page_type is a Buildin extension and can be page, folder, or mind_map.
Folders and mind maps still use object: "page".

`database`

{
  "object": "database",
  "id": "66666666-6666-4666-8666-666666666666",
  "created_time": "2026-04-09T08:00:00.000Z",
  "last_edited_time": "2026-04-09T09:30:00.000Z",
  "created_by": {
    "object": "user",
    "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb"
  },
  "last_edited_by": {
    "object": "user",
    "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb"
  },
  "title": [
    {
      "type": "text",
      "text": {
        "content": "Task Board",
        "link": null
      },
      "plain_text": "Task Board",
      "href": null
    }
  ],
  "description": [],
  "icon": null,
  "cover": null,
  "parent": {
    "type": "page_id",
    "page_id": "55555555-5555-4555-8555-555555555555"
  },
  "properties": {
    "Name": {
      "id": "title",
      "type": "title",
      "name": "Name"
    },
    "Status": {
      "id": "16161616-1616-4616-8616-161616161616",
      "type": "select",
      "name": "Status"
    }
  },
  "in_trash": false,
  "is_inline": false,
  "url": "https://buildin.ai/database/66666666-6666-4666-8666-666666666666"
}

database.properties contains schema and is not split into a data source object.
is_inline indicates whether the database is displayed inline in its parent page.
title and description are rich_text arrays.

`block`

{
  "object": "block",
  "id": "44444444-4444-4444-8444-444444444444",
  "parent": {
    "type": "page_id",
    "page_id": "11111111-1111-4111-8111-111111111111"
  },
  "created_time": "2026-04-09T08:00:00.000Z",
  "last_edited_time": "2026-04-09T09:30:00.000Z",
  "created_by": {
    "object": "user",
    "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb"
  },
  "last_edited_by": {
    "object": "user",
    "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb"
  },
  "has_children": false,
  "in_trash": false,
  "type": "paragraph",
  "paragraph": {
    "rich_text": [
      {
        "type": "text",
        "text": {
          "content": "Project kickoff notes",
          "link": null
        },
        "plain_text": "Project kickoff notes",
        "href": null
      }
    ],
    "color": "default"
  }
}

See Block Types for block content schemas and writable type coverage.

`list`

{
  "object": "list",
  "results": [],
  "next_cursor": "opaque_cursor",
  "has_more": true
}

Field	Type	Description
`object`	string	Always `list`.
`results`	array	Items for the current page.
`next_cursor`	string or null	Cursor for the next page; `null` when there are no more results.
`has_more`	boolean	Whether another page is available.

`error`

{
  "object": "error",
  "status": 400,
  "code": "validation_error",
  "message": "parent.page_id is required",
  "request_id": "req_xxx",
  "details": [
    {
      "path": "parent.page_id",
      "reason": "required"
    }
  ]
}

See Error Codes for the complete error model.

Object Models

Core Objects

user

bot_user

page

database

block

list

error

Related Docs

Related Capabilities

References

Related Docs

`user`

`bot_user`

`page`

`database`

`block`

`list`

`error`