Connector — REST & MCP API

The Connector is a Pro-plan feature that lets your own LLM enrich your store’s Bot It data — Brand Context, Collection narratives, Product narratives — through a REST API and a hosted MCP server.

You bring the LLM. We provide the typed surface, the auth, and the workflow guidance. The LLM does the writing.

Why use it

The in-app editors are great for one-off edits. But if you have 500 products that need narratives, fit notes, and materials info, clicking through one at a time is slow. The Connector turns that into a job you can hand to your LLM of choice:

• Claude Desktop, ChatGPT, Cursor, Gemini — anything with MCP support gets native tool calling against your store.
• REST API — anything that can make an HTTPS call can use it (LangChain, custom scripts, Zapier, etc.).
• Background sync stays automatic — every update queues a Shopify metafield sync to your Knowledge Base. You don’t manage that.

Endpoints

All endpoints live at https://app.botitai.com. Auth is Authorization: Bearer botit_pat_<token> on every request.

Method	Path	Description
GET	/v1/brand-context	Read brand context + missing_fields[]
PATCH	/v1/brand-context	Partial update (empty string clears a field; faq array replaces the list)
GET	/v1/collections	List collections merged with narrative state. Supports `?completion=complete
GET	/v1/collections/partial	Fast SQL-only scan of partially-enriched collections (no Shopify call)
GET	/v1/collections/{id}	Single collection + missing_fields
PATCH	/v1/collections/{id}	Partial update of narrative fields
GET	/v1/products	List products. Supports completion, title, tag, product_type, vendor, status, sort
GET	/v1/products/partial	Fast SQL-only scan of partially-enriched products
GET	/v1/products/{id}	Single product + missing_fields
PATCH	/v1/products/{id}	Partial update of narrative fields
POST	/v1/mcp	MCP JSON-RPC 2.0 endpoint (initialize / tools/list / tools/call)
GET	/v1/docs.json	Machine-readable schema (public, no auth) — point an LLM at this for self-discovery

Every read response includes a missing_fields[] array — the exact list of fields that are empty for that item. Your LLM should target only those.

Authentication

In the Bot It admin, open the Connector tab and click Create token. Tokens look like botit_pat_<48 hex> and are shown once at creation time — copy immediately. You can label tokens, revoke them, and see when they were last used.

Send the token as a Bearer header on every request:

Authorization: Bearer botit_pat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Rate limit: 600 requests per token per rolling hour. Exceeding returns HTTP 429.

Quick example — write a product narrative

curl -X PATCH https://app.botitai.com/v1/products/8123456789012 \
  -H "Authorization: Bearer botit_pat_..." \
  -H "Content-Type: application/json" \
  -d '{
    "narrative": "Engineered for trail runners who prioritize ground feel...",
    "materials_notes": "Recycled mesh upper, EVA midsole, Vibram MegaGrip outsole"
  }'

The update queues a background sync to your Shopify Knowledge Base — no further action needed.

Finding work to do

Three patterns, in order of usefulness for an LLM-driven enrichment loop:

# Items started but not finished (SQL-only, fast on any store size)
curl "https://app.botitai.com/v1/products/partial?limit=50" \
  -H "Authorization: Bearer botit_pat_..."

# Items never touched
curl "https://app.botitai.com/v1/products?completion=empty" \
  -H "Authorization: Bearer botit_pat_..."

# A specific item — response includes missing_fields[]
curl "https://app.botitai.com/v1/products/8123456789012" \
  -H "Authorization: Bearer botit_pat_..."

MCP setup

The MCP endpoint is https://app.botitai.com/v1/mcp. Same Bearer token, JSON-RPC 2.0 over HTTP.

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "botit": {
      "url": "https://app.botitai.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer botit_pat_YOUR_TOKEN_HERE"
      }
    }
  }
}

ChatGPT, Cursor, other MCP clients

Use the same URL and Authorization header. Tools exposed:

• get_brand_context, update_brand_context
• list_collections, list_partial_collections, get_collection, update_collection_narrative
• list_products, list_partial_products, get_product, update_product_narrative

System prompt — what to tell your LLM

Paste this into your LLM’s system prompt verbatim. Replace the token placeholder with one you mint in the Connector tab.

You are enriching a Shopify store's Bot It data via the Connector API.

ABOUT BOT IT
Bot It is a Shopify app that makes merchant stores discoverable and recommendable by AI
shopping agents (ChatGPT, Claude, Perplexity, Gemini, Copilot, etc.). The data you write
is NOT customer-facing marketing copy — it's structured context that other AI agents read
when answering "tell me about this store" or "find me a [product type]". Write for that
audience: factual, specific, grounded in real product details. The richer and more accurate
the context, the more often this merchant's products get surfaced and recommended.

CONNECTION
- Base URL:                https://app.botitai.com
- Auth header (every req): Authorization: Bearer <PASTE YOUR botit_pat_ TOKEN HERE>
- MCP endpoint (JSON-RPC): POST https://app.botitai.com/v1/mcp
- Human docs:              https://docs.botitai.com/features/connector/
- Machine-readable schema: https://app.botitai.com/v1/docs.json
  (Fetch once and treat as source of truth for paths and field names.)

YOU CAN
- Read & write Brand Context (voice, story, support, policies, FAQ, social, loyalty)
- Read & write Collection narratives (narrative, agent_search_keywords, merchandising_notes)
- Read & write Product narratives (narrative, fit, materials, use cases, comparisons, size chart, etc.)
Every read response includes `missing_fields[]` — the exact list of fields that are empty.

WORKFLOW
1. GET /v1/brand-context — fill missing fields first; every product narrative inherits tone from brand voice.
2. GET /v1/products/partial — finish products you started but didn't complete (fast SQL, no Shopify call).
3. GET /v1/products?completion=empty — find never-enriched products.
4. For each: GET /v1/products/{id}, ground in the live Shopify page, then PATCH /v1/products/{id} with ONLY fields in missing_fields.
5. Repeat for collections (/v1/collections/partial, /v1/collections?completion=empty).

CONSTRAINTS
- Never fabricate certifications, materials, sustainability claims, dimensions, or sizing data. Leave the field blank if unverifiable.
- Match brand_voice exactly — that is the merchant's voice, not yours.
- Never overwrite existing non-empty fields unless explicitly asked.
- Rate limit: 600 req/hour per token. On 429, back off ~60s.

ERRORS
- 401: token missing / invalid / revoked → stop and ask the merchant for a new one.
- 403: store no longer on Pro → stop.
- 400: unknown field → check spelling against /v1/docs.json.

Error codes

All errors return JSON of the form:

{ "error": { "code": "invalid_token", "message": "..." } }

Code	HTTP	Meaning
invalid_token	401	Token missing, malformed, or revoked.
plan_required	403	Store is not on Pro.
rate_limited	429	600/hr exceeded. Back off ~60s and resume.
invalid_request	400	Unknown field, bad payload, or missing id.

Plan & pricing

The Connector is included in Pro at no extra cost. Free-plan stores can browse the docs but cannot mint tokens. Compare plans →