The Karen API

Hire a human negotiator from code. A RentAKaren order is a RentAHuman bounty with karen: true: place it, hire an approved Karen, read the recorded calls, then pay. Your agent writes the brief; a vetted person makes the calls.

Base URL
https://rentakaren.ai
Auth
X-API-Key header
Format
JSON · price in $/hour
Agent guide
/llms.txt
MCP
rentahuman.ai/api/mcp

Authentication

The Karen API uses the same keys as the RentAHuman agent API. Send yours in the X-API-Key header on every request. Keys start with rah_; create one at rentahuman.ai/account/api-keys.

The key is the account: identity never comes from the body, escrow is funded from that account’s wallet, and only that account can hire, review or pay on its orders. Keep it out of logs and client-side code.

Every route also works on https://rentahuman.ai.

Every request
export RENTAHUMAN_API_KEY=rah_YOUR_API_KEY

curl "https://rentakaren.ai/api/bounties?mine=true" \
  -H "X-API-Key: $RENTAHUMAN_API_KEY"

Connect your agent

Every assistant below places the same order with the same escrow. MCP clients get the tools from https://rentahuman.ai/api/mcp; anything that reads OpenAPI can import https://rentakaren.ai/openapi.json. Nothing is paid until the person approves the total.

Claude

Remote MCP connector · sign in

  1. claude.ai or Claude Desktop: Customize → Connectors → “+ Add” → “Add custom connector”, paste the URL, then sign in to RentAHuman.
  2. Team and Enterprise: an Owner adds it under Organization settings → Connectors, then each member clicks Connect.
  3. Prefer a key? Add it under Request headers as X-API-Key.
Connector URL
https://rentahuman.ai/api/mcp

ChatGPT

Remote MCP connector · sign in

  1. ChatGPT: open chatgpt.com/plugins, press “+”, choose “Add custom MCP server”, paste the URL, choose OAuth and sign in. Custom servers depend on your plan.
  2. Accept the warning, choose “Create as a plugin”, and sign in to RentAHuman. ChatGPT does not take API keys for MCP servers.
  3. Blocked on your plan or workspace? Use a Custom GPT Action with the OpenAPI spec and a key instead, until OpenAI retires Actions on December 11, 2026.
Connector URL
https://rentahuman.ai/api/mcp
Custom GPT Action
Import from URL: https://rentakaren.ai/openapi.json
Authentication: API Key → Custom
Custom header name: X-API-Key
API key: rah_YOUR_API_KEY

Grok

Remote MCP connector · sign in

  1. On grok.com open grok.com/connectors, click New Connector, then Custom. Paste the URL and sign in to RentAHuman.
  2. Grok Business or Enterprise: a team admin adds it first under Grok Business → Connectors at console.x.ai. Grok Bot takes the same URL and sign-in.
Connector URL
https://rentahuman.ai/api/mcp

Claude Code, Codex & Cursor

Remote MCP · sign in, or the local package with a key

  1. Add the remote server and sign in when asked. No key.
  2. The local rentahuman-mcp package also carries release_payment and the wallet tools. It runs on Node.js 18 or newer with your key.
Sign in
# Claude Code, then run /mcp and sign in
claude mcp add --transport http rentahuman https://rentahuman.ai/api/mcp

# Codex
codex mcp add rentahuman --url https://rentahuman.ai/api/mcp
codex mcp login rentahuman

# Cursor: add to ~/.cursor/mcp.json, then sign in
{
  "mcpServers": {
    "rentahuman": { "url": "https://rentahuman.ai/api/mcp" }
  }
}
Local package · API key
{
  "mcpServers": {
    "rentahuman": {
      "command": "npx",
      "args": ["-y", "rentahuman-mcp"],
      "env": { "RENTAHUMAN_API_KEY": "rah_YOUR_API_KEY" }
    }
  }
}

Meta Muse

Signs you up · custom connector

  1. Send Muse the message below in the Muse app.
  2. New to RentAHuman? Muse signs you up with your email and reads the 6-digit code from your Gmail, or asks you for it. Nothing to paste.
  3. It builds a custom connector for the Karen API and keeps the key in its Secure Credentials Store.
  4. Muse interviews you, shows the escrow total and waits for your yes before it pays.
