Back to API docs

API v2 and MCP

One set of actions — catalog (products, categories, attributes, tags, images) and sales proposals (templates, clients, lines) — available three ways: as a simple JSON API, as MCP tools for AI models, and to the AI tools inside Wantly.

1. API key

Use your tenant address, e.g. https://your-company.wantly.eu. The plan must include API access.
Main key — Settings → API → Generate API key. Full access to every action.
Scoped keys — limited keys for AI models or integrations. Scopes: catalog.read (search and read), catalog.write (create and change), catalog.delete (trash products, merge and delete categories), proposals.read (list and read proposals, templates, contacts), proposals.write (create and edit proposals), proposals.delete (delete proposals), proposals.send (e-mail proposals to clients), contacts.read (search and read contacts), contacts.write (create and change contacts). Ask your administrator to create one.
Send the key as Authorization: Bearer YOUR_KEY or X-Api-Key: YOUR_KEY.

2. Simple JSON API

Every action is POST /api/v2/{action} with a JSON object. Responses are always one of:

{ "ok": true,  "action": "products_search", "dry_run": false, "data": { ... } }
{ "ok": false, "action": "products_get", "error": { "code": "not_found", "message": "Product not found: X1", "details": { } } }

Over MCP the same action is a tool: on success the tool result is the data object; on failure the result has isError: true and the body {"ok": false, "error": {"code", "message", "details"}}. With dry_run the result is wrapped as {"dry_run": true, "result": …}.

Error codes: unauthorized (401), forbidden (403, key scope), not_found (404), conflict (409), invalid_input (422, unknown or wrong fields are reported by name), internal_error (500).

Preview any change: write actions accept "dry_run": true — everything runs and the result is returned, then rolled back.

curl -X POST https://your-company.wantly.eu/api/v2/products_search \
  -H "Authorization: Bearer YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"query": "kettle", "limit": 5}'

Machine-readable spec (OpenAPI 3): /api/v2/openapi.json. Actions allowed for a key: GET /api/v2/actions.

Guide for AI agents: catalog guide (Markdown) — how products, variations, attributes, categories, tags and images work, the rules for merging and cleanup, and step-by-step workflows. Give it to any model that will work on the catalog; MCP clients get it as the guide_read tool and the wantly://guides/catalog resource. For proposals: proposals guide (/api/v2/guide?topic=proposals, guide_read with "topic": "proposals", MCP resource wantly://guides/proposals).

3. Connect an AI model (MCP)

The same actions are MCP tools at https://your-company.wantly.eu/api/mcp (Streamable HTTP). The tool list follows the key's scopes, or the permissions given at sign-in.

claude.ai, Claude Desktop / mobile (Connectors) and ChatGPT — sign in with your Wantly account, no API key needed:

claude.ai → Settings → Connectors → Add custom connector (ChatGPT: Settings → Connectors → Create). Name: Wantly; URL: the MCP address above. Leave the OAuth client fields empty.
Click Connect. A Wantly page opens: log in (and pass 2FA), tick what the AI may do, click Allow.
The AI now works as you: new proposals get you as the author. Administrators can grant every permission; other users can read the catalog and prepare proposals and contacts.

Signed-in sessions renew automatically for 60 days of inactivity. See or disconnect apps at /oauth/connections. The plan must include API access.

Clients with an API key (Claude Code, Cursor, scripts):

Claude Code

claude mcp add --transport http wantly https://your-company.wantly.eu/api/mcp --header "Authorization: Bearer YOUR_KEY"

Cursor (.cursor/mcp.json) and other clients that accept a URL with headers

{
  "mcpServers": {
    "wantly": {
      "url": "https://your-company.wantly.eu/api/mcp",
      "headers": { "Authorization": "Bearer YOUR_KEY" }
    }
  }
}

Clients that only run local (stdio) servers can bridge with mcp-remote:

npx -y mcp-remote https://your-company.wantly.eu/api/mcp --header "Authorization: Bearer YOUR_KEY"

The older proposal-only wrapper (Connect an agent) keeps working.

4. Actions

Loading the action list…