Made in Builder

Made in Builder.io

How to Build: Localization webinar on March 23rd @ 10am PST. Register Now

×

Developers

Product

Use Cases

Pricing

Developers

Resources

Company

Log in

Product

Features

Integrations

Talk to an Expert

Pricing

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. 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:

The Write API supports POST, PATCH, PUT, and DELETE.

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

When sending a PATCH request, properties of the request body merge with the current document, so you do not need to supply the entire document contents, only what you have changed.

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

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

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

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.

{
  // ownerId is your Public API Key
  "ownerId": "YJIGb4i01jvw0SRdL5Bt",
  "createdDate": 1675443038945,
  // @version is type number 
  "@version": 3,
  // id is type string
  "name": "test-out-json",
  // modelId is type string.
  // modelId is the id of the model 
  // where the content is to be created
  "modelId": "38834b40eced4c24947a3909cb42be3e",
  // set published to: "archived", "draft", or "published"
  "published": "draft",
  // Optional. query is where you specify your targeting properties
  "query": [
    {
      "@type": "@builder.io/core: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 3rd 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?