---
title: "Get Or Create Scope"
method: POST
path: "/v3/workspaces/{workspace_id}/scopes"
tags: ["scopes"]
---

# Get Or Create Scope

`POST /v3/workspaces/{workspace_id}/scopes`

Get a Scope by ID or create a new Scope with the given ID.

Returns 201 when the scope is created and 200 when it already exists.
A pre-existing peer occupying the scope's reserved internal name is never
adopted; that conflict returns 409.

## Path parameters

- `workspace_id` string, required

## Request body

- ScopeCreate — Schema for creating (or getting) a scope by its unprefixed name.
  - `id` string, required
  - `metadata` object, nullable

## Response `200`

Successful Response

- Scope — Scope response — external view of the peer backing a scope. The ``id`` is the unprefixed scope name; the reserved peer-name prefix is an internal implementation detail and never surfaces here.
  - `id` string, required
  - `metadata` object
  - `created_at` string, date-time, required

## Other responses

- `201` — Successful Response
- `409` — Conflict
- `422` — Validation Error

## Changes

- **2026-08-27** (v3) `63b701d883c9` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/plastic-labs/apis/honcho-api/changes/v3/workspaces/:workspace_id/scopes/post.md)

---

[API](https://skmtc.dev/plastic-labs/apis/honcho-api.md) · [All operations](https://skmtc.dev/plastic-labs/apis/honcho-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/plastic-labs/honcho-api/revisions/63b701d883c9/schema)