How to Connect Hermes Agent to Originality.ai Detector API

Originality.ai's official API documentation sets a hard rate limit of 500 requests per minute and returns HTTP 429 when that ceiling is hit. API access also requires an Enterprise subscription before you can create a key on the token dashboard. Those two constraints explain the real job for content ops: you need programmatic originality detector scans that batch, retry, and log, not another person pasting prose into a browser tab between deadlines.

An Originality detector integration lets Hermes Agent submit content to Originality.ai via API and return AI-likelihood scores into a reusable content workflow. Search demand sits in a narrow but commercial band. DataForSEO US estimates for "originality detector" run near 140 monthly searches at keyword difficulty 82 of 100, while "originality.ai api" is smaller (about 20 monthly searches) with a CPC near $7.97. High difficulty mostly reflects brand-navigational SERPs around Originality.ai itself. Official docs answer endpoints and headers. They do not show Hermes skill prompts, batch loops, or where scan reports should live so a human can audit them next week. That content gap is the reason for this guide.

Originality.ai publishes API V3 at https://api.originality.ai/api/v3 with REST endpoints for single scan, batch scan, URL scan, credit balance, and scan results. Auth is a single header: X-OAI-API-KEY. A scan can toggle AI detection, plagiarism, fact checking, readability, grammar, and AI Allowance in one request. Responses return AI confidence (AI vs Original), optional block-level scores, plagiarism matches, and credit usage. Vendor model notes claim Lite stays under a 1% false positive rate when light AI editing is acceptable, and Turbo under 5% when you want harder-to-bypass detection. Treat those figures as vendor-published guidance and validate them on your own corpus before you wire hard publish gates.

Nous Research Hermes Agent is an open-source (MIT) autonomous agent you run yourself, not a hosted SaaS copilot. Official docs describe skills under ~/.hermes/skills/ that follow the agentskills.io standard, progressive disclosure so full procedures load only when needed, and MCP servers declared in ~/.hermes/config.yaml under mcp_servers for tools that live outside Hermes. Skills can declare required_environment_variables that Hermes prompts for on local CLI load and passes into terminal and code sandboxes. Messaging gateways will not collect secrets in chat. That skill-plus-env surface is the clean place to hang the Originality.ai API.

Connect-and-scan checklist

1. Subscribe to Originality.ai Enterprise and create an API key on the token dashboard.
2. Store ORIGINALITY_API_KEY in ~/.hermes/.env (never in git or skill markdown).
3. Author a skill (or thin MCP wrapper) that POSTs plain text to /api/v3/scan.
4. Run a single-document smoke test and parse results.ai.confidence.
5. Add batch scanning with concurrency well under 500 requests per minute.
6. Write timestamped JSON reports beside the source draft and share them for human review.
7. Confirm auto credit top-up settings so a runaway loop cannot surprise-bill the card on file.

Follow these steps in order. You can stop after a successful single scan if you only need local CLI validation. Production content pipelines should complete report storage so scores outlive the agent session.

1. Get Enterprise access and an API key

Official setup is explicit: create or log into Originality.ai, subscribe at the Enterprise plan tier, then create an API key from the API token dashboard. Without Enterprise, you will not have a production API path even if you can use the browser product. Issue one key per environment (dev, staging, prod) so a leaked local key does not open the production credit balance.

All requests must send:

X-OAI-API-KEY: your-api-key

Base URL for Version 3:

https://api.originality.ai/api/v3

2. Put the key in Hermes environment config

Hermes skills can declare required environment variables and prompt for them securely when the skill loads in the local CLI. Messaging surfaces tell you to set secrets with local setup or ~/.hermes/.env instead of collecting keys in chat. For Originality.ai:

# ~/.hermes/.env (keep out of git)
ORIGINALITY_API_KEY=your_key_here

Declared skill env vars pass through to execute_code and terminal sandboxes when the skill loads. Prefer that path over embedding the key in a one-liner the model can echo later. Keep Fast.io MCP tokens and Originality keys under separate names so blast radius stays small.

