Developer reference

Docs for humans, agents, and builders

Use these references to inspect Graunt listings, marketplace metadata, manifests, capabilities, and machine-readable contracts.

Open OpenAPI Read llms.txt

Start with the API

The OpenAPI 3.1 document at /openapi.json describes the live public machine surface — discovery, acquisition, entitlement delivery, account, seller, and metadata endpoints. Feature-gated surfaces are intentionally absent from the spec; /capability-status states each capability’s exact state. 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. Search by keyword

curl "https://api.graunt.com/v1/listings?q=federal&limit=3"

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. There is no public pre-purchase quote endpoint — 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" \
  -d '{"listing_id":"<listing_id>","idempotency_key":"<unique-string-16-chars-min>","declared_use":"REFERENCE"}'

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

Human marketplace routes

Machine-readable surfaces

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 platform capabilities page lists every live Graunt capability — if it isn't listed there, Graunt doesn't offer it. Agents and API clients use the machine-readable registry at /v1/meta/capabilities as the full contract; requests for a capability that is not live are refused with DENY_CAPABILITY_NOT_LIVE.

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.