Getting started

The InfraNest API lets you automate the infrastructure you manage in InfraNest: DNS records, monitors, maintenance windows, incidents and status pages. This guide takes you from no token to your first call in about five minutes.

Before you start

An InfraNest account on a plan that includes the API.
Your organization's ID. It's under Settings → Organization in the app, with a copy button. Or ask the API: GET /api/organizations lists every organization your token can reach. See the FAQ.
A terminal with curl.

The API lives at https://api.infranest.io/api. Every request sends a token and asks for JSON.

There are two ways in. An API token, used in this guide, is for your own scripts and tools and acts as you. An app that acts for other people — an integration, a hosted service — uses OAuth: each person connects it to their own account, and nobody copies a token.

Create a token

In the app, open My account → Developer and choose New token.
Give it a name that says where it will be used, for example ci-dns.
Give it only what it needs. For this guide, tick DNS → Read.
Copy the token. It's shown once. Store it where your scripts read secrets, never in code.

A token works with your infrastructure, never with your account: tokens, members, billing and passwords stay in the app. Some actions are not available to a token at all; see Tokens and scopes. What you do with a token is your responsibility, and it can cause costs at your providers; see Responsibility and costs.

Make your first call

List the DNS zones in your organization. Replace 42 with your organization's ID.

curl https://api.infranest.io/api/organizations/42/dns-zones \
  -H "Authorization: Bearer $INFRANEST_TOKEN" \
  -H "Accept: application/json"

You get back the zones in that organization, each with an id you use to work with its records.

When something goes wrong

Every error has the same shape and a stable code, with a hint saying what to do:

json

{
  "code": "scope_missing",
  "message": "This API token does not have the dns.write scope.",
  "hint": "Create a token that includes the scope named in \"required\". Give each token only the scopes it needs.",
  "retryable": false,
  "required": "dns.write"
}

Write your scripts against code, never the message. The full list is in Errors.

Getting started ​

Before you start ​

Create a token ​

Make your first call ​

When something goes wrong ​

What next ​

Getting started

Before you start

Create a token

Make your first call

When something goes wrong

What next