Admin API: domains

The API offers the same actions as the Domains section of the panel: add a domain, change its settings, run a check, collect domains into groups and route them to a node. All methods require a token with Full access («Полный доступ») (full). Authorization is described on the Admin API: overview and authorization page, and the response and error format on the Request, response and error format page.

Domain object

The health block

What each stage message means is described on the Domain check page.

Domains

List domains

GET /api/v1/domains

Returns all of the team's domains. No parameters and no pagination.

Response — code 200 and an array of domain objects. Recently added ones come first. If there are no domains, an empty array [] is returned.

Add domains

POST /api/v1/domains

Adds one or more domains with the same settings.

Response — code 201 and an object with the items array: the added domains. The group_name, index_campaign, campaign_count and health fields are not filled in this response — read them with a list request.

Names are converted to lower case. A domain that is already in the tracker is skipped without an error and does not appear in items.

With cloudflare: true, the tracker checks where the domain's DNS points. If the domain does not point to the Cloudflare network, it is not added. If DNS does not respond yet, the domain is added with the pending status. More on the Working with Cloudflare page.

Errors:

Example request:

curl -X POST https://panel.example.com/api/v1/domains \
  -H "Api-Key: <token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"track.example.com","new_group":"Nutra PL","no_index":true}'

Example response:

{
  "items": [
    {
      "id": "3f2a9c1e-5b7d-4e8f-a1b2-c3d4e5f6a7b8",
      "name": "track.example.com",
      "ssl_status": "pending",
      "dns_status": "pending",
      "cloudflare": false,
      "group_id": "9d8c7b6a-1f2e-4d3c-b5a4-0e9f8d7c6b5a",
      "group_name": null,
      "no_index": true,
      "index_campaign_id": null,
      "index_campaign": null,
      "campaign_count": 0,
      "proxy_node_id": null,
      "blocked": false
    }
  ]
}

Edit a domain

PUT /api/v1/domains/{id}

Changes the settings of the domain with the ID from the path. Only the fields you pass change. The domain name cannot be changed.

null and an empty string in group_id and index_campaign_id change nothing. To clear a value, pass clear_group or clear_index.

Response — code 200 and the domain object after the change.

If after the change the domain counts as a domain behind Cloudflare, the tracker checks its DNS again. When the domain does not point to the Cloudflare network, the whole request is rejected and no field changes.

Errors:

Check a domain

POST /api/v1/domains/{id}/verify

Runs the DNS, HTTP, HTTPS and certificate check and waits for it to finish. No body is needed.

Response — code 200 and an object with two fields: dns_status and health. The health format is described in The health block. Here dns_status is pending if the dns stage is not in the ok state; otherwise it is the health.proxy value: proxied or direct.

Errors:

Delete a domain

DELETE /api/v1/domains/{id}

Deletes a domain. The domain does not go to the trash. Campaigns that used it are left without a domain.

Response — code 204 with no body. If there is no domain with this ID, you get 404 with the not_found code; if the ID is not a UUID, 400 with the bad_request code.

Domain groups

Groups determine which domains media buyers and designers see. More on the Domain groups and media buyer access page.

List groups

GET /api/v1/domain-groups

Response — code 200 and an array of groups sorted by name.

Create a group

POST /api/v1/domain-groups

Response — code 201 and a group object with an empty shared_to and domain_count equal to 0. If name is empty or the body was not parsed — 422 with the validation code and the message name is required.

Delete a group

DELETE /api/v1/domain-groups/{id}

Deletes a group. The domains stay in the tracker without a group, and users lose access to them through this group.

Response — code 204 with no body. If there is no such group, you get 404 with the not_found code; if the ID is not a UUID, 400 with the bad_request code.

Share a group with users

POST /api/v1/domain-groups/{id}/share

Sets the list of users who can see the group and its domains. The list is replaced as a whole.

IDs that are not in the team are skipped without an error. User IDs are returned by the list method on the Admin API: users page.

Response — code 204 with no body.

Errors: 400 with the bad_request code — the body was not parsed or an ID is not a UUID; 404 with the not_found code — the group does not exist.

Example request:

curl -X POST https://panel.example.com/api/v1/domain-groups/9d8c7b6a-1f2e-4d3c-b5a4-0e9f8d7c6b5a/share \
  -H "Api-Key: <token>" \
  -H "Content-Type: application/json" \
  -d '{"user_ids":["1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d"]}'

Routing to a reverse proxy node

Both methods set the domain's proxied A record to the node's address through the Cloudflare account added to the tracker, and remember the binding. The node must be in the ready status. Preparation is described on the Reverse proxy nodes and Working with Cloudflare pages, and the node and account methods on the Admin API: reverse proxy nodes and Cloudflare page.

Route a domain to a node

POST /api/v1/domains/{id}/route

Routes the domain with the ID from the path to a node.

Response — code 200 and an object: ok — true, node_ip — the node's address.

Errors:

Route several domains

POST /api/v1/domains/route-bulk

Routes up to 500 domains per request to one node.

Response — code 200, even if some domains could not be routed. Check the failed array.

The errors are the same as for the previous method, except cf_error: the causes for each domain come in failed. Codes 400 and 404 refer only to the node: a domain with an invalid or unknown ID goes into failed. The validation code is also returned for an empty domain_ids and for a list longer than 500 IDs.