API Reference

Complete reference for the Helix Humanize API.

Base URL

https://api.feeds.onhelix.ai

Authentication

All requests require API key authentication using the Bearer token scheme:

Authorization: Bearer YOUR_API_KEY

See the Authentication Guide for details on obtaining and using API keys.

Submit Humanize Request

Submit text for humanization. Returns immediately with a job ID. The humanization runs asynchronously -- poll the status endpoint or retrieve results when ready.

POST /humanize

Request

Headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Body:

{
  "text": "It is important to note that the utilization of comprehensive strategies can facilitate the optimization of outcomes.",
  "styleGuide": "Write in a casual, conversational tone.",
  "maxIterations": 10,
  "jobId": "my-custom-job-id"
}

Parameters:

Parameter	Type	Required	Description
text	string	Yes	Text to humanize (1-100,000 characters)
styleGuide	string	No	Style instructions for the rewriter (1-2,000 characters)
maxIterations	number	No	Maximum modification passes (1-20, default: 10)
jobId	string	No	Custom job identifier for idempotency (alphanumeric, hyphens, underscores, max 256 chars)

Response

Status: 202 Accepted

{
  "success": true,
  "data": {
    "jobId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Response Fields:

Field	Type	Description
jobId	string	Job identifier. Use this to check status and get results

Idempotency

Submitting a request with an existing jobId reconnects to the running or completed workflow instead of starting a new one. If the previous job with that jobId failed, the API returns a 400 error.

Errors

400 Bad Request:

{
  "success": false,
  "error": "Previous humanize job failed. Please retry with a new jobId."
}

{
  "success": false,
  "error": "Validation error: text must be at least 1 character"
}

401 Unauthorized:

{
  "success": false,
  "error": "Invalid or missing API key"
}

Example

curl -X POST https://api.feeds.onhelix.ai/humanize \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Furthermore, the implementation of robust methodologies facilitates enhanced outcomes.",
    "maxIterations": 5
  }'

Check Status

Check the current status of a humanize job.

GET /humanize/:jobId/status

Request

Headers:

Authorization: Bearer YOUR_API_KEY

Path Parameters:

Parameter	Type	Required	Description
jobId	string	Yes	Job identifier

Response

Status: 200 OK

{
  "success": true,
  "data": {
    "jobId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed"
  }
}

Response Fields:

Field	Type	Description
jobId	string	Job identifier
status	string	Current status: running, completed, failed

Status Values:

Status	Description
running	Job is actively processing
completed	Job finished successfully, results are available
failed	Job failed (workflow failed, timed out, terminated, or cancelled)

Errors

401 Unauthorized:

{
  "success": false,
  "error": "Invalid or missing API key"
}

404 Not Found:

{
  "success": false,
  "error": "Job not found: my-job-id"
}

Example

curl "https://api.feeds.onhelix.ai/humanize/550e8400-e29b-41d4-a716-446655440000/status" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Result

Retrieve the humanization result. If the job is still processing, the request waits up to 60 seconds for completion before returning an error.

GET /humanize/:jobId

Request

Headers:

Authorization: Bearer YOUR_API_KEY

Path Parameters:

Parameter	Type	Required	Description
jobId	string	Yes	Job identifier

Query Parameters:

Parameter	Type	Required	Description
includeRewrittenText	boolean	No	Include the final rewritten text (default: true)

Response

Status: 200 OK

{
  "success": true,
  "data": {
    "jobId": "550e8400-e29b-41d4-a716-446655440000",
    "originalText": "It is important to note that the utilization of comprehensive strategies can facilitate the optimization of outcomes.",
    "modifications": [
      [
        {
          "fragment": {
            "prefix": "",
            "match": "It is important to note that the utilization of comprehensive strategies can facilitate the optimization of outcomes.",
            "suffix": ""
          },
          "replaceWith": "Using broad strategies helps improve outcomes.",
          "reasoning": "Removed hedging phrase and replaced formal vocabulary"
        }
      ]
    ],
    "rewrittenText": "Using broad strategies helps improve outcomes."
  }
}

Response Fields:

Field	Type	Description
jobId	string	Job identifier
originalText	string	The original text that was submitted
modifications	array	Array of modification batches (see below)
rewrittenText	string	Final humanized text (omitted if includeRewrittenText=false)

Modification Batch Structure:

Each modification batch is an array of individual modifications:

Field	Type	Description
fragment.prefix	string	Text immediately before the replaced section
fragment.match	string	The exact text that was replaced
fragment.suffix	string	Text immediately after the replaced section
replaceWith	string	The replacement text
reasoning	string	Why this modification was made

Errors

401 Unauthorized:

{
  "success": false,
  "error": "Invalid or missing API key"
}

404 Not Found:

{
  "success": false,
  "error": "Job not found: my-job-id"
}

500 Internal Server Error:

{
  "success": false,
  "error": "Humanize job failed. Please retry with a new jobId."
}

{
  "success": false,
  "error": "Humanize job is still processing. Poll GET /humanize/:jobId/status and retry when completed."
}

{
  "success": false,
  "error": "Humanize job completed but produced no output."
}

Example

# Get full result
curl "https://api.feeds.onhelix.ai/humanize/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get result without rewritten text (modifications only)
curl "https://api.feeds.onhelix.ai/humanize/550e8400-e29b-41d4-a716-446655440000?includeRewrittenText=false" \
  -H "Authorization: Bearer YOUR_API_KEY"

Error Responses

All endpoints may return these standard errors:

400 Bad Request

Invalid request parameters or body:

{
  "success": false,
  "error": "Validation error: text must be at least 1 character"
}

401 Unauthorized

Missing or invalid API key:

{
  "success": false,
  "error": "Invalid or missing API key"
}

404 Not Found

Job not found:

{
  "success": false,
  "error": "Job not found: my-job-id"
}

500 Internal Server Error

Server error:

{
  "success": false,
  "error": "An internal error occurred. Please try again later."
}

Next Steps

• Quickstart Guide: Get started in under 5 minutes
• Overview: Understand how humanization works
• Authentication: API key best practices