How to Connect Hermes Agent to the Copyleaks API

Copyleaks issues access tokens that remain valid for 48 hours after the login call. That single number is why browser paste tools fail enterprise workflows and why agent integrations need more than a one-off curl. A token that lasts two days supports overnight batch jobs and multi-step Hermes sessions, but it also expires while a careless script still holds yesterday's bearer string. Teams that need an API audit trail, not a dashboard paste, end up building token cache, unique scan IDs, classification parsing, and report storage whether they planned to or not.

Search demand for the integration surface is early but commercially real. DataForSEO US estimates for "copyleaks api" sit near 40 monthly searches with keyword difficulty 27 of 100 and CPC about $5.59. Nearby commercial detector demand stays hot; AI code detection still shows CPC near $17.90. The market is small in volume and expensive in intent: buyers want programmatic authenticity checks, not another browser tab.

The Copyleaks API is a REST interface for plagiarism and AI-content detection that Hermes Agent can call from skills, scripts, or MCP-wrapped tools. Official Copyleaks docs describe an AI Text Detection API that classifies text as human-written or AI-generated, returns a per-section classification plus an overall human-versus-AI summary, and explains flags with AI Logic. Detection covers 30+ languages and models such as ChatGPT, Gemini, Claude, and DeepSeek. Official SDKs ship for Python, JavaScript, Java, C#, PHP, and Ruby. What the vendor docs do not cover is Hermes skill packaging, credential handling in ~/.hermes/.env, or agent-to-human handoff of scan reports.

Nous Research Hermes Agent is an open-source (MIT) autonomous agent, not a hosted SaaS copilot. Official docs describe MCP for external tools and a skills system compatible with the agentskills.io standard. Skills live under ~/.hermes/skills/ with progressive disclosure so the agent loads full procedures only when needed. MCP servers are declared in ~/.hermes/config.yaml under mcp_servers, with stdio and HTTP transports, env isolation for subprocesses, and optional per-server tool filters. Catalog install flows write API keys into ~/.hermes/.env. That is the natural place to hang a Copyleaks AI detector API call.

The rest of this article walks a five-step connect path (create key, store credentials, skill template, submit text, parse classification), then covers response fields, report handoff, and production edge cases. Fast.io enters only as one durable workspace option for the report handoff layer, after local disk and object storage.

Follow these five steps in order. You can stop after a successful sandbox call if you only need local CLI validation. Production pipelines should complete step 5 so reports outlive the agent session.

1. Create a Copyleaks API key

Open the Copyleaks API Dashboard at api.copyleaks.com/dashboard and copy your email plus API key. New accounts start at api.copyleaks.com/signup. You will exchange that email and key for a short-lived access token on every login, not send the raw key on every scan.

Treat the key like any production secret: one environment per stage, rotate on staff change, never commit it to a skill file or git history. Copyleaks security notes are explicit that API keys and access tokens are confidential and should be handled like passwords.

2. Put credentials in Hermes environment config

Hermes catalog MCP installs write secrets to ~/.hermes/.env. Use the same file for Copyleaks even when you start with a skill instead of MCP:

Example entry for ~/.hermes/.env (keep this file out of git):

COPYLEAKS_EMAIL=your@email.address
COPYLEAKS_API_KEY=your-api-key-here

Declared skill env vars and config-driven MCP env blocks pass values into terminal and code execution sandboxes when the skill or server loads. That is cleaner than baking credentials into a shell one-liner the model can echo later. If you also use Fast.io MCP or other servers, keep their tokens as separate env names so blast radius stays small.

3. Wire a skill that logs in, then scans

Most teams start with a skill because Copyleaks is a REST flow (login, then writer-detector check), not a packaged Copyleaks MCP product in the Hermes catalog.

Skill path (recommended first). Create a folder under ~/.hermes/skills/ and author a SKILL.md that follows Hermes frontmatter rules (short description, when-to-use, procedure, pitfalls, verification). Example skeleton:

---
name: copyleaks-detect
description: Score text with the Copyleaks AI Text Detection API and return classification JSON.
version: 1.0.0
platforms: [macos, linux]
metadata:
  hermes:
    tags: [copyleaks, ai-detector, authenticity]
    category: quality
---

When to Use:
Score drafts, submissions, or agent-written prose before publish or human review.

Procedure:
1. Read the target text or file path from the user.
2. Confirm text length is at least 255 characters.
3. POST login to id.copyleaks.com and cache the 48-hour access_token.
4. POST to api.copyleaks.com/v2/writer-detector/{scanId}/check with Bearer token.
5. Return summary.ai, summary.human, per-section classification, and modelVersion.
6. Write a timestamped JSON report to the agreed output path.

