Last updated 2026-10-25

API reference

Base URL https://kinsy.ai/v1. All responses are JSON; errors use the envelope. The machine-readable version of this page is /v1/openapi.json.

Resources at a glance

Decks — POST /v1/decks starts a build and answers at once with a deck id. GET /v1/decks/{id} is the status and, once done, the download links, with ?include=slides,quality adding per-slide details and the fact-check summary. GET /v1/decks/{id}/files/{kind} downloads pptx, pdf or a png zip. GET /v1/decks lists your decks, newest first, paged by cursor.
Edits — POST /v1/decks/{id}/edits rewrites one slide (numbered from 1) from an instruction. The call is synchronous: it returns once the slide has been rewritten and re-rendered, which takes longer when the slide needs a new picture. Keep your client's read timeout generous (two minutes) and do not retry an edit that timed out without checking the deck first; edits are charged when they complete.
Intake — POST /v1/intake returns the questions the builder would ask about a brief, each with suggested answers, so you can decide them up front instead of letting the builder choose.
Files — POST /v1/files extracts the text of a document to pass as a source. Supported: PDF, Word-style text documents, Markdown and plain text, spreadsheets and CSV, and images.
Account — GET /v1/me for the plan and balance; GET /v1/themes and GET /v1/templates for the catalogues.

Build options

Field	Values	Meaning
`slides`	4–25, default 10	Target slide count. The deck follows the material, so the final count can land near rather than on the target; the credit band is charged on the target.
`intake`	`auto` (default), `skip`	`auto`: the builder asks its own questions and fills any you did not answer. `skip`: build straight from the brief and your `answers`.
`answers`	object	Your answers to intake questions by key (`audience`, `tone`, …). Yours always win.
`research`	`auto` (default), `on`, `off`	`auto` turns live research on when the brief depends on recent events.
`theme`, `template`	ids from the catalogues	Visual theme and deck template; omitted means Kinsy chooses from the content.
`brand_kit_id`	id	A brand kit uploaded in the web app.

Status fields

status is queued, running, done or error. While running, phase, progress (0–1), slides_rendered and slides_total move. On done, artifacts.pptx and artifacts.pdf carry url, filename and expires_at, and watermark says whether the free-plan mark is on the slides. On error, error is a short plain-English sentence.

Reference

Generated from the OpenAPI document. Every call except the catalogues and the spec needs Authorization: Bearer ksy_live_….

POST /v1/auth/device

Start a device sign-in (what `kinsy login` calls)

No key needed.

Request body (application/json)

Field	Type
`client`	string	The tool asking, e.g. cli/0.1.0.
`hostname`	string	The machine asking to sign in; shown on the approval page.

Response 200

Field	Type
`device_code` required	string	Secret; poll with it. Never shown to the person.
`expires_in` required	integer	Seconds until the codes expire (600).
`interval` required	integer	Minimum seconds between polls.
`user_code` required	string	Eight characters the person types in, shown as XXXX-XXXX.
`verification_uri` required	string
`verification_uri_complete` required	string	verification_uri with the code pre-filled.

Errors use the envelope.

POST /v1/auth/device/token

Poll for the key once the sign-in is approved in the browser

No key needed.

Request body (application/json)

Field	Type
`device_code` required	string

Response 200

Field	Type
`api_key`	string \| null	Only on the single approved answer; the key is created at that moment.
`email`	string \| null
`interval` required	integer	Seconds to wait before the next poll (grows on slow_down).
`key_hint`	string \| null
`key_id`	string \| null
`status` required	`pending` · `slow_down` · `approved` · `denied` · `expired` · `claimed`	approved carries the key exactly once; afterwards the code reads claimed.

Errors use the envelope.

POST /v1/decks

Create a deck (answers in under two seconds; poll the status URL)

Parameters

Name	In	Type
`Idempotency-Key`	header	string \| null
`authorization`	header	string \| null
`x-kinsy-client`	header	string \| null

Request body (application/json)

Field	Type
`answers`	object
`brand_kit_id`	string \| null
`brief`	string	What the deck should say and who it is for.
`callback_url`	string \| null	Reserved.
`intake`	`auto` · `skip`
`research`	`auto` · `on` · `off`
`slides`	integer \| null	Target slide count (default 10).
`sources`	array of Source	Documents the deck is built from (text already extracted).
`template`	string \| null
`theme`	string \| null

Source

Field	Type
`name` required	string
`text` required	string

Response 202

Field	Type
`created_at` required	string
`credits_charged`	integer
`deck_id` required	string
`status`	`queued`
`status_url` required	string

Errors use the envelope.

GET /v1/decks

Your decks, newest first

Parameters

Name	In	Type
`limit`	query	integer
`cursor`	query	string \| null
`authorization`	header	string \| null
`x-kinsy-client`	header	string \| null

