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