API v2 Migration Guide: What’s Changed and Why

API v2 Migration Guide: What’s Changed and Why

We’re releasing API v2 today, and we know that API changes can be a headache. We’ve been crystal clear that API v1 isn’t going anywhere, it’ll stay available for the next 12 months. But we built v2 to address some pain points we’ve heard from our API customers, and we wanted to make migration straightforward.

Here’s what changed, why we changed it, and how to move your implementation forward if you want to take advantage of the new features.

What’s New in V2

Response Structure: v2 uses a more consistent response format. Every successful request returns the same JSON structure with content, metadata, and confidence score. No more variable response shapes depending on which endpoint you hit.

Error Handling: Instead of HTTP status codes that sometimes didn’t match the actual error type, v2 uses explicit error codes in the response. You can handle errors programmatically instead of trying to parse status codes.

Batch Processing: The Batch Endpoint is v2-only. If you want to use batch processing, you need to migrate to v2.

Webhooks: v2 introduces webhook support for asynchronous processing. You can submit a long-running request and get notified when it completes instead of polling.

Authentication: We’ve simplified auth. Instead of API key in headers, v2 supports API key in headers or as a query parameter. Easier to test, more flexible for different deployment scenarios.

Why We Made These Changes

Consistency matters. v1 grew organically, and different endpoints returned data in different formats. That meant your integration code had to handle multiple response shapes. v2 standardizes everything.

Error handling was our biggest pain point. Customers were trying to catch errors based on HTTP status codes, but that didn’t always map to the actual error. v2 uses explicit error codes so you know exactly what happened and why.

Async processing was the other big one. Some requests naturally take longer than others. v1 forced you to wait for synchronous responses or set short timeouts. v2’s webhook support means you can submit requests, do other things, and get notified when they’re ready. That’s better for production systems.

Migration Steps

Step 1: Update your authentication. If you’re using API key in headers (Authorization: Bearer YOUR_KEY), that still works in v2. No change required. But you now have the option to pass the key as a query parameter, which can be simpler in some scenarios.

Step 2: Update your response handling. v2 responses have a consistent structure. Get the sample response from our documentation, update your code to parse that structure instead of checking for variable formats.

Step 3: Update your error handling. Instead of catching HTTP errors, catch v2 error codes and handle them explicitly. That’s more reliable than trying to interpret status codes.

Step 4: Test. We’ve built a v2 sandbox environment where you can test your implementation before pointing production traffic at v2.

How Long Do I Have to Migrate?

v1 will be fully supported through April 2027. That’s 12 months from release. We’re not rushing you. But v2 will have all the new features and ongoing improvements. Eventually, v1 will reach end-of-life and we’ll deprecate it.

Most customers we’ve worked with migrate in a few hours. The changes are straightforward. The longest part is usually testing.

Code Examples

Our documentation includes before/after code examples for every major language. Python, JavaScript, Go, Ruby, Java. See what your implementation looks like in v2, compare it to v1, and understand what needs to change.

We’ve also built migration checklist in the documentation. Go through it step by step and you’ll catch everything.

Webhook Setup

If you want to use webhooks for async processing, you need to set up a webhook endpoint that can receive POST requests from us. Your webhook receives an event payload with the humanized content when processing completes.

That’s optional. You can still use synchronous requests in v2 if you prefer. But webhooks unlock async processing, which is useful for batch operations.

Support During Migration

We’re here to help. Our support team has v2 documentation and can help you troubleshoot any issues during migration. We’re also monitoring the sandbox environment to identify any gotchas early.

If you hit blockers, reach out. Migration should be smooth, and we want to make sure it is.

What’s Next

v2 is the foundation for features we’re building next: better streaming for large requests, enhanced webhook retry logic, and simplified SDKs in more languages.

The consistent structure of v2 makes those things possible. That’s part of why we did this refactoring now.

Ready to Upgrade?

v2 is live now. You can start migrating immediately or wait until you need v2 features like batch processing or webhooks. v1 will keep working.

Check out our API documentation for the full v2 specification, code examples, and step-by-step migration guides.

Questions? Our support team is standing by.

What changed between v1 and v2

The v2 API is a non-breaking superset of v1 with a few intentional simplifications. If you’re on v1, you can keep running unchanged through the deprecation window. To take advantage of the new capabilities (richer responses, batch v2, webhooks), migrate at your own pace.

Endpoint changes

Request shape

The request body is unchanged for the standard endpoint:

// v1 (still works)
{ "text": "...", "tone": "professional" }

// v2 (same)
{ "text": "...", "tone": "professional" }

Optional new fields in v2:

• preserveKeywords – array of strings to lock from rewriting. Useful for SEO.
• language – explicit ISO 639-1 code; previously auto-detected only.
• humanizationLevel – integer 1-5, controls how aggressively the engine rewrites. 3 is default.
• callbackUrl – for batch jobs, send results to a webhook instead of polling.

