Blocks

Reusable content blocks — list, get by ID, get by slug.

Blocks are the building pieces of your website pages. A block can be a hero section, a pricing table, a testimonials list, a CTA banner, anything you set up in the dashboard. Each block has a list of typed fields (text, image, video) that your frontend reads and renders.

List blocks

GET /api/organizations/{orgId}/blocks

Returns all published blocks for the organization.

Query parameters

Name Type Description
pages string Comma-separated list of pages to filter blocks by (e.g. home,pricing).

Response

{
  "items": [
    {
      "id": "blk_1",
      "slug": "homepage-hero",
      "name": "Homepage Hero",
      "status": "published",
      "fields": [
        { "key": "title", "type": "text", "value": "Grow with content" },
        { "key": "image", "type": "image", "value": { "url": "...", "alt": "..." } }
      ]
    }
  ]
}

Example (curl)

curl "https://www.inventra.sh/api/organizations/$ORG_ID/blocks?pages=home" \
  -H "x-api-key: $API_KEY"

Example (TypeScript)

const res = await fetch(
  `https://www.inventra.sh/api/organizations/${ORG_ID}/blocks?pages=home`,
  { headers: { 'x-api-key': API_KEY } }
);
const { items } = await res.json();

SDK equivalent

const blocks = await inventra.blocks.list({ pages: ['home'] });

Get a block by ID

GET /api/organizations/{orgId}/blocks/{blockId}

Response

A single Block object (same shape as items in the list response) or 404 if not found or not published.

Get a block by slug

GET /api/organizations/{orgId}/blocks/by-slug/{slug}

Returns the block whose slug frontmatter matches.

Response

{
  "id": "blk_1",
  "slug": "homepage-hero",
  "name": "Homepage Hero",
  "status": "published",
  "fields": [ /* ... */ ]
}

Example (TypeScript)

const hero = await inventra.blocks.getBySlug('homepage-hero');

Field types

Each block contains a list of fields. Every field has key, type, and value. The shape of value depends on the type:

Type value shape
text string
image { url: string; alt: string }
video { url: string; status: 'ready' | 'processing' | 'failed' }

The SDK provides Blocks.getText(block, key) and Blocks.getImage(block, key) helpers that return typed values directly — see the SDK Blocks reference.

PreviousOverviewNextContents