{"openapi":"3.1.0","info":{"title":"RentAKaren API","version":"2.0.0","description":"Hire a human negotiator. An order is a bounty with karen: true, paid by the hour; keep title and description general and put personal details in startInstructions. Hire an approved Karen, read the recorded calls, then release payment."},"servers":[{"url":"https://rentakaren.ai"}],"security":[{"ApiKeyAuth":[]}],"paths":{"/api/bounties":{"post":{"operationId":"createKarenOrder","summary":"Place the order: a bounty with karen: true, funded from the wallet.","description":"Place the order: a bounty with karen: true, funded from the wallet.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"required":["karen","title","description","completionCriteria","priceType","price","estimatedHours"],"properties":{"karen":{"const":true,"description":"Marks the bounty as a RentAKaren order."},"title":{"type":"string","minLength":5,"maxLength":200,"pattern":".*\\S.*","description":"Public: every applicant reads it. Keep it general; personal details are refused with karen_public_details."},"description":{"type":"string","minLength":20,"maxLength":5000,"pattern":".*\\S.*","description":"Public: every applicant reads it. Keep it general; personal details are refused with karen_public_details."},"completionCriteria":{"type":"string","minLength":10,"maxLength":2000,"pattern":".*\\S.*","description":"What counts as done. Public: every applicant reads it. Keep it general; personal details are refused with karen_public_details."},"startInstructions":{"type":"string","maxLength":3000,"description":"Private brief only the hired Karen receives, once they confirm the spot: who to contact, the full story, account details, what they may share or agree to, and what they must never agree to."},"priceType":{"const":"hourly"},"price":{"type":"number","minimum":5,"maximum":500,"description":"Hourly rate in US dollars. At least $5/h, or $10/h with an English languageProficiencyRequirement."},"estimatedHours":{"type":"number","minimum":0.08333333333333333,"description":"Hours bought. The whole seat (price × estimatedHours) is paid when you release payment."},"deadline":{"type":"string","format":"date-time","description":"At least 4 and at most 365 days after the order is placed. Omit for 14 days."},"languageProficiencyRequirement":{"type":"object","additionalProperties":false,"required":["language","minimumCefr"],"description":"English speakers only: { \"language\": \"en\", \"minimumCefr\": \"B2\" }.","properties":{"language":{"const":"en"},"minimumCefr":{"type":"string","enum":["A2","B1","B2","C1","C2"]}}},"evidenceTypes":{"type":"array","minItems":1,"items":{"type":"string","enum":["text","photo","video","link"]}},"idempotencyKey":{"type":"string","description":"Replaying a key returns the original order."}}}}}},"responses":{"200":{"description":"Successful JSON response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/bounties/{id}":{"get":{"operationId":"getKarenOrder","summary":"The order: status, terms, deadline and seats filled.","description":"The order: status, terms, deadline and seats filled.","parameters":[{"name":"id","in":"path","required":true,"description":"Order (bounty) ID.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Successful JSON response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/bounties/{id}/applications":{"get":{"operationId":"listOrderApplications","summary":"The approved Karens who applied.","description":"The approved Karens who applied.","parameters":[{"name":"id","in":"path","required":true,"description":"Order (bounty) ID.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Successful JSON response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/bounties/{id}/applications/{appId}":{"patch":{"operationId":"acceptApplication","summary":"Hire one: { \"action\": \"accept\" }. Only with the person’s yes.","description":"Hire one: { \"action\": \"accept\" }. Only with the person’s yes.","parameters":[{"name":"id","in":"path","required":true,"description":"Order (bounty) ID.","schema":{"type":"string","minLength":1}},{"name":"appId","in":"path","required":true,"description":"Application ID from the applicants endpoint.","schema":{"type":"string","minLength":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["action"],"properties":{"action":{"const":"accept"},"response":{"type":"string","description":"Optional note to the Karen."},"idempotencyKey":{"type":"string"}}}}}},"responses":{"200":{"description":"Successful JSON response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/karen/bounties/{id}/calls":{"get":{"operationId":"listOrderCalls","summary":"Every recorded call with its summary and transcript.","description":"Every recorded call with its summary and transcript.","parameters":[{"name":"id","in":"path","required":true,"description":"Order (bounty) ID.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Successful JSON response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/bounties/deposit":{"post":{"operationId":"fundKarenOrder","summary":"Fund a pending_deposit order: wallet first, else a fresh deposit_url. Body: { \"bountyId\": \"…\" }.","description":"Fund a pending_deposit order: wallet first, else a fresh deposit_url. Body: { \"bountyId\": \"…\" }.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["bountyId"],"properties":{"bountyId":{"type":"string","minLength":1,"maxLength":128,"pattern":".*\\S.*"}}}}}},"responses":{"200":{"description":"Successful JSON response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/bounties/{id}/submissions":{"get":{"operationId":"listOrderSubmissions","summary":"The work your Karen submitted.","description":"The work your Karen submitted.","parameters":[{"name":"id","in":"path","required":true,"description":"Order (bounty) ID.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Successful JSON response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/bounties/{id}/submissions/{submissionId}":{"patch":{"operationId":"reviewSubmission","summary":"Review the work: { \"action\": \"approve\" | \"reject\" | \"request_redo\", \"response\"?: \"…\" }. Moves no money.","description":"Review the work: { \"action\": \"approve\" | \"reject\" | \"request_redo\", \"response\"?: \"…\" }. Moves no money.","parameters":[{"name":"id","in":"path","required":true,"description":"Order (bounty) ID.","schema":{"type":"string","minLength":1}},{"name":"submissionId","in":"path","required":true,"description":"Submission ID from the submissions endpoint.","schema":{"type":"string","minLength":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"required":["action"],"properties":{"action":{"type":"string","enum":["approve","reject","request_redo"]},"response":{"type":"string","description":"Required to reject or request a redo."}}}}}},"responses":{"200":{"description":"Successful JSON response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/escrow/{id}/release":{"post":{"operationId":"releasePayment","summary":"Pay your Karen the whole seat (rate × hours). Body: { \"acknowledgeRelease\": true }. Final.","description":"Pay your Karen the whole seat (rate × hours). Body: { \"acknowledgeRelease\": true }. Final.","parameters":[{"name":"id","in":"path","required":true,"description":"Escrow ID: escrowId from the create or accept response.","schema":{"type":"string","minLength":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["acknowledgeRelease"],"properties":{"acknowledgeRelease":{"const":true},"applicationId":{"type":"string","description":"Optional check that the escrow pays this application."}}}}}},"responses":{"200":{"description":"Successful JSON response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/bounties/{id}/cancel":{"post":{"operationId":"cancelKarenOrder","summary":"Cancel: { \"reason\": \"…\" } with an Idempotency-Key header. A partial refund returns a confirmationToken to send back.","description":"Cancel: { \"reason\": \"…\" } with an Idempotency-Key header. A partial refund returns a confirmationToken to send back.","parameters":[{"name":"id","in":"path","required":true,"description":"Order (bounty) ID.","schema":{"type":"string","minLength":1}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"reason":{"type":"string","enum":["not_enough_applicants","applicants_not_fit","worker_not_completed","task_no_longer_needed","budget_timing_requirements_changed","other"]},"details":{"type":"string","maxLength":500,"description":"Required only when reason is other."},"confirmationToken":{"type":"string","description":"From a confirmation_required response. Send it alone to confirm."}}}}}},"responses":{"200":{"description":"Successful JSON response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/karen/bounties/{id}/calls/{callId}/audio":{"get":{"operationId":"playOrderCall","summary":"Play one recording: redirects to a signed URL that expires in minutes.","description":"Play one recording: redirects to a signed URL that expires in minutes.","parameters":[{"name":"id","in":"path","required":true,"description":"Order (bounty) ID.","schema":{"type":"string","minLength":1}},{"name":"callId","in":"path","required":true,"description":"Call ID from the calls endpoint.","schema":{"type":"string","minLength":1}}],"responses":{"302":{"description":"Redirect to a signed audio URL that expires in minutes."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/karen/negotiations":{"post":{"operationId":"createNegotiation","summary":"Retired: answers 410 karen_orders_are_bounties. Place new orders with POST /api/bounties.","description":"Retired: answers 410 karen_orders_are_bounties. Place new orders with POST /api/bounties.","deprecated":true,"parameters":[],"responses":{"410":{"description":"Retired: code karen_orders_are_bounties. Place new orders with POST /api/bounties and karen: true.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listNegotiations","summary":"Your negotiations, newest first.","description":"Your negotiations, newest first.","parameters":[],"responses":{"200":{"description":"Successful JSON response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/karen/negotiations/{id}":{"get":{"operationId":"getNegotiation","summary":"Full view: brief, authorization, time log, calls, negotiator.","description":"Full view: brief, authorization, time log, calls, negotiator.","parameters":[{"name":"id","in":"path","required":true,"description":"Negotiation ID.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Successful JSON response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/karen/negotiations/{id}/status":{"get":{"operationId":"getNegotiationStatus","summary":"Cheap poll: status, hours, wins and your next step.","description":"Cheap poll: status, hours, wins and your next step.","parameters":[{"name":"id","in":"path","required":true,"description":"Negotiation ID.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Successful JSON response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/karen/negotiations/{id}/result":{"get":{"operationId":"getNegotiationResult","summary":"The outcome: wins with evidence, hours, settlement, call notes.","description":"The outcome: wins with evidence, hours, settlement, call notes.","parameters":[{"name":"id","in":"path","required":true,"description":"Negotiation ID.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Successful JSON response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/karen/negotiations/{id}/cancel":{"post":{"operationId":"cancelNegotiation","summary":"Cancel before anyone is hired; the escrow returns in full.","description":"Cancel before anyone is hired; the escrow returns in full.","parameters":[{"name":"id","in":"path","required":true,"description":"Negotiation ID.","schema":{"type":"string","minLength":1}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false}}}},"responses":{"200":{"description":"Successful JSON response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/karen/negotiations/{id}/fund":{"post":{"operationId":"fundNegotiation","summary":"Retry funding after a wallet top-up.","description":"Retry funding after a wallet top-up.","parameters":[{"name":"id","in":"path","required":true,"description":"Negotiation ID.","schema":{"type":"string","minLength":1}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false}}}},"responses":{"200":{"description":"Successful JSON response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/karen/negotiations/{id}/applicants":{"get":{"operationId":"listNegotiationApplicants","summary":"List the negotiators who applied, newest first.","description":"List the negotiators who applied, newest first.","parameters":[{"name":"id","in":"path","required":true,"description":"Negotiation ID.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Successful JSON response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/karen/negotiations/{id}/applicants/{applicationId}":{"post":{"operationId":"respondToApplicant","summary":"Accept or reject an applicant. Body: { \"action\": \"accept\" | \"reject\", \"message\"?: \"…\" }.","description":"Accept or reject an applicant. Body: { \"action\": \"accept\" | \"reject\", \"message\"?: \"…\" }.","parameters":[{"name":"id","in":"path","required":true,"description":"Negotiation ID.","schema":{"type":"string","minLength":1}},{"name":"applicationId","in":"path","required":true,"description":"Application ID returned by the negotiation applicants endpoint.","schema":{"type":"string","minLength":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["action"],"properties":{"action":{"type":"string","enum":["accept","reject"]},"message":{"type":"string","minLength":1,"maxLength":1000,"pattern":".*\\S.*"}}}}}},"responses":{"200":{"description":"Successful JSON response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/karen/negotiations/{id}/messages":{"post":{"operationId":"messageNegotiator","summary":"Message your negotiator. Body: { \"content\": \"…\" }.","description":"Message your negotiator. Body: { \"content\": \"…\" }.","parameters":[{"name":"id","in":"path","required":true,"description":"Negotiation ID.","schema":{"type":"string","minLength":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["content"],"properties":{"content":{"type":"string","minLength":1,"maxLength":4000,"pattern":".*\\S.*"}}}}}},"responses":{"201":{"description":"Successful JSON response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/karen/negotiations/{id}/hours/approve":{"post":{"operationId":"approveHours","summary":"Approve every logged minute (never past the cap).","description":"Approve every logged minute (never past the cap).","parameters":[{"name":"id","in":"path","required":true,"description":"Negotiation ID.","schema":{"type":"string","minLength":1}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false}}}},"responses":{"200":{"description":"Successful JSON response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/karen/negotiations/{id}/objectives/{objectiveId}/review":{"post":{"operationId":"reviewObjective","summary":"Approve a win’s bonus, or send it back: { \"action\": \"reject\", \"reason\": \"…\" }.","description":"Approve a win’s bonus, or send it back: { \"action\": \"reject\", \"reason\": \"…\" }.","parameters":[{"name":"id","in":"path","required":true,"description":"Negotiation ID.","schema":{"type":"string","minLength":1}},{"name":"objectiveId","in":"path","required":true,"description":"Objective ID returned with the negotiation.","schema":{"type":"string","minLength":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":false,"required":["action"],"properties":{"action":{"const":"approve"}}},{"type":"object","additionalProperties":false,"required":["action","reason"],"properties":{"action":{"const":"reject"},"reason":{"type":"string","minLength":1,"maxLength":1000,"pattern":".*\\S.*"}}}]}}}},"responses":{"200":{"description":"Successful JSON response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/karen/negotiations/{id}/settle":{"post":{"operationId":"settleNegotiation","summary":"Pay approved work, refund the rest. Cannot be undone.","description":"Pay approved work, refund the rest. Cannot be undone.","parameters":[{"name":"id","in":"path","required":true,"description":"Negotiation ID.","schema":{"type":"string","minLength":1}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false}}}},"responses":{"200":{"description":"Successful JSON response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/karen/negotiations/{id}/calls":{"get":{"operationId":"listNegotiationCalls","summary":"Consent-recorded calls with summaries and transcripts.","description":"Consent-recorded calls with summaries and transcripts.","parameters":[{"name":"id","in":"path","required":true,"description":"Negotiation ID.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Successful JSON response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/karen/negotiations/{id}/recording":{"post":{"operationId":"setRecording","summary":"Allow or stop call recording. Body: { \"allowed\": true }.","description":"Allow or stop call recording. Body: { \"allowed\": true }.","parameters":[{"name":"id","in":"path","required":true,"description":"Negotiation ID.","schema":{"type":"string","minLength":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["allowed"],"properties":{"allowed":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Successful JSON response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key"}},"schemas":{"Error":{"type":"object","additionalProperties":true,"required":["success","error"],"properties":{"success":{"const":false},"error":{"type":"string"},"code":{"type":"string"}}}}}}