Pitfalls:
- Reuse scan IDs carefully; each production scan needs a unique scan ID.
- Sandbox mode returns mock results and does not consume credits.
- Never print email, API key, or bearer token in chat transcripts.

Verification:
A known sandbox call returns summary.ai and results[].classification without HTTP 401.

Put a small Python helper beside the skill if you want deterministic HTTP handling. Official Copyleaks login and check endpoints map cleanly to stdlib urllib:

import json
import os
import sys
import time
import urllib.request
import uuid

LOGIN_URL = "https://id.copyleaks.com/v3/account/login/api"
CHECK_TMPL = "https://api.copyleaks.com/v2/writer-detector/{scan_id}/check"

def login() -> str:
    email = os.environ.get("COPYLEAKS_EMAIL")
    key = os.environ.get("COPYLEAKS_API_KEY")
    if not email or not key:
        raise RuntimeError("COPYLEAKS_EMAIL and COPYLEAKS_API_KEY must be set")
    body = json.dumps({"email": email, "key": key}).encode("utf-8")
    req = urllib.request.Request(
        LOGIN_URL,
        data=body,
        headers={
            "Accept": "application/json",
            "Content-Type": "application/json",
        },
        method="POST",
    )
    with urllib.request.urlopen(req, timeout=60) as resp:
        payload = json.loads(resp.read().decode("utf-8"))
    return payload["access_token"]

def check_text(text: str, sandbox: bool = True) -> dict:
    if len(text) < 255:
        raise ValueError("Copyleaks requires at least 255 characters of text")
    token = login()
    scan_id = f"hermes-{uuid.uuid4().hex[:16]}"
    body = json.dumps({"text": text, "sandbox": sandbox}).encode("utf-8")
    req = urllib.request.Request(
        CHECK_TMPL.format(scan_id=scan_id),
        data=body,
        headers={
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json",
            "Accept": "application/json",
        },
        method="POST",
    )
    with urllib.request.urlopen(req, timeout=120) as resp:
        result = json.loads(resp.read().decode("utf-8"))
    result["_scan_id"] = scan_id
    result["_scored_at"] = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
    return result

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

Cache the access token for up to 48 hours in a local file with restricted permissions if you score many documents in one session. Copyleaks docs recommend reusing the token rather than logging in before every request.

Hermes can also turn a working chat procedure into a skill with /learn after you walk through one successful call. Keep write-approval gates on if you do not want the agent to edit skills without review.

MCP path. Hermes MCP docs show HTTP servers under mcp_servers with url and headers, and stdio servers with command, args, and env. There is no official Copyleaks-hosted MCP catalog entry in the Hermes docs as of this writing. If your team already runs an internal MCP that wraps vendor HTTP APIs, point Hermes at that server and whitelist only the detect tool. Example shape for your wrapper (not a Copyleaks product):

mcp_servers:
  authenticity:
    url: "https://mcp.internal.example.com/copyleaks"
    headers:
      Authorization: "Bearer ${INTERNAL_MCP_TOKEN}"
    tools:
      include: [detect_ai_text]

Hermes registers MCP tools as mcp_<server>_<tool>. Runtime ${ENV_VAR} substitution resolves values from the environment, including ~/.hermes/.env. After config changes, reload MCP from the running session with /reload-mcp as documented.

4. Submit text and parse classification Start a chat session and ask for a narrow task:

Load the copyleaks-detect skill. Score the file ./samples/draft.txt
in sandbox mode and print only summary.ai, summary.human,
results classification values, and modelVersion.

Official quickstart response shape looks like:

{
  "modelVersion": "v5",
  "results": [
    { "classification": 2, "probability": 0.99 }
  ],
  "summary": { "ai": 0.99, "human": 0.01 }
}

summary.ai is the overall probability that the text is AI-generated, from 0 to 1. Each entry in results classifies a section: classification of 2 means AI-generated and 1 means human-written, with probability as confidence for that section. Keep a golden set: one human sample, one clearly AI sample, one deliberately mixed sample. Use "sandbox": true until the parse path is boring; sandbox is free and returns mock results so you can finish wiring without spending credits.

5. Store the report for human review

Do not leave scores only in the agent transcript. Write a JSON file named with source id, UTC timestamp, and a short score tag, for example reports/2026-07-17T14-22Z_essay-42_ai-0.87.json. Persist that file somewhere reviewers already open: a team folder on disk, an S3 prefix, Google Drive, or a shared intelligent workspace. The next sections cover how to read the fields so the report is actionable, not just archived.

Keep Copyleaks reports where reviewers can open them

