Projects

A project is a boundary beneath your organization ("workspace") for one agent. If you run several agents under one Reflexio account, projects keep each agent's API keys, configuration, and learned data separate from the others.

Why Projects Exist

Reflexio isolates data by organization: one workspace, one configuration, one set of learnings. That's fine for a single agent, but a design partner running several agents under one org found that learnings didn't transfer cleanly between them — a lesson from agent A is often irrelevant to agent B, and it crowds out retrieval slots that B's own learnings should occupy. Worse, a lesson that helps A can actively harm B, because playbooks are procedural: they instruct an agent how to behave, and one agent's instructions are not automatically another's.

Projects give you a way to say "this data belongs to this agent." Create one project per agent — a support bot, a sales assistant, a staging environment for the same agent — and each keeps its own API keys, its own configuration overrides, and its own profiles, playbooks, interactions, and evaluations.

The Hierarchy

organization (workspace)   account, login, billing
  └─ project                 one agent — API keys, config overrides, learned data
      └─ user_id              the people or sessions that agent talks to

• Organization is your Reflexio account: login, team members, billing, and subscription. It's the boundary the Account Setup guide covers.
• Project sits beneath it. Every workspace starts with one project named Default (slug default) — you don't have to create one to get started, and existing workspaces were given a Default project automatically when projects shipped.
• user_id is unchanged: the identifier you already pass to publish_interaction() and the rest of the client, now scoped within whichever project the request resolves to.

Managing Projects

Projects are managed from Settings → Projects in the portal.

• Create — name the project and choose a slug (used in code and API filters; it can be changed later, the project's id cannot). Slugs are unique within a workspace.
• Rename — update a project's name and/or slug at any time.
• Switch — the project switcher sits in the sidebar, above the pages it scopes (Dashboard, Evaluations, Experiments, Interactions, Profiles, Playbooks, Human Questions, Settings, and API Keys — everything except the org-level Usage, Billing, and Account pages). The API Keys page and the per-project overrides on Settings already read your selection there today.
• Delete — every workspace must keep at least one project, so deleting your only remaining project is refused. Deleting the project you currently have selected succeeds and switches you to another one automatically. A project that still has an API key pointing at it must have that key deleted or repointed first.

Per-Project API Keys

When you create an API key (Account → API Keys), you choose which project it belongs to. The key you get back reads and writes only within that project, and it can't be moved to another project afterward — create a new key for a different project instead. The API Keys page itself shows only the keys for whichever project is currently selected in the switcher.

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/tokens" \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "name": "production-key",
  "role": "full_access",
  "project_id": "prj_abc123"
}
JSON

Omit project_id and the key is created for the workspace's currently-selected project. Keys created before projects existed keep working — they resolve to the workspace's Default project.

Per-Project Configuration Overrides

Most of a workspace's configuration — storage, provider keys, extraction and evaluation windows — is shared by every project in it. A small set of request-path behavioral fields can be overridden per project instead, so one agent can run a different extraction preset or agent-context prompt without affecting its siblings:

• agent_context_prompt
• extraction_preset
• enable_document_expansion
• retrieval_floor
• stride_size
• tool_can_use
• window_size

On the Settings page, each of these fields shows a badge next to its control: Workspace when the field is inheriting the org's value, or Overridden for <project> when this project has its own value. Overriding a field seeds it from the current workspace value so nothing changes until you edit it; Reset to workspace removes the override and the field goes back to inheriting. Every other section of Settings — storage, provider keys, and the debounce-scheduled extractor/evaluator settings — is workspace-wide and has no per-project override.

curl -X PUT "${REFLEXIO_URL:-https://www.reflexio.ai}/api/projects/prj_abc123/config" \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "overrides": {
    "extraction_preset": "concise"
  }
}
JSON

The overrides payload replaces the project's overlay wholesale — it isn't a patch. Omitting a key from it is how you clear that override and go back to inheriting the workspace value. GET /api/projects/{project_id}/config returns all three layers — workspace, overrides, and the resolved effective config — along with overridable_keys, the full allowlist above, and config_version, which increments on every write.

Project CRUD and configuration endpoints require a portal login session, not an API key — they're workspace-admin operations, managed from the portal rather than from your agent's own credentials.

What's Not Scoped to a Project

• Cross-project reads. Nothing in Reflexio reads across two projects, with two exceptions: data-subject export/erasure and full account deletion always reach every project in the workspace (these are legal obligations against the organization, not a per-project feature), and billing rollups always report at the org level (see below).
• Billing. There's no per-project billing. Usage from every project in a workspace is attributed to the organization and billed there — the same subscription and usage dashboard cover all of a workspace's projects together.
• Team membership, storage configuration, and provider/LLM credentials. These stay workspace-wide; see Account Setup.
• claude-smart. Its own notion of a "project" is unrelated — a git repository, scoped by user_id — and is not affected by anything on this page.
• Local/OSS development. Projects don't apply outside Enterprise deployments.

Related

• Account Setup — organization-level login, team, and API keys
• Web Portal Usage — the Dashboard, Interactions, Profiles, Playbooks, and Evaluation pages
• Configuration Guide — the full workspace configuration document