Register now: Best Builder Practices for Marketers & Designers

Announcing Visual Copilot - Figma to production in half the time

Builder.io logo
Contact Sales
Platform
Developers
Contact Sales

Blog

Home

Resources

Blog

Forum

Github

Login

Signup

×

Visual CMS

Drag-and-drop visual editor and headless CMS for any tech stack

Theme Studio for Shopify

Build and optimize your Shopify-hosted storefront, no coding required

Resources

Blog

Get StartedLogin

With the Write API you can POST, PATCH, PUT, and DELETE Builder content using HTTP Request Methods. You can use the Write API for use cases such as writing programmatically from your own internal application, or as part of a code release and build process.

Tip: The Write API is separate from the Admin API. If you need to administer Builder Spaces and create, read, update, and delete models, use the Admin API.

To use the instructions in this document, you need:

To create new entries in Builder, send a POST request as follows:

curl https://builder.io/api/v1/write/MODEL_NAME \
  -X POST \
  -d '{ "name": "Hi!", "data": { "field": "value" } }' \
  -H 'Authorization: Bearer YOUR_PRIVATE_KEY' \
  -H 'Content-Type: application/json'

# Example response
# {
#  "name": "Hi!",
#  "id": "ca7397dfdcd93",
#  "data": { "field": "value" }
# }

Each time you send a POST request, a new resource is created.

When using the POST method with the Builder Write API, the payload of the POST request must contain content data that conforms to the structure defined by the schema.

Include in your POST requests properties such as name, modelId, published, and data. The data property can contain various fields based on your content requirements, such as title, blocks, inputs, and state.

The data property can be any arbitrary key-value pairs, with an optional blocks property. If data does include a blocks property, the blocks property must be an array of Builder blocks.

You only need the blocks property if you're using Page or Section models; that is, a visual feature. With a Data model, there is only data and no blocks, so the blocks property isn't applicable.

The BuilderBlock interface defines a Builder block, which is a nested element used in Builder's Visual Editor. The following is an excerpt of BuilderBlock interface featuring the most commonly used properties.

Refer to this object shape when sending a POST request to the Write API:

interface BuilderBlock {
  '@type': '@builder.io/sdk:Element';
  tagName?: string;
  responsiveStyles?: {
    large?: Record<string, string>;
    medium?: Record<string, string>;
    small?: Record<string, string>;
  };
  component?: {
    name: string;
    options?: Record<string, any>;
  };
  children?: BuilderBlock[];
  ...
}

For the complete BuilderBlock interface, which includes many additional properties, such as bindings, actions, and code, see the source code on GitHub.

A detailed example of a POST request is as follows:

// example POST request

curl https://builder.io/api/v1/write/MODEL_NAME \
  -X POST \
  -d '{
    "name": "Hi!",
    "data": {
      "blocks": [
        {
          "@type": "@builder.io/sdk:Element",
          "tagName": "div",
          "children": [
            {
              "@type": "@builder.io/sdk:Element",
              "component": {
                "name": "Text",
                "options": {
                  "text": "Hello World"
                }
              }
            }
          ]
        }
      ],
      "customProperty": "Custom value"
    }
  }' \
  -H 'Authorization: Bearer YOUR_PRIVATE_KEY' \
  -H 'Content-Type: application/json'

When sending a POST request for a Data model, omit the blocks property, for example:

// example data property for a Data model
...
{
  "data": {
     "message": "my message value",
     "count": 10
  }
}
...

When sending a POST request for a Page or Section model, be sure to include the blocks property, for example:

// example data property for a Page or Section model
...
{
  "data": {
     "blocks": [...],
     "message": "my message value",
     "count": 10
  }
}
...

For more information, read the MDN document, POST.

Use a PUT request to create or replace an entire resource.

When sending a PUT request, provide the complete representation of the resource you want to replace. This replaces the existing resource, or if the resource doesn't exist, it creates a new resource. If you don't specify a property, it is deleted.

To replace entries in Builder, send a PUT request as follows:

curl https://builder.io/api/v1/write/MODEL_NAME/ENTRY_ID \
  -X PUT \
  -d '{ "data": { "field": "newValue" } }' \
  -H 'Authorization: Bearer YOUR_PRIVATE_KEY' \
  -H 'Content-Type: application/json'

# Example response
# {
#  "id": "ca7397dfdcd93",
#  "data": { "field": "newValue" }
# }

For more information, read the MDN document, PUT.

Use a PATCH request to update or modify a specific part or property of an existing resource. Unlike PUT, which replaces the entire resource, PATCH only updates the specified fields or properties.

In a PATCH request, you send the changes you want to make those changes apply to the existing resource. PATCH is useful when you want to modify specific attributes without sending the entire resource representation.

To update entries in Builder, send a PATCH request as follows:

curl https://builder.io/api/v1/write/MODEL_NAME/ENTRY_ID \
  -X PATCH \
  -d '{ "data": { "field": "newValue" } }' \
  -H 'Authorization: Bearer YOUR_PRIVATE_KEY' \
  -H 'Content-Type: application/json'

# Example response
# {
#  "name": "Hi!",
#  "id": "ca7397dfdcd93",
#  "data": { "field": "newValue" }
# }

For more information, read the MDN document, PATCH.

To delete entries in Builder, send a DELETE request as in the following:

curl https://builder.io/api/v1/write/MODEL_NAME/ENTRY_ID \
  -X DELETE \
  -H 'Authorization: Bearer YOUR_PRIVATE_KEY'

# Example response
# {
#  "message": "Success"
# }

For more information, read the MDN document, DELETE.

The following is an example of the shape of the content to send in the body of a request to the Write API. This example reflects the shape of the content that Builder uses in the Visual Editor and is informed by Builder's JSON schema.

{
  "name": "My content name",
  // set published to: "archived", "draft", or "published"
  "published": "draft",
  // Optional. query is where you specify your targeting properties
  "query": [
    {
      "property": "urlPath",
      "operator": "is",
      "value": "/test-out-json"
    }
  ],
  // example of a custom field. See 
  // https://www.builder.io/c/docs/custom-fields
  // The type is what you specified in the model 
  // when creating the custom field. 
  "data": {
    "someProperty": "hello",
  }
}
Was this article helpful?

Product

Visual CMS

Theme Studio for Shopify

Sign up

Login

Featured Integrations

React

Angular

Next.js

Gatsby

Get In Touch

Chat With Us

Twitter

Linkedin

Careers

© 2020 Builder.io, Inc.

Security

Privacy Policy

Terms of Service

Newsletter

Get the latest from Builder.io

By submitting, you agree to our Privacy Policy

Product

Platform Overview

Integrations

What's New

Open Source

Builder

Builder

Mitosis

Mitosis

Qwik

Qwik

Partytown

Partytown

Popular Guides

From Design to Code Guide

Composable Commerce Guide

Headless CMS Guide

Headless Commerce Guide

Composable DXP Guide

Design to Code

Resources

Blog

Knowledge Base

Community Forum

Partners

Templates

Success Stories

Showcase

Resource Center

Frameworks

React

React

Next

Next.js

Qwik

Qwik

Gatsby

Gatsby

Angular

Angular

Vue

Vue

Svelte

Svelte

Remix logo

Remix

Nuxt

Nuxt

Hydrogen

Hydrogen

See All

© 2024 Builder.io, Inc.

Security

Privacy Policy

SaaS Terms

Security & Compliance

Cookie Preferences