# NameOcean API

> NameOcean is a domain registrar. With one API key an AI agent can search and register domains, manage DNS records, change nameservers and issue free wildcard SSL certificates on behalf of its user.

Base URL: https://nameocean.net/api/v1/
Auth: send the user's key in every request as `Authorization: Bearer <API_KEY>`.
The user finds the key at https://nameocean.net/dashboard/api/
Format: JSON in, JSON out. Errors return `{"error": "<what went wrong and how to fix it>"}` with a 4xx/5xx status.
Rate limit: 120 requests per minute per key.
Money: registrations and renewals are paid from the account credit (USD). Check `GET /account` first. If credit is too low the API answers 402; ask the user to add funds at https://nameocean.net/dashboard/billing/

## Ask before spending
Registering or renewing a domain charges the user's credit. Always tell the user the domain and the price and get a clear yes before calling `POST /domains` or `POST /domains/{name}/renew`.

## Account
- GET /account → {email, credit, currency, domains, dns_zones}

## Domains
- GET /domains/check?name=example.com&years=1 → {name, available, register_price, renew_price, premium} or {available: false, reason}
- GET /domains → {domains: [{name, expires_on, auto_renew, locked, active, pending, suspended}]}
- POST /domains  body {"name": "example.com", "years": 1} → 201 {domain, charged, credit}
  Premium domains also need "accept_premium": true. A new domain gets a DNS zone automatically after a minute or two.
- GET /domains/{name} → details, nameservers and SSL status
- PATCH /domains/{name}  body {"auto_renew": true, "locked": false}
- PUT /domains/{name}/nameservers  body {"nameservers": ["ns1.vercel-dns.com", "ns2.vercel-dns.com"]}  (2-4 hosts)
  or body {"nameservers": "nameocean"} to go back to NameOcean DNS (needed for DNS records and SSL below).
- POST /domains/{name}/renew → renews one year. Allowed within 60 days of expiry.
- GET /domains/{name}/auth-code → {auth_code} for transferring the domain away

## DNS
A zone is the DNS of one domain hosted on NameOcean's nameservers (ns1-ns4.nameocean.net).
- GET /dns → {zones: [{name, serial}]}
- POST /dns  body {"name": "example.com"} → create a zone for a domain registered elsewhere
- GET /dns/{zone}/records → {records: [{id, type, hostname, ...}]}
- POST /dns/{zone}/records  body depends on type:
  - A        {"type": "A", "hostname": "@", "ip": "203.0.113.10", "ttl": "1h"}   (IPv6 addresses work too)
  - CNAME    {"type": "CNAME", "hostname": "www", "target": "@", "ttl": "1h"}  (target "@" means the zone itself)
  - MX       {"type": "MX", "hostname": "@", "priority": 10, "target": "mail.example.com", "ttl": "1h"}
  - TXT      {"type": "TXT", "hostname": "@", "text": "v=spf1 include:_spf.google.com ~all", "ttl": "1h"}
  - SRV      {"type": "SRV", "hostname": "_sip._tcp", "priority": 10, "weight": 5, "port": 5060, "target": "sip.example.com", "ttl": "1h"}
  - PTR      {"type": "PTR", "hostname": "203.0.113.10", "target": "host.example.com", "ttl": "1h"}
  - REDIRECT {"type": "REDIRECT", "hostname": "old", "target": "https://example.com/new", "save_path": true}
  `hostname` is relative to the zone: "@" is the zone itself, "www" is www.example.com. ttl is one of 5m, 15m, 30m, 1h, 1d.
  Targets are plain hostnames without a trailing dot. A CNAME cannot be at "@" and cannot share a hostname with any other record.
- PATCH /dns/{zone}/records/{type}/{id}  body: only the fields to change
- DELETE /dns/{zone}/records/{type}/{id} → 204

## SSL
Free wildcard certificates (example.com and *.example.com) from Let's Encrypt. The domain must use NameOcean nameservers.
- GET /ssl/{zone} → {status: none | issuing | waiting_for_nameservers | active, expires_on, auto_renew, download_url}
- POST /ssl/{zone} → 202, starts issuing. Poll GET until status is "active" (usually a few minutes). download_url is a zip with the certificate and key.
- PATCH /ssl/{zone}  body {"auto_renew": true}

## App servers (NameOcean hosting)
`{server}` is the server's id or its default domain (`3f9a1c2e` or `3f9a1c2e.nameocean.org`). An agent running ON the server can use its own default domain (shown by `nameocean-info` / the git remote).
Web traffic needs no port: the load balancer takes HTTPS on 443 and forwards it to port 80 of the server.
- GET /servers → {servers: [{id, name, status, plan, default_domain, cpu, memory_mb, disk_gb, private_ip, ipv6, ssh: {host, port, user, command}, git_remote, backups, ports: [...], domains: [...]}]}
- GET /servers/{server}
- GET /servers/{server}/ports → {ports: [{id, protocol, internal_port, external_port}]}
- POST /servers/{server}/ports  body {"port": 25565, "protocol": "tcp"}  → 201 {id, internal_port, external_port, connect_to}
  `port` is what the program listens on (it must listen on 0.0.0.0). The external port is the same number when it is >= 10000 and free, otherwise a random free port from 10000 up. Clients connect to {default_domain}:{external_port}. Traffic does not pass the load balancer (no HTTPS added). Max 10 ports per server; port 22 (SSH) cannot be closed; port 80 is refused (already served).
- DELETE /servers/{server}/ports/{id} → 204
- GET /servers/{server}/domains → {domains: [{id, domain, status: setting_up | active, url}]}
- POST /servers/{server}/domains  body {"domain": "example.com"} or {"domain": "app.example.com"}  → 201
  The domain (or its parent) must be a DNS zone in the account using NameOcean nameservers. NameOcean then creates the DNS records (@ A/AAAA + www CNAME, or A/AAAA for a subdomain), issues a free SSL certificate and configures the load balancer (HTTP → HTTPS, bare domain → www). Poll GET until status is "active" (usually a few minutes). A domain can be bound to one server at a time.
- DELETE /servers/{server}/domains/{id} → 204, removes the binding and the A/AAAA records NameOcean added for it.

## Example: point a new domain to a server with HTTPS
1. GET /domains/check?name=kahvebot.com  → tell the user the price, get a yes
2. POST /domains {"name": "kahvebot.com", "years": 1}
3. POST /dns/kahvebot.com/records {"type": "A", "hostname": "@", "ip": "203.0.113.10", "ttl": "5m"}
4. POST /dns/kahvebot.com/records {"type": "CNAME", "hostname": "www", "target": "@", "ttl": "1h"}
5. POST /ssl/kahvebot.com, then GET /ssl/kahvebot.com until status is "active"

## Example: put a domain on a NameOcean app server
1. GET /servers → pick the server (or use its default domain)
2. POST /servers/3f9a1c2e/domains {"domain": "kahvebot.com"}
3. GET /servers/3f9a1c2e/domains until "kahvebot.com" is "active" → https://kahvebot.com serves the server's port 80

## curl
curl https://nameocean.net/api/v1/account -H "Authorization: Bearer $NAMEOCEAN_API_KEY"
curl -X POST https://nameocean.net/api/v1/dns/example.com/records -H "Authorization: Bearer $NAMEOCEAN_API_KEY" -H "Content-Type: application/json" -d '{"type":"TXT","hostname":"@","text":"hello","ttl":"1h"}'

Human docs: https://nameocean.net/developers/