Registry Items

Upload and update registry items (blocks) within a project. This is the same endpoint used by the Stow CLI when you run stow push.

Upsert a registry item

POST https://stow.build/api/registry/items

Creates a new registry item or updates an existing one. If an item with the same name already exists in the project it will be replaced.

Request body

Registry item fields

Use the registry item spec for the full schema, field requirements, and framework-specific guidance, including supported framework values such as React, Vue, and Svelte.

Example request

curl -X POST https://stow.build/api/registry/items \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "projectSlug": "my-project",
    "registryItem": {
      "name": "hero-section",
      "type": "registry:block",
      "title": "Hero Section",
      "description": "A responsive hero section with gradient background.",
      "files": [
        {
          "path": "blocks/hero-section.tsx",
          "type": "registry:block",
          "content": "export default function HeroSection() { ... }"
        }
      ],
      "dependencies": ["framer-motion"],
      "meta": {
        "stow": {
          "framework": "React",
          "tokenPrice": 5,
          "isVisible": true,
          "previewUrl": "https://example.com/preview/hero"
        }
      }
    }
  }'

Success response

Returns 200 OK with an empty body on success. If the item did not previously exist it is created; if it did it is replaced.

Thumbnails

If you provide a meta.stow.thumbnailUrl, the image at that URL will be fetched and stored. The URL must return an image content type (PNG, JPEG, WebP, GIF, or SVG).

If you only provide a meta.stow.previewUrl and no thumbnail, a screenshot of the preview URL will be generated automatically.

Error responses