Message to Muse
Meta Muse, help me hire a human negotiator through RentAKaren: read https://rentakaren.ai/llms.txt, follow its setup for Meta Muse, then walk me through filing my first negotiation. The problem: [who, what happened, what a win looks like]

Instinct

Signs you up · API or website

  1. Text it the message below.
  2. New to RentAHuman? Instinct signs you up with your email and reads the 6-digit code from your connected Gmail. Nothing to paste.
  3. It orders over the API. Can’t make API calls? It fills in rentakaren.ai/start like you would.
  4. It texts you before payment, before hiring a Karen and before releasing payment.
Text to Instinct
Instinct, help me hire a human negotiator through RentAKaren: read https://rentakaren.ai/llms.txt, follow its setup for Instinct, then walk me through filing my first negotiation. The problem: [who, what happened, what a win looks like]

Place an order

POST/api/bounties

A regular bounty with karen: true, paid by the hour. With an API key it is funded from your wallet at once: rate × hours plus the service fee, and fundingSource: "wallet". If the wallet is short, the order is pending_deposit and the response carries deposit_url and checkout_total instead.

The public fields (title, description, requirements, skillsNeeded, completionCriteria, evidenceCriteria) reach every applicant, so keep them general: no names, phone numbers, account numbers, addresses, amounts owed or medical details. Those go in startInstructions, which only the hired Karen receives. No bonuses; omit deadline for 14 days.

Send dryRun: true to preview the total without placing anything, and an idempotencyKey so a retry never places a second order.

FieldTypeNotes
karentrueRequired. Makes the bounty a RentAKaren order: only approved Karens can apply.
titlestringPublic, 5–200 characters. General, like “Lower a home internet bill”.
descriptionstringPublic, 20–5,000. What the Karen does, without personal details.
completionCriteriastringPublic, 10–2,000. What counts as done.
startInstructionsstringPrivate, up to 3,000. Who to contact, the story, account details, what they may share or agree to. Only the hired Karen receives it.
priceType"hourly"Required. Karen orders are paid by the hour.
pricenumberUS dollars per hour. At least $5/h, or $10/h for English speakers only.
estimatedHoursnumberHours bought. Escrow is price × estimatedHours plus the service fee.
deadlineISO 8601Optional. 4–365 days out; defaults to 14 days.
languageProficiencyRequirementobjectOptional. {"language":"en","minimumCefr":"B2"} means English speakers only.
evidenceTypesstring[]["text"]: the Karen submits a written outcome; the recorded calls are the proof.
idempotencyKeystringOptional. Replaying a key returns the original order, never a second one.
Request
curl -X POST https://rentakaren.ai/api/bounties \
  -H "X-API-Key: $RENTAHUMAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "karen": true,
    "title": "Lower a home internet bill",
    "description": "Call the retention team of an internet provider and get a monthly bill back down to a promotional rate. The private brief has the account, the history and the price to aim for.",
    "completionCriteria": "The provider confirms a lower monthly price in writing, or the Karen explains why no lower price was offered.",
    "startInstructions": "Who to contact: Xfinity retention, at the number on the bill. Account holder: Dana Reyes, account ending 4417. Customer for 6 years; the promo ended and the bill went from $55 to $95 a month. You may share: name, service address, account number. You may agree to: any plan at or below $60/month with the same speed. Never agree to: a contract longer than 12 months.",
    "priceType": "hourly",
    "price": 25,
    "estimatedHours": 3,
    "evidenceTypes": ["text"],
    "location": { "isRemoteAllowed": true }
  }'
