Marketplace

Browse, search, and manage marketplace genie listings with categories and statistics.

All requests use a single endpoint: POST https://api.helpgenie.ai/v1 with resource: "marketplace".

Access control

The list, all, get, categories, stats, and trending actions are publicly accessible. The create, update, and delete actions require internal admin authentication. The clone, reviews, favorites, collections, and submissions actions require user authentication.

The create, update, and delete actions are admin-only operations. Only users with the internal_admin role can perform these actions. Non-admin users will receive a 403 Forbidden response.

sortBy values

Value	Description
"popular"	Sort by view count (most viewed first)
"newest"	Sort by creation date (most recent first) — default
"rating"	Sort by rating (highest rated first)
"clones"	Sort by clone count (most cloned first)

---

List genies (slim)

Retrieves a simplified list of marketplace genies optimized for dropdowns and compact listings. Returns only essential fields without nested relations.

resource · string · required

Must be "marketplace"

action · string · required

Must be "list"

data · object

Show properties

limit · number

Items per page. Range: 1-500. Default: 20.

offset · number

Pagination offset. Default: 0.

query · object

Show properties

category · string

Filter by category slug.

brand · string

Filter by brand slug.

search · string

Search in name, tagline, and description.

featured · string

Set to "true" to show only featured genies.

minRating · string

Minimum rating filter.

difficulty · string

Filter by difficulty metadata.

industry · string

Filter by industry metadata.

sortBy · string

Sort order. One of "popular", "newest", "rating", "clones". Default: "newest".

Response

success · boolean

data · object

Show properties

genies · object[]

Show Slim genie fields

id · string

slug · string

display_name · string

tagline · string

thumbnail_url · string

rating · number

category_id · string

is_featured · boolean

clone_count · number

count · number

limit · number

offset · number

Example request

const response = await ApiService.invoke<{
  genies: MarketplaceGenie[];
  count: number;
}>({
  resource: "marketplace",
  action: "list",
  data: {
    limit: 20,
    query: {
      category: "customer-service",
      sortBy: "popular",
    },
  },
});

---

List genies (complete)

Retrieves the full marketplace genie listing with all fields and nested relations (category, brand, and creator in admin mode).

resource · string · required

Must be "marketplace"

action · string · required

Must be "all"

data · object

Show properties

limit · number

Items per page. Range: 1-500. Default: 20.

offset · number

Pagination offset. Default: 0.

adminMode · boolean

Admin only. Include non-public genies in results.

query · object

Same query parameters as the list action. Default sort: featured first, then by clones.

Response

success · boolean

data · object

Show properties

genies · object[]

Array of full genie objects. See genie object.

count · number

limit · number

offset · number

Example request

const response = await ApiService.invoke<{
  genies: MarketplaceGenie[];
  count: number;
}>({
  resource: "marketplace",
  action: "all",
  data: {
    limit: 50,
    query: {
      search: "sales",
      minRating: "4",
    },
  },
});

---

Get a genie

Retrieves a specific marketplace genie by slug or ID. Automatically increments the view count and includes related genies from the same category.

resource · string · required

Must be "marketplace"

action · string · required

Must be "get"

id · string · required

The genie slug (preferred) or UUID.

data · object

Show properties

adminMode · boolean

Admin only. Allow fetching non-public genies.

Response

success · boolean

data · object

All fields from the genie object, plus:

Show additional fields

related_genies · object[]

Genies from the same category.

Show properties

id · string

slug · string

display_name · string

tagline · string

thumbnail_url · string

rating · number

category_id · string

Example request

const response = await ApiService.invoke<MarketplaceGenie>({
  resource: "marketplace",
  action: "get",
  id: "sales-assistant",
});

---

Create a listing

Creates a new marketplace listing. Automatically marks the agent as a marketplace template and links the listing back to the agent.

Only internal admins can create marketplace listings.

resource · string · required

Must be "marketplace"

action · string · required

Must be "create"

data · object · required

Show properties

agent_id · string · required

ID of the agent to list on the marketplace.

slug · string · required

URL-friendly unique identifier.

display_name · string · required

Public display name.

category_id · string · required

Category ID for the listing.

tagline · string

Short one-liner description.

description · string

Full description.

brand_id · string

Associated brand ID.

is_featured · boolean

Feature on homepage. Default: false.

is_public · boolean

Publish to marketplace. Default: true.

thumbnail_url · string

Preview image URL.

demo_video_url · string

Demo video URL.

metadata · object

Additional metadata (e.g. difficulty, industry).

Response (status 201)

success · boolean

data · object

The created marketplace genie with all fields. See genie object.

Example request

