Skip to main content

Payload

Payload is the CMS Viewfield supports first: Viewfield's own blog runs on it, and the same instance is what the connector is tested against. Connect your Payload and a reviewed piece is saved in your posts collection as a draft version, with its images, and published as that one document when a manager presses Publish.

Payload 3.x, spoken to over its REST API. A key made before Payload 3.46 must be generated again once your Payload runs version 4.

What your Payload needs​

A developer sets this up once, in payload.config:

  1. API keys on your users collection: auth: { useAPIKey: true }.
  2. One integration user for Viewfield, with Enable API Key ticked. Give it the smallest access that works:
    • on your posts collection: create, read, update and readVersions;
    • on your media collection: create (read is public);
    • on the users collection: read on its own record. Payload checks a key by reading its user under the user's own access rules, so without this a live key answers "forbidden" there instead of the user. The connect check names this rule when it is missing, and the connect form says it up front.
  3. Drafts on for posts: versions: { drafts: true }. Without it a save would create a live document; with it, Viewfield writes _status: 'draft' and the live version stays as it was.
  4. Visitors read only published posts: the collection's read access filters anonymous reads to _status: 'published'. Viewfield proves this before its first write by reading the collection without the key and expecting no draft back; a Payload that shows drafts to anyone is refused until the rule is fixed.
  5. Keep at least one post in the collection. Payload has no schema endpoint, so Viewfield reads your fields, and what your editor can load (lists, quotes, images, code blocks), from the posts already there. An empty collection cannot be chosen: create one draft in it in Payload, then choose it again.

Recommended, and what Viewfield's own instance does: alt required on media, the SEO plugin (meta.title, meta.description, meta.image), the template's slugField with its slug lock, and Payload's own internal collections (payload-locked-documents, payload-migrations) closed to non-admins.

The whole header Payload documents, users API-Key <key>, can be pasted as the key: Viewfield reads the collection name out of it.

Connecting​

Under Settings › Connections › Payload (or in the welcome), paste the key. Viewfield:

  1. finds Payload on your website without sending the key: it asks /api/access at your site, which Payload answers for any visitor, and tries a custom path (/cms) when you typed one; only an answer that is Payload's is sent the key. When Payload is not found there, the form asks for the address it runs at, like https://cms.acme.com. The key is only ever sent over https to your own domain or to Payload Cloud (*.payloadcms.app);
  2. proves the key against /me and reads what the user may do from /api/access;
  3. lists your collections, each with whether Viewfield can write to it (a collection with drafts off is shown and marked as not writable).

A key Payload does not know answers like an anonymous visitor rather than with a 401, so a refused call is checked against /me again: a user in the answer is a permission gap for that one call, and user: null is a dead key, which marks the connection for reconnecting. Regenerating the key in Payload and reconnecting fixes it.

The destination​

A Payload connection does not choose your posts collection for you: under the connection, add a destination and pick it. Viewfield reads up to twenty documents from it to learn the body field and its format (Lexical, Markdown or HTML), the slug lock, the upload collection and the editor's features, and suggests the mapping of the title, slug, body, excerpt, SEO fields, image and publish date. Add the public URL rule, the address a post has on your site (https://acme.com/blog/{slug}), so Viewfield can check the page once it is live and offer Publish.

While your collection holds no draft yet, Viewfield reads Payload's own access rules as a visitor sees them: a read rule that shows visitors only published documents (for example, _status equals published) proves drafts are private, and one that lets visitors read everything stops the send. When the rules do not say either way, the destination asks you, before the first send, to tick that your read access hides drafts from visitors. Once a draft exists, Viewfield checks it itself.

What Viewfield writes​

  • The body compiled to Lexical when your body field is rich text: headings, paragraphs, lists, quotes, links (with ids, as Payload 3 writes them), inline code, the template's Code block for fenced code, and upload nodes for images. The compile is deterministic, so what you reviewed is what is sent. A Markdown or HTML body field takes the text as is.
  • Blocks Viewfield does not know are not written; a custom block schema is handed off.
  • The slug, with generateSlug: false, so Payload keeps the one you reviewed.
  • The title, the excerpt, the SEO fields and the publish date (the post form's Publish date, today unless you change it), and the destination's own mapped fields from the post form (an author, categories, tags, the values your collection requires).
  • Images, uploaded to your media collection first, once, and placed as upload nodes.

A save sends ?draft=true with _status: 'draft', so the live version is untouched. Publish re-reads the latest draft, refuses unless it still holds exactly what Viewfield saved, and sets _status: 'published'. Visible on website appears once the public page at your URL rule, read with no key, shows the piece's title or opening words; the piece then reads Published. Without a URL rule on your own hosts, the post stays Published in CMS until a manager confirms it is live.

For a page change on a Payload page whose body is Lexical, Viewfield writes the title, the meta description and the H1 where they are mapped; a change to the body (an opening, a section, an FAQ, a comparison table) is copied in by hand. A Markdown or HTML body takes those too.

What Viewfield refuses, and why​

  • A post someone has open in Payload's editor answers 423: Viewfield reports it as locked, applies nothing, and the same write succeeds once the post is closed.
  • A post edited in the admin after Viewfield's draft is refused: an update because the live copy moved, a publish because the draft is no longer ours. Prepare an update from the editor.
  • An interrupted create (a timeout after Payload may have created the document) is proven only through a correlation field on the destination: a text field of your collection that holds Viewfield's id for the post, suggested when the collection has one named viewfieldId and mappable by hand under Viewfield id. Without one, Viewfield stops at once and asks you to check Payload rather than guess: say I checked: it is not there to send again, or I checked: it is there with the document's id to link it. An interrupted update is proven by its content: the newest draft in Payload is compared with what Viewfield sent, and a draft that holds other content is yours to look at.
  • A collection without drafts, or whose drafts anyone can read, is refused until the config is fixed.
  • Never an administrator password, never a write where drafts are visible to the public, never a site that is not on your own hosts.

Availability​

Tested against a live Payload 3.90.2 that Viewfield runs: the connector passed every check of the run against Viewfield's own deployed Payload (connect, describe, save as draft with an image, an anonymous read that cannot see the draft, publish, a visitor's read of the published post, the 423, the refused update after an admin edit, and the published post served at its public address on viewfield.ai) on October 14, 2026, so sending drafts, images and publishing are open to every workspace. That run was on Viewfield's own instance, not a customer's account, which is why this page says tested and not verified. The connect form always says what a connection does in your workspace today.

Our own blog​

Viewfield's blog at viewfield.ai/blog is a Payload instance exactly like the one described here, and new posts are written in Viewfield and published through the product.