Agent Access on Graunt

Use Graunt's machine-readable catalog to discover, inspect, compare, and acquire evaluated packets with rights, provenance, pricing, manifest, and entitlement context.

What agents can read today

How an agent uses Graunt today

Acquire a free packet (e.g., Packet 3 — OMB Federal AI Use Case Inventory)

  1. Discover via GET /v1/listings?per_page=20. Pick the listing where is_free=true and asset_class=PACKET_BUNDLE.
  2. Inspect via GET /v1/listings/{id}. Confirm rights_block.training_allowed, rights_passport.agent_access_allowed, and the bundle asset_count + manifest_sha256.
  3. Authenticate as a registered organization. POST /v1/auth/login returns a 24-hour JWT. (One-time setup: POST /v1/auth/register with type=BOTH and complete email verification.)
  4. Acquire via POST /v1/purchases with body {listing_id, idempotency_key, declared_use}. Free listings clear immediately to status=COMPLETED with free_acquisition=true; client_secret is null (Stripe is skipped on the free path).
  5. Deliver via GET /v1/entitlements/{entitlement_id}/packet-bundle. Returns a manifest body with asset_count, manifest_sha256, and one short-lived presigned URL per asset.

Acquire a paid packet (e.g., the SEC Marketing Rule reference packet at $2.50)

  1. Discover + Inspect as above. Paid listings carry price_cents > 0 and the commercial_terms block surfaces processing fee, delivery fee, and buyer total. Full marketplace pricing metadata lives at GET /v1/meta/pricing.
  2. Authenticate as a registered buyer organization. The buyer org's verification_tier must clear the listing's min_buyer_tier (default REGISTERED — verified email).
  3. Initiate purchase via POST /v1/purchases. The response includes a Stripe client_secret for the PaymentIntent created on the buyer's behalf, along with the listing's delivery_kind.
  4. Complete payment. Today: the buyer organization's operator completes the payment in a browser at /buyer/checkout/{listing_id} (Stripe Elements mounted on Graunt). The publishable key is fetched from GET /v1/meta/stripe-publishable-key and the client confirms the PaymentIntent against the same Stripe account that issued the secret. Fully autonomous agent paid checkout is on the roadmap (delegated agent purchasing under buyer-defined credentials, spend controls, approval policies, and audit records); it is not the current public surface.
  5. Observe completion. Stripe webhook flips the purchase to COMPLETED and creates the entitlement. The agent polls GET /v1/purchases/{id} or GET /v1/entitlements?per_page=10.
  6. Deliver via GET /v1/entitlements/{entitlement_id}/packet-bundle. Same shape as the free path.

Create a listing (seller-side agent flow)

  1. Authenticate as a seller organization (type SELLER or BOTH, status ACTIVE).
  2. Open an upload session: POST /v1/packet-upload-sessions with body {idempotency_key, name, description}. Returns session_id and a new bundle_id.
  3. Register each asset: POST /v1/packet-upload-sessions/{sid}/assets with {original_filename, declared_size_bytes, declared_content_sha256, declared_role, ordering, file_format}. Returns a presigned PUT URL with the matching content-type.
  4. Upload bytes: PUT the file to the presigned URL. Include header x-amz-server-side-encryption: AES256.
  5. Finalize: POST /v1/packet-upload-sessions/{sid}/finalize with {idempotency_key}. Returns bundle_revision_id, manifest_sha256, and the validated asset_count.
  6. Create the listing: POST /v1/listings with body referencing packet_bundle_revision_id, plus price_cents, tags, rights_block, rights_passport, publication_metadata, industry_tag_codes, intended_uses, aup_version_acknowledged, aup_text_hash_acknowledged, idempotency_key.
  7. Admin review. The new listing lands in PENDING_REVIEW. An admin completes POST /v1/admin/listings/{id}/review with {decision: "APPROVED"} before it appears in the public catalog. Every seller path goes through the same review gate.

Idempotency: every write that creates a new resource accepts an idempotency_key (≥32 chars). Replays return the original response without re-executing side effects. Errors carry a machine-readable error.code (e.g., VALIDATION_ERROR, BUNDLE_NOT_FOUND, BUNDLE_ARCHIVED, EMAIL_VERIFICATION_REQUIRED, ORG_NOT_ACTIVE, EMAIL_IN_USE).

Account state, verification, and recovery

Every authenticated route returns structured precondition errors so an agent never has to guess what went wrong. A buyer or seller agent should always check the org's verification state before triggering paid flows or seller payout setup.

Actionable error codes returned by gated routes:

Human counterparts of these flows live at /account, /account/verify-email, /seller, and /buyer/checkout/{listing_id}. Errors include a recovery_suggestion string that mirrors the human-page CTA copy.

Accountable agent commerce

Graunt is built for agent-readable commerce: structured packet metadata, declared rights, provenance, Packet Evidence Records, prices, signed manifests, and entitlement paths are exposed so software can discover, compare, and prepare acquisition decisions.

Current paid purchase execution runs through authenticated buyer-organization accounts. Graunt's direction is delegated agent purchasing under buyer-defined credentials, permissions, spend controls, approval policies, and audit records — designed so authorized agents can transact without turning the marketplace into unauthenticated bot checkout.

Unauthenticated agent paid checkout is not part of the current public surface. Every paid purchase remains accountable to a registered buyer organization. Free listings (price_cents = 0) can additionally be acquired through the public-token-grant flow described above.

Fields agents should read before recommending an asset

See also /llms.txt for the orientation manifest and additional pointers.

Seller vs. source / publisher

Two distinct identifiers live on every listing and they should never be conflated:

Agents recommending an asset should surface both: who packaged it and where the underlying material comes from. Domains and email addresses (thelapidary.ai, etc.) are contact information, never seller display names.

Entitlement access policy

An entitlement is a durable access right, not a finite download coupon. Packet-bundle entitlements grant ongoing access according to listing terms; delivery is protected by per-call rate limits and short-TTL presigned URLs rather than by a lifetime download counter.

Entitlement responses (GET /v1/entitlements/{id}, GET /v1/entitlements?per_page=N) include both the legacy download_count / max_downloads fields (single-file safety) AND the canonical Pre P6-6 access-policy block:

{
  "access_status": "ACTIVE",
  "delivery_policy": {
    "mode": "RATE_LIMITED",
    "lifetime_download_limit": null,
    "presigned_url_ttl_seconds": 900,
    "max_urls_per_batch": 100
  },
  "rate_limit": {
    "limited": false,
    "retry_after_seconds": null,
    "policy": "per_org_per_entitlement_delivery_window"
  }
}

For packet-bundle entitlements, delivery_policy.lifetime_download_limit is null — access does not expire by usage. Single-file entitlements continue to echo the legacy lifetime cap until a follow-up slice replaces it with the Redis-backed per-window rate limit. Either way: agents and UIs should consume delivery_policy + rate_limit, not the legacy download_count diff.

Native bundle capacity

Native packet-bundle delivery is canonical. Multi-asset packets — including reference packets that ship hundreds of source documents alongside the primary data — are uploaded as a single packet_bundle_revision with one row per delivered file and a single manifest_sha256 covering the canonical inventory.

Optional ZIP archive export is reserved as a derived convenience artifact — it is generated from the canonical bundle revision when requested and is never the source of truth. Agents should consume the manifest and retrieve assets individually or through the bundle delivery route.

Machine surface

The OpenAPI document covers only endpoints that exist at runtime today. Roadmap surfaces (machine-native access, pools, demand signals, broader signing-key management) are feature-flagged off and are intentionally absent from the spec.

Search and discovery

Listing search is hard-filter first. The machine-readable contract at /v1/meta/search-contract (schema_version 2) describes every supported filter, groups them under filter_groups for clarity, and enumerates the canonical taxonomy under tag_taxonomy. Agents reading the contract can construct valid queries without scraping human pages.

Ranking is ts_rank_cd × title_coef. There is no quality coefficient, no seller-prestige boost, no agent-reputation multiplier, no composite trust score, and no hidden rerank. Manifest-completeness is a sort tiebreaker only when q is present. Common agent guesses that are not supported (verified_quality, quality_score, composite_trust_score, seller_prestige, training_safe, guaranteed_clean, scanner-presence filters while substrate is inert) live under unsupported_filters with their reason — that block is the contract's anti-hallucination guard.

Concrete search examples live at /examples. For seller-side guidance on which structured fields drive which filter groups, see /sellers/standards and the deterministic seller_discoverability_guidance block on the contract.

Forward direction

Graunt's long-term direction includes expanded machine participation across the marketplace lifecycle — agent-assisted supply creation, discovery, and procurement — with delegated agent purchasing under buyer-governed authority, spend controls, approval policies, and audit records. That capability is under development; no external program for it is open today.

Graunt is not affiliated with, partnered with, or endorsed by any specific model vendor or agent runtime. The marketplace is provider-neutral; references to LLMs and agents describe consumers of the data, not commercial partnerships.