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

# Create Block Document

`POST /api/block_documents/`

## Request

- The document declares no server URL.
- Auth: none declared

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.dev/prefecthq/apis/prefect-versions-api.md) - [All operations](https://skmtc.dev/prefecthq/apis/prefect-versions-api/llms.txt) - [OpenAPI document](https://skmtc.dev/prefecthq/apis/prefect-versions-api/revisions/a7958ce57e96?raw)