create Collection Media Import

POST /v1/developer/collections/{collection}/media/imports

Operation ID: createCollectionMediaImport

Collection-owned image library import. Plan first, then confirm the exact digest. Persistent jobs and authority fail closed; HTTPS DNS/redirect checks, MIME/bytes/pixel/10 MiB bounds apply before the canonical uploader. Four new jobs per collection per refill hour, up to 50 images per job. Source query strings remain private. This does not publish Articles or activate serving routes. Jobs/results expire after 24 hours; explicit resume skips already settled sources. CMS library writes are distinct from TEST/LIVE booking authority.

Contract status

Field	Value
Maturity	`preview`
Required capability	`media.import`
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:

{
  "type": "object",
  "properties": {
    "requestId": {
      "type": "string",
      "format": "uuid"
    },
    "urls": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "src": {
            "type": "string",
            "format": "uri",
            "maxLength": 2048
          },
          "alt": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500
          }
        },
        "required": [
          "src"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 50
    },
    "planDigest": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$"
    },
    "confirm": {
      "type": "boolean",
      "enum": [
        true
      ]
    }
  },
  "required": [
    "requestId",
    "urls",
    "planDigest",
    "confirm"
  ],
  "additionalProperties": false
}

Minimal example:

{
  "requestId": "11111111-1111-4111-8111-111111111111",
  "urls": [
    {
      "src": "https://media.example.com/photo.jpg",
      "alt": "Waterfront"
    }
  ],
  "planDigest": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "confirm": true
}

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.

curl --request POST \
  "$KISMET_API_ORIGIN/v1/developer/collections/example-collection/media/imports" \
  --header "Authorization: Bearer $KISMET_DEVELOPER_API_KEY" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{"requestId":"11111111-1111-4111-8111-111111111111","urls":[{"src":"https://media.example.com/photo.jpg","alt":"Waterfront"}],"planDigest":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","confirm":true}'

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

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "collectionId": {
      "type": "string",
      "format": "uuid"
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "running",
        "completed",
        "failed"
      ]
    },
    "publication": {
      "type": "string",
      "enum": [
        "library_only"
      ]
    },
    "totalCount": {
      "type": "integer",
      "minimum": 0
    },
    "processedCount": {
      "type": "integer",
      "minimum": 0
    },
    "importedCount": {
      "type": "integer",
      "minimum": 0
    },
    "existingCount": {
      "type": "integer",
      "minimum": 0
    },
    "failedCount": {
      "type": "integer",
      "minimum": 0
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "src": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "imported",
              "existing",
              "failed"
            ]
          },
          "image": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "url": {
                "type": "string",
                "format": "uri"
              }
            },
            "required": [
              "id",
              "url"
            ],
            "additionalProperties": false
          },
          "code": {
            "type": "string"
          }
        },
        "required": [
          "src",
          "status"
        ],
        "additionalProperties": false
      }
    },
    "errorCode": {
      "type": [
        "null",
        "string"
      ]
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time"
    },
    "expiresAt": {
      "type": "string",
      "format": "date-time"
    }
  },
  "required": [
    "id",
    "collectionId",
    "status",
    "publication",
    "totalCount",
    "processedCount",
    "importedCount",
    "existingCount",
    "failedCount",
    "results",
    "errorCode",
    "createdAt",
    "updatedAt",
    "expiresAt"
  ],
  "additionalProperties": false
}