Webanto API reference

Authenticate every request with a bearer API key in the Authorization header. Keys are secret — the raw value is shown only once, when you create or rotate a key.

Create and manage keys under Settings → API Keys.

Authorization: Bearer wba_live_xxxxxxxxxxxxxxxxxxxxxxxx

Base URL: https://api.webanto.com/api/v1

Enrich and publish are asynchronous. Send a unique Idempotency-Key, then poll the returned job ID or include a public HTTPS webhook with a 32-character-or-longer signing secret. Routes whose scope is an OAuth scope also accept an OAuth access token as the bearer; inference, catalog and usage routes accept API keys only.

curl https://api.webanto.com/api/v1/products/product_id/enrich \
  -H "Authorization: Bearer $WEBANTO_API_KEY" \
  -H "Idempotency-Key: 01J8WEBANTOEXAMPLE" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook": {
      "url": "https://example.com/webhooks/webanto",
      "secret": "replace-with-at-least-32-random-characters"
    }
  }'

Download the canonical OpenAPI 3.1 document

Authenticate with a Webanto API key. Each tool needs its key scope, and the key owner must still hold the matching organization permission. The tool list shows only the tools the key can call, and no tool publishes to a live store.

{
  "mcpServers": {
    "webanto": {
      "type": "http",
      "url": "https://webanto.com/api/mcp",
      "headers": { "Authorization": "Bearer ${WEBANTO_API_KEY}" }
    }
  }
}

Setup guide for Claude, ChatGPT, Claude Code, Codex, Cursor and VS Code

POST /api/v1/embeddings

model

The embeddings model to use: "nomic-embed-text" or "clip".

input

A single string or an array of up to 100 strings to embed.

curl https://api.webanto.com/api/v1/embeddings \
  -H "Authorization: Bearer $WEBANTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nomic-embed-text",
    "input": ["a photo of a cat", "a photo of a dog"]
  }'

{
  "model": "nomic-embed-text",
  "data": [
    { "index": 0, "embedding": [0.0123, -0.0456, "..."] },
    { "index": 1, "embedding": [0.0789, -0.0012, "..."] }
  ],
  "usage": { "total_tokens": 14 },
  "credits": 1
}

POST /api/v1/image-embeddings

urls

An array of up to 60 https image URLs to embed. Provide urls or images, not both.

images

An array of up to 60 base64-encoded image objects with a b64 field. Provide images or urls, not both.

curl https://api.webanto.com/api/v1/image-embeddings \
  -H "Authorization: Bearer $WEBANTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "urls": ["https://cdn.example.com/card.jpg"] }'

{
  "model": "dinov3",
  "dim": 1280,
  "embeddings": [[0.009, -0.002, "..."]],
  "errors": [],
  "credits": 1
}

POST /api/v1/images

prompt

The text description of the image to generate (required, up to 4000 characters).

size

One of 1328x1328, 1664x928, 928x1664, 1472x1104, 1104x1472, 1584x1056, or 1056x1584. Defaults to 1328x1328. Credits scale with pixel count.

seed

Optional seed, 0 to 4294967295. The same prompt, size, and seed reproduce the image; the response returns the seed.

curl https://api.webanto.com/api/v1/images \
  -H "Authorization: Bearer $WEBANTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "qwen-image", "prompt": "a red maple leaf on a white background, studio product photo", "size": "1328x1328" }'

{
  "created": 1730000000,
  "model": "qwen-image",
  "data": [{ "b64_json": "iVBORw0KGgo...", "seed": 1234567 }],
  "credits": 8
}

POST /api/v1/images/remove-background

curl https://api.webanto.com/api/v1/images/remove-background \
  -H "Authorization: Bearer $WEBANTO_API_KEY" \
  -H "Content-Type: image/jpeg" \
  --data-binary @product.jpg \
  --output cutout.png

HTTP/1.1 200 OK
Content-Type: image/png
X-Webanto-Model: birefnet-general
X-Webanto-Credits: 2

<raw PNG bytes — product on solid white>

POST /api/v1/chat

model

The chat model to use: "qwen".

messages

An array of up to 50 message objects with role and content fields. Role is system, user, or assistant.

max_tokens

Optional. Maximum tokens to generate (up to 4096). Reasoning calls are floored to 3072 so hidden reasoning can't consume the whole budget and return empty content; the floor is not applied when reasoning_effort is "none".

temperature

Optional. Sampling temperature between 0 and 2.

reasoning_effort

Optional; reasoning is on by default. Set to none for fewer completion tokens and credits on extraction or classification, with weaker multi-step reasoning. The SDK values low, medium, and high all keep reasoning on; they do not select different levels.

web_search

Optional; default false. Searches and reads pages before answering, reporting sources under x_webanto_web_search. Requires the search scope and cannot be combined with images. Uses more tokens than a direct call; enable when current information is needed.

X-Webanto-Priority

Optional header; default interactive. Use background for scheduled or batch jobs, which queue separately from capacity reserved for live users. Other values return 400.

curl https://api.webanto.com/api/v1/chat \
  -H "Authorization: Bearer $WEBANTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen",
    "messages": [{ "role": "user", "content": "Explain embeddings in one sentence." }]
  }'

{
  "id": "chatcmpl-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "chat.completion",
  "created": 1721260800,
  "model": "qwen",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "..." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 12, "completion_tokens": 24, "total_tokens": 36 },
  "credits": 1
}

curl https://api.webanto.com/api/v1/chat \
  -H "Authorization: Bearer $WEBANTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen",
    "reasoning_effort": "none",
    "messages": [{ "role": "user", "content": "Extract the year as a bare number: The treaty was signed in 1885." }]
  }'

curl https://api.webanto.com/api/v1/chat \
  -H "Authorization: Bearer $WEBANTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen",
    "web_search": true,
    "messages": [{ "role": "user", "content": "What changed in the latest Next.js release?" }]
  }'

{
  "choices": [ { "index": 0, "message": { "role": "assistant", "content": "..." }, "finish_reason": "stop" } ],
  "usage": { "prompt_tokens": 4820, "completion_tokens": 310, "total_tokens": 5130 },
  "credits": 3,
  "x_webanto_web_search": {
    "sources": ["https://nextjs.org/blog/..."],
    "sourced": true,
    "expected": true,
    "searches": 1,
    "turns": 3,
    "exhausted": false
  }
}

1. 1

   Queued

   Your task is saved and waiting to start or resume.
   →
2. 2

   Running

   Work is underway. Counts update as items finish.
   →
3. 3

   Check the results

   Review successful, failed, and unfinished items before taking the next action.

Request headers

Verify the signature

Compute the HMAC over the raw body exactly as received, compare in constant time, and reject timestamps more than 300 seconds old to block replays. Rotating the signing secret takes effect for every attempt that has not yet been sent.

const crypto = require("node:crypto");

// `rawBody` must be the exact bytes Webanto sent, before any JSON parsing.
function verifyWebhook(rawBody, headers, secret) {
  const header = headers["webanto-signature"] ?? "";
  const parts = Object.fromEntries(header.split(",").map((part) => part.split("=")));
  const timestamp = Number(parts.t);
  const signature = parts.v1;
  if (!Number.isInteger(timestamp) || !signature) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(signature);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Payload shape

Every event uses the same envelope. The data object depends on the event type.

{
  "id": "products.sync_completed:wfjob_123",
  "type": "products.sync_completed",
  "created_at": "2026-11-05T12:00:00.000Z",
  "organization_id": "org_123",
  "data": { "integration": "shopify", "mode": "delta", "total_synced": 12 }
}

Events