Binboi Logo
Dashboard
Binboi Docs/Core/API

API Reference

Base URL: https://api.binboi.com. All endpoints are mounted under /api/v1/ and accept and return JSON.

Endpoints are subject to change before v1.0.

Authentication

Every request requires a Personal Access Token in the Authorization header:

code
Authorization: Bearer binboi_pat_a1b2c3d4_0123456789abcdef0123456789abcdef0123

Generate tokens at binboi.com/dashboard/access-tokens.

Endpoints

GET /api/v1/auth/me

Return the authenticated account.

code
curl https://api.binboi.com/api/v1/auth/me \
  -H "Authorization: Bearer binboi_pat_..."

Response 200:

code
{
  "id": "usr_4f2b9a7e",
  "email": "you@example.com",
  "plan": "FREE"
}

GET /api/v1/tokens

List your active tokens. Revoked tokens are not returned.

code
curl https://api.binboi.com/api/v1/tokens \
  -H "Authorization: Bearer binboi_pat_..."

Response 200:

code
{
  "tokens": [
    {
      "id": "tok_7c3a1d20",
      "label": "laptop",
      "prefix": "binboi_pat_a1b2c3d4",
      "created_at": "2026-05-26T19:48:12Z",
      "last_used_at": "2026-06-14T08:11:03Z"
    }
  ]
}

POST /api/v1/tokens

Create a new token. The full token is returned once — store it immediately.

code
curl -X POST https://api.binboi.com/api/v1/tokens \
  -H "Authorization: Bearer binboi_pat_..." \
  -H "Content-Type: application/json" \
  -d '{"label":"ci-runner"}'

Response 201:

code
{
  "id": "tok_a91f0b3e",
  "label": "ci-runner",
  "prefix": "binboi_pat_a91f0b3e",
  "token": "binboi_pat_a91f0b3e_4d5e6f708192a3b4c5d6e7f80910a2b3c4d5",
  "created_at": "2026-06-15T12:04:18Z"
}

DELETE /api/v1/tokens/:id

Revoke a token. Any tunnels using it are closed immediately. Frees one slot from your active token quota.

code
curl -X DELETE https://api.binboi.com/api/v1/tokens/tok_a91f0b3e \
  -H "Authorization: Bearer binboi_pat_..."

Response 204 (no body).

GET /api/v1/tunnels

List active tunnels on your account.

code
curl https://api.binboi.com/api/v1/tunnels \
  -H "Authorization: Bearer binboi_pat_..."

Response 200:

code
{
  "tunnels": [
    {
      "subdomain": "my-app",
      "port": 3000,
      "started_at": "2026-06-15T11:02:44Z",
      "token_id": "tok_7c3a1d20"
    },
    {
      "subdomain": "wispy-otter-7421",
      "port": 8080,
      "started_at": "2026-06-15T12:01:11Z",
      "token_id": "tok_7c3a1d20"
    }
  ]
}

GET /api/v1/tunnels/:subdomain

Get detail for a single tunnel.

code
curl https://api.binboi.com/api/v1/tunnels/my-app \
  -H "Authorization: Bearer binboi_pat_..."

Response 200:

code
{
  "subdomain": "my-app",
  "port": 3000,
  "started_at": "2026-06-15T11:02:44Z",
  "token_id": "tok_7c3a1d20",
  "reserved": true
}

DELETE /api/v1/tunnels/:subdomain

Close an active tunnel.

code
curl -X DELETE https://api.binboi.com/api/v1/tunnels/my-app \
  -H "Authorization: Bearer binboi_pat_..."

Response 204 (no body).

GET /api/v1/requests?subdomain=<sub>

Recent requests captured for a tunnel, within the plan's retention window.

code
curl "https://api.binboi.com/api/v1/requests?subdomain=my-app" \
  -H "Authorization: Bearer binboi_pat_..."

Response 200:

code
{
  "requests": [
    {
      "id": "req_182f0",
      "method": "GET",
      "path": "/api/users",
      "status": 200,
      "duration_ms": 12,
      "received_at": "2026-06-15T12:02:11Z"
    },
    {
      "id": "req_182ef",
      "method": "POST",
      "path": "/api/login",
      "status": 401,
      "duration_ms": 43,
      "received_at": "2026-06-15T12:02:09Z"
    }
  ]
}

GET /api/v1/billing/summary

Return the authenticated account's billing summary — current plan, period, and usage counters.

code
curl https://api.binboi.com/api/v1/billing/summary \
  -H "Authorization: Bearer binboi_pat_..."

GET /api/v1/instance

Return public metadata about the API instance (build, region, server time).

code
curl https://api.binboi.com/api/v1/instance

There is currently no /health or /api/v1/health endpoint — those paths return 404. A health endpoint is planned but not yet shipped.

Errors

All errors follow this shape:

code
{ "error": { "code": "TOKEN_LIMIT_REACHED", "message": "Active token limit reached for plan FREE" } }

| Code | HTTP | Meaning | |---|---|---| | UNAUTHORIZED | 401 | Token missing, malformed, or revoked. | | TOKEN_LIMIT_REACHED | 403 | Active token cap hit. Revoke one or upgrade. | | TUNNEL_LIMIT_REACHED | 403 | Active tunnel cap hit. Close one or upgrade. | | SUBDOMAIN_TAKEN | 409 | Reserved subdomain already owned by another account. | | NOT_FOUND | 404 | Resource does not exist on this account. | | RATE_LIMITED | 429 | Throttled. See Retry-After header. |

Rate limits

100 requests/minute per token by default. Subject to change.

When throttled, the response is 429 RATE_LIMITED with a Retry-After header in seconds.

Next

Edit this page on GitHub