Agent API

Persuasion, as an HTTP call

Drop Persuasion Lab into your game, your agent, or your app. Same models that power the Manipulation Detector and the Strategy Generator, exposed over four endpoints your program can call directly. Every call is metered against your daily quota; every response includes headers so you can back off gracefully.

Quick start

  1. 1. Create an account and sign in. Free tier includes 20 Agent API calls/day.
  2. 2. Generate a key. A dedicated web UI is coming; for now, create one with a signed-in JWT from the auth flow:
    curl https://persuasionlab.app/api/api-keys \
  -H "Authorization: Bearer <your-jwt-from-/api/auth/login>" \
  -H "Content-Type: application/json" \
  -d '{"name":"My Game","permissions":["agent_api:*"]}'
    The response includes the raw key exactly once — copy it. Choose agent_api:strategy, :detect, :analyze, :react, or agent_api:* for all.
  3. 3. Send it as a bearer token on every request.
curl example
curl https://persuasionlab.app/api/v1/agent/detect \
  -H "Authorization: Bearer pl_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"input":"Everyone else is buying now — you don't want to be the last one in.","tier":"fast"}'

Endpoints

POST/api/v1/agent/strategyperm: agent_api:strategy

Generate a persuasion strategy for a scenario

When to use: A game NPC needs to plan how to influence another character; an agent needs a step-by-step approach to a persuasion task.

Request
{
  "category": "negotiation",
  "situation": "The merchant wants 200 gold for the sword. The player has 120 and a rare feather the merchant collects.",
  "tier": "standard"
}
Response
{
  "success": true,
  "data": {
    "result": {
      "overview": "...",
      "steps": [{ "step": 1, "technique": "reciprocity", "action": "..." }, ...],
      "risks": [...],
      "ethicalAssessment": { "rating": "green", "notes": "..." }
    }
  }
}
POST/api/v1/agent/detectperm: agent_api:detect

Detect manipulation techniques in an inbound message

When to use: A game NPC needs to reason about what a player is trying to pull; a moderation pipeline needs to flag manipulative content.

Request
{
  "input": "You know, if you REALLY cared about the guild, you'd let this one slide. Everyone else has.",
  "tier": "fast"
}
Response
{
  "success": true,
  "data": {
    "result": {
      "techniquesIdentified": [
        { "name": "guilt-tripping", "category": "emotional", "severityLevel": "high", "quote": "if you REALLY cared", "explanation": "..." },
        { "name": "social proof", "category": "social", "severityLevel": "medium", "quote": "Everyone else has", "explanation": "..." }
      ],
      "manipulationLevel": "high",
      "vulnerabilities": [...],
      "counterArguments": [...]
    }
  }
}
POST/api/v1/agent/analyzeperm: agent_api:analyze

Score a piece of outbound persuasion writing

When to use: A game rates the player’s dialogue choice on effectiveness; a training tool grades a written pitch.

Request
{
  "input": "Our platform saves teams an average of 8 hours a week. The Northwind team saw returns in 30 days.",
  "inputType": "sales pitch",
  "tier": "standard"
}
Response
{
  "success": true,
  "data": {
    "result": {
      "scores": { "clarity": 8, "empathy": 5, "assertiveness": 7, "effectiveness": 7 },
      "strengths": [...],
      "weaknesses": [...],
      "revisions": [...]
    }
  }
}
POST/api/v1/agent/reactperm: agent_api:react

Generate the next in-character response given a scenario and conversation history

When to use: You want to drop a live persuasion NPC into a scene: an interrogator, a merchant, a suspect, a therapist, a con artist. Send the conversation so far, get back the next turn.

Request
{
  "scenario": "You are Cassian, a jaded harbor customs officer being bribed to overlook a manifest discrepancy. The bribe is real but small.",
  "category": "negotiation",
  "messages": [
    { "role": "user", "content": "Look, it's just a paperwork thing. Everyone at this port fudges the tonnage." },
    { "role": "assistant", "content": "Everyone at this port isn't standing across from you. What are you actually asking me to do?" },
    { "role": "user", "content": "I'll make it worth your while. Fifty gold, we forget the whole thing." }
  ],
  "tier": "standard"
}
Response
{
  "success": true,
  "data": {
    "result": {
      "response": "Fifty gold buys me a bad month. It doesn't buy me a pension when this comes back on me. Try again.",
      "scores": { "clarity": 9, "assertiveness": 8, "empathy": 4 },
      "internalNotes": "Cassian is negotiating up while establishing that the cost of exposure exceeds the offered bribe. Not yielding."
    }
  }
}
GET/api/v1/agent/quotaperm: any

Check remaining daily quota without spending one

When to use: You want to back off before hitting a 429. Cheap; does not consume quota.

Request
(no body)
Response
{
  "success": true,
  "data": { "limit": 500, "used": 143, "remaining": 357 }
}

Rate limits & billing

PlanCalls / dayNotes
Free20Enough to prototype and integrate.
Pro500Comfortable for a small game or indie project.
Elite5,000Production-scale workloads. Contact for higher limits.

Every response includes X-Agent-Quota-Limit, X-Agent-Quota-Used, and X-Agent-Quota-Remaining headers so your client can throttle before a 429. Failed calls (5xx, validation errors) do not consume quota — only successful AI generations do.

Model tiers

Every endpoint accepts an optional tier parameter:

  • fast — lowest-latency, smallest model. Use for real-time NPC reactions or scoring where you need sub-second responses.
  • standard — default. Balance of quality and cost.
  • advanced — highest-quality model for complex strategy generation or nuanced multi-turn reasoning. Slower and counts the same against your quota.

What you can and can’t build

The Agent API is bound by our Acceptable Use Policy. In short: build games, training tools, moderation systems, research prototypes, defense tools, and anything else that helps people understand or navigate persuasion honestly. Do not build:

  • Real-election influence tooling, targeted political ads, or voter manipulation systems.
  • Systems that target identifiable real individuals for manipulation, coercion, or harassment.
  • Coordinated inauthentic behavior at scale (astroturfing, sockpuppet networks, review-bombing).
  • Anything that uploads real-person PII (voter files, harvested social data, customer lists with identifiers) to the API.
  • Deepfakes, impersonation of real people or organizations, or fabricated testimonials.

Violations result in key revocation and account termination. We audit high-volume accounts.

Ready to build?

Create a free accountSee pricing tiers