Bulk upsert articles

Add or update a batch of articles in one call. Unlike POST /locations-directory/articles, this endpoint does not create a new article every time: an article's identity here is the combination of its type_id and its set of linked LOCATION/SERVICE/STAFF entities (its "link tuple"), so re-submitting that same combination versions the existing article instead of creating a second one or failing with a conflict. It targets article types whose link patterns all have MULTIPLE cardinality — types with a SINGLE-cardinality pattern must be written through POST /locations-directory/articles instead, which enforces the "at most one live article per entity" rule this endpoint does not.

Applying a batch is all-or-nothing: if any article in articles fails validation, the whole batch is rejected with 422 Unprocessable Entity and nothing is written.

A version_token identifies one write run, and a run may span several calls to this endpoint when a source document has more than 100 articles — every call in the run must carry the same version_token, because POST /locations-directory/articles/rollback uses it to undo the run as a unit. Re-submitting a link tuple under a version_token that already wrote it is treated as retrying that exact write and is skipped, even if the submitted content differs — see version_token below for the full contract and the reason a fresh token must be minted per run.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…

Scope

locations-directory:write

Body Params

The batch of articles to upsert.

One batch of articles to upsert. version_token and source_key are batch-level (they apply to every article in articles, not per article) — see the field descriptions and the endpoint description for the full contract.

string
required
length ≤ 255

An opaque token identifying one write run. A run may span several calls to this endpoint (for example, a source document with more than 100 articles needs several batches), and every call in the same run must carry the same version_token — rollback (POST /locations-directory/articles/rollback) is keyed on it and undoes a whole run at once. Mint a fresh token per run (a job id, a UUID, anything unique), never per request and never derived from something stable like a document id: re-submitting an article identity (type_id plus its set of linked entities) under a token it already carries is treated as retrying that exact write, and is silently skipped — even when the content differs. Must not contain control characters.

string
required
length ≤ 255

Free-form identifier of the source document this batch came from (for example a file path or an external document id). Not used for identity or deduplication — purely descriptive. Must not contain control characters.

articles
array of objects
required
length between 1 and 100

The articles to upsert. 1 to 100 items. Each entry has the same shape as the POST /locations-directory/articles request body. Within one batch, no two articles may share the same type_id and set of linked entities — that combination is an article's identity, and repeating it in the same request is rejected as invalid rather than silently applied twice.

articles*

An article is a versioned piece of content — for example a note or an FAQ entry — of a given article type (type_id), linked to one or more LOCATION, SERVICE, or STAFF entities. links must be present with at least one of locations/services/staff non-empty — see #/article_links.

string
required
length between 1 and 64

Id of the article type this article belongs to (see the Article Types API). The type determines the expected content format (free text or a JSON value validated against a JSON Schema) and which combinations of linked entities (links) are allowed.

string
required

The article's content. Its shape depends on the article type's configured content type: a JSON string for TEXT types, or an arbitrary JSON value validated against the type's JSON Schema for JSON types. Serializes to at most 100,000 characters.

tags
array of strings
Defaults to []

Free-form labels for the article, useful for filtering with GET /locations-directory/articles. Up to 50 tags, each up to 64 characters and non-blank.

tags
links
object
required
Responses

Language
Credentials
OAuth2
Missing 1 required scope
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json