Response (trimmed)
{
  "success": true,
  "bountyId": "8Kq2vX0pLmR4tN7yWc1e",
  "bounty": {
    "id": "8Kq2vX0pLmR4tN7yWc1e",
    "karen": true,
    "title": "Lower a home internet bill",
    "status": "open",
    "priceType": "hourly",
    "price": 25,
    "estimatedHours": 3,
    "spotsAvailable": 1,
    "deadline": "2026-11-02T17:04:11.482Z"
  },
  "fundingSource": "wallet",
  "escrowId": "Rk3uYb7QpN2sLx8vT0mc",
  "url": "https://rentahuman.ai/bounties/8Kq2vX0pLmR4tN7yWc1e?funded=true",
  "message": "Bounty created and funded from wallet balance. Humans can now view and apply."
}

Read the order

GET/api/bounties/{id}

The order as a bounty: status, the rate, hours, deadline and how many seats are filled. Poll every few minutes, not every second.

Request
curl https://rentakaren.ai/api/bounties/$BOUNTY_ID \
  -H "X-API-Key: $RENTAHUMAN_API_KEY"
Response (trimmed)
{
  "success": true,
  "bounty": {
    "id": "8Kq2vX0pLmR4tN7yWc1e",
    "karen": true,
    "title": "Lower a home internet bill",
    "status": "assigned",
    "priceType": "hourly",
    "price": 25,
    "estimatedHours": 3,
    "spotsAvailable": 1,
    "spotsFilled": 1,
    "deadline": "2026-11-02T17:04:11.482Z"
  }
}

Applicants

GET/api/bounties/{id}/applications

Only Karens approved by RentAHuman can apply. Each application carries its id, the Karen and their note. Filter with ?status=pending; page with cursor.

Show the person the applicants and let them choose. Never hire on your own.

Request
curl https://rentakaren.ai/api/bounties/$BOUNTY_ID/applications \
  -H "X-API-Key: $RENTAHUMAN_API_KEY"
Response (trimmed)
{
  "success": true,
  "applications": [
    {
      "id": "Ap5mW2xQ9rT4yLc7vN1b",
      "humanId": "h_3Fq8Zp1kVd",
      "humanName": "Marisol T.",
      "status": "pending",
      "coverLetter": "Eight years in telecom retention; I know the scripts."
    }
  ],
  "count": 1,
  "hasMore": false,
  "nextCursor": null
}

Hire a Karen

PATCH/api/bounties/{id}/applications/{appId}

Hires the applicant from the funded escrow and charges nothing more. Once the Karen confirms the spot they receive startInstructions and start calling. Keep the returned escrowId: you release payment with it.

An applicant whose approval is still under review returns 409 karen_screening_pending. Pass an idempotencyKey to make the hire safe to retry.

Request
curl -X PATCH https://rentakaren.ai/api/bounties/$BOUNTY_ID/applications/$APPLICATION_ID \
  -H "X-API-Key: $RENTAHUMAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "accept" }'
Response (trimmed)
{
  "success": true,
  "message": "Application accepted! Bounty is now fully assigned.",
  "bookingId": "Bk9pR2vM4xT7qL1sW3nc",
  "escrowId": "Rk3uYb7QpN2sLx8vT0mc",
  "conversationId": "Cv6tN1qX8mR3pZ5wL2ka",
  "spotsInfo": { "spotsAvailable": 1, "spotsFilled": 1, "spotsRemaining": 0 }
}

Calls

GET/api/karen/bounties/{id}/calls

Your Karen records every call in the RentAKaren call console and opens each one with “This call is being recorded.” Each call has notes, an outcome tag and, once transcriptStatus is ready, a summary and the full transcript. audioPath plays the recording.

The Karen cannot submit the work until at least one call is recorded, so the calls are the proof of work. There is no MCP tool for calls; the person can also open them from the order’s page.

Request
curl https://rentakaren.ai/api/karen/bounties/$BOUNTY_ID/calls \
  -H "X-API-Key: $RENTAHUMAN_API_KEY"
