Save a Valentine online: the storage API.

Security model

• Whoever has the short link sees the Valentine. The id is random (12 characters from 31, practically unguessable) and the page is kept out of search engines (noindex). But anyone who knows the link can read what is in it, names and picture links included, also through GET /sites/<id>. Do not put in anything the recipient should not see.
• Only the edit key can change it. Creating a Valentine returns a key (vc_…, 40 random characters) that is shown exactly once. Only its SHA-256 hash is stored. If you lose the key you can no longer change or delete the Valentine; it simply expires after its period. The key does not belong in a link or in the data.
• No login needed. Creating, changing, pictures and deleting all work without an account. An account (Google only, no passwords) is only needed to manage several Valentines or to use premium; see below.
• Rotate the key: POST /sites/<id>/rotate-key issues a new one; the old one stops working immediately.
• Per-sender limits without storing IPs: for the daily limits a pseudonym is computed from the IP address (SHA-256 with a secret salt). The address itself is not stored.
• Pictures: the type is checked from the first bytes (JPEG, PNG, WebP, GIF, AVIF; no SVG). File ids are random.
• Browsers and CSRF: CORS is *, but no credentials cross origins. Writes authenticated by the session cookie alone only count when the Origin header is in ALLOWED_ORIGINS (https://d-solve.de); otherwise the request is treated as not signed in. Requests with an edit key (Authorization: Bearer vc_…) need no session and stay open for AI agents.
• Privacy: the data sits on a d-solve.de server at Cloudflare, is deleted when the period ends, and whoever has the link can see the Valentine. See the privacy notice (German).

Hard limits

The limits are cost caps. Their values live in exactly one place, workers/valentine-captcha-api/config.json, and the service returns them live at GET /api/limits (with today's usage under today). No caller can exceed them. An agent fetches them before creating anything. Daily quotas reset per UTC day.

The operator may also limit requests per sender and minute; that answers with 429 and "code":"rate" too. Which functions are on is listed in features (cloud, accounts, premium, bulk, urlImport).

Endpoints

API base: https://d-solve.de/valentine/api. All responses are JSON, timestamps are Unix seconds. Errors look like {"error":"…","code":"…"}; code is only present for some. Requests with a body send content-type: application/json. Auth means Authorization: Bearer <key>; the account endpoints use the session cookie instead. OPTIONS (CORS preflight) answers 204.

data may only contain the Valentine parameters: lang, to, from, title, subtitle, select, prompt, help, cells, img1 … img9, question, scale, readouts, reveal, msg (reference), plus the old names hint, name, by and message. Anything else is rejected with 400, so typos do not vanish silently. Checked on the way in: lang is en or de, cells is all, any or a list of squares 1–9, and every img… is a public http(s) picture address.

The pages themselves

An expired or deleted Valentine shows a short notice page (404). https://d-solve.de/valentine/ without an id leads to the link builder.

Walkthrough with curl

data consists of exactly the link parameters (all parameters): a flat JSON object, name → text, not URL-encoded (no %20). In title, subtitle, prompt, question and reveal, *asterisks* and line breaks (\n in JSON) work as in the link. Empty values are not stored; data: addresses are rejected (upload the picture instead). The examples assume:

API=https://d-solve.de/valentine/api

1. Look up limits and retention (optional)

curl -sS "$API/limits"

2. Create a Valentine

curl -sS -X POST "$API/sites" \
  -H "content-type: application/json" \
  -d '{
    "data": {
      "lang": "en",
      "to": "Sarah",
      "from": "Alex",
      "prompt": "a *cute* animal.",
      "cells": "1,3,5",
      "question": "On a scale of *0 to yes*,\nwill you be my valentine?",
      "scale": "NO,MAYBE,YES",
      "msg": "Dinner is at 8."
    },
    "retentionDays": 30
  }'

3. The response: short link and key

{
  "id": "k7m2p9q4r6t8",
  "url": "https://d-solve.de/valentine/k7m2p9q4r6t8",
  "subpages": {},
  "data": { "lang": "en", "to": "Sarah", … },
  "images": [], "imageCount": 0,
  "retentionDays": 30,
  "createdAt": 1790000000, "updatedAt": 1790000000, "expiresAt": 1792592000,
  "owned": false,
  "editKey": "vc_…40 characters…",
  "apiUrl": "https://d-solve.de/valentine/api/sites/k7m2p9q4r6t8",
  "note": "…"
}

Save the editKey now. It is never shown again. For the next steps:

ID=k7m2p9q4r6t8
KEY=vc_…

4. Read

curl -sS "$API/sites/$ID"

Public, no key. Returns data, images and expiresAt. The key is never included.

5. Change

curl -sS -X PUT "$API/sites/$ID" \
  -H "authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{"data": { "lang": "en", "to": "Sarah", "from": "Alex", "msg": "Dinner is at 9." }}'

data replaces everything stored so far. To change one value, read the Valentine first (step 4), edit the object and send it back in full.

6. Upload a picture

Three ways, all with the key; number and size are capped (limits.maxImagesPerSite, limits.maxImageBytes); JPEG, PNG, WebP, GIF and AVIF are accepted.

# a) raw bytes
curl -sS -X POST "$API/sites/$ID/images" \
  -H "authorization: Bearer $KEY" -H "content-type: image/jpeg" \
  --data-binary @kitten.jpg

# b) form with a "file" field
curl -sS -X POST "$API/sites/$ID/images" \
  -H "authorization: Bearer $KEY" -F "[email protected]"

# c) the server fetches a public picture itself (for AI agents)
curl -sS -X POST "$API/sites/$ID/images" \
  -H "authorization: Bearer $KEY" -H "content-type: application/json" \
  -d '{"url":"https://upload.wikimedia.org/wikipedia/commons/…/kitten.jpg"}'

{ "id": "…", "url": "https://d-solve.de/valentine/img/….jpg", "contentType": "image/jpeg", "size": 183422, "imageCount": 1, "maxImages": 9 }

7. Use the picture URL in data

The returned url is an ordinary picture link. Put it in any img1 … img9. The Valentine only changes once you write the data:

curl -sS -X PUT "$API/sites/$ID" \
  -H "authorization: Bearer $KEY" -H "content-type: application/json" \
  -d '{"data": { …all values so far…, "img1": "https://d-solve.de/valentine/img/….jpg" }}'

Delete a picture: curl -sS -X DELETE "$API/sites/$ID/images/<imageId>" -H "authorization: Bearer $KEY". The picture id is in the upload response and in GET /sites/:id/images.

8. Check and change the retention

curl -sS "$API/sites/$ID" | grep -o '"expiresAt":[0-9]*'     # Unix seconds, date -d @1792592000
curl -sS -X PUT "$API/sites/$ID" \
  -H "authorization: Bearer $KEY" -H "content-type: application/json" \
  -d '{"retentionDays": 90}'

retentionDays must be one of the allowed options (step 1) and restarts the period from now. data and retentionDays can be combined in one request.

9. Verify and rotate the key

curl -sS -X POST "$API/sites/$ID/verify"     -H "authorization: Bearer $KEY"
curl -sS -X POST "$API/sites/$ID/rotate-key" -H "authorization: Bearer $KEY"   # {"editKey":"vc_…"}; the old key stops working at once

10. Delete

curl -sS -X DELETE "$API/sites/$ID" -H "authorization: Bearer $KEY"

Deletes the Valentine and all its pictures for good. The short link then shows a notice page.

Errors

For AI agents

If you can make HTTP requests, you can create the Valentine yourself. If you cannot, give the user the finished curl command or the long link. Everything about the content of the Valentine is in llms.txt; this section is only about storing it. MCP clients use the MCP server instead of raw HTTP.

Recipe

1. Ask: short link with storage (data on the server, deleted after the period) or long link without storage (private, nothing stored)? Do not decide silently for the user.
2. Read the limits: GET /api/limits. If features.cloud is false or the request fails, stay with the long link. Let the user pick a period from retention.options (default retention.defaultDays).
3. Build the data: the same parameters as in the link, as JSON, not URL-encoded. Leave uploaded pictures out for now, or keep public picture links.
4. Create: POST /api/sites with {data, retentionDays}. Keep id, url and editKey from the response.
5. Pictures: for each one, POST /api/sites/<id>/images with {"url":"https://…"} (server import). Set the returned url as the value of img1 … img9 in data, then PUT /api/sites/<id> with the complete data.
6. Check: GET /api/sites/<id>, then open the short link or hand it to the user.
7. Tell the user: the short link, the edit key and the expiry as a date (from expiresAt).

Rules

• Show the edit key to the user once, clearly, and ask them to save it (password manager, a note). It is the only way to change or delete the Valentine later. It is never shown again, and you cannot keep it for them.
• Never put the key into a link, into data, into a request URL or to third parties. It belongs in the Authorization header.
• State the retention and say the Valentine is deleted afterwards. To extend it, call PUT with retentionDays.
• Use the {url} import for pictures when you cannot send files. Only use addresses you actually found and checked.
• Always write in full: PUT with data replaces everything. GET first, edit, then PUT.
• On 429 or 503 fall back to the link mode and deliver the long link; tell the user briefly why.
• On 409 image-limit use fewer pictures or delete an old one; do not retry.
• The user can carry on by hand: in the link builder, load the short link and key.

MCP server

For chat clients that cannot make HTTP calls themselves (Claude, ChatGPT and other MCP clients) the same API is available as a remote MCP server (Model Context Protocol): https://d-solve.de/valentine/mcp, transport Streamable HTTP, JSON-RPC 2.0 over POST, no authentication, no sessions. Add it as a connector or custom integration; the server’s instructions point to llms.txt.

Every tool is exactly one of the endpoints above, through the same handler, with the same validation, limits and error codes. The edit key is a tool argument (editKey) and becomes the Authorization header internally.

Results are JSON, as text and as structuredContent. An API error becomes a tool result with isError: true and the fields status, error and code. Try it with curl:

curl -sS -X POST https://d-solve.de/valentine/mcp -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Accounts, premium and bulk creation are not exposed as tools; agents work with the edit key. GET /valentine/mcp answers 405 with a short description, and the OpenAPI document names the server under x-mcp.

Accounts, premium and Stripe

An account is optional and only needed for premium or several Valentines. There are no passwords, only sign-in with Google.

• Sign in: GET /api/auth/providers lists the available providers (currently Google only, via accounts.providers). GET /api/auth/login?provider=google&return=<address> redirects to Google (OAuth 2.1 Authorization Code with PKCE; the worker is the confidential client, no token reaches the browser). The return address must be on an allowed origin (https://d-solve.de). After the callback the worker sets the HttpOnly cookie __Secure-vc_session (Secure, SameSite=Lax, Path=/valentine; 30 days sliding, 90 at most) and redirects to <return>#/auth/ok. The session is stored in D1 only as a SHA-256 hash. End it with POST /api/auth/logout (this one) or POST /api/auth/logout-all (all).
• Account and limits: GET /api/auth/me shows name, premium status and this account’s limits. GET /api/me/sites lists your own Valentines.
• Attaching Valentines to the account: a Valentine created while signed in belongs to the account, and the owner may write without the key. One created without an account is taken over with POST /api/sites/<id>/claim and {"editKey":"…"}; the key stays valid as well. How many Valentines an account may hold and which periods apply is in /api/auth/me under limits.
• Premium: POST /api/billing/checkout with {"return":"…"} returns a Stripe Checkout address for a subscription (price from premium.stripePriceId, monthly or yearly). Afterwards the browser goes to <return>#/konto/premium-ok, on cancel to <return>#/konto. Premium lasts until the end of the paid period plus 3 days grace and ends when the subscription is cancelled. To cancel or change payment details, POST /api/billing/portal with {"return":"…"} returns the address of the Stripe customer portal. Activation arrives through the Stripe webhook, not through the return address. Only offered when premium.available in /api/limits is true.
• Bulk creation: POST /api/sites/bulk creates up to 50 Valentines at once for premium accounts (for a whole class or team), as long as features.bulk is on, which it is for the Valentine service.

More

• OpenAPI description (JSON) for tools that read interfaces automatically.
• Link builder: save online with a click, upload pictures, load Valentines.
• Documentation: how it works, every parameter, host your own copy.
• llms.txt: the complete instructions for AI agents (parameters, pictures, API, MCP) in one file.
• MCP server: the same API for chat clients, see above.
• Run it yourself: the service is a Cloudflare Worker, see workers/valentine-captcha-api/ in the repository.