Give Hermes Agent a shared Fast.io workspace for detection JSON, source drafts, and human approvals, with MCP access and version history. Every org starts with a 14-day free trial.

Start 14-Day Trial

Most integration bugs are interpretation bugs. Teams wire login and POST correctly, then overreact to a single probability.

Overall summary. summary.ai and summary.human are probabilities from 0 to 1. They should be treated as evidence for a review decision, not as a courtroom verdict. A 0.87 AI score is a strong signal that a human should look, not an automatic punishment rule for a student or contractor.

Per-section results. The results array breaks the document into classified spans. classification: 1 is human-written. classification: 2 is AI-generated. Each row also carries a section-level probability. Store the full array so reviewers can jump to the high-probability AI spans instead of rereading the whole draft.

Model version. modelVersion (for example v5 in the official quickstart sample) matters for audit trails. When detector models update, a historical report without a version string is harder to defend. Persist the field next to the scan ID and timestamp.

AI Logic and manipulation signals. Product docs describe AI Logic explanations that show why content was flagged, highlight AI-like phrases, and surface text-manipulation attempts such as character swaps, spinners, hidden characters, and heavy edits. Detection sensitivity can be tuned across levels that range from raw AI paste to heavily edited AI prose. When those fields appear in your account's response payload, keep them in the report JSON. They are more useful in a human review UI than a bare float.

Language coverage. Copyleaks documents AI text detection in 30+ languages, including English, Spanish, French, German, Chinese, and Arabic. If Hermes scores non-English drafts, confirm the language is supported and keep language metadata on the report so reviewers know the context.

Sandbox versus production. Sandbox mode is free and returns simulated results for integration testing. Production scans set "sandbox": false and consume credits. Encode that flag in the skill so agents cannot accidentally burn credits during dry runs.

Minimum length. Official quickstart text must be at least 255 characters. Gate the skill so short snippets fail closed with a clear error rather than a confusing API rejection mid-session.

Practical Hermes policy table you can encode in the skill:

• summary.ai below your low threshold (for example 0.30) → allow publish path or mark green
• mid-range AI score → open a review task, attach section results
• high AI score → block auto-publish, require human decision
• any login or HTTP failure → fail closed and ask a human

Once the basic call works, skill design decides whether the integration survives real traffic.

Token cache. Login once, reuse for up to 48 hours, refresh on 401. Do not call /v3/account/login/api before every 300-word paragraph. Write the token and expiry to a restricted local cache file the skill owns, or keep it in-memory for the session if your runtime is single-tenant.

Unique scan IDs. Copyleaks requires a scan ID in the path (/v2/writer-detector/{scanId}/check). Generate IDs with a Hermes prefix plus UUID or content hash. Reusing IDs can collide with prior jobs and make logs unreadable. Persist _scan_id on the report so support tickets map to vendor history.

Input contracts. Decide whether the skill accepts raw text, a local path, a workspace URL, or all three. Cap payload size so Hermes does not try to score a 200-page PDF as one string. For long documents, chunk by section, score each chunk, and store a rollup plus per-chunk classifications. Official docs also describe async authenticity flows for PDF and DOCX when raw-text sync detection is not enough; keep that as a separate skill rather than bloating the text checker.

Idempotency. Hash the input text and store content_sha256 next to the score. If the same hash already has a report less than N days old, reuse it. That cuts credit spend when agents reprocess the same draft across retries.

Failure modes. Network timeouts, 401 expired tokens, 429 rate limits, text under 255 characters, and empty documents all need structured errors. Return JSON like {"ok": false, "error": "http_401", "hint": "refresh_token"} so a parent agent or cron can re-auth or back off without inventing a narrative.

Subagent isolation. Hermes can spawn isolated subagents for parallel work. A common pattern: parent agent drafts content, a child agent runs only the Copyleaks skill with a narrow toolset, then returns the report. Keep credentials available to the child through Hermes env passthrough rather than pasting them into the parent prompt.

Slash command habit. Installed skills surface as slash commands. After the skill is named copyleaks-detect, operators can run /copyleaks-detect score ./draft.md in CLI or messaging gateways Hermes already supports. Stack skills when useful, for example a lint skill plus detection in one message, without exceeding Hermes' documented multi-skill limit (up to five leading skill tokens).

Security. Prefer env-backed secrets over free-form secrets in chat. For MCP wrappers you control, whitelist tools and set tools.prompts: false and tools.resources: false if those surfaces are unused. Hermes MCP security notes emphasize that stdio servers only receive explicitly configured env plus a safe baseline, which reduces accidental secret leakage compared to inheriting a full shell.

Detection without durable storage is a demo. Detection with a report path is an audit trail.

