Moving to napi.neuwo.ai

The Auto-Tagging API answers at https://napi.neuwo.ai. An integration built against the previous address, https://m1api.neuwo.ai, moves by changing that one setting. The token, the paths, the request fields and the shape of the response are the same at both addresses.

This page is for the developer making that change. The API reference describes every endpoint and field, and the Introduction shows a first call.

What to change

The settings that belong to your account, such as the tag limit, the minimum score, the IAB Content version, Google Topics, smart tags and the language of the tag names, are carried over. Tokens are enabled at the new address account by account. Until yours is, a call there answers 403. Neuwo confirms when your account is ready.

What stays the same

• The response carries the same top-level keys in the same order. Every tags[].URI is wrapped in angle brackets, and every score and relevance is a string.
• brand_safety comes back as BS_score and BS_indication.
• Smart tags come from the same rules.
• The error codes and their bodies: 401 when the token is missing, 403 when it is not recognised, 422 when a required field is missing or the content is only whitespace.
• The defaults: XML unless the call sends format=json, and a tag_min_score of 0.1 unless your account or the call sets another.

What the new address adds

None of these need a change in an existing integration.

• The token can also travel in an Authorization: Bearer header, which keeps it out of URLs and access logs. ?token= keeps working.
• Every response carries an X-Request-Id header. Quote it when you contact Neuwo about a call.
• Optional request fields: headline_weight, iab_content_versions, iab_audience_versions, google_topics and per-tier IAB Content limits. The reference describes each one.
• When classification is temporarily unavailable, the answer is a 503 with a JSON body of {"message": "…"}. The previous address could answer 200 with an empty result in that situation. Treat a 503 as a call to repeat shortly.
• Pictures. POST /GetAiTopics/image classifies an image with the same token: send image_url in place of content, and the answer has the same shape as for text. Images shows the call.
• Sentiment. On request, Neuwo switches on a page-level sentiment for your account. The response then carries one more key, sentiment, after the existing ones, or three more elements at the end of the XML. Until it is switched on, nothing changes. Sentiment describes the field.

Small differences to check in your code

• Scores and relevances carry up to four decimals. The previous address sent up to five for tag scores and two for relevances. Compare them as numbers.
• parents holds the same chains, but entries on the same level can come in a different order. The order is not part of the contract.
• The same text gives the same answer on every call.

How to move

1. If your network has an egress allow-list, add napi.neuwo.ai. Do not pin the certificate: it is issued by Let's Encrypt and renews on its own.
2. Send one call to the new address and compare the keys with a call to the previous one.
3. Change the base URL. Every environment at once is the simplest. A staged change also works, since both addresses answer the same token.
4. Let Neuwo know the day you switch, at adops@neuwo.ai.

To go back, change the base URL back. Nothing else is needed, because no state moves between the addresses.