Examples

Concrete examples of Graunt packet metadata, manifests, agent workflows, and search query patterns. These are illustrative shapes, not live inventory — see /explore for the current public listings and /openapi.json for the live API contract.

Packet listing metadata shape

Every public listing response carries a rich, machine-readable metadata block. Illustrative shape:

{
  "id": "<uuid>",
  "dataset_name": "Federal AI Use Case Inventory 2024",
  "category": "GOVERNMENT",
  "asset_class": "PACKET_BUNDLE",
  "file_format": "PDF",
  "price_cents": 0,
  "acquisition_mode": "PUBLIC_TOKEN_GRANT_FREE",
  "rights_block": {
    "license_family": "GOVERNMENT_PUBLIC_DOMAIN",
    "citation_required": true,
    "training_allowed": true,
    "redistribution_allowed": true,
    "personal_data_sensitive": false
  },
  "rights_passport": {
    "access_mode": "OPEN_PUBLIC",
    "delivery_mode": "STANDARD_DOWNLOAD",
    "agent_access_allowed": true
  },
  "publication_metadata": {
    "publisher_name": "U.S. Office of Management and Budget",
    "publisher_role": "GOVERNMENT",
    "publication_date": "2024-12-01",
    "language": "en",
    "jurisdictions": ["US"]
  },
  "packet_bundle": {
    "asset_count": 328,
    "manifest_sha256": "sha256:<hex>",
    "total_bytes": 1234567890
  }
}

Packet manifest shape

Packet listings expose a structured manifest at GET /v1/listings/{id}/manifest. Pilot-stage signed listings additionally carry integrity headers. Illustrative shape:

{
  "kind": "PACKET_BUNDLE_MANIFEST_PUBLIC",
  "bundle_id": "<uuid>",
  "revision_id": "<uuid>",
  "manifest_sha256": "sha256:<hex>",
  "asset_count": 328,
  "assets": [
    {
      "ordering": 1,
      "asset_role": "PRIMARY",
      "original_filename": "use-cases.csv",
      "file_format": "CSV",
      "file_size_bytes": 4456321,
      "content_sha256": "sha256:<hex>"
    }
  ]
}

Scanner signal shape

Scanner outputs are bounded disclosure signals. They feed Graunt's append-only scanner-history substrate and the audit log; they never auto-block publication or change ranking. Illustrative shape (LLM-origin):

{
  "schema_version": 1,
  "status": "scanned",
  "llm_signals_present": false,
  "confidence": "low",
  "detector_version": "graunt-heuristic-1.0.0",
  "caveats": [
    "DISCLOSE_ONLY signal",
    "presence indicator only; not a determination of intent or impact"
  ]
}

For the prompt-injection-risk and credential-pattern signals (default-OFF at v0 substrate), output is bounded category counts only — no raw matched text and no raw secret values.

Agent discovery workflow

Read the orientation manifest at /llms.txt for current entry points.
Read the OpenAPI contract at /openapi.json for the live machine surface.
Read the agent-surface contract at GET /v1/meta/agent-surface for the structured agent-readable description (trust primitives, scanner signals, participation, search contract, roadmap direction).
Read the seller / agent acceptance standards at GET /v1/meta/seller-standards before preparing or recommending a packet.
Search at GET /v1/listings?q=...&packet_family=...&asset_class=...&min_price=.... Use the machine-readable GET /v1/meta/search-contract for the supported parameter set and validation behavior.
Inspect at GET /v1/listings/{id} for declared rights, the rights passport, publication metadata, packet checks, and (for packets) the manifest reference.
Authenticate the buyer organization (one-time setup; the buyer-org operator holds credentials and controls spend / approval policy).
Acquire via POST /v1/purchases. Free listings clear immediately; paid listings complete through the buyer-organization's Stripe Elements confirmation in a browser today, with delegated agent purchasing planned for a future slice.
Deliver via GET /v1/entitlements/{entitlement_id}/packet-bundle — manifest + short-lived presigned URLs per asset.

Commissioned packet preparation workflow

Commissioned-packet workflows let builders prepare packet materials under an organization's account. Stage 1 (founder-org) is live; future stages widen the path. Illustrative flow:

Open a commission request describing packet family, packet kind, source constraints, and budget / bounty terms.
Prepare materials — manifest, evidence references, rights / provenance declarations.
Submit for review — the commissioned listing lands in PENDING_REVIEW like any other listing.
Founder / admin review — same publication gate as the self-listed path; rights, provenance, and scanner signals reviewed.
Publication — on approval, the listing becomes ACTIVE and the allocation ledger records builder attribution.

External commissioned-builder identities are part of the roadmap (Stage 2 widens the path); today the publication gate remains under operator approval.

Future attribution-aware participation

The allocation ledger reserves contributor role kinds today and ships role-widening through future participation slices. Illustrative future row shape (for explanation only — not all role kinds emit allocation rows today):

{
  "purchase_id": "<uuid>",
  "participant_org_id": "<uuid>",
  "role_kind": "BUILDER",
  "attribution_type": "COMMISSIONED",
  "reward_kind": "ATTRIBUTION_ONLY",
  "pool_basis": "OUTSIDE_TRANSACTION",
  "status": "ACCRUED"
}

Reward kinds available today are CASH (for live seller and platform allocation) and ATTRIBUTION_ONLY (for non-cash attribution). GRAUNT_CREDIT and REPUTATION_POINT are reserved in the enum; closed-loop, non-tradable, never marketed as "tokens" or "cashable instruments" in the alpha horizon.

Search query patterns

Hard filters never affect ranking; ranking is ts_rank_cd × title_coef. Every example below is a real, supported query under the current /v1/meta/search-contract (schema_version 2). Unsupported filters reject with HTTP 400 — the contract's unsupported_filters block documents every term agents are likely to guess.

Free evaluation packets, JSONL: GET /v1/listings?packet_family=EVALUATION&file_format=JSONL&free_only=true
Government-published reference data: GET /v1/listings?packet_family=REFERENCE_DATA
Signed-manifest packets only: GET /v1/listings?requires_signed_manifest=true
Industry-tag descendants: GET /v1/listings?industry_tag=energy_utilities
Canonical taxonomy tag (aliases rewrite): GET /v1/listings?tag=rag-corpus — matches listings whose persisted tags[] include the canonical rag-corpus. Aliases like ?tag=rag rewrite transparently; unknown tokens reject with 400.
Canonical class filter: GET /v1/listings?tag_class=asset-type — matches listings whose persisted tags[] overlap with the canonical set for the asset-type class.
Multi-asset packet bundles (≥ 2 assets): GET /v1/listings?has_bundle_assets=true&min_bundle_asset_count=2
Provenance-rich packets with a DOI: GET /v1/listings?has_publication_metadata=true&has_doi=true
Packets with declared evidence references: GET /v1/listings?has_evaluated_evidence=true

The tag and tag_class filters match against the persisted listings.tags[] array (canonical taxonomy values). Server-derived taxonomy chips on listing summaries / detail pages are informational and do not by themselves make a listing reachable by tag= — sellers can adopt suggested canonical tags through the existing seller update path. The complete supported-parameter set, validation behavior, ranking invariants, and the canonical tag taxonomy live at GET /v1/meta/search-contract.