trqsh
Reference40 operations · v1.0.0

trqsh Control API

Manage cloud accounts, credentials, domains and reported usage. To start or stop a tunnel on a computer, use the separate local agent API.

Connect and authenticate

This deployment's base URL
https://api.trqsh.uz/v1

Append the endpoint path below. Send Authorization: Bearer YOUR_API_KEY or a dashboard access JWT. The same header carries either credential; a local control token does not authenticate here.

Shell · authenticated read
curl -fsS \  -H "Authorization: Bearer $TRQSH_API_KEY" \  "https://api.trqsh.uz/v1/me"
PowerShell · authenticated read
$trqshHeaders = @{ Authorization = "Bearer $env:TRQSH_API_KEY" }Invoke-RestMethod -Uri "https://api.trqsh.uz/v1/me" -Headers $trqshHeaders

Supply your real key through a private environment variable. /me works with API keys or JWTs; /account is a user-profile endpoint intended for dashboard JWTs.

Requests, responses and errors

  • Send JSON bodies with Content-Type: application/json. Replace path placeholders such as {id} with the returned resource ID.
  • Successful DELETE actions commonly return 204 with no body; do not parse them as JSON.
  • Resource failures normally return {"error":"message"}. Check the HTTP status before reading success fields.
  • 401 means missing/rejected credentials; 403 means a permission, plan or disabled-feature condition; 409 means a conflict; 429 means rate limiting.
  • SSE endpoints return text/event-stream. Read streamed event frames and reconnect when necessary.

Limits and required fields come from the checked-in contract. Deployed API versions can differ. Fetch the deployed OpenAPI document when building a client for a specific server. Development email auth and optional Stripe billing endpoints are conditional features.

Download deployed OpenAPI

Example: reserve a hostname

Shell · creates an account resource
curl -fsS \  -H "Authorization: Bearer $TRQSH_API_KEY" \  -H "Content-Type: application/json" \  -d '{"subdomain":"myapp"}' \  "https://api.trqsh.uz/v1/subdomains"

A successful reservation returns 201. Start the actual tunnel with /http 3000 --subdomain myapp on the agent. Cloud GET /tunnels lists sessions reported by the edge; it does not launch your local app.

Authentication

POST/auth/signupNo Bearer auth

Create an account (dev/email flow)

Test-only endpoint, disabled by default. Requires explicit TRQSH_DEV_AUTH=1 in development and is always forbidden in production. Public accounts use GitHub or Google with a verified email.

Request body · required · application/json
FieldTypeDetails
emailrequiredstringformat: email
nameoptionalstringSee full definition.
SignupRequest · JSON Schema
{  "type": "object",  "required": [    "email"  ],  "properties": {    "email": {      "type": "string",      "format": "email"    },    "name": {      "type": "string"    }  }}

Responses

  • 200Account created
    200 response schema · application/json
    FieldTypeDetails
    useroptionalobjectSee full definition.
    orgoptionalobjectSee full definition.
    tokensoptionalTokensSee full definition.
    AuthResponse · JSON Schema
    {  "type": "object",  "properties": {    "user": {      "type": "object"    },    "org": {      "type": "object"    },    "tokens": {      "$ref": "#/components/schemas/Tokens"    }  }}
  • 403Email-only authentication is disabled
  • 409User already exists
POST/auth/loginNo Bearer auth

Log in (dev/email flow)

Test-only email login, disabled by default. Explicit development opt-in is required; production always rejects it. Use GitHub/Google OAuth or device approval.

Request body · required · application/json
FieldTypeDetails
emailrequiredstringformat: email
nameoptionalstringSee full definition.
SignupRequest · JSON Schema
{  "type": "object",  "required": [    "email"  ],  "properties": {    "email": {      "type": "string",      "format": "email"    },    "name": {      "type": "string"    }  }}

Responses

  • 200Tokens
    200 response schema · application/json
    FieldTypeDetails
    useroptionalobjectSee full definition.
    orgoptionalobjectSee full definition.
    tokensoptionalTokensSee full definition.
    AuthResponse · JSON Schema
    {  "type": "object",  "properties": {    "user": {      "type": "object"    },    "org": {      "type": "object"    },    "tokens": {      "$ref": "#/components/schemas/Tokens"    }  }}
  • 401No such user
  • 403Development authentication is disabled
