API reference

The Humind public API lets you push your catalog into Humind from any stack. Authenticate with a single API key per environment, send JSON over HTTPS, get back JSON. No SDK to install, no Shopify required. Optional webhooks push notifications back to you instead of polling.

This is the integration path if you're not on Shopify. If you are, install the Humind Shopify app instead. It syncs everything automatically and you can ignore this section.

What you can do

• Products: create, update, list, archive products and their variants. See Products.
• Collections: group products into collections so the assistant can narrow recommendations. See Collections.
• Knowledge: push FAQs, sizing guides, return policies, and other free-form content the assistant can ground its answers on. See Knowledge.
• Translations: patch per-locale titles, descriptions, and handles one locale at a time as a sub-resource on products, collections, and knowledge entries. See Products / Translations, Collections / Translations, Knowledge / Translations.
• Variants: manage a single product variant without resending the full product. See Products / Variants.
• Imports: bulk NDJSON uploads for the initial sync of large catalogs. See Imports.
• Webhooks: subscribe to import events (import.completed, import.failed). See Webhooks.

Base URL

https://api.thehumind.com/public/v1

All endpoints are versioned under /public/v1. Breaking changes ship under a new prefix (/public/v2) and the previous version stays live during the migration window. See Versioning.

Quick start

Already have a key? Push your first product:

curl -X POST https://api.thehumind.com/public/v1/products \
  -H "Authorization: Bearer hmd_live_REPLACE_WITH_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "SKU-123",
    "title": "Hydrating face cream",
    "handle": "hydrating-face-cream",
    "status": "active",
    "default_language": "fr",
    "variants": [
      { "external_id": "SKU-123-50ML", "title": "50 ml", "price": 29.90, "currency": "EUR" }
    ]
  }'

You'll get back 201 Created for new products, 200 OK when updating an existing one (matched by external_id). The response carries the full product object including the humind_id Humind assigned.

Sandbox: use a hmd_test_* API key from your dashboard to develop against test data without touching your live catalog. See Authentication.

Don't have a key yet? See Authentication to generate one from your dashboard.

OpenAPI specification

The full machine-readable spec is downloadable here:

• openapi.yaml

Import it in Postman, Insomnia, Bruno, or any client that speaks OpenAPI 3.0 to get a pre-built collection of every endpoint with example payloads.

Routes at a glance

All paths are relative to https://api.thehumind.com/public/v1. Every write request requires an Idempotency-Key header. See the per-resource pages for full schemas, examples, and error tables.

Resource	Method	Path	Scope	Purpose
Products	POST	/products	catalog:write	Create or upsert a product
Products	POST	/products/batch	catalog:write	Upsert up to 500 products
Products	GET	/products	catalog:read	List products
Products	GET	/products/{id}	catalog:read	Retrieve a product
Products	PUT	/products/{id}	catalog:write	Replace a product
Products	PATCH	/products/{id}	catalog:write	Partially update a product
Products	DELETE	/products/{id}	catalog:write	Archive or hard-delete a product
Products	PUT	/products/{id}/variants/{external_id}	catalog:write	Upsert a variant
Products	DELETE	/products/{id}/variants/{external_id}	catalog:write	Remove a variant
Products	PUT	/products/{id}/translations/{lang}	catalog:write	Upsert a translation
Products	DELETE	/products/{id}/translations/{lang}	catalog:write	Remove a translation
Collections	POST	/collections	catalog:write	Create or upsert a collection
Collections	POST	/collections/batch	catalog:write	Upsert up to 500 collections
Collections	GET	/collections	catalog:read	List collections
Collections	GET	/collections/{id}	catalog:read	Retrieve a collection
Collections	PUT	/collections/{id}	catalog:write	Replace a collection
Collections	PATCH	/collections/{id}	catalog:write	Partially update a collection
Collections	DELETE	/collections/{id}	catalog:write	Archive or hard-delete a collection
Collections	PUT	/collections/{id}/translations/{lang}	catalog:write	Upsert a translation
Collections	DELETE	/collections/{id}/translations/{lang}	catalog:write	Remove a translation
Knowledge	POST	/knowledge	knowledge:write	Create or upsert a knowledge item
Knowledge	POST	/knowledge/batch	knowledge:write	Upsert up to 500 items
Knowledge	GET	/knowledge	knowledge:read	List knowledge items
Knowledge	GET	/knowledge/{id}	knowledge:read	Retrieve an item
Knowledge	PUT	/knowledge/{id}	knowledge:write	Replace an item
Knowledge	PATCH	/knowledge/{id}	knowledge:write	Partially update an item
Knowledge	DELETE	/knowledge/{id}	knowledge:write	Archive or hard-delete an item
Knowledge	PUT	/knowledge/{id}/translations/{lang}	knowledge:write	Upsert a translation
Knowledge	DELETE	/knowledge/{id}/translations/{lang}	knowledge:write	Remove a translation
Knowledge	POST	/knowledge/{id}/file-upload-url	knowledge:write	Mint a SAS URL for a file upload
Knowledge	POST	/knowledge/{id}/file-upload-completed	knowledge:write	Finalise a file upload
Imports	POST	/imports	imports:write	Create an import + get upload URL
Imports	GET	/imports/{sync_id}	imports:write	Poll an import's status
Imports	POST	/imports/{sync_id}/start	imports:write	Start processing an uploaded import
Imports	POST	/imports/{sync_id}/cancel	imports:write	Cancel a pending or running import
Webhooks	POST	/webhooks/endpoints	webhooks:manage	Register an endpoint
Webhooks	GET	/webhooks/endpoints	webhooks:manage	List endpoints
Webhooks	GET	/webhooks/endpoints/{id}	webhooks:manage	Retrieve an endpoint
Webhooks	PATCH	/webhooks/endpoints/{id}	webhooks:manage	Update an endpoint
Webhooks	DELETE	/webhooks/endpoints/{id}	webhooks:manage	Delete an endpoint
Webhooks	POST	/webhooks/endpoints/{id}/rotate-secret	webhooks:manage	Rotate the signing secret
Webhooks	GET	/webhooks/deliveries	webhooks:manage	List recent deliveries
Webhooks	GET	/webhooks/deliveries/{id}	webhooks:manage	Inspect a delivery

SDKs

None today. The API is designed to be flat enough that any HTTP client works:

• cURL for one-shots and shell scripts
• fetch in Node, browsers, Deno, Bun
• requests in Python
• http.Client in Go
• Any other JSON-over-HTTPS client

If you'd like a typed SDK in your language of choice, reach out to support. Tell us what language matters most to you.

Status & changelog

• Service status: thehumind.com/status
• Public API changes are tracked in the changelog.

Next

• Authentication: generate, use, and rotate keys.
• Conventions: request format, identifiers, idempotency, versioning.
• Errors: error format, HTTP codes, Humind error codes.
• Rate limits: current per-key limits, the 429 response, backoff.
• Products: push your catalog.
• Collections: group products for narrower assistant recommendations.
• Knowledge: push the content the assistant grounds its answers on.
• Imports: async NDJSON ingestion for large catalogs.
• Webhooks: receive signed event deliveries instead of polling.