DNS API

Adding a custom domain normally ends with Openship telling you which records to create and waiting for you to create them. Connect a DNS provider and Openship can preview and apply those records for you without leaving the page. Applying DNS is always an explicit action: creating a project domain or saving a service route never changes the provider's zone silently. In the dashboard, credentials live under Settings → DNS and each pending domain's records panel contains the apply action.

Cloudflare is the only provider today. The provider list is served by the API rather than hard-coded in the dashboard, so GET /api/dns/providers is the authoritative answer to "what can I connect?".

Endpoints

Connect a provider

POST /api/dns/credentials

curl -X POST https://your-host/api/dns/credentials \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"provider":"cloudflare","name":"Cloudflare production","apiToken":"cf-..."}'

For Cloudflare, create a token at dash.cloudflare.com/profile/api-tokens scoped to Zone:Zone:Read and Zone:DNS:Edit, limited to the zones you want Openship to manage.

Check a zone

POST /api/dns/verify-zone

The response separates four outcomes, because they call for different actions:

curl -X POST https://your-host/api/dns/verify-zone \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"hostname":"app.example.com"}'

Add, preview, and apply a domain

POST /api/domains persists a pending domain and returns the records it needs. It does not call the DNS provider. Service-level custom routes follow the same contract: saving the route creates its pending domain row, and that row supplies the :id used by the shared plan and apply endpoints.

Preview the exact provider changes before writing anything:

curl https://your-host/api/domains/dom_123/dns/plan \
  -H "Authorization: Bearer $OPENSHIP_TOKEN"

{
  "data": {
    "status": "matched",
    "provider": "cloudflare",
    "zoneName": "example.com",
    "records": [
      { "name": "app.example.com", "type": "A", "action": "create", "desired": "203.0.113.10" }
    ]
  }
}

The plan classifies every record as create, update, adopt, in-sync, or conflict. A conflict is reported rather than overwritten. status: "none" means no connected credential manages the zone, so use the records returned by POST /api/domains (or GET /api/domains/:id/records) and add them manually.

Apply the previewed records explicitly:

curl -X POST https://your-host/api/domains/dom_123/dns/apply \
  -H "Authorization: Bearer $OPENSHIP_TOKEN"

The response reports applied, skipped, or failed for every record. provisioned is true only when the matching provider has every actionable record in place; a partial write returns provisioned: false with a reason and the per-record failures.

No verification is triggered by apply. The records are seconds old, a resolver may still be holding a negative answer for the name, and a failed check burns one of Let's Encrypt's per-hostname validation failures. The domain stays pending and the domains:verify-pending sweep picks it up after its ten-minute grace window.

Removing records

Disconnecting a credential does not touch DNS. Removing a domain does — but only records Openship created, identified by the Managed by Openship comment it writes on every record.

Errors