3. Author a Hermes skill for the Originality.ai scan API

Most teams start with a skill because Originality.ai is a REST API, not a packaged MCP product. Skills live under ~/.hermes/skills/ with a required SKILL.md. Example skeleton (adjust paths and thresholds for your team):

---
name: originality-detect
description: Scan plain text with the Originality.ai detector API and return AI scores.
version: 1.0.0
platforms: [macos, linux]
metadata:
  hermes:
    tags: [originality, ai-detector, plagiarism]
    category: quality
---

# Originality.ai detector skill

## When to Use
Score drafts, client deliverables, or agent-written prose before publish or human review.

## Procedure
1. Read the target plain text or file path from the user.
2. POST to https://api.originality.ai/api/v3/scan with X-OAI-API-KEY.
3. Prefer check_ai true; only enable plagiarism/facts when policy requires them.
4. Return title, aiModelVersion, AI confidence, Original confidence, credits used.
5. Write a timestamped JSON report next to the source draft.

## Pitfalls
- Submit plain text. Formatted HTML and PDF blobs hurt scoring accuracy.
- storeScan false means you cannot reopen vendor-side results later.
- Plagiarism checks can take up to 60 seconds and may time out on long copy.
- Never print the API key in chat transcripts or report files.

## Verification
A short known-human sample should not force extreme AI confidence on ordinary prose.

You can also walk Hermes through one successful call, then run /learn so the agent authors a skill that follows house authoring standards. Keep write-approval gates on if you do not want unsupervised skill edits.

4. Make a single-scan smoke test

A minimal Python helper keeps HTTP handling deterministic. Hermes can run it via terminal or execute_code once ORIGINALITY_API_KEY is present:

import json
import os
import sys
import urllib.request

BASE = "https://api.originality.ai/api/v3"

def scan(title: str, content: str, model: str = "lite") -> dict:
    key = os.environ.get("ORIGINALITY_API_KEY")
    if not key:
        raise RuntimeError("ORIGINALITY_API_KEY is not set")
    body = json.dumps({
        "title": title,
        "check_ai": True,
        "check_plagiarism": False,
        "check_facts": False,
        "check_readability": False,
        "check_grammar": False,
        "storeScan": True,
        "aiModelVersion": model,
        "content": content,
    }).encode("utf-8")
    req = urllib.request.Request(
        f"{BASE}/scan",
        data=body,
        headers={
            "Content-Type": "application/json",
            "X-OAI-API-KEY": key,
        },
        method="POST",
    )
    with urllib.request.urlopen(req, timeout=90) as resp:
        return json.loads(resp.read().decode("utf-8"))

if __name__ == "__main__":
    path = sys.argv[1]
    with open(path, "r", encoding="utf-8") as f:
        print(json.dumps(scan(path, f.read()), indent=2))

Curl shape from the official docs (swap host path to the V3 base in production):

curl --location 'https://api.originality.ai/api/v3/scan' \
  --header 'X-OAI-API-KEY: your-api-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "Smoke test draft",
    "check_ai": true,
    "check_plagiarism": false,
    "check_facts": false,
    "check_readability": false,
    "check_grammar": false,
    "storeScan": true,
    "aiModelVersion": "lite",
    "content": "Plain text sample for an originality detector smoke test."
  }'

5. Optional MCP wrapper for multi-tool agents

If other agents or tools already speak MCP, wrap the same REST client as a small stdio MCP server and register it in Hermes:

# ~/.hermes/config.yaml
mcp_servers:
  originality:
    command: "node"
    args: ["/path/to/originality-mcp-server.js"]
    env:
      ORIGINALITY_API_KEY: "${ORIGINALITY_API_KEY}"

Official Hermes MCP docs support local command/args/env servers and remote url/headers HTTP servers, plus per-server tool filters so you expose only scan_text and credit_balance rather than every helper method. Prefer a skill first; graduate to MCP when more than one agent process needs the same tool surface.

