Skip to content

Saved context

Saved context is an account's or person's curated selection of relevant services, time-series families, and event searches. Each entry is period-free: the application supplies the period, requested time-series resolution, and event location at runtime.

Three distinct context types

Context type What it stores What it resolves
Data services and sources Explicit service/source selections plus catalogue classifications and tags Published data-service catalogue entries
Time series Family, grouped-service, source, classification, tag, and quality selections; source/quality preferences One row per family and its best authorized concrete variant
Events Event-feed/source selections plus occurrence types, subtypes, tags, countries, regions, attendance/status, flags, and text Actual event occurrences from every matching feed

The shared shell is deliberately small: name, icon, order, account or personal scope, ownership, optimistic version, and health. The three definitions and their resolution rules are separate. A time-series collection is not treated as an event query.

Scope and security

  • An account context entry is visible to every authenticated user in the same active account. Creating, changing, or archiving one requires the account's catalogue editor role.
  • A personal context entry is visible and editable only by whoever created it: the person signed in to the admin, or, through the API, the API key that created it.
  • Clients never submit an account or personal owner. Both come from the verified caller: your company for an API key, you when signed in.
  • Resolving or querying context reapplies normal catalogue and row visibility. A saved reference cannot grant access.
  • An unavailable explicit reference leaves the context visible with needs_attention and a non-disclosing issue count.

Manage saved context

Use GET /v1/saved-context to populate preferred navigation. Create a typed definition with POST /v1/saved-context, replace it with PUT /v1/saved-context/{contextGid}, and archive it with DELETE /v1/saved-context/{contextGid}?expectedVersion=…. Updates require the latest expectedVersion, preventing one session from silently overwriting another.

The authenticated API reference and test console documents all fields and runs these requests against the live service.

Create a single favorite time-series family with the minimum definition:

{
  "kind": "time_series",
  "scope": "personal",
  "name": "Gold OHLC",
  "slug": "gold-ohlc",
  "familyGids": ["<family UUID>"]
}

Create shared event context in the same endpoint, with event filters rather than catalogue families:

{
  "kind": "events",
  "scope": "account",
  "name": "Live football",
  "slug": "live-football",
  "eventTypes": ["TVBroadcast"],
  "tags": ["football"],
  "flags": {"live": true}
}

Copy the returned version into expectedVersion when replacing the definition, or into the archive query parameter. Account scope requires the catalogue editor role; personal scope does not.

Save any query as context

Every service query page in the admin (a time series, a data-service member series, an event feed, a lookup) carries ☆ Add this query to my context. One click creates a personal saved context of the matching kind for the service shown — the family of a time series with its source preferred, the data service itself, the event feed with the type, status, attendance-mode and text filters currently in the form, or the lookup service — and opens it. The time and location box is not stored: a saved context selects what, callers supply when and where at query time. Once the service is in your context the button turns into ★ In saved context and opens it. Families keep their own button on the family page.

Load favorites in an application

Fetch relevant context once after sign-in. The response combines shared account context and the caller's personal context; q searches names, descriptions, and slugs, while nextCursor continues longer lists.

GET https://quicklookup.com/api/v1/saved-context?limit=50
Authorization: Bearer <your API key>

For example, GET /v1/saved-context?q=football&kind=events returns matching event context before the application queries one.

{
  "items": [
    {
      "gid": "<context UUID>",
      "kind": "time_series",
      "scope": "personal",
      "name": "Gold OHLC",
      "status": "ready",
      "familyGids": ["<family UUID>"]
    },
    {
      "gid": "<context UUID>",
      "kind": "events",
      "scope": "account",
      "name": "Live football",
      "status": "ready",
      "eventTypes": ["TVBroadcast"],
      "tags": ["football"],
      "flags": {"live": true}
    }
  ],
  "nextCursor": null
}

Resolve catalogue-oriented context when the user opens it:

GET https://quicklookup.com/api/v1/saved-context/<context UUID>/items
Authorization: Bearer <your API key>

The kind tells the client how to use the context. data_services and time_series use the items endpoint. events uses the event-query endpoint with the application's runtime period and optional location; saved context supplies only its reusable feed and event filters.

Open time-series context

Call GET /v1/saved-context/{contextGid}/items. Optionally add from, to, and resolution to influence concrete-variant selection for this request. They are never written back to saved context. Each family returns its recommended concrete queryUrl; query that URL with the normal required period.

A favorite time series is simply personal context whose familyGids contains one family. Use Add to my context on a family page, or create the same definition through the API. It still follows the family's best available source and quality automatically.

Query event context

Call POST /v1/saved-context/{contextGid}/events/query with:

{
  "from": "2026-09-12T00:00:00Z",
  "to": "2026-09-13T00:00:00Z",
  "near": {"longitude": -21.9426, "latitude": 64.1466, "radiusKm": 25},
  "order": "distance_asc",
  "limit": 100
}

The service applies the saved occurrence filters—such as TVBroadcast and flags.live=true—to every selected visible feed, merges the results, and returns an opaque nextCursor. Send that cursor with the same runtime request for the next page. Omit near and use starts_asc or starts_desc when location is irrelevant.

Use saved context through MCP

An agent can call list_saved_context, inspect a result with get_saved_context, then call resolve_saved_context or query_saved_event_context. These tools are read-only and use the same scope, definitions, runtime inputs, results, and cursors as REST. See Integrate with QuickLookup for the complete tool list.