API reference

API preview. This page is the planned Palepale backend contract. The public website and Discord activation are live; account creation, wallet funding, pairing, plans, and the additional routes below will be enabled as the backend is implemented. Examples use placeholders and never contain a real credential.

Base URLs and authentication

The API origin supplied during activation is kept separate from this website. SDK clients use the origin with /v1; account, billing, pairing, and live-event routes use the same origin without the suffix. Set these values in your local shell:

export PALEPALE_API_URL="https://YOUR_API_ORIGIN"export PALEPALE_BASE_URL="$PALEPALE_API_URL/v1"export PALEPALE_CHAT_URL="https://YOUR_CHAT_ORIGIN"export PALEPALE_API_KEY="YOUR_DEVICE_API_KEY"

$env:PALEPALE_API_URL = "https://YOUR_API_ORIGIN"$env:PALEPALE_BASE_URL = "$env:PALEPALE_API_URL/v1"$env:PALEPALE_CHAT_URL = "https://YOUR_CHAT_ORIGIN"$env:PALEPALE_API_KEY = "YOUR_DEVICE_API_KEY"

The service will use bearer authentication for API requests. Account keys and paired device keys are separate: an account key manages the account, while a device key is the credential an app sends with model requests. Keep both out of browser code, repositories, screenshots, and support messages.

Discovery

GET /api/me returns the account's service URLs after authentication. A public client can use GET /v1/models without a key to inspect the catalog.

curl "$PALEPALE_API_URL/api/me" \  -H "Authorization: Bearer $PALEPALE_API_KEY"curl "$PALEPALE_BASE_URL/models"

The discovery response is shaped like this:

{  "site": "https://YOUR_SITE_ORIGIN",  "api": "https://YOUR_API_ORIGIN"}

Streaming chat

POST /v1/chat/completions is the OpenAI-compatible model route. The backend will preserve ordered messages, system instructions, tools, tool choice, response format, and supported sampling controls. Select an exact model ID from GET /v1/models.

curl -N "$PALEPALE_BASE_URL/chat/completions" \  -H "Authorization: Bearer $PALEPALE_API_KEY" \  -H "Content-Type: application/json" \  -d @- <<'JSON'{  "model": "REPLACE_WITH_APPROVED_MODEL_ID",  "messages": [    {"role": "system", "content": "Be concise."},    {"role": "user", "content": "Explain this API in one paragraph."}  ],  "max_tokens": 1024,  "stream": true,  "stream_options": {"include_usage": true}}JSON

For a non-streaming request, omit stream or set it to false. Streaming responses use Server-Sent Events: read choices[].delta.content, assemble any tool-call argument fragments by index, read the final usage event, and stop at data: [DONE]. The response includes an X-Request-Id header. A stream can still contain an error after its HTTP status has opened.

Reasoning-capable models accept reasoning_effort values supported by their catalog entry. temperature and top_p are forwarded only when the selected model supports them. The service caps output and concurrency to the active plan or wallet budget.

Models and capabilities

GET /v1/models is public and returns the approved catalog:

{  "object": "list",  "data": [    {      "id": "REPLACE_WITH_APPROVED_MODEL_ID",      "object": "model",      "context_window": 128000,      "max_output_tokens": 16384,      "pricing": {        "input_per_1m_usd": 0.0,        "cached_input_per_1m_usd": 0.0,        "output_per_1m_usd": 0.0      },      "capabilities": {        "streaming": true,        "tool_calling": true,        "reasoning": true,        "temperature": true,        "caching": true      }    }  ]}

Rates in the catalog are USD per one million tokens. Missing capabilities are not a promise of support. Access is confirmed when a model is activated for an account.

Tool calling

Declare standard JSON-schema functions in tools. The model returns a tool_calls finish reason and each call has an ID. Your application executes the permitted action and sends a matching tool message:

