API

This section is for developers. If you have not read Getting started yet, it says what Neuwo returns and how else it can reach your pages.

Two APIs

Each has its own token and base URL, and a token issued for one does not work on the other. Both are issued by Neuwo together with the endpoint URL: contact Neuwo or email adops@neuwo.ai, as there is no self-service signup.

• The EDGE API takes a URL. Neuwo fetches the published page and analyses it. It is built for calls from the browser, and it is the API Bid Enrichment runs on, by both the Prebid module and the Google Ad Manager route.
• The Auto-Tagging API takes the text itself, for content that is not published yet or has no public address. It is a server-side call.

Make your first call

One request to the EDGE API, with the token and the page you want analysed:

curl -H "origin: https://example.com" "YOUR_ENDPOINT/edge/GetAiTopics?token=YOUR_TOKEN&url=https://example.com/article"

Three things decide whether this works:

• The base URL is the endpoint Neuwo issued you. ctx.neuwo.ai is the shared one; if you were given your own, use that instead.
• The origin header is required, and it names the site the request comes from. Your endpoint answers the origins it is configured for and refuses the rest.
• The first call for a new URL usually returns a message instead of categories. Neuwo queues the page, which typically takes 10 to 60 seconds. Call again after that and the categories are there.

A 401 means the token is wrong or missing, and a 403 means the token is valid but is not allowed to do this.

To analyse text rather than a published page, post it to the Auto-Tagging API with its own token:

curl -X POST "https://napi.neuwo.ai/api/aitopics/GetAiTopics?token=YOUR_AUTO_TAGGING_TOKEN" \
  --data-urlencode "format=json" \
  --data-urlencode "headline=Cats: The Perfect Companion for Modern Living" \
  --data-urlencode "content=Cats make wonderful pets for modern households."

• Send format=json. Without it the answer comes back as XML.
• The categories come back in the same call. Text is analysed while you wait, so there is nothing to call again.
• The headline is analysed with the text. headline_weight sets how much it counts, or 0 leaves it out; see the API reference.

Read the response

Trimmed to one entry per block, this is the shape the Auto-Tagging API returns:

{
  "tags": [
    {
      "URI": "<https://tags.neuwo.ai/masterID101332>",
      "value": "Domestic Animals and Pets",
      "score": "0.79728"
    }
  ],
  "brand_safety": { "BS_score": "1.0", "BS_indication": "yes" },
  "marketing_categories": {
    "iab_tier_1": [{ "ID": "IAB16", "label": "Pets", "relevance": "0.54" }]
  },
  "smart_tags": [{ "ID": "123", "name": "animals-group" }]
}

• tags is the subject in Neuwo's own vocabulary, each with a unique ID and a score. The Auto-Tagging API names the ID URI and wraps it in angle brackets; treat it as an opaque string.
• brand_safety comes back in one of two shapes, either BS_score and BS_indication, which is what the Auto-Tagging API returns, or score and indication, so read it defensively.
• marketing_categories holds the standard sets: iab_tier_1 to iab_tier_3, iab_audience_tier_3 to iab_audience_tier_5, google_topics, and marketing_items for any custom categories built for you. A set with nothing in it can be left out, so treat each one as optional.
• smart_tags is filled only if smart tags are enabled for your account.

Scores and relevances are strings, not numbers. Parse before you compare them.

If Neuwo could not analyse the page, the response carries an error message rather than any of these blocks.

Images

The Auto-Tagging API also classifies a picture. The address is the text endpoint with /image at the end, the token is the same, and image_url takes the place of content:

curl -X POST "https://napi.neuwo.ai/api/aitopics/GetAiTopics/image?token=YOUR_AUTO_TAGGING_TOKEN" \
  -d "image_url=https://example.com/images/wildfire.jpg" \
  -d "format=json"

