API Documentation

Returns the N most recently published blog posts.

Response

Example

GET https://btelo.com/api/blog/posts?n=5

Start an OAuth 2.0 authorization code flow. Redirects the user to the btelo.com login page, then back to your redirect_uri with ?code=... on success. Desktop/mobile clients must use PKCE (RFC 7636) by passing code_challenge — this allows the subsequent /api/oauth/token call to omit client_secret.

Response

Example

GET https://btelo.com/api/oauth/authorize?client_id=CLIENT_ID&redirect_uri=https://yourapp.com/callback&response_type=code&state=xyz&scope=openid+profile+email&code_challenge=CHALLENGE&code_challenge_method=S256

Exchange an authorization code for a JWT access token, or refresh an existing token. Two flows are supported: (1) confidential-client flow requires client_secret; (2) PKCE public-client flow (for desktop/mobile apps) requires code_verifier instead — client_secret is optional and may be omitted entirely.

Response

Example

POST https://btelo.com/api/oauth/token  body (PKCE): grant_type=authorization_code&code=CODE&redirect_uri=...&client_id=...&code_verifier=VERIFIER

Returns the authenticated user's profile. Requires a valid Bearer access token obtained from /api/oauth/token.

Response

Example

GET https://btelo.com/api/oauth/userinfo  Authorization: Bearer <access_token>

Returns the RSA public key set (JWKS) used to verify JWT access tokens issued by /api/oauth/token.

Response

Example

GET https://btelo.com/api/oauth/jwks.json

Returns the currently logged-in user's profile (session cookie required). Returns 401 if not authenticated.

Response

Example

GET https://btelo.com/api/auth/me

Returns the authenticated user's editable profile. Auth: session cookie (browser) or Btelo-Api-Key + user_id (server-to-server).

Response

Example

GET https://btelo.com/api/profile  (Cookie: btelo_session=... or Authorization: Bearer ...)

Update the authenticated user's profile. Send only the fields you want to change. Auth: session cookie (browser) or Btelo-Api-Key + user_id (server-to-server).

Response

Example

PUT https://btelo.com/api/profile  body: {"name":"New Name","bio":"Hello world"}

Delete the currently logged-in account. Requires a browser session cookie; HMAC/API-key auth is intentionally not accepted. The user must manually type their full user id and send it as user_id_confirm. The backend validates an exact match before deleting. Account/login/app state is removed; historical order rows are retained for legal/accounting audit. This endpoint does not cancel Apple or Stripe subscriptions; users must cancel those in Apple subscriptions or Stripe billing.

Response

{
  "ok": true,
  "deleted": true
}

Example

POST https://btelo.com/api/account/delete  Cookie: btelo_session=...  body: {"user_id_confirm":"32hexuserid"}

Bind the authenticated user to an inviter by invite code. This is allowed after registration only if the user does not already have an inviter. Once set, the inviter cannot be changed. Future successful subscription payments use this inviter relationship to apply regular invite rewards or share-partner commission ledger entries.

Response

Example

POST https://btelo.com/api/profile/inviter  body: {"invite_code":"streamer-jenny"}

Send an email to a user immediately, or schedule it for a future time. Requires Btelo-Api-Key header.

Response

Example

POST https://btelo.com/api/email/send  Btelo-Key-Id: ... Btelo-Ts: ... Btelo-Sign: ...  body: {"user_id":"abc","subject":"Hello","html":"<h1>Hi</h1>"}

List scheduled emails. Optionally filter by user_id. Requires Btelo-Api-Key header.

Response

Example

GET https://btelo.com/api/email/scheduled?user_id=abc  Btelo-Key-Id: ... Btelo-Ts: ... Btelo-Sign: ...

Cancel a pending scheduled email before it is sent. Requires Btelo-Api-Key header.

Response

Example

DELETE https://btelo.com/api/email/scheduled/abc123  Btelo-Key-Id: ... Btelo-Ts: ... Btelo-Sign: ...

Health check. Returns 200 OK with body "ok".

Response

Example

GET https://btelo.com/api/health

Returns this API documentation as JSON.

