Jatater AI integration guide
Quick start
Project: your-project
Base endpoint: https://your-project.jatater.ai/api/development
Sign in, enter your project name, then open Docs → Copy for agent. Paste the result into your coding agent. The workspace fills in the development endpoint and key. New projects use the configured trial provider for chat. Additional services can be enabled in AI configuration.
Sign up with a verified email, Google, or GitHub at https://account.jatater.ai/dashboard/. Each new account gets one workspace (tenant), its first project, and $0.50 of testing credit. Request additional projects with a reason and the desired services; request more testing credit from Workspace & credit. Each project can have five environments, independently of other projects in the workspace. Development and Production count toward this limit and cannot be deleted individually. Workspace owners and platform administrators can permanently delete a complete project in Project settings; workspace usage and credit records remain for billing.
Each project has its dashboard at https://your-project.jatater.ai/dashboard/ and its API at https://your-project.jatater.ai/api/ENVIRONMENT. Each environment runs in its own Workers for Platforms Worker. Jatater’s separate service-development deployment uses account-dev.jatater.ai and your-project--dev.jatater.ai; its users, keys, configurations, credits and usage are separate from production. All service-development hosts require Cloudflare Access and the platform administrator identity; public Google login cannot bypass this. Customers can still use their own development project environment inside the production service.
-
Store the development key supplied by Copy for agent in a local, ignored environment file as
JATATER_DEVELOPMENT_KEY. You can also create a key in Access & keys and choose it in Docs. Keep it out of source control and shipped clients. -
Exchange it for an AI token:
POST https://your-project.jatater.ai/api/development/auth/key
Authorization: Bearer jat_YOUR_DEVELOPMENT_KEY
- Send the returned
tokenas the Bearer token to the AI endpoints. Renew it before the returned expiry (ten minutes by default). Never put provider secrets in a client build.
const base = "https://your-project.jatater.ai/api/development";
const localDevelopmentKey = process.env.JATATER_DEVELOPMENT_KEY;
const grant = await fetch(`${base}/auth/key`, {
method: "POST",
headers: { Authorization: `Bearer ${localDevelopmentKey}` },
}).then((r) => {
if (!r.ok) throw new Error("Authentication failed");
return r.json();
});
const response = await fetch(`${base}/v1/chat/completions`, {
method: "POST",
headers: {
Authorization: `Bearer ${grant.token}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "generic",
messages: [{ role: "user", content: "Hello!" }],
}),
});
if (!response.ok) throw new Error(await response.text());
const completion = await response.json();
OpenAI-compatible clients can use ${base}/v1 as their base URL and the short-lived AI token as their API key. Use a prompt ID, such as generic, as the model alias. Refresh authentication in your client; do not send the long-lived development/scoped key directly to AI endpoints.
Unity
For the phone call sample, open Docs → Unity package releases. Follow the release instructions to import the package or open the example project. In the development environment, open Access & keys and copy the Unity starter scoped key. New workspaces receive $0.50 of testing credit. The starter key has its own $0.50 lifetime spending cap. Use the development API endpoint, set the conversation prompt to Client controlled, and publish it so the character's personality can come from the sample. For a shipped Steam build, set the Steam app ID and publisher key in Project settings and switch the Unity client to Steam ticket authentication.
The package setup instructions cover local Whisper transcription, Pocket TTS playback, and supplying microphone audio from an existing voice chat pipeline. Request another player authentication provider through Request a feature. Download the Unity SDK package · Download the complete Unity example project
Authentication
Steam (default): use Steam's GetAuthTicketForWebApi with identity jatater. Send { "ticket": "HEX_TICKET" } to POST /auth/steam. Jatater checks the ticket, app ownership, and the project's ban list. The response contains a session JWT (six hours by default). Send that session JWT to POST /auth/ai-token to obtain an AI JWT (ten minutes by default). Renewing AI access checks bans again; the AI token cannot outlive the session. Steam app IDs and publisher keys are configured per project.
Development: POST /auth/key accepts a locally stored development key only in that project's development environment. It does not need a Steam app ID. Authentication remains required even when configuration restrictions are off.
Scoped API keys are for testing. The workspace owner enables them per environment in Access & keys. Exchange a key through /auth/key. Select a spending limit and a reset period. A lifetime limit applies across the key's life. Daily limits reset at 00:00 UTC and monthly limits reset at 00:00 UTC on the first day of the month. The same key shares its allowance across all environments where it is published. Estimated spending is checked when issuing AI tokens. Scopes include llm:generic, stt, tts, voice, and feedback. Use * to allow all configured services.
For a browser demo, add its exact origin under Project settings → Browser clients and publish it to the environment. HTTPS origins and HTTP on localhost are supported. A browser key can be copied from the page and reused elsewhere. Give a test demo a small recurring budget and narrow scopes. For a production game, authenticate each player and disable scoped keys.
Tokens are bound to the project, project environment, Jatater service environment, and token kind. A session token cannot call AI endpoints. A development token cannot call production. A ban, key revocation, disabled API-key setting, or spending cutoff stops renewal; an already issued AI token remains usable until its configured expiry (up to 60 minutes).
Project settings configure authentication.aiTokenMinutes (integer 1–60, default 10) and authentication.sessionHours (integer 1–24, default 6) for each published environment configuration. Changes apply to newly issued tokens; existing tokens keep their original expiry.
LLM
POST /v1/chat/completions accepts OpenAI-style messages. Select a prompt with prompt_id (the legacy conversation_type alias remains supported), or use its ID as model. If omitted, generic is selected when configured. Unknown explicit prompt IDs are rejected.
{
"prompt_id": "customer-dialogue",
"messages": [
{ "role": "system", "content": "The customer is asking about a refund." },
{ "role": "user", "content": "Can you help me?" }
],
"max_tokens": 512,
"stream": true
}
Prompt modes:
-
Client controlled: forward client system instructions. An untrusted client can replace or append instructions; use Locked when the server must control the prompt.
-
Prefix + append: combine the server prefix with all client system/developer instructions, in that order.
-
Locked: remove client system/developer instructions and send only the server-owned system prompt.
In enforced mode, Jatater pins the model, clamps output tokens, checks a conservative input-token upper bound, and applies the output format. Supported production messages are text system, developer, user, and assistant messages. Additional message fields, tool calls, image inputs, and unrecognized top-level parameters are rejected. Input bounds count UTF-8 bytes with overhead; they may reject before a provider's exact tokenizer would. They are not billed token counts.
Supported production options: stream, temperature, top_p, presence_penalty, frequency_penalty, stop, seed, max_tokens, max_completion_tokens, response_format, stream_options, and n: 1. JSON schema and JSON object settings override client format requests. Provider support for structured output still matters; streamed JSON is not buffered for output validation.
Development passthrough forwards the client's JSON parameters and model, apart from Jatater's prompt_id / conversation_type fields and streaming usage collection. Request size, authentication, provider selection, and the platform rate limit still apply. The declared prompt must exist. Shared platform keys still enforce the administrator’s model allowlist and output ceiling. Passthrough allows untrusted clients to control most request parameters; keep it for trusted development only. This mode cannot be published to other environments.
Streaming responses preserve SSE and are forwarded incrementally. No conversation history is stored: send the conversation history on each request. System-prompt control prevents client field overrides; it is not a guarantee against prompt injection in natural-language messages.
New configurations default to enforced mode with a locked system prompt. You may delete Generic, including the final prompt. An empty prompt list disables LLM requests until you add and publish a prompt; no hidden generic fallback is created. Prompt rules help constrain requests but are not an authorization boundary.
Prompt tools
Prompt fields show an approximate token estimate based on UTF-8 length, not a model tokenizer. Send test request exchanges the Jatater API/development key you enter and uses the same published configuration, permissions, provider, model allowlist, credit checks and usage recording as normal requests. Publish edits first. Test requests consume usage normally. The result shows actual provider-reported input, cached-input and output tokens when returned. The key is not saved in browser storage.
AI Rewrite proposes a replacement system prompt for you to review and apply. It is unavailable until the platform administrator supplies a shared provider key and enables the feature in Platform settings. The default model is DeepSeek V4.1 Flash; the provider, model, rewrite instructions, output ceiling and hourly allowance are configurable per feature. Its atomic hourly limit is shared by every project and member of a workspace (default 20). Failed attempts also consume allowance. Rewrites are sponsored platform operations and do not deduct workspace credits.
Speech to text
POST /v1/audio/transcriptions accepts either an audio/wav body or multipart form data with a file field. The model comes from the published configuration. This initial transport supports PCM16 WAV, one or two channels, at 8–48 kHz. Both actual upload bytes and parsed audio duration are checked on the server. Clients cannot bypass limits by reporting a shorter duration.
For a complete WAV, the response includes text. Set ?language=en (or another supported call language) on the request when known. Inworld uses a language hint to bias recognition. Background sounds can still produce unexpected text or languages. Test quiet speech, keyboard and desk noise, and natural pauses in the languages your players use.
Live Inworld transcription
Enable speech transcription on the environment, select an Inworld credential and publish. Exchange a Steam or scoped credential for a short-lived AI token with the stt scope. Open wss://your-project.jatater.ai/api/ENVIRONMENT/v1/audio/transcriptions/stream on the same project and environment as the token. Native clients use an Authorization: Bearer header. Browser clients can use WebSocket subprotocols:
const url = new URL(base + "/v1/audio/transcriptions/stream");
url.protocol = "wss:";
url.searchParams.set("language", "en");
const socket = new WebSocket(url, ["jatater.stt.v1", "bearer." + grant.token]);
Once open, send signed little-endian PCM16, mono, resampled to 16 kHz. For instance, 100 ms contains 1,600 samples, or 3,200 bytes. Flush the final partial frame on release. A game using Meta Voice Chat, Dissonance or Vivox should read the existing local microphone capture stream and feed copies of its samples to transcription. The voice chat system retains ownership of recording. Keep provider credentials on the server. Inworld audio formats
In Dissonance, subscribe with DissonanceComms.SubscribeToRecordedAudio. In Vivox, use a Capture Source tap. For Meta Voice Chat, take the local input before network encoding so remote players and the character's playback stay out of transcription. Meta Voice Chat · Dissonance recorded audio · Vivox capture taps
| Capture mode | When the player stops speaking |
| --- | --- |
| Push-to-talk, one socket per utterance | After the last frame, send {"closeStream":{}} once. Keep reading until done or an error. |
| Push-to-talk with a reused socket | Send {"endTurn":{}} on release and leave the socket open. When shutting down with pending audio, send just closeStream for the final turn. |
| Hands-free | Send silence frames while the microphone is open so Inworld can measure pauses. Accept a server-finalized turn immediately. If speech has stopped and the server has yet to finalize the turn, start with a client silence fallback of 800–1,000 ms and tune it with players who pause mid-sentence. |
The worker sets the values recommended by Inworld's speech team for game conversations:
{
"endOfTurnConfidenceThreshold": 0.4,
"inworldSttV1Config": {
"vadThreshold": 0.35,
"minEndOfTurnSilenceWhenConfident": 300,
"maxTurnSilence": 800
}
}
Each {"type":"transcript","text":"…","isFinal":false} replaces the current preview. On isFinal:true, clear the preview and submit the final text to the LLM once if it contains speech. speechStarted and speechStopped describe microphone activity. A done event with no final words completes a silent turn. An error event includes a code; if the socket closes unexpectedly, discard any unfinished preview. Each socket shares the environment's audio byte and duration limits and expires with its AI token. Open a new session between turns as needed. Inworld STT best practices · Inworld WebSocket protocol
Text to speech
Pocket TTS plays responses locally. To use cloud synthesis, open AI configuration → Text to speech, enable Inworld, choose the credential, model ID, and voice ID, then publish. An Inworld provider key can carry a contracted price per million characters. The provider charges a workspace-owned Inworld key directly. For an authorized platform-funded key, the workspace pays the configured synthesis cost without an AI markup. An enabled infrastructure estimate also applies.
Send POST https://your-project.jatater.ai/api/development/v1/audio/speech with the AI bearer token, Content-Type: application/json, and {"text":"Hello there!"}. The environment supplies the voice and model. An optional voiceId overrides the default voice. The endpoint returns a WAV file. A scoped test key needs the tts scope. Inworld TTS
Voice reference designer
POST https://your-project.jatater.ai/api/development/v1/voice/design
Authorization: Bearer AI_TOKEN
Content-Type: application/json
{"description":"A warm older voice, slightly gravelly, calm and measured, with clear American pronunciation."}
An Inworld key with Voices Write permission is required for new generations. Supply one English name or voice description in description, up to 1,000 characters (or the environment's lower configured limit). For example, Donald Trump or An older female courtroom judge with a firm New York American accent, a low slightly raspy voice, crisp consonants, measured pace, dry impatience and commanding authority. Jatater passes that input directly to Inworld's designPrompt with designPromptMode: "DESIGN_PROMPT_MODE_ASSISTED", the configured reference script and language, and one requested sample. There is no separate character-name field or extra LLM request. See Inworld's voice design best practices and Design Voice API.
Generated samples return previewVoices[0].downloadUrl, a five-minute signed link to binary audio in private R2 storage. Request the design again for a fresh link. Custom overrides return base64 previewAudio instead. All audio is mono PCM16 WAV at 24 kHz for Pocket TTS. Each sample includes voiceId and a SHA-256 checksum of the WAV bytes; reuse an existing runtime reference when both match. Voice designs are not published to the Inworld voice library.
The generated cache is on by default and isolated by project and environment. Its identity is only the normalized input: Unicode NFKC normalization, lowercase, then removal of everything except letters and numbers. Donald Trump, Donald trump, donald_trump and Donald-Trump all match. Matching is exact after normalization, not semantic or approximate: Trump does not match Donald Trump, and changing words in a description creates another identity. Changing the reference script or language retains the existing sample until you explicitly regenerate or delete it. A database uniqueness constraint and generation lease prevent simultaneous requests from creating duplicates.
D1 stores searchable metadata and the R2 object key, never generated audio. The dashboard's Generated voice cache starts collapsed, queries D1, and displays ten records per page. It supports listening, Download WAV, individual deletion and bulk selection/deletion. Details shows the original request settings and provider response without audio, including any additional fields Inworld returns. Metadata is limited to 32 KB; oversized provider metadata is explicitly marked as omitted. Inworld's documented response does not include its internally expanded assisted design prompt, so Jatater does not invent one. Regenerate voice explicitly removes the matching cached sample and generates another using the published settings; download the old sample first if you want to keep it.
Deletion marks metadata first, deletes R2 audio, then removes metadata. Interrupted operations retain a retryable record. Scheduled reconciliation removes orphaned objects or metadata in bounded batches, so direct Cloudflare deletions converge as well. If caching is disabled, download objects are temporary and the transient/ R2 lifecycle rule removes them after one day.
Custom voice.overrides take priority even when caching is disabled. Their name and optional aliases use exactly the same normalization as the cache. Download a cached WAV, upload it as an override, and use the game's name or description as its name or an alias. Overrides contain a stable UUID id, checksum, and base64 previewAudio; they are included in configuration exports and excluded from the generated cache. Uploading a WAV normalizes it for Pocket TTS. Imports validate WAV format, size, duration, unique names/IDs and the checksum before accepting changes. Old configurations receive deterministic IDs and checksums during migration. Keep the ID when editing an override, and recompute the checksum if its audio changes.
The default script targets 10–15 seconds. Inworld's design API controls the final duration and permits 1–30 seconds; this service does not promise an exact clip duration or retry generation automatically. Adjust the reference script for your desired speaking speed.
Feedback
Send a JSON report to POST https://your-project.jatater.ai/api/development/v1/feedback with the AI bearer token and Content-Type: application/json. This works from any HTTP client. Steam and development grants normally include all scopes. A scoped key needs feedback or *. Treat a shared backend key as one reporter.
const report = {
id: crypto.randomUUID(),
kind: "bug",
description: "The voice preview stopped playing.",
platform: "web",
version: "1.0.2"
};
await fetch(base + "/v1/feedback", {
method: "POST",
headers: { Authorization: `Bearer ${grant.token}`, "Content-Type": "application/json" },
body: JSON.stringify(report)
});
Use bug or feedback and a description of up to 10,000 characters. Retry the same report with its original UUID. A new report returns 201, a repeat returns 200, disabled intake returns 403, and the limit of 20 new reports per authenticated identity per UTC day returns 429. Optional fields include version, platform, diagnostics (up to 32,768 characters) and attachments (up to three files, each up to 1 MiB). Each file has name, MIME type and base64 data. Supported formats are PNG, JPEG, WebP, MP4 and WebM. Include user-selected files and omit secrets from diagnostics.
In Feedback, filter by status and type, sort reports, download attachments, export the filtered reports as JSON, or dismiss and reopen reports individually or in batches. Exports include diagnostics and file metadata. Turn off Accept user feedback to close intake.
Abuse and alerts
Bans lists project-wide manual account bans with their authentication type, account ID, reason, author, and time. Select an environment to inspect active automatic blocks, the requests and spend that triggered them, and their expiry. Editors can remove a manual ban or release a temporary block here.
Abuse counts verified identities in five-minute windows within this environment. Set the scan interval, request and estimated-cost thresholds for review, automatic request threshold for blocking, and block duration. Run a scan for immediate review or release a block. A temporary block returns HTTP 429 with temporarily_blocked, including for an already-issued AI token.
Alerts lets workspace members subscribe their signed-in email address or their current browser. Editors can enable individual channels and choose unusual request volume, an automatic block or a new bug report as triggers. The cooldown applies separately to each trigger. Subscribers can unsubscribe in Alerts at any time. Urgent email comes from [email protected].
Configuration
Every project starts with permanent development and production environments. Editors can create and delete additional named environments. Jatater itself has separate development and production deployments; these are independent of project environments.
Export downloads one environment-neutral JSON configuration. It includes model choices, prompt definitions, limits, response schemas, provider priority and definitions, encrypted project-owned provider keys, public scoped API keys, speech settings, and voice settings with custom references. Generated caches are excluded. Development tokens, memberships and project-level Steam authentication remain managed separately.
Exports use integer schemaVersion: 4 with a prompts array. Imports also accept versions 2 and 3 and version 1 files with conversations; unknown future versions are rejected. The internal API retains its old field for compatibility.
scopedApiKeys contains each public client key's stable id, name, raw value, scopes, budgetUsd and optional resetPeriod (defaults to lifetime). Publishing that configuration in another environment of the same project enables the same key there. All environments share the same spending allowance for its current budget period. Imports preserve the allowance. Once an owner disables scoped keys, enable them explicitly in Access & keys to restore access. Existing keys must retain their ID, value, scopes and budget. Revoked keys cannot be reactivated by importing an old file. Removing a key from a version 4 configuration removes access to that environment; revoking the key stops new tokens in every environment. Version 1–3 imports preserve the destination's existing scoped keys. Legacy keys stored only as hashes cannot be recovered for export; create a replacement. Development tokens remain private and are not exported. Limits are checked on token renewal using delayed usage accounting, so they are not an instantaneous hard cutoff.
Import validates the complete file in the backend, then loads it into the selected environment for review. Non-development environments use enforced mode. Publish after reviewing. Owned provider definitions include apiKey: "jatater-key:v1:..."; a random workspace encryption key is generated once, encrypted with the backend master key and never sent to the browser. The encrypted provider value authenticates its workspace, provider and destination host, and works across environments and projects in the same workspace. Shared platform keys remain access-checked references. Imports reuse unchanged credentials; changed definitions create a separate key rather than rotating a key used by another environment.
To import a raw provider key, replace that provider's apiKey string with the raw secret, retaining its provider, baseUrl, label and pricing. The backend encrypts it before storage and never returns the raw value. Treat any file containing raw keys as a secret. Tampered ciphertext, a different workspace, invalid schemas and mismatched voice checksums fail before any provider key is stored.
For an AI agent workflow, export the configuration, edit its prompts and limits, then import it into the intended environment, review, test and publish. Keep the exported encrypted credentials intact. Never include dashboard session cookies or backend encryption keys.
Every publish creates an immutable configuration revision. You can add optional release notes describing the intent of a publish. Version history displays notes and configuration downloads. Compare & copy versions compares any environment or historical version using red removals and green additions. Select a source version and the current destination to preview and publish a copy with an optional note. The source is immutable; copying creates a new destination version, enforces restrictions outside Development, and rejects a destination changed since the preview. Scoped key values are masked and audio is compared by checksum. AI tokens select a revision at issuance, and the proxy fetches that revision from KV with a 30-second edge cache. Existing tokens continue on their previous revision until their configured expiry (up to 60 minutes). This avoids races between configuration changes and in-flight conversations. Restore creates a new revision from history; it does not erase history. Concurrent edits use an expected revision and reject stale saves.
Provider secrets are encrypted in D1. Each environment gets a derived encryption key and AI signing key. Its entire KV snapshot, including prompts and provider credentials, is encrypted with that environment’s key. Workers receive only their own keys, a KV binding, telemetry, a rate limiter and the private authentication service; they have no D1 binding. They cannot decrypt other environments’ snapshots. Secrets are never returned to the dashboard, even to administrators. Provider credential changes take effect through republished snapshots; old tokens/revisions can retain their previous credential until their configured expiry (up to 60 minutes). Rotate a leaked provider key at the provider for an immediate external cutoff. Export is not a secret backup.
Rates and accounting
Use Project settings → Project usage pricing to see the current USD input, cached input, and output rates per million tokens for platform-funded models. In the platform's shared key vault, an administrator configures the Isoquant credential and model for new projects. Workspace-owned credentials can use separate providers and negotiated rates. Previously configured project routes continue to use their chosen provider.
Platform settings → Default usage pricing sets the percentage markup on platform-funded model usage. A 20% markup turns $1.00 of provider cost into $1.20 of usage charged. A platform administrator can set a project-specific override in Project settings. An explicit 0% override waives the markup. The platform can optionally include a Cloudflare cost estimate in USD per million service requests. Customer charges, provider cost, markup and the infrastructure estimate are available in usage exports.
Total input includes the cached subset. The charge is (input - cached) × input rate + cached × cached rate + output × output rate, divided by one million. Requests retain fractional microdollars until the cumulative sampled hourly amount is rounded for settlement. Inworld charges always use the configured contract rates; its token usage does not provide a dependable per-request negotiated dollar price. Other providers may supply usage.cost; otherwise configured rates apply. Speech uses the configured per-hour price, and voice design uses the per-request price. Missing or invalid token counts use conservative bounds and are marked estimated. Interrupted calls can also be estimated.
Shared vault keys can be made available to all projects. The selected Default shared provider is used when the project's provider priority is empty. Provider secrets remain server-only. Platform model prices override shared LLM key prices. Models and prices are snapshotted at publication, so edits do not reprice historical usage; existing tokens can retain their old snapshot until its configured expiry (up to 60 minutes).
Credits and invoicing
Workspace owners can add USD credits from Billing. A $5 purchase adds exactly $5 of credit. Stripe Checkout displays the applicable sales tax separately. Historical orders include their total, tax, status and Stripe invoice links. Owners can page through their workspace ledger and export the loaded entries. Platform administrators can view purchases across workspaces.
Automatic top-up is optional. Choose a balance threshold, a reload amount and a monthly cap, authorize off-session payments, then finish payment-method setup in Stripe. The first top-up can occur immediately if the balance is already low. Later top-ups require the balance to recover above the threshold and cross it again. The cap applies to credit principal in each UTC calendar month. Applicable tax is additional. Declines and authentication requests pause automatic payments. The invoice link lets the customer finish payment. Owners can disable future reloads under Billing.
Platform administrators can grant postpay after the workspace has an email and a Stripe billing address. Customers can enter their address under Manage billing details. The account worker invoices outstanding usage from closed UTC calendar months, deducting previous invoices and available credits. It carries fractional cents and balances below $0.50 forward. Postpay invoices are due in 30 days.
The central account worker owns payments, signed webhooks, billing settings and financial records. Customer workers emit usage measurements. A D1 transaction records each payment or reversal once and updates the workspace balance. The ledger stores signed integer USD microdollars. Orders store cents. Refunds and disputes adjust only the associated credit principal and preserve history. Accounting records have no automatic expiry.
Statistical usage billing
Jatater follows Cloudflare's SaaS billing recipe. Analytics Engine indexes points by workspace. A scheduled job queries one workspace at a time, weights quantities and costs by _sample_interval, and persists hourly dimensions in D1. Recent estimates support admission and top-up decisions. A closed hour's sampled result is reconciled after an hour of ingestion time, including downward adjustments. Existing AI tokens and the reporting delay can permit a temporary negative prepaid balance. New funded sessions and capped keys require accounting refreshed in the previous five minutes. The accounting job runs every minute.
Each point identifies the project, environment, credential, provider, model, configuration revision, pricing revision, funding source and scoped key. Dashboards export input, cached-input and output tokens, speech hours, voice designs, estimated and unpriced request counts, TTS character counts, provider cost, customer charge, markup and Cloudflare estimates. The original metrics retain their positions. Doubles 13–17 hold observability events, observability bytes, TTS characters, estimated Cloudflare cost and markup. Provider and customer charges stay separate for bring-your-own-key workspaces. The request path sends no per-request billing writes to D1.
Usage reports use UTC hour boundaries and can cover up to 93 days per query. Workspace owners can filter by project or environment. Permanent billing history and hourly usage survive deletion of a project and expiration of Analytics Engine's three-month event retention period. Prompt contents and payment credentials are excluded from billing points.
Cloudflare statistical billing · Analytics Engine retention · Stripe off-session consent · Automatic invoice tax
Observability
Observability is off by default. A workspace owner or platform administrator can enable it per project. Each request type has an enable checkbox and its own probability from 0 to 1 (1 means every request). Authentication types are enabled by default. Types include Steam authentication, API-key authentication, AI-token renewal, LLM, speech transcription, voice design, voice reference download and other requests. There is no global sampling control.
Settings redeploy every environment Worker; the dashboard shows propagation status and failed updates are retried. Worker-wide sampling stays at 100%, automatic invocation logs and traces are disabled, and the application selects requests before capturing anything. Disabled projects and disabled or unsampled types emit no application request log or observability billing event. A sampled request emits one structured completion, failure or cancellation event, including streamed responses.
Cloudflare Workers Logs stores those events. The dashboard reads only the authorized project's logs and offers a colored expandable JSON view, input/output, duration, status and sender. Sender identity supports a provider/type plus optional subject, key ID and Steam app ID; no additional authentication providers are implemented. Tokens, keys and Steam tickets are redacted. JSON input/output capture is bounded to 32 KiB per side, with truncated/invalid payloads marked; audio is represented by metadata, not recorded bytes. Text fields and deeply nested data are bounded too. Log availability follows Cloudflare retention (up to seven days on the paid plan). Turning logging off stops new capture after settings propagate; retained logs expire normally.
One Analytics Engine event is emitted for each recorded request, indexed by workspace, carrying the event count and encoded size without the payload. There is no per-request D1 counter. Cloudflare's weighted count is rolled up with normal accounting so monthly billing survives log expiry and project deletion. These events do not inflate the AI request count. The free allowance is 100,000 recorded events per workspace per UTC calendar month, shared across projects. The initial overage price is $0 per million events. Administrators configure the allowance in thousands and the price per million in Platform settings. Current-month overage uses the configured price; already posted charges are never reversed by a replay. Counts reflect Analytics Engine sampling and ingestion delay.
API routes under /dashboard/admin: GET/PUT /projects/:project/observability, GET /projects/:project/observability/logs?from=MILLISECONDS&to=MILLISECONDS (optional environment, type, cursor), and GET/PUT /observability/pricing. Settings updates require expectedRevision; pricing writes require platform administration. The admin Worker needs a secret OBSERVABILITY_TOKEN with Cloudflare's Workers Observability Write permission, which Cloudflare requires for telemetry queries. No token is exposed to dashboard clients.
Status
status.jatater.ai uses the UptimeFlare monitoring engine and a Jatater-branded interface. It checks the public site, dashboard dependencies and API router every minute, with 24-hour/7-day/30-day uptime, 90-day daily history, response times and incident periods. Statistics start at the first actual observation; missing or stale monitoring is shown as unknown. Checks do not call paid AI providers and therefore do not establish availability of every upstream model.
Chat fallback priorities
In Provider keys → Regional chat routing, add a rule for the two-letter country codes and requested model. Choose the primary key and its actual upstream model ID. Add up to two optional fallbacks. For example, set CN to use a DeepSeek Direct key and model, with no cross-provider fallback. Publish the environment. Requests from a configured country must match an allowed model for that country. The dispatcher supplies the country and a matching rule stays within its listed destinations.
In Platform settings, an administrator can choose up to three globally shared keys and their upstream model IDs for a requested model. In Workspace & credit, the owner can set a workspace-wide BYOK route using keys owned by projects in that workspace. For requests outside a regional rule, a matching workspace route takes precedence. Projects with their own keys otherwise follow the published project order. Platform routes apply to projects using shared keys. Each attempt checks model access, pricing and credit. Usage records the serving key and actual model.
Three slow starts or transient failures among the latest six observations in a 45-second window open the provider circuit. A request counts as slow after six seconds without usable output. Streaming calls must return a meaningful event. Non-streaming calls must return a complete reply. With another destination in the priority list, the gateway can switch after eight seconds, before sending output to the client. The request has a 60-second deadline and a three-attempt limit. Rate limits cool down the individual key. Standard provider endpoints share health across projects. Custom BYOK endpoints share health within their workspace.
While open, a Durable Object runs a one-token test completion about every 20 seconds using the affected key. Two fast, successful probes restore traffic. Probes contain a fixed test prompt and can incur a small upstream charge. A stream stays with its serving provider once output reaches the client.
GET, PUT, and DELETE on /platform/fallbacks or /tenants/:tenant/fallbacks manage these routes. A PUT accepts {model, targets: [{credentialId, model}]} in priority order. A DELETE accepts {model}.
Dashboard API
All dashboard API routes use the /dashboard/admin prefix on the current dashboard host. The central admin.jatater.ai dashboard uses Cloudflare Access and is restricted to the configured platform administrator. Customer dashboards support single-use email codes, Google OIDC, and GitHub OAuth with a verified primary email. Both social sign-in flows use PKCE and state validation. All three methods issue host-bound HTTP-only sessions. Cross-host login handoffs are single-use and bound to the initiating browser. Customer sessions never grant platform administrator privileges, even if their email matches the administrator.
Workspace owners manage their projects and project memberships. Editors configure AI, provider keys and environments; viewers can inspect them. A project subdomain restricts every API request to that project. Owners manage production API-key enablement and scoped-key creation. Platform-only operations, such as shared vault grants and request approvals, belong on the central admin host.
Agents can import/export the JSON configuration, or call this API using the user's authenticated dashboard session. Central admin automation must also authenticate through Cloudflare Access. Supply X-Jatater-Client: agent and Content-Type: application/json for non-browser mutations. Never embed session cookies or provider secrets in config files or generated docs. A game client key cannot call the dashboard API. Routes below are relative to /dashboard/admin:
-
POST /onboardwith{name,projectId,projectName}creates the first workspace after sign-in. -
GET /tenants;POST /tenantswith{name,ownerEmail,projectId,projectName}is platform-admin only. -
GET /tenants/:tenant/requestslists project and credit requests for owners/admins. -
GET /project-id-availability?id=...checks live, retired and pending IDs. Submitting a request reserves the ID atomically. Declining releases a pending reservation. -
POST /tenants/:tenant/project-requestsaccepts{projectId,projectName,reason,services}. The optionalserviceslist records interest inllm,stt, orvoice. Projects can configure any available service. -
GET /project-requestslists pending project requests across workspaces for platform admins. Pass the returnednextvalue asafterto load the next page. -
POST /tenants/:tenant/credit-requestswith{amountUsd,reason}. -
POST /project-requests/:id/reviewor/credit-requests/:id/reviewwith{approve}is platform-admin only; credit approval can includeamountUsd. -
PUT /platform-settingswith{trialCredentialId}chooses the globally available default shared provider for projects without an explicit priority list. -
GET /me,GET /projects,POST /projectswith{id,name,tenantId}(platform-admin only). -
GET /projects/:project/environments;POSTwith{name};DELETE /projects/:project/environments/:environmentfor custom environments. -
GET /projects/:project/:environment/configreturns{revision,config}. -
PUT /projects/:project/:environment/configwith{config,expectedRevision,note}validates and publishes. -
GET /projects/:project/:environment/historylists the latest 100 revisions and notes;GET .../history/:revisiondownloads that revision’s internal configuration. -
POST /projects/:project/:environment/restorewith{revision,expectedRevision}. -
POST /projects/:project/:environment/retry-publishrepairs a pending KV publication. -
GET /projects/:project/providersreturns key metadata and rates, never secrets. -
POST /credentialsaccepts{name,provider,baseUrl?,secret,pricing,projectId,grants,globalAccess?}. Providers:isoquant,inworld,deepseek,openrouter,openai-compatible, orsteam. A null project ID creates an admin-owned shared key. Prices are{models:{MODEL:{inputPerMillion,outputPerMillion,cachedInputPerMillion?}},sttPerHour,voicePerRequest,ttsPerMillionCharacters?}; unavailable audio rates are null. -
GET /projects/:project/:environment/usage?from=UNIX_SECONDS&to=UNIX_SECONDSreturns usage quantities, provider cost, hourly dimensions, and freshness. The Usage page exports the same JSON. -
GET/POST /projects/:project/:environment/keys; create with{name,kind,scopes,budgetUsd,resetPeriod?}. Kinds aredevelopmentandapi-key. Development secrets are shown at creation. Owners can also copy a published scoped testing key in Access & keys.DELETE .../keys/:idrevokes it. -
PATCH /projects/:project/environments/:environmentwith{allowApiKeys:true}requires the workspace owner or platform administrator. -
GET/PUT /projects/:project/members; grant with{email,role}.DELETE .../members/:emailremoves access. -
GET/PUT /projects/:project/bansmanages manual bans. Send{accountType,subject,reason}and useDELETE .../bans/:subject?accountType=steamwith the matching type to remove a ban. -
GET/PUT /platform-modelsmanages the global priced model catalog (administrator only). -
GET/PUT /tenants/:tenant/modelsmanages additional workspace model grants (administrator only). -
PUT /tenants/:tenant/banaccepts{banned,reason}(administrator only); reason is required when banning. -
GET/PUT /assistant/settingsconfigures the assistant (administrator only). -
GET /projects/:project/assistantreports availability;POST .../assistant/rewriteaccepts{prompt,instructions?}. -
POST /projects/:project/:environment/testaccepts{apiKey,promptId,message}and uses the normal AI transport. -
GET /billing/historylists global purchases (administrator only);GET /tenants/:tenant/billingreturns workspace purchase/ledger history (owner/admin only). -
PUT /tenants/:tenant/billing/auto-topupaccepts{enabled,thresholdMicros,amountCents,monthlyLimitCents,consent?,requestId?}. Enabling requires affirmative consent and a new UUID per setup intent. Complete the returned Stripe setup URL. -
POST /tenants/:tenant/billing/portalopens billing details. Platform administrators can usePUT /tenants/:tenant/billing/modewith{"mode":"prepaid"}or{"mode":"postpay"}. -
GET/PUT /platform/settingsmanages platform usage pricing.GET /projects/:project/pricingreads project rates. A platform administrator can set{markupBps: number | null}withPUTon that project route. -
POST /tenants/:tenant/billing/checkoutstarts hosted Checkout for{amountCents,requestId}. Reuse the UUID when retrying the same purchase. Access billing routes from the account dashboard. -
POST /tenants/:tenant/billing/orders/:order/cancelcloses a pending manual purchase at Stripe. The signed payment or expiration event settles the order in billing history.
Security and behavior
Never trust project, Steam identity, or environment claims supplied by a client without server verification. Every token and permission check is scoped to the requested project and environment. Shared keys cannot be attached to arbitrary provider URLs. Provider requests use fixed route suffixes, no client headers, and no redirect following. Upstream error bodies are not returned, to avoid leaking credentials or internal details.
Project names are globally unique within a service deployment, enforced by the database even during simultaneous creation. System names (including status/admin/account), the service-development suffix and malformed hostname labels are reserved.
An administrator can ban a workspace with a reason. This blocks customer dashboard access, new tokens and assistant usage; the dispatcher also blocks its project routes as the KV ban propagates. Existing tokens expire within the configured AI lifetime (up to 60 minutes), and KV propagation can delay immediate route enforcement. Admin access remains available for investigation and unbanning.
Normal Steam traffic uses local JWT verification, cached configuration, and a direct upstream request. Ban database checks occur at session issuance and AI token renewal. Cloudflare rate-limit bindings provide a generous abuse backstop without database counters. They are regional approximate rate limits, not spending limits. Configured provider routes can fail over within their permitted destinations. The central account service handles payment collection.
Useful error codes: invalid_token (401), player_banned / scope_not_allowed (403), spending_limit_reached (402), input_token_limit / audio_duration_limit (413), configuration_changed_reload (409), accounting_stale / provider_not_configured (503), and provider_rate_limited (429).
References: Inworld usage records, Inworld chat completions, Inworld voice design, Analytics Engine usage billing, Analytics Engine sampling, Cloudflare Access JWT validation.
Feature requests
Every signed-in workspace member, including viewers, can use Request a feature. Submit a short title and a prompt describing the feature and how it helps. If it sounds good, we’ll ship it to you ASAP. Track its status and review history on the same page. Platform administrators can filter and review all requests in Feature requests; review notes are visible to the requesting workspace.
