Make your first request

You need Python 3.11 and curl to try Q’s HTTP contract locally. This path does not require Docker, a provider account or SDK installation. It returns synthetic evidence; use a provisioned Q environment for actual retrieval and generation.

Start the sandboxCopy Anchor Link

From the Q repository root, keep this command running in one terminal:

python3 examples/sandbox/server.py

It listens only on 127.0.0.1:8787, accepts the fixed non-secret fixture token below and discards its in-memory state on exit. It never loads provider credentials or calls a live Q deployment.

Retrieve evidenceCopy Anchor Link

In a second terminal, set the local API root:

export Q_API_BASE_URL=http://127.0.0.1:8787/v1

Copy this request. The token is valid only in the local sandbox.

curl --fail-with-body --silent --show-error \
  "$Q_API_BASE_URL/search" \
  --header 'Authorization: Bearer q_local_sandbox' \
  --header 'Content-Type: application/json' \
  --data '{"query":"Q integration evidence","mode":"web","max_results":3}'

A successful response contains results. Read the returned source URLs and evidence instead of treating the number of matches as a quality score. This sandbox always returns its fixture source; an empty result on a real deployment has a different meaning from an unavailable retrieval provider. See evidence availability.

Read a final answerCopy Anchor Link

curl --fail-with-body --silent --show-error \
  "$Q_API_BASE_URL/answer" \
  --header 'Authorization: Bearer q_local_sandbox' \
  --header 'Content-Type: application/json' \
  --data '{"query":"What does the Q integration fixture demonstrate?","stream":false}'

The final answer is Q fixtures test API integration [1]. and the response includes sources, citations and quality. Check those fields before presenting a grounded answer. For streamed answers, follow the machine streaming contract: draft text may be replaced, and a connection closing does not prove a successful final result.

Choose your next stepCopy Anchor Link

Move to a provisioned environmentCopy Anchor Link

Obtain a scoped credential through your environment’s control plane and use its API root. These literal sandbox requests are not production credential examples. Keep real credentials in a backend secret store and out of shell history, process arguments, URLs and browser bundles; the qualified curl journey passes credentials through stdin.

Inspect the deployed capability and OpenAPI documents before calling an operation. Provider access, billing, corpus permissions and Temporal workers are server-side requirements. A q_test_ key prefix alone does not guarantee isolation or free provider calls. Complete the integration release checklist before exposing a real integration to users.