{  "model": "REPLACE_WITH_APPROVED_MODEL_ID",  "messages": [    {"role": "user", "content": "Find order 4815."}  ],  "tools": [    {      "type": "function",      "function": {        "name": "lookup_order",        "description": "Look up an order the signed-in user may access.",        "parameters": {          "type": "object",          "properties": {"order_id": {"type": "string"}},          "required": ["order_id"],          "additionalProperties": false        }      }    }  ],  "tool_choice": "auto"}

Tool results must retain the tool_call_id returned by the model:

{"role":"tool","tool_call_id":"call_example","content":"{\\"status\\":\\"shipped\\"}"}

Code search tool

POST /v1/tools/codesearch is a planned paid tool route. It requires a query and accepts optional language, repository, result count, file, pattern type, and symbol filters.

curl "$PALEPALE_BASE_URL/tools/codesearch" \  -H "Authorization: Bearer $PALEPALE_API_KEY" \  -H "Content-Type: application/json" \  -d '{"query":"retry with exponential backoff","lang":"typescript","repo":"YOUR_REPO","count":10}'

The response includes query, results, and truncated. A result may contain repo, path, line, url, and snippet; symbol results also include kind, name, and line. Search requests follow the active token and rate limits.

Account, balance, and usage

These authenticated routes are planned for the account service:

GET /api/meGET /api/me/usage?days=30GET /api/me/usage/log?page=1&sort=ts&dir=desc&days=30GET /api/me/paymentsGET /api/me/keysGET /api/me/subscriptionPOST /api/me/balance-fallbackPOST /api/me/keys/{ref}/revokePOST /api/me/subscription/cancelPOST /api/me/billing-portalPOST /api/me/delete

Disable or enable wallet fallback for a plan request with:

curl -X POST "$PALEPALE_API_URL/api/me/balance-fallback" \  -H "Authorization: Bearer $PALEPALE_API_KEY" \  -H "Content-Type: application/json" \  -d '{"on":false}'

GET /api/me/usage returns days, model totals, and a daily series. Each model total contains requests, prompt_tokens, completion_tokens, cached_tokens, and spent_usd. The log endpoint is paginated and returns whole-window totals. Payment history returns entries such as at, usd, and kind.

GET /v1/account, GET /v1/devices, GET /v1/usage, and GET /v1/usage/{request} remain the compact gateway views for an activated device. Lists use a next_before cursor and only expose records owned by that account.

Plans, passes, and subscriptions

GET /api/plans is public and returns the plan catalog. A plan has id, label, tagline, price_usd, days, concurrency, scope, features, and an optional badge.

curl "$PALEPALE_API_URL/api/plans"curl -X POST "$PALEPALE_API_URL/api/plans/PLAN_ID/buy" \  -H "Authorization: Bearer $PALEPALE_API_KEY"

Buying a plan spends the account wallet and returns ok and a pass_id, or a typed 402 error when the wallet is insufficient. GET /api/me/subscription returns a subscription or null; POST /api/me/subscription/cancel stops renewal while keeping the current term active. POST /api/me/billing-portal returns a hosted billing URL when billing is enabled.

Plans, passes, and wallet balance are separate from per-million-token rates. A plan allowance is used first for requests in its scope; wallet fallback can be disabled with the route above. Confirm allowance, model access, expiry, and renewal with the Palepale team before activation.

Signup, funding, and checkout

The following account flow is planned. It is shown so client developers can prepare integrations; the website does not currently create accounts or accept payment.

1. Request a proof-of-work challenge:

curl "$PALEPALE_CHAT_URL/api/pow?kind=signup"

2. Find a nonce where sha256("<challenge>:<nonce>") has the requested leading zero bits, then submit it:

curl -X POST "$PALEPALE_CHAT_URL/api/signup" \  -H "Content-Type: application/json" \  -H "X-Pow: CHALLENGE.NONCE" \  -d '{"email":"you@example.com"}'

The planned response contains account_number, formatted, and api_base; the initial secret is shown once. Challenges expire and a 428 pow_required response includes a fresh challenge.

