---
title: "Create record change request"
method: POST
path: "/api/v1/records/{recordId}/change-requests"
tags: ["Records", "Change Requests"]
---

# Create record change request

`POST /api/v1/records/{recordId}/change-requests`

## Request

- Base URL: `https://api-docs.busabase.com`
- URL: `https://api-docs.busabase.com/api/v1/records/{recordId}/change-requests`
- Auth: none declared

## Path parameters

- `recordId` string, required

## Request body

- object
  - `fields` object: Updated field values keyed by field slug. If you set the base's PRIMARY field (its first field), keep it a short human-readable name — it is the record's display title everywhere.
  - `message` union
    - string: Explanation shown to the human reviewer. Write a conventional-commit style subject — imperative verb + what + why, e.g. "Update deal stage to qualified — demo booked for July 8".
    - string: Explanation shown to the human reviewer. Say what is being removed and why, e.g. "Archive duplicate contact — merged into Acme Corp".
    - string
  - `author` string
  - `baseCommitId` string
  - `operation` union, required
    - unknown
    - unknown
    - unknown
  - `autoMerge` union
    - boolean
    - boolean: Whether to approve and merge this change immediately. Omitted defaults to merging immediately if the actor has write access on the target node, otherwise falling back to a pending Change Request; pass explicit false to force review even with write access. Archiving is reversible: the record leaves every listing but is restored intact by `operation: "restore"`.
    - boolean: Whether to approve and merge this change immediately. Omitted defaults to merging immediately if the actor has write access on the target node, otherwise falling back to a pending Change Request; pass explicit false to force review even with write access. Restoring is itself the undo of an archive, and is undone again by `operation: "delete"`.
  - `submittedBy` union
    - string
    - string
  - `deleteMode` 'archive'

## Response `200`

Creates a record change request selected by `operation`. All three operations are permission-aware: they merge immediately when the actor has write access on the Base's node, and land as a pending Change Request otherwise or when `autoMerge: false` is passed.

