--- title: Create Scope | Luma Agents --- POST /v1/scopes Select code samplecURL (shell:curl) ```js const url = 'https://agents.lumalabs.ai/v1/scopes'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"config":{},"display_name":"example","expires_in_seconds":1,"key":"example"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request POST \ --url https://agents.lumalabs.ai/v1/scopes \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "config": {}, "display_name": "example", "expires_in_seconds": 1, "key": "example" }' ``` - Productionagents.lumalabs.ai/v1/scopes Create a scope (workspace) or retrieve an existing one by `key`. Supplying `key` makes creation idempotent, however many requests race: a new key is 201, and a repeat that omits `config` or names the same one is 200 with `replayed: true` and the original scope. A repeat with a different `config` is 409 `SCOPE.IDEMPOTENCY_CONFLICT`. A key another team holds is 409 `SCOPE.KEY_TAKEN`, never a retrieval. ## Authorizations - **[BearerAuth](/api/agents/index.md#bearerauth)** ## Request Bodyrequired Media typeapplication/json *CreateScopeRequest* object **config** Any of: - [object](#tab-panel-0-0) - [null](#tab-panel-0-1) object ***key*** additional properties any null **display\_name** Any of: - [string](#tab-panel-1-0) - [null](#tab-panel-1-1) string <= 256 characters null **expires\_in\_seconds** Any of: - [integer](#tab-panel-2-0) - [null](#tab-panel-2-1) integer \>= 60 null **key** Any of: - [string](#tab-panel-3-0) - [null](#tab-panel-3-1) string <= 256 characters null ##### Examplegenerated ```json { "config": {}, "display_name": "example", "expires_in_seconds": 1, "key": "example" } ``` ## Responses ### 200 An existing scope, replayed by `key`. Media typeapplication/json *ScopeResponse* object **client\_id** required *Client Id* string **client\_key** Any of: - [string](#tab-panel-4-0) - [null](#tab-panel-4-1) string null **config** Any of: - [object](#tab-panel-5-0) - [null](#tab-panel-5-1) object ***key*** additional properties any null **created\_at** required *Created At* string format: date-time **display\_name** Any of: - [string](#tab-panel-6-0) - [null](#tab-panel-6-1) string null **expires\_at** Any of: - [string](#tab-panel-7-0) - [null](#tab-panel-7-1) string format: date-time null **replayed** *Replayed* True when a create re-posted an existing key and this is the scope that key already names. boolean **scope\_id** required *Scope Id* UUID identifying this scope. Pass as scope\_id when creating sessions. string **state** required *State* string **tenant\_id** Any of: - [string](#tab-panel-8-0) - [null](#tab-panel-8-1) string null ##### Example ```json { "replayed": false } ``` ### 201 Successful Response Media typeapplication/json *ScopeResponse* object **client\_id** required *Client Id* string **client\_key** Any of: - [string](#tab-panel-9-0) - [null](#tab-panel-9-1) string null **config** Any of: - [object](#tab-panel-10-0) - [null](#tab-panel-10-1) object ***key*** additional properties any null **created\_at** required *Created At* string format: date-time **display\_name** Any of: - [string](#tab-panel-11-0) - [null](#tab-panel-11-1) string null **expires\_at** Any of: - [string](#tab-panel-12-0) - [null](#tab-panel-12-1) string format: date-time null **replayed** *Replayed* True when a create re-posted an existing key and this is the scope that key already names. boolean **scope\_id** required *Scope Id* UUID identifying this scope. Pass as scope\_id when creating sessions. string **state** required *State* string **tenant\_id** Any of: - [string](#tab-panel-13-0) - [null](#tab-panel-13-1) string null ##### Example ```json { "replayed": false } ``` ### 422 Validation Error Media typeapplication/json *HTTPValidationError* object **detail** *Detail* Array\ *ValidationError* object **ctx** *Context* object **input** *Input* **loc** required *Location* Array **msg** required *Message* string **type** required *Error Type* string ##### Examplegenerated ```json { "detail": [ { "ctx": {}, "input": "example", "loc": [ "example" ], "msg": "example", "type": "example" } ] } ```