--- title: "plan Article Import" description: "Import canonical Articles as isolated drafts. Review the returned immutable revision and explicitly publish it to staging. Production Article reads and serving routes remain unchanged. Requires collection-scoped server credentials; content channel is independent of TEST/LIVE transaction mode." --- `POST /v1/developer/collections/{collection}/articles/imports/plan` **Operation ID:** `planArticleImport` Import canonical Articles as isolated drafts. Review the returned immutable revision and explicitly publish it to staging. Production Article reads and serving routes remain unchanged. Requires collection-scoped server credentials; content channel is independent of TEST/LIVE transaction mode. ## Contract status | Field | Value | | --- | --- | | Maturity | `preview` | | Required capability | `content.write` | | Freshness class | `authenticated-state` | | Quota cost | `1` | All operations require a Kismet Developer Bearer credential. Collection and resource authority is resolved from the credential's installation grants; identifiers in the URL never grant access. ## Request parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `collection` | path | string | yes | | ## Request body The request body is JSON. The canonical schema is: ```json { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,79}$" }, "expectedRevision": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ] }, "document": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "sourcePublishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "excerpt": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ] }, "hero": { "anyOf": [ { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "alt": { "type": "string", "minLength": 1, "maxLength": 500 }, "caption": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] } }, "required": [ "url", "alt" ], "additionalProperties": false }, { "type": "null" } ] }, "body": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "prose" ] }, "html": { "type": "string", "minLength": 1, "maxLength": 100000 } }, "required": [ "type", "html" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "src": { "type": "string", "format": "uri", "maxLength": 2048 }, "alt": { "type": "string", "minLength": 1, "maxLength": 500 }, "caption": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] } }, "required": [ "type", "src", "alt" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "pullquote" ] }, "text": { "type": "string", "minLength": 1, "maxLength": 5000 }, "cite": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "faq" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "q": { "type": "string", "minLength": 1, "maxLength": 500 }, "a": { "type": "string", "minLength": 1, "maxLength": 5000 } }, "required": [ "q", "a" ], "additionalProperties": false }, "minItems": 1, "maxItems": 50 } }, "required": [ "type", "items" ], "additionalProperties": false } ] }, "minItems": 1, "maxItems": 200 }, "authorId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "categoryIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 30, "default": [] }, "source": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "imported" ] }, "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "capturedAt": { "type": "string", "format": "date-time" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "kind", "url", "capturedAt", "sha256" ], "additionalProperties": false } }, "required": [ "slug", "title", "body", "source" ], "additionalProperties": false } }, "required": [ "key", "expectedRevision", "document" ], "additionalProperties": false } ``` Minimal example: ```json { "key": "string", "expectedRevision": "string", "document": { "slug": "string", "title": "string", "body": [ "string" ], "source": { "kind": "imported", "url": "string", "capturedAt": "string", "sha256": "string" } } } ``` ## cURL Set `KISMET_API_ORIGIN=https://api.ksmt.app` and configure `KISMET_DEVELOPER_API_KEY` in your environment. Run server-credential requests from your backend, not browser code. ```sh curl --request POST \ "$KISMET_API_ORIGIN/v1/developer/collections/example-collection/articles/imports/plan" \ --header "Authorization: Bearer $KISMET_DEVELOPER_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data '{"key":"string","expectedRevision":"string","document":{"slug":"string","title":"string","body":["string"],"source":{"kind":"imported","url":"string","capturedAt":"string","sha256":"string"}}}' ``` ## Responses | Status | Meaning | | --- | --- | | 200 | Success. | | 400 | Invalid request parameters or body. | | 401 | Missing, invalid, expired, or inappropriate credential/session. | | 403 | Credential lacks the required grant/capability, or an origin/CSRF check failed. | | 404 | The authorized resource was not found. | | 409 | Request conflicts with the installation environment or current state. | | 429 | Rate limit or quota exceeded; inspect response metadata before retrying. | | 503 | A required Kismet dependency is temporarily unavailable. | ### 200 response schema Content type: `application/json`. Required fields, nullable values, and nested structures are defined below.
View complete response schema ```json { "type": "object", "properties": { "action": { "type": "string", "enum": [ "create", "update" ] }, "planDigest": { "type": "string" }, "input": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,79}$" }, "expectedRevision": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ] }, "document": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "sourcePublishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "excerpt": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ] }, "hero": { "anyOf": [ { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "alt": { "type": "string", "minLength": 1, "maxLength": 500 }, "caption": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] } }, "required": [ "url", "alt" ], "additionalProperties": false }, { "type": "null" } ] }, "body": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "prose" ] }, "html": { "type": "string", "minLength": 1, "maxLength": 100000 } }, "required": [ "type", "html" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "src": { "type": "string", "format": "uri", "maxLength": 2048 }, "alt": { "type": "string", "minLength": 1, "maxLength": 500 }, "caption": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] } }, "required": [ "type", "src", "alt" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "pullquote" ] }, "text": { "type": "string", "minLength": 1, "maxLength": 5000 }, "cite": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "faq" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "q": { "type": "string", "minLength": 1, "maxLength": 500 }, "a": { "type": "string", "minLength": 1, "maxLength": 5000 } }, "required": [ "q", "a" ], "additionalProperties": false }, "minItems": 1, "maxItems": 50 } }, "required": [ "type", "items" ], "additionalProperties": false } ] }, "minItems": 1, "maxItems": 200 }, "authorId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "categoryIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 30, "default": [] }, "source": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "imported" ] }, "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "capturedAt": { "type": "string", "format": "date-time" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "kind", "url", "capturedAt", "sha256" ], "additionalProperties": false } }, "required": [ "slug", "title", "body", "source" ], "additionalProperties": false } }, "required": [ "key", "expectedRevision", "document" ], "additionalProperties": false }, "path": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } } }, "required": [ "action", "planDigest", "input", "path", "warnings" ], "additionalProperties": false } ```
## Machine-readable sources - [This page as Markdown](/api/reference/plan-article-import.md) - [Developer API OpenAPI v0.7.50](/openapi.json)