Quickstart
Check that Sparq is reachable, authenticate, and set up a workspace, project, environment and client.
This quickstart uses curl against the Admin API. You need an operator key or a key with admin
rights on a workspace. Keep keys out of your shell history and out of browsers: send them from a
server or a file.
export SPARQ_API_URL=https://api.sparqhq.ai # or http://127.0.0.1:8000 for a local stack
export SPARQ_KEY="$(cat path/to/your-key)" # never paste a key on the command line1. Check that Sparq is up
The health probes need no authentication.
curl "$SPARQ_API_URL/health/ready"{ "status": "ok", "checks": { "database": "ok" }, "version": "<server version>" }2. Ask who you are
Every authenticated call sends Authorization: Bearer <token>. whoami tells you how Sparq sees
the caller: principal, credential, workspace, project and client.
curl "$SPARQ_API_URL/v1/whoami" -H "Authorization: Bearer $SPARQ_KEY"3. Create a workspace and a project
A workspace is your organisation. A project is one application's contract with Sparq.
curl -X POST "$SPARQ_API_URL/v1/admin/workspaces" \
-H "Authorization: Bearer $SPARQ_KEY" -H "Content-Type: application/json" \
-d '{ "slug": "acme", "name": "Acme" }'
curl -X POST "$SPARQ_API_URL/v1/admin/workspaces/$WORKSPACE_ID/projects" \
-H "Authorization: Bearer $SPARQ_KEY" -H "Content-Type: application/json" \
-d '{ "slug": "support-assistant", "name": "Support assistant" }'Creating a workspace needs an operator key. Both calls answer 201 with the new object; keep its id.
4. Add an environment and a client
Environments are the stages a Release is promoted through. A client (audience tenant) is one of your own customers; its data, budget and traces are isolated from every other client.
curl -X POST "$SPARQ_API_URL/v1/admin/projects/$PROJECT_ID/environments" \
-H "Authorization: Bearer $SPARQ_KEY" -H "Content-Type: application/json" \
-d '{ "name": "dev" }'
curl -X POST "$SPARQ_API_URL/v1/admin/projects/$PROJECT_ID/audience-tenants" \
-H "Authorization: Bearer $SPARQ_KEY" -H "Content-Type: application/json" \
-d '{ "external_id": "org_4417", "name": "Northwind Retail" }'external_id is your own identifier for the customer, as it appears in your users' sign-in tokens.
5. Keep a client's data in one region
A compliance profile tells the Frontier Gateway where a client's prompts may be processed. If no
model deployment satisfies it, the call is refused with no_compliant_model; it is never routed
elsewhere.
curl -X PUT "$SPARQ_API_URL/v1/admin/audience-tenants/$CLIENT_ID/compliance-profile" \
-H "Authorization: Bearer $SPARQ_KEY" -H "Content-Type: application/json" \
-d '{ "audience_tenant_id": "'$CLIENT_ID'", "version": 1, "data_regions": ["eu"] }'6. Issue a project key
curl -X POST "$SPARQ_API_URL/v1/admin/credentials" \
-H "Authorization: Bearer $SPARQ_KEY" -H "Content-Type: application/json" \
-d '{
"type": "project_api_key",
"owner": { "kind": "team", "name": "Support platform team" },
"project_id": "'$PROJECT_ID'",
"environment": "dev",
"purpose": "Back-end calls from the support assistant"
}'The response holds the key in secret, shown once. Store it in your secret manager. Sparq keeps
only a peppered hash and a short fingerprint.
Next steps
- Authentication: project keys and your own users' tokens.
- Concepts: how workspaces, projects, environments, clients and Releases fit together.
- Streaming: what your chat interface will receive once runs are available.