Update a scope

curl --request PATCH \
  --url https://api.getmodus.com/api/v1/scopes/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Customer Churn Analyzer v2"
}
'

{
  "id": 42,
  "slug": "customer-churn-analyzer-a3f",
  "name": "Customer Churn Analyzer",
  "status": "active",
  "orgUuid": "00000000-0000-0000-0000-000000000001",
  "hasUnpublishedChanges": false,
  "accessConfig": {
    "visibility": "shared",
    "groupPermissions": {
      "group_eng_uuid": {
        "use": true,
        "manage": false
      }
    },
    "guardrails": [],
    "sharedWith": [],
    "ownerUserId": "user_2abc",
    "ownerEmail": "alice@example.com"
  },
  "createdAt": "2026-05-01T10:00:00.000Z",
  "updatedAt": "2026-05-11T10:00:00.000Z",
  "canManage": true,
  "canUse": true,
  "manageDenial": "needs_group_manage",
  "description": "Predicts churn risk for a customer given a 90-day usage window.",
  "activeVariationId": "00000000-0000-4000-a000-000000000100",
  "draftVariationId": "00000000-0000-4000-a000-000000000101",
  "pendingOwnershipTransfer": {
    "pendingOwnerUserId": "user_2abc123def456",
    "requestedByUserId": "user_2xyz789ghi012",
    "requestedAt": "2026-06-05T12:00:00.000Z",
    "pendingOwnerEmail": "newowner@example.com"
  },
  "variation": {
    "expectedOutput": "A 3-bullet summary highlighting churn risk drivers.",
    "instructions": [
      "Be concise.",
      "Always justify the score."
    ],
    "model": "anthropic/claude-sonnet-4.6",
    "toolset": {
      "web_search": {
        "enabled": true
      },
      "calculator": {
        "enabled": true
      }
    },
    "connectionSet": [
      {}
    ],
    "contextSelections": [
      {}
    ],
    "evaluations": [
      {}
    ],
    "interfaces": [
      {}
    ],
    "supervisionSubordinateIds": [
      "12",
      "17"
    ],
    "supervisionSubordinateDescriptions": {
      "12": "Reads warehouse facts",
      "17": "Drafts the report"
    },
    "modelSettings": {
      "contextWindow": 2
    }
  },
  "deletedAt": null
}

{
  "error": {
    "code": "BAD_REQUEST",
    "status": "INVALID_ARGUMENT",
    "message": "Invalid value for query parameter `pageSize`.",
    "requestId": "req_01HQ7K8ABCDEFGHIJKLMNOPQRS"
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "status": "UNAUTHENTICATED",
    "message": "Missing or invalid access token.",
    "requestId": "req_01HQ7K8ABCDEFGHIJKLMNOPQRS"
  }
}

{
  "error": {
    "code": "FORBIDDEN",
    "status": "PERMISSION_DENIED",
    "message": "Missing required scope(s) for this operation.",
    "requestId": "req_01HQ7K8ABCDEFGHIJKLMNOPQRS",
    "info": {
      "missing": [
        "<required-scope>"
      ]
    }
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "status": "NOT_FOUND",
    "message": "Resource not found.",
    "requestId": "req_01HQ7K8ABCDEFGHIJKLMNOPQRS"
  }
}

{
  "error": {
    "code": "CONFLICT",
    "status": "ALREADY_EXISTS",
    "message": "A resource with that identifier already exists.",
    "requestId": "req_01HQ7K8ABCDEFGHIJKLMNOPQRS"
  }
}

{
  "error": {
    "code": "VALIDATION",
    "status": "INVALID_ARGUMENT",
    "message": "Updates that would revoke your own access are not allowed.",
    "requestId": "req_01HQ7K8ABCDEFGHIJKLMNOPQRS"
  }
}

{
  "error": {
    "code": "INTERNAL_ERROR",
    "status": "INTERNAL",
    "message": "An unexpected error occurred.",
    "requestId": "req_01HQ7K8ABCDEFGHIJKLMNOPQRS"
  }
}

PATCH

api

scopes

{id}

curl --request PATCH \
  --url https://api.getmodus.com/api/v1/scopes/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Customer Churn Analyzer v2"
}
'

