Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

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:project scope, and publish:project to 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.

LayerBecomes
A named textA text field
A named imageAn image field
A named frame with a background imageA background field
The background image of the section itselfA background field named background
A named slider or other element with repeated itemsA 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": []
  }
}
FieldMeaning
nameThe section name. You use it to add the section to a page.
pageThe library page the section is on. A library can have the same section name on two pages, for example one page per language.
placementheader, content or footer.
fieldsValues you can set. example is the value in the library.
listsRepeated items, such as cards or slides. You send one entry per item.
warningsLayers 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.json

summer.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]"
  }
}
ValueRules
sectionThe section name. Add "page": "Home FR" when the name is on more than one library page.
Text fieldPlain text. A blank line starts a new paragraph. A heading stays a heading. HTML shows as text.
Image and background fieldA public https:// URL to an image of at most 20 MB. Vev copies the image into the project.
ListOne object per item. Each item has the fields of the list.
Fields you leave outKeep 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.

resultMeaning
updatedThe content was changed.
detachedA designer detached the section in the editor. The API leaves it alone.
not_foundNo 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.json

summer-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"
  }
}
FieldRules
libraryThe project gets the breakpoints and the variables of the library.
pagesUp to 20 pages. The first page is the home page. Sections work as in Create a page with your content.
variablesValues for the library's variables, as in Project Variables.
publishPublishes 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"
  }
}