# Resolver — AI customer support for Shopify

> Resolver reads a merchant's support inbox, matches each email to the real Shopify order, and drafts or auto-sends accurate replies in the customer's language. This file tells an AI assistant (e.g. Claude) how to use the Resolver API on a merchant's behalf.

## API basics
- Base URL: https://app.resolver.chat/api/v1
- Auth: every request needs the header  Authorization: Bearer RESOLVER_API_KEY  where the key starts with rsk_live_ or rsk_test_. The merchant creates a key in the Resolver dashboard under Settings -> "API & MCP". Keys are scoped (read vs write) and can be revoked at any time.
- Format: JSON. List responses use the envelope { "object":"list", "data":[...], "has_more":bool, "next_cursor":string|null }. Paginate by passing ?cursor=THE_NEXT_CURSOR. Single resources carry an "object" field. Every response includes an X-Request-Id header.
- Errors: { "error": { "type","code","message","request_id" } } with the matching HTTP status (401 no/blank key, 403 insufficient_scope, 404 not-owned/absent, 429 rate limited).
- Always start with GET /me — it returns the key's company, mode (live/test), granted scopes, and how many stores it can reach.

## Endpoints
- GET /me — key context.
- GET /shops , GET /shops/{id} — the merchant's connected Shopify stores.
- GET /tickets?shop_id=&status=&category=&limit=&cursor= — support tickets, newest activity first (limit <= 200). status e.g. OPEN, WAITING_CUSTOMER, RESOLVED, ESCALATED. Omit shop_id for all stores.
- GET /tickets/{id} — one ticket: the full email thread, the AI-written draft reply, the matched Shopify order snapshot, and the customer's order history.
- POST /tickets/{id}/regenerate  body {instructions?} — (re)generate the AI reply draft. Does NOT send. Scope: tickets:write.
- POST /tickets/{id}/reply  body {body?} — send a reply to the customer (uses the saved draft when body is omitted). THIS EMAILS A REAL CUSTOMER. Scope: tickets:write.
- GET /disputes , GET /disputes/{id} — chargebacks / payment disputes with evidence status.
- GET /customs , GET /customs/{id} — customs / clearance holds detected in tracking.
- GET /tasks , GET /tasks/{id} ; POST /tasks {title,detail?,col?,due?,ticket_id?} ; PATCH /tasks/{id} ; DELETE /tasks/{id} — the team task board. Writes: tasks:write.
- GET /stats?shop_id=&days= — support metrics (ticket volume, open backlog, resolution rate, reply times) over the owned stores.

## How an AI should use this
1. Call GET /me and GET /shops to learn the account.
2. To triage, list GET /tickets?status=OPEN then GET /tickets/{id} for full context.
3. To answer a ticket: POST /tickets/{id}/regenerate to draft, show the merchant the draft, and only POST /tickets/{id}/reply AFTER they approve — replying sends a real email.
4. A read-only key returns 403 insufficient_scope on any write; ask the merchant for a full-access key if writes are needed.
5. Anything the key does not own returns 404 — you can never see another merchant's data.

## Connect via MCP (Model Context Protocol)
There is an MCP server that exposes these endpoints as tools (list_tickets, get_ticket, regenerate_draft, send_reply, list_disputes, list_customs, list_tasks, create_task, update_task, delete_task, stats). It calls this same API. Configure it with env RESOLVER_API_KEY (required) and optional RESOLVER_API_BASE (default https://app.resolver.chat). Full human + AI guide: https://resolver.chat/for-ai

## Example
curl -H "Authorization: Bearer rsk_live_YOURKEY" https://app.resolver.chat/api/v1/tickets?status=OPEN&limit=5

Human docs: https://resolver.chat/for-ai