const response = await ApiService.invoke<MarketplaceGenie>(
  {
    resource: "marketplace",
    action: "create",
    data: {
      agent_id: "agent-123",
      slug: "sales-assistant",
      display_name: "Sales Assistant",
      category_id: "category-456",
      tagline: "Close more deals with voice AI",
      is_featured: true,
      metadata: { difficulty: "beginner", industry: "sales" },
    },
  },
  201
);

---

Update a listing

Updates an existing marketplace listing.

Only internal admins can update marketplace listings.

resource · string · required

Must be "marketplace"

action · string · required

Must be "update"

id · string · required

The listing ID.

data · object · required

Show properties

display_name · string

tagline · string

description · string

category_id · string

brand_id · string

is_featured · boolean

is_public · boolean

thumbnail_url · string

demo_video_url · string

metadata · object

Response

success · boolean

data · object

The updated marketplace genie with all fields.

Example request

const response = await ApiService.invoke<MarketplaceGenie>({
  resource: "marketplace",
  action: "update",
  id: "genie-uuid",
  data: {
    display_name: "Updated Sales Assistant",
    is_featured: false,
  },
});

---

Delete a listing

Permanently deletes a marketplace listing and unlinks the agent from the marketplace.

Only internal admins can delete marketplace listings.

resource · string · required

Must be "marketplace"

action · string · required

Must be "delete"

id · string · required

The listing ID.

Response

success · boolean

data · object

Show properties

success · boolean

id · string

The deleted listing ID.

Example request

const response = await ApiService.invoke<{
  success: boolean;
  id: string;
}>({
  resource: "marketplace",
  action: "delete",
  id: "genie-uuid",
});

---

List categories

Retrieves all marketplace categories ordered by display order. No authentication required.

resource · string · required

Must be "marketplace"

action · string · required

Must be "categories"

Response

success · boolean

data · object

Show properties

categories · object[]

Show properties

id · string

name · string

slug · string

description · string

icon · string

order · number

parent_id · string | null

created_at · string

count · number

Example request

const response = await ApiService.invoke<{
  categories: MarketplaceCategory[];
  count: number;
}>({
  resource: "marketplace",
  action: "categories",
});

---

Get statistics

Retrieves aggregate statistics about the marketplace. No authentication required.

resource · string · required

Must be "marketplace"

action · string · required

Must be "stats"

Response

success · boolean

data · object

Show properties

total_genies · number

Total number of marketplace genies.

total_views · number

Combined view count across all genies.

total_clones · number

Combined clone count across all genies.

featured_count · number

Number of featured genies.

categories_count · number

Number of categories.

Example request

const response = await ApiService.invoke<{
  total_genies: number;
  total_views: number;
  total_clones: number;
  featured_count: number;
  categories_count: number;
}>({
  resource: "marketplace",
  action: "stats",
});

---

Clone a marketplace genie

Clones a marketplace genie into the authenticated user’s account. Delegates to handle-agent for the actual agent clone, tracks the clone in user_marketplace_clones, and increments the listing’s clone_count.

resource · string · required

Must be "marketplace"

action · string · required

Must be "clone"

id · string · required

The marketplace genie listing ID. Can also be passed as marketplace_genie_id in the data object.

data · object

Show properties

cloneName · string

Custom name for the cloned genie.

customizations · object

Custom overrides applied to the clone.

currentCloneCount · number

Current clone count (incremented by 1). Default: 0.

Response

success · boolean

data · object

Show properties

success · boolean

marketplace_genie_id · string

The listing that was cloned.

cloneResult · object

The result from the agent clone operation, including the new agent.

Example request

const response = await ApiService.invoke({
  resource: "marketplace",
  action: "clone",
  id: "marketplace-genie-uuid",
  data: {
    cloneName: "My Custom Sales Bot",
    customizations: { industry: "retail" },
  },
});

---

Reviews

Manages reviews for marketplace genies. Uses a mode parameter inside data to select the operation. When mode is omitted, lists reviews.

resource · string · required

Must be "marketplace"

action · string · required

Must be "reviews"

id · string

The marketplace genie ID. Can also be passed as marketplace_genie_id in data.

Create a review

data · object · required

Show properties

mode · string · required

Must be "create".

marketplace_genie_id · string · required

The genie being reviewed.

rating · number · required

Rating value.

review_text · string

Review body text.

is_verified_clone · boolean

Whether the reviewer has cloned this genie. Default: false.

Returns { review: {...} } with status 201.

Update a review

Set mode: "update". Requires review_id, plus optional rating and review_text. Only the review owner can update.

Delete a review

Set mode: "delete". Requires review_id. Only the review owner can delete.

List reviews (default)

When mode is omitted, lists reviews for the given genie with pagination.

data · object

Show properties

marketplace_genie_id · string · required

