Docs / API reference

DNS hosts

Connect the DNS host of your domains (Cloudflare, Hostinger, GoDaddy, Route 53 and more) with your own API token so OneSend can write records, or get exact instructions for any other host. Tokens are encrypted at rest and never returned.

Base URL https://your-server.example (your OneSend server). Authentication and errors are described in the overview.

DNS host catalog

GET /v1/dns-hosts

Every DNS host OneSend knows: automatic hosts have a connector that writes records with your API token; the others get step-by-step instructions. guide says how that host wants names and values typed.

Authentication: Authorization: Bearer with an API key or a session token.

Responses

200 Success

{
  "data": [{
    "id": string,
    "name": string,
    "automatic": boolean,
    "stability": "stable" | "beta" | null,
    "betaReason": string or null,
    "website": string or null,
    "docsUrl": string or null,
    "tokenUrl": string or null,
    "credentials": [{ … }],
    "help": {
      "where": string,
      "permission": string,
      "notes": [string]
    },
    "guide": {
      "nameField": "relative" | "fqdn" | "fqdn-dot",
      "apex": string,
      "txtQuotes": "none" | "required",
      "longTxt": "whole" | "split",
      "mxPriority": "field" | "in-value",
      "ttl": string,
      "dnsPage": string,
      "steps": [string],
      "docsUrl": string or null
    }
  }]
}
Errors: 400, 401, 403, 404, 429, 500
  • 400 Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected server error (internal)

Detect the DNS host of a domain

GET /v1/dns-hosts/detect

Looks up the NS records (DNS-over-HTTPS; a subdomain uses its parent zone) and matches them against known DNS hosts. Works for any domain.

Authentication: Authorization: Bearer with an API key or a session token.

Parameters

NameInTypeDescription
domainrequiredquerystring

Responses

200 Success

{
  "domain": string,
  "host": string,
  "name": string,
  "confidence": "high" | "medium" | "low" | "none",
  "nameservers": [string],
  "automatic": boolean,
  "zone": string or null,
  "note": string or null,
  "connectionId": string or null,
  "detectedAt": string
}
Errors: 400, 401, 403, 404, 429, 500
  • 400 Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected server error (internal)

List DNS host connections

GET /v1/dns-hosts/connections

Tokens are never returned; keyHint shows the last characters.

Authentication: Authorization: Bearer with an API key or a session token.

Responses

200 Success

{
  "data": [{
    "id": string,
    "object": "dns_host_connection",
    "host": string,
    "name": string,
    "keyHint": string or null,
    "config": map of string,
    "status": "untested" | "ok" | "error",
    "lastError": string or null,
    "lastTestedAt": string or null,
    "createdAt": string,
    "updatedAt": string
  }]
}
Errors: 400, 401, 403, 404, 429, 500
  • 400 Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected server error (internal)

Connect a DNS host

POST /v1/dns-hosts/connections

Stores the API token (encrypted at rest) so OneSend can write DNS records. The credentials keys are the host's fields from GET /v1/dns-hosts.

Authentication: Authorization: Bearer with an API key or a session token.

Request body

application/json, required.

FieldTypeDescription
hostrequiredstring
namestring
credentialsrequiredmap of string

Responses

201 Success

{
  "id": string,
  "object": "dns_host_connection",
  "host": string,
  "name": string,
  "keyHint": string or null,
  "config": map of string,
  "status": "untested" | "ok" | "error",
  "lastError": string or null,
  "lastTestedAt": string or null,
  "createdAt": string,
  "updatedAt": string
}
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500
  • 400 Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 409 The request conflicts with the current state, for example a duplicate name or a reused Idempotency-Key (conflict)
  • 413 The request body is larger than the limit for this endpoint (payload_too_large)
  • 415 The body is not sent as Content-Type: application/json (unsupported_media_type)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected server error (internal)

Get a DNS host connection

GET /v1/dns-hosts/connections/{id}

Authentication: Authorization: Bearer with an API key or a session token.

Parameters

NameInTypeDescription
idrequiredpathstring

Responses

200 Success

{
  "id": string,
  "object": "dns_host_connection",
  "host": string,
  "name": string,
  "keyHint": string or null,
  "config": map of string,
  "status": "untested" | "ok" | "error",
  "lastError": string or null,
  "lastTestedAt": string or null,
  "createdAt": string,
  "updatedAt": string
}
Errors: 400, 401, 403, 404, 429, 500
  • 400 Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected server error (internal)

Update a DNS host connection

PATCH /v1/dns-hosts/connections/{id}

Rename it or replace credential fields (omitted fields are kept).

Authentication: Authorization: Bearer with an API key or a session token.

Parameters

NameInTypeDescription
idrequiredpathstring

Request body

application/json, required.

FieldTypeDescription
namestring
credentialsmap of string

Responses

200 Success

{
  "id": string,
  "object": "dns_host_connection",
  "host": string,
  "name": string,
  "keyHint": string or null,
  "config": map of string,
  "status": "untested" | "ok" | "error",
  "lastError": string or null,
  "lastTestedAt": string or null,
  "createdAt": string,
  "updatedAt": string
}
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500
  • 400 Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 409 The request conflicts with the current state, for example a duplicate name or a reused Idempotency-Key (conflict)
  • 413 The request body is larger than the limit for this endpoint (payload_too_large)
  • 415 The body is not sent as Content-Type: application/json (unsupported_media_type)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected server error (internal)

Delete a DNS host connection

DELETE /v1/dns-hosts/connections/{id}

The stored token is deleted. DNS records at the host are not changed.

Authentication: Authorization: Bearer with an API key or a session token.

Parameters

NameInTypeDescription
idrequiredpathstring

Responses

204 No content

Errors: 400, 401, 403, 404, 409, 429, 500
  • 400 Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 409 The request conflicts with the current state, for example a duplicate name or a reused Idempotency-Key (conflict)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected server error (internal)

Test a DNS host connection

POST /v1/dns-hosts/connections/{id}/test

Calls the host API with the stored token. Changes nothing.

Authentication: Authorization: Bearer with an API key or a session token.

Parameters

NameInTypeDescription
idrequiredpathstring

Responses

200 Success

{
  "ok": boolean,
  "account": string or null,
  "zones": number or null,
  "note": string or null,
  "error": {
    "code": string,
    "message": string
  }
}
Errors: 400, 401, 403, 404, 409, 429, 500
  • 400 Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 409 The request conflicts with the current state, for example a duplicate name or a reused Idempotency-Key (conflict)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected server error (internal)