devgate API

Authentication

Create a key in the dashboard under Identity & Access → API Keys. Give it a description and choose Read and write or Read only — a read-only key can make GET calls and nothing else. The secret starts with dgapi_ and is shown once: devgate keeps only a hash of it, so a lost key is revoked and replaced, not recovered. The list shows when each key was last used.

Send it as a bearer token on every call:

A key acts as the account it was created in — in a team, the team’s account. The owner and admins create and revoke keys; members see them. Revoking takes effect on the next call. The key is not your authtoken, and the authtoken does not work here.

Requests and objects

• Send bodies as JSON with Content-Type: application/json.
• Every object has an id with a type prefix (ep_ endpoints, rd_ reserved domains, ts_ tunnel sessions, req_ requests), its uri, and created_at. Times are RFC 3339 in UTC.
• Objects that point at others nest a reference: {"id": "rd_88", "uri": "…"}.
• PATCH changes only the fields you send. DELETE and stop calls answer 204 with no body.
• An id from another account answers 404, the same as one that never existed.

Pagination

Lists come newest first, up to limit objects (100, the most, unless you ask for fewer). While there are more, next_page_uri holds the next page’s URL — follow it until it is null. It is built from before_id, the id of the last object on the page, and keeps your filters.

{
  "endpoints": [
    { "id": "ep_415", "uri": "https://api.devgate.online/v1/endpoints/ep_415", … },
    { "id": "ep_412", "uri": "https://api.devgate.online/v1/endpoints/ep_412", … }
  ],
  "uri": "https://api.devgate.online/v1/endpoints",
  "next_page_uri": "https://api.devgate.online/v1/endpoints?limit=2&before_id=ep_412"
}

Rate limits

Each key may make 120 requests a minute; every answer carries X-RateLimit-Limit and X-RateLimit-Remaining. Past the limit, calls answer 429 with Retry-After in seconds. Keys count separately, so a busy CI key doesn’t slow down your monitoring.

Errors

A failed call answers with an HTTP status and a body naming the error. msg is the same sentence the dashboard shows; a field problem also lists every field under details.errors.

{
  "error_code": "ERR_DEVGATE_100",
  "status_code": 400,
  "msg": "A cloud endpoint has no upstream, so its policy must end in a terminating action that runs on every request: forward-internal, custom-response, redirect or deny.",
  "details": {
    "errors": { "traffic_policy": ["A cloud endpoint has no upstream, …"] }
  }
}

Endpoints

Everything on the dashboard’s Endpoints page: cloud endpoints, reserved ones, and agent endpoints while their agent runs. Cloud endpoints are created, changed and deleted here; reserved ones changed and deleted; agent endpoints only read — the agent that started one sets its options.

The endpoint object

{
  "id": "ep_412",
  "uri": "https://api.devgate.online/v1/endpoints/ep_412",
  "created_at": "2026-10-29T09:12:44Z",
  "updated_at": "2026-10-29T09:12:44Z",
  "type": "cloud",
  "name": "cloud-k2m9x0qa",
  "url": "https://shop.devgate.run",
  "proto": "https",
  "bindings": ["public"],
  "description": "Storefront",
  "enabled": true,
  "online": true,
  "paused": false,
  "pooling_enabled": false,
  "traffic_policy": "on_http_request:\n  - actions:\n      - type: forward-internal\n        config:\n          url: https://web.example.internal",
  "upstream_url": null,
  "domain": { "id": "rd_88", "uri": "https://api.devgate.online/v1/reserved_domains/rd_88" },
  "tunnel_session": null
}

• type — cloud, reserved (created in the dashboard, served by an agent), or agent (started by an agent with --url or a random URL).
• enabled — switched on; online — serving now (a cloud endpoint while enabled, an agent one while its agent runs).
• paused — on a domain your plan keeps but doesn’t serve; an upgrade brings it back.
• traffic_policy — the policy as written, YAML or JSON; empty when there is none.
• upstream_url — where the agent forwards, e.g. http://localhost:3000; null on a cloud endpoint.
• tunnel_session — the agent session serving it now, if any.

Create a cloud endpoint

The URL must be on one of your domains, or end in .internal for an internal one (the binding follows from the URL unless you pass bindings). The policy must answer every request itself, and the endpoint counts toward your plan’s online endpoints — the same checks as the dashboard’s.

curl https://api.devgate.online/v1/endpoints \
  -H "Authorization: Bearer $DEVGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://shop.devgate.run",
    "description": "Storefront",
    "traffic_policy": "on_http_request:\n  - actions:\n      - type: forward-internal\n        config:\n          url: https://web.example.internal"
  }'

It answers 201 with the endpoint.

Change the policy, switch it off

# Replace the Traffic Policy (an empty string removes a reserved endpoint's)
curl -X PATCH https://api.devgate.online/v1/endpoints/ep_412 \
  -H "Authorization: Bearer $DEVGATE_API_KEY" -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile p policy.yml '{traffic_policy: $p}')"

# Take it offline without deleting it
curl -X PATCH https://api.devgate.online/v1/endpoints/ep_412 \
  -H "Authorization: Bearer $DEVGATE_API_KEY" -H "Content-Type: application/json" \
  -d '{"enabled": false}'

A policy is checked before it is saved, as in the editor: a mistake answers 400 with the line and column, and paid actions on a plan without them answer 400 too.

Reserved domains

Your dev domain, branded names under devgate.run, and your own domains — the Domains page. Custom domains wait in pending until their CNAME is verified.

One name under devgate.run, like shop.devgate.run, is reserved as a branded domain (Hobby and up); any other hostname is your own domain (Pay-as-you-go), and the answer carries the cname_target to point it at:

curl https://api.devgate.online/v1/reserved_domains \
  -H "Authorization: Bearer $DEVGATE_API_KEY" -H "Content-Type: application/json" \
  -d '{"domain": "app.example.com", "description": "Production"}'

# After adding the CNAME record:
curl -X POST https://api.devgate.online/v1/reserved_domains/rd_91/verify -H "Authorization: Bearer $DEVGATE_API_KEY"

The domain object has domain, type (dev, branded or custom), status (active or pending), cname_target, verified_at, checked_at, dns_error — what the last check found missing — and paused.

Tunnel sessions

One per endpoint a running agent holds open. Stopping a session is Stop Endpoint in the dashboard: the agent leaves that tunnel down — its other tunnels keep running — until it is restarted, and an agent endpoint goes away with its last session. Agents older than 0.20.0 can’t be stopped remotely; their sessions show "stoppable": false.

A session has agent_version, os, ip, running, last_heartbeat_at, stopped_at, stoppable and its endpoint.

# Stop every tunnel serving ep_412
curl -s "https://api.devgate.online/v1/tunnel_sessions" -H "Authorization: Bearer $DEVGATE_API_KEY" \
  | jq -r '.tunnel_sessions[] | select(.endpoint.id == "ep_412") | .uri' \
  | xargs -I{} curl -X POST {}/stop -H "Authorization: Bearer $DEVGATE_API_KEY"

Requests

The HTTP requests Traffic Inspector shows, newest first, with its filters: endpoint_id, domain_id, method, status (2xx, 3xx, 4xx, 5xx or error) and q, a piece of the path.

With full capture on, capture holds the request and response headers and the first 10 KB of each body — text as text, anything else as base64.

Usage

GET /usage answers with this month’s figures from Usage & Limits: transfer (bytes_in, bytes_out), requests, connections, endpoint_hours, policy_units, what the plan included, the credit and how much is used and remaining, period_cost with its breakdown in US dollars, and usage per endpoint under endpoints. See usage and limits for what each meter counts.