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