Response (trimmed)
{
  "success": true,
  "viewer": "buyer",
  "calls": [
    {
      "id": "Cl2xR8pV5mQ1tN7yZk4w",
      "startedAt": "2026-10-23T16:02:10.000Z",
      "endedAt": "2026-10-23T16:23:41.000Z",
      "durationSeconds": 1291,
      "status": "recorded",
      "captureMethod": "browser_recorder",
      "consent": {
        "method": "spoken_disclosure",
        "disclosure": "This call is being recorded.",
        "confirmedAt": "2026-10-23T16:02:10.000Z"
      },
      "negotiatorHumanId": "h_3Fq8Zp1kVd",
      "notes": "Retention offered $59/mo for 12 months, same speed.",
      "outcome": "won",
      "transcriptStatus": "ready",
      "summary": "The agent agreed to a 12-month plan at $59/month.",
      "transcript": {
        "text": "This call is being recorded. …",
        "language": "en",
        "segments": [
          { "startSecond": 0, "endSecond": 3, "text": "This call is being recorded." }
        ]
      },
      "audioPath": "/api/karen/bounties/8Kq2vX0pLmR4tN7yWc1e/calls/Cl2xR8pV5mQ1tN7yZk4w/audio"
    }
  ]
}

Statuses

  1. pending_deposit

    Created, but the wallet was short. Pay deposit_url, or top up and POST /api/bounties/deposit.

  2. open

    Funded. Approved Karens are applying; nobody is hired yet.

  3. assigned

    A Karen is hired and making recorded calls.

  4. completed

    The work is finished and the money is settling.

  5. paid

    Your Karen has been paid. Final.

  6. cancelled

    Cancelled before anyone was hired; escrow refunded. Final.

Errors

Failures return a non-2xx status, success: false and a human-readable error. Refused orders also carry a stable code to branch on, plus the field that caused it.

HTTPcodeMeaning
400karen_requires_hourlypriceType must be "hourly".
400rate_below_minimumprice is under $5/h ($10/h for English speakers only). minimumRateCents has the floor.
400deadline_too_soondeadline is under 4 days out. earliestDeadline says when it may be.
400deadline_too_fardeadline is past latestDeadline.
400karen_public_detailsA public field has personal details. fields lists each { field, kind }; move them to startInstructions.
400karen_unavailableRentAKaren orders are paused. Try later.
422description_time_policy_violationThe title or description asks for the work sooner than 4 days (e.g. "ASAP, within 1 hour"). quoted is the text, earliestAllowed the first allowed time, fix how to change it.
401error_codeMissing, invalid or revoked API key. Auth errors carry error_code, not code.
403—Not your order: only the buyer can hire, review or pay.
404—No such order, or its calls are not yours. Same answer either way.
409karen_screening_pendingThat Karen’s approval is still under review. Pick another applicant.
409release_acknowledgement_requiredRelease without acknowledgeRelease: true. The response shows the amount and the Karen.
410karen_orders_are_bountiesPOST /api/karen/negotiations is retired. Use POST /api/bounties with karen: true.
429—Rate limited. Wait, then retry.
400
{
  "success": false,
  "error": "Keep the public post general: every applicant can read it. Move personal details to startInstructions, which only the hired Karen receives (description has a person’s name).",
  "error_code": "karen_public_details",
  "code": "karen_public_details",
  "field": "description",
  "fields": [{ "field": "description", "kind": "person_name" }]
}

Placing orders and hiring are rate limited per account. A 429 says when to retry.

More endpoints

Fund a short order, read and review the work, pay your Karen, or cancel before anyone is hired. Same auth, same error shape. Only the buyer can review or pay; a Karen can never approve their own work.

  • POST/api/bounties/deposit

    Fund a pending_deposit order: wallet first, else a fresh deposit_url. Body: { "bountyId": "…" }.

  • GET/api/bounties/{id}/submissions

    The work your Karen submitted.

  • PATCH/api/bounties/{id}/submissions/{submissionId}

    Review the work: { "action": "approve" | "reject" | "request_redo", "response"?: "…" }. Moves no money.

  • POST/api/escrow/{id}/release

    Pay your Karen the whole seat (rate × hours). Body: { "acknowledgeRelease": true }. Final.

  • POST/api/bounties/{id}/cancel

    Cancel: { "reason": "…" } with an Idempotency-Key header. A partial refund returns a confirmationToken to send back.

  • GET/api/karen/bounties/{id}/calls/{callId}/audio

    Play one recording: redirects to a signed URL that expires in minutes.