POST/auth/logoutNo Bearer auth

Clear browser session cookies and revoke the supplied refresh token

Reads the refresh token from the browser cookie or JSON body. Existing short-lived access tokens expire normally. Does not revoke API keys.

Request body · optional · application/json
FieldTypeDetails
refresh_tokenoptionalstringRefresh token to revoke; optional when the browser cookie is present
JSON Schema
{  "type": "object",  "properties": {    "refresh_token": {      "type": "string",      "description": "Refresh token to revoke; optional when the browser cookie is present"    }  }}

Responses

  • 200Signed out
    200 response schema · application/json
    FieldTypeDetails
    statusoptionalstringvalues: ok
    JSON Schema
    {  "type": "object",  "properties": {    "status": {      "type": "string",      "enum": [        "ok"      ]    }  }}
POST/auth/refreshNo Bearer auth

Exchange a refresh token for a new token pair

Request body · required · application/json
FieldTypeDetails
refresh_tokenoptionalstringSee full definition.
JSON Schema
{  "type": "object",  "properties": {    "refresh_token": {      "type": "string"    }  }}

Responses

  • 200Tokens
    200 response schema · application/json
    FieldTypeDetails
    access_tokenoptionalstringSee full definition.
    refresh_tokenoptionalstringSee full definition.
    expires_inoptionalintegerSee full definition.
    token_typeoptionalstringSee full definition.
    Tokens · JSON Schema
    {  "type": "object",  "properties": {    "access_token": {      "type": "string"    },    "refresh_token": {      "type": "string"    },    "expires_in": {      "type": "integer"    },    "token_type": {      "type": "string"    }  }}
GET/auth/providersNo Bearer auth

List configured public sign-in providers

Available in production; returns only provider names and no credentials or internal status.

Responses

  • 200Configured OAuth providers
    200 response schema · application/json
    FieldTypeDetails
    providersoptionalstring[]See full definition.
    JSON Schema
    {  "type": "object",  "properties": {    "providers": {      "type": "array",      "items": {        "type": "string",        "enum": [          "github",          "google"        ]      }    }  }}
GET/auth/oauth/{provider}No Bearer auth

Begin an OAuth flow (github|google)

Parameters

Name / locationTypeDetails
providerpath · requiredstringvalues: github, google

Responses

  • 302Redirect to the provider
GET/auth/oauth/{provider}/callbackNo Bearer auth

Complete a browser-bound OAuth flow with PKCE

Requires verified provider email and a stable provider ID. Redirects to the dashboard with a short-lived single-use exchange code; never returns tokens in a browser URL.

Parameters

Name / locationTypeDetails
providerpath · requiredstring
codequery · requiredstring
statequery · requiredstring

Responses

  • 302Dashboard exchange or sign-in error redirect
  • 400Invalid browser state or PKCE binding
POST/auth/device/codeNo Bearer auth

Start a device-authorization flow (CLI/GUI login)

Responses

  • 200Device + user codes
    200 response schema · application/json
    FieldTypeDetails
    device_codeoptionalstringSee full definition.
    user_codeoptionalstringSee full definition.
    verification_urioptionalstringSee full definition.
    verification_uri_completeoptionalstringSee full definition.
    intervaloptionalintegerSee full definition.
    expires_inoptionalintegerSee full definition.
    DeviceCode · JSON Schema
    {  "type": "object",  "properties": {    "device_code": {      "type": "string"    },    "user_code": {      "type": "string"    },    "verification_uri": {      "type": "string"    },    "verification_uri_complete": {      "type": "string"    },    "interval": {      "type": "integer"    },    "expires_in": {      "type": "integer"    }  }}
POST/auth/device/approveBearer auth

Approve a device user code (browser, authenticated)

Request body · required · application/json
FieldTypeDetails
user_codeoptionalstringSee full definition.
JSON Schema
{  "type": "object",  "properties": {    "user_code": {      "type": "string"    }  }}

Responses

  • 200Approved
POST/auth/device/tokenNo Bearer auth

Poll for the device API key

Request body · required · application/json
FieldTypeDetails
device_codeoptionalstringSee full definition.
JSON Schema
{  "type": "object",  "properties": {    "device_code": {      "type": "string"    }  }}

