DocsBuildAPI ReferenceSDK Reference

Marketplace

v0.1.0

Discover, install, and rate connectors that extend what your agents can do

Typescript

bash
npm install @human/client-sdk

List

List marketplace connectors Browse the Agent Marketplace with optional filtering, search, and cursor-based pagination.

ParameterDescription
filtersOptional filters, search, sort, and pagination
typescript
// First page
const page1 = await client.marketplace.list({ limit: 20 });


// Next page
const page2 = await client.marketplace.list({
  limit: 20,
  cursor: page1.next_cursor
});


// With filters
const aiConnectors = await client.marketplace.list({
  category: 'ai',
  search: 'language model',
  sort_by: 'rating'
});

Returns: Paginated list of marketplace connectors

Get

Get connector details by ID Returns the full connector listing including readme, changelog, required permissions, and pricing information.

ParameterDescription
idConnector ID
typescript
const connector = await client.marketplace.get('conn_abc123');
console.log(connector.readme);
console.log(connector.permissions);

Returns: Full connector details

Errors

NotFoundError — If connector doesn't exist

Install

Install a connector Binds a connector instance to the caller's organization context. An optional configuration map can be passed for the connector's initialization hook.

ParameterDescription
idConnector ID to install
requestOptional installation configuration
typescript
const result = await client.marketplace.install('conn_abc123', {
  config: { api_key: 'sk-...', region: 'us-east-1' }
});
console.log(result.installation_id);

Returns: Installation result with installation ID and status

Errors

NotFoundError — If connector doesn't exist

ConflictError — If connector is already installed

AuthorizationError — If not authorized to install connectors

Uninstall

Uninstall a connector Removes a previously installed connector from the caller's organization context.

ParameterDescription
idConnector ID to uninstall
typescript
await client.marketplace.uninstall('conn_abc123');

Errors

NotFoundError — If connector doesn't exist or is not installed

AuthorizationError — If not authorized to uninstall connectors

Submit Rating

Submit a rating for a connector Submits or updates the caller's rating for a connector. Each passport may hold one active rating per connector.

ParameterDescription
idConnector ID to rate
ratingRating score and optional review text
typescript
const rating = await client.marketplace.submitRating('conn_abc123', {
  rating: 5,
  review: 'Excellent connector, easy to integrate.'
});

Returns: Created or updated rating

Errors

NotFoundError — If connector doesn't exist

ValidationError — If rating value is out of range (1-5)

AuthorizationError — If not authorized to submit ratings

Get Ratings

Get ratings for a connector Returns a paginated list of ratings and reviews for a connector.

ParameterDescription
idConnector ID
filtersOptional pagination parameters
typescript
const ratings = await client.marketplace.getRatings('conn_abc123');
for (const r of ratings.data) {
  console.log(`${r.rating}/5 - ${r.review}`);
}

Returns: Paginated list of connector ratings

Errors

NotFoundError — If connector doesn't exist

Types

typescript
interface MarketplaceConnector {
  /** Unique connector ID */
  id: string;
  /** Human-readable connector name */
  name: string;
  /** Short description of what the connector does */
  description: string;
  /** Marketplace category for browsing and filtering */
  category: ConnectorCategory;
  /** Publisher organization name */
  publisher: string;
  /** Semantic version string (e.g. "1.2.0") */
  version: string;
  /** Average rating (1.0 - 5.0), null if unrated */
  rating_avg: number | null;
  /** Total number of ratings received */
  rating_count: number;
  /** Total number of installations */
  install_count: number;
  /** Current publication status */
  status: ConnectorStatus;
  /** URL to the connector's icon image */
  icon_url: string | null;
}


interface ConnectorDetails {
  /** Full readme content (Markdown) */
  readme: string;
  /** Changelog content (Markdown) */
  changelog: string;
  /** Permissions the connector requires when installed */
  permissions: string[];
  /** Pricing information for the connector */
  pricing: ConnectorPricing;
}


interface ConnectorPricing {
  /** Pricing model */
  model: 'free' | 'paid' | 'freemium';
  /** Monthly price in cents (0 for free connectors) */
  monthly_price_cents?: number;
  /** Whether a free trial is available */
  free_trial?: boolean;
}


interface ConnectorRating {
  /** Unique rating ID */
  id: string;
  /** ID of the connector being rated */
  connector_id: string;
  /** Passport ID of the reviewer */
  passport_id: string;
  /** Rating score (1-5 inclusive) */
  rating: 1 | 2 | 3 | 4 | 5;
  /** Optional review text */
  review: string | null;
  /** When this rating was submitted */
  created_at: Timestamp;
}


interface InstallConnectorRequest {
  /** Optional configuration passed to the connector on install */
  config?: Record<string, string | number | boolean>;
}


interface InstallConnectorResult {
  /** Unique installation ID */
  installation_id: string;
  /** ID of the installed connector */
  connector_id: string;
  /** Status of the installation */
  status: 'installed' | 'pending';
  /** When the installation was created */
  installed_at: Timestamp;
}


interface ConnectorListFilters {
  /** Filter by marketplace category */
  category?: ConnectorCategory;
  /** Full-text search across name and description */
  search?: string;
  /** Sort order for results */
  sort_by?: 'relevance' | 'rating' | 'installs' | 'newest';
}


interface RatingRequest {
  /** Rating score (1-5 inclusive) */
  rating: number;
  /** Optional review text */
  review?: string;
}