canonical: https://jentic.com/apis/openchannel.io/openchannel-market

# OpenChannel Market API

OpenChannel Market is an app-marketplace platform that lets SaaS vendors stand up a branded marketplace for their ecosystem partners. The Market API exposes the full marketplace surface - apps and app versions, developer accounts, custom checkout and refund webhooks, subscriptions, reviews, statistics, and admin operations. It supports the full app lifecycle from draft creation through publish-to-live, and provides search, text search, and bySafeName lookups for storefront integrations. The API is the same one used by OpenChannel's own admin interfaces, so it offers parity with what marketplace operators see in the UI.

## For AI agents

Manage an OpenChannel app marketplace - create app versions, publish to live, run text search, process custom-gateway payments and refunds, and read developer and review data.

## Scope

Does not handle storefront rendering, payment processing, or end-user authentication - use for OpenChannel marketplace administrative operations only.

## Capabilities

- Create, version, and publish marketplace apps through draft, pending, and live lifecycle states
- Run free-text and structured search across the marketplace catalogue including bySafeName lookups
- Process payments and refunds through the custom-gateway endpoints for marketplace transactions
- Manage developer accounts, statistics, and ownership records for each marketplace app
- Handle app reviews and ratings to drive marketplace social proof
- Drive subscription lifecycles with status changes and renewal handling tied to app ownerships

## Use cases

### Marketplace App Lifecycle Automation

Automate the full app submission flow on an OpenChannel marketplace - create a new version on `/apps/{appId}/versions/{version}`, attach assets, transition status via `/apps/{appId}/versions/{version}/status`, and finally publish with `/apps/{appId}/publish` or `/apps/{appId}/live.` This removes manual marketplace-admin clicks for vendors that ship updates frequently.

Example prompt: POST /apps with name and developerId, POST `/apps/{appId}/versions/{version}` with manifest and screenshots, then POST `/apps/{appId}/publish` to push it live.

### Marketplace Search and Discovery

Power storefront search and discovery experiences with `/apps/textSearch` for free-text matching and `/apps/bySafeName/{safeName}` for canonical slug lookups. These endpoints return the same app metadata exposed in the OpenChannel admin, suitable for building custom marketplace front-ends or agent-driven recommendations.

Example prompt: GET `/apps/textSearch`?q=analytics and return the top 10 apps ranked by relevance for an analytics-focused marketplace section.

### Custom Gateway Payments and Refunds

Process marketplace payments and refunds through OpenChannel's custom gateway when the marketplace operator integrates its own PSP. The `/custom-gateway/payment/{ownershipId}` and `/custom-gateway/refund/{ownershipId}` endpoints record payment outcomes against an ownership record so subscription state stays consistent with PSP events.

Example prompt: On a Stripe webhook for charge.refunded, POST `/custom-gateway/refund/{ownershipId}` with the refunded amount and reference to update the marketplace ownership state.

### AI Agent Marketplace Operations

Through Jentic, an AI marketplace agent can submit app updates, moderate reviews, and respond to developer queries without learning the 72-endpoint OpenChannel surface. The agent searches by intent, loads the operation, and executes against the marketplace base URL with credentials isolated in your Jentic One instance.

