Unified context query

The platform-native Context Platform read surface: one authorization-safe router over eight registered providers (Knowledge, Adoption, Delivery Health, Decisions, vSOW snapshots, Relationships, Context Opportunities, and derived Context Concepts). Supports search, get_projection, get_object, and list_objects. Opportunity is included in the bounded default search; Concept is project-scoped, must be requested explicitly, supports search/get_object/list_objects, and is derived on read rather than persisted. Returns per-provider execution status, item authority, per-provider + aggregate freshness and coverage, limitations, partial failure, and an opaque continuation cursor. The context-engine:read scope grants ENTRY; each provider then applies its own permission and visibility, so holding the scope does not grant any domain's data. Distinct from the legacy /api/v1/context/search (Knowledge-only evidence) and /api/v1/context/query (deterministic Context Package briefing), which remain supported. The router is read-only: it never approves, mutates, or synthesizes.

POST/api/v1/context/unified

Authorization

context-engine:readapi key scoperequired

Required scope when calling with an API key.

Request body

operationstringrequired

One of: search, get_projection, get_object, list_objects.

subjectobjectrequired

{ type, id }. Supported subject types depend on the addressed providers (e.g. project, engagement, account, commitment).

domainsarrayoptional

Explicit domains from the runtime contract: knowledge, adoption, delivery, decision, execution, commitment, resource, financial, relationship, opportunity, concept. A provider is selected only when it implements the requested operation and subject. Omitting domains for search uses the bounded default knowledge + delivery + decision + opportunity; it never fans out to all eight providers. Concept is never in the default.

querystringoptional

Required for search (1–500 chars).

projectionstringoptional

Required for get_projection. Implemented today: delivery.health.

object_idstringoptional

Required for get_object. Namespaced, e.g. decisions-context:<source_id>, opportunity:<uuid>, or concept:<hash>.

kindsarrayoptional

Optional item-kind filter: evidence, fact, decision, inference, signal, risk, projection, definition, snapshot, opportunity, concept.

include_evidencebooleanoptional

Request evidence references where a provider supports them.

include_historybooleanoptional

Include historical/superseded objects in list_objects (default true).

occurred_afterstringoptional

ISO timestamp lower bound.

occurred_beforestringoptional

ISO timestamp upper bound.

limitnumberoptional

Max results (max 100).

cursorstringoptional

Opaque router continuation cursor from a prior response. Treat as opaque; reuse only with the same operation/subject/domains/query/filters.

Example request

{
  "operation": "search",
  "subject": {
    "type": "project",
    "id": "24ea6df2-7f4c-4c32-9fc1-6c8a0cb5b4b2"
  },
  "domains": [
    "knowledge",
    "adoption",
    "decision"
  ],
  "query": "tax category decision",
  "limit": 25
}

Request

POST /api/v1/context/unified

curl -X POST "https://www.digitalstack360.com/api/v1/context/unified" \
  -H "Authorization: Bearer $DS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"operation":"search","subject":{"type":"project","id":"24ea6df2-7f4c-4c32-9fc1-6c8a0cb5b4b2"},"domains":["knowledge","adoption","decision"],"query":"tax category decision","limit":25}'

Examples use a placeholder key from your environment. Store your key in $DS_API_KEY — never commit it.

Response

200 OK

{
  "data": {
    "subject": {
      "type": "project",
      "id": "24ea6df2-7f4c-4c32-9fc1-6c8a0cb5b4b2"
    },
    "operation": "search",
    "query": "tax category decision",
    "outcome": "partial",
    "providers": [
      {
        "provider_id": "adoption-context",
        "status": "success",
        "items": [],
        "freshness": {
          "status": "current",
          "basis": "source"
        },
        "coverage": {
          "status": "partial"
        },
        "limitations": []
      },
      {
        "provider_id": "decisions-context",
        "status": "timed_out",
        "items": [],
        "freshness": {
          "status": "unknown",
          "basis": "unknown"
        },
        "coverage": {
          "status": "unknown"
        },
        "limitations": [
          {
            "code": "provider_timed_out",
            "provider_id": "decisions-context",
            "message": "The provider did not respond within the time limit."
          }
        ]
      },
      {
        "provider_id": "knowledge-corpus",
        "status": "success",
        "items": [],
        "freshness": {
          "status": "unknown",
          "as_of": "2026-06-01T00:00:00Z",
          "basis": "source"
        },
        "coverage": {
          "status": "partial"
        },
        "limitations": []
      }
    ],
    "results": [
      {
        "id": "knowledge-corpus:span-1",
        "kind": "evidence",
        "domain": "knowledge",
        "statement": "Tax-category mapping uses Shopify Tax…",
        "authority": {
          "authority_type": "compatibility_projection",
          "owning_domain": "knowledge",
          "owning_system": "engagement-knowledge-corpus",
          "mutable_here": false
        },
        "evidence": [
          {
            "provider_id": "knowledge-corpus",
            "source_id": "…",
            "source_type": "document",
            "page": 4,
            "paragraph": 2,
            "provenance_quality": "exact"
          }
        ]
      }
    ],
    "freshness": {
      "status": "mixed",
      "by_provider": {}
    },
    "coverage": {
      "requested_domains": [
        "knowledge",
        "adoption",
        "decision"
      ],
      "searched_domains": [
        "knowledge",
        "adoption"
      ],
      "unsupported_domains": [],
      "failed_domains": [
        "decision"
      ],
      "by_provider": {}
    },
    "truncated": false,
    "limitations": []
  },
  "meta": {
    "request_id": "req_…",
    "outcome": "partial"
  }
}

Errors

401

missing_auth

No credentials provided

401

invalid_api_key

API key is invalid or revoked

400

bad_request

Invalid body, unknown operation/domain/kind, missing operation-required field, oversized query/cursor, or malformed cursor

403

scope_insufficient

Key lacks context-engine:read scope