{"openapi":"3.1.0","info":{"title":"Ingram Domains API","version":"2.0.0","description":"REST API for the Ingram Domains registrar. Built agent-first: every operation is also exposed as an MCP tool.\n\nAll POST/DELETE/PATCH endpoints accept an optional `Idempotency-Key` header. Replays with the same key + body return the cached response (with `Idempotent-Replay: true`). Same key + different body returns `409 idempotency_key_reused`. Cached entries are kept for ~24 hours."},"servers":[{"url":"https://domains.ingram.tech"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"ingram_live_<32 base64url chars>","description":"Mint at https://domains.ingram.tech/settings/tokens or via POST /api/v1/accounts."}},"schemas":{"CheckResult":{"type":"object","properties":{"domain":{"type":"string"},"tld":{"type":"string"},"result":{"type":"string","enum":["AVAILABLE","NOT AVAILABLE","ERROR","PENDING APPLICATION"]},"reason":{"type":"string"},"price":{"type":"number","description":"EUR per year"},"currency":{"type":"string","enum":["EUR"]},"source":{"type":"string","enum":["fastly","das","registry"]}},"required":["domain","tld","result","source"]},"Error":{"type":"object","properties":{"error":{"type":"string","example":"Unauthorized"},"details":{"nullable":true}},"required":["error"]},"TldPrice":{"type":"object","properties":{"tld":{"type":"string"},"currency":{"type":"string","enum":["EUR"]},"register":{"type":"number","description":"EUR per year"},"renew":{"type":"number"},"transfer":{"type":"number"}},"required":["tld","currency","register"]},"SignupResponse":{"type":"object","properties":{"user_id":{"type":"string","example":"usr_3nXk9…"},"organization_id":{"type":"string","example":"org_7Qm2p…"},"email":{"type":"string"},"api_token":{"type":"string","description":"Shown exactly once — store it now."},"api_token_prefix":{"type":"string"},"balance":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"}},"required":["amount","currency"]},"prefund":{"type":"object","properties":{"payment_intent_id":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string"}},"required":["payment_intent_id","amount","currency"]}},"required":["user_id","organization_id","email","api_token","api_token_prefix","balance"]},"DomainListItem":{"type":"object","properties":{"domain":{"type":"string"},"addedVia":{"type":"string"},"createdAt":{"type":"string"}},"required":["domain","addedVia","createdAt"]},"RegisterResponse":{"type":"object","properties":{"domain":{"type":"string"},"duration":{"type":"number"},"pricePaid":{"type":"number"},"currency":{"type":"string","enum":["EUR"]},"dryRun":{"type":"boolean"},"registryStatus":{"type":"string"},"paymentIntentId":{"type":"string"}},"required":["domain","duration","pricePaid","currency","dryRun","registryStatus"]},"DomainInfo":{"type":"object","additionalProperties":{"nullable":true},"description":"Registry-side detail. Field casing mirrors Netim's REST v1.0 — most fields are camelCase but DNSSEC-related flags use PascalCase (IsSigned, HasDNS4Service, DNSSEC). ccTLDs add their own fields."},"PurchaseOutcome":{"type":"object","properties":{"domain":{"type":"string"},"dryRun":{"type":"boolean"},"duration":{"type":"number"},"pricePaid":{"type":"number"},"currency":{"type":"string","enum":["EUR"]},"registryStatus":{"type":"string"},"paymentIntentId":{"type":"string"}},"required":["domain","dryRun","pricePaid","currency","registryStatus"]},"RegistryOperation":{"type":"object","additionalProperties":{"nullable":true},"description":"Netim operation response: { ID_OPE, STATUS (\"Done\" | \"Pending\" | \"Failed\" | \"Cancelled\"), MESSAGE, TYPE, DATE }. Mutations are async — \"Pending\" means accepted, not applied."},"ZoneRecord":{"type":"object","additionalProperties":{"nullable":true},"description":"A zone record as returned by the registry."}},"parameters":{}},"paths":{"/api/v1/check":{"get":{"summary":"Check domain availability","description":"Public. Checks availability (and yearly registration price) for a name across supported TLDs, or a single FQDN.","security":[],"parameters":[{"schema":{"type":"string","minLength":2,"maxLength":253},"required":true,"name":"q","in":"query"}],"responses":{"200":{"description":"Availability results","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"results":{"type":"array","items":{"$ref":"#/components/schemas/CheckResult"}}},"required":["query","results"]}}}},"400":{"description":"Malformed or invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/suggest":{"get":{"summary":"Related-name suggestions","description":"Public. Related-name suggestions from the Domainr/Fastly suggest engine — names only, no availability (stream each through /check). Returns an empty list rather than erroring when the integration is absent or upstream hiccups: suggestions are garnish, never a blocker.","security":[],"parameters":[{"schema":{"type":"string","minLength":2,"maxLength":253},"required":true,"name":"q","in":"query"}],"responses":{"200":{"description":"Name suggestions","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"suggestions":{"type":"array","items":{"type":"string"}}},"required":["query","suggestions"]}}}},"400":{"description":"Malformed or invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/tlds":{"get":{"summary":"TLD price list","description":"Retail prices per TLD (register / renew / transfer, EUR). Echo these into `confirm_price` on spending calls.","responses":{"200":{"description":"Prices per TLD","content":{"application/json":{"schema":{"type":"object","properties":{"tlds":{"type":"array","items":{"$ref":"#/components/schemas/TldPrice"}}},"required":["tlds"]}}}},"401":{"description":"Missing or invalid authentication.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient permissions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/accounts":{"post":{"summary":"Programmatic signup","description":"Create a user + organization + API token in one unauthenticated call. Optionally prefund the wallet in the same request.","security":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":8,"maxLength":128},"token_name":{"type":"string","minLength":1,"maxLength":64},"prefund":{"type":"object","properties":{"amount":{"type":"integer","minimum":500,"maximum":1000000,"default":1000},"currency":{"type":"string","minLength":3,"maxLength":3,"default":"eur"},"payment_method":{"type":"string","minLength":1},"shared_payment_token":{"type":"string","minLength":1}},"additionalProperties":false}},"required":["email"]}}}},"responses":{"201":{"description":"Account created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupResponse"}}}},"400":{"description":"Malformed or invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Prefund payment declined.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. a duplicate or in-use resource).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A request shape or domain rule was violated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/domains":{"get":{"summary":"List portfolio domains","description":"Every domain in the token's workspace, newest first, with how it arrived (register / transfer / internal_transfer / imported) and when.","responses":{"200":{"description":"The organization's domains","content":{"application/json":{"schema":{"type":"object","properties":{"domains":{"type":"array","items":{"$ref":"#/components/schemas/DomainListItem"}}},"required":["domains"]}}}},"401":{"description":"Missing or invalid authentication.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Register a domain","description":"Paid. Debits the org wallet (optionally topping it up in the same call). Rejects with `price_changed` if the price moved more than 1 cent from `confirm_price`.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","minLength":3},"duration":{"type":"integer","minimum":1,"maximum":10,"default":1},"confirm_price":{"type":"number","minimum":0,"description":"Echo the price from /check or /tlds (EUR)."},"payment_method":{"type":"string","minLength":1},"shared_payment_token":{"type":"string","minLength":1}},"required":["domain","confirm_price"]}}}},"responses":{"201":{"description":"Registration accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterResponse"}}}},"400":{"description":"Malformed or invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment failed or insufficient balance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient permissions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Price changed, or Idempotency-Key reused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A request shape or domain rule was violated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/domains/{name}":{"get":{"summary":"Domain detail","description":"Live registry state for a portfolio domain: status, registration/expiry dates, nameservers, and the registrar-lock / auto-renew / WHOIS-privacy / DNSSEC flags.","parameters":[{"schema":{"type":"string","minLength":3,"example":"example.com"},"required":true,"name":"name","in":"path"}],"responses":{"200":{"description":"Portfolio link + registry detail","content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"addedVia":{"type":"string"},"createdAt":{"type":"string"},"info":{"$ref":"#/components/schemas/DomainInfo"}},"required":["domain","addedVia","createdAt","info"]}}}},"401":{"description":"Missing or invalid authentication.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete or release a domain","description":"Default mode END_OF_PERIOD disables auto-renew (the domain lapses at expiry); mode=NOW deletes at the registry immediately.","parameters":[{"schema":{"type":"string","minLength":3,"example":"example.com"},"required":true,"name":"name","in":"path"},{"schema":{"type":"string","enum":["NOW","END_OF_PERIOD"]},"required":false,"name":"mode","in":"query"}],"responses":{"200":{"description":"Deletion / release accepted","content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"dryRun":{"type":"boolean"},"mode":{"type":"string"},"registryStatus":{"type":"string"}},"required":["domain","dryRun","mode","registryStatus"]}}}},"401":{"description":"Missing or invalid authentication.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient permissions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. a duplicate or in-use resource).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A request shape or domain rule was violated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/domains/{name}/renew":{"post":{"summary":"Renew a domain","description":"Paid. Same wallet + `confirm_price` contract as registration.","parameters":[{"schema":{"type":"string","minLength":3,"example":"example.com"},"required":true,"name":"name","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"duration":{"type":"integer","minimum":1,"maximum":10,"default":1},"confirm_price":{"type":"number","minimum":0,"description":"Echo the price from /check or /tlds (EUR)."},"payment_method":{"type":"string","minLength":1},"shared_payment_token":{"type":"string","minLength":1}},"required":["confirm_price"]}}}},"responses":{"200":{"description":"Renewal accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOutcome"}}}},"400":{"description":"Malformed or invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment failed or insufficient balance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient permissions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Price changed, or Idempotency-Key reused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A request shape or domain rule was violated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/domains/{name}/transfer":{"post":{"summary":"Transfer a domain in","description":"Paid — transfers typically include a year's renewal at the registry. Echo the transfer price from /tlds.","parameters":[{"schema":{"type":"string","minLength":3,"example":"example.com"},"required":true,"name":"name","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"auth_code":{"type":"string","minLength":1},"confirm_price":{"type":"number","minimum":0,"description":"Echo the price from /check or /tlds (EUR)."},"payment_method":{"type":"string","minLength":1},"shared_payment_token":{"type":"string","minLength":1}},"required":["auth_code","confirm_price"]}}}},"responses":{"202":{"description":"Transfer initiated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOutcome"}}}},"400":{"description":"Malformed or invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment failed or insufficient balance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient permissions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Price changed, or Idempotency-Key reused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A request shape or domain rule was violated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/domains/{name}/settings":{"patch":{"summary":"Toggle domain preferences","description":"Each toggle is an independent registry call, applied sequentially; the per-toggle outcome is returned so partial failures are observable.","parameters":[{"schema":{"type":"string","minLength":3,"example":"example.com"},"required":true,"name":"name","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"auto_renew":{"type":"boolean"},"registrar_lock":{"type":"boolean"},"whois_privacy":{"type":"boolean"},"dnssec":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Per-toggle outcomes","content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"applied":{"type":"object","additionalProperties":{"anyOf":[{"type":"boolean"},{"type":"string"}]}},"errors":{"type":"object","additionalProperties":{"type":"string"}}},"required":["domain","applied"]}}}},"400":{"description":"Malformed or invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient permissions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. a duplicate or in-use resource).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/domains/{name}/auth-code":{"post":{"summary":"Request the EPP auth code","description":"Emails the domain's EPP/authorization code to the registrant contact — the prerequisite for transferring the domain to another registrar. Disable registrar lock before the gaining registrar submits.","parameters":[{"schema":{"type":"string","minLength":3,"example":"example.com"},"required":true,"name":"name","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"send_to_registrant":{"type":"boolean","default":true}},"default":{}}}}},"responses":{"202":{"description":"Auth-code request accepted","content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"delivery":{"type":"string","enum":["registrant_email","regenerated"]},"message":{"type":"string"},"registry":{"$ref":"#/components/schemas/RegistryOperation"}},"required":["domain","delivery","message","registry"]}}}},"401":{"description":"Missing or invalid authentication.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient permissions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. a duplicate or in-use resource).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/domains/{name}/zone":{"get":{"summary":"List zone records","description":"DNS records of the domain's hosted zone. Only domains delegated to our nameservers have one — external delegation answers `409 no_hosted_zone`.","parameters":[{"schema":{"type":"string","minLength":3,"example":"example.com"},"required":true,"name":"name","in":"path"}],"responses":{"200":{"description":"Zone records","content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"records":{"type":"array","items":{"$ref":"#/components/schemas/ZoneRecord"}}},"required":["domain","records"]}}}},"401":{"description":"Missing or invalid authentication.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. a duplicate or in-use resource).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a zone record","description":"Adds a record to the hosted zone (A/AAAA/CNAME/MX/TXT/NS/CAA/SRV). Changes propagate from our nameservers in ~30 seconds. `409 no_hosted_zone` when the domain is delegated elsewhere.","parameters":[{"schema":{"type":"string","minLength":3,"example":"example.com"},"required":true,"name":"name","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"subdomain":{"type":"string","maxLength":255,"default":""},"type":{"type":"string","enum":["A","AAAA","CNAME","MX","TXT","NS","CAA","SRV"]},"value":{"type":"string","minLength":1,"maxLength":2048},"ttl":{"type":"integer","minimum":60,"maximum":86400},"priority":{"type":"integer","minimum":0,"maximum":65535},"weight":{"type":"integer","minimum":0,"maximum":65535},"port":{"type":"integer","minimum":1,"maximum":65535}},"required":["type","value"]}}}},"responses":{"201":{"description":"Record created","content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"record":{"type":"object","additionalProperties":{"nullable":true}},"result":{"$ref":"#/components/schemas/RegistryOperation"}},"required":["domain","record","result"]}}}},"400":{"description":"Malformed or invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient permissions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. a duplicate or in-use resource).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a zone record","description":"Identifies the record by the same triple Netim expects: subdomain + type + value (query params).","parameters":[{"schema":{"type":"string","minLength":3,"example":"example.com"},"required":true,"name":"name","in":"path"},{"schema":{"type":"string","default":""},"required":false,"name":"subdomain","in":"query"},{"schema":{"type":"string"},"required":true,"name":"type","in":"query"},{"schema":{"type":"string"},"required":true,"name":"value","in":"query"}],"responses":{"200":{"description":"Record deleted","content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"deleted":{"type":"object","additionalProperties":{"nullable":true}},"result":{"$ref":"#/components/schemas/RegistryOperation"}},"required":["domain","deleted","result"]}}}},"400":{"description":"Malformed or invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid authentication.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient permissions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. a duplicate or in-use resource).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}