Response shape

v2 responses are a superset of v1. Existing fields are unchanged:

{
  "success": true,
  "humanized_text": "...",
  "confidence_score": 0.94,
  "processing_time_ms": 1247,
  "tokens_used": 42
}

New fields added in v2 (always present, but optional to consume):

• request_id – for support tickets and trace logs.
• language_detected – ISO 639-1 code, even if you specified one.
• cache_status – hit or miss (we cache identical inputs for 1 hour).
• tone_applied – confirms which tone was used (helpful when you don’t pass one).

Authentication

No change. v1 keys work in v2 with no migration. Authorization: Bearer YOUR_KEY header is the only auth method.

Migration paths by integration type

Direct HTTP calls (no SDK)

Just update the URL prefix from https://api.aihumanizerapi.com/humanize to https://api.aihumanizerapi.com/v1/humanize. That’s the entire change. Your existing payload and response handling work unchanged.

// Before
fetch('https://api.aihumanizerapi.com/humanize', {...})

// After
fetch('https://api.aihumanizerapi.com/v1/humanize', {...})

Python SDK

Update to the latest SDK release:

pip install --upgrade aihumanizer

# Code stays the same
from aihumanizer import Client
client = Client(api_key='...')
result = client.humanize('your text', tone='professional')

The SDK targets v2 endpoints by default in 1.2.0+. Pin to aihumanizer==0.x if you need to stay on v1 temporarily.

Node.js SDK

npm install @aihumanizer/sdk@latest

const { Client } = require('@aihumanizer/sdk');
const client = new Client({ apiKey: process.env.AIH_API_KEY });
const result = await client.humanize({ text: 'your text', tone: 'professional' });

WordPress plugin

The plugin auto-updates to v2 endpoints with no config change. If you have any custom code calling the plugin’s hooks directly, no changes needed.

Zapier / Make integrations

Both have been updated to v2. Existing zaps and scenarios continue to run; new ones will use v2 by default. No action required.

New features worth adopting

Batch endpoint with webhooks

v1 batch was synchronous and capped at 50 items. v2 raises to 100 per request and adds an async path for jobs of any size. For example, to humanize 1,000 items:

POST /v1/humanize/batch
{
  "items": [/* up to 1000 */],
  "callbackUrl": "https://yourapp.com/webhook/humanize-complete"
}

// Response
{ "job_id": "j_abc123", "status": "queued" }

Your webhook receives the full result when the job completes. Saves you polling overhead. See webhook setup for the full flow.

Streaming responses

For chat-style interfaces or live-typing UIs, the new /v1/humanize/stream endpoint returns Server-Sent Events as the engine produces tokens. Useful for chatbot integrations where users expect to see output appearing in real time.

Confidence-based routing

The confidence_score field is more accurate in v2 (calibrated against detector pass-rate). Use it to route low-confidence outputs to human review:

const result = await client.humanize({ text, tone });
if (result.confidence_score < 0.85) {
  await routeToReviewQueue(text, result.humanized_text);
} else {
  await publish(result.humanized_text);
}

Tone application visibility

The new tone_applied response field tells you which tone the engine used. If you didn’t specify one and want to know the default behavior, this confirms it.

Deprecation timeline

• 2026-01-15 – v2 launched, both versions live.
• 2026-09-01 – v1 deprecated. Returns Deprecation header but still works.
• 2026-12-31 – v1 removed. Calls return 410 Gone.

If you’re still on v1 in Q4 2026, you’ll start receiving the Sunset response header pointing to this guide. We’ll also email key contacts ahead of removal.

Troubleshooting common migration issues

“My SDK upgrade broke type hints”

v2 SDK responses include the new fields by default, which may cause stricter TypeScript or Python type checks to fail. Update your response type to match the v2 schema in our API docs.

“Confidence scores changed after migrating”

The v2 confidence score is recalibrated. v1 scores were optimistic; v2 scores correlate more directly with detector pass-rate. A v1 score of 0.97 typically maps to a v2 score of 0.92-0.94. Your acceptance threshold may need to drop slightly.

“Rate limit errors after migration”

v1 and v2 share the same rate-limit pool, so migrating shouldn’t change your limits. If you’re seeing 429s post-migration, it’s probably unrelated. Check the Retry-After header and adjust your client’s backoff. See rate-limit best practices.

“Streaming endpoint returns 400”

The streaming endpoint requires Accept: text/event-stream in the request header. Without it, you get 400. Most HTTP clients don’t set this by default – add it explicitly.

If you hit anything unexpected, open a support ticket with the request_id from a failing call (it’s in v2 response payloads). We’ll trace it server-side and respond same-day for paying customers.

For new accounts, sign up for a free API key and start on v2 directly – there’s no reason to write new integrations against the deprecating v1 surface.