Kontent.ai
Copyright © 2023 Kontent.ai. All rights reserved.
  • Web
  • Privacy policy
  • Cookies policy
  • Consent settings
  • Security
  • GDPR
  • Documentation
  • API reference
  • Product updates
Kontent.ai Learn
  • Plan
  • Set up
  • Model
  • Develop
  • Create

Import content items

Is this page helpful?
Complete and continue
  • Sign in
    • JavaScript
      JavaScript
    • .NET
      .NET
    • REST
      REST
    Tomas Nosek
    43 minutes
    This lesson shows you how to import a single content item using Management API. In short, to import content, you define a content type for the imported content if it’s not created already. Then, you’ll create a new content item and add content to its variants.

    1. Define a content type for the content item

    Before importing your content, you need to define a content type for the items you want to import. The content type in this example is named Cafe (with the codename and external ID both as cafe) and contains a few elements. To add a content type, send a POST request with these properties:
    • The display name of the new content type.
    • (Optional) The codename of the content type. If you don’t specify the codename, it will be generated from the content type’s display name. However, you can change the codename later.
    • (Optional) The external ID can be used as a unique identifier to retrieve content from a different system. See more about how to use different identifiers.
    • A set of the elements you want to have in your content type.
    Don't forget to set your Management API key in the request’s authorization header (or the ManagementClient definition when using an SDK).
    After making the request, you’ll get a JSON response like this:

    2. Import content to a content item

    Importing a content item consists of two tasks. That’s because, technically, each content item is a wrapper that contains language variants. Variants then hold the content. This enables content to be localized but the same approach applies to projects with one language as well.

    2a. Create a content item

    To add a content item, send a PUT request with these properties:
    • The name, which is a string representing the display name of the new content item.
    • The codename of the content type, which is used for the content item.
    As importing a lot of content can become confusing, handling content from your original system's point of view is typically easier. Use external IDs to identify your content when doing a migration. With external IDs, you can also reference items that haven't been imported yet. That's when content items link each other in rich text or linked items elements. You don't need to worry about the order in which the content items are imported. However, if you don't want to use external IDs, you can use other identifiers as well.
    After sending the request, Kontent.ai generates the internal ID and codename for the content item and includes it in the response. Also, the content item is assigned to the default collection.
    You've just created an empty content item. To verify that the content item has been added, you have two options:
    • Retrieve the content item via API.
    • Check your content list in Kontent.ai.
    So far, you have only specified the general attributes of the content item – its name, content type, and external ID. Now, let's add the actual (localized) content.

    2b. Add (localized) content

    The actual content is stored in the individual content elements in each variant. To add content there, send a PUT request and specify the following:
    • The content item you're importing content to – ideally with its external ID. For example, ext-cafe-brno.
    • The language's code name – available in Environment settings > Localization. For example, en-US.
    • Elements with content that you want to import. Omitted elements will:
      • Remain empty when creating new content
      • Remain unchanged when updating already existing content
      • Generate automatically if they're URL slugs
    The response will include the updated item variant.
    To verify that the variant has been imported, you have two options:
    • Retrieve variants of the item via API.
    • Check your content list in Kontent.ai.
    What's next?
    Import linked content
    Content items often contain references to other content items in linked items elements or rich text elements. This lesson shows you how to import these references to Kontent.ai.
    • Develop with Kontent.ai
    • Hello World
    • Hello Web Spotlight
    • Run a sample app
    • Build apps
    • Decide navigation and URLs
    • Environments
    • Get Developer Certification
    • JSON
    A model of a content item.
    • JSON
    • JSON
    What content items consist of
    The created item will show up as Not translated.
    {
  "id": "f15799a1-dff0-5216-a014-e963f9ea6bbc",
  "codename": "cafe",
  "last_modified": "2019-10-08T12:47:27.4261844Z",
  "external_id": "cafe",
  "name": "Cafe",
  "content_groups": [],
  "elements": [
    {
      "name": "Price per unit",
      "guidelines": null,
      "is_required": false,
      "type": "number",
      "id": "965cf18c-998a-456b-bee3-91defdf39782",
      "codename": "price_per_unit"
    },
    {
      "guidelines": "<h2>Keep Guidelines where the creative process happens.</h2>\n<p>These are sample guidelines that you can place for the whole content item. It’s a place where you can include your content brief, voice and tone recommendations or the URL to a wireframe, so the author will have all the relevant instructions at hand before writing a single line.</p>\n<p>Besides overview guidelines, you can include instructions for each particular content element, as you will see below.</p>",
      "type": "guidelines",
      "id": "8816e7d0-ca5e-4cfa-88b4-c1944862ff9f",
      "codename": "n8e317a38_e3bc_4d98_a63d_f1e336c5a9e6"
    },
    {
      "maximum_text_length": null,
      "name": "Street",
      "guidelines": null,
      "is_required": false,
      "type": "text",
      "id": "2b7b256c-73cc-4be0-b749-4c410209df02",
      "codename": "street"
    },
    {
      "maximum_text_length": null,
      "name": "City",
      "guidelines": null,
      "is_required": false,
      "type": "text",
      "id": "fa17f73a-833c-4cf2-aa7b-3b5c4edad6b3",
      "codename": "city"
    },
    {
      "maximum_text_length": null,
      "name": "Country",
      "guidelines": null,
      "is_required": false,
      "type": "text",
      "id": "2b36b05e-5f4f-4630-b502-154f5b3b90c3",
      "codename": "country"
    },
    {
      "maximum_text_length": null,
      "name": "State",
      "guidelines": null,
      "is_required": false,
      "type": "text",
      "id": "3638f2cd-3fea-4a4e-a6b6-bdd39f3b9f66",
      "codename": "state"
    },
    {
      "maximum_text_length": null,
      "name": "ZIP Code",
      "guidelines": null,
      "is_required": false,
      "type": "text",
      "id": "35ad677a-cfe5-4573-814d-5895e3de8396",
      "codename": "zip_code"
    },
    {
      "maximum_text_length": null,
      "name": "Phone",
      "guidelines": null,
      "is_required": false,
      "type": "text",
      "id": "4ec54355-4177-4b29-9a16-b25a7c8fba26",
      "codename": "phone"
    },
    {
      "maximum_text_length": null,
      "name": "Email",
      "guidelines": null,
      "is_required": false,
      "type": "text",
      "id": "9bc4b679-4353-40c7-bcfd-145110ced7d9",
      "codename": "email"
    },
    {
      "asset_count_limit": null,
      "maximum_file_size": null,
      "allowed_file_types": "any",
      "image_width_limit": null,
      "image_height_limit": null,
      "name": "Photo",
      "guidelines": null,
      "is_required": false,
      "type": "asset",
      "id": "1693ecd3-fb15-4d56-975a-4b8dbdedf65b",
      "codename": "photo"
    }
  ]
}
    {
  "id": "8ceeb2d8-9676-48ae-887d-47ccb0f54a79",
  "name": "Brno",
  "codename": "brno",
  "type": {
    "id": "fe41ae5a-5fe2-420a-8560-f7d6d3533dc2"
  },
  "collection": {
    "id": "00000000-0000-0000-0000-000000000000"
  },
  "sitemap_locations": [],
  "external_id": "ext-cafe-brno",
  "last_modified": "2017-11-09T16:51:09.041611Z"
}
    {
    "elements": [
        {
            "element": {
                "id": "866afdba-d334-f01a-1d52-a9ca3f57cb4b"
            },
            "value": "Nove Sady 25"
        },
        {
            "element": {
                "id": "339e6d4f-67c1-5f5e-6921-3b374eb96f5b"
            },
            "value": "Brno"
        },
        {
            "element": {
                "id": "7531a08f-e148-8cc0-9d2d-155215502e08"
            },
            "value": "Czech Republic"
        },
        {
            "element": {
                "id": "a015b689-cad3-1ac9-04b4-73697525752d"
            },
            "value": "Jihomoravsky kraj"
        },
        {
            "element": {
                "id": "bb158ac2-41e1-5a7d-0826-bb8bf6744f0e"
            },
            "value": "60200"
        },
        {
            "element": {
                "id": "1c71bc62-4b62-f307-37ef-0823776f8f73"
            },
            "value": "+420 555 555 555"
        },
        {
            "element": {
                "id": "6f726c77-36bd-8062-51df-056136e10d35"
            },
            "value": "brnocafe@kontent.ai"
        },
        {
            "element": {
                "id": "5769c0f4-66a8-4c73-3c19-c023bdfa123a"
            },
            "value": [
                {
                    "id": "8fad2e2c-1351-4bfc-be12-007582d61c48"
                }
            ]
        },
        {
            "element": {
                "id": "e82d0f49-5b15-45e1-9b1f-32ccc1be4941"
            },
            "value": [
                {
                    "id": "2ab0aad5-7609-4371-8d6e-cb4a917b2ad1"
                },
                {
                    "id": "405c6578-8233-4277-9826-6b5e74dc6f39"
                }
            ]
        }
    ],
    "workflow_step": {
        "id": "88ac5e6e-1c5c-4638-96e1-0d61221ad5bf"
    },
    "item": {
        "id": "33389c83-dcfe-48f9-b0ee-f94aeabd2b08"
    },
    "language": {
        "id": "00000000-0000-0000-0000-000000000000"
    },
    "last_modified": "2021-12-03T09:52:05.5604855Z"
}
    • Overview
    • Import content via API
    • Automate migrations with CLI
    • PDFs and other formats
    • cURL
    • cURL
    • cURL
    Why PUT is better than POSTBesides the PUT request from the example, you can also use a POST request. However, using a PUT operation has its advantages and makes the import process much smoother. With PUT requests, you can:
    • Run the same request repeatedly – If the item doesn't exist, it will be created. If it does, it will be updated.
    • Reference your items with external IDs
    You can find out more about both topics in the API reference on upserting content items.
    Avoid security incidentsAfter you finish importing content, consider deactivating the Management API if you don’t plan on using the API further.
    curl --request POST \
  --url https://manage.kontent.ai/v2/projects/<YOUR_ENVIRONMENT_ID>/types \
  --header 'Authorization: Bearer <YOUR_MANAGEMENT_API_KEY>' \
  --header 'Content-type: application/json' \
  --data '
{
  "codename": "cafe",
  "name": "Cafe",
  "external_id": "cafe",
  "elements": [
    {
      "name": "Price per unit",
      "type": "number",
      "codename": "price_per_unit"
    },
    {
      "guidelines": "<h2>Keep Guidelines where the creative process happens.</h2>\n<p>These are sample guidelines that you can place for the whole content item. It’s a place where you can include your content brief, voice and tone recommendations or the URL to a wireframe, so the author will have all the relevant instructions at hand before writing a single line.</p>\n<p>Besides overview guidelines, you can include instructions for each particular content element, as you will see below.</p>",
      "type": "guidelines",
      "codename": "n2f836bce_e062_b2cd_5265_f5c3be3aa6f5"
    },
    {
      "name": "Street",
      "type": "text",
      "codename": "street"
    },
    {
      "name": "City",
      "type": "text",
      "codename": "city"
    },
    {
      "name": "Country",
      "type": "text",
      "codename": "country"
    },
    {
      "name": "State",
      "type": "text",
      "codename": "state"
    },
    {
      "name": "ZIP Code",
      "type": "text",
      "codename": "zip_code"
    },
    {
      "name": "Phone",
      "type": "text",
      "codename": "phone"
    },
    {
      "name": "Email",
      "type": "text",
      "codename": "email"
    },
    {
      "name": "Photo",
      "type": "asset",
      "codename": "photo"
    }
  ]
}'
    curl --request PUT \
  --url https://manage.kontent.ai/v2/projects/<YOUR_ENVIRONMENT_ID>/items/external-id/ext-cafe-brno \
  --header 'Authorization: Bearer <YOUR_MANAGEMENT_API_KEY>' \
  --header 'Content-type: application/json' \
  --data '
{
  "name": "Brno",
  "type": {
     "codename": "cafe"
  }
}'
    curl --request PUT \
  --url https://manage.kontent.ai/v2/projects/<YOUR_ENVIRONMENT_ID>/items/external-id/ext-cafe-brno/variants/codename/en-US \
  --header 'authorization: Bearer <YOUR_MANAGEMENT_API_KEY>' \
  --header 'content-type: application/json' \
  --data '
  {
    "elements": [
      {
        "element": {
          "codename": "street"
        },
        "value": "Nove Sady 25"
      },
      {
        "element": {
          "codename": "city"
        },
        "value": "Brno"
      },
      {
        "element": {
          "codename": "country"
        },
        "value": "Czech Republic"
      },
      {
        "element": {
          "codename": "state"
        },
        "value": "Jihomoravsky kraj"
      },
      {
        "element": {
          "codename": "zip_code"
        },
        "value": "60200"
      },
      {
        "element": {
          "codename": "phone"
        },
        "value": "+420 555 555 555"
      },
      {
        "element": {
          "codename": "email"
        },
        "value": "brnocafe@kontent.ai"
      }
    ]
  }'
    • Content model
    • Content items
    • Linked content
    • Assets
    • Rich text
  • 1. Define a content type for the content item
  • 2. Import content to a content item