Isolated development environmentsCopy Anchor Link

In the developer portal, choose Create organization → Isolated development. Q creates a separate Wocha organisation owned by your signed-in account. Its tenant ID, API keys, knowledge and spend records are separate from your other organisations. Create a key inside that organisation with ai:search to try keyword retrieval. For answers, add ai:answer and check the deployment's supported models.

A q_test_ prefix is only a test marker. It does not create a separate tenant, hide production documents, or make provider requests free. Use a separate development organisation even when you use test-marked keys. These organisations share Q's deployment and infrastructure; they are not dedicated servers.

Sample knowledgeCopy Anchor Link

New development organisations contain a tenant-visible, keyword-only document about the fictional Aurora project. The organisation page shows its document ID. No embedding or generation provider is called to seed it. With your development key stored on your backend, send this body to POST /v1/knowledge/retrieve:

{
  "query": "Aurora",
  "mode": "keyword",
  "sources": ["local"]
}

Use Reset sample to restore that one document. The operation increments its version and tombstones its old chunks. It preserves your other documents, credentials and spend history. It is available only to an owner or admin of a development organisation. Retrying organisation creation recovers the same organisation for the same account/name/environment and does not reset its data or budget.

Spend controlsCopy Anchor Link

Initial provider-spend ceilings are $0.25 per day, $1 per month and $0.05 per run, enforced through Q's existing spend ledger on metered provider dispatch. These are provider-cost controls, not a total invoice cap or free credits. Requests may fail when their estimate exceeds a ceiling, balance is exhausted, provider pricing is unavailable, or credentials are missing. Sample reset does not replenish spend. An operator can tighten limits; setup retries preserve those changes.

Readiness checksCopy Anchor Link

The organisation page's Environment readiness panel checks registration, tenant-isolation configuration, the headless knowledge API setting, sample presence, budget configuration and the existence of an active search-scoped key. It also runs the deployment's bounded database/schema and configured dependency probes. Only owners and admins can inspect it.

configuration_ready means these configuration checks passed. It does not mean your chosen key was authenticated, a provider accepted a request, budget remains, an ingestion worker is polling, or an agent run completed. Those checks are explicitly marked not_checked. A Temporal namespace probe does not prove worker execution. Test the exact development key and your intended workflow before promoting your integration.

The portal uses these user-authenticated management endpoints:

• POST /api/v1/developers/organizations with {"name":"My development project","environment":"development"}.
• GET /api/v1/developers/organizations/{org_id}/readiness (read-only; no provider calls).
• POST /api/v1/developers/organizations/{org_id}/development/reset-sample (sample only).

They require a Wocha user session and current organisation membership, not a tenant API key. The creation API defaults to standard for existing clients.

Deployment prerequisitesCopy Anchor Link

Apply migration 20261013_020000_development_environment before rolling out the API. The runtime role needs its existing table and sequence grants. Enable Q_ENABLE_RLS and SPEND_LEDGER_ENABLED; development creation and resets fail closed when either is disabled. Enable HEADLESS_API_ENABLED to retrieve the sample. Configure Wocha organisation provisioning as for standard organisation creation.

Failed external provisioning can leave an organisation without completed Q setup. Retry with the same name and account; Q completes setup before granting the owner membership. Do not work around a failed setup by reusing production keys.

Track integration progressCopy Anchor Link

The portal diagnostics dashboard combines readiness with active-key checks, recorded HTTP responses and scoped durable-run diagnostics. Missing telemetry is kept distinct from a successful integration.