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

# Heedjy API

Jentic publishes the only available OpenAPI specification for Heedjy API, keeping it validated and agent-ready. Heedjy provides a Site API for building custom marketplace and app-listing experiences. The current API surface exposes an OAuth 2.0 token endpoint and an apps listing endpoint, letting integrators authenticate and pull the catalog of apps available on a given Heedjy marketplace. It is intended as a building block for embedded marketplace UIs rather than a full storefront management API.

## For AI agents

Authenticate with OAuth 2.0 and list apps available on a Heedjy marketplace through 2 endpoints.

## Scope

Does not handle order processing, payments, app installation, or storefront rendering - use for OAuth token exchange and read-only app catalog listing only.

## Capabilities

- Exchange client credentials for an OAuth 2.0 access token via POST `/api/oauth2/token`
- List apps published on the connected Heedjy marketplace via GET `/api/v1/apps`
- Filter app listings by query parameters supported on `/api/v1/apps` for paginated browsing
- Use the issued bearer token to authorise downstream Heedjy calls under the same client
- Surface the Heedjy app catalog inside an embedded marketplace UI

## Use cases

### Embedded Marketplace App Picker

A SaaS product embeds Heedjy's app catalog inside a settings page so end-users can browse and install third-party integrations. The token endpoint authenticates the SaaS, and GET `/api/v1/apps` returns the catalog payload that the UI renders. The integration only needs two endpoints to power the picker.

Example prompt: Call POST `/api/oauth2/token` with client credentials, then GET `/api/v1/apps` with the bearer token to render a list of marketplace apps

### Catalog Sync to Internal Database

An ops team mirrors the Heedjy app catalog into their internal database nightly so analytics and merchandising teams can join it against installation data. The OAuth token plus a single paginated GET `/api/v1/apps` call provides the canonical app records.

Example prompt: Authenticate with POST `/api/oauth2/token`, then iterate GET `/api/v1/apps` with pagination and upsert each record into the internal catalog table

### Token Lifecycle Manager

A platform service manages OAuth 2.0 tokens for many tenants, refreshing them ahead of expiry. The `/api/oauth2/token` endpoint accepts client credentials and returns a token plus expiry, letting the service schedule renewal jobs.

Example prompt: Call POST `/api/oauth2/token` with grant_type=client_credentials and persist the returned access_token and expires_in for renewal

### AI Agent Marketplace Browser

An AI assistant helps users discover Heedjy apps by intent, e.g. 'find a CRM integration for my store'. Through Jentic, the agent obtains a token, calls `/api/v1/apps`, and filters the response by name or category before presenting matches.

Example prompt: Search Jentic for 'list marketplace apps', load the GET `/api/v1/apps` operation, and return the apps whose names match a user-supplied keyword

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/oauth2/token` | Exchange client credentials for an access token |
| GET | `/api/v1/apps` | List apps on the Heedjy marketplace |

## Key resources

- **OAuth Token** — Issue OAuth 2.0 access tokens from client credentials
- **Apps** — List apps published on the Heedjy marketplace

## Why Jentic

- **Setup:** Wiring Heedjy by hand means running the OAuth 2.0 exchange against `/api/oauth2/token` with your client id and secret, then attaching the resulting bearer token on each call. Through Jentic you install once, import the Heedjy API from the API Directory, store the client credentials once, and your agent calls it.
- **Permission scoping:** Heedjy exposes a token exchange and a read-only app listing (`/api/oauth2/token`, `/api/v1/apps`), so limit the agent to the operations it needs, such as listing marketplace apps. You choose the operations it may call, so anything beyond that set is not included unless you add it.
- **Credential handling:** Your Heedjy client id and secret are stored once, encrypted, by your own Jentic One instance and exchanged for a token at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list marketplace apps' or 'get an oauth token for heedjy', and Jentic returns the matching operation with its input schema, including the token-then-list sequence, so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Ticketmaster Discovery API** — Ticketmaster Discovery exposes a different kind of catalog (events) but uses a similar OAuth + listing pattern
- **RAWG Video Games Database API** — RAWG provides a large public catalog API, useful as a comparison for catalog browsing patterns
- **Booking.com API** — Booking.com exposes a different listing API (accommodations) - not a like-for-like alternative

## FAQ

### Why is there no official OpenAPI spec for Heedjy API?

Heedjy publishes reference docs on heedjy.readme.io but does not distribute a maintained OpenAPI file. Jentic generates and maintains this spec so that AI agents and developers can call Heedjy via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Heedjy API use?

Heedjy uses OAuth 2.0 client-credentials flow. POST `/api/oauth2/token` returns a bearer token that is sent as Authorization: Bearer ... on `/api/v1/apps.` Through Jentic, the client_id and client_secret live in the encrypted vault.

### Can I list every app on my Heedjy marketplace with this API?

Yes. GET `/api/v1/apps` returns the catalog of apps for the connected client. Pagination parameters on the endpoint let an agent walk the full list in chunks.

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

The OpenAPI spec does not declare hard rate limits; Heedjy applies fair-use limits per client. For catalog sync jobs, request a fresh token only when the previous one is near expiry rather than on every call.

### How do I authenticate and list apps through Jentic?

Run pip install jentic, have the agent search for 'list marketplace apps', load the operation chain (token then apps), and execute it with the stored client credentials.

### Does the Heedjy API support creating or updating apps?

No. The current published surface is limited to issuing tokens and listing apps. Authoring or editing app records happens inside the Heedjy admin UI.

### Can I limit what my agent is allowed to do with the Heedjy API?

Yes. Because Jentic One is self-hosted and runs under your own rules, you decide which Heedjy operations the agent may call. The API exposes only a token exchange (POST `/api/oauth2/token`) and a read-only app listing (GET `/api/v1/apps`), so you can restrict the agent to just listing marketplace apps and its token step while keeping your client credentials stored on your instance and never in the prompt. Any operation you do not grant is not available to the agent.