REST API

Manage tunnels, domains, tokens, and usage over HTTP. Authenticate with your agent token.

The control-plane API lets you read and manage your account programmatically. The base URL is https://api.osmrouter.com.

Authentication

Send your agent token as a Bearer token:

curl https://api.osmrouter.com/v1/usage \
  -H "Authorization: Bearer $OSM_TOKEN"

Create tokens under Tokens in the dashboard. The same token authenticates the CLI, the SDK, and the API.

Endpoints

Method	Path	Description
`GET`	`/v1/me`	The current account (id, email, name, plan).
`GET`	`/v1/usage`	Current plan, limits, and usage (domains, tunnels, bandwidth).
`GET`	`/v1/usage/history`	Daily usage rollups over time.
`GET`	`/v1/tunnels`	Tunnels on your account and their status.
`DELETE`	`/v1/tunnels/:id`	Release a tunnel (free its name or port).
`GET`	`/v1/requests`	Recent requests captured by the Traffic Inspector.
`GET`	`/v1/domains`	Custom domains and their verification state.
`POST`	`/v1/domains`	Add a domain (returns the DNS TXT record to publish).
`POST`	`/v1/domains/:id/verify`	Re-check a domain's DNS TXT record.
`DELETE`	`/v1/domains/:id`	Remove a domain.
`GET`	`/v1/keys`	List agent tokens (metadata only).
`POST`	`/v1/keys`	Create an agent token (returns the secret once).
`DELETE`	`/v1/keys/:id`	Revoke an agent token.

Examples

Read current usage against your plan:

curl https://api.osmrouter.com/v1/usage \
  -H "Authorization: Bearer $OSM_TOKEN"

{
	"plan": "free",
	"limits": { "domains": 2, "tunnels": 10, "bandwidthBytes": 53687091200 },
	"used": { "domains": 0, "tunnels": 1, "bandwidthBytes": 846 }
}

List live tunnels:

curl https://api.osmrouter.com/v1/tunnels \
  -H "Authorization: Bearer $OSM_TOKEN"

Read recent inspector requests:

curl https://api.osmrouter.com/v1/requests \
  -H "Authorization: Bearer $OSM_TOKEN"

{
	"requests": [
		{
			"method": "GET",
			"path": "/",
			"status": 200,
			"durationMs": 234,
			"bytes": 28,
			"ip": "203.0.113.7",
			"userAgent": "curl/8.7.1",
			"proto": "HTTP/2.0",
			"host": "my-app.osmrouter.com"
		}
	]
}

Trigger a domain re-check:

curl -X POST https://api.osmrouter.com/v1/domains/<id>/verify \
  -H "Authorization: Bearer $OSM_TOKEN"

Errors

Requests without a valid token return 401:

{ "error": "unauthorized" }

Next steps

Auth tokens — create, rotate, and revoke the token you authenticate with.
Traffic Inspector — what the /v1/requests data means.

Authentication

Endpoints

Examples

Errors

Next steps

On this page