Keep Originality.ai scan reports next to every draft

Give Hermes Agent a shared workspace with MCP access so detector JSON, drafts, and editor decisions stay versioned and searchable. Start with a 14-day free trial on Starter ($29/mo), Business ($99/mo), or Growth ($299/mo).

Start 14-Day Trial

A useful originality detector API call returns more than a single percentage. Originality.ai V3 responses nest results under a results object. For AI detection you care about three surfaces first.

Fields Hermes should always capture

Title and identifiers: The request title plus any private/public identifiers returned in results.properties. Use them to join the report back to the draft filename.

• Credits used: results.credits.used so budget scripts can stop before auto top-up buys more credits than planned.
• AI classification and confidence: results.ai.classification and results.ai.confidence with AI and Original scores. Example smoke responses show high AI confidence (near 0.95) on sample prose that the model treats as synthetic. Map those floats into team policy (allow, review, block) instead of inventing ad hoc cutoffs per chat.
• Block-level scores: results.ai.blocks[] with per-paragraph fake / real values. Editors need spans, not only document averages.
• AI Allowance: When check_ai_allowance is true, responses include allowance buckets (0%, 5%, 15%, 25%, 40%). Treat allowance as a policy dial, not a second accuracy metric. A 15% threshold means hybrid editing is acceptable; a 0% threshold is zero-tolerance.

Keep plagiarism, facts, readability, and grammar off by default for pure authenticity gates. Each extra check costs credits and latency. Official docs note plagiarism can take up to 60 seconds depending on document size. If you hit timeouts, split long copy into chunks and scan separately, then merge report sections yourself.

Choosing aiModelVersion

Official model strings include:

• lite: Vendor guidance claims under 1% false positives and suits cases where lightly AI-edited text is acceptable (often academia-oriented workflows).
• turbo: Vendor guidance claims under 5% false positives and positions Turbo as harder to bypass on recent LLMs (GPT-4o class, Gemini Pro, Claude 3, Llama 3, and similar).
• multilang: Non-English coverage for languages listed in the docs (including Spanish, French, German, Portuguese, Chinese, Japanese, and others).
• lite-102: Newer Lite beta line when you are testing model upgrades.
• academic: Framed for teachers and students when institutional policy is the buyer.

Pin the model string in the skill so two agents in the same week do not silently disagree because one used Turbo and one used Lite. Log the model name inside every report file.

Plain text in, structured policy out

Docs recommend plain text for the most accurate AI scoring. Hermes should strip CMS chrome, HTML, and markdown decoration before the POST body when your goal is authenticity, not formatting QA. After the response lands, normalize into an internal schema such as:

{
  "source_path": "drafts/client-a/post.md",
  "vendor": "originality.ai",
  "endpoint": "/api/v3/scan",
  "aiModelVersion": "turbo",
  "ai_confidence": 0.12,
  "original_confidence": 0.88,
  "decision": "review",
  "credits_used": 9,
  "scanned_at": "2026-07-17T12:00:00Z"
}

Store the raw vendor JSON next to the normalized summary. Future model upgrades will break assumptions if you only keep a single float.

Official docs document a Batch Scan endpoint alongside single scan. Content teams usually need Hermes to walk a folder of drafts, not hit one endpoint once. Design the batch layer yourself even when you use the vendor batch route, because agent workflows still own concurrency, retries, and report paths.

Safe batch loop pattern

1. List candidate files from the workspace or local directory.
2. Convert each file to plain text.
3. Cap concurrent POSTs well below 500 requests per minute (start with 5 to 10 in-flight jobs for editorial traffic).
4. On HTTP 429, back off using remaining-limit headers when present, then retry with jitter.
5. On timeouts during plagiarism-enabled scans, fall back to AI-only or split the document.
6. Write one report JSON per source file plus a batch summary CSV or JSONL for the editor queue.

A skill prompt that works well for Hermes:

