Marketplace - Help Genie

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.

string

required

Must be "marketplace"

string

required

Must be "list"

object

Show properties

number

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

number

Pagination offset. Default: 0.

object

Show properties

string

Filter by category slug.

string

Filter by brand slug.

string

Search in name, tagline, and description.

string

Set to "true" to show only featured genies.

string

Minimum rating filter.

string

Filter by difficulty metadata.

string

Filter by industry metadata.

string

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

Response

boolean

object

Show properties

object[]

Show Slim genie fields

string

number

string

boolean

number

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

curl -X POST https://api.helpgenie.ai/v1/marketplace \
  -H "Content-Type: application/json" \
  -d '{
    "action": "list",
    "data": {
      "limit": 20,
      "offset": 0,
      "query": {
        "category": "customer-service",
        "search": "sales",
        "sortBy": "popular",
        "featured": "true",
        "minRating": "4"
      }
    }
  }'

List genies (complete)

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

string

required

Must be "marketplace"

string

required

Must be "all"

object

Show properties

number

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

number

Pagination offset. Default: 0.

boolean

Admin only. Include non-public genies in results.

object

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

Response

boolean

object

Show properties

object[]

Array of full genie objects. See genie object.

number

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.

string

required

Must be "marketplace"

string

required

Must be "get"

string

required

The genie slug (preferred) or UUID.

object

Show properties

boolean

Admin only. Allow fetching non-public genies.

Response

boolean

object

All fields from the genie object, plus:

Show additional fields

Genies from the same category.

Show properties

string

number

string

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.

string

required

Must be "marketplace"

string

required

Must be "create"

object

required

Show properties

string

required

ID of the agent to list on the marketplace.

string

required

URL-friendly unique identifier.

string

required

Public display name.

string

required

Category ID for the listing.

string

Short one-liner description.

string

Full description.

string

Associated brand ID.

boolean

Feature on homepage. Default: false.

boolean

Publish to marketplace. Default: true.

string

Preview image URL.

string

Demo video URL.

object

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

Response (status 201)

boolean

object

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

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.

string

required

Must be "marketplace"

string

required

Must be "update"

string

required

The listing ID.

object

required

Show properties

string

boolean

string

object

Response

boolean

object

The updated marketplace genie with all fields.

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.

string

required

Must be "marketplace"

string

required

Must be "delete"

string

required

The listing ID.

Response

boolean

object

Show properties

boolean

string

The deleted listing ID.

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

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

string

required

Must be "marketplace"

string

required

Must be "categories"

Response

boolean

object

Show properties

object[]

Show properties

string

number

string | null

string

number

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

Get statistics

Retrieves aggregate statistics about the marketplace. No authentication required.

string

required

Must be "marketplace"

string

required

Must be "stats"

Response

boolean

object

Show properties

number

Total number of marketplace genies.

number

Combined view count across all genies.

number

Combined clone count across all genies.

number

Number of featured genies.

number

Number of categories.

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

{
  "success": true,
  "data": {
    "total_genies": 42,
    "total_views": 5420,
    "total_clones": 128,
    "featured_count": 8,
    "categories_count": 12
  }
}

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.

string

required

Must be "marketplace"

string

required

Must be "clone"

string

required

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

object

Show properties

string

Custom name for the cloned genie.

object

Custom overrides applied to the clone.

number

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

Response

boolean

object

Show properties

boolean

string

The listing that was cloned.

object

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

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

curl -X POST https://api.helpgenie.ai/v1/marketplace \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "clone",
    "id": "marketplace-genie-uuid",
    "data": {
      "cloneName": "My Custom Sales Bot"
    }
  }'

Reviews

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

string

required

Must be "marketplace"

string

required

Must be "reviews"

string

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

Create a review

object

required

Show properties

string

required

Must be "create".

string

required

The genie being reviewed.

number

required

Rating value.

string

Review body text.

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.

object

Show properties

string

required

Filter reviews for this genie.

number

Filter by exact rating value.

boolean

Show only verified-clone reviews.

number

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

number

Pagination offset. Default: 0.

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

Favorites

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

string

required

Must be "marketplace"

string

required

Must be "favorites"

Add a favorite

object

required

Show properties

string

required

Must be "add".

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.

object

Show properties

number

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

number

Pagination offset. Default: 0.

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

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

string

required

Must be "marketplace"

string

required

Must be "trending"

object

Show properties

number

Maximum results. Max: 100. Default: 10.

string

Filter by category.

boolean

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

Response

boolean

object

Show properties

object[]

Array of trending genie objects with trending_score.

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.

string

required

Must be "marketplace"

string

required

Must be "collections"

Create a collection

object

required

Show properties

string

required

Must be "create".

string

required

Collection name.

string

Collection description.

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.

object

Show properties

number

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

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.

string

required

Must be "marketplace"

string

required

Must be "submissions"

Create a submission

object

required

Show properties

string

required

Must be "create".

string

required

The agent to submit for marketplace listing.

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.

object

Show properties

string

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

number

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

number

Pagination offset. Default: 0.

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

Genie object

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

string

object

Show properties

string

object

Show properties

string

boolean

string

number

object

string

object

Show properties

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

​Access control

​sortBy values

​List genies (slim)

​Response

​List genies (complete)

​Response

​Get a genie

​Response

​Create a listing

​Response (status 201)

​Update a listing

​Response

​Delete a listing

​Response

​List categories

​Response

​Get statistics

​Response

​Clone a marketplace genie

​Response

​Reviews

​Create a review

​Update a review

​Delete a review

​List reviews (default)

​Favorites

​Add a favorite

​Remove a favorite

​List favorites (default)

​Trending

​Response

​Collections

​Create a collection

​Update a collection

​Delete a collection

​Add genie to collection

​Remove genie from collection

​Get a single collection

​List collections (default)

​Submissions

​Create a submission

​Moderate a submission (admin only)

​Delete a submission

​List submissions (default)

​Genie object

​Error responses

Access control

`sortBy` values

List genies (slim)

Response

List genies (complete)

Response

Get a genie

Response

Create a listing

Response (status 201)

Update a listing

Response

Delete a listing

Response

List categories

Response

Get statistics

Response

Clone a marketplace genie

Response

Reviews

Create a review

Update a review

Delete a review

List reviews (default)

Favorites

Add a favorite

Remove a favorite

List favorites (default)

Trending

Response

Collections

Create a collection

Update a collection

Delete a collection

Add genie to collection

Remove genie from collection

Get a single collection

List collections (default)

Submissions

Create a submission

Moderate a submission (admin only)

Delete a submission

List submissions (default)

Genie object

Error responses