--- title: "Create an article draft" method: POST path: "/products/help-desk/knowledge-base/articles" tags: ["help-desk"] --- # Create an article draft `POST /products/help-desk/knowledge-base/articles` ## Request - Base URL: `https://api.sparkvault.com/v1` - URL: `https://api.sparkvault.com/v1/products/help-desk/knowledge-base/articles` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Uses the organization administrator's own console session, never an API key or impersonated session. The help desk must be active. Management writes require an active admin with a Full License and a matching version; private content stays encrypted in the desk vault until explicitly published. ## Request body - KnowledgeBaseArticleInput - `title` string, required - `slug` string, required - `summary` string - `body_markdown` string, required: Nonempty Markdown, at most 500 KiB in UTF-8. Stored as an immutable encrypted revision. - `category_id` string, nullable - `position` integer - `seo_title` string, nullable - `seo_description` string, nullable - `seo_keywords` string[] - `related_article_ids` string[] - `source` KnowledgeBaseImportSource - `external_id` string, required - `source_hash` string, required - `source_path` string, nullable - `source_created_at` string, date-time, nullable - `source_updated_at` string, date-time, nullable - `source_published_at` string, date-time, nullable - `source_metrics` object - `views` integer - `helpful` integer - `not_helpful` integer - `related_external_ids` string[] - `path` string, nullable: Optional safe root-relative published path; authentication, portal and internal paths are reserved. - `featured` boolean - `popular_rank` integer, nullable - `cover_image_url` string, nullable ## Response `201` The saved result. - object - `data` object, required - `article` KnowledgeBaseArticle, required - `title` string, required - `slug` string, required - `summary` string - `body_markdown` string: Nonempty Markdown, at most 500 KiB in UTF-8. Stored as an immutable encrypted revision. - `category_id` string, nullable - `position` integer - `seo_title` string, nullable - `seo_description` string, nullable - `seo_keywords` string[] - `related_article_ids` string[] - `source` KnowledgeBaseImportSource - `external_id` string, required - `source_hash` string, required - `source_path` string, nullable - `source_created_at` string, date-time, nullable - `source_updated_at` string, date-time, nullable - `source_published_at` string, date-time, nullable - `source_metrics` object - `views` integer - `helpful` integer - `not_helpful` integer - `related_external_ids` string[] - `path` string, nullable: Optional safe root-relative published path; authentication, portal and internal paths are reserved. - `featured` boolean - `popular_rank` integer, nullable - `cover_image_url` string, nullable - `article_id` string, required - `version` integer, required: The version last read; a stale version is refused with 409. - `current_revision_id` string, required - `published_revision_id` string, nullable, required - `source_revision_id` string, nullable - `has_unpublished_changes` boolean, required - `archived` boolean - `created_at` integer - `updated_at` integer - `asset_bindings` object: Server-pinned image reference to immutable asset id for this revision. Returned in article detail and revision reads, omitted from workspace summaries; clients cannot set it. Restoring preserves its historical media. - `meta` ResponseMeta: Envelope metadata present on every successful response. - `api_version` string - `request_id` string - `response_ms` integer - `timestamp` integer: Unix seconds. - `pools` object: Storage and bandwidth capacity snapshot for the account. - `billing` object - `past_due` boolean - `quota` object: This minute of the account request budget. Present on authenticated success responses that passed the throttle; absent otherwise. - `limit` integer - `used` integer - `remaining` integer - `resets_at` integer: Unix seconds. ## Other responses - `400`: VALIDATION_ERROR — the request contains an invalid or unsupported value. - `401`: AUTHENTICATION_ERROR — a current organization session is required. - `403`: FORBIDDEN — an organization administrator is required; management writes also require a Full License. - `404`: NOT_FOUND — this account has no matching article, category, image, revision or operation. - `409`: CONFLICT — a stale version, publication in progress, changed public release, or lifecycle fence. Reload before retrying. - `429`: RATE_LIMIT_EXCEEDED — wait for the Retry-After interval. ## Changes - **2026-10-28** `a9a10e328ba5`: 24 info - the response property `error/details` became required for the status `400` - the response property `error/details` became required for the status `401` - the response property `error/details` became required for the status `403` - the response property `error/details` became required for the status `404` - …20 more - **2026-10-28** `56d7c265a77a`: 6 breaking - the response property `error/details` became nullable for the status `400` - the response property `error/details` became nullable for the status `401` - the response property `error/details` became nullable for the status `403` - the response property `error/details` became nullable for the status `404` - …2 more - **2026-10-27** `ac44ec1f8cfa`: 1 info - endpoint added [Operation history](https://skmtc.dev/sparkvault/apis/sparkvault-api/changes/products/help-desk/knowledge-base/articles/post.md) --- [API](https://skmtc.dev/sparkvault/apis/sparkvault-api.md) - [All operations](https://skmtc.dev/sparkvault/apis/sparkvault-api/llms.txt) - [OpenAPI document](https://skmtc.dev/sparkvault/apis/sparkvault-api/revisions/97cfadccd0c0?raw)