# MeowMeow Domains API v1

Base URL: the same HTTPS origin as this document, /api/v1.
OpenAPI: /api/v1/openapi.json. Human documentation: /api/docs.
Create a key in the Telegram bot: Profile > API > Create key.
Set Authorization: Bearer YOUR_KEY. Never put a secret in a URL, source code,
logs, prompts shared with third parties or version control. Use an environment
variable or your agent's secret store. Keys are customer-scoped and revocable.

One key provides all API features for its owner's account. There are no key
types, per-order or daily spending caps, or per-key request quotas. The key
does not expire automatically. Purchases use the available account balance.
Create, replace or disable the key in Profile > API. Replacement immediately
invalidates the old key; update your agent with the new secret.
Disabling a key does not cancel jobs already accepted. The API cannot enable
autorenew. Never share your key with anyone you do not trust with your account.

Purchase workflow:
1. GET /account: check available balance and purchases_enabled.
2. POST /domains/search {"query":"my-project","category":"basic"}.
   Results contain available names only, indicative USD prices, not guarantees.
3. POST /quotes with a new Idempotency-Key, e.g. a UUID:
   {"names":["example.com"],"kind":"registration","period":1,
    "category":"basic","configuration":{"mode":"skip"}}.
   Exact quote, expiry, Prime pricing and total are returned; no purchase yet.
   Registration is one year. Renewals: kind renewal, period 1–10 subject to
   domain eligibility; inspect renewal_periods on GET /domains/{id}.
4. Verify total and expiry against the user's explicit spending authorization.
   POST /orders/{id}/confirm with {} and a NEW Idempotency-Key.
5. Poll GET /orders/{id}. A 202 means accepted, NOT registered or TLS ready.
   Item status succeeded means that item completed. partial means some items
   failed; inspect every item. unknown requires reconciliation, not repurchase.
6. GET /domains to find the registered domain ID. GET /domains/{id} separately
   reports Cloudflare/TLS state. Certificate issuance is asynchronous.

All writes except read-only search require an Idempotency-Key (8–128 ASCII
letters/digits/._:-). Retry the SAME action with the SAME key and SAME JSON.
Reusing a key for a different payload returns 409. Stored responses may have an
older status: poll the resource for current state. If the response is lost, retry
with the same key. For request_processing or internal uncertainty, poll the
returned /requests/{request_id}. NEVER submit an uncertain purchase with a new
key. If no linked resource appears, contact support; do not guess the outcome.

GET /domains/{id}/dns returns a local provider snapshot. To refresh it, queue
dns.sync and poll the operation before reading it again. DNS changes are queued
using POST /domains/{id}/operations with {"kind":"dns.add","payload":{
"record_type":"A","name":"*","content":"YOUR_PUBLIC_SERVER_IP",
"ttl":300,"proxied":false}}. Use a public routable IP you control.
Names: @ apex, * wildcard, or a label. All owned domain changes are async.
For dns.rrset, supply expected from the corresponding snapshot's rrsets list
(or empty_rrset_expected for a previously absent set), plus record_type, name
and values [{content,ttl,proxied,priority,comment}]. An empty values list deletes
that name/type. A stale snapshot is rejected; do not overwrite unseen changes.
No internal provider IDs, checkpoint fields or foreign domains are accepted.

NS changes use ns.set with nameservers (2–20 hostnames). native.configure
switches delegation to the registrar; cloudflare.connect connects Cloudflare
and can change delegation. These can affect website availability: obtain the
user's approval before changing hosting/delegation. cloudflare.setting uses
setting/value; for GEO add countries, an array of ISO alpha-2 codes (e.g. ["US","DE"]).
GEO is per-domain, not a service preset. value=true requires a nonempty list;
value=false disables the rule, and countries=[] clears the selection.
Omitting countries reuses the domain's saved selection.
Available values are in GET /domains/{id}. cloudflare.proxy uses
enabled true/false. cloudflare.purge clears cache. New Cloudflare connections
require Prime; existing entitled connections remain editable after expiry.
Cloudflare availability/SSL is not immediate or guaranteed by operation enqueue.
Redirect and glue schemas are in OpenAPI. No external domain import/transfer.

List pagination: GET /orders and /domains accept limit 1–100, offset 0–100000;
response contains items,total,next_offset. Monetary values are decimal STRINGS
in USD. Timestamps are ISO 8601. Error JSON: error.code,error.message,request_id.
Do not rely on human message wording. 401 invalid key, 409 idempotency conflict
or request in progress, 422 invalid/business request (including insufficient
balance), 503 provider/feature temporarily unavailable. Respect Retry-After.
Pagination and request-size validation are protocol constraints, not usage quotas.
API never exposes registrar/Cloudflare credentials. Keep API keys private.