GitHubContact Support
DocsAPI ReferenceGuidesExamples

Search Documentation

Search through documentation, guides, and resources.

API Documentation

Integrate Truuly's humanization and detection capabilities into your applications

Last Updated: January 27, 2025

Getting Started

Base URL

https://api.truuly.me/v1

Authentication

All API requests require authentication using your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Rate Limits

Pro Plan

  • • 100 requests per minute
  • • 50,000 words per month
  • • Burst: 200 requests in 10 seconds

Enterprise Plan

  • • Custom rate limits
  • • Unlimited words (or custom limit)
  • • Dedicated API endpoints

Rate limit headers are included in all responses:

X-RateLimit-Limit: 100X-RateLimit-Remaining: 95X-RateLimit-Reset: 1706380800

Endpoints

1. Humanize Text

POST/humanize

Transform AI-generated text into natural, human-like content.

Request Body

{
  "text": "string (required, 10-5000 words)",
  "mode": "light|balanced|aggressive|stealth (optional, default: balanced)",
  "tone": "formal|balanced|casual (optional, default: balanced)",
  "vocabulary": "basic|standard|advanced (optional, default: standard)",
  "projectId": "string (optional)",
  "returnDetection": true|false (optional, default: false)
}

Response

{
  "success": true,
  "data": {
    "humanizedText": "string",
    "originalWordCount": 500,
    "humanizedWordCount": 495,
    "transformationPercent": 65,
    "aiScoreBefore": 87,
    "aiScoreAfter": 15,
    "processing": {
      "model": "gpt-4o",
      "temperature": 0.75,
      "timeMs": 3500
    },
    "detection": { // if returnDetection=true
      "average": 15,
      "detectors": {
        "gptzero": 12,
        "zerogpt": 18,
        "originality": 14,
        "local": 16
      }
    }
  },
  "metadata": {
    "requestId": "req_abc123",
    "timestamp": "2025-01-27T15:30:00Z",
    "wordsUsed": 500
  }
}

Example Request (cURL)

curl -X POST https://api.truuly.me/v1/humanize \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "In today's digital landscape...",
    "mode": "aggressive",
    "tone": "casual",
    "returnDetection": true
  }'

2. Detect AI Content

POST/detect

Analyze text and get AI probability scores from multiple detectors.

Request Body

{
  "text": "string (required, 50-10000 words)",
  "detectors": ["gptzero", "zerogpt", "originality", "local"] (optional)
}

Response

{
  "success": true,
  "data": {
    "averageScore": 75,
    "classification": "ai", // "human" | "mixed" | "ai"
    "detectors": {
      "gptzero": {
        "score": 78,
        "confidence": "high",
        "details": "..."
      },
      "zerogpt": {
        "score": 72,
        "confidence": "high"
      },
      "originality": {
        "score": 80,
        "confidence": "high"
      },
      "local": {
        "score": 70,
        "aiWordCount": 15,
        "aiPhraseCount": 8
      }
    },
    "analysis": {
      "burstiness": 0.45,
      "perplexity": 0.60,
      "aiWordCount": 15,
      "aiPhraseCount": 8
    }
  },
  "metadata": {
    "requestId": "req_def456",
    "timestamp": "2025-01-27T15:31:00Z"
  }
}

3. Batch Humanize

POST/humanize/batch

Process multiple texts in a single request. Asynchronous processing with webhook callback.

Request Body

{
  "items": [
    {
      "id": "item1",
      "text": "string",
      "mode": "balanced",
      "tone": "casual"
    },
    {
      "id": "item2",
      "text": "string",
      "mode": "aggressive"
    }
  ],
  "webhookUrl": "https://your-app.com/webhook (optional)",
  "projectId": "string (optional)"
}

Response

{
  "success": true,
  "data": {
    "batchId": "batch_xyz789",
    "status": "processing",
    "itemCount": 2,
    "estimatedCompletionTime": "2025-01-27T15:35:00Z"
  }
}

Check status with GET /humanize/batch/:batchId or wait for webhook callback.

4. Get Usage Stats

GET/usage

Get current usage statistics for your API key.

Response

{
  "success": true,
  "data": {
    "currentPeriod": {
      "start": "2025-01-01T00:00:00Z",
      "end": "2025-02-01T00:00:00Z",
      "wordsUsed": 25000,
      "wordsLimit": 50000,
      "requestsUsed": 1250,
      "requestsLimit": 10000
    },
    "today": {
      "wordsUsed": 500,
      "requestsUsed": 25
    },
    "rateLimit": {
      "limit": 100,
      "remaining": 95,
      "resetAt": "2025-01-27T16:00:00Z"
    }
  }
}

Error Handling

Error Response Format

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Text must be between 10 and 5000 words",
    "details": {
      "field": "text",
      "received": 8,
      "expected": "10-5000"
    }
  },
  "metadata": {
    "requestId": "req_error123",
    "timestamp": "2025-01-27T15:32:00Z"
  }
}

Common Error Codes

400 - VALIDATION_ERRORClient Error

Invalid request parameters. Check error details for specific field issues.

401 - UNAUTHORIZEDClient Error

Missing or invalid API key. Check Authorization header.

403 - FORBIDDENClient Error

API key doesn't have permission for this endpoint. Upgrade plan or check API key permissions.

429 - RATE_LIMIT_EXCEEDEDClient Error

Too many requests. Check X-RateLimit headers and implement backoff strategy.

402 - USAGE_LIMIT_EXCEEDEDClient Error

Monthly word limit reached. Upgrade plan or wait for reset.

500 - INTERNAL_SERVER_ERRORServer Error

Something went wrong on our end. Retry with exponential backoff or contact support.

503 - SERVICE_UNAVAILABLEServer Error

Service temporarily unavailable (maintenance or high load). Retry after delay indicated in Retry-After header.

SDK Libraries

Official SDKs

Node.js / TypeScript

npm install @truuly/sdk
import { Truuly } from '@truuly/sdk';

const truuly = new Truuly('YOUR_API_KEY');

const result = await truuly.humanize({
  text: 'Your AI text...',
  mode: 'balanced'
});

console.log(result.humanizedText);

Python

pip install truuly
from truuly import Truuly

truuly = Truuly(api_key='YOUR_API_KEY')

result = truuly.humanize(
    text='Your AI text...',
    mode='balanced'
)

print(result.humanized_text)

Community SDKs

Community-maintained libraries (not officially supported):

  • PHP: truuly/php-sdk
  • Ruby: truuly-rb
  • Go: github.com/truuly/truuly-go

Best Practices

Implement Exponential Backoff

When you hit rate limits (429) or server errors (500/503), retry with exponential backoff: 1s, 2s, 4s, 8s, etc.

Cache Results

Humanizing the same text always gives similar results. Cache humanized output to save API calls and reduce latency.

Use Batch Endpoint for Multiple Texts

If processing multiple texts, use /humanize/batch instead of individual requests. It's more efficient and avoids rate limits.

Monitor Usage Proactively

Call /usage endpoint periodically to track consumption. Set up alerts when approaching 80% of limits.

Don't Expose API Keys Client-Side

Never include API keys in frontend JavaScript. Always proxy through your backend to protect credentials.

Don't Ignore Error Responses

Always check success field and handle errors gracefully. Log error details for debugging.

Next Steps

API Setup

Resources