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

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".

When returned from the dedicated mind-map endpoints, a mind map uses object: "mind_map" and includes its complete node tree and settings. See Mind Maps for that response shape and edit operations.

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.

database_view

database_view is a view of a database (table/board/gallery/list/calendar/timeline/form) and a sub-resource of database.

• object is always "database_view".
• type cannot be changed after creation; the space type is not exposed through v2.
• property_layout is the ordered column layout and references the exact property_id returned by the database or view API; legacy databases may use a non-title id for the title property. On layout writes, the literal title remains a compatibility alias and resolves to the sole title property when the schema has no exact title key. It is empty for timeline/form views.
• filter / sorts use the structure saved by the web client (nested groups, string-only value, operators like eq/neq/in/...). For select and multi_select filters, the canonical value is the option id exposed by Retrieve a database. Writes also accept a unique option name for backward compatibility and normalize it to the id. This is a separate contract from the Notion-style query request dialect; the two are never converted into each other. Conditions referencing deleted properties are pruned on read.
• page_sort is only returned by the view detail endpoint and holds the manual record order.
• group_by is only supported by table/board views.
• config is the curated per-type config projection (table wrap/freeze/aggregations, board/gallery card and cover settings, calendar/timeline date properties, form display switches).

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
        },
        "annotations": {
          "text_color": "red",
          "background_color": "light_yellow"
        },
        "plain_text": "Project kickoff notes",
        "href": null
      }
    ],
    "text_color": "blue",
    "background_color": "yellow_green"
  }
}

The type-specific content for paragraphs, headings, list items, to-do items, quotes, toggles, and callouts has two independent color channels:

• text_color: default, black, gray, brown, orange, pink, yellow, green, blue, purple, or red.
• background_color: default, gray, brown, orange, pink, yellow, green, blue, purple, red, light_yellow, light_green, light_blue, light_purple, light_red, yellow_green, green_blue, blue_purple, purple_red, or red_orange.

Both fields may be set at the same time. The same fields are available in every rich_text[].annotations object, including captions and table cells. default clears only that channel. The legacy single-channel color field remains accepted for compatibility, but new integrations should use the explicit fields.

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

list

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

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.

Related Docs

Related Capabilities

• Get Current Identity
• Get Page
• Get Block
• Get Database
• Search Content

References

• Page Property Models
• Block Types