Scopes

Two questions decide who can see something in Epismo: where does it live (its scope) and who else is it shared with. Getting these right is how you keep drafts private, share work with a team, and avoid accidentally exposing data.

• scope: where a private record lives, in your personal space or one or more workspace projects.
• sharedWith: specific people who get access on top of the scope.
• visibility (packs only): whether the pack is also discoverable publicly.

Where a record lives: scope

Use scope when creating or updating a private pack or track. Keep it to yourself with personal scope:

{ "scope": { "type": "personal" } }

Or place it in one or more workspace projects so the project's members can see it:

{ "scope": { "type": "projects", "ids": ["project-id"] } }

On update, omitting scope preserves the existing scope; you do not have to resend it just to change a title.

Project scope is valid only in workspace context. If no workspace is selected, use personal scope.

Searching across locations: scopes

A single record lives in one scope, but a search often needs to look in several places at once. That is why search uses scopes (plural):

{
	"scopes": [{ "type": "personal" }, { "type": "projects", "ids": ["project-id"] }]
}

This searches your personal space and the listed project together in one call.

Search scope is a filter, not a move. Passing scopes decides where to look; it does not change where matching records live.

Granting extra access: sharedWith

sharedWith adds specific people on top of the scope, useful when one teammate needs access but does not belong to the project.

{
	"sharedWith": {
		"userIds": ["user-id"],
		"emails": ["teammate@example.com"]
	}
}

On update, omitting sharedWith preserves the existing value.

sharedWith grants extra access, but it does not move the record into a different scope. If you later remove a person from sharedWith, their extra access is removed unless they can still see the record through the scope.

Public visibility for packs

visibility applies only to packs.

Public visibility does not turn tracks public, because tracks do not support public visibility. It also does not make project membership irrelevant for private collaboration workflows; use scope and sharedWith to model who should collaborate on the source record.

Putting it together

Imagine a context pack with scope: { "type": "projects", "ids": ["proj-1"] } and sharedWith: { "emails": ["lead@example.com"] }:

• Members of proj-1 can see it (from the scope).
• lead@example.com can see it too, even if they are not in proj-1 (from sharedWith).
• Nobody else can, unless the pack's visibility is set to public, which makes it discoverable on the hub independently of scope. Tracks have no public visibility; they are always private.

When in doubt, start with personal scope to test privately, then widen access once the content is ready to share.