Search context evidence

Full-text search of ACTIVE evidence spans in the Engagement Knowledge Corpus, bound to an authorized project or engagement. Returns ranked passages with source provenance (page/paragraph/section, provenance quality), honest scope, freshness, and keyset continuation — evidence, never a synthesized answer. Project queries search directly-bound sources; engagement queries fan out to caller-visible child projects (direct engagement-bound sources are not yet supported). PostgreSQL full-text retrieval; no semantic/vector search. Requires the context-engine:read scope (agent:read alone is insufficient) plus the context:read permission.

POST/api/v1/context/search

Authorization

context-engine:readapi key scoperequired

Required scope when calling with an API key.

context:searchsession capabilityoptional

Required capability when calling with a signed-in session.

Request body

subject_refobjectrequired

Deterministic subject: { type: project|engagement, id: UUID }.

querystringrequired

Search text (websearch syntax; 1–500 chars).

include_parent_contextbooleanoptional

Project queries only. Currently returns an unsupported scope state (engagement binding not yet available).

include_child_projectsbooleanoptional

Engagement queries: fan out to visible child projects. Default true.

source_typesarrayoptional

Optional source_type filter.

occurred_afterstringoptional

ISO timestamp lower bound on source occurrence.

occurred_beforestringoptional

ISO timestamp upper bound on source occurrence.

limitnumberoptional

Max results (default 20, max 100).

cursorstringoptional

Opaque keyset continuation cursor from a prior response.

Example request

{
  "subject_ref": {
    "type": "project",
    "id": "24ea6df2-7f4c-4c32-9fc1-6c8a0cb5b4b2"
  },
  "query": "Shopify Tax"
}

Request

POST /api/v1/context/search

curl -X POST "https://www.digitalstack360.com/api/v1/context/search" \
  -H "Authorization: Bearer $DS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject_ref":{"type":"project","id":"24ea6df2-7f4c-4c32-9fc1-6c8a0cb5b4b2"},"query":"Shopify Tax"}'

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",
      "display_name": "Replatform"
    },
    "query": {
      "text": "Shopify Tax"
    },
    "scope": {
      "direct_sources": {
        "status": "supported",
        "included": true
      },
      "parent_context": {
        "status": "unsupported",
        "reason": "engagement_binding_not_available",
        "included": false
      },
      "child_projects": {
        "status": "not_applicable",
        "included": false
      },
      "projects_examined": 1,
      "projects_excluded": 0
    },
    "results": [
      {
        "span_id": "…",
        "text": "Tax-category mapping uses Shopify Tax…",
        "rank": 0.91,
        "source_id": "…",
        "source_title": "Tax Design",
        "source_type": "document",
        "subject_binding": {
          "type": "project",
          "id": "…",
          "name": "Replatform"
        },
        "match_origin": "direct",
        "page": 4,
        "paragraph": 2,
        "section": null,
        "provenance_quality": "exact",
        "occurred_at": "2026-06-01T00:00:00Z",
        "source_ingested_at": "2026-07-01T00:00:00Z",
        "content_version": 1,
        "segmentation_version": 1,
        "stored_document_id": "…"
      }
    ],
    "freshness": {
      "status": "mixed",
      "oldest_source_at": "2026-06-01T00:00:00Z",
      "newest_source_at": "2026-06-01T00:00:00Z"
    },
    "coverage": {
      "sources_matched": 1,
      "projects_examined": 1,
      "note": "result-scoped; corpus denominator not asserted"
    },
    "truncated": false,
    "continuation": null
  }
}

Errors

401

missing_auth

No credentials provided

401

invalid_api_key

API key is invalid or revoked

400

bad_request

Invalid subject_ref, empty/oversized query, or bad limit/cursor

403

scope_insufficient

Key lacks context-engine:read scope

404

not_found

Subject is outside the workspace or not visible