Queues multiple blocks for asynchronous creation and connects them to one or more channels. Returns immediately with a batch_id that can be used to poll for status via GET /v3/blocks/batch/{batch_id}.

Designed for import use cases such as migrating from other services or re-importing Are.na exports.

Each block in the blocks array follows the same format as single block creation. Blocks are processed sequentially in the background and partial success is supported — if some blocks fail, the successful ones are still created.

Limits:

Maximum 50 blocks per request
Maximum 20 channels per request
All channels must be private

Batch results are available for 24 hours after submission.

⚠️ Premium Only: This endpoint requires a Premium subscription.

Body Params

channel_ids

array

required

Array of channel IDs or slugs. Accepts numeric IDs, string IDs, or channel slugs (e.g., `[123, "456", "my-channel-slug"]`).

blocks

BlockInput[]

required

Array of blocks to create

Block Input 1

value

string

required

The content to create a block from. Can be either: - A URL (creates Image, Link, or Embed block based on content type) - Text/markdown content (creates a Text block)

title

string

Optional title for the block

description

string

Optional description (supports markdown)

original_source_url

string

Original source URL for attribution

original_source_title

string

Title of the original source

alt_text

string

Alt text for images (accessibility)

metadata

object

Arbitrary key-value pairs stored on an entity. Keys are alphanumeric/underscore, max 40 characters. Values are scalars (string, number, boolean). Max 50 keys, 32KB total.

POST

https://api.are.na/v3/blocks/batch

Response returned when a batch is accepted for processing

batch_id

string (uuid)!

Unique identifier for this batch

status

string!

Initial status of the batch

pending

total

integer!

Total number of blocks queued for creation