Using AI assistants with the Kumkuat API
You can run every Kumkuat API workflow by describing it in plain English to an AI assistant such as Claude or ChatGPT; the assistant writes and runs the API calls for you. This is the short version; for endpoint details see the Kumkuat API guide.
Before you start
An assistant needs three things before it can work with Kumkuat:
- An API key for the right workspace. In Kumkuat, open Workspace → API → Manage API Keys and create one. Each workspace has its own personas and keys, so switch to the correct workspace first.
- The API reference. Point the assistant at
https://api.kumkuat.ai/openapi.json(machine-readable) orhttps://api.kumkuat.ai/docs. This keeps it from guessing endpoint names. - Your inputs. For example, a spreadsheet of names, a draft press release, or the question you want an audience to answer.
Every request sends the key in an X-API-Key header to https://api.kumkuat.ai. Tell the assistant this up front.
How the assistant reaches the API
The deciding question is whether your assistant can make web requests itself, or only write code for you to run.
| Setup | How it works | Best for |
|---|---|---|
| Claude with a computer (Cowork in the Claude desktop app, or Claude Code) | Claude writes and runs the calls in its own workspace, reads the results, and fixes errors as it goes | Bulk jobs: hundreds of personas, whole-audience scorecards |
| Custom GPT with an Action (ChatGPT) | Import https://api.kumkuat.ai/openapi.json as the Action schema and set API-key auth with the header name X-API-Key. ChatGPT can then call Kumkuat directly | Repeat, small tasks your team runs from ChatGPT |
| Any assistant, you run the code | Ask for a Python script, run it on your computer with your key in an environment variable, and paste back any errors | Assistants with no network access, or strict IT rules about where keys go |
Built-in "run code" tools in regular chat windows often cannot reach outside websites, and features change between plans. If a call fails with a network error, fall back to the third option.
If your team already uses Claude, the Kumkuat MCP server gives Claude tools for persona chat, grades and reactions without any prompt engineering. The prompts below work in any assistant and cover the write-side workflows (creating and tuning personas) that the MCP server does not.
Copy-paste prompts
Replace the words in brackets, attach your file if there is one, and paste. Each prompt names the right endpoints and asks for a preview before anything is written, so it works as a safe starting point in any assistant.
1. Add or edit audiences
Use the Kumkuat API (base https://api.kumkuat.ai, header X-API-Key, spec at
https://api.kumkuat.ai/openapi.json).
I've attached a spreadsheet of [journalists] with columns Name, Outlet, and Beat.
1. List my existing personas (GET /api/v1/personas, limit 500, page with offset)
and match them to the sheet by name, ignoring any "(Outlet)" suffix.
2. For names with no match, create them with POST /api/v1/personas/build, sending
{"personas": [{"name", "organisation", "context"}]} where context is the Beat.
3. Put every persona in the category "[EU Fintech Press]". Use PUT
/api/v1/personas/{id} with the FULL persona object, changing only category.
Show me the match report and planned changes first. Don't write until I say go.
To tune voices instead, swap steps 2–3 for: "For each persona, call POST /api/v1/personas/{id}/analyze-voice with up to 7 writing samples from the sheet and profile_name 'Professional Voice'. Skip personas that already have a profile with that name."
2. Create an audience scorecard
Use the Kumkuat API (base https://api.kumkuat.ai, header X-API-Key).
Here is a draft press release: [paste text].
1. Save it with POST /api/v1/documents {"title", "content"}.
2. Get all personas in the category "[Investors]".
3. Call POST /api/v1/personas/reaction-insights with "personas" (objects with id,
name, description) and "document" (id, title, content). Use the /async version
if there are 10 or more personas.
4. Give me a table of persona, grade, and overall_take, then the three changes
that would raise the most grades.
A useful follow-up: "Write two alternative versions, score all three the same way, and tell me which grades best."
3. Chat with an audience
Use the Kumkuat API (base https://api.kumkuat.ai, header X-API-Key).
Ask every persona in the category "[Media]" this question:
"[Would you cover our Q3 launch, and what would your headline be?]"
Use POST /api/v1/personas/interact with persona_id, input_content, and
interaction_type "conversation". The answer is in the "response" field.
Summarize the common themes, quote the three most useful answers, and save
all answers to a CSV.
For a back-and-forth with one persona, tell the assistant to include the conversation so far in input_content on each call. Each call stands alone, so the persona does not remember earlier turns on its own.
Tips for reliable, safe results
- Preview first. Always ask for a match report or dry run before anything is written.
POST /api/v1/personas/bulk-updatesupportsdry_run: truefor exactly this. - Test on a few, then scale up. Run 3 personas, check them in the Kumkuat app, then run the rest.
- Ask for resumable runs. For big jobs, have the assistant log each finished persona and skip it on a rerun, so a timeout never means starting over.
- Send full objects on edits.
PUT /api/v1/personas/{id}replaces the whole record. Remind the assistant to read the persona, change one field, and send it all back. - Don't let it guess. If the assistant invents a field name, paste the error back. Kumkuat's 422 and 400 errors name the missing field.
- Protect the key. Share it only with an assistant or tool your company has approved. Never paste it into a shared doc or public chat. Rotate it when the job is done (Workspace → API).
Going further with Claude skills
Once a prompt works, you can stop retyping it. In Claude, a skill saves a workflow (the steps, the endpoints, and the checks) so that a one-line request runs the whole thing. Kumkuat skills already exist for tuning persona voices, adding links and ingesting sources, and uploading headshots. For example, "Tune the voices for the personas in this sheet" is enough on its own.
To make your own, run a workflow with Claude once, then say "turn this into a skill." In ChatGPT, a Custom GPT with the Kumkuat Action and your prompt saved as its instructions does the same job.