canonical: https://jentic.com/apis/graunt.com/graunt

# Graunt API

The Graunt API runs a marketplace for agent-ready data packets, where listings expose stable IDs, declared rights, provenance, pricing, and manifest references. Buyers purchase a listing to receive an entitlement, then download the packet as a signed-URL list, source archive, or machine ZIP, or ask sourced-answer queries over it. Sellers publish listings through packet upload sessions, and payment runs through Stripe with money values expressed in integer cents.

## For AI agents

Lets an AI agent search and buy agent-ready data packets, receive entitlements, download packet assets via signed URLs, and query entitled content.

## Scope

Does not handle model training, data labeling, or general cloud file storage. Use for buying and selling agent-ready data packets only.

## Capabilities

- Search and read public listings of agent-ready data packets
- Purchase a listing and receive an entitlement to its packet
- Download an entitled packet as a signed-URL list, source archive, or machine ZIP
- Mint and revoke scoped access passes and packet access keys for a purchase
- Publish a listing as a seller through a packet upload session
- Ask sourced-answer queries over an entitled packet

## Use cases

### Agent data acquisition

An AI agent can acquire data autonomously through Graunt: searching public listings, running a buy preflight, purchasing a listing, and downloading the resulting entitlement as a machine ZIP or an LLM-ready pack. Scoped agent credentials keep the agent's reach to purchase and download routes. Connected through Jentic, the agent calls only the operations its rule allows.

Example prompt: Search listings for a topic, purchase the best match, and download its entitlement as a machine ZIP

### Entitlement delivery and access control

Buyers need to hand packet access to downstream systems without sharing a master credential. Graunt issues durable packet access keys and short-lived access passes bound to a single entitlement, each read-only and surfaced once at creation. An agent can mint, list, and revoke these so access stays auditable.

Example prompt: Mint a read-only access pass for an owned entitlement and then revoke it when the task finishes

### Seller listing publication

Data sellers list packets for sale by creating a packet upload session, registering assets with presigned PUT URLs, and finalizing a frozen bundle revision before submitting the listing for review. Graunt validates and hashes the bundle on finalize. An agent can drive this pipeline end to end for a catalog of datasets.

Example prompt: Create a packet upload session, register an asset, finalize the bundle, and create a listing for it

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/v1/listings` | Search active listings |
| GET | `/v1/listings/{id}` | Fetch a public listing detail |
| POST | `/v1/purchases` | Initiate a full purchase of a listing |
| GET | `/v1/entitlements/{id}/download` | Fetch a presigned download URL for an owned entitlement |
| POST | `/v1/access-passes` | Create a Graunt Access Pass |
| POST | `/v1/datasets` | Upload a dataset file with metadata |
| GET | `/v1/receipts` | List receipts for the auth org |

## Key resources

- **Listings** — Search, read, and publish marketplace listings for data packets
- **Purchases** — Initiate full or held purchases and request refunds
- **Entitlements** — Download packets and manage access keys for owned entitlements
- **Access passes** — Create, resolve, and revoke read-only passes to entitled content
- **Refinery** — Validate, import, and compile seller-ready packets

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 53 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 47 / 100
  - Developer Experience & Jentic Compatibility: 61 / 100
  - AI-Readiness & Agent Experience: 47 / 100
  - Agent Usability: 51 / 100
  - Security: 61 / 100
  - AI Discoverability: 75 / 100
- **View full report:** https://jentic.com/apis/graunt.com/graunt/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Graunt by hand means juggling several Bearer token types, a user JWT, a scoped agent token, access-pass and packet-access-key tokens, and the Stripe payment flow yourself. Through Jentic you install once, import Graunt from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Graunt puts the entitlement id in the URL path (`/v1/entitlements/{id}/...`), so a rule can pin your agent to one entitlement and its download and query operations. You choose the operations it may call, so publishing or refund operations are not included unless you add them.
- **Credential handling:** Your Graunt token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'buy a data listing' or 'download an entitlement', and Jentic returns the matching Graunt operation with its input schema so the agent calls the right endpoint without reading the reference docs.

## Related APIs

- **Financial Datasets API** — A provider of ready financial datasets versus Graunt's open packet marketplace.
- **Sokosumi API** — Another agent-facing marketplace versus Graunt's data-packet listings.
- **Noden Marketplace API** — A general marketplace to pair with Graunt's data-packet commerce.

## FAQ

### What authentication does the Graunt API use?

Graunt uses Bearer tokens in the Authorization header, per its OpenAPI spec: a user JWT from login, a scoped agent Bearer token for the agent purchase and listing routes, and short-lived access-pass or packet-access-key Bearer tokens for read-only packet access. A scoped X-API-Key app credential is also defined. Public listing endpoints need no credential. Through Jentic the token is stored encrypted by your own Jentic One instance and injected at execution time.

### Can I buy and download a data packet with the Graunt API?

Yes. The purchase operation buys an active listing and creates an entitlement, and the entitlement download operation returns a presigned URL for the packet. You can also pull a bundle as a signed-URL list, a source archive, a machine ZIP, or an LLM-ready pack.

### What are the rate limits for the Graunt API?

The OpenAPI spec does not publish fixed rate limits, though some public operations such as free-access grants are noted as rate-limited. Check https://graunt.com for current limits.

### How do I buy and download a packet with the Graunt API through Jentic?

Search Jentic for 'buy a data listing' and it returns the Graunt purchase operation with its input schema, then search 'download an entitlement' for the download operation. Install Jentic One with `curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh`, import Graunt from the API Directory, and store your token once. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with Graunt?

Yes. Scope the agent to one entitlement: Graunt puts the entitlement id in the URL path (`/v1/entitlements/{id}/...`), so a rule can let the agent download and query that packet and touch no other, and every call it makes is logged.

### Is there a Graunt MCP server?

You don't need an MCP server to connect your agent to Graunt. Jentic connects it directly from the API Directory: import it, store your credential once, and your agent discovers and calls the operations it needs on demand.