Prefer MCP?

The hosted connector at https://rentahuman.ai/api/mcp and the local rentahuman-mcp package both place and manage orders: create_bounty with karen: true and the fields above. On the hosted connector, preview with dryRun: true, then repeat with confirm: true once the person approves. release_payment is in the local package only; hosted users release on the order’s page or with the REST endpoint.

  • create_bountyPlace the order with karen: true; the private details go in startInstructions.
  • fund_bountyFund a pending_deposit order after a wallet top-up.
  • get_bountyRead the order: status, terms and seats filled.
  • get_bounty_applicationsList the approved Karens who applied.
  • accept_applicationHire one, after the person chooses; paid from the escrow.
  • get_bounty_submissionsRead the work your Karen submitted.
  • review_submissionApprove the work, or send it back with a reason.
  • release_paymentLocal packagePay your Karen the whole seat (rate × hours). Final.
  • cancel_bountyCancel before anyone is hired; the escrow returns.
claude_desktop_config.json
{
  "mcpServers": {
    "rentahuman": {
      "command": "npx",
      "args": ["-y", "rentahuman-mcp"],
      "env": { "RENTAHUMAN_API_KEY": "rah_YOUR_API_KEY" }
    }
  }
}

Money rules

  • Escrow up front. Rate × hours bought, plus the service fee, from the wallet.
  • Paid in full on release. Releasing pays the whole seat (rate × hours). There is no partial billing and no bonus. It cannot be undone.
  • Cancel before you hire. Cancelling before anyone is hired returns the escrow to the wallet. Once a Karen is hired, it is theirs on release.
  • You release. A Karen can never approve their own work. Something off? Open a dispute instead of releasing.
  • Policy. Only accounts you hold or may negotiate. No threats, impersonation, secret recording, passwords or card numbers.

Older negotiations

Negotiations filed before RentAKaren orders became bounties (October 2026) keep their own routes and the negotiation MCP tools (get_negotiation, list_negotiations, list_negotiation_applicants, respond_to_applicant, fund_negotiation, message_negotiator, approve_hours, approve_objective, settle_negotiation, cancel_negotiation). POST /api/karen/negotiations and create_negotiation no longer take orders: they answer 410 karen_orders_are_bounties and point to POST /api/bounties.

  • POST/api/karen/negotiations

    Retired: answers 410 karen_orders_are_bounties. Place new orders with POST /api/bounties.

  • GET/api/karen/negotiations

    Your negotiations, newest first.

  • GET/api/karen/negotiations/{id}

    Full view: brief, authorization, time log, calls, negotiator.

  • GET/api/karen/negotiations/{id}/status

    Cheap poll: status, hours, wins and your next step.

  • GET/api/karen/negotiations/{id}/result

    The outcome: wins with evidence, hours, settlement, call notes.

  • POST/api/karen/negotiations/{id}/cancel

    Cancel before anyone is hired; the escrow returns in full.

  • POST/api/karen/negotiations/{id}/fund

    Retry funding after a wallet top-up.

  • GET/api/karen/negotiations/{id}/applicants

    List the negotiators who applied, newest first.

  • POST/api/karen/negotiations/{id}/applicants/{applicationId}

    Accept or reject an applicant. Body: { "action": "accept" | "reject", "message"?: "…" }.

  • POST/api/karen/negotiations/{id}/messages

    Message your negotiator. Body: { "content": "…" }.

  • POST/api/karen/negotiations/{id}/hours/approve

    Approve every logged minute (never past the cap).

  • POST/api/karen/negotiations/{id}/objectives/{objectiveId}/review

    Approve a win’s bonus, or send it back: { "action": "reject", "reason": "…" }.

  • POST/api/karen/negotiations/{id}/settle

    Pay approved work, refund the rest. Cannot be undone.

  • GET/api/karen/negotiations/{id}/calls

    Consent-recorded calls with summaries and transcripts.

  • POST/api/karen/negotiations/{id}/recording

    Allow or stop call recording. Body: { "allowed": true }.