Example prompt: Through Jentic, search for 'publish an OpenChannel app version', load POST `/apps/{appId}/publish`, and execute it with the appId returned from the catalogue.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/apps` | List marketplace apps |
| POST | `/apps` | Create a new marketplace app |
| GET | `/apps/textSearch` | Search apps by free-text keyword |
| GET | `/apps/bySafeName/{safeName}` | Look up an app by its safe-name slug |
| POST | `/apps/{appId}/publish` | Publish an app to the marketplace |
| POST | `/apps/{appId}/live` | Push an app version live |
| POST | `/custom-gateway/payment/{ownershipId}` | Record a custom-gateway payment |
| POST | `/custom-gateway/refund/{ownershipId}` | Record a custom-gateway refund |

## Key resources

- **Apps** — Manage marketplace apps and their lifecycle
- **App Versions** — Version, publish, and retire individual app versions
- **Developer Accounts** — Manage marketplace developer identities and ownership
- **Custom Gateway** — Record payments and refunds from a custom PSP
- **Reviews** — Manage app reviews and ratings
- **Search** — Free-text and structured search across marketplace apps

## Why Jentic

- **Setup:** Wiring the OpenChannel Market API by hand means encoding basic-auth credentials into the Authorization header, and finding the right call across a 72-endpoint marketplace surface yourself. Through Jentic you install once, import the OpenChannel Market API from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** The API puts the app id and ownership id in the URL path (`/apps/{appId}/publish`, `/custom-gateway/refund/{ownershipId}`), so a rule can pin your agent to one app or one ownership: it can publish that app or make it live. You choose the operations it may call, so refunds and payment operations are not included unless you add them.
- **Credential handling:** Your OpenChannel Market basic-auth username and password are stored once, encrypted, by your own Jentic One instance and injected into the Authorization header at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'publish an OpenChannel app' or 'search apps by name', and Jentic returns the matching operation from the marketplace surface with its request schema so the agent calls the right endpoint without browsing the OpenChannel reference.

## Related APIs

- **OpenChannel Market API (alternative listing)** — Sibling listing of the same OpenChannel Market API surface.
- **Shopify API** — App store and storefront APIs for the Shopify ecosystem.
- **Stripe API** — PSP for the underlying payments alongside OpenChannel custom-gateway recording.

## FAQ

### What authentication does the OpenChannel Market API use?

The spec declares an HTTP Basic auth scheme (basicAuth), so requests carry an Authorization header with base64-encoded credentials issued by the marketplace operator. Through Jentic, the basic auth username and password are stored encrypted in your Jentic One instance and injected into the header at execution time, so the agent never sees raw marketplace credentials.

### Can I publish an app version through this API?

Yes. After creating or updating an app version with POST `/apps/{appId}/versions/{version}`, call POST `/apps/{appId}/publish` to publish it through the marketplace review workflow or POST `/apps/{appId}/live` to push it live directly. Status transitions are also exposed via POST `/apps/{appId}/versions/{version}/status` for finer-grained control.

### What are the rate limits for the OpenChannel Market API?

OpenChannel does not publish a single global rate limit in the spec - limits depend on the marketplace tier and underlying tenancy. Treat 429 responses as a back-off signal, batch search calls, and avoid tight polling on /apps endpoints during catalogue refreshes.

### How do I search the marketplace through Jentic?

Search Jentic for 'search OpenChannel marketplace apps', load GET `/apps/textSearch`, and execute it with the q query parameter. Jentic returns the parsed app list including safeName, version, and developerId fields so the agent can hand them to subsequent `/apps/bySafeName/{safeName}` lookups.

### Can I record refunds against an ownership record?

Yes. POST `/custom-gateway/refund/{ownershipId}` records a refund event against the ownership identifier returned when a customer first purchased or installed the app. Pair this with POST `/custom-gateway/payment/{ownershipId}` when integrating a custom PSP that issues both charge and refund webhooks.

### Is the OpenChannel Market API free?

OpenChannel is a commercial SaaS platform - access to the API requires an active OpenChannel marketplace tenancy. Pricing is published on openchannel.io and depends on tier, app count, and traffic; there is no public free tier exposed through this API.

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

Yes. Jentic One is self-hosted by you, so your own rules decide which OpenChannel operations and credentials the agent can use. Because the API puts the app id and ownership id in the URL path, such as POST `/apps/{appId}/publish` and POST `/custom-gateway/refund/{ownershipId}`, you can pin the agent to a single app or ownership and grant only the calls it needs, for example letting it publish or push an app live. Payment and refund operations on the custom gateway stay off limits unless you explicitly add them to the agent's allowed set.