# Add a block

> POST /v1/pages/{page_id}/blocks — Append ONE block to the page DRAFT, preserving every existing block byte-for-byte. Optionally wire an uploaded file (public_path…

Page: https://getbioflow.com/docs/api-reference/addBlock

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}



## POST /v1/pages/{page_id}/blocks

Append ONE block to the page DRAFT, preserving every existing block byte-for-byte. Optionally wire an uploaded file (public_path from List files) into IMAGE/FILE/CAROUSEL/PRODUCT blocks. Requires expected_updated_at.

Requires scope: pages:write. Plan entitlement: public_api (Creator and Pro).

Consequential operation — send an Idempotency-Key header.

```json
{
  "servers": [
    {
      "url": "https://app.getbioflow.com"
    }
  ],
  "paths": {
    "/v1/pages/{page_id}/blocks": {
      "post": {
        "operationId": "addBlock",
        "summary": "Add a block",
        "description": "Append ONE block to the page DRAFT, preserving every existing block byte-for-byte. Optionally wire an uploaded file (public_path from List files) into IMAGE/FILE/CAROUSEL/PRODUCT blocks. Requires expected_updated_at.\n\nRequires scope: pages:write. Plan entitlement: public_api (Creator and Pro).\n\nConsequential operation — send an Idempotency-Key header.",
        "security": [
          {
            "apiKeyBearer": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "x-scopes": [
          "pages:write"
        ],
        "x-entitlement": "public_api",
        "x-meter-cost": 1,
        "x-idempotent": true,
        "parameters": [
          {
            "in": "path",
            "name": "page_id",
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "Page ID from List pages"
            },
            "required": true,
            "description": "Page ID from List pages"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AddBlockRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The page with the new block",
            "headers": {
              "X-Request-Id": {
                "description": "Unique request identifier — quote it in support requests.",
                "schema": {
                  "type": "string",
                  "example": "req_01abc"
                }
              },
              "RateLimit-Policy": {
                "description": "IETF draft-11 rate-limit policy (structured field).",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "IETF draft-11 rate-limit state (structured field).",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Page"
                }
              }
            }
          },
          "400": {
            "description": "Validation failed (invalid_request)",
            "headers": {
              "X-Request-Id": {
                "description": "Unique request identifier — quote it in support requests.",
                "schema": {
                  "type": "string",
                  "example": "req_01abc"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key (invalid_api_key)",
            "headers": {
              "X-Request-Id": {
                "description": "Unique request identifier — quote it in support requests.",
                "schema": {
                  "type": "string",
                  "example": "req_01abc"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Denied: insufficient_scope, feature_not_enabled, or test_key_read_only",
            "headers": {
              "X-Request-Id": {
                "description": "Unique request identifier — quote it in support requests.",
                "schema": {
                  "type": "string",
                  "example": "req_01abc"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited: rate_limited (per-key burst) or quota_exhausted (monthly)",
            "headers": {
              "X-Request-Id": {
                "description": "Unique request identifier — quote it in support requests.",
                "schema": {
                  "type": "string",
                  "example": "req_01abc"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected failure (internal_error)",
            "headers": {
              "X-Request-Id": {
                "description": "Unique request identifier — quote it in support requests.",
                "schema": {
                  "type": "string",
                  "example": "req_01abc"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AddBlockRequest": {
        "type": "object",
        "properties": {
          "expected_updated_at": {
            "type": "string",
            "minLength": 1,
            "description": "Concurrency stamp: the draft.updated_at you last read. A mismatch is refused with 409 stale_snapshot — re-read the page and retry."
          },
          "kind": {
            "type": "string",
            "minLength": 1,
            "description": "Block kind, e.g. LINK"
          },
          "data": {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {}
          },
          "file_url": {
            "description": "public_path of a workspace file from List files",
            "type": "string"
          },
          "file_name": {
            "type": "string"
          },
          "supplied_endorsements": {
            "description": "Every testimonial or review quote this write adds, with the name of who said it, exactly as they were given to you. A quote, quotation or customer name not listed here (or already on the page) is left empty or removed.",
            "maxItems": 20,
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "quote": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 500
                },
                "author": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 120
                }
              },
              "required": [
                "quote",
                "author"
              ]
            }
          },
          "persons_own_words": {
            "description": "The person's OWN words, exactly as they wrote them, when this write puts them in quotation marks on their page. Only unattributed first-person words count: a sentence naming someone else, or shaped as a review or testimonial, unlocks nothing; pass a real review in supplied_endorsements.",
            "type": "string",
            "maxLength": 2000
          }
        },
        "required": [
          "expected_updated_at",
          "kind"
        ]
      },
      "Page": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "DRAFT",
              "PUBLISHED",
              "ARCHIVED"
            ]
          },
          "locale": {
            "type": "string"
          },
          "public_url": {
            "description": "Live URL when routed; null for unrouted drafts",
            "type": [
              "string",
              "null"
            ]
          },
          "theme": {
            "type": "object",
            "properties": {
              "label": {
                "type": "string"
              },
              "preset_key": {
                "type": "string"
              }
            },
            "required": [
              "label",
              "preset_key"
            ],
            "additionalProperties": false
          },
          "draft": {
            "type": "object",
            "properties": {
              "updated_at": {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
                "example": "2026-07-20T12:00:00.000Z",
                "description": "Concurrency stamp — pass as expected_updated_at on every write"
              },
              "block_count": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              "blocks": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/PageBlockRef"
                }
              }
            },
            "required": [
              "updated_at",
              "block_count",
              "blocks"
            ],
            "additionalProperties": false
          },
          "published": {
            "type": "object",
            "properties": {
              "is_live": {
                "type": "boolean"
              },
              "block_count": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              "live_updated_at": {
                "anyOf": [
                  {
                    "type": "string",
                    "format": "date-time",
                    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
                    "example": "2026-07-20T12:00:00.000Z"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "required": [
              "is_live",
              "block_count",
              "live_updated_at"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "id",
          "title",
          "description",
          "slug",
          "status",
          "locale",
          "public_url",
          "theme",
          "draft",
          "published"
        ],
        "additionalProperties": false
      },
      "PageBlockRef": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "kind": {
            "type": "string"
          },
          "enabled": {
            "type": "boolean"
          },
          "label": {
            "type": "string",
            "description": "Display label derived from data"
          }
        },
        "required": [
          "id",
          "kind",
          "enabled",
          "label"
        ],
        "additionalProperties": false
      },
      "Problem": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "Docs URL, https://getbioflow.com/docs/api/errors/<code>"
          },
          "title": {
            "type": "string",
            "description": "Human summary — never parse"
          },
          "status": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "HTTP status, mirrored in the body"
          },
          "detail": {
            "description": "Human detail — never parse",
            "type": "string"
          },
          "instance": {
            "type": "string",
            "example": "urn:request:req_01abc"
          },
          "code": {
            "type": "string",
            "enum": [
              "invalid_request",
              "invalid_api_key",
              "insufficient_scope",
              "feature_not_enabled",
              "test_key_read_only",
              "resource_not_found",
              "stale_snapshot",
              "endorsements_unconfirmed",
              "idempotency_in_progress",
              "idempotency_key_reused",
              "endpoint_verification_failed",
              "endpoint_limit_reached",
              "rate_limited",
              "quota_exhausted",
              "internal_error",
              "query_timeout"
            ],
            "description": "The stable machine-readable code — branch on this"
          },
          "request_id": {
            "type": "string",
            "example": "req_01abc"
          },
          "errors": {
            "description": "Field-level validation errors (400 only)",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "pointer": {
                  "type": "string",
                  "example": "/title"
                },
                "code": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              },
              "required": [
                "pointer",
                "code",
                "message"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "type",
          "title",
          "status",
          "instance",
          "code",
          "request_id"
        ],
        "additionalProperties": false,
        "description": "RFC 9457 problem details"
      }
    }
  }
}
```
