Docs

One script tag and one function, onetag.ask. The same reference, written for AI coding tools, is at llms.txt.

Install

Get a key, then add two script tags to your page:

<script src="https://onetagai.com/v1.js" data-key="YOUR_ONETAG_KEY"></script>
<script type="module">
  const summary = await onetag.ask("Summarize in 3 bullets", document.body);
</script>

The SDK tag is a classic script, so onetag is ready before any module script runs. Top-level await only works inside <script type="module">, so put your calls there (or inside an async function).

The SDK is open source (github.com/fengyiqicoder/onetagai). You can also load it from jsDelivr, https://cdn.jsdelivr.net/gh/fengyiqicoder/onetagai@main/sdk/v1.js, or copy v1.js into your own site; it talks to https://onetagai.com/v1/ask either way.

onetag.ask

onetag.ask(prompt, input?, options?) → Promise<string | object>

prompt is the instruction. input is what it works on. The promise resolves with the answer as text, or as a parsed object when you pass json: true.

Input

Options

<script type="module">
  const out = document.querySelector("#answer");
  await onetag.ask("Explain this table to a beginner", document.querySelector("table"), {
    stream: (delta) => { out.textContent += delta; },
    maxTokens: 300,
  });
</script>

onetag.configure

onetag.configure({ key: "YOUR_ONETAG_KEY", endpoint: "https://onetagai.com/v1/ask" });

Sets the key in code instead of the data-key attribute. endpoint defaults to /v1/ask on the server the SDK was loaded from; you only need it to point the SDK somewhere else.

Handling errors

Every failure throws onetag.OneTagError with .code (from the table below), .message (a sentence you can show to people) and .status (the HTTP status, or 0 when there was no response).

<script type="module">
  const out = document.querySelector("#out");
  try {
    out.textContent = await onetag.ask("Translate to French", document.querySelector("#text"));
  } catch (e) {
    out.textContent = e.code === "quota_exceeded" ? "The AI is taking a break." : e.message;
  }
</script>

Error codes

Limits

We email you when a key has used 80% and 100% of its tokens. A free key that is used up answers quota_exceeded until it is upgraded; a Pro key until the 1st.

Pricing

Upgrade with the email your key belongs to; the key itself does not change. Cancelling in the billing portal puts the key back on Free at the end of the paid month.

Domain lock (Pro)

A Pro key can be locked to a domain from its dashboard. Then it only works from browser pages on that domain or its subdomains, and on localhost or 127.0.0.1 while you build. A key locked to example.com works on www.example.com and blog.example.com, not on example.org. OneTag AI checks the Origin header the browser sends, or the Referer when there is no Origin.

A locked key rejects every request without an Origin or Referer with domain_not_allowed: curl, code running on a server, and pages opened from file://. A locked key is for browser pages on your site. Clear the domain on the manage page to allow everything again.

Free keys are never locked: they work from any page, any domain and curl, and anyone who copies the key out of your page source shares its 1,000,000 tokens. That is what the lock is for.

HTTP API

The SDK wraps one endpoint. You can call it directly from any language with a key that is not locked to a domain.

POST https://onetagai.com/v1/ask
Content-Type: application/json

Example

curl https://onetagai.com/v1/ask \
  -H "Content-Type: application/json" \
  -d '{"key": "YOUR_ONETAG_KEY", "prompt": "Summarize in one sentence", "input": "OneTag AI lets any static page call an AI model with one script tag, without a backend and without an API key in the page."}'

The answer, with the tokens it used:

{"text": "OneTag AI adds AI to static pages with a single script tag.", "usage": {"input": 61, "output": 14}}

Streaming

With "stream": true the response is text/event-stream: one data: line per event, with a blank line between events. The text arrives in delta events, and the last event carries done and the usage.

data: {"delta": "OneTag AI adds"}

data: {"delta": " AI to static pages"}

data: {"delta": " with a single script tag."}

data: {"done": true, "usage": {"input": 61, "output": 14}}

If the AI provider fails partway through, the stream ends with an error event instead: data: {"error": {"code": "upstream", "message": "..."}}.

Errors

Errors found before the answer starts come back as JSON with the HTTP status from the error table:

HTTP/1.1 401 Unauthorized

{"error": {"code": "bad_key", "message": "Unknown or disabled key."}}