> ## Documentation Index > Fetch the complete documentation index at: https://docs.getmodus.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a scope > Creates a scope (owned by you) and returns it in draft state. Defaults to org-shared `use` + `manage` access. Call POST /scopes/{id}/deploy to publish it. **Requires:** `scopes:write` ## OpenAPI ````yaml https://api.getmodus.com/openapi.json post /api/v1/scopes openapi: 3.0.3 info: title: Modus Public API version: 1.0.0 servers: [] security: - bearerAuth: [] tags: - name: Scopes description: Create, configure, deploy, and manage scopes. - name: Scopes · Conversations description: Read scope conversation threads. - name: Scopes · Supervision description: Scope supervision sub-resource. - name: Scopes · Memories description: Long-term memory stored per scope. - name: Scopes · Chat description: Chat with a published scope. - name: Scopes · Context description: Compose a scope’s context without an LLM call. - name: Modus · Chat description: Chat with Modus — your org-wide assistant. - name: Modus · Conversations description: Read Modus and cross-scope conversation threads. - name: Modus · Context description: Compose full-environment context without an LLM call. - name: Workflows description: Create, configure, deploy, and manage workflows. - name: Workflows · Runs description: Inspect workflow run history. - name: Workflows · Interfaces description: Slack / MCP / Teams interface management. - name: Connections description: Read connected integrations. - name: Tools description: Catalog of tools/integrations a scope can select in its toolset. - name: Suggestions description: Approved suggested questions and first-party suggestion usage events. - name: Context description: Create and manage organization context items. - name: Usage description: Organization LLM usage reporting. - name: Users description: Organization and membership management. - name: Runs · Streaming description: 'Run lifecycle: stream, poll, resume, interrupt, and cancel executions.' - name: Scopes · Runs description: Run a published or draft scope. - name: Modus · Runs description: Run the Modus home agent. paths: /api/v1/scopes: post: tags: - Scopes summary: Create a scope description: >- Creates a scope (owned by you) and returns it in draft state. Defaults to org-shared `use` + `manage` access. Call POST /scopes/{id}/deploy to publish it. **Requires:** `scopes:write` operationId: ScopesController_create parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateSkillDto' examples: minimal: value: name: Customer Churn Analyzer withInstructions: value: name: Customer Churn Analyzer description: Predicts churn risk over a 90-day window. instructions: - You are a senior data analyst. responses: '201': description: '' content: application/json: schema: $ref: '#/components/schemas/ScopeDto' '400': description: >- Malformed request — invalid query parameters or request body (`code: BAD_REQUEST`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' example: error: code: BAD_REQUEST status: INVALID_ARGUMENT message: Invalid value for query parameter `pageSize`. requestId: req_01HQ7K8ABCDEFGHIJKLMNOPQRS '401': description: 'Missing, invalid, or expired access token (`code: UNAUTHORIZED`).' content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' example: error: code: UNAUTHORIZED status: UNAUTHENTICATED message: Missing or invalid access token. requestId: req_01HQ7K8ABCDEFGHIJKLMNOPQRS '403': description: >- Authenticated, but the token lacks a required scope (`code: FORBIDDEN`). The missing scopes are listed in `info`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' example: error: code: FORBIDDEN status: PERMISSION_DENIED message: Missing required scope(s) for this operation. requestId: req_01HQ7K8ABCDEFGHIJKLMNOPQRS info: missing: - '404': description: >- The resource does not exist, or you do not have access to it (`code: NOT_FOUND`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' example: error: code: NOT_FOUND status: NOT_FOUND message: Resource not found. requestId: req_01HQ7K8ABCDEFGHIJKLMNOPQRS '409': description: >- The request conflicts with the current state of the resource, e.g. a duplicate (`code: CONFLICT`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' example: error: code: CONFLICT status: ALREADY_EXISTS message: A resource with that identifier already exists. requestId: req_01HQ7K8ABCDEFGHIJKLMNOPQRS '422': description: >- The request was well-formed but failed a business rule (`code: VALIDATION`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' example: error: code: VALIDATION status: INVALID_ARGUMENT message: Updates that would revoke your own access are not allowed. requestId: req_01HQ7K8ABCDEFGHIJKLMNOPQRS '500': description: 'An unexpected server error occurred (`code: INTERNAL_ERROR`).' content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' example: error: code: INTERNAL_ERROR status: INTERNAL message: An unexpected error occurred. requestId: req_01HQ7K8ABCDEFGHIJKLMNOPQRS security: - bearerAuth: [] servers: - url: https://api.getmodus.com components: schemas: CreateSkillDto: type: object properties: name: type: string description: Display name for the scope. Will be slugified into a URL-safe path. example: Customer Churn Analyzer minLength: 1 maxLength: 200 description: type: string description: >- Optional one-paragraph description shown in the builder and scope catalog. example: Predicts churn risk for a customer given a 90-day usage window. expectedOutput: type: string description: >- Optional summary of the expected output schema, used when supervising other scopes. example: 'JSON: { churn_probability: number, drivers: string[] }' instructions: description: >- Ordered list of system-prompt instruction fragments. Joined at run time. example: - You are a senior data analyst. - Always cite the SQL you used. type: array items: type: string toolset: description: >- Toolset configuration (tools this scope may invoke). Service sanitizes the shape on write. allOf: - $ref: '#/components/schemas/ToolsetDto' model: type: string description: >- Model identifier to use at run time (e.g. `claude-sonnet-4-5`). Falls back to org default when absent. example: claude-sonnet-4-5 modelSettings: description: >- Model-specific runtime controls such as reasoning effort and context window. allOf: - $ref: '#/components/schemas/ModelSettingsDto' connectionSet: type: array description: >- List of integration connection refs available to this scope. Shape is integration-specific. items: type: object additionalProperties: true example: [] contextSelections: type: array description: Selected context items (sources / docs) the scope may read. items: type: object additionalProperties: true example: [] interfaces: type: array description: >- Interface configuration (chat, API, webhook…). Shape is interface-specific. items: type: object additionalProperties: true example: [] accessConfig: description: >- Access configuration. Omit to use the default (full-org shared with use + manage). allOf: - $ref: '#/components/schemas/AccessConfigDto' required: - name ScopeDto: type: object properties: id: type: number description: Numeric scope id (stable per-org; not reused after delete). example: 42 slug: type: string description: URL-safe slug used in human-readable links. Unique per org. example: customer-churn-analyzer-a3f name: type: string description: Display name of the scope. Shown in the builder and in run logs. example: Customer Churn Analyzer description: type: string description: Optional one-paragraph description of what this scope does. example: Predicts churn risk for a customer given a 90-day usage window. nullable: true status: description: >- Lifecycle status. `draft` = never deployed. `active` = deployed. `deleted` = soft-deleted. example: active allOf: - $ref: '#/components/schemas/ResourceLifecycleStatus' orgUuid: type: string description: Org UUID this scope belongs to. Matches the caller’s principal. example: 00000000-0000-0000-0000-000000000001 activeVariationId: type: string description: >- Active (deployed) variation id. Null until the scope is first deployed. example: 00000000-0000-4000-a000-000000000100 nullable: true draftVariationId: type: string description: Most recent draft variation id. Null when there is no draft pending. example: 00000000-0000-4000-a000-000000000101 nullable: true hasUnpublishedChanges: type: boolean description: >- True when the draft variation differs from the active variation (deploy would publish changes). example: false accessConfig: description: Access configuration — who in the org can use / manage this scope. allOf: - $ref: '#/components/schemas/AccessConfigDto' pendingOwnershipTransfer: description: >- Pending ownership transfer awaiting recipient acceptance. Absent when no request is in flight. nullable: true type: object allOf: - $ref: '#/components/schemas/PendingOwnershipTransferDto' variation: description: >- Variation-detail payload (`toolset`, `instructions`, `model`, etc.) for the requested view. Populated by `GET /api/v1/scopes/:id`; absent on list rows. allOf: - $ref: '#/components/schemas/SkillVariationDto' createdAt: type: string description: Creation timestamp. example: '2026-05-01T10:00:00.000Z' updatedAt: type: string description: Most recent update timestamp. example: '2026-05-11T10:00:00.000Z' deletedAt: type: string description: Soft-delete timestamp. Null for active scopes. example: null nullable: true canManage: type: boolean description: >- 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: type: boolean description: >- Whether the requesting principal can use (run, view history of) this scope. Derived server-side from the principal + accessConfig. example: true manageDenial: type: string enum: - not_owner - needs_group_manage nullable: true description: >- 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. example: needs_group_manage required: - id - slug - name - status - orgUuid - hasUnpublishedChanges - accessConfig - createdAt - updatedAt - canManage - canUse - manageDenial ErrorResponseDto: type: object properties: error: $ref: '#/components/schemas/ErrorEnvelopeDto' required: - error ToolsetDto: type: object properties: tools: description: List of tools the scope may invoke. example: - id: web_search enabled: true type: array items: $ref: '#/components/schemas/ToolsetToolDto' ModelSettingsDto: type: object properties: reasoningEffort: description: Optional reasoning effort for models that support it. allOf: - $ref: '#/components/schemas/ReasoningEffort' contextWindow: type: number description: Selected model context window in tokens. minimum: 1 AccessConfigDto: type: object properties: visibility: type: string description: >- Visibility tier. `shared` applies the group-permission map; `private` ignores groups and uses owner + sharedWith for access. enum: - shared - private example: shared groupPermissions: type: object description: >- Map of group UUID -> { use, manage } booleans. Empty object when visibility is `private`. example: group_eng_uuid: use: true manage: false additionalProperties: $ref: '#/components/schemas/GroupPermissionDto' guardrails: description: >- Free-form guardrail labels enforced at run time (e.g. PII redaction profile names). example: [] type: array items: type: string sharedWith: description: Per-user share entries used for private-visibility scopes. example: [] type: array items: $ref: '#/components/schemas/SharedUserDto' ownerUserId: type: string description: >- Clerk user id of the scope owner. Set on first write; cannot be changed by clients. example: user_2abc nullable: true ownerEmail: type: string description: >- Lowercased email of the scope owner. Used by private-scope ACL when owner email matches. example: alice@example.com nullable: true required: - visibility - groupPermissions - guardrails - sharedWith ResourceLifecycleStatus: type: string enum: - draft - active - deleted description: >- Lifecycle status. `draft` = never deployed. `active` = deployed. `deleted` = soft-deleted. PendingOwnershipTransferDto: type: object properties: pendingOwnerUserId: type: string description: >- Clerk user id of the org member who will become owner once they accept. example: user_2abc123def456 pendingOwnerEmail: type: string description: >- Email of the pending recipient, resolved from org membership at request time. example: newowner@example.com nullable: true requestedByUserId: type: string description: >- Clerk user id of the member who requested the transfer (the current owner). example: user_2xyz789ghi012 requestedAt: type: string description: When the transfer was requested. example: '2026-06-05T12:00:00.000Z' required: - pendingOwnerUserId - requestedByUserId - requestedAt SkillVariationDto: type: object properties: expectedOutput: type: string description: Free-form expected-output prompt that constrains the scope’s reply. example: A 3-bullet summary highlighting churn risk drivers. instructions: type: array description: >- Ordered list of instruction blocks. Each entry is a free-form string the builder rendered into the system prompt. items: type: string example: - Be concise. - Always justify the score. model: type: string description: Provider-prefixed model id. The orchestrator routes by prefix. example: anthropic/claude-sonnet-4.6 modelSettings: description: >- Model-specific runtime controls such as reasoning effort and context window. allOf: - $ref: '#/components/schemas/ModelSettingsDto' toolset: type: object description: >- Builder-managed toolset descriptor. Map of `{toolName: config}`; opaque to the API surface. additionalProperties: true example: web_search: enabled: true calculator: enabled: true connectionSet: type: array description: >- Connection selections (DBs, integrations) attached to the variation. Each entry is a builder-managed object; opaque here. items: type: object additionalProperties: true contextSelections: type: array description: >- Context selections attached to the variation. Free-form builder objects. items: type: object additionalProperties: true evaluations: type: array description: >- Evaluation entries (task + expected-output pairs) saved for this variation. items: type: object additionalProperties: true interfaces: type: array description: >- Interface entries attached to the variation (chat, slack, webhook, etc.). Each is a builder-managed object. items: type: object additionalProperties: true supervisionSubordinateIds: type: array description: >- IDs of scopes supervised by this scope (when it is a manager). Stringified for wire stability. items: type: string example: - '12' - '17' supervisionSubordinateDescriptions: type: object description: Map of subordinateId -> manager-provided description blurb. additionalProperties: type: string example: '12': Reads warehouse facts '17': Drafts the report required: - expectedOutput - instructions - model - toolset - connectionSet - contextSelections - evaluations - interfaces - supervisionSubordinateIds - supervisionSubordinateDescriptions ErrorEnvelopeDto: type: object properties: code: description: Modus-specific machine code. allOf: - $ref: '#/components/schemas/ApiErrorCode' status: description: Canonical status string for the error. allOf: - $ref: '#/components/schemas/ApiErrorStatus' message: type: string example: Skill was not found or you lack permission. requestId: type: string example: req_01HQ7K8ABCDEFGHIJKLMNOPQRS info: type: object description: >- Optional domain-specific context. Shape varies per endpoint — see the operation's error response examples. additionalProperties: true example: skillId: sk_abc123 required: - code - status - message - requestId ToolsetToolDto: type: object properties: id: type: string description: >- Stable id of the tool (matches the registry key on the workflow runtime). example: web_search enabled: type: boolean description: >- Whether this tool is enabled for the scope. Defaults to true when absent. example: true config: type: object additionalProperties: true description: >- Free-form tool-specific configuration (e.g. allowlists). Schema varies per tool. example: max_results: 5 required: - id ReasoningEffort: type: string enum: - none - minimal - low - medium - high - xhigh - max description: Optional reasoning effort for models that support it. GroupPermissionDto: type: object properties: use: type: boolean description: Whether members of this group may use (run / invoke) the scope. example: true manage: type: boolean description: >- Whether members of this group may manage (edit / deploy / delete) the scope. example: false required: - use - manage SharedUserDto: type: object properties: email: type: string description: >- Lowercased email of a user explicitly granted access to a private scope. example: alice@example.com addedAt: type: string description: ISO-8601 timestamp at which this user was added to the share list. example: '2026-05-01T10:00:00Z' addedBy: type: string description: Clerk user id of the principal that added this share entry. example: user_2abc userId: type: string description: >- Clerk user id of the invited user. Stored for display; access checks use email. example: user_2xyz permission: description: >- Per-invitee access level for private scopes. `manage` grants edit / deploy / delete (implies use); `use` (default) grants run-only. example: use allOf: - $ref: '#/components/schemas/SharedUserPermission' required: - email ApiErrorCode: type: string enum: - VALIDATION - BAD_REQUEST - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - CONFLICT - RATE_LIMITED - INTERNAL_ERROR description: Modus-specific machine code. ApiErrorStatus: type: string enum: - INVALID_ARGUMENT - UNAUTHENTICATED - PERMISSION_DENIED - NOT_FOUND - ALREADY_EXISTS - RESOURCE_EXHAUSTED - INTERNAL description: Canonical status string for the error. SharedUserPermission: type: string enum: - use - manage description: >- Per-invitee access level for private scopes. `manage` grants edit / deploy / delete (implies use); `use` (default) grants run-only. securitySchemes: bearerAuth: scheme: bearer bearerFormat: Modus PAT (modus___) or OAuth 2.1 access token type: http description: >- A Modus personal access token (`modus___`) or an OAuth 2.1 access token, sent as `Authorization: Bearer `. ````