Response

Example

GET https://btelo.com/api/doc

List all available subscription tiers with pricing. Auth: Bearer user JWT OR HMAC.

Response

{
  tiers: [
    {
      slug,
      name,
      level,
      monthly_cents,
      yearly_cents,
      trial_days,
      monthly_credit_cap
    }
  ]
}—monthly_credit_capistheAI-creditallowancegrantedeachcalendarmonthatthistier(0fortierswithnoallowance).

Example

GET https://btelo.com/api/v1/tiers  Authorization: Bearer <user_jwt>

Get a user's current subscription status. Auth: Bearer user JWT (user_id inferred from token) OR HMAC + user_id. With Bearer, query user_id is ignored.

Response

{
  active,
  had_subscription,
  tier?,
  status?,
  plan?,
  source?,
  platform?,
  app_id?,
  cancel_at_period_end?,
  current_period_end?,
  canceled_at?,
  has_access?
}—active=truewhentheeffectiveunifiedbillingsourceisactive/trialing/grace.source/platformmaybestripe,
apple,
ormanual.Whenactive=false,
fieldsdescribetheMOSTRECENTsubscriptionsourcesotheclientcandistinguish'neversubscribed'from'expired'.

Example

GET https://btelo.com/api/v1/subscription?tier=pro  Authorization: Bearer <user_jwt>

Create a Stripe Checkout URL for a subscription. Auth: Bearer user JWT OR HMAC + user_id.

Response

{
  url: "https: //checkout.stripe.com/..."
}

Example

POST https://btelo.com/api/v1/subscription/checkout-url  Authorization: Bearer <user_jwt>  body: {"tier":"pro","plan":"monthly","success_url":"https://yourapp.com/ok","cancel_url":"https://yourapp.com/cancel"}

Get a user's credit balance. Auth: Bearer user JWT OR HMAC + user_id.

Response

{
  user_id,
  credits
}

Example

GET https://btelo.com/api/v1/credits  Authorization: Bearer <user_jwt>

Deduct credits from a user's balance. Returns 402 if insufficient. Auth: Bearer user JWT (self-deduct) OR HMAC + user_id (any user).

Response

{
  user_id,
  deducted,
  remaining
}

Example

POST https://btelo.com/api/v1/credits/deduct  Authorization: Bearer <user_jwt>  body: {"amount":100,"reason":"image generation"}

Create a Stripe Checkout URL for a one-time credit purchase. Auth: Bearer user JWT OR HMAC + user_id.

Response

{
  url: "https: //checkout.stripe.com/..."
}

Example

POST https://btelo.com/api/v1/credits/checkout-url  Authorization: Bearer <user_jwt>  body: {"slug":"credits-500","success_url":"https://yourapp.com/ok","cancel_url":"https://yourapp.com/cancel"}

Calculate the wallet credit cost for a product entitlement price. This does not require btelo-side SKU configuration: product servers choose their own SKU names and dollar prices, and btelo converts price_cents to credits using the same credit price curve used by credit purchases. Auth: Bearer user JWT OR HMAC.

Response

{
  price_cents,
  cost_credits,
  basis
}—basisis"btelo_credit_price_curve".

Example

POST https://btelo.com/api/v1/entitlements/quote  Authorization: Bearer <user_jwt>  body: {"price_cents":5000}

List active product entitlements for a user, or check one product/SKU pair. Auth: Bearer user JWT (user_id inferred from token) OR HMAC + user_id. With Bearer, query user_id is ignored.

Response

{
  user_id,
  entitlements: [
    {
      id,
      product,
      sku,
      name,
      kind,
      price_cents,
      cost_credits,
      granted_at,
      expires_at?
    }
  ],
  active?,
  product?,
  sku?
}

Example

GET https://btelo.com/api/v1/entitlements?product=vibe-remote&sku=lifetime  Authorization: Bearer <user_jwt>

