Marketplace API

The Marketplace API provides endpoints for browsing, reviewing, submitting, and managing plugins and themes.

All marketplace endpoints are prefixed with /marketplace.

Plugin Marketplace

Browse Plugins

GET /marketplace/browse

Returns a paginated list of published plugins.

Query Parameters:

Parameter	Type	Default	Description
`page`	number	1	Page number
`limit`	number	20	Items per page (max 100)
`search`	string	—	Search by name/description
`category`	string	—	Filter by category slug
`sort`	string	`popular`	Sort order: `popular`, `recent`, `rating`

Response:

{
  "data": [
    {
      "id": "uuid",
      "name": "my-plugin",
      "displayName": "My Plugin",
      "description": "A useful plugin",
      "version": "1.0.0",
      "author": "developer",
      "category": "ai",
      "downloadCount": 1500,
      "averageRating": 4.5,
      "ratingCount": 23,
      "isActive": true
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 20
}

Get Featured Plugins

GET /marketplace/plugins/featured

Returns plugins marked as featured by administrators.

Response: Array of plugin objects.

Get Plugin Categories

GET /marketplace/plugins/categories

Returns a list of all unique plugin categories.

Response:

["ai", "analytics", "communication", "content", "security", "utilities"]

Get Plugin Detail

GET /marketplace/plugins/:id

Returns full details for a single plugin, including rating statistics.

Response:

{
  "id": "uuid",
  "name": "my-plugin",
  "displayName": "My Plugin",
  "description": "A useful plugin",
  "version": "1.0.0",
  "author": "developer",
  "category": "ai",
  "downloadCount": 1500,
  "averageRating": 4.5,
  "ratingCount": 23,
  "isActive": true,
  "homepage": "https://example.com",
  "repository": "https://github.com/example/my-plugin",
  "ratingStats": {
    "averageRating": 4.5,
    "totalReviews": 23,
    "distribution": { "1": 0, "2": 1, "3": 2, "4": 5, "5": 15 }
  }
}

Plugin Reviews

Get Plugin Reviews

GET /marketplace/plugins/:id/reviews

Returns all reviews for a plugin.

Response: Array of review objects:

[
  {
    "pluginId": "uuid",
    "userId": "uuid",
    "rating": 5,
    "title": "Excellent plugin",
    "comment": "Works great!",
    "createdAt": "2025-01-15T10:00:00Z"
  }
]

Submit Plugin Review

POST /marketplace/plugins/:id/reviews

Auth Required: Yes (JWT)

Reviews are upserted — submitting again updates your existing review.

Request Body:

{
  "rating": 5,
  "review": "Works great for my use case."
}

Delete Plugin Review

DELETE /marketplace/plugins/:id/reviews

Auth Required: Yes (JWT) — deletes your own review for this plugin.

Plugin Versioning

Get Plugin Versions

GET /marketplace/plugins/:id/versions

Returns all published versions for a plugin, sorted by release date descending.

Response:

[
  {
    "pluginId": "uuid",
    "version": "1.2.0",
    "changelog": "Added new AI features",
    "compatibility": {
      "minPlatformVersion": "0.1.0",
      "maxPlatformVersion": "1.0.0"
    },
    "downloadUrl": "https://cdn.agentbase.dev/plugins/my-plugin/1.2.0.tgz",
    "fileSize": 45000,
    "checksum": "sha256:abc123...",
    "publishedBy": "uuid",
    "releasedAt": "2025-02-01T12:00:00Z"
  }
]

Get Specific Version

GET /marketplace/plugins/:id/versions/:version

Returns details for a specific plugin version.

Publish Plugin Version

POST /marketplace/plugins/:id/versions

Auth Required: Yes (JWT)

Request Body:

{
  "version": "1.2.0",
  "changelog": "Added new AI features",
  "downloadUrl": "https://cdn.agentbase.dev/plugins/my-plugin/1.2.0.tgz",
  "fileSize": 45000,
  "checksum": "sha256:abc123...",
  "compatibility": {
    "minPlatformVersion": "0.1.0",
    "maxPlatformVersion": "1.0.0"
  }
}

All fields except version are optional.

Theme Marketplace

Browse Themes

GET /marketplace/themes

Returns a paginated list of published themes.

Query Parameters:

Parameter	Type	Default	Description
`page`	number	1	Page number
`limit`	number	20	Items per page
`search`	string	—	Search by name/description
`category`	string	—	Filter by category slug
`sort`	string	`popular`	Sort order: `popular`, `recent`, `rating`

Response:

{
  "data": [
    {
      "id": "uuid",
      "name": "modern-dark",
      "displayName": "Modern Dark",
      "description": "A sleek dark theme",
      "version": "1.0.0",
      "author": "designer",
      "category": "dark",
      "downloadCount": 3200,
      "averageRating": 4.8,
      "ratingCount": 48,
      "previewUrl": "https://cdn.agentbase.dev/themes/modern-dark/preview.png"
    }
  ],
  "total": 15,
  "page": 1,
  "limit": 20
}

Get Featured Themes

GET /marketplace/themes/featured

Returns themes marked as featured by administrators.

Get Theme Categories

GET /marketplace/themes/categories

Returns all unique theme categories.

Get Theme Detail

GET /marketplace/themes/:id

Returns full details for a single theme, including rating statistics.

Theme Reviews

Get Theme Reviews

GET /marketplace/themes/:id/reviews

Submit Theme Review

POST /marketplace/themes/:id/reviews

Auth Required: Yes (JWT)

Reviews are upserted — submitting again updates your existing review.

Request Body:

{
  "rating": 5,
  "review": "Love the design!"
}

Delete Theme Review

DELETE /marketplace/themes/:id/reviews

Auth Required: Yes (JWT) — deletes your own review for this theme.

Developer Submission

Submit Plugin

POST /marketplace/submit/plugin

Auth Required: Yes (JWT)

Submit a new plugin for marketplace review. The plugin enters a review queue before being published.

Request Body:

Field	Type	Required	Description
`name`	string	✓	Machine-readable name (slug)
`slug`	string	✓	URL-friendly identifier
`version`	string	✓	SemVer version (e.g. `1.0.0`)
`description`	string		Short description
`author`	string		Author display name
`authorUrl`	string		Author website URL
`repositoryUrl`	string		Source code repository URL
`iconUrl`	string		Plugin icon image URL
`screenshots`	string[]		Array of screenshot URLs
`isPaid`	boolean		Whether the plugin is a paid listing
`price`	number		Price in USD (required if isPaid)
`manifest`	object		Full plugin manifest JSON

{
  "name": "my-plugin",
  "slug": "my-plugin",
  "version": "1.0.0",
  "description": "A useful AI plugin for Agentbase",
  "author": "Your Name",
  "authorUrl": "https://yoursite.com",
  "repositoryUrl": "https://github.com/you/my-plugin",
  "iconUrl": "https://yoursite.com/icon.png",
  "screenshots": ["https://yoursite.com/screenshot1.png"],
  "isPaid": false
}

Submit Theme

POST /marketplace/submit/theme

Auth Required: Yes (JWT)

Submit a new theme for marketplace review.

Request Body:

Field	Type	Required	Description
`name`	string	✓	Machine-readable name
`slug`	string	✓	URL-friendly identifier
`version`	string	✓	SemVer version
`description`	string		Short description
`author`	string		Author display name
`authorUrl`	string		Author website URL
`previewUrl`	string		Live preview URL
`iconUrl`	string		Theme icon image URL
`screenshots`	string[]		Array of screenshot URLs
`category`	string		Theme category slug
`isPaid`	boolean		Whether this is a paid listing
`price`	number		Price in USD (required if isPaid)
`manifest`	object		Full theme manifest JSON
`defaultStyles`	object		Default style variables

{
  "name": "my-theme",
  "slug": "my-theme",
  "version": "1.0.0",
  "description": "A beautiful responsive theme",
  "category": "business",
  "previewUrl": "https://preview.example.com",
  "isPaid": false
}