An API marketplace or portal makes services discoverable, understandable, and governable. In a Pool API context, the catalog may include model routes, prompt libraries, credit products, compute shapes, node capacity, token operations, databases, CMS connectors, domain inventory, webhooks, and agent tools. A useful portal is more than a grid of logos. It connects a human-readable product description to a machine-readable contract, access policy, lifecycle, usage model, and support path.
The marketplace and gateway should remain conceptually separate. The marketplace describes and governs offerings. The gateway authenticates and routes runtime traffic. Combining everything into one application makes catalog changes risky and encourages product metadata to leak into hot-path routing. A portal can publish immutable specifications and plan references while the gateway enforces the current resolved policy.
Create a normalized catalog entry
Normalize without erasing differences
Each offering needs a stable identifier, name, provider, summary, category, capabilities, audience, regions, lifecycle state, documentation, specification references, authentication methods, plan options, support contact, terms, and change history. Preserve provider-specific extensions rather than flattening every service into the same fields. A model route and a database API share catalog basics but have different capability details.
Use namespaces so two providers can publish similarly named products without collision. Separate the logical product from versions and deployment instances. A product may have several API versions and several regional endpoints. A plan may grant access to only part of the product. Keeping these entities distinct makes deprecation, pricing, and routing manageable.
Publish machine-readable contracts
The OpenAPI Specification defines a language-agnostic description for HTTP APIs; the authoritative OpenAPI 3.2 specification is a strong foundation for endpoint, parameter, schema, and security documentation. Event-driven products can publish an AsyncAPI document. GraphQL, gRPC, and tool protocols need their corresponding schemas. The catalog should identify the format and exact version rather than offering one generic “API spec” link.
Validate specifications on ingestion. Resolve references, reject dangerous external fetches, and scan for secrets. Generate examples and documentation from the contract, but let owners add conceptual guides that explain workflows and policy. A complete schema does not tell a developer when to reserve credits, how to handle a webhook replay, or which model profile fits a task.
Design provider onboarding as a workflow
A provider submits ownership, product metadata, specification, endpoint verification, support information, security contacts, and plan definitions. Automated checks validate URLs, schemas, authentication declarations, example requests, and health. Reviewers approve the listing before publication. High-risk categories such as financial movement or untrusted compute may require additional security and legal review.
Keep draft, review, approved, published, suspended, deprecated, and retired states. Publishing should reference an immutable catalog revision. A provider can prepare the next revision without changing the public listing. Emergency suspension blocks new access and can instruct the gateway to stop routing while preserving the catalog history and customer notices.
Separate discovery from access
Public discovery can show what an API does without granting credentials. Access requests create a relationship between a consumer account, application, product version, plan, and policy. Some products can approve automatically; others require provider review, identity verification, contract acceptance, or a technical questionnaire. Record the approval decision and terms version.
Issue credentials through the gateway or dedicated identity system, not inside static documentation. Use scopes tied to product capabilities. Let consumers rotate keys, view last use, and revoke applications. For agent clients, prefer short-lived tokens or delegated credentials over embedding a permanent marketplace key in prompts or code bundles.
Model plans, quotas, and credits explicitly
Separate access tiers from metered usage
A plan defines access scope, quota dimensions, concurrency, rate limits, support, region, and billing or credit rules. Avoid hard-coding plan names into the gateway. The access grant references a plan version resolved into enforceable policy. If a plan changes, existing grants can remain on the old version or migrate through an explicit process.
Keep request limits separate from credit balances. A free plan may have a daily quota without prepaid credits. A paid plan may have a balance plus per-minute limits. A compute marketplace may reserve GPU-seconds, while a model marketplace meters input and output units. The catalog can display normalized examples but must preserve the underlying unit and conversion version.
Collect metering at the enforcement point
Usage records should originate as close as possible to the gateway or resource controller that observed the work. Each record includes consumer, product, version, endpoint or operation, provider, unit quantities, timestamp, trace, policy version, and idempotency identifier. Send records to an immutable ledger or event stream, then aggregate for dashboards and invoices.
Do not trust provider-submitted totals as the only source when the marketplace controls routing. Reconcile gateway observations with provider reports. For long-running compute, meter leases and measured execution. For asynchronous jobs, separate submission from completed work. The consumer should be able to inspect usage records and dispute specific identifiers.
Make trust evidence specific
Badges such as “verified” are ambiguous unless the portal states what was verified. Ownership verification, specification validation, security review, uptime history, identity review, and financial licensing are different claims. Publish the scope, reviewer, date, and expiry where appropriate. Do not invent customer ratings, partner logos, or certification status.
Operational signals can include recent availability, latency class, incident status, and support response target, but label them as measured by the marketplace or declared by the provider. Protect against gaming and low sample sizes. A marketplace can rank relevance without implying quality, or let consumers filter by capabilities and policy rather than presenting one opaque score.
Treat deprecation as a product workflow
Every version needs a lifecycle and dates. Deprecation announces that a version remains available but should not receive new integrations. Sunset states when traffic will stop. Retirement blocks use while preserving documentation and history. Send notices to affected access grants and expose machine-readable deprecation fields in the catalog and gateway responses.
A breaking change should create a new version. Nonbreaking documentation improvements can update the catalog revision. Provide migration guides and, where possible, compatibility reports generated from specifications. Do not silently point a versioned URL at incompatible behavior. Agents and generated clients need the same stability as human developers.
Support search by capability and constraints
Keyword search is useful, but Pool API discovery often needs structured filters: resource type, modality, authentication, region, latency class, input format, output contract, network, compute shape, provider, lifecycle, and plan. Use controlled vocabularies with extensible namespaces. Allow a product to declare several categories without duplicating the listing.
For machine clients, provide a catalog API that returns compact capability records and links to full specifications. Apply authorization before revealing private products or negotiated plans. Agents should not receive every marketplace secret or endpoint; they receive the subset allowed for the workflow and a short-lived route or tool reference.
Write documentation around tasks
Organize each product page around what the consumer can accomplish, prerequisites, authentication, first successful request, error handling, limits, webhooks, versioning, and support. Include tested examples in common languages, but keep the canonical request and response schema visible. Show example data, never live credentials or customer information.
A “try it” console is a data-entry tool and requires security, consent, rate limits, and credential handling. A static editorial portal can instead provide copyable examples and link to a secure external console when one actually exists. Do not add decorative buttons that imply account creation, key issuance, or purchases when those functions are unavailable.
A catalog and access surface
GET /catalog/products
GET /catalog/products/{id}
GET /catalog/products/{id}/versions
GET /catalog/products/{id}/specifications
POST /provider-submissions
POST /access-requests
GET /access-grants
GET /usage-records
GET /change-noticesThe public catalog can be cacheable. Access and usage endpoints are tenant-scoped and private. Return links to canonical documentation, terms, status, and support. Use content negotiation or explicit download links for specifications rather than embedding a huge schema in every product response.
Govern the marketplace itself
Define who can create providers, approve products, publish revisions, suspend traffic, change plans, view usage, and resolve disputes. Separate reviewer and provider roles. High-impact changes should require expected versions and, where appropriate, multiple approvals. Every catalog and policy mutation gets an audit event.
Moderate listings for misleading claims, copied documentation, hidden fees, unsafe endpoints, and unsupported compatibility promises. Establish an appeals path. Marketplace governance should be published in understandable terms, especially when rankings or suspension can materially affect providers.
A portal is a contract directory
A strong API marketplace connects discovery, machine-readable contracts, access policy, metering, lifecycle, and trust evidence. Keep the catalog separate from runtime routing, validate specifications, version plans, and publish precise deprecation dates. Make every trust claim specific and every interactive function real.
Explore the static Pool API Portal blueprint, the Marketplace architecture page, and the complete set of Pool API Field Notes.
