---
title: "Create Block Document"
method: POST
path: "/api/block_documents/"
tags: ["Block documents"]
---

# Create Block Document

`POST /api/block_documents/`

Create a new block document.

## Headers

- `x-prefect-api-version` string

## Request body

- BlockDocumentCreate — Data used by the Prefect REST API to create a block document.
  - `name` string — The block document's name. Not required for anonymous block documents.
  - `data` object — The block document's data
  - `block_schema_id` string, uuid, required — A block schema ID
  - `block_type_id` string, uuid, required — A block type ID
  - `is_anonymous` boolean — Whether the block is anonymous (anonymous blocks are usually created by Prefect automatically)

## Response `201`

Successful Response

- BlockDocument — An ORM representation of a block document.
  - `id` string, uuid
  - `created` string, date-time
  - `updated` string, date-time
  - `name` string — The block document's name. Not required for anonymous block documents.
  - `data` object — The block document's data
  - `block_schema_id` string, uuid, required — A block schema ID
  - `block_schema` BlockSchema — An ORM representation of a block schema.
    - `id` string, uuid
    - `created` string, date-time
    - `updated` string, date-time
    - `checksum` string, required — The block schema's unique checksum
    - `fields` object — The block schema's field schema
    - `block_type_id` string, uuid, required — A block type ID
    - `block_type` BlockType — An ORM representation of a block type
      - `id` string, uuid
      - `created` string, date-time
      - `updated` string, date-time
      - `name` string, required — A block type's name
      - `slug` string, required — A block type's slug
      - `logo_url` string, uri — Web URL for the block type's logo
      - `documentation_url` string, uri — Web URL for the block type's documentation
      - `description` string — A short blurb about the corresponding block's intended use
      - `code_example` string — A code snippet demonstrating use of the corresponding block
      - `is_protected` boolean — Protected block types cannot be modified via API.
    - `capabilities` string[] — A list of Block capabilities
    - `version` string — Human readable identifier for the block schema
  - `block_type_id` string, uuid, required — A block type ID
  - `block_type_name` string — The associated block type's name
  - `block_type` BlockType — An ORM representation of a block type
    - `id` string, uuid
    - `created` string, date-time
    - `updated` string, date-time
    - `name` string, required — A block type's name
    - `slug` string, required — A block type's slug
    - `logo_url` string, uri — Web URL for the block type's logo
    - `documentation_url` string, uri — Web URL for the block type's documentation
    - `description` string — A short blurb about the corresponding block's intended use
    - `code_example` string — A code snippet demonstrating use of the corresponding block
    - `is_protected` boolean — Protected block types cannot be modified via API.
  - `block_document_references` object — Record of the block document's references
  - `is_anonymous` boolean — Whether the block is anonymous (anonymous blocks are usually created by Prefect automatically)

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/prefecthq/apis/untitled-api-2.md) · [All operations](https://skmtc.net/prefecthq/apis/untitled-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/prefecthq/untitled-api-2/revisions/29ba6c4f8837/schema)