Skip to content
Agents
Scopes

Create Scope

POST
/v1/scopes
curl --request POST \
--url https://agents.lumalabs.ai/v1/scopes \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "config": {}, "display_name": "example", "expires_in_seconds": 1, "key": "example" }'

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.

Media typeapplication/json
CreateScopeRequest
object
config
Any of:
object
key
additional properties
any
display_name
Any of:
string
<= 256 characters
expires_in_seconds
Any of:
integer
>= 60
key
Any of:
string
<= 256 characters
Examplegenerated
{
"config": {},
"display_name": "example",
"expires_in_seconds": 1,
"key": "example"
}

An existing scope, replayed by key.

Media typeapplication/json
ScopeResponse
object
client_id
required
Client Id
string
client_key
Any of:
string
config
Any of:
object
key
additional properties
any
created_at
required
Created At
string format: date-time
display_name
Any of:
string
expires_at
Any of:
string format: date-time
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
Example
{
"replayed": false
}

Successful Response

Media typeapplication/json
ScopeResponse
object
client_id
required
Client Id
string
client_key
Any of:
string
config
Any of:
object
key
additional properties
any
created_at
required
Created At
string format: date-time
display_name
Any of:
string
expires_at
Any of:
string format: date-time
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
Example
{
"replayed": false
}

Validation Error

Media typeapplication/json
HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
ctx
Context
object
input
Input
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
Examplegenerated
{
"detail": [
{
"ctx": {},
"input": "example",
"loc": [
"example"
],
"msg": "example",
"type": "example"
}
]
}