Updating Content with the Write API

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.

Prerequisites

To use the instructions in this document, you need:

A Private API Key

Making requests to the Write API

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

`POST`

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

`PATCH`

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

`PUT`

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

`DELETE`

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

Example content JSON

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?