HTTP

Outside TypeScript there is no hand-written SDK, and there does not need to be one. The OpenAPI document is emitted from the running server, so a generated client is as current as the reference on this site.

The document

https://ownsi.dev/openapi/json

The same document backs every endpoint page under Endpoints, and can be downloaded from the menu at the top of any of them.

The API is not open yet. A generated client works today only against the zone read and the public proof page; every other route wants a session the app issues, and there are no public keys to stand in for one. See Authentication.

Generating a client

openapi-python-client generate --url https://ownsi.dev/openapi/json

oapi-codegen -package ownsi https://ownsi.dev/openapi/json > ownsi.go

openapi-generator generate -i https://ownsi.dev/openapi/json -g rust -o ./ownsi

npx @openapitools/openapi-generator-cli generate \
  -i https://ownsi.dev/openapi/json \
  -g <your-language> -o ./ownsi

Most generators handle the request/response shapes fine but do not model GET /api/zones/:name as a stream — they will hand you the whole body at once, or nothing. If you need the frames as they arrive, read that one endpoint by hand: it is plain server-sent events over a normal response body.

By hand

The whole API is JSON over HTTP with a cookie. There is nothing to install.

curl -N https://ownsi.dev/api/zones/acme.com

curl -X POST https://ownsi.dev/api/domains \
  -H "content-type: application/json" \
  -b "$SESSION_COOKIE" \
  -d '{"domain":"acme.com"}'

curl -X POST https://ownsi.dev/api/claims \
  -H "content-type: application/json" \
  -b "$SESSION_COOKIE" \
  -d "{\"domainId\":\"$DOMAIN_ID\"}"

curl https://ownsi.dev/api/claims/$CLAIM_ID -b "$SESSION_COOKIE"

curl -X POST https://ownsi.dev/api/verifications/$VERIFICATION_ID/runs -b "$SESSION_COOKIE"

Two things to get right in any language

Narrow on the discriminant before reading the payload

diagnosis.observed has a different shape for each of the thirteen code values, and a zone frame’s data has a different shape per step. In a language without unions, that is a switch on the tag before you touch the rest.

match diagnosis["code"]:
    case "negative_cache":
        wait(diagnosis["observed"]["secondsRemaining"])
    case "record_at_apex":
        show(diagnosis["observed"]["name"], diagnosis["observed"]["value"])
    case _:
        show(diagnosis["fix"])

Falling through to fix is always safe: every diagnosis has one.

Retry only what is worth retrying

unresolvable (502) and rate_limited (429) are worth a backoff. Nothing else is — see the table.On 429, honour Retry-After. Forcing runs in a loop does not make DNS answer faster; the verification’s own waitEstimate.secondsRemaining is the honest interval.

Using the API

Endpoints

Clients

Guides

The document

Generating a client

By hand

Two things to get right in any language

​The document

​Generating a client

​By hand

​Two things to get right in any language

The document

Generating a client

By hand

Two things to get right in any language