VapCal – Guide for AI agents

This page describes the VapCal website for AI agents. It is not a code repository AGENTS.md.

Last updated: 2026-10-04 · Status: live · Profile version: creabyte-ai-0.1

Introduction

Calculators and charts for mixing vape liquids: nicotine mix chart, single mix, shots, coil, PG/VG, dilute/boost and batch cost.

For: Adults (18+) who mix their own e-liquids.

What it is not:

• No shop: VapCal sells no liquids, nicotine or hardware.
• No subscription: support payments are one-time and add up; they pay for the infrastructure.
• No medical advice.
• No public price list for shop embed or white-label (on request).
• No data export for accounts.
• No OpenAPI description, no MCP server.
• No account deletion through agent keys.

Imprint

• Operator: Creabyte (https://creabyte.com)
• Legal form: sole proprietorship (currently inactive)
• Seat: Solothurn, Switzerland
• Full imprint: https://www.vapcal.com/impressum

Contact

Contact form only: https://www.vapcal.com/contact. No public email address.

• The contact form is the channel for every written inquiry: calculators, accounts, support payments, shop embed, white-label and custom work.
• An agent can prepare the message. The person reviews it and submits the form.
• The Impressum (https://www.vapcal.com/impressum) is the legal notice, not a contact channel.

How agents can act

• Read and cite: available. Public, no account: the pages linked from https://www.vapcal.com/llms.txt, their Markdown copies, and the calculators marked public in Tooling.
• Prepare a request that a person submits: available. The contact form, and a support payment (support:prepare): the agent prepares it, the person checks it and pays on https://www.vapcal.com/support.
• Run a calculation via deep link: available. The same URL returns the page or, for agents, Markdown (see Tooling).
• Run a calculation with an agent key: available when the key has calc:run and the account has unlocked that calculator (see Tooling and Authorization).
• Act for a logged-in person with an agent key: available. The account holder creates the key and hands it to the agent (see Authorization). Needs an account.

Tooling

Eight calculators. Full entries (method, parameters, example request, example response, formats, auth, side effects, limits) are in tools.md. Short list:

• single-mix (calc=simple, JSON kind=simple): Nicotine base and liquid amounts for one target strength. Access: public, free, no account.
• mix-chart (calc=chart, JSON kind=chart): Table of nicotine base and liquid amounts for ten target strengths. Access: public, free, no account.
• shot-calculator (calc=shots, JSON kind=shots): How many nicotine shots a bottle needs. Access: account with support level Unlock (support from EUR 6).
• ohm-watt (calc=coil, JSON kind=coil): Ohm's law for a coil build. Access: account with support level Tools (support from EUR 15).
• coil-wraps (calc=wraps, JSON kind=wraps): Resistance of a single round-wire coil. Access: account with support level Tools (support from EUR 15).
• pgvg-adjust (calc=pgvg, JSON kind=pgvg): How much PG or VG to add to reach a target ratio. Access: account with support level Tools (support from EUR 15).
• dilute-boost (calc=dilute, JSON kind=dilute): Lower or raise the nicotine strength of an existing liquid. Access: account with support level Tools (support from EUR 15).
• batch-cost (calc=cost, JSON kind=cost): PG, VG and nicotine amounts for a batch that hits a target total cost. Access: account with support level Lab (support from EUR 35).

A calculation is GET https://www.vapcal.com/?calc=<kind>&… (HTML) or GET https://www.vapcal.com/index.md?calc=<kind>&… (Markdown). Accept: text/markdown or format=md on the page URL returns the same Markdown. JSON is GET https://www.vapcal.com/api/calc?kind=<kind>&… with no Authorization header. With an agent key, the same calculation is GET /api/agent/calc?kind=<kind>&… (scope calc:run; Markdown by default, JSON with Accept: application/json). The answer includes the public share link. Nothing is stored. Invalid inputs answer 400 with the allowed ranges (calc_input); a valid mix with no result answers 400 calc_impossible; an unknown kind answers 400 calc_kind; a locked calculator answers 403 with an unlock note and no numbers.

Rules for agents

Desired

• Citing a page with its link, and sharing the share link of a calculation.
• Conditional requests (If-None-Match) and the published reading rate.
• Asking through the contact form when a fact is not on the site.

Not desired

• Submitting the contact form, a registration, a login or a support payment in a person's name.
• Changing account data, keys or anything that makes data public, without the confirmation link the account holder opens.
• Bulk sweeps over parameter ranges or result pages.
• Rule: agent keys never get admin or translation rights, whoever owns the key.

With a login, these are never performed for a key and answer 202 with status: pending_confirmation plus a link: account or profile changes (including avatar and language), e-mail or password changes, key management, permanently deleting a preset, emptying the preset trash, support payments, and supporters-wall visibility or the public support comment. The account holder opens the link in the logged-in browser, sees what will happen and which key asked, and approves or rejects it (POST with CSRF). Links are single-use, bound to the browser session that first opens them, and expire after 24 hours (password changes: 1 hour). GET /api/agent/confirmations?id= shows the status.

Key actions other than a calculation, plus approvals and rejections, are logged as "user X via agent key <name>". A calculation is not logged (see Authorization). The account holder sees their entries in /account.

Not for agents: /api (except GET /api/calc and /api/agent/* with an agent key), /account, /checkout, /login, /register, /forgot-password, /reset-password, /confirm-email, /confirm-password-change, /sumup/, /stripe/, /revolut/. Crawling follows https://www.vapcal.com/robots.txt.

Results are arithmetic aids for adults who mix their own liquids, not medical advice.

Unpublished topics

• Shop embed and white-label terms (in preparation, on request). No public price list.
• B2B and custom integrations.

Where to ask instead of guessing: the contact form (see Contact).

Authorization

Recommended with login. The account holder creates a key in https://www.vapcal.com/account (browser session) and gives it to the agent. Keys are named, stored only as a hash (the plaintext is shown once), expire after 1, 7, 30, 90, 365 days (holder's choice), can be revoked at any time, and record when they were last used, except GET /api/agent/calc, which does not. Expired or revoked keys stop working immediately.

Agent keys

• Send the key only as the header Authorization: Bearer <key>. Keys in a query string or cookie are rejected.
• Key format: vck_<12 hex>_<64 hex>.
• A key-authenticated request gets no session and no cookie and needs no CSRF token.
• Only /api/agent/* accepts keys. A Bearer request to any other path gets 401.
• Responses are Markdown by default; send Accept: application/json for JSON (see Response format).
• Effective rights are the account's own rights, narrowed by the key's scopes.
• GET /api/agent/me JSON also returns donor_level, a deprecated alias of support_level. The Markdown view does not. Use support_level.

Scopes (a new key starts with calc:run and presets:read only; every other scope is opt-in):

• presets:read (on a new key): Read your calculator presets and the preset trash.
• presets:write (opt-in): Create, rename and update presets; restore from the trash.
• presets:delete (opt-in): Move presets to the trash; ask for permanent deletion (confirmation link).
• account:read (opt-in): Read your account summary (never secrets).
• account:write (opt-in): Ask for an account, profile, sharing or key change. The request still needs the account holder to open the confirmation link; the key does not apply the change itself.
• support:prepare (opt-in): Prepare a support payment; you check and pay it yourself (confirmation link).
• calc:run (on a new key): Run a calculation the account has unlocked. Nothing is stored, and this call is not written to the audit log.

GET /api/agent/calc (scope calc:run) runs a calculation and nothing else: no confirmation link, no row in the agent audit log, and no last-used update. The other endpoints still log and still update last-used. A calculator the account has not unlocked answers 403 with the unlock note (level, EUR threshold, https://www.vapcal.com/support and https://www.vapcal.com/login) and no numbers. A key without calc:run answers 403.

Never available through a key:

• Creating, changing or revoking keys directly (only the human in /account; an agent can only request it).
• Account deletion.
• Keys in a query string or cookie (rejected).
• Any route other than /api/agent/* (a Bearer request elsewhere gets 401; it never reaches a session route).

Endpoints that accept a key:

Errors: 401 invalid, expired or revoked key (the same generic message for all), 403 missing scope, 404 unknown endpoint, 406 no acceptable format, 429 too many requests from one key, or too many failed keys from one real client IP (see Limits). The lock is skipped when that IP is still a trusted proxy.

Response format

• Markdown is the default for every /api/agent/* response when the request has no Accept header (or only */*). An explicit Accept header always wins: application/json returns the same payload as JSON; an Accept that allows neither Markdown nor JSON gets 406. Every response sends Vary: Accept, Authorization and Cache-Control: private, no-store.
• Markdown and JSON carry the same facts; only the format differs. User-entered text (preset names, profile fields) appears as inline code, so it cannot add links or markup.

Private Markdown views (always Markdown, same key and scope checks as the endpoint they mirror, never for browser sessions, never cached):

Limits

Enforced

• Agent keys: 120 requests per key per minute. Failed key attempts: 20 per real client IP in 15 minutes, then 429. The lock applies when trusted_proxies is empty (REMOTE_ADDR is the client, including a direct deploy or mod_remoteip) and when X-Forwarded-For names a client outside that list. It does not apply when the resolved IP is still inside trusted_proxies (the header is missing or every hop is trusted), so one proxy address cannot lock every caller. A valid key is never blocked by other people's failures.

Published reading rule (not enforced)

• Reading (pages, Markdown copies, calculator URLs, https://www.vapcal.com/api/calc): About 1 request per second, with bursts of up to 10. No bulk sweeps: do not iterate over parameter ranges or crawl result pages; ask for the calculation you need. Use conditional requests: send If-None-Match with the ETag (or If-Modified-Since); a 304 has no body. On 429, wait as long as Retry-After says before the next request.

Pricing

Free without an account: Single mix, Mix chart. Voluntary one-time support payments add up (no subscription), pay for the infrastructure and unlock more calculators for the account: from EUR 6 (Unlock): Shot calculator; from EUR 15 (Tools): Ohm / watt, Coil wraps, PG/VG adjust, Dilute / boost; from EUR 35 (Lab): Batch cost. Saved presets: up to 10 from support level Lab (support from EUR 35).

Support payments are voluntary and one-time. They pay for the infrastructure. There is no subscription.

Languages

Human pages are available in 13 languages: Schwiizerdütsch, Deutsch, English, Español, Français, Italiano, Hrvatski, Српски, Nederlands, tlhIngan Hol, 日本語, Vlaams (België), Rumantsch. A human page takes ?lang= (the enabled code).

Everything for agents (this page, tools.md, llms.txt, calculator answers in Markdown, /api/agent/*, scope labels) is English only. lang does not change it.

Canonical links

Canonical host: the live site answers https://vapcal.com with 301 to https://www.vapcal.com. The canonical link, the sitemap and JSON-LD use that same origin (the configured public site URL, here https://www.vapcal.com).

• Home: https://www.vapcal.com/
• Support: https://www.vapcal.com/support
• Contact: https://www.vapcal.com/contact
• Imprint: https://www.vapcal.com/impressum
• Cookies: https://www.vapcal.com/cookies
• Versions: https://www.vapcal.com/versions
• For AI agents: https://www.vapcal.com/agents
• Wallpapers: https://www.vapcal.com/wallpapers
• Calculators: https://www.vapcal.com/?calc=simple, https://www.vapcal.com/?calc=chart, https://www.vapcal.com/?calc=shots, https://www.vapcal.com/?calc=coil, https://www.vapcal.com/?calc=wraps, https://www.vapcal.com/?calc=pgvg, https://www.vapcal.com/?calc=dilute, https://www.vapcal.com/?calc=cost

Machine-readable files

• agents.md: this page
• tools.md: every calculator (method, parameters, example request, example response, formats, auth, side effects, limits), same date as this page
• llms.txt: overview and links
• robots.txt
• sitemap.xml
• OpenAPI: none
• index.md: Markdown copy of https://www.vapcal.com/
• support.md: Markdown copy of https://www.vapcal.com/support
• wallpapers.md: Markdown copy of https://www.vapcal.com/wallpapers
• contact.md: Markdown copy of https://www.vapcal.com/contact
• impressum.md: Markdown copy of https://www.vapcal.com/impressum
• cookies.md: Markdown copy of https://www.vapcal.com/cookies
• versions.md: Markdown copy of https://www.vapcal.com/versions
• JSON-LD (schema.org) in the HTML of every public page
• Accept: text/markdown (or format=md) on a public page URL returns its Markdown copy; on a calculator URL it returns the calculation