Response 200

Field	Type
`decks` required	array of DeckSummary
`next_cursor`	string \| null

DeckSummary

Field	Type
`client`	string \| null
`created_at`	string \| null
`deck_id` required	string
`status` required	string
`title`	string \| null
`updated_at`	string \| null

Errors use the envelope.

GET /v1/decks/{deck_id}

Status of a deck build, and the files once it is done

Parameters

Name	In	Type
`deck_id` required	path	string
`include`	query	string	Comma list: slides, quality
`authorization`	header	string \| null
`x-kinsy-client`	header	string \| null

Response 200

Field	Type
`artifacts`	DeckArtifacts \| null
`client`	string \| null
`created_at`	string \| null
`deck_id` required	string
`error`	string \| null
`phase`	string \| null
`progress`	number
`quality`	QualitySummary \| null
`slides`	array of SlideInfo \| null
`slides_rendered`	integer
`slides_total`	integer \| null
`status` required	string
`title`	string \| null
`updated_at`	string \| null
`watermark`	boolean \| null

DeckArtifacts

Field	Type
`pdf`	DeckArtifact \| null
`pptx`	DeckArtifact \| null

DeckArtifact

Field	Type
`expires_at` required	string
`filename` required	string
`url` required	string

QualitySummary

Field	Type
`available` required	boolean
`fact_claims`	integer
`findings`	array of QualityFinding
`flagged`	integer
`missing_topics`	array of string

QualityFinding

Field	Type
`claim`	string
`fix`	string
`fixed`	boolean
`slide`	integer \| null
`verdict`	string

Errors use the envelope.

POST /v1/decks/{deck_id}/edits

Rewrite one slide from an instruction

Parameters

Name	In	Type
`deck_id` required	path	string
`authorization`	header	string \| null
`x-kinsy-client`	header	string \| null

Request body (application/json)

Field	Type
`instruction` required	string
`slide` required	integer	1-based slide number.

Response 200

Field	Type
`clarify`	string \| null
`credits_charged`	integer
`deck_id` required	string
`images_generated`	integer
`layout_changed`	boolean
`slide`	SlideInfo \| null
`title`	string

SlideInfo

Field	Type
`headline`	string \| null
`layout` required	string
`num` required	integer
`png_url`	string

Errors use the envelope.

GET /v1/decks/{deck_id}/files/{kind}

Download a finished deck (pptx, pdf or png zip)

Parameters

Name	In	Type
`deck_id` required	path	string
`kind` required	path	string
`redirect`	query	boolean	false → return the link as JSON
`authorization`	header	string \| null
`x-kinsy-client`	header	string \| null

Response 200

Field	Type
`expires_at` required	string
`filename` required	string
`url` required	string

Errors use the envelope.

POST /v1/files

Extract the text of a document to use as a source

Parameters

Name	In	Type
`authorization`	header	string \| null
`x-kinsy-client`	header	string \| null

Request body (multipart/form-data)

Field	Type
`file` required	string

Response 200

Field	Type
`char_count` required	integer
`name` required	string
`text` required	string
`truncated` required	boolean

Errors use the envelope.

POST /v1/intake

The questions the builder would ask about a brief

Parameters

Name	In	Type
`authorization`	header	string \| null
`x-kinsy-client`	header	string \| null

Request body (application/json)

Field	Type
`brief`	string
`sources`	array of Source

Source

Field	Type
`name` required	string
`text` required	string

Response 200

Field	Type
`questions` required	array of IntakeQuestionV1
`research_available`	boolean
`time_sensitive`	boolean
`time_sensitive_reason`	string

IntakeQuestionV1

Field	Type
`key` required	string
`question` required	string
`suggested`	array of string
`why`	string

Errors use the envelope.

GET /v1/me

Who am I and what can I spend

Parameters

Name	In	Type
`authorization`	header	string \| null
`x-kinsy-client`	header	string \| null

Response 200

Field	Type
`client` required	string
`credits` required	CreditBalance
`email`	string \| null
`email_verified` required	boolean
`key`	KeyInfo \| null
`plan` required	string
`target_max` required	integer
`uid` required	string
`watermark` required	boolean

CreditBalance

Field	Type
`degraded`	boolean
`extra` required	integer
`monthly_grant` required	integer
`period_remaining` required	integer
`period_used` required	integer
`resets_at`	string \| null
`total` required	integer

KeyInfo

Field	Type
`created_at` required	string
`hint` required	string
`key_id` required	string
`label` required	string
`last_used_at`	string \| null
`src` required	string

Errors use the envelope.

GET /v1/templates

List the deck templates

No key needed.

Response 200

Errors use the envelope.

GET /v1/themes

List the slide themes

No key needed.

Response 200

Errors use the envelope.