Responses

  • 200API key
    200 response schema · application/json
    FieldTypeDetails
    api_keyoptionalstringSee full definition.
    JSON Schema
    {  "type": "object",  "properties": {    "api_key": {      "type": "string"    }  }}
  • 400authorization_pending | expired_token | invalid_device_code

Account

GET/accountBearer auth

The authenticated user and their orgs

User profile for a dashboard JWT. API-key callers should use /me because they identify an organization rather than a user subject.

Responses

  • 200Account
  • 404User profile not found for this principal

Profile & effective plan

GET/meBearer auth

Profile, organization, effective plan and usage for a JWT or API key

API-key callers receive the organization owner's profile. Expired paid grants use the effective Free plan.

Responses

  • 200Account snapshot
    200 response schema · application/json
    FieldTypeDetails
    useroptionalobjectSee full definition.
    orgoptionalobjectSee full definition.
    planoptionalstringSee full definition.
    plan_expires_atoptionalstring | nullformat: date-time
    via_api_keyoptionalbooleanSee full definition.
    usageoptionalobjectSee full definition.
    limitsoptionalobjectSee full definition.
    JSON Schema
    {  "type": "object",  "properties": {    "user": {      "type": "object"    },    "org": {      "type": "object"    },    "plan": {      "type": "string"    },    "plan_expires_at": {      "type": [        "string",        "null"      ],      "format": "date-time"    },    "via_api_key": {      "type": "boolean"    },    "usage": {      "type": "object"    },    "limits": {      "type": "object"    }  }}

API keys

GET/api-keysBearer auth

List API keys (prefixes only)

Responses

  • 200Keys
POST/api-keysBearer auth

Create an API key (plaintext returned once)

Request body · optional · application/json
FieldTypeDetails
nameoptionalstringSee full definition.
JSON Schema
{  "type": "object",  "properties": {    "name": {      "type": "string"    }  }}

Responses

  • 201Created
    201 response schema · application/json
    FieldTypeDetails
    idoptionalstringSee full definition.
    nameoptionalstringSee full definition.
    prefixoptionalstringSee full definition.
    api_keyoptionalstringPlaintext, shown once
    CreatedAPIKey · JSON Schema
    {  "type": "object",  "properties": {    "id": {      "type": "string"    },    "name": {      "type": "string"    },    "prefix": {      "type": "string"    },    "api_key": {      "type": "string",      "description": "Plaintext, shown once"    }  }}
DELETE/api-keys/{id}Bearer auth

Revoke an API key

Parameters

Name / locationTypeDetails
idpath · requiredstring

Responses

  • 204Revoked

Reserved subdomains

GET/subdomainsBearer auth

List reserved subdomains

Responses

  • 200OK
POST/subdomainsBearer auth

Reserve a subdomain (subject to plan limits)

Request body · optional · application/json
FieldTypeDetails
subdomainoptionalstringSee full definition.
JSON Schema
{  "type": "object",  "properties": {    "subdomain": {      "type": "string"    }  }}

Responses

  • 201Reserved
  • 403Plan limit reached
  • 409Subdomain already taken
DELETE/subdomains/{id}Bearer auth

Release a reserved subdomain

Parameters

Name / locationTypeDetails
idpath · requiredstring

Responses

  • 204Released

Custom domains

GET/domainsBearer auth

List custom domains

Responses

  • 200OK
POST/domainsBearer auth

Add a custom domain (returns DNS verification instructions)

Request body · optional · application/json
FieldTypeDetails
domainoptionalstringSee full definition.
JSON Schema
{  "type": "object",  "properties": {    "domain": {      "type": "string"    }  }}

Responses

  • 201Added
  • 403Plan does not allow custom domains
POST/domains/{id}/verifyBearer auth

Verify a custom domain via DNS TXT

Parameters

Name / locationTypeDetails
idpath · requiredstring

Responses

  • 200Verified
  • 400DNS record not found yet

Usage

GET/usageBearer auth

Usage for the active org (last 30 days)

Responses

  • 200OK
GET/usage/historyBearer auth

Usage time series for the active org (bucket=hour|day, days=N), for dashboard graphs

Parameters