{
  "id": 42,
  "slug": "customer-churn-analyzer-a3f",
  "name": "Customer Churn Analyzer",
  "status": "active",
  "orgUuid": "00000000-0000-0000-0000-000000000001",
  "hasUnpublishedChanges": false,
  "accessConfig": {
    "visibility": "shared",
    "groupPermissions": {
      "group_eng_uuid": {
        "use": true,
        "manage": false
      }
    },
    "guardrails": [],
    "sharedWith": [],
    "ownerUserId": "user_2abc",
    "ownerEmail": "alice@example.com"
  },
  "createdAt": "2026-05-01T10:00:00.000Z",
  "updatedAt": "2026-05-11T10:00:00.000Z",
  "canManage": true,
  "canUse": true,
  "manageDenial": "needs_group_manage",
  "description": "Predicts churn risk for a customer given a 90-day usage window.",
  "activeVariationId": "00000000-0000-4000-a000-000000000100",
  "draftVariationId": "00000000-0000-4000-a000-000000000101",
  "pendingOwnershipTransfer": {
    "pendingOwnerUserId": "user_2abc123def456",
    "requestedByUserId": "user_2xyz789ghi012",
    "requestedAt": "2026-06-05T12:00:00.000Z",
    "pendingOwnerEmail": "newowner@example.com"
  },
  "variation": {
    "expectedOutput": "A 3-bullet summary highlighting churn risk drivers.",
    "instructions": [
      "Be concise.",
      "Always justify the score."
    ],
    "model": "anthropic/claude-sonnet-4.6",
    "toolset": {
      "web_search": {
        "enabled": true
      },
      "calculator": {
        "enabled": true
      }
    },
    "connectionSet": [
      {}
    ],
    "contextSelections": [
      {}
    ],
    "evaluations": [
      {}
    ],
    "interfaces": [
      {}
    ],
    "supervisionSubordinateIds": [
      "12",
      "17"
    ],
    "supervisionSubordinateDescriptions": {
      "12": "Reads warehouse facts",
      "17": "Drafts the report"
    },
    "modelSettings": {
      "contextWindow": 2
    }
  },
  "deletedAt": null
}

{
  "error": {
    "code": "BAD_REQUEST",
    "status": "INVALID_ARGUMENT",
    "message": "Invalid value for query parameter `pageSize`.",
    "requestId": "req_01HQ7K8ABCDEFGHIJKLMNOPQRS"
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "status": "UNAUTHENTICATED",
    "message": "Missing or invalid access token.",
    "requestId": "req_01HQ7K8ABCDEFGHIJKLMNOPQRS"
  }
}

{
  "error": {
    "code": "FORBIDDEN",
    "status": "PERMISSION_DENIED",
    "message": "Missing required scope(s) for this operation.",
    "requestId": "req_01HQ7K8ABCDEFGHIJKLMNOPQRS",
    "info": {
      "missing": [
        "<required-scope>"
      ]
    }
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "status": "NOT_FOUND",
    "message": "Resource not found.",
    "requestId": "req_01HQ7K8ABCDEFGHIJKLMNOPQRS"
  }
}

{
  "error": {
    "code": "CONFLICT",
    "status": "ALREADY_EXISTS",
    "message": "A resource with that identifier already exists.",
    "requestId": "req_01HQ7K8ABCDEFGHIJKLMNOPQRS"
  }
}

{
  "error": {
    "code": "VALIDATION",
    "status": "INVALID_ARGUMENT",
    "message": "Updates that would revoke your own access are not allowed.",
    "requestId": "req_01HQ7K8ABCDEFGHIJKLMNOPQRS"
  }
}

{
  "error": {
    "code": "INTERNAL_ERROR",
    "status": "INTERNAL",
    "message": "An unexpected error occurred.",
    "requestId": "req_01HQ7K8ABCDEFGHIJKLMNOPQRS"
  }
}

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

number

required

Numeric scope id.

Example:

42

Query Parameters

updateMask

string

Comma-separated list of fields to update. Omit to update all provided fields.

Example:

"name,description"

Body

application/json

name

string

New display name for the scope.

Required string length: 1 - 200

Example:

"Customer Churn Analyzer v2"

description

string

Updated description.

Example:

"Predicts churn risk over a 180-day window."

expectedOutput

string

Updated expected-output summary, used when this scope is supervised.

Example:

"JSON: { churn_probability: number }"

instructions

string[]

Updated instruction fragments. Replaces the prior list when present.

Example:

["You are a senior data analyst."]

toolset

object

Updated toolset configuration.

Show child attributes

model

string | null

Updated model id. Pass null (explicit) to clear and use the org default.

Example:

"claude-sonnet-4-5"

modelSettings

object | null

Updated model-specific runtime controls. Pass null to clear.

Show child attributes

connectionSet

object[]

Updated connection set. Shape is integration-specific.

Example:

[]

contextSelections

object[]

Updated context selections (sources / docs the scope may read).

Example:

[]

interfaces

object[]

Updated interface configuration.

Example:

[]

evaluations

object[]

Updated evaluation entries (task + expected-output pairs) saved for the draft variation. Replaces the prior list when present.

Example:

[]

supervisionSubordinateDescriptions

object

Map of subordinate scope id (stringified) to the manager-provided description blurb. Replaces the prior map when present.

Show child attributes

Example:

{
  "12": "Reads warehouse facts",
  "17": "Drafts the report"
}

accessConfig

object

Updated access configuration. The service rejects changes that would lock the caller out of use + manage.

Show child attributes

managerId

number | null

Re-parent the scope under a new manager (or remove its current manager when null). When this field is present, all other fields are ignored.

Example:

17

Response

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.

Show child attributes

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.

Show child attributes

variation

object

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

Show child attributes

deletedAt

string | null

Soft-delete timestamp. Null for active scopes.

Example:

null

Delete a scope Deploy a scope

Connections

Context

Modus · Chat

Modus · Context

Modus · Conversations

Scopes

Scopes · Chat

Scopes · Context

Scopes · Conversations

Scopes · Memories

Scopes · Supervision

Suggestions

Tools

Usage

Users

Workflows

Workflows · Interfaces

Workflows · Runs

Modus · Runs

Runs · Streaming

Scopes · Runs

Authorizations

Path Parameters

Query Parameters

Body

Response