Skip to content
Embabel Worlds

Pin a captured scope: clear its expiry so it survives until explicitly deleted

POST
/api/v1/admin/kg/scopes/{name}/pin
curl --request POST \
  --url http://localhost:11044/api/v1/admin/kg/scopes/example/pin \
  --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
name
required
string

The scope’s name as given in captureAs (the identifier referenced as $name in a query, without the $), among the acting user’s scopes; 404 when there is no such live scope, including one that has already expired

Query Parameters

Section titled “Query Parameters”
username
string

Username whose scopes to act on, honoured only when the request has no authenticated principal (dev-mode calls); an authenticated caller always acts on its own scopes. 401 when neither resolves to a user

Responses

Section titled “Responses”

200

Section titled “200”

The scope as stored, now with no expiry

Media typeapplication/json

A captured query scope: a frozen result set referenced in a later query as (x:$name).

object
capturedAt
required

When the membership froze, ISO-8601.

string
expiresAt

When the scope lapses, ISO-8601 — null means PINNED (kept until deleted).

string
members
required

How many members the capture froze. Membership is frozen; values stay live.

integer format: int64
name
required

The name the scope was captured under, unique per user; a later query binds it as (x:$name).

string
outputLabel
required

The node label later references bind with.

string
statement
required

The statement that produced the capture — the scope’s provenance.

string

Example generated

{
  "capturedAt": "example",
  "expiresAt": "example",
  "members": 1,
  "name": "example",
  "outputLabel": "example",
  "statement": "example"
}

401

Section titled “401”

No authenticated principal and no resolvable username

Media typeapplication/json

A refusal carrying only a human-readable reason.

object
error
required

What went wrong, in the terms the caller can act on.

string

Example generated

{
  "error": "example"
}

404

Section titled “404”

No such scope (or it already expired)

Media typeapplication/json

A refusal carrying only a human-readable reason.

object
error
required

What went wrong, in the terms the caller can act on.

string

Example generated

{
  "error": "example"
}