Agent API

Start here

Three requests take an agent from nothing to a defensible acquisition decision. Discovery requires no account and no credential: search, listing detail (declared rights, provenance, the Packet Evidence Record, pricing in integer cents), and bundle manifests are all public reads. Examples target api.graunt.com; responses are JSON envelopes shaped {ok, data} or {ok: false, error}.

curl "https://api.graunt.com/v1/listings?q=marketing+rule&per_page=10"

curl https://api.graunt.com/v1/listings/{listing_id}

curl https://api.graunt.com/v1/listings/{listing_id}/agent-commerce-manifest

# Hand off: surface purchase_handoff.listing_url (from step 2)
# to your human buyer. No credential needed.

# Entitled read: list everything the buyer organization can access.
curl -H "Authorization: Bearer gap_live_YOUR_PASS" \
  https://api.graunt.com/v1/access-passes/manifest

Reading a listing

Listing detail (GET /v1/listings/{id}) carries everything an agent needs for a defensible recommendation. The load-bearing fields:

• rights_block — license family, citation requirement, no-train / no-redistribute / personal-data-sensitive flags.
• rights_passport — access mode, delivery mode, agent-access-allowed declaration (listing-level only).
• packet_manifest — for packet-overlay listings, the structured family / kind / sources / structure / evidence_refs payload.
• publication_metadata — publisher role, jurisdictions, language, publication date, standard identifiers.
• packet_checks — the Packet Evidence Record: bounded declared-rights, provenance, manifest, validation, and content-metadata signals.
• provenance — seller-declared source, fetched-at timestamp, version identifier, citation template.
• lineage — superseded_by_listing_id / replaces_listing_id for declarative supersession.
• pricing + purchase_handoff — integer-cent price and the hand-to-your-human block (below).

For pilot-stage signed listings, the manifest endpoint’s integrity headers carry the signing-key id, custody tier, and signature. See also /llms.txt for the orientation manifest.

Search and discovery

Listing search is hard-filter first. The machine-readable contract at /v1/meta/search-contract (schema_version 3) describes every supported filter, groups them under filter_groups, 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. Common agent guesses that are not supported live under unsupported_filters with their reason — the contract's anti-hallucination guard.

Try queries live against the catalog at /explore or GET /v1/listings?q=; seller-side discoverability guidance is the deterministic seller_discoverability_guidance block on the contract.

How an agent uses Graunt today

Acquire a free packet

1. Discover + inspect (quickstart steps 1–2). Pick a listing where is_free=true; confirm rights_block.training_allowed, rights_passport.agent_access_allowed, and the bundle asset_count + manifest_sha256.
2. 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.)
3. 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).
4. 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

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 pricing metadata: 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. The buyer organization’s operator completes the payment in a browser at /checkout/{listing_id} (Stripe Elements mounted on Graunt). The publishable key comes from GET /v1/meta/stripe-publishable-key; the client confirms the PaymentIntent against the same Stripe account that issued the secret.
5. Observe completion. Stripe webhook flips the purchase to COMPLETED and creates the entitlement. Poll 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. Automated publication. The new listing lands in PENDING_REVIEW and a publication-trust run starts automatically. Listings that clear the deterministic checks publish to the public catalog with no manual step; ones missing required information return a fix request to the seller; only flagged or sensitive-category listings hold for human review. Every seller path runs the same automated gate.

Test first: validate a packet manifest before you upload with POST /v1/refinery/validate (public, no auth) — the same deterministic presence / validation / coherence checks the Refinery runs on ingest. The contract is at GET /v1/meta/packet-assembly-contract; a human/agent reference plus a live validator are at /build-a-packet.

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).

Recommending a purchase to your human

An agent that finds a useful packet does not need purchase credentials to act on it: it hands the buy link to its human buyer. Both GET /v1/listings/{id} and GET /v1/listings/{id}/agent-commerce-manifest carry a purchase_handoff object with listing_url, checkout_url, price_cents, currency, is_free, and a locked instruction sentence.

1. Find a candidate via anonymous keyword search — GET /v1/listings?q=... requires no credential or account.
2. Read the purchase_handoff block from the listing detail JSON or the agent commerce manifest.
3. Hand off: surface purchase_handoff.listing_url and the price to your human buyer. The human opens the link, signs in, and completes checkout at checkout_url. Free listings carry checkout_url: null and route through the free-acquisition path instead.

The handoff itself needs no scope, token, or registration. Purchase execution remains with the authenticated human buyer organization; agents holding a scoped buy:execute credential can instead use the agent purchase endpoints in the surface map.

Packet access for an entitled agent

Once an organization holds an entitlement, an agent can pull the packet in the format its runtime supports. Pick the access mode by what the client can do.

• API key / header access. A durable read-only packet access key (POST /v1/entitlements/{id}/packet-access-keys, returned once) sent as Authorization: Bearer to GET /v1/entitlements/{id}/packet-access-manifest. Best for agents and apps that can send HTTP headers.
• Machine packet ZIP. GET /v1/entitlements/{id}/machine-zip returns a short-lived download URL for a ZIP with the packet manifest, router, indexes, content units, and the agent guide. Best for tools that work from uploaded files.
• Agent Access Link. A scoped, revocable, read-only browser link for an LLM that can open URLs but cannot set headers. It grants access to one packet revision until it expires; the raw token is shown once. POST /v1/entitlements/{id}/agent-access-links.
• Per-client access profile. POST /v1/entitlements/{id}/llm-access-profiles with the tools you use returns the best access format for each known client. It does not claim to work with every client.

Using a Graunt link

Every Graunt credential is also usable as one paste-able read-only URL. Assistants that fetch URLs can read entitled content through a pass link; API agents can continue to use Bearer credentials. Responses are Markdown by default; send Accept: application/json for the JSON envelope.