Redeem wallet credits for a product entitlement. This is the recommended buyout/lifetime access flow. No btelo-side product/SKU configuration is required: the authenticated product backend sends its own SKU and price_cents. This endpoint is HMAC-only so users cannot forge dynamic prices from the browser. The product defaults to Btelo-Key-Id and, if provided, must match Btelo-Key-Id. Currently only lifetime entitlements are supported. Repeated redemption of the same active user/product/sku returns the existing entitlement without deducting credits again.

Response

{
  user_id,
  created,
  remaining,
  cost_credits,
  entitlement: {
    id,
    product,
    sku,
    name,
    kind,
    price_cents,
    cost_credits,
    granted_at
  }
}

Example

POST https://btelo.com/api/v1/entitlements/redeem?user_id=usr_123  Btelo-Key-Id: vibe-remote  Btelo-Ts: ...  Btelo-Sign: ...  body: {"sku":"lifetime","name":"Vibe Remote Lifetime","price_cents":5000}

Check whether a user is marked as an owner of an app. Btelo admins set owner apps on the user detail page. Auth: Bearer user JWT (user_id inferred from token) OR HMAC + user_id. With Bearer, query user_id is ignored.

Response

{
  user_id,
  owner_apps,
  app?,
  is_owner?
}—owner_appsisthecompletearrayofappslugs.appandis_ownerarepresentwhenqueryappisprovided.

Example

GET https://btelo.com/api/v1/ownership?app=vibe-remote  Authorization: Bearer <user_jwt>

Returns the AI proxy API documentation as JSON. Lists all AI endpoints, auth requirements, and request/response formats.

Response

Example

GET https://btelo.com/api/ai/readme

Get the caller's current monthly AI-credit allowance and wallet balance. Use this to render a usage gauge before making AI calls. Auth: Bearer user JWT (required — HMAC not supported on this endpoint).

Response

{
  tier,
  monthly_cap,
  allowance_used,
  allowance_remaining,
  wallet_credits,
  total_available,
  month
}—monthly_cap=AI-creditallowancefortheuser'stierthiscalendarmonth(0ifnoactivesubscription);allowance_used=consumedthismonth;allowance_remaining=max(0,
cap-used);wallet_credits=purchasedone-timecredits;total_available=allowance_remaining+wallet_credits;month='2006-01'UTC.

Example

GET https://btelo.com/api/ai/quota  Authorization: Bearer <user_jwt>

OpenAI image generation with auto-resize. Auth: Bearer user JWT OR HMAC. Bearer calls are metered per-user.

Example

POST https://btelo.com/v1/images/generations  Authorization: Bearer <user_jwt>  Btelo-Product: btelo-up

OpenAI text-to-speech proxy. Auth: Bearer user JWT OR HMAC. Bearer calls are metered per-user.

Example

POST https://btelo.com/v1/audio/speech  Authorization: Bearer <user_jwt>  Btelo-Product: btelo-up

Public price list for every enabled model, normalized to credits. Chat rates are credits per 1k input/output/cache-read/cache-write tokens; image rates are credits per single image for each (model,size,quality) combo; TTS rates are credits per 1k characters. Use this to label model pickers with authoritative, always-fresh cost info — re-fetch on startup and whenever model admin state may have changed.

Response

{
  chat: [
    {
      provider,
      model,
      max_output_tokens,
      input_credits_per_1k,
      output_credits_per_1k,
      cache_read_credits_per_1k,
      cache_write_credits_per_1k
    }
  ],
  image: [
    {
      provider,
      model,
      size,
      quality,
      credits_per_image
    }
  ],
  tts: [
    {
      provider,
      model,
      credits_per_1k_chars
    }
  ],
  video: [
    {
      provider,
      model,
      resolution,
      duration_seconds,
      credits_per_video
    }
  ],
  music: [
    {
      provider,
      model,
      credits_per_song
    }
  ],
  unit,
  update
}

Example

GET https://btelo.com/api/ai/pricing