Name / locationTypeDetails
bucketquery · optionalstringvalues: hour, day
daysquery · optionalinteger

Responses

  • 200OK

Organizations

GET/orgsBearer auth

Orgs the caller belongs to

Responses

  • 200OK

Tunnel sessions

GET/tunnelsBearer auth

Live (active) tunnel sessions for the organization

Read-only list reported by the edge, capped at 200 sessions. This endpoint does not create or stop a local tunnel.

Responses

  • 200OK
GET/tunnels/historyBearer auth

Paginated tunnel-session history for the org (active + closed)

Parameters

Name / locationTypeDetails
activequery · optionalbooleanUse true to return active sessions only
limitquery · optionalintegerPage size, capped at 200default: 50; minimum: 1; maximum: 200
offsetquery · optionalintegerNumber of sessions to skipdefault: 0; minimum: 0

Responses

  • 200OK

Plans

GET/plansBearer auth

The plan/quota catalog

Responses

  • 200OK
GET/plans/publicNo Bearer auth

The plan/quota catalog, unauthenticated (build-time consumption by the marketing site)

Responses

  • 200OK

Regions

GET/regionsNo Bearer auth

The edge PoP catalog (code, city, endpoint) for region selection

Responses

  • 200OK

Location

GET/geoNo Bearer auth

Detect the caller's country and recommend the nearest edge region

Parameters

Name / locationTypeDetails
ipquery · optionalstringOverride IP (dev only)

Responses

  • 200OK

QR remote control

POST/remote/sessionsBearer auth

Start a /qr remote-control pairing session (CLI console, authenticated)

Responses

  • 201Pairing code + viewer URL
    201 response schema · application/json
    FieldTypeDetails
    codeoptionalstringPairing code — also the viewer URL's capability token
    urloptionalstringhttps://qr.<base>/<code>
    expires_atoptionalstringformat: date-time
    RemoteSession · JSON Schema
    {  "type": "object",  "properties": {    "code": {      "type": "string",      "description": "Pairing code — also the viewer URL's capability token"    },    "url": {      "type": "string",      "description": "https://qr.<base>/<code>"    },    "expires_at": {      "type": "string",      "format": "date-time"    }  }}
GET/remote/sessions/{code}/agentBearer auth

Console (agent) side event stream — inbound commands/presence/ended (SSE)

Parameters

Name / locationTypeDetails
codepath · requiredstring

Responses

  • 200text/event-stream of RemoteEvent frames
  • 404No such session
POST/remote/sessions/{code}/publishBearer auth

Console (agent) side — publish transcript lines or a state snapshot to viewers

Parameters

Name / locationTypeDetails
codepath · requiredstring
Request body · required · application/json
FieldTypeDetails
typeoptionalstringvalues: lines, state, command, presence, ended
linesoptionalstring[]See full definition.
stateoptionalobjectSee full definition.
commandoptionalstringSee full definition.
connectedoptionalbooleanSee full definition.
RemoteEvent · JSON Schema
{  "type": "object",  "description": "One envelope shape for both the agent and viewer streams; fields present depend on type.",  "properties": {    "type": {      "type": "string",      "enum": [        "lines",        "state",        "command",        "presence",        "ended"      ]    },    "lines": {      "type": "array",      "items": {        "type": "string"      }    },    "state": {      "type": "object",      "properties": {        "online": {          "type": "boolean"        },        "edge": {          "type": "string"        },        "tunnels": {          "type": "array",          "items": {            "type": "object",            "properties": {              "id": {                "type": "string"              },              "public_url": {                "type": "string"              },              "local_addr": {                "type": "string"              },              "status": {                "type": "string"              },              "requests": {                "type": "integer"              }            }          }        }      }    },    "command": {      "type": "string"    },    "connected": {      "type": "boolean"    }  }}

Responses

  • 204Delivered (fanned out to any connected viewers)
  • 404No such session
POST/remote/sessions/{code}/endBearer auth

Console (agent) side — end the pairing early

Parameters

Name / locationTypeDetails
codepath · requiredstring

Responses

  • 204Ended; viewers see a final "ended" event
  • 404No such session
GET/remote/sessions/{code}/viewerNo Bearer auth

Phone/browser side event stream — transcript/state/presence/ended (SSE, public)

No login: the code itself, embedded in the QR/link the console shows, is the capability. Replays recent transcript + the last known state on connect.

Parameters

Name / locationTypeDetails
codepath · requiredstring

Responses

  • 200text/event-stream of RemoteEvent frames
  • 404No such session
POST/remote/sessions/{code}/commandNo Bearer auth

Phone/browser side — send a command to the paired console (public)

Parameters

Name / locationTypeDetails
codepath · requiredstring
Request body · required · application/json
FieldTypeDetails
textrequiredstringmaxLength: 240
JSON Schema
{  "type": "object",  "required": [    "text"  ],  "properties": {    "text": {      "type": "string",      "maxLength": 240    }  }}

Responses

  • 204Delivered to the attached console
  • 404No such session
  • 409No console is currently attached to this session

Optional billing integration

POST/billing/checkoutBearer auth

Create a Stripe Checkout Session to subscribe to / change plan (Part 07)

Optional operator-enabled Stripe integration. The hosted website may use a manual contact-based upgrade flow instead.

Request body · required · application/json
FieldTypeDetails
planrequiredstringvalues: pro, team, payg
cadenceoptionalstringvalues: monthly, annual, metered; default: "monthly"
JSON Schema
{  "type": "object",  "required": [    "plan"  ],  "properties": {    "plan": {      "type": "string",      "enum": [        "pro",        "team",        "payg"      ]    },    "cadence": {      "type": "string",      "enum": [        "monthly",        "annual",        "metered"      ],      "default": "monthly"    }  }}

Responses

  • 200Checkout URL
    200 response schema · application/json
    FieldTypeDetails
    urloptionalstringSee full definition.
    session_idoptionalstringSee full definition.
    JSON Schema
    {  "type": "object",  "properties": {    "url": {      "type": "string"    },    "session_id": {      "type": "string"    }  }}
  • 400Unknown/non-billable plan or no price configured
  • 503Stripe not configured
POST/billing/portalBearer auth

Create a Stripe Customer-Portal session (manage/cancel/invoices)

Responses

  • 200Portal URL
    200 response schema · application/json
    FieldTypeDetails
    urloptionalstringSee full definition.
    JSON Schema
    {  "type": "object",  "properties": {    "url": {      "type": "string"    }  }}
  • 400No subscription to manage yet
  • 503Stripe not configured
GET/billing/subscriptionBearer auth

The caller org's current plan + subscription

Responses

  • 200Subscription state
    200 response schema · application/json
    FieldTypeDetails
    planoptionalstringSee full definition.
    billing_enabledoptionalbooleanSee full definition.
    subscriptionoptionalSubscriptionSee full definition.
    JSON Schema
    {  "type": "object",  "properties": {    "plan": {      "type": "string"    },    "billing_enabled": {      "type": "boolean"    },    "subscription": {      "$ref": "#/components/schemas/Subscription"    }  }}
POST/billing/webhooksNo Bearer auth

Stripe webhook receiver (public; Stripe-Signature verified). Source of truth for plan state.

Parameters

Name / locationTypeDetails
Stripe-Signatureheader · requiredstring

Responses

  • 200Processed (or duplicate ignored)
  • 400Invalid signature or payload
  • 503Webhook secret not configured

Named schemas

References such as #/components/schemas/Tokens refer to the definitions below. These are JSON Schema definitions, not credential values or example responses.

SignupRequest
FieldTypeDetails
emailrequiredstringformat: email
nameoptionalstringSee full definition.
SignupRequest · JSON Schema
{  "type": "object",  "required": [    "email"  ],  "properties": {    "email": {      "type": "string",      "format": "email"    },    "name": {      "type": "string"    }  }}
Tokens
FieldTypeDetails
access_tokenoptionalstringSee full definition.
refresh_tokenoptionalstringSee full definition.
expires_inoptionalintegerSee full definition.
token_typeoptionalstringSee full definition.
Tokens · JSON Schema
{  "type": "object",  "properties": {    "access_token": {      "type": "string"    },    "refresh_token": {      "type": "string"    },    "expires_in": {      "type": "integer"    },    "token_type": {      "type": "string"    }  }}
AuthResponse
FieldTypeDetails
useroptionalobjectSee full definition.
orgoptionalobjectSee full definition.
tokensoptionalTokensSee full definition.
AuthResponse · JSON Schema
{  "type": "object",  "properties": {    "user": {      "type": "object"    },    "org": {      "type": "object"    },    "tokens": {      "$ref": "#/components/schemas/Tokens"    }  }}
DeviceCode
FieldTypeDetails
device_codeoptionalstringSee full definition.
user_codeoptionalstringSee full definition.
verification_urioptionalstringSee full definition.
verification_uri_completeoptionalstringSee full definition.
intervaloptionalintegerSee full definition.
expires_inoptionalintegerSee full definition.
DeviceCode · JSON Schema
{  "type": "object",  "properties": {    "device_code": {      "type": "string"    },    "user_code": {      "type": "string"    },    "verification_uri": {      "type": "string"    },    "verification_uri_complete": {      "type": "string"    },    "interval": {      "type": "integer"    },    "expires_in": {      "type": "integer"    }  }}
CreatedAPIKey
FieldTypeDetails
idoptionalstringSee full definition.
nameoptionalstringSee full definition.
prefixoptionalstringSee full definition.
api_keyoptionalstringPlaintext, shown once
CreatedAPIKey · JSON Schema
{  "type": "object",  "properties": {    "id": {      "type": "string"    },    "name": {      "type": "string"    },    "prefix": {      "type": "string"    },    "api_key": {      "type": "string",      "description": "Plaintext, shown once"    }  }}
Subscription
FieldTypeDetails
idoptionalstringSee full definition.
org_idoptionalstringSee full definition.
stripe_subscription_idoptionalstringSee full definition.
stripe_customer_idoptionalstringSee full definition.
planoptionalstringvalues: free, pro, team, payg
statusoptionalstringvalues: active, trialing, past_due, canceled, incomplete
current_period_endoptionalstringformat: date-time
cancel_at_period_endoptionalbooleanSee full definition.
Subscription · JSON Schema
{  "type": "object",  "properties": {    "id": {      "type": "string"    },    "org_id": {      "type": "string"    },    "stripe_subscription_id": {      "type": "string"    },    "stripe_customer_id": {      "type": "string"    },    "plan": {      "type": "string",      "enum": [        "free",        "pro",        "team",        "payg"      ]    },    "status": {      "type": "string",      "enum": [        "active",        "trialing",        "past_due",        "canceled",        "incomplete"      ]    },    "current_period_end": {      "type": "string",      "format": "date-time"    },    "cancel_at_period_end": {      "type": "boolean"    }  }}
RemoteSession
FieldTypeDetails
codeoptionalstringPairing code — also the viewer URL's capability token
urloptionalstringhttps://qr.<base>/<code>
expires_atoptionalstringformat: date-time
RemoteSession · JSON Schema
{  "type": "object",  "properties": {    "code": {      "type": "string",      "description": "Pairing code — also the viewer URL's capability token"    },    "url": {      "type": "string",      "description": "https://qr.<base>/<code>"    },    "expires_at": {      "type": "string",      "format": "date-time"    }  }}
RemoteEvent
FieldTypeDetails
typeoptionalstringvalues: lines, state, command, presence, ended
linesoptionalstring[]See full definition.
stateoptionalobjectSee full definition.
commandoptionalstringSee full definition.
connectedoptionalbooleanSee full definition.
RemoteEvent · JSON Schema
{  "type": "object",  "description": "One envelope shape for both the agent and viewer streams; fields present depend on type.",  "properties": {    "type": {      "type": "string",      "enum": [        "lines",        "state",        "command",        "presence",        "ended"      ]    },    "lines": {      "type": "array",      "items": {        "type": "string"      }    },    "state": {      "type": "object",      "properties": {        "online": {          "type": "boolean"        },        "edge": {          "type": "string"        },        "tunnels": {          "type": "array",          "items": {            "type": "object",            "properties": {              "id": {                "type": "string"              },              "public_url": {                "type": "string"              },              "local_addr": {                "type": "string"              },              "status": {                "type": "string"              },              "requests": {                "type": "integer"              }            }          }        }      }    },    "command": {      "type": "string"    },    "connected": {      "type": "boolean"    }  }}
Local agent API