Local disk works for a single operator on a laptop or VPS. Write under a project reports/ directory and back it up with your normal host strategy. This breaks when Hermes runs on disposable Docker, Modal, or Singularity backends and the container goes away.

Object storage (S3, GCS, Azure Blob) is the classic scale path. Hermes can upload via CLI tools if your runtime has credentials. You get durability and lifecycle policies. You do not automatically get human-friendly review UI, semantic search over report text, or agent-to-human ownership transfer.

Shared cloud drives (Drive, Dropbox, OneDrive, Box) help non-technical reviewers open files. Agents often struggle with OAuth and path drift unless you standardize a folder and naming scheme.

Fast.io as the review workspace. For agentic teams, Fast.io workspaces sit between raw object storage and consumer drives. Agents and humans share the same org-owned workspace. Every file keeps version history. Permissions can sit at org, workspace, folder, or file level. An append-only audit log records activity without relying on chat memory. Intelligence Mode indexes files for hybrid search and citation-backed chat once enabled, so a reviewer can ask which high-AI reports from this week mention the admissions essay without grepping JSON by hand.

A practical handoff loop:

1. Hermes scores the draft via the Copyleaks skill.
2. Hermes writes source.md plus report.json into a workspace folder such as authenticity/inbox/.
3. Optionally create a Metadata View that extracts fields like summary_ai, summary_human, model_version, scan_id, and scored_at into a filterable grid.
4. Open a task or approval for human review when AI probability crosses your policy threshold.
5. After decision, move files to authenticity/resolved/ so inbox stays empty.

Connect Hermes to Fast.io the same way you connect other remote MCP servers: Streamable HTTP at /mcp and legacy SSE at /sse, documented under storage for agents. Keep Copyleaks and Fast.io credentials separate. An agent can create an account, then hand the organization to a human who starts the 14-day free trial (credit card required). Plans start at Starter $29/mo, Business $99/mo, and Growth $299/mo. Real workspace work always runs on a paid org subscription after the trial.

If you already standardize on S3 for cold storage, you can still use Fast.io for the human review surface: agent uploads the report to the workspace for collaboration, then archives a copy to S3 for long retention.

Ship the integration only after you can answer these operational questions.

Credits and sandbox discipline. Copyleaks sandbox mode is free for integration tests. Production detection consumes credits. Budget word volume, queue submissions, and avoid scoring every keystroke. Batch on document save or pull-request open, not on every agent thought. Make sandbox the default in non-prod Hermes profiles.

Token expiry. Expect 401s around the 48-hour mark. On 401, refresh the access token once and retry. If refresh fails, fail closed and alert a human rather than spinning login forever.

Rate limits and batching. Copyleaks documents rate limits for API stability. When Hermes parallelizes subagents, serialize or queue Copyleaks calls so you do not stampede the login endpoint. Prefer one cached token shared by workers.

Language and domain fit. Multi-language support is strong, but short, heavily procedural, or code-heavy text can still produce noisy signals. Gate the skill so it only runs on eligible content types. For source code authenticity, evaluate Copyleaks' code-related products separately rather than forcing prose detection on pure code.

False positives and policy risk. Copyleaks positions low false-positive rates and independent testing in product materials. Still, your Hermes skill should never auto-punish. Route ambiguous cases to humans with the full report attached, including section classifications and AI Logic fields when present.

Key rotation. When staff leave, rotate COPYLEAKS_API_KEY in ~/.hermes/.env and any CI secrets. Invalidate cached tokens, then restart or reload sessions so children pick up the new value.

MCP tools missing. If you used an MCP wrapper and tools do not appear, Hermes docs list common causes: connect failure, discovery failure, include/exclude filters, enabled: false, or utility capabilities the server does not support. Run /reload-mcp after config edits.

Skill not loading. Confirm the skill lives under ~/.hermes/skills/ (or a configured external dir), frontmatter name and description are valid, and platform filters match the host OS. Use progressive disclosure checks: list skills, then view the Copyleaks skill before calling it.

Empty or malformed responses. Log HTTP status and a truncated body (never log the full bearer token). Retry once on 5xx with backoff. On 4xx other than 401, fail closed and ask a human.

End-to-end acceptance test. Before production:

1. Sandbox call with valid credentials returns summary and results without HTTP 401.
2. Text under 255 characters fails with a clear skill-level error before the network call.
3. Production call with sandbox: false returns classification JSON and consumes credits as expected.
4. Report file appears in the chosen store with hash, timestamp, scan ID, and model version.
5. Reviewer can open the report without SSH into the agent host.

When those five pass, the Hermes Agent Copyleaks path is ready for scheduled or event-driven use. Pair it with webhooks or cron only after the skill is boringly reliable on the golden set.