Docs — GRAUNT

Start with the API

The OpenAPI 3.1 document at /openapi.json describes every machine surface that runs today — discovery, acquisition, entitlement delivery, account, seller, admin, and metadata endpoints. Operation IDs in the spec are stable; security scopes, response envelopes, and error shapes are documented inline. Agents that follow the .well-known discovery convention can also reach the contract at /.well-known/openapi.json.

Copy-paste quickstart (curl)

All examples target api.graunt.com. Replace placeholders before running. Responses are JSON envelopes shaped {ok, data} or {ok:false, error}.

1. Search active listings

curl https://api.graunt.com/v1/listings

2. Filter by starter-supply category

curl "https://api.graunt.com/v1/listings?starter_supply_slug=project-governance"

3. Get listing detail

curl https://api.graunt.com/v1/listings/<listing_id>

4. Get the packet manifest

curl https://api.graunt.com/v1/listings/<listing_id>/manifest

5. Inspect current pricing metadata

curl https://api.graunt.com/v1/meta/pricing

6. Inspect the capability registry (LIVE / PREVIEW / PLANNED / DISABLED / RESERVED / ABSENT)

curl https://api.graunt.com/v1/meta/capabilities

7. Register a buyer organization (programmatic onboarding)

curl -X POST https://api.graunt.com/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"name":"<org name>","email":"<ops@example.com>","password":"<at-least-12-chars>","type":"BOTH"}'

Verify email before purchases. The verification link arrives at the registered address.

8. Authenticate

curl -X POST https://api.graunt.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"<ops@example.com>","password":"<your-password>"}'

Response includes a JWT in data.token. Use it as Authorization: Bearer $JWT. (not yet operational) Public pre-purchase quote endpoint is not live. Today, agents should inspect listing price fields and /v1/meta/pricing, then send the buyer to checkout for the final total.

9. Acquire a free listing (authenticated)

curl -X POST https://api.graunt.com/v1/purchases \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $UUID" \
  -d '{"listing_id":"<listing_id>"}'

Paid purchases require Stripe Elements completion in a browser today; autonomous agent checkout is not part of the current public surface.

Human marketplace routes

/explore — paginated catalog (P7-3 canonical)
/sell — seller landing
/api-agents — agent-readable surface descriptor
/trust — trust model, evidence buckets, review gates
/pricing — pricing + commission reference
/help — support paths + recovery
/capability-status — 6-state capability registry

Machine-readable surfaces

/.well-known/ai-plugin.json — AI plugin manifest
/llms.txt — agent / crawler orientation
/v1/meta/pricing — canonical pricing metadata
/v1/meta/capabilities — 6-state capability registry (JSON)
/v1/meta/search-contract — deterministic search / discovery contract
/v1/meta/agent-surface — omnibus agent-readable contract
/v1/meta/agent-participation — participation contract (planned + gated programs)
/v1/meta/scanner-signals — bounded scanner-signal catalog
/v1/meta/seller-standards — machine-readable seller acceptance standards
/v1/meta/requirement-groups — composable packet requirement groups (SAFE public projection: constitution_version + group ids + per-group summaries)
/v1/meta/content-profiles — registered content profiles (validator-passable packet kinds + families + required requirement groups)
/v1/meta/constitution — ratified Packet Constitution version (constitution_version)

Listing and packet metadata

Every public listing response carries a rich, machine-readable metadata block (rights, provenance, publication metadata, asset class, file format, manifest status, etc.). Packet listings additionally carry a structured manifest with evidence references across the seven canonical buckets (INTEGRITY, STRUCTURE, FRESHNESS, RIGHTS, SAFETY, ORIGIN, DELIVERY_MATCH). See /v1/listings for the public discovery surface and per-listing detail at /v1/listings/{id} + /v1/listings/{id}/manifest.

Capabilities and current limits

The capability status page (and machine equivalent at /v1/meta/capabilities) labels every Graunt capability with one of six states — LIVE / PREVIEW / PLANNED / DISABLED / RESERVED / ABSENT. Use it as the source of truth before reading any other Graunt page.

If a feature in this docs page is labelled or implied by a route, but the capability registry reports it is not LIVE today, the registry wins.