3. Read accepted funding rails and limits:

GET /api/fundingGET /checkout?usd=25GET /checkout?plan=PLAN_ID&renew=1

GET /api/funding returns min_usd, max_usd, pay_with, and rails. An authenticated checkout returns JSON with checkout_url or redirects to the hosted page. After payment, the wallet is credited and can be checked through GET /api/me or GET /api/me/usage; client code should not assume a payment is complete until the balance changes.

Pairing and device keys

Desktop clients can request a short-lived pairing code instead of handling an account key directly:

curl -X POST "$PALEPALE_API_URL/api/pair/start" \  -H "Content-Type: application/json" \  -d '{"hostname":"YOUR_DEVICE_NAME"}'curl "$PALEPALE_API_URL/api/pair/DEVICE_CODE"

POST /api/pair/start returns device_code, user_code, and a short TTL. Polling returns 202 while pending, 200 once with the device key, and 410 after expiry. An authenticated browser approves with:

curl -X POST "$PALEPALE_CHAT_URL/api/pair/approve" \  -H "Content-Type: application/json" \  -d '{"user_code":"ABCD-EFGH","approve":true}'

The key list contains a reference, name, hint, creation time, and current-key flag. Revoke another key with POST /api/me/keys/{ref}/revoke; revoking the current key returns 409 cannot_revoke_current so a replacement can be installed first. Account deletion is irreversible and requires the account number plus an explicit active-subscription check.

Chat helpers and live events

The planned chat origin provides browser-oriented aliases:

GET /api/modelsPOST /api/chatPOST /api/tools/codesearchPOST /api/tools/generate_imageGET /api/live?topics=tokensGET /api/live/tokensGET /pairPOST /pair

/api/chat uses the same message and tool shapes as /v1/chat/completions. Live routes use Server-Sent Events and may send heartbeat comments; reconnect with backoff. Image generation and browser chat require the account's proof-of-work challenge when the service asks for X-Pow.

Utility and integration routes

These public or service routes are reserved for the planned release:

GET /healthzGET /install.shGET /install.ps1GET /llms.txtGET /llms-full.txtGET /docsGET /docs/{name}GET /docs/{name}.mdGET /docs/opencode.jsonGET /docs/opencode-plugin.jsGET /paidGET /privacyGET /termsGET /acceptable-useGET /refundsGET /whyGET /impressumGET /GET /chatPOST /webhooks/paymentPOST /webhooks/stripe

Webhook handlers verify their signature before crediting an account. Installer and OpenCode URLs will be published only when the corresponding release is available. Do not hard-code a private gateway URL into an app distributed to customers.

Error envelopes and retries

JSON errors use one stable envelope:

{  "error": {    "type": "invalid_api_key",    "message": "The device credential is invalid or expired."  }}

Common types include bad_request, bad_amount, bad_ref, number_mismatch, cannot_renew, rail_not_accepted, invalid_api_key, account_disabled, insufficient_balance, plan_allowance_spent, model_not_found, not_found, no_such_plan, no_subscription, no_customer, cannot_revoke_current, subscription_active, pair_expired, body_too_large, pow_required, rate_limited, tool_error, checkout_failed, cancel_failed, portal_failed, live_full, live_warming, tool_unavailable, checkout_unconfigured, no_model, no_provider, no_price, price_fault, and upstream_unavailable. The service returns Retry-After for rate limits and X-Request-Id on model responses. Streaming errors are sent as an SSE error event followed by data: [DONE].

Do not retry a request automatically after output has arrived: the billing result may be uncertain. Retry idempotent reads with backoff, use a fresh proof-of-work challenge after 428, and contact Palepale on Discord with the request ID when an activation or payment needs review.

Current activation

Until the planned account and billing routes ship, access is activated by the Palepale team. Request API access, confirm the live model catalog and allowance, then use the quickstart or OpenCode setup.

Need a hand?

Open Palepale Discord for activation or account support. Compare API offers or choose a plan.