• image_url or image_b64. A public address Neuwo fetches, or the bytes themselves base64-encoded, with image_mime such as image/jpeg. JPEG, PNG, WebP, GIF, BMP and TIFF up to 25 MB by URL, or about 15 MB as base64. content and headline can travel in the same call to classify a picture together with its story.
• The answer is the same as for text. It carries the tags, marketing_categories, brand_safety and smart_tags blocks described under Read the response, as JSON or XML, with the settings of your token. The other fields of the text endpoint, such as format, lang and tag_limit, work here too.
• Neuwo reads the picture on its own infrastructure and classifies what it is about with the same models as an article. No third party sees the picture.
• The score limits for IAB categories on pictures are set by Neuwo. The per-call IAB limits of the text endpoint do not apply to a picture.
• A picture that cannot be fetched or decoded answers 400. When the image service is temporarily unavailable, the answer is 503: repeat the call shortly.

Sentiment

On request, Neuwo adds a page-level sentiment to the answers of the Auto-Tagging API: whether the events a text reports are negative, neutral or positive, and how strongly. An obituary, an accident report or a match lost are negative; a product launch, an award or a match won are positive; reference, service and most factual news reporting are neutral, which is deliberately the wide default band.

It is a separate question from brand safety. An accident report is negative and brand-safe at the same time, and brand_safety keeps answering the safety question on its own.

• Neuwo switches it on for your account, on request at adops@neuwo.ai. There is no request parameter for it. Until it is on, nothing in your responses changes: the field is left out, never sent as null.
• The object is the same on every endpoint. label is negative, neutral or positive. score is a number from -1 to 1 with two decimals, the strength of that valence rather than a confidence. model_version names the model that produced it, sentiment-model-v1 today.
• label is a band of score. Neutral is a deliberately wide band in the middle of the scale. If you want a narrower or wider neutral band, cut on score yourself, and pin model_version, because a new model version can move the cuts.
• Sentiment is computed when a text is analysed. A text that Neuwo analysed before sentiment was available can come back from its cache without the field for up to two days; a fresh analysis carries it. Treat a missing sentiment as not computed, never as neutral.

Where it appears:

• POST /GetAiTopics with format=json: a sentiment object as the last key of the response, after smart_tags.
• POST /GetAiTopics as XML: three elements at the end, sentiment_label, sentiment_score and sentiment_model_version. Without the feature none of the three is sent.
• POST /GetAiTopics/image: the same as POST /GetAiTopics, in JSON and in XML.
• POST /GetCustomTopics: the same object after tags, or the same three elements in XML.

The call itself does not change. A routine piece of local news, sent as under Make your first call:

curl -X POST "https://napi.neuwo.ai/api/aitopics/GetAiTopics?token=YOUR_AUTO_TAGGING_TOKEN" \
  --data-urlencode "format=json" \
  --data-urlencode "headline=Council approves next year's road maintenance budget" \
  --data-urlencode "content=The city council approved next year's road maintenance budget on Tuesday. Resurfacing of the main street begins in May and is expected to take four months, with traffic diverted along the ring road during the work. Residents can follow the schedule on the city's website."

With sentiment switched on, the answer ends with the new object. Trimmed to the blocks you already know:

{
  "tags": [ … ],
  "brand_safety": { "BS_score": "1.0", "BS_indication": "yes" },
  "marketing_categories": { … },
  "smart_tags": [],
  "sentiment": {
    "label": "neutral",
    "score": 0.04,
    "model_version": "sentiment-model-v1"
  }
}

• score is a number, unlike the scores and relevances above it, which are strings.
• A score of 0.04 sits inside the neutral band: a factual report with no loss or gain in it. A strongly negative report scores towards -1, a celebratory one towards 1.

The same answer as XML ends with the three elements before the closing tag:

<rsp version="1.0">
  …
  <sentiment_label>neutral</sentiment_label>
  <sentiment_score>0.04</sentiment_score>
  <sentiment_model_version>sentiment-model-v1</sentiment_model_version>
</rsp>

Reference

Every endpoint, parameter and response, with a request builder.

API reference

SDKs

• JavaScript and TypeScript
• Python
• .NET

Per-endpoint code samples for each SDK are shown inside the reference next to the endpoint they belong to. These pages cover installation, authentication and a full walkthrough.

Moving from the previous address

An integration built against https://m1api.neuwo.ai moves to https://napi.neuwo.ai by changing its base URL. The token, the paths and the response are the same. What changes, and how to move.