- union
  - object
    - `id` string, required
    - `baseId` string, required
    - `headCommitId` string, required
    - `parentRecordId` string, required
    - `parentCommitId` string, required
    - `status` 'active' | 'archived', required
    - `createdBy` string, required
    - `createdByUser` object
      - `id` string, required
      - `name` string, required
      - `email` string, required
      - `image` string, required
      - `role` string
    - `fieldUsers` object
    - `archivedAt` string, required
    - `createdAt` string, required
    - `updatedAt` string, required
    - `base` object, required
      - `id` string, required
      - `nodeId` string, required
      - `slug` string, required
      - `name` string, required
      - `description` string, required
      - `reviewPolicy` object, required
        - `kind` unknown, required
        - `requiredApprovals` number, required
      - `createdAt` string, required
      - `fields` object[], required
        - `id` string, required
        - `baseId` string, required
        - `slug` string, required
        - `name` union, required
          - string
          - object
        - `type` 'text' | 'longtext' | 'markdown' | 'html' | 'attachment' | 'relation' | 'member' | 'number' | 'date' | 'checkbox' | 'select' | 'multiselect' | 'url' | 'embed' | 'email' | 'phone' | 'created_time' | 'updated_time' | 'created_by' | 'updated_by' | 'auto_number' | 'ai_summary' | 'ai_tags' | 'code' | 'json' | 'yaml' | 'formula' | 'lookup' | 'whiteboard', required
        - `required` boolean, required
        - `position` number, required
        - `options` object
          - `help` object
            - `description` string
            - `example` string
          - `ai` object
            - `model` string
            - `prompt` string
            - `reviewRequired` boolean
            - `sourceFieldIds` string[]
          - `attachment` object
            - `allowedMimeTypes` string[]
          - `choices` object[]
            - `color` string
            - `id` string, required
            - `name` string, required
          - `code` object
            - `language` string
          - `date` object
            - `includeTime` boolean
            - `timezone` string: IANA time zone, e.g. "Asia/Shanghai". Omit to show each reader their own local time.
          - `embed` object
            - `aspectRatio` '16:9' | '4:3' | '1:1'
            - `providers` string[]
          - `formula` object
            - `expression` string, required
            - `format` 'auto' | 'number' | 'currency' | 'percent' | 'date'
            - `precision` integer
            - `currency` string
          - `inverseFieldId` string
          - `lookup` object
            - `relationFieldSlug` string, required: Slug of a `relation` field on THIS Base — the hop to follow.
            - `targetFieldSlug` string, required: Slug of the field on the related Base whose values are pulled over.
            - `rollup` 'values' | 'count' | 'sum' | 'average' | 'min' | 'max' | 'concatenate'
            - `limit` 'all' | 'first': `first` looks at only the first linked record; default `all`.
          - `multiple` boolean
          - `number` object
            - `format` 'plain' | 'currency'
            - `currency` string
            - `locale` string
          - `targetBaseId` string: Relation target Base id (bse_…). Or pass targetBaseSlug to name it by slug.
          - `targetBaseSlug` string: Relation target Base by slug — a convenience alias for targetBaseId, resolved server-side (active bases in the current space). If both are given, targetBaseId wins.
    - `headCommit` object, required
      - `id` string, required
      - `baseId` string, required
      - `targetType` 'base' | 'node', required
      - `nodeId` string, required
      - `operationId` string, required
      - `parentCommitId` string, required
      - `payload` object, required
      - `operation` 'node_create' | 'node_rename' | 'node_delete' | 'node_restore' | 'node_move' | 'record_create' | 'record_update' | 'record_delete' | 'record_variant' | 'view_create' | 'view_update' | 'view_delete' | 'view_restore' | 'base_add_field' | 'base_delete_field' | 'base_update_field' | 'base_convert_field' | 'base_reorder_fields' | 'base_restore_field' | 'base_archive' | 'base_restore' | 'record_restore' | 'skill_file_create' | 'skill_file_update' | 'skill_file_delete' | 'skill_metadata_update' | 'drive_file_create' | 'drive_file_update' | 'drive_file_delete' | 'drive_metadata_update' | 'airapp_file_create' | 'airapp_file_update' | 'airapp_file_delete' | 'airapp_metadata_update' | 'doc_update' | 'whiteboard_document_update' | 'workflow_document_update' | 'html_document_update', required
      - `message` string, required
      - `author` string, required
      - `authorUser` object
        - `id` string, required
        - `name` string, required
        - `email` string, required
        - `image` string, required
        - `role` string
      - `createdAt` string, required
    - `materialized` unknown, required
  - object
    - `id` string, required
    - `baseId` string, required
    - `targetType` 'base' | 'node', required
    - `nodeId` string, required
    - `status` 'in_review' | 'changes_requested' | 'approved' | 'rejected' | 'merged' | 'abandoned' | 'conflict', required
    - `submittedBy` string, required
    - `submittedByUser` object
      - `id` string, required
      - `name` string, required
      - `email` string, required
      - `image` string, required
      - `role` string
    - `sourceAttribution` object
      - `displayName` string, required
      - `ownerName` string, required
      - `channel` 'web_ui' | 'browser' | 'openapi' | 'sdk' | 'cli' | 'mcp' | 'skill' | 'webhook' | 'automation' | 'import', required
      - `playbook` object
        - `kind` 'skill' | 'prompt', required
        - `accessible` boolean, required
        - `nodeId` string, required
        - `key` string, required
        - `nodeType` string, required
        - `nodeSlug` string, required
        - `label` string, required
    - `sourceMeta` object, required
    - `reviewPolicySnapshot` object, required
    - `mergeSummary` object, required: Filled in when the change request merges. `slugChanges` (present only when non-empty) lists items a restore brought back under a new slug because another item took the old one while they were in the Trash: `{ nodeId, nodeType, name, fromSlug, toSlug }`. Read the new slug from here instead of assuming the old one.
    - `rejectedReason` string, required
    - `reviewedAt` string, required
    - `mergedAt` string, required
    - `createdAt` string, required
    - `updatedAt` string, required
    - `base` object, required
      - `id` string, required
      - `nodeId` string, required
      - `slug` string, required
      - `name` string, required
      - `description` string, required
      - `reviewPolicy` object, required
        - `kind` unknown, required
        - `requiredApprovals` number, required
      - `createdAt` string, required
      - `fields` object[], required
        - `id` string, required
        - `baseId` string, required
        - `slug` string, required
        - `name` union, required
          - string
          - object
        - `type` 'text' | 'longtext' | 'markdown' | 'html' | 'attachment' | 'relation' | 'member' | 'number' | 'date' | 'checkbox' | 'select' | 'multiselect' | 'url' | 'embed' | 'email' | 'phone' | 'created_time' | 'updated_time' | 'created_by' | 'updated_by' | 'auto_number' | 'ai_summary' | 'ai_tags' | 'code' | 'json' | 'yaml' | 'formula' | 'lookup' | 'whiteboard', required
        - `required` boolean, required
        - `position` number, required
        - `options` object
          - `help` object
            - `description` string
            - `example` string
          - `ai` object
            - `model` string
            - `prompt` string
            - `reviewRequired` boolean
            - `sourceFieldIds` string[]
          - `attachment` object
            - `allowedMimeTypes` string[]
          - `choices` object[]
            - `color` string
            - `id` string, required
            - `name` string, required
          - `code` object
            - `language` string
          - `date` object
            - `includeTime` boolean
            - `timezone` string: IANA time zone, e.g. "Asia/Shanghai". Omit to show each reader their own local time.
          - `embed` object
            - `aspectRatio` '16:9' | '4:3' | '1:1'
            - `providers` string[]
          - `formula` object
            - `expression` string, required
            - `format` 'auto' | 'number' | 'currency' | 'percent' | 'date'
            - `precision` integer
            - `currency` string
          - `inverseFieldId` string
          - `lookup` object
            - `relationFieldSlug` string, required: Slug of a `relation` field on THIS Base — the hop to follow.
            - `targetFieldSlug` string, required: Slug of the field on the related Base whose values are pulled over.
            - `rollup` 'values' | 'count' | 'sum' | 'average' | 'min' | 'max' | 'concatenate'
            - `limit` 'all' | 'first': `first` looks at only the first linked record; default `all`.
          - `multiple` boolean
          - `number` object
            - `format` 'plain' | 'currency'
            - `currency` string
            - `locale` string
          - `targetBaseId` string: Relation target Base id (bse_…). Or pass targetBaseSlug to name it by slug.
          - `targetBaseSlug` string: Relation target Base by slug — a convenience alias for targetBaseId, resolved server-side (active bases in the current space). If both are given, targetBaseId wins.
    - `node` object, required
      - `id` string, required
      - `parentId` string, required
      - `type` 'folder' | 'base' | 'skill' | 'drive' | 'airapp' | 'file' | 'doc' | 'form' | 'whiteboard' | 'workflow' | 'html', required
      - `slug` string, required
      - `name` string, required
      - `description` string, required
      - `metadata` object
        - `version` string
      - `settings` object
        - `airappEngine` 'browser' | 'local' | 'remote'
      - `explicitVisibility` 'private' | 'workspace' | 'public'
      - `icon` union
        - object
          - `type` unknown, required
          - `value` string, required
        - object
          - `type` unknown, required
          - `url` string, required
          - `attachmentId` string, required
          - `originalUrl` string
          - `originalAttachmentId` string
          - `crop` object
            - `x` number, required
            - `y` number, required
            - `zoom` number, required
      - `position` number, required
      - `createdAt` string, required
      - `updatedAt` string, required
      - `baseId` string, required
      - `children` object[], required
        - `id` string, required
        - `parentId` string, required
        - `type` 'folder' | 'base' | 'skill' | 'drive' | 'airapp' | 'file' | 'doc' | 'form' | 'whiteboard' | 'workflow' | 'html', required
        - `slug` string, required
        - `name` string, required
        - `description` string, required
        - `metadata` object
          - `version` string
        - `settings` object
          - `airappEngine` 'browser' | 'local' | 'remote'
        - `explicitVisibility` 'private' | 'workspace' | 'public'
        - `icon` union
          - object
            - `type` unknown, required
            - `value` string, required
          - object
            - `type` unknown, required
            - `url` string, required
            - `attachmentId` string, required
            - `originalUrl` string
            - `originalAttachmentId` string
            - `crop` object
              - …
        - `position` number, required
        - `createdAt` string, required
        - `updatedAt` string, required
        - `baseId` string, required
        - `children` unknown[], required
          - unknown
        - `hasChildren` boolean
        - `shared` boolean
        - `sharedViaAncestor` boolean
      - `hasChildren` boolean
      - `shared` boolean
      - `sharedViaAncestor` boolean
    - `operations` object[], required
      - `id` string, required
      - `changeRequestId` string, required
      - `baseId` string, required
      - `targetType` 'base' | 'node', required
      - `nodeId` string, required
      - `operation` 'node_create' | 'node_rename' | 'node_delete' | 'node_restore' | 'node_move' | 'record_create' | 'record_update' | 'record_delete' | 'record_variant' | 'view_create' | 'view_update' | 'view_delete' | 'view_restore' | 'base_add_field' | 'base_delete_field' | 'base_update_field' | 'base_convert_field' | 'base_reorder_fields' | 'base_restore_field' | 'base_archive' | 'base_restore' | 'record_restore' | 'skill_file_create' | 'skill_file_update' | 'skill_file_delete' | 'skill_metadata_update' | 'drive_file_create' | 'drive_file_update' | 'drive_file_delete' | 'drive_metadata_update' | 'airapp_file_create' | 'airapp_file_update' | 'airapp_file_delete' | 'airapp_metadata_update' | 'doc_update' | 'whiteboard_document_update' | 'workflow_document_update' | 'html_document_update', required
      - `status` 'pending' | 'merged' | 'archived' | 'failed', required
      - `targetRecordId` string, required
      - `targetViewId` string, required
      - `filePath` string, required
      - `sourceRecordId` string, required
      - `sourceCommitId` string, required
      - `baseCommitId` string, required
      - `headCommitId` string, required
      - `deleteMode` 'archive', required
      - `mergedRecordId` string, required
      - `mergedViewId` string, required
      - `position` number, required
      - `createdAt` string, required
      - `updatedAt` string, required
      - `headCommit` object, required
        - `id` string, required
        - `baseId` string, required
        - `targetType` 'base' | 'node', required
        - `nodeId` string, required
        - `operationId` string, required
        - `parentCommitId` string, required
        - `payload` object, required
        - `operation` 'node_create' | 'node_rename' | 'node_delete' | 'node_restore' | 'node_move' | 'record_create' | 'record_update' | 'record_delete' | 'record_variant' | 'view_create' | 'view_update' | 'view_delete' | 'view_restore' | 'base_add_field' | 'base_delete_field' | 'base_update_field' | 'base_convert_field' | 'base_reorder_fields' | 'base_restore_field' | 'base_archive' | 'base_restore' | 'record_restore' | 'skill_file_create' | 'skill_file_update' | 'skill_file_delete' | 'skill_metadata_update' | 'drive_file_create' | 'drive_file_update' | 'drive_file_delete' | 'drive_metadata_update' | 'airapp_file_create' | 'airapp_file_update' | 'airapp_file_delete' | 'airapp_metadata_update' | 'doc_update' | 'whiteboard_document_update' | 'workflow_document_update' | 'html_document_update', required
        - `message` string, required
        - `author` string, required
        - `authorUser` object
          - `id` string, required
          - `name` string, required
          - `email` string, required
          - `image` string, required
          - `role` string
        - `createdAt` string, required
      - `baseFields` object, required
    - `primaryOperation` object, required
      - `id` string, required
      - `changeRequestId` string, required
      - `baseId` string, required
      - `targetType` 'base' | 'node', required
      - `nodeId` string, required
      - `operation` 'node_create' | 'node_rename' | 'node_delete' | 'node_restore' | 'node_move' | 'record_create' | 'record_update' | 'record_delete' | 'record_variant' | 'view_create' | 'view_update' | 'view_delete' | 'view_restore' | 'base_add_field' | 'base_delete_field' | 'base_update_field' | 'base_convert_field' | 'base_reorder_fields' | 'base_restore_field' | 'base_archive' | 'base_restore' | 'record_restore' | 'skill_file_create' | 'skill_file_update' | 'skill_file_delete' | 'skill_metadata_update' | 'drive_file_create' | 'drive_file_update' | 'drive_file_delete' | 'drive_metadata_update' | 'airapp_file_create' | 'airapp_file_update' | 'airapp_file_delete' | 'airapp_metadata_update' | 'doc_update' | 'whiteboard_document_update' | 'workflow_document_update' | 'html_document_update', required
      - `status` 'pending' | 'merged' | 'archived' | 'failed', required
      - `targetRecordId` string, required
      - `targetViewId` string, required
      - `filePath` string, required
      - `sourceRecordId` string, required
      - `sourceCommitId` string, required
      - `baseCommitId` string, required
      - `headCommitId` string, required
      - `deleteMode` 'archive', required
      - `mergedRecordId` string, required
      - `mergedViewId` string, required
      - `position` number, required
      - `createdAt` string, required
      - `updatedAt` string, required
      - `headCommit` object, required
        - `id` string, required
        - `baseId` string, required
        - `targetType` 'base' | 'node', required
        - `nodeId` string, required
        - `operationId` string, required
        - `parentCommitId` string, required
        - `payload` object, required
        - `operation` 'node_create' | 'node_rename' | 'node_delete' | 'node_restore' | 'node_move' | 'record_create' | 'record_update' | 'record_delete' | 'record_variant' | 'view_create' | 'view_update' | 'view_delete' | 'view_restore' | 'base_add_field' | 'base_delete_field' | 'base_update_field' | 'base_convert_field' | 'base_reorder_fields' | 'base_restore_field' | 'base_archive' | 'base_restore' | 'record_restore' | 'skill_file_create' | 'skill_file_update' | 'skill_file_delete' | 'skill_metadata_update' | 'drive_file_create' | 'drive_file_update' | 'drive_file_delete' | 'drive_metadata_update' | 'airapp_file_create' | 'airapp_file_update' | 'airapp_file_delete' | 'airapp_metadata_update' | 'doc_update' | 'whiteboard_document_update' | 'workflow_document_update' | 'html_document_update', required
        - `message` string, required
        - `author` string, required
        - `authorUser` object
          - `id` string, required
          - `name` string, required
          - `email` string, required
          - `image` string, required
          - `role` string
        - `createdAt` string, required
      - `baseFields` object, required
    - `operationCount` number, required
    - `reviews` object[], required
      - `id` string, required
      - `changeRequestId` string, required
      - `reviewerId` string, required
      - `reviewer` object
        - `id` string, required
        - `name` string, required
        - `email` string, required
        - `image` string, required
        - `role` string
      - `verdict` 'approved' | 'rejected', required
      - `reason` string, required
      - `visibleOperationHeads` object, required
      - `createdAt` string, required
    - `materialized` unknown, required

---

[API](https://skmtc.dev/busabase/apis/busabase-api.md) · [All operations](https://skmtc.dev/busabase/apis/busabase-api/llms.txt) · [OpenAPI document](https://skmtc.dev/busabase/apis/busabase-api/revisions/bc6a7d5ff4c1?raw)