DEVELOPER DOCUMENTATION · V0.1

One network.
Every commerce workflow.

Discover suppliers, inspect offers, request quotations and follow orders through a shared REST API and remote MCP endpoint.

Download the OpenAPI specification ↗

Start with discovery

curl 'https://api.gbos.io/v1/search?q=power&type=Goods&maxPrice=150'

Search supports q, kind, category, type, location, verified, available, maxPrice, maxLeadTime, limit and offset. Set kind=suppliers for supplier discovery. Results are bounded to 50 per request. Search snapshots update within approximately five minutes; returned offers are reloaded from the authoritative database.

Connect an MCP client

Endpoint: https://mcp.gbos.io/mcp
Transport: Streamable HTTP (stateless)
Accept: application/json, text/event-stream
Authorization: Bearer YOUR_GBOS_GRANT   # private tools only

Use any client supporting a remote Streamable HTTP server and optional custom authorization headers. Public tools work without authentication. In your GBOS workspace, open Agents, create a grant, and copy its token once. Keep tokens out of source code and browser links.

{
  "mcpServers": {
    "gbos": {
      "url": "https://mcp.gbos.io/mcp",
      "headers": { "Authorization": "Bearer ${GBOS_TOKEN}" }
    }
  }
}

Client configuration formats and environment-variable interpolation vary. Set the bearer header using your client’s secret storage. OAuth clients can discover the authorization server through protected-resource metadata at https://mcp.gbos.io/.well-known/oauth-protected-resource. The server supports dynamic public client registration, authorization code with S256 PKCE, explicit consent, one-hour access tokens and rotating 30-day refresh tokens. Manual expiring bearer grants remain available for clients with custom header support.

Tool	Authorization / behavior
search_products, search_suppliers	Public keyword and filter search
get_product_details, compare_offers	Public specifications, provenance and current supplier offers
get_supplier_capabilities	Public verification and commercial capabilities
request_quotation	write:rfq scope; verified buyer identity; idempotencyKey
get_quotation_status, get_order_status	read:commerce scope; transaction participant only
accept_quotation	Returns a human review link; never places an order

A discovery tool does not grant purchase authority. A buyer must review the exact quote revision and explicitly confirm in GBOS before an order exists.

Search filters

Use manufacturer and currency for exact matches. Pair specKey with specValue for a case-insensitive exact declared specification, including its unit (for example, Voltage and 24 V). Price filters do not convert currencies. These filters are also exposed by search_products. Search snapshots refresh within about five minutes; current offers are hydrated from the authoritative database.

REST authentication

Human accounts use Cognito email verification and short-lived ID tokens. Send the token as Authorization: Bearer …. Workspace membership is checked server-side on every private record. Agent grants last 1–30 days, have explicit scopes, and can be revoked immediately from the application.

Quotation to order

Buyer calls POST /v1/rfqs with listingId, quantity, destination, notes and an Idempotency-Key header.
Supplier calls POST /v1/quotes with RFQ ID, price, currency, shipping, tax, expiry and terms.
Buyer reviews the current revision and calls POST /v1/quotes/{id}/accept with {"confirm":true,"revision":1}.
Conditional transaction writes create one order and record the acceptance atomically. Concurrent acceptance cannot create duplicate orders.
Supplier advances fulfillment using POST /v1/orders/{id}/status. Goods ship, services enter progress, and digital goods are provisioned before completion.

Use a new Idempotency-Key for a new intent and reuse the same key and payload for a retry. A reused key with different data returns 409. Keys are retained for seven days. Audit events are append-only through the API and linked by hashes.

Catalog ingestion

Supplier uploads support CSV, XLSX, JSON and XML, up to 3 MB and 5,000 rows per job, with a daily 20-job quota. Text-based PDF catalogs (up to 50 pages) run in a memory-limited worker with a 20-second deadline and produce private text for manual review; they never publish products automatically. Full reports and extracted text are available through expiring, participant-authorized downloads. Import reports identify invalid and duplicate rows. A verified business may connect a same-domain HTTPS feed or a product page containing schema.org Product/Service JSON-LD. Redirects, DNS destinations, network ranges, robots rules, file sizes and spreadsheet formulas are validated.

Download the CSV template. Useful columns: title, type, category, description, manufacturer, partNumber, specifications (JSON), price, currency, unit, minimum, leadTimeDays, availability, quantityAvailable, location and sourceUrl.

Verification and freshness

A supplier can verify a business through an already verified matching domain email or a DNS TXT challenge. Unclaimed imported profiles show their source and cannot receive RFQs or orders. Published prices, availability and delivery times are declarations, not live inventory or fulfillment guarantees. Confirm commercial terms in a current quote.

Rate limits and errors

The shared API starts at 15 requests/second with a burst of 30. Respect 429 responses with backoff. Validation errors return 400, unauthenticated requests 401, denied participant access 403, missing resources 404 and concurrent state conflicts 409. Requests include a request ID for operator troubleshooting.