apply Article Import
View .mdPOST /v1/developer/collections/{collection}/articles/imports/apply
Operation ID: applyArticleImport
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
Section titled “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
Section titled “Request parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
collection |
path | string | yes |
Request body
Section titled “Request body”The request body is JSON. The canonical schema is:
{ "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 }, "planDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 128 } }, "required": [ "key", "expectedRevision", "document", "planDigest", "idempotencyKey" ], "additionalProperties": false}Minimal example:
{ "key": "string", "expectedRevision": "string", "document": { "slug": "string", "title": "string", "body": [ "string" ], "source": { "kind": "imported", "url": "string", "capturedAt": "string", "sha256": "string" } }, "planDigest": "string", "idempotencyKey": "string"}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.
curl --request POST \ "$KISMET_API_ORIGIN/v1/developer/collections/example-collection/articles/imports/apply" \ --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"}},"planDigest":"string","idempotencyKey":"string"}'Responses
Section titled “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
Section titled “200 response schema”Content type: application/json. Required fields, nullable values, and nested structures are defined below.
View complete response schema
{ "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "articleId": { "type": "string", "format": "uuid" }, "collectionId": { "type": "string" }, "key": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,79}$" }, "revision": { "type": "integer", "exclusiveMinimum": 0 }, "createdAt": { "type": "string", "format": "date-time" }, "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": [ "id", "articleId", "collectionId", "key", "revision", "createdAt", "document" ], "additionalProperties": false}