API

Kitful REST API

Generate articles, follow their progress and export them with an API key, or read a site's published posts with a read token.

On this page

Routes
Generate an article
Follow a job
Export an article
Errors

The Kitful API has two parts. Each takes its own credential, sent as Authorization: Bearer <credential>.

Credential	Starts with	Where you get it	What it opens
API key	`kit_`	Account > Profile > API keys, at kitful.ai/account/profile	Every site your account owns: generate, status and export
Read token	`kit_read_`	The headless destination of one site, shown once when you connect it	That site's published posts, read only: see Blog API

Keep both on your server. Neither belongs in browser code or a public repository.

Routes

Method	Route	Credential
POST	`/api/v1/articles/generate`	API key
GET	`/api/v1/articles/status/{jobId}`	API key
GET	`/api/v1/articles/{articleId}/export`	API key
GET	`/api/v1/blog/posts`	Read token
GET	`/api/v1/blog/posts/{slug}`	Read token

Every route lives under https://kitful.ai.

Generate an article

curl -X POST https://kitful.ai/api/v1/articles/generate \
  -H "Authorization: Bearer $KITFUL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "focusKeyword": "how to plan a crm migration",
    "context": "We sell a CRM to teams of 10 to 50 people.",
    "spaceSlug": "my-site",
    "settings": { "language": "en-US", "useFaqs": true, "wordCount": 1500 }
  }'

focusKeyword is required, up to 300 characters.
context is optional, up to 1,000 characters: what the article should know about you or the reader.
spaceSlug picks the site. Without it the article goes to the first site you created.
settings is optional. Anything you leave out comes from the site's article settings.

Setting	Values
`language`	A language tag such as `en-US` or `fr`
`wordCount`	300 to 6000; leave it out for automatic length
`promoMode`	`off`, `subtle`, `strong`
`viewPoint`	`auto`, `first_plural`, `first_singular`, `second`, `third`
`useFaqs`, `useConclusion`, `useTables`	`true` or `false`
`useFeaturedImage`, `useImages`, `useVideo`	`true` or `false`
`imageStyle`	`minimalist`, `photorealistic`, `illustration`, `doodle`, `cartoon`, `3d`, `infographic`, `painting`, `line-art`, `dithered`, `engraved-collage`, `papercraft`

A run costs the same credits as one started in Kitful: see Credits and usage. The answer is 202 with the job to follow:

{ "jobId": "01EXAMPLEJOB", "status": "pending" }

Follow a job

curl https://kitful.ai/api/v1/articles/status/01EXAMPLEJOB \
  -H "Authorization: Bearer $KITFUL_API_KEY"

{
  "jobId": "01EXAMPLEJOB",
  "status": "completed",
  "currentStep": "finalize",
  "articleId": "01EXAMPLEARTICLE",
  "articleUrl": "https://kitful.ai/my-site/articles/01EXAMPLEARTICLE"
}

status is pending, in-progress, completed or failed. currentStep is null until the run starts, then research, construct, image_gen or finalize; older jobs can report other values. articleId and articleUrl stay null until the article exists. Poll every 15 seconds or slower: an article takes a few minutes.

Export an article

curl -OJ "https://kitful.ai/api/v1/articles/01EXAMPLEARTICLE/export?format=markdown" \
  -H "Authorization: Bearer $KITFUL_API_KEY"

format is markdown (the default), html or zip, which holds both. The answer is a file download named after the article's slug.

Errors

Every error answers JSON with the same message in error and message:

{
  "error": "Insufficient credits. This action requires 20 credits.",
  "message": "Insufficient credits. This action requires 20 credits."
}

Status	Meaning
400	The request is invalid; the message says what is wrong
401	The credential is missing or not valid
402	Not enough credits for this run, or the subscription is inactive
404	No job, article or site with that id or `spaceSlug` in your account
429	Your plan's limit of articles generating at once is reached; wait for one to finish
500	Kitful failed; try again

The blog routes also send a code to branch on. A 500 always carries code: "server_error".