API

Basics

The REST API is served under https://wikipedia2.org/mvp2/v1/. Requests that create or change data need a signed-in user: send the access token as Authorization: Bearer <token> (the website uses the auth_token cookie).

The headers below are optional. Requests without them behave exactly as before.

Idempotency-Key

Send Idempotency-Key on a POST that creates something to make it safe to retry after a timeout or a lost connection. Use any unique value per logical operation: a UUID, or a stable id such as workflowId/nodeId. Allowed: 1–128 characters of letters, digits and . _ : / -.

The server remembers the first response for 24 hours, per user. Login endpoints under /auth/ do not accept the header.

Keys are scoped to your user and to the dry run mode (see below), so the same key used with and without Compas-Dry-Run are two different keys. Stored key format:

compas:idem:v1:{userId}:{dry|real}:{Idempotency-Key}

curl -X POST https://wikipedia2.org/mvp2/v1/group-profiles \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2d4e-import-42" \
  -d '{"profileName":"Example group"}'

# Retry with the same key and body → same response, nothing new is created
HTTP/1.1 201 Created
Idempotent-Replayed: true
{"profileId":"…","profileUrl":"/group/…","warning":null}

Compas-Dry-Run · create sandbox data

Send Compas-Dry-Run: true to create entities in your personal sandbox. Dry run entities are real rows, but they are hidden from search, autocompletion and lists for everyone else, skip notifications and automatic translation, and are deleted 7 days after creation.

Dry run must be enabled for your account first (POST /mvp2/v1/settings/dry-run). Without it the request gets 403. Without sign-in it gets 401. A value other than true/false gets 400. Successful responses carry Compas-Dry-Run: true.

Combine it with Idempotency-Key to retry sandbox creates safely.

# 1. Allow dry run for your account (once)
curl -X POST https://wikipedia2.org/mvp2/v1/settings/dry-run \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}'

# 2. Create a sandbox profile
curl -X POST https://wikipedia2.org/mvp2/v1/human-profiles \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Compas-Dry-Run: true" \
  -d '{"profileName":"Test person","quoteId":"<quote uuid>"}'

HTTP/1.1 201 Created
Compas-Dry-Run: true

Compas-Include-Dry-Run · read your sandbox data

Reads never return dry run entities by default. Send Compas-Include-Dry-Run: true to also see your own dry run entities (never other users’) in search and autocompletion.

A request that sends Compas-Dry-Run: true also sees its own dry run entities. The header needs a signed-in user.

curl -X POST https://wikipedia2.org/mvp2/v1/main-search/autocompletion \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Compas-Include-Dry-Run: true" \
  -d '{"text":"Test person"}'

X-Bot-Version · label what a bot created

Bot accounts can send X-Bot-Version with the version of the script or importer that makes the request, for example X-Bot-Version: wikidata-import-1.4.2. The value is stored with each entity the request creates, so later you can find what a given version of your bot made.

Up to 32 characters: letters, digits, spaces and visible punctuation (ASCII). Leading and trailing spaces are dropped, and an empty value counts as not sent. A longer value or other characters get 400 and nothing is created. The header is optional, and it is ignored on requests from people’s own accounts.

curl -X POST https://wikipedia2.org/mvp2/v1/documents/quotes/from-web-page/ \
  -H "Authorization: Bearer $BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Bot-Version: wikidata-import-1.4.2" \
  -d '{"docId":"<document uuid>","quote":"…"}'