All Resources
GET
Get a block
/v3/blocks/{id}
GET
Get block comments
/v3/blocks/{id}/comments
GET
Get block connections
/v3/blocks/{id}/connections
POST
Create a block
/v3/blocks
POST
Create a comment
/v3/blocks/{id}/comments
PUT
Update a block
/v3/blocks/{id}
View as Markdown

Creates a new block and connects it to one or more channels.

The value field accepts either a URL or text content:

  • If value is a valid URL, the block type is inferred (Image, Link, Embed, etc.)
  • If value is plain text, a Text block is created

You can connect the block to multiple channels at once (up to 20).

Authentication required.

Body Params
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)
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"]`).
insert_at
integer
Position to insert the block in the channel. Only valid when connecting to a single channel.
POST
https://api.are.na/v3/blocks
TextBlock
TextBlock
A text block containing markdown content
id
integer!
Unique identifier for the block
base_type
string!
Base type of the block (always "Block")
Block
title
string | null
Block title
description
MarkdownContent
Block description with multiple renderings
MarkdownContent
MarkdownContent
Markdown content with multiple renderings
unknown
null
state
BlockState!
Processing state of a block.
processingavailablefailed
visibility
BlockVisibility!
Visibility of a block.
publicprivateorphan
comment_count
integer!
Number of comments on the block
created_at
string (date-time)!
When the block was created
updated_at
string (date-time)!
When the block was last updated
user
EmbeddedUser!
Embedded user representation (used when user is nested in other resources)
id
integer!
Unique identifier for the user
type
string!
User type
User
name
string!
User's display name
slug
string!
URL-safe identifier (use this in API paths)
avatar
string | null (uri)!
URL to user's avatar image
initials
string!
User's initials
source
BlockSource
Source URL and metadata (if block was created from a URL)
BlockSource
BlockSource
unknown
null
_links
Links!
HATEOAS links for navigation and discovery.
self
Link!
A hypermedia link containing the URL of a linked resource.
connection
EmbeddedConnection
Connection context (only present when block is returned as part of channel contents).
EmbeddedConnection
EmbeddedConnection
Embedded connection representation used when connection is nested in other resources
unknown
null
can
BlockAbilities
Abilities object (only present for full block responses, not in channel contents).
BlockAbilities
BlockAbilities
Actions the current user can perform on the block
unknown
null
type
string!
Block type (always "Text" for TextBlock)
Text
content
MarkdownContent!
Markdown content with multiple renderings
markdown
string!
Original markdown value
html
string!
HTML rendering of the markdown
plain
string!
Plain text rendering of the markdown
ImageBlock
ImageBlock
An image block containing an uploaded or scraped image
id
integer!
Unique identifier for the block
base_type
string!
Base type of the block (always "Block")
Block
title
string | null
Block title
description
MarkdownContent
Block description with multiple renderings
MarkdownContent
MarkdownContent
Markdown content with multiple renderings
unknown
null
state
BlockState!
Processing state of a block.
processingavailablefailed
visibility
BlockVisibility!
Visibility of a block.
publicprivateorphan
comment_count
integer!
Number of comments on the block
created_at
string (date-time)!
When the block was created
updated_at
string (date-time)!
When the block was last updated
user
EmbeddedUser!
Embedded user representation (used when user is nested in other resources)
id
integer!
Unique identifier for the user
type
string!
User type
User
name
string!
User's display name
slug
string!
URL-safe identifier (use this in API paths)
avatar
string | null (uri)!
URL to user's avatar image
initials
string!
User's initials
source
BlockSource
Source URL and metadata (if block was created from a URL)
BlockSource
BlockSource
unknown
null
_links
Links!
HATEOAS links for navigation and discovery.
self
Link!
A hypermedia link containing the URL of a linked resource.
connection
EmbeddedConnection
Connection context (only present when block is returned as part of channel contents).
EmbeddedConnection
EmbeddedConnection
Embedded connection representation used when connection is nested in other resources
unknown
null
can
BlockAbilities
Abilities object (only present for full block responses, not in channel contents).
BlockAbilities
BlockAbilities
Actions the current user can perform on the block
unknown
null
type
string!
Block type (always "Image" for ImageBlock)
Image
image
BlockImage!
alt_text
string | null
Alternative text associated with the image
blurhash
string | null
BlurHash representation of the image for progressive loading
width
integer | null
Original image width in pixels
height
integer | null
Original image height in pixels
src
string (uri)
URL to the original image
aspect_ratio
number | null (float)
Image aspect ratio (width / height)
content_type
string
Image content type
filename
string
Image filename
file_size
integer | null
File size in bytes
updated_at
string (date-time)
When the image was last updated
small
ImageVersion!
A resized/processed version of an image with multiple resolution URLs
medium
ImageVersion!
A resized/processed version of an image with multiple resolution URLs
large
ImageVersion!
A resized/processed version of an image with multiple resolution URLs
square
ImageVersion!
A resized/processed version of an image with multiple resolution URLs
LinkBlock
LinkBlock
A link block representing a URL with optional preview
id
integer!
Unique identifier for the block
base_type
string!
Base type of the block (always "Block")
Block
title
string | null
Block title
description
MarkdownContent
Block description with multiple renderings
MarkdownContent
MarkdownContent
Markdown content with multiple renderings
unknown
null
state
BlockState!
Processing state of a block.
processingavailablefailed
visibility
BlockVisibility!
Visibility of a block.
publicprivateorphan
comment_count
integer!
Number of comments on the block
created_at
string (date-time)!
When the block was created
updated_at
string (date-time)!
When the block was last updated
user
EmbeddedUser!
Embedded user representation (used when user is nested in other resources)
id
integer!
Unique identifier for the user
type
string!
User type
User
name
string!
User's display name
slug
string!
URL-safe identifier (use this in API paths)
avatar
string | null (uri)!
URL to user's avatar image
initials
string!
User's initials
source
BlockSource
Source URL and metadata (if block was created from a URL)
BlockSource
BlockSource
unknown
null
_links
Links!
HATEOAS links for navigation and discovery.
self
Link!
A hypermedia link containing the URL of a linked resource.
connection
EmbeddedConnection
Connection context (only present when block is returned as part of channel contents).
EmbeddedConnection
EmbeddedConnection
Embedded connection representation used when connection is nested in other resources
unknown
null
can
BlockAbilities
Abilities object (only present for full block responses, not in channel contents).
BlockAbilities
BlockAbilities
Actions the current user can perform on the block
unknown
null
type
string!
Block type (always "Link" for LinkBlock)
Link
image
BlockImage
Preview image (if available)
BlockImage
BlockImage
unknown
null
content
MarkdownContent
Extracted text content from the link
MarkdownContent
MarkdownContent
Markdown content with multiple renderings
unknown
null
AttachmentBlock
AttachmentBlock
An attachment block containing an uploaded file
id
integer!
Unique identifier for the block
base_type
string!
Base type of the block (always "Block")
Block
title
string | null
Block title
description
MarkdownContent
Block description with multiple renderings
MarkdownContent
MarkdownContent
Markdown content with multiple renderings
unknown
null
state
BlockState!
Processing state of a block.
processingavailablefailed
visibility
BlockVisibility!
Visibility of a block.
publicprivateorphan
comment_count
integer!
Number of comments on the block
created_at
string (date-time)!
When the block was created
updated_at
string (date-time)!
When the block was last updated
user
EmbeddedUser!
Embedded user representation (used when user is nested in other resources)
id
integer!
Unique identifier for the user
type
string!
User type
User
name
string!
User's display name
slug
string!
URL-safe identifier (use this in API paths)
avatar
string | null (uri)!
URL to user's avatar image
initials
string!
User's initials
source
BlockSource
Source URL and metadata (if block was created from a URL)
BlockSource
BlockSource
unknown
null
_links
Links!
HATEOAS links for navigation and discovery.
self
Link!
A hypermedia link containing the URL of a linked resource.
connection
EmbeddedConnection
Connection context (only present when block is returned as part of channel contents).
EmbeddedConnection
EmbeddedConnection
Embedded connection representation used when connection is nested in other resources
unknown
null
can
BlockAbilities
Abilities object (only present for full block responses, not in channel contents).
BlockAbilities
BlockAbilities
Actions the current user can perform on the block
unknown
null
type
string!
Block type (always "Attachment" for AttachmentBlock)
Attachment
attachment
BlockAttachment!
filename
string | null
Attachment filename
content_type
string | null
Attachment content type
file_size
integer | null
File size in bytes
file_extension
string | null
File extension
updated_at
string | null (date-time)
When the attachment was last updated
url
string (uri)!
Attachment download URL
image
BlockImage
Preview image (for PDFs and other previewable files)
BlockImage
BlockImage
unknown
null
EmbedBlock
EmbedBlock
An embed block containing embedded media (video, audio, etc.)
id
integer!
Unique identifier for the block
base_type
string!
Base type of the block (always "Block")
Block
title
string | null
Block title
description
MarkdownContent
Block description with multiple renderings
MarkdownContent
MarkdownContent
Markdown content with multiple renderings
unknown
null
state
BlockState!
Processing state of a block.
processingavailablefailed
visibility
BlockVisibility!
Visibility of a block.
publicprivateorphan
comment_count
integer!
Number of comments on the block
created_at
string (date-time)!
When the block was created
updated_at
string (date-time)!
When the block was last updated
user
EmbeddedUser!
Embedded user representation (used when user is nested in other resources)
id
integer!
Unique identifier for the user
type
string!
User type
User
name
string!
User's display name
slug
string!
URL-safe identifier (use this in API paths)
avatar
string | null (uri)!
URL to user's avatar image
initials
string!
User's initials
source
BlockSource
Source URL and metadata (if block was created from a URL)
BlockSource
BlockSource
unknown
null
_links
Links!
HATEOAS links for navigation and discovery.
self
Link!
A hypermedia link containing the URL of a linked resource.
connection
EmbeddedConnection
Connection context (only present when block is returned as part of channel contents).
EmbeddedConnection
EmbeddedConnection
Embedded connection representation used when connection is nested in other resources
unknown
null
can
BlockAbilities
Abilities object (only present for full block responses, not in channel contents).
BlockAbilities
BlockAbilities
Actions the current user can perform on the block
unknown
null
type
string!
Block type (always "Embed" for EmbedBlock)
Embed
embed
BlockEmbed!
url
string | null (uri)
Embed URL
type
string | null
Embed type
title
string | null
Embed title
author_name
string | null
Author name
author_url
string | null (uri)
Author URL
source_url
string | null (uri)
Embed source URL
width
integer | null
Embed width
height
integer | null
Embed height
html
string | null
Embed HTML
thumbnail_url
string | null (uri)
Thumbnail URL
image
BlockImage
Thumbnail image (if available)
BlockImage
BlockImage
unknown
null
PendingBlock
PendingBlock
A block that is currently being processed. The final type (Text, Image, Link, etc.)
id
integer!
Unique identifier for the block
base_type
string!
Base type of the block (always "Block")
Block
title
string | null
Block title
description
MarkdownContent
Block description with multiple renderings
MarkdownContent
MarkdownContent
Markdown content with multiple renderings
unknown
null
state
BlockState!
Processing state of a block.
processingavailablefailed
visibility
BlockVisibility!
Visibility of a block.
publicprivateorphan
comment_count
integer!
Number of comments on the block
created_at
string (date-time)!
When the block was created
updated_at
string (date-time)!
When the block was last updated
user
EmbeddedUser!
Embedded user representation (used when user is nested in other resources)
id
integer!
Unique identifier for the user
type
string!
User type
User
name
string!
User's display name
slug
string!
URL-safe identifier (use this in API paths)
avatar
string | null (uri)!
URL to user's avatar image
initials
string!
User's initials
source
BlockSource
Source URL and metadata (if block was created from a URL)
BlockSource
BlockSource
unknown
null
_links
Links!
HATEOAS links for navigation and discovery.
self
Link!
A hypermedia link containing the URL of a linked resource.
connection
EmbeddedConnection
Connection context (only present when block is returned as part of channel contents).
EmbeddedConnection
EmbeddedConnection
Embedded connection representation used when connection is nested in other resources
unknown
null
can
BlockAbilities
Abilities object (only present for full block responses, not in channel contents).
BlockAbilities
BlockAbilities
Actions the current user can perform on the block
unknown
null
type
string!
Block type (always "PendingBlock" for blocks being processed)
PendingBlock
    Log in
    Sign up