Pages from Your Content
Use a library as a template, and fill its sections with your own texts and images. The library holds the design. Your request holds the content.
Requirements
- A library with the sections you want to use.
- An API key with the
create:projectscope, andpublish:projectto publish (see Authentication).
The library key is in the editor URL when you open the library: https://editor.vev.design/edit/[libraryKey]/...
Prepare the library
You fill content by name. In the library, name the sections and the layers that you want to fill, in the layers panel.
| Layer | Becomes |
|---|---|
| A named text | A text field |
| A named image | An image field |
| A named frame with a background image | A background field |
| The background image of the section itself | A background field named background |
| A named slider or other element with repeated items | A list. The fields of its first item apply to every item. |
Section names must be unique on their library page. Field names must be unique within a section. Names are not case sensitive: Headline and headline are the same name. Layers without a name stay as they are in the library.
The API uses the last published version of the library. Publish the library after you rename layers or change sections.
See what a library can fill
curl https://api.vev.design/v2/libraries/[libraryKey]/sections \
--header "x-vev-key: [your-key]"{
"success": true,
"data": {
"sections": [
{
"name": "Hero",
"page": "Home",
"description": "Large headline over a full-width photo",
"placement": "content",
"fields": [
{ "name": "background", "type": "background", "example": "https://cdn.vev.design/.../beach.jpg" },
{ "name": "Headline", "type": "text", "example": "Summer is here" },
{ "name": "Button text", "type": "text", "example": "Book now" }
],
"lists": [],
"warnings": []
},
{
"name": "Destinations",
"page": "Home",
"placement": "content",
"fields": [{ "name": "Title", "type": "text", "example": "Where to next?" }],
"lists": [
{
"name": "Cards",
"fields": [
{ "name": "City", "type": "text", "example": "Lisbon" },
{ "name": "Photo", "type": "image", "example": "https://cdn.vev.design/.../lisbon.jpg" }
]
}
],
"warnings": ["Two or more layers are named \"Price\". Rename one to use it."]
}
],
"warnings": []
}
}| Field | Meaning |
|---|---|
name | The section name. You use it to add the section to a page. |
page | The library page the section is on. A library can have the same section name on two pages, for example one page per language. |
placement | header, content or footer. |
fields | Values you can set. example is the value in the library. |
lists | Repeated items, such as cards or slides. You send one entry per item. |
warnings | Layers or sections you cannot use yet, and how to fix them in the library. |
The list has the same sections as the library panel in the editor. Library pages that you share as whole pages, or exclude, are not in it.
Text that is linked to a project variable is not a field.
Create a page with your content
Send the library and the sections, top to bottom. Use the section, field and list names from the section list.
curl -X POST https://api.vev.design/v2/projects/[projectKey]/pages \
--header "x-vev-key: [your-key]" \
--header "Content-Type: application/json" \
--data @summer.jsonsummer.json:
{
"title": "Summer campaign",
"library": "[libraryKey]",
"sections": [
{
"section": "Hero",
"fields": {
"Headline": "Summer is here",
"Button text": "Book now",
"background": "https://images.example.com/beach.jpg"
}
},
{
"section": "Destinations",
"fields": { "Title": "Where to next?" },
"lists": {
"Cards": [
{ "City": "Lisbon", "Photo": "https://images.example.com/lisbon.jpg" },
{ "City": "Oslo", "Photo": "https://images.example.com/oslo.jpg" }
]
}
}
]
}{
"success": true,
"data": {
"pageKey": "[pageKey]",
"projectKey": "[projectKey]",
"editorUrl": "/edit/[projectKey]/[pageKey]"
}
}| Value | Rules |
|---|---|
section | The section name. Add "page": "Home FR" when the name is on more than one library page. |
| Text field | Plain text. A blank line starts a new paragraph. A heading stays a heading. HTML shows as text. |
| Image and background field | A public https:// URL to an image of at most 20 MB. Vev copies the image into the project. |
| List | One object per item. Each item has the fields of the list. |
| Fields you leave out | Keep the content from the library. |
Components from the library stay linked to it, as when you add a section in the editor. When the library gets a new version, the editor offers the update in the project.
To add the sections to an existing page, send its pageKey instead of title. The sections go below the content that is on the page.
Limits per request: 50 sections, 100 items per list and 50 different images.
To change brand colors, fonts or other values that the whole project uses, see Project Variables.
Link sections for later updates
Give a section an id to link it to your data. Use any key that is unique on the page, for example "hero" or "product-42".
{
"library": "[libraryKey]",
"sections": [
{ "id": "hero", "section": "Hero", "fields": { "Headline": "Summer is here" } }
]
}In the editor, the content you set in a linked section is locked: its texts, images and list items. Designers can still change the style and the layout, move the section or delete it. To edit the content in the editor, right-click the section and choose Detach from API. A detached section is no longer linked.
An id can have letters, digits, - and _, at most 64.
Update linked sections
Change the content of linked sections by their id. Fields you leave out keep their content.
curl -X PATCH https://api.vev.design/v2/projects/[projectKey]/pages/[pageKey]/sections \
--header "x-vev-key: [your-key]" \
--header "Content-Type: application/json" \
--data '{
"sections": [
{ "id": "hero", "fields": { "Headline": "Now 30% off" } },
{ "id": "cities", "lists": { "Cards": [{ "City": "Lisbon" }, { "City": "Rome" }, { "City": "Paris" }] } }
],
"publish": true
}'{
"success": true,
"data": {
"sections": [
{ "id": "hero", "result": "updated" },
{ "id": "cities", "result": "updated" }
],
"publishing": true
}
}A list you send replaces the list. Items are updated in order, new items are copies of the first item, and items past the end of your list are removed.
result | Meaning |
|---|---|
updated | The content was changed. |
detached | A designer detached the section in the editor. The API leaves it alone. |
not_found | No section on the page has this id, for example because a designer deleted it. |
Field names are the names in the section, as in the section list. You can also fill fields that you left out when you created the section.
publish publishes the project after the update. It needs the publish:project scope. If the editor is open, designers see the change at once.
Create a project in one call
Build a whole project from a library: pages with your content, values for the library's variables, and a publish to your Vev staging domain.
curl -X POST https://api.vev.design/v2/projects \
--header "x-vev-key: [your-key]" \
--header "Content-Type: application/json" \
--data @summer-project.jsonsummer-project.json:
{
"title": "Summer campaign",
"library": "[libraryKey]",
"variables": { "Brand color": "#e30613" },
"pages": [
{
"title": "Home",
"sections": [
{ "section": "Hero", "fields": { "Headline": "Summer is here", "background": "https://images.example.com/beach.jpg" } }
]
},
{
"title": "Destinations",
"sections": [
{ "section": "Destinations", "lists": { "Cards": [{ "City": "Lisbon" }, { "City": "Oslo" }] } }
]
}
],
"publish": true
}{
"success": true,
"data": {
"projectKey": "[projectKey]",
"editorUrl": "/edit/[projectKey]/[pageKey]",
"title": "Summer campaign",
"created": 1793706522432,
"index": "[pageKey]",
"pages": [
{ "pageKey": "[pageKey]", "title": "Home", "editorUrl": "/edit/[projectKey]/[pageKey]" },
{ "pageKey": "[pageKey2]", "title": "Destinations", "editorUrl": "/edit/[projectKey]/[pageKey2]" }
],
"url": "https://[your-staging-domain]/summer-campaign"
}
}| Field | Rules |
|---|---|
library | The project gets the breakpoints and the variables of the library. |
pages | Up to 20 pages. The first page is the home page. Sections work as in Create a page with your content. |
variables | Values for the library's variables, as in Project Variables. |
publish | Publishes the project to your Vev staging domain. Needs the publish:project scope. The first publish takes about a minute before url shows the page. |
Errors
If a name or a value is wrong, the API answers 400 and creates no page or project. The message says what to fix:
{
"success": false,
"error": {
"message": "The section \"Hero\" has no field \"Subtitle\". Fields: \"Headline\", \"Button text\", \"background\".",
"code": "bad_request",
"errorId": "44b2b5ba-5f03-40c0-a154-093b103dd10d"
}
}