Overview
The objects you work with in Sparq, and how they fit together.
The core idea
Applications integrate with the Project, never with the model. Each application gets a Project with a stable contract. Behind it, Sparq can swap models, update instructions, add tools and re-index knowledge, and the application does not change.
Objects
| Object | What it is |
|---|---|
| Workspace | The top-level owner: your organisation. Holds projects, people and budgets. |
| Project | One application's contract with Sparq: its credentials, token issuers, agents, skills, tools, knowledge, model classes and budgets. |
| Environment | A stage of a project, such as dev, qa, preprod or prod. Environments have a promotion order; a protected environment needs a second approver to publish. |
| Release | An immutable bundle of a project's configuration: models, instructions, agents, tools, guardrails, knowledge and the evaluation baseline. Promoted and rolled back as a whole. |
| Client (audience tenant) | One of your own customers, inside a project. Data, memory, traces and budgets are isolated per client. |
| Compliance profile | A client's rules: allowed regions, providers and model classes, data sensitivity, retention. Model routing obeys it and fails closed. |
| Credential | Anything that authenticates a caller: a project key, a token issuer binding, a delegated tool token. Every request, cost row and audit record names the credential that caused it. |
| Agent spec | Data that defines an agent: its job, instructions, model class, tools, skills, limits and the actions that need approval. |
| Run | One execution of an agent. It streams events, may pause for a person, and ends in a typed terminal state. |
Every client-scoped record carries the isolation key (workspace, project, client). Each project
also has a reserved client of its own, for work that is not on behalf of a customer.
Two APIs, one contract
| Path | Used by | |
|---|---|---|
| Runtime API | /v1/... | Your application at run time: sessions, messages, runs, approvals, features |
| Admin API | /v1/admin/... | Your back office and the consoles: tenancy, credentials, compliance, models, changes, usage, audit |
Both are described by one OpenAPI document and versioned together. See versioning.
What Sparq never does
- It never runs your code. It reaches your systems only through tools you expose (MCP servers, or operations imported from your OpenAPI document).
- It never reads your databases directly.
- It never puts a credential into a model's context, a run's state or a trace.