# HIOBuy Public API Documentation

> HIOBuy is a China sourcing platform API for **Taobao**, **1688**, and **Weidian**. Integrate product search/detail, domestic procurement (`/v1/orders/*`), and cross-border fulfillment (`/v1/fulfillment/*`). Default API responses use HIOBuy **standard** unified models; set `response_format=upstream` only when you need vendor raw JSON.

## Docs for machines

- [Full English doc index (Markdown)](https://hiobuy.com/llms-full.txt): all 41 pages with descriptions
- [HTML doc index](https://hiobuy.com/en/api-docs/llms-index): browsable index for humans and agents
- [OpenAPI 3.0 — /v1/*](https://api.hiobuy.com/openapi.json): machine-readable REST schemas (`standard` + `upstream`)
- [Sitemap](https://hiobuy.com/sitemap.xml): all localized HTML doc URLs

## Quick start (read in this order)

1. [index](https://hiobuy.com/en/api-docs)
2. [authentication](https://hiobuy.com/en/api-docs/authentication)
3. [response-format](https://hiobuy.com/en/api-docs/response-format)
4. [product-detail](https://hiobuy.com/en/api-docs/product-detail)
5. [product-search](https://hiobuy.com/en/api-docs/product-search)
6. [order-preview](https://hiobuy.com/en/api-docs/order-preview)
7. [order-create](https://hiobuy.com/en/api-docs/order-create)
8. [errors](https://hiobuy.com/en/api-docs/errors)
9. [sandbox](https://hiobuy.com/en/api-docs/sandbox)
10. [agent-api](https://hiobuy.com/en/api-docs/agent-api)

## Key conventions

- **Auth:** `Authorization: Bearer hio_live_*` (production) or `hio_test_*` (sandbox). See [authentication](https://hiobuy.com/en/api-docs/authentication).
- **Response format:** omit `response_format` or use `"standard"` (recommended). [response-format](https://hiobuy.com/en/api-docs/response-format).
- **Order lines:** prefer `lines[].id` + `lines[].spec_id` from product search/detail — **not** Taobao `source_product_id`. [order-preview](https://hiobuy.com/en/api-docs/order-preview).
- **Sandbox:** deterministic `sb_*` fixtures with `hio_test_*` keys. [sandbox](https://hiobuy.com/en/api-docs/sandbox).

## AI / agent integrations (not in OpenAPI)

- [Agent API & MCP](https://hiobuy.com/en/api-docs/agent-api): `GET /ai/v1/tools`, `POST /ai/v1/tools/call`, MCP at `/mcp` — **Live keys only** (`hio_live_*`), returns **standard** product models.

## Optional

- Chinese docs mirror: https://hiobuy.com/zh/api-docs (same slugs under `/zh/api-docs/{slug}`)
- Developer portal: https://developers.hiobuy.com
- Support: support@hiobuy.com