Scan every Markdown file under drafts/pending with originality-detect.
Use aiModelVersion turbo, check_ai true, other checks false, storeScan true.
Max concurrency 5. On 429, wait and retry up to 3 times.
Write reports under reports/originality/{basename}-{timestamp}.json.
After the batch, print a table of path, AI confidence, decision, credits used.

Credits and auto top-up

Originality.ai accounts can auto top up credits when balances fall low, charging the default payment method so workflows keep running. That is convenient for always-on queues and dangerous for an agent loop with a bug. Before unattended batches, open top-up settings, lower or disable auto top-up for staging keys, and poll the credit balance endpoint so Hermes can stop when remaining credits cross a hard floor. Manually purchasing credits is the safer path for controlled campaigns.

Error classes worth encoding in the skill

• 401 / 403: Bad or missing X-OAI-API-KEY. Fail closed; do not invent "human" scores.
• 429: Rate limit. Back off. Do not fan out more workers.
• Timeouts: Common when plagiarism or long documents are enabled. Reduce checks or chunk content.
• Empty or non-plain content: Refuse to scan and ask for plain text rather than POSTing binary noise.
• Partial batch failure: Keep successful reports, list failures with status codes, and never delete source drafts.

Browser tool vs API workflow

The browser product is better for ad hoc spot checks by a single editor. The Originality.ai API is better when Hermes Agent (or any automation) must scan dozens of drafts, apply consistent model and allowance settings, and leave machine-readable reports. If your volume is occasional and human-driven, stay in the UI. If authenticity is a gate in a content pipeline, wire the API through a Hermes skill and treat the browser as the exception path for edge cases the agent escalates.

A detector score that dies in chat history is not an editorial control. After Hermes receives the JSON, persist it with the draft so reviewers can reopen both sides of the decision.

Local disk works for single-developer experiments. Write reports under a reports/originality/ folder next to the repo and commit only redacted samples. Local disk fails when the agent runs on Docker, Modal, or a remote SSH host that disappears after the job, or when two editors need the same file without SSH access.

Object storage (S3, GCS, Azure Blob) works for durable blobs and lifecycle policies. You still build listing, permissions, and review UI yourself. Raw buckets do not give semantic search over "show me last week's Turbo scans above 0.7 AI confidence" without extra indexing work.

Shared intelligent workspaces sit between those options for agent-plus-human teams. Fast.io is one such workspace: org-owned storage with per-file version history, granular permissions, an append-only audit log, Intelligence Mode for hybrid search after indexing, and a consolidated MCP toolset over Streamable HTTP at /mcp (legacy SSE at /sse). Hermes can write the draft and the Originality report into the same workspace folder. Editors open the files in the UI while agents use MCP. For broader agent storage patterns, see storage for agents and the MCP skill documentation.

Practical layout:

content-ops/
  drafts/
    2026-07-17-client-post.md
  reports/
    originality/
      2026-07-17-client-post-turbo.json
  decisions/
    2026-07-17-client-post-review.md

When reports need structured fields (AI confidence, model version, decision, editor, scanned_at), Metadata Views can turn a folder of JSON or PDF summaries into a sortable grid without hand-built OCR rules. Intelligence Mode remains the search and summarization layer; Metadata Views is the extraction layer when you want typed columns agents can query later.

Human review should still own the final call. Detectors misclassify non-native English writing, heavily edited hybrid drafts, and some newer model outputs. Hermes can queue a task or collaborative note when AI confidence crosses a threshold, attach the report, and wait for an approval step before any branded client share goes out. Ownership transfer on Fast.io lets an agent stage the workspace, then hand the org-owned project to a human editor while keeping admin access for support.

Pricing context if you evaluate Fast.io as that handoff layer: Starter is $29/mo, Business $99/mo, Growth $299/mo. Every organization starts with a 14-day free trial that requires a credit card. Creating a user account does not unlock workspace work until an organization is on a paid subscription (or its trial).