Filter reviews for this genie.

rating · number

Filter by exact rating value.

verified_only · boolean

Show only verified-clone reviews.

limit · number

Results per page. Max: 200. Default: 50.

offset · number

Pagination offset. Default: 0.

Returns { items: [...], count, limit, offset }.

---

Favorites

Manages a user’s marketplace favorites. Uses a mode parameter inside data.

resource · string · required

Must be "marketplace"

action · string · required

Must be "favorites"

Add a favorite

data · object · required

Show properties

mode · string · required

Must be "add".

marketplace_genie_id · string · required

The genie to favorite.

Returns { favorite: {...} } with status 201.

Remove a favorite

Set mode: "remove" with marketplace_genie_id.

List favorites (default)

When mode is omitted, lists all favorites for the authenticated user with pagination.

data · object

Show properties

limit · number

Results per page. Max: 200. Default: 50.

offset · number

Pagination offset. Default: 0.

Returns { items: [...], count, limit, offset }. Each item includes the full marketplace_genie object.

---

Trending

Returns trending marketplace genies from the trending_marketplace_genies view, ordered by trending score. No authentication required.

resource · string · required

Must be "marketplace"

action · string · required

Must be "trending"

data · object

Show properties

limit · number

Maximum results. Max: 100. Default: 10.

category · string

Filter by category.

risingOnly · boolean

Only show rising genies (fewer than 50 clones, 5+ daily interactions).

Response

success · boolean

data · object

Show properties

items · object[]

Array of trending genie objects with trending_score.

Example request

const response = await ApiService.invoke({
  resource: "marketplace",
  action: "trending",
  data: { limit: 10, risingOnly: true },
});

---

Collections

Manages user-curated collections of marketplace genies. Uses a mode parameter inside data.

resource · string · required

Must be "marketplace"

action · string · required

Must be "collections"

Create a collection

data · object · required

Show properties

mode · string · required

Must be "create".

name · string · required

Collection name.

description · string

Collection description.

is_public · boolean

Whether the collection is publicly visible. Default: false.

Returns { collection: {...} } with status 201.

Update a collection

Set mode: "update" with collection_id and any of name, description, is_public.

Delete a collection

Set mode: "delete" with collection_id.

Add genie to collection

Set mode: "add-genie" with collection_id and marketplace_genie_id.

Remove genie from collection

Set mode: "remove-genie" with collection_id and marketplace_genie_id.

Get a single collection

Pass collection_id (or id) without a mode. Returns the collection and its genies.

List collections (default)

When no mode and no collection_id are provided, lists all collections for the authenticated user.

data · object

Show properties

limit · number

Results per page. Max: 200. Default: 50.

offset · number

Pagination offset. Default: 0.

Returns { items: [...], count, limit, offset }.

---

Submissions

Manages marketplace submission requests. Users submit their genies for marketplace listing; admins moderate them. Uses a mode parameter inside data.

resource · string · required

Must be "marketplace"

action · string · required

Must be "submissions"

Create a submission

data · object · required

Show properties

mode · string · required

Must be "create".

agent_id · string · required

The agent to submit for marketplace listing.

submission_data · object

Additional submission details (tagline, description, category preference, etc.).

Returns { submission: {...} } with status 201. Initial status is "pending".

Moderate a submission (admin only)

Set mode to "approve", "reject", or "under-review". Requires submission_id. Optional admin_notes.

Delete a submission

Set mode: "delete" with submission_id. Admins can delete any submission; regular users can only delete their own.

List submissions (default)

When mode is omitted, lists submissions with pagination. Admins see all submissions; regular users see only their own.

data · object

Show properties

status · string

Filter by status: "pending", "approved", "rejected", "under_review".

limit · number

Results per page. Max: 200. Default: 50.

offset · number

Pagination offset. Default: 0.

Returns { items: [...], count, limit, offset }.

---

Genie object

The full genie object returned by all, get, create, and update actions.

id · string

agent_id · string

slug · string

display_name · string

tagline · string

description · string

category_id · string

category · object

Show properties

id · string

name · string

slug · string

brand_id · string

brand · object

Show properties

id · string

name · string

slug · string

is_featured · boolean

is_public · boolean

thumbnail_url · string

demo_video_url · string

rating · number

view_count · number

clone_count · number

metadata · object

created_at · string

updated_at · string

creator · object

Show properties

id · string

full_name · string

email · string

---

Error responses

Status	Code	Description
400	VALIDATION_ERROR	Missing required parameters
401	UNAUTHORIZED	Missing or invalid authentication token
403	FORBIDDEN	Non-admin attempting a write operation
404	NOT_FOUND	Marketplace genie not found
500	INTERNAL_ERROR	Server error