Last updated 2026-10-25

Quickstart

The short way: the command line

npx kinsy-cli login                      # once: a code appears, you confirm it on kinsy.ai
npx kinsy-cli create "Q3 board update for a 40-person SaaS company: revenue, churn, hiring plan, two asks for the board." \
  --file q3-metrics.csv --slides 10 --wait --out board.pptx

One to two minutes later board.pptx is on disk and the printed link opens the same deck on kinsy.ai. Every command and flag is on the command line page; agents get the same thing as a skill.

The long way: four calls with curl

Create a key, start a deck, poll until it is done, download the file. Everything below works from a terminal with curl and jq.

1. Create a key

export KINSY_API_KEY="ksy_live_…"

2. Start a deck

curl -s -X POST https://kinsy.ai/v1/decks \
  -H "Authorization: Bearer $KINSY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brief": "Q3 board update for a 40-person SaaS company: revenue, churn, hiring plan, two asks for the board.",
    "slides": 10
  }'

The call answers within two seconds:

{
  "deck_id": "deck-7f3a1c",
  "status": "queued",
  "status_url": "https://kinsy.ai/v1/decks/deck-7f3a1c",
  "created_at": "2026-10-25T09:12:04+00:00",
  "credits_charged": 40
}

To build from documents, pass their text as sources (extract a file first with POST /v1/files):

-d '{
  "brief": "Summarise the attached report for the leadership team.",
  "sources": [{"name": "report.pdf", "text": "…extracted text…"}],
  "slides": 12
}'

By default the builder asks itself the questions it would normally ask you (audience, tone, emphasis) and picks sensible answers. Pass "answers": {"audience": "the board"} to decide any of them yourself, or "intake": "skip" to skip the questions altogether.

3. Poll until it is done

until [ "$(curl -s https://kinsy.ai/v1/decks/deck-7f3a1c \
  -H "Authorization: Bearer $KINSY_API_KEY" | jq -r .status)" = "done" ]; do
  sleep 5
done

While it runs, the status call reports status (queued, running, done or error), phase, progress from 0 to 1, and slides_rendered of slides_total. A finished deck usually takes one to two minutes.

4. Download the deck

curl -L -o board-update.pptx https://kinsy.ai/v1/decks/deck-7f3a1c/files/pptx \
  -H "Authorization: Bearer $KINSY_API_KEY"

The file route answers with a redirect to a signed download link. Add ?redirect=false to get the link as JSON instead (useful when your HTTP client does not follow redirects, or when you want the filename). The done status also carries both links under artifacts.

Open the file in PowerPoint: every text box, table and chart is editable, and the fonts travel with the deck.

5. Change a slide

curl -s -X POST https://kinsy.ai/v1/decks/deck-7f3a1c/edits \
  -H "Authorization: Bearer $KINSY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"slide": 3, "instruction": "Tighten the headline and cut the bullets to three."}'

Slides are numbered from 1. An edit costs 5 credits, plus 10 when the slide gets a new picture. If the instruction is too ambiguous to carry out faithfully, the response carries a clarify question instead of a changed slide and nothing is charged.

Retrying safely

Send an Idempotency-Key header with POST /v1/decks. A retry with the same key within 24 hours returns the first response again and charges nothing; the response carries Idempotent-Replayed: true.