Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.copass.com/llms.txt

Use this file to discover all available pages before exploring further.

A project is a logical grouping inside a sandbox — a way to slice one tenancy into several work areas without having to spin up separate sandboxes. Retrieval scopes by project, and collaboration grants can be scoped by project, so a teammate can see just one slice of a sandbox while the rest stays invisible to them. Use projects when one sandbox holds work for multiple teams or initiatives and you want each team to see only their slice.

​
What you can do

  • Create a project inside a sandbox; name and describe it.
  • Link or unlink data sources to/from a project (M:N — one source can belong to many projects, one project can hold many sources).
  • Scope retrieval calls to one project (discover / interpret / search accept project_id).
  • Scope a collaboration grant to one project so a teammate sees only that slice.
  • Archive a project (reversible) or delete it (permanent).
“Create a project called support in this sandbox and link my Intercom and Zendesk sources.” “Show me retrieval scoped to the marketing project.” “Add @alice as editor on the support project only.”

​
Via the CLI

# Per-project config (different concept — local config file in your repo)
copass config project list
copass config project set <path> <value>

# Project resource CRUD goes through the SDK / API today

​
Via the SDK / API

// Create a project
const project = await client.projects.create(sandboxId, {
  name: 'support',
  description: 'Customer support workspace',
  data_source_ids: ['ds_intercom', 'ds_zendesk'],
});

// Link / unlink data sources
await client.projects.linkSource(sandboxId, project.project_id, 'ds_helpscout');
await client.projects.unlinkSource(sandboxId, project.project_id, 'ds_zendesk');

// Scope retrieval to the project
const menu = await client.matrix.discover({
  query: 'why are tickets stalling?',
  project_id: project.project_id,
});

// Lifecycle
await client.projects.archive(sandboxId, project.project_id);  // reversible
await client.projects.del(sandboxId, project.project_id);      // permanent

​
Anatomy of a project

FieldPurpose
project_idStable id; passed to retrieval and grants.
name, descriptionHuman-readable.
data_source_idsM:N link to data sources in the same sandbox.
statusactive / archived. Archived projects don’t appear in retrieval.
metadataFree-form JSON the SDK stores verbatim.

​
Project vs sandbox vs config file

Three “project” things show up in Copass — they’re related but distinct:
TermWhat it is
Project (this page)A resource inside a sandbox. Has an id, links to data sources, scopes retrieval.
SandboxThe tenancy boundary that holds projects. See Sandboxes.
.olane/config.jsonA local CLI config file in your repo. Tweaked via copass config project *. Not the same as the Project resource.

​
Common patterns

One sandbox, many products

Hold all your apps’ work in one sandbox; create a project per product. Retrieval stays clean per product without fragmenting the sandbox.

Per-team grants

Invite a team as editors scoped to their project only. They see and mutate their slice; the rest of the sandbox is invisible.

Mixed-source project

Link multiple data sources (Slack + GitHub + Notion) to one project so retrieval over that project pulls from all three.

Archive vs delete

Archive when you might come back to it. Delete when the data must go. Archive is reversible.

​
Next steps