Made in Builder.io

Watch the biggest Figma-to-code launch of the year

Builder.io logo
Talk to Us
Platform
Developers
Talk to Us

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",
  }
}

Looking to hire a third party to help with your project?

Submit a project request and our partnerships team will reach out to connect you with an Expert from our partner ecosystem.

Connect with us

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