Convert one user-uploaded image into a fully-spec-compliant macOS + iOS app-icon bundle. Returns a ZIP containing: macos/icon.icns (drop-in binary), macos/icon.iconset/* (Apple squircle template, 16-1024 px with @2x), and ios/AppIcon.appiconset/* (iPhone + iPad full-bleed PNGs at every standard size, plus 1024 marketing image and a preconfigured Contents.json). Pure CPU work — no upstream AI is called. Flat 50 credits per request; free when called with Btelo-Product: btelo-up.

Response

Example

POST https://btelo.com/v1/images/icon-pack  Authorization: Bearer <user_jwt>  Btelo-Product: btelo-up  -F [email protected]

MiniMax video generation (synchronous wrapper — the server submits the async task, polls every 5s up to 5 min, then returns the final download URL). Billed once at submission per (model, resolution, duration); full refund on upstream failure or timeout. The (model, resolution, duration) triple must match an enabled row in the video price table (see GET /api/ai/pricing → video). Auth: Bearer user JWT OR HMAC.

Response

{
  status: "success",
  task_id,
  file_id,
  download_url
}

Example

POST https://btelo.com/v1/minimax/video/generation  Authorization: Bearer <user_jwt>  Btelo-Product: btelo-up  body: {"model":"MiniMax-Hailuo-02","prompt":"a cat surfing","resolution":"768P","duration":6}

MiniMax music generation (synchronous). Flat per-song charge for tracks up to 5 minutes. model must be an enabled music-* slug (music-2.6, music-2.5+, music-2.5, music-2.0). Auth: Bearer user JWT OR HMAC.

Response

Example

POST https://btelo.com/v1/minimax/music/generation  Authorization: Bearer <user_jwt>  Btelo-Product: btelo-up  body: {"model":"music-2.6","lyrics":"...","prompt":"upbeat pop"}

MiniMax lyrics generation. Flat per-song charge billed against the virtual 'lyrics-gen' model (see GET /api/ai/pricing → music). Auth: Bearer user JWT OR HMAC.

Response

Example

POST https://btelo.com/v1/minimax/music/lyrics  Authorization: Bearer <user_jwt>  Btelo-Product: btelo-up  body: {"prompt":"a wistful autumn ballad"}

Anthropic Messages API wire format. Integrate with @anthropic-ai/sdk or any Anthropic-compatible client — callers see pure Anthropic semantics (messages, content blocks, tool_use, stop_reason). Upstream happens to be MiniMax's anthropic-compat endpoint, but that is an implementation detail. Distinct from /v1/responses (Codex) and /v1/chat/completions (OpenAI). Auth: Bearer user JWT OR HMAC. Bearer calls are metered against the user's subscription tier + wallet.

Example

POST https://btelo.com/v1/messages  Authorization: Bearer <user_jwt>  Btelo-Product: btelo-up

OpenAI Chat Completions wire format. Use with OpenAI SDKs and legacy OpenAI-style clients. NOTE: codex 0.95+ does NOT use this path — codex speaks Responses API only (see /v1/responses). Distinct from /v1/messages (Anthropic) and /v1/responses (Codex). Supports streaming. Requires AI API key (HMAC headers or user JWT).

Example

POST https://btelo.com/v1/chat/completions  body: {"model":"MiniMax-M2.7","messages":[{"role":"user","content":"hi"}]}

Register a new integration. Auth: admin session cookie OR HMAC from an integration with is_admin=true. Returns the created integration including the generated secret.

Response

Example

POST https://btelo.com/admin/integrations  Btelo-Key-Id: ... Btelo-Ts: ... Btelo-Sign: ...  body: {"id":"auto-social","name":"Auto Social","redirect_uris":["https://auto-social.com/auth/cb"]}

List all registered integrations. Secrets are included (plaintext) because they must be retrievable for re-display.

Response

Example

GET https://btelo.com/admin/integrations  Btelo-Key-Id: ... Btelo-Ts: ... Btelo-Sign: ...

Update an existing integration's name, redirect URIs, and admin flag. The secret is NOT changed (use /rotate for that). Pass the full desired redirect_uris list — the stored list is replaced, not merged.

Response

Example

PATCH https://btelo.com/admin/integrations/vibe-remote  Btelo-Key-Id: ... Btelo-Ts: ... Btelo-Sign: ...  body: {"name":"Vibe Remote","redirect_uris":["https://vibe-remote.com/auth/cb","https://app.vibe-remote.com/auth/cb"],"is_admin":false}

Delete an integration permanently. Existing OAuth tokens already issued keep working until expiry; new logins and HMAC calls are rejected immediately.

Response

Example

DELETE https://btelo.com/admin/integrations/vibe-remote  Btelo-Key-Id: ... Btelo-Ts: ... Btelo-Sign: ...

Rotate the secret of an existing integration. The previous secret is invalidated immediately. Returns the new plaintext secret.

Response

Example

POST https://btelo.com/admin/integrations/vibe-remote/rotate  Btelo-Key-Id: ... Btelo-Ts: ... Btelo-Sign: ...

Enable or disable an integration without deleting it. Disabled integrations cannot authenticate (OAuth and HMAC both return 401).

Response

Example

POST https://btelo.com/admin/integrations/vibe-remote/disable  Btelo-Key-Id: ... Btelo-Ts: ... Btelo-Sign: ...  body: {"disabled":true}

OpenAI Responses API wire format — the protocol codex 0.95+ speaks to custom providers. Input items are message / function_call / function_call_output; tools are declared as flat {type,name,parameters}. Always SSE; events follow the response.* schema (response.created, response.output_item.added, response.output_text.delta, response.output_item.done, response.completed). Internally translated to Chat Completions before forwarding upstream and streamed back as Responses events. Distinct from /v1/messages (Anthropic protocol) and /v1/chat/completions (OpenAI Chat protocol) — they are NOT interchangeable. Codex clients SHOULD set model_provider.proxy.wire_api="responses" in ~/.codex/config.toml. Same auth, billing, and quota pipeline as the other AI proxy paths.

Example

POST https://btelo.com/v1/responses  body: {"model":"MiniMax-M2.7","instructions":"be helpful","input":[{"type":"message","role":"user","content":[{"type":"input_text","text":"hi"}]}],"stream":true}

Web-search tool exposed by the minimax-coding-plan-mcp server (the `web_search` MCP tool). Returns a structured JSON of organic results with title / link / snippet. Preferred over shell `curl` inside agent sandboxes — avoids dumping raw HTML into function_call_output. Same auth + billing pipeline as the other /v1 AI proxy routes.

Example

POST https://btelo.com/v1/coding_plan/search  body: {"query":"codex CLI mcp config"}

Image-understanding tool exposed by the minimax-coding-plan-mcp server (the `understand_image` MCP tool). Analyzes images with AI based on text prompts. Supports JPEG/PNG/GIF/WebP up to 20MB. Same auth + billing pipeline as the other /v1 AI proxy routes.

Example

POST https://btelo.com/v1/coding_plan/vlm  body: {"prompt":"what is in this screenshot?","image":"https://.../shot.png"}

Caller's current monthly allowance + wallet (requires user JWT).

Caller's recent AI usage rows (requires user JWT). ?month=YYYY-MM optional.

List every meta blob owned by the caller. Each entry has `kind`, `data` (verbatim JSON you stored), and `updated_at`.

Response

{
  metas: [
    {
      kind: string,
      data: any,
      updated_at: string
    }
  ]
}

Example

GET https://btelo.com/api/meta  Authorization: Bearer <jwt>

Fetch a single meta blob by kind. 404 if absent. `kind` must match [a-z0-9_.-]{1,64}.

Response

{
  kind: string,
  data: any,
  updated_at: string
}

Example

GET https://btelo.com/api/meta/settings  Authorization: Bearer <jwt>

Create-or-update the blob under kind. Body must be valid JSON (object, array, number, string, boolean, or null) and ≤ 256 KiB. (user_id, kind) is the unique key — there is no separate POST/create.

Response

{
  kind: string,
  data: any,
  updated_at: string
}

Example

PUT https://btelo.com/api/meta/settings  Authorization: Bearer <jwt>  body: {"theme":"dark","lang":"en"}

Remove the blob under kind. Idempotent — returns 204 even if the kind was already absent.

Response

Example

DELETE https://btelo.com/api/meta/settings  Authorization: Bearer <jwt>

Return store product IDs for one app/platform. Client apps use this to discover StoreKit product IDs without hardcoding them. Auth: Bearer user JWT OR HMAC.

Response

{
  app_id,
  name,
  platform,
  ios_bundle_id?,
  products: [
    {
      kind,
      store_product_id,
      tier?,
      plan?,
      credit_slug?,
      credits?,
      cents?
    }
  ]
}

Example

GET https://btelo.com/api/v1/billing/config?app_id=btelo-english&platform=apple  Authorization: Bearer <user_jwt>

Sync an Apple StoreKit purchase to btelo. The app sends the transaction_id after purchase; btelo verifies it with Apple's App Store Server API, checks the configured bundle/product mapping, then records either a unified billing subscription or a one-time wallet credit transaction. The app should pass StoreKit appAccountToken during purchase when possible so Apple server notifications can be routed even if they arrive before this client sync. Auth: Bearer user JWT.

Response

Example

POST https://btelo.com/api/v1/iap/apple/transactions  Authorization: Bearer <user_jwt>  body: {"app_id":"btelo-english","transaction_id":"2000000123456789"}

Apple App Store Server Notifications V2 receiver. Configure this exact URL as both Production and Sandbox Server URL for each app that uses btelo billing. This endpoint is called by Apple, not by client apps. A single shared URL is safe for multiple apps because btelo routes by bundleId + originalTransactionId/appAccountToken and validates product mappings before writing subscription state or wallet-credit transactions.

Response

Example

App Store Connect -> My Apps -> <app> -> App Information -> App Store Server Notifications -> Version 2 -> Production/Sandbox URL = https://btelo.com/api/iap/apple/notifications

Create or update a billing app config. Auth: HMAC from an Integration with is_admin=true.

Example

POST https://btelo.com/api/v1/billing/apps  <admin HMAC headers>  body: {"id":"btelo-english","name":"Btelo English","ios_bundle_id":"com.btelo.english"}

Create or update a store product mapping. Auth: HMAC from an Integration with is_admin=true.

Return active announcements for one product app. Disabled announcements, expired announcements, and announcements for other apps are filtered out by btelo.com. Audience targeting is returned for product apps to evaluate locally.

Response

Example

GET https://btelo.com/api/v1/announcements?app=btelo-english  <Btelo HMAC headers>

Prompt for product app agents implementing Btelo feedback. Use this as the canonical integration behavior instead of inventing app-specific feedback protocols.

Create a product-scoped feedback thread. Product apps may use their own user ids; the user_id does not need to exist in btelo.com. If Authorization: Bearer is present and user_id is omitted, btelo uses the JWT subject. Clients should provide system_info whenever possible so admins can diagnose issues without asking the user for hidden technical details.

Response

{
  id,
  product_name,
  user_id,
  user_name?,
  status,
  messages[
    
  ]
}.Officialresponsesarereturnedasmessageswithauthor="official"andauthor_label="Officialreply".

Example

POST https://btelo.com/api/v1/feedback  Btelo-Product: btelo-english  body: {"user_id":"app-user-123","user_name":"Alice","content":"The transcript screen is blank.","system_info":{"user":{"email":"[email protected]","created_at":"2026-05-01T12:00:00Z"},"subscription":{"tier":"pro","status":"active","source":"apple"},"app":{"version":"1.4.2","build":"88","route":"#/video"},"device":{"platform":"ios","model":"iPhone","os":"17.5"},"browser":{"user_agent":"...","language":"en-US","timezone":"America/Chicago","screen":"390x844"}}}

List feedback threads for one product/user pair, including official replies and user follow-ups. If Authorization: Bearer is present and user_id is omitted, btelo uses the JWT subject.

Response

Example

GET https://btelo.com/api/v1/feedback?product_name=vibe-remote&user_id=app-user-123

Append a user follow-up to an existing feedback thread. The supplied product/user identity must match the original thread.

Response

Example

POST https://btelo.com/api/v1/feedback/{id}/messages  body: {"product_name":"vibe-remote","user_id":"app-user-123","content":"More details..."}