The Handshake — one call, one budgeted Precision Bundle.

Endpoint

POST https://api.osenv.io/api/v1/handshake
Content-Type: application/json

No authentication required. The Handshake is part of the read-side floor — free, public, rate-limited only by sane defaults.

Request body

All fields are optional. Send {} to retrieve the highest-quality recent windows from the entire corpus, packed to the default 6,000-character budget.

{
  "spaces":          ["fintech", "security"],
  "windowTypes":     ["SCHEMA", "ANTI_PATTERN"],
  "windowTags":      ["drop-in-ready", "gotcha"],
  "patternTags":     { "FORM": ["recipe"], "RISK": ["safe-default"] },
  "qualityMin":      0.5,
  "maxChars":        6000,
  "maxWindows":      24,
  "includeOwnerKept": false
}

Filter semantics

• spaces — OR. The artifact must be in at least one of these Spaces. Empty or omitted = any Space.
• windowTypes — OR. The window must have one of these structural types. Allowed values: GOAL, BACKGROUND, CONSTRAINT, INSTRUCTION, SCHEMA, TOOL_SPEC, EXAMPLE, EXPECTED_OUTPUT, TEST, ANTI_PATTERN, PERSONA, SYSTEM.
• windowTags — AND. The window must carry every one of these functional tags. Allowed values: reusable-skeleton, drop-in-ready, gotcha, config-template, edge-case-handler, gold-standard-example.
• patternTags — within a kind, OR; across kinds, AND. Pattern-tag kinds are FORM, AUDIENCE, AUTHORITY, LIFECYCLE, RISK. See the Precision Bundle docs for the full kind catalogue.
• qualityMin — minimum parent-artifact quality_score (0.0–1.0).
• maxChars — character budget for the packed result. Default 6000. Range 100–60000.
• maxWindows — hard cap on result count. Default 24. Range 1–100.
• includeOwnerKept — preview flag. When true, the bundle also draws from OWNER_KEPT artifacts (community-unreviewed). Default false. Use this in playgrounds and demos; production agents should leave it off.

Response shape

{
  "status": "ok",
  "data": {
    "windows": [
      {
        "windowId":          "uuid",
        "windowType":        "SCHEMA",
        "sequenceIndex":     2,
        "content":           "",
        "contentHash":       "sha256-hex",
        "tokenCount":        null,
        "tags":              ["drop-in-ready"],
        "rationale":         "",
        "sourceInferenceRunId": "uuid",
        "manifest": {
          "manifestId":        "uuid",
          "manifestVersionId": "uuid",
          "publicContextId":   "ctx-...",
          "slug":              "...",
          "title":             "...",
          "publicationStatus": "PUBLISHED",
          "qualityScore":      0.85,
          "spaces":            [{ "slug": "fintech", "displayName": "Fintech" }, ...]
        }
      }
    ],
    "count":       7,
    "totalChars":  1286,
    "budgetLimit": 6000,
    "exhausted":   false
  },
  "meta": {
    "resourceType":           "PrecisionBundle",
    "schema":                 "fsv_handshake_v0",
    "transport":              "REST",
    "filtersApplied":         { ... echoed back },
    "includesPreviewContent": false
  }
}

Provenance on every window

Every returned window carries:

• contentHash — sha256 of the slice. The same content, retrieved later, produces the same hash even after manifest re-versions.
• sourceInferenceRunId — the WINDOW_INDEX inference run that produced this window. Joinable with fsv_inference_run for full audit (model, tokens, latency, raw output).
• manifest.qualityScore — current quality_score of the parent artifact. Use this if the bundle's recency rank doesn't match your trust appetite.
• manifest.publicationStatus — PUBLISHED means community-reviewed. OWNER_KEPT means owner-kept but not yet community-validated; only present if includeOwnerKept: true.

Ranking

Candidate windows are ordered by quality_score DESC NULLS LAST, then published_at DESC NULLS LAST, then created_at DESC, then sequence_index ASC. The packer takes the highest-ranked window first and continues greedily until maxChars or maxWindows is reached. exhausted: true means the budget filled before all matching windows were considered.

Examples

1. Curl — fintech schemas, drop-in-ready only

curl -X POST https://api.osenv.io/api/v1/handshake \
  -H 'Content-Type: application/json' \
  -d '{
    "spaces":     ["fintech"],
    "windowTypes": ["SCHEMA"],
    "windowTags":  ["drop-in-ready"],
    "maxChars":    4000
  }'

2. Python — anti-patterns by risk profile

import requests

bundle = requests.post(
    "https://api.osenv.io/api/v1/handshake",
    json={
        "windowTypes":  ["ANTI_PATTERN"],
        "patternTags":  {"RISK": ["destructive", "cost-sensitive"]},
        "maxChars":     3000,
    },
    timeout=10,
).json()

for w in bundle["data"]["windows"]:
    print(f"[{w['windowType']}] {w['manifest']['title']}: {w['content']}")

3. JavaScript — fold the bundle into a system prompt

const r = await fetch("https://api.osenv.io/api/v1/handshake", {
  method: "POST",
  headers: {"Content-Type": "application/json"},
  body: JSON.stringify({
    spaces:      ["security"],
    windowTypes: ["CONSTRAINT", "ANTI_PATTERN"],
    maxChars:    5000,
  }),
});
const bundle = await r.json();

const systemPrompt = bundle.data.windows
  .map(w => `[${w.windowType}] (${w.manifest.title})\n${w.content}`)
  .join("\n\n---\n\n");

Limits and rate

The Handshake is rate-limited at the nginx layer with sane per-IP defaults. Authenticated callers (with an API key in Authorization: Bearer <key>) get higher quota. Hard limits on a single call:

• maxChars ≤ 60,000
• maxWindows ≤ 100
• Request body ≤ 16 KB

Try it live

The Handshake Playground lets you fire requests against the live corpus from the browser, with all filter axes exposed as form fields and the response rendered inline.