• Access-pass link. GET /p/{pass} (root with manifest / content / ask / resources links), /p/{pass}/content (licensed content with citations), /p/{pass}/ask?q={question} (cited source passages, no synthesis), /p/{pass}/resources/{id}. Read-only: it cannot purchase, change, or revoke anything.
• Discovery-key link. GET /k/{key} (root + instructions), /k/{key}/search?q={keywords} (attributed catalog metadata — hit/no-hit plus rights, price, and the purchase_handoff block), /k/{key}/listings/{id}. Public metadata only; never entitled content.

Original source files and Refinery-generated machine files are listed and counted separately in the manifest. Responses never carry a raw key, a verifier hash, or a long-lived storage URL.

Refinery → packets agents can use

Sellers prepare supply in the Refinery; what reaches the catalog is an evaluated packet, not a raw file. Every packet an agent reads carries declared rights, declared intended uses, and provenance grounding — all machine-readable before any decision.

• Declared intended_uses
  What the packet is built for: ai_training, ai_reference, agent_tool, evaluation, analytics.
• Provenance grounding
  Source records travel with the packet so an agent can trace where the material came from.
• Rights block
  License family, training & redistribution flags, citation requirement — declared, not inferred.
• Manifest hashes
  content_sha256 + packet_manifest_hash for integrity at delivery.

How a refined packet reads to an agent

Two example shapes (illustrative — browse the Marketplace for live packets):

Copy import JSON for your agent

An agent with a grnt_agent_* credential can submit a prepared packet. Preflight first, then submit — the result enters publication review through the canonical gate; the agent surface never publishes a listing directly.

POST /v1/agents/listings/submit
Authorization: Bearer grnt_agent_YOUR_AGENT_KEY
Content-Type: application/json

{
  "title": "US vendor master, normalized",
  "summary": "Deduplicated, schema-normalized vendor reference data.",
  "packet_kind": "vendor_master_normalization.v1",
  "delivery_format": "CSV",
  "intended_uses": ["ai_reference", "agent_tool"],
  "rights_basis": "owned_original"
}

Copy import JSON

Validate the shape first with POST /v1/agents/listings/preflight.

Test entitlement preview

Once a buyer holds an entitlement for a packet, fetch the bundle — the manifest, sidecars, and source assets resolve through short-lived presigned URLs scoped to the entitled delivery:

curl -H "Authorization: Bearer YOUR_BUYER_TOKEN" \
  https://api.graunt.com/v1/entitlements/{entitlement_id}/packet-bundle

Copy entitlement call

Live / refreshed feeds

A fixture-backed machine-only observation feed is callable today for an entitled, authenticated principal: GET /v1/feeds/{feedId}/manifest, /latest, /changes, /health, and POST /v1/feeds/{feedId}/sessions. It returns machine-readable observations only — no raw media or stream is included.

/capability-status states the exact state — available, preview, reserved, or provider-not-configured — for every access mode, including provider-backed live feeds, account snapshots, and pools.

Account state, verification, and recovery

Every authenticated route returns structured precondition errors so an agent never has to guess what went wrong. Check GET /v1/auth/me right after login and branch on status + email_verified; gated routes answer with machine-readable codes (EMAIL_VERIFICATION_REQUIRED, ORG_NOT_ACTIVE, SELLER_PAYOUT_SETUP_REQUIRED, PAYMENT_REQUIRED, ENTITLEMENT_REQUIRED) plus a recovery_suggestion string that mirrors the human-page CTA copy. The exhaustive request/response contract is in /openapi.json.

Human counterparts live at /account, /account/verify-email, /studio, and /checkout/{listing_id}.

Entitlement delivery

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}) carry the canonical 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"
  }
}

Consume delivery_policy + rate_limit, not the legacy download_count / max_downloads fields (still echoed for single-file entitlements).

Authentication model

Graunt discriminates bearer credentials by literal prefix, and there is no fall-through between credential families — a malformed token of one family is rejected, never reinterpreted as another. Tokens are returned exactly once at issuance, stored server-side only as hashes, and never belong in a URL.

The *_YOUR_* forms above are placeholders, never real tokens. Agents connecting over the MCP transport authenticate with the same grnt_agent_* credential; connection details live at /agents/mcp (JSON-RPC 2.0 at POST /v1/mcp/messages).

Surface map

The agent-relevant endpoint catalog, grouped by job. The full request/response contract for every live endpoint is the OpenAPI 3.1 document at /openapi.json.

Discovery no credential

Discovery reads optionally accept an agent discovery key (Authorization: Bearer gdk_live_YOUR_KEY) for tracked agent identity. The key is optional, never a wall — every discovery read also works with no credential at all.

Prepare before you register discovery key

Drafts are private and key-scoped — never searchable, never catalog-visible. When the human registers and claims the key, the drafts move to their account. Templates: GET /v1/meta/packet-assembly-contract + GET /v1/meta/packet-assembly-starter-kit (the human zip download is /v1/meta/packet-assembly-starter-kit.zip).

Commerce JWT or scoped agent credential

Entitled access JWT, pass, or key

Meta-contracts no credential

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.

Held (early-listing) packets are human-buyer authorization only in this release: POST /v1/purchases/held and the agent BUY preflight and execute endpoints all reject an agent-bearer held purchase with 409 DENY_CAPABILITY_NOT_LIVE — the same literal contract on every surface, with no purchase, entitlement, or payout side effects. An agent that finds a useful early listing hands the buy link to its human buyer.

The exact runtime state of every capability named on this page — live, preview, planned, reserved, or provider-not-configured — is published at /capability-status. When this page and the capability registry disagree, the registry wins.