Skip to main content
GET
Get a scope

Authorizations

Authorization
string
header
required

A Modus personal access token (modus_<orgUuid>_<prefix>_<secret>) or an OAuth 2.1 access token, sent as Authorization: Bearer <token>.

Path Parameters

id
number
required

Numeric scope id.

Example:

42

Query Parameters

view
enum<string>

Which variation snapshot to read. Defaults to active.

Available options:
active,
draft

Response

id
number
required

Numeric scope id (stable per-org; not reused after delete).

Example:

42

slug
string
required

URL-safe slug used in human-readable links. Unique per org.

Example:

"customer-churn-analyzer-a3f"

name
string
required

Display name of the scope. Shown in the builder and in run logs.

Example:

"Customer Churn Analyzer"

status
enum<string>
required

Lifecycle status. draft = never deployed. active = deployed. deleted = soft-deleted.

Available options:
draft,
active,
deleted
Example:

"active"

orgUuid
string
required

Org UUID this scope belongs to. Matches the caller’s principal.

Example:

"00000000-0000-0000-0000-000000000001"

hasUnpublishedChanges
boolean
required

True when the draft variation differs from the active variation (deploy would publish changes).

Example:

false

accessConfig
object
required

Access configuration — who in the org can use / manage this scope.

createdAt
string
required

Creation timestamp.

Example:

"2026-05-01T10:00:00.000Z"

updatedAt
string
required

Most recent update timestamp.

Example:

"2026-05-11T10:00:00.000Z"

canManage
boolean
required

Whether the requesting principal can manage (edit/delete/deploy) this scope. Derived server-side from the principal + accessConfig. Present on every Scope response.

Example:

true

canUse
boolean
required

Whether the requesting principal can use (run, view history of) this scope. Derived server-side from the principal + accessConfig.

Example:

true

manageDenial
enum<string> | null
required

Why canManage is false, for client-facing guidance: needs_group_manage (shared, but no group you belong to grants Manage) or not_owner (private, and you are not the owner). null when canManage is true.

Available options:
not_owner,
needs_group_manage
Example:

"needs_group_manage"

description
string | null

Optional one-paragraph description of what this scope does.

Example:

"Predicts churn risk for a customer given a 90-day usage window."

activeVariationId
string | null

Active (deployed) variation id. Null until the scope is first deployed.

Example:

"00000000-0000-4000-a000-000000000100"

draftVariationId
string | null

Most recent draft variation id. Null when there is no draft pending.

Example:

"00000000-0000-4000-a000-000000000101"

pendingOwnershipTransfer
object | null

Pending ownership transfer awaiting recipient acceptance. Absent when no request is in flight.

variation
object

Variation-detail payload (toolset, instructions, model, etc.) for the requested view. Populated by GET /api/v1/scopes/:id; absent on list rows.

deletedAt
string | null

Soft-delete timestamp. Null for active scopes.

Example:

null