Create an image item associated with an entity

Last published: 2025-11-30

Concepts covered in this guide

  • Companies endpoint to list the companies to update the content
  • Search for locating the content entity which we will add the image to
  • Entity endpoint for creating our content entity to hold the page data.
    • Entity representation for the data associated with the entity.
    • Image Item used to create the image item representation and metadata.
    • Image item file endpoint used to post image file data associated with the image representation.

This guide shows end to end how to create an image associated with an entity. We will walk through locating the company we are working with, finding the entity to associate the image with using search, then adding an image item representation and it's file data. Images will then be served from CDN edge points.

Step 1: Orientation, finding our company URN

Lets start off with the basics and fetch the companies to locate our content:

curl -X GET -H "Authorization: Bearer $TOKEN" https://api.baack.co/n/v1/companies
{
 "companies": [
   {
     "urn": "2ad747ab-51a9-11f0-b99c-d8bbc160a611",
     "url": "/n/v1/company/2ad747ab-51a9-11f0-b99c-d8bbc160a611"
   }
 ]
}

Lets search for the entity we will add our image to by creating a search:

curl -X POST -H "Authorization: Bearer $TOKEN" https://api.baack.co/n/v1/search --data '{"owner":{"urn":"2ad747ab-51a9-11f0-b99c-d8bbc160a611"},"includeScopes":["ENTITY"]}'

{
 "urn": "1c05a7a9-0661-4dd0-a710-0378b34a961c",
 "url": "/n/v1/search/1c05a7a9-0661-4dd0-a710-0378b34a961c",
 "owner": {
   "urn": "2ad747ab-51a9-11f0-b99c-d8bbc160a611",
   "url": "/n/v1/company/2ad747ab-51a9-11f0-b99c-d8bbc160a611"
 },
 "createdTimestamp": "2025-11-30T09:50:48.725",
 "updatedTimestamp": "2025-11-30T09:50:48.725",
 "status": "PENDING",
 "order": "UNDEFINED",
 "includeScopes": [
   "ENTITY"
 ]
}

curl -X GET -H "Authorization: Bearer $TOKEN" https://api.baack.co/n/v1/search/1c05a7a9-0661-4dd0-a710-0378b34a961c

{
 "urn": "1c05a7a9-0661-4dd0-a710-0378b34a961c",
 "url": "/n/v1/search/1c05a7a9-0661-4dd0-a710-0378b34a961c",
 "owner": {
   "urn": "2ad747ab-51a9-11f0-b99c-d8bbc160a611",
   "url": "/n/v1/company/2ad747ab-51a9-11f0-b99c-d8bbc160a611"
 },
 "createdTimestamp": "2025-11-30T09:50:48.725",
 "updatedTimestamp": "2025-11-30T09:50:48.971",
 "status": "FULL_RESULT",
 "order": "UNDEFINED",
 "items": [
   {
     "urn": "d6d64928-5c9b-4403-b341-db40abfd1313",
     "url": "/n/v1/entity/d6d64928-5c9b-4403-b341-db40abfd1313",
     "sortOrder": 0,
     "type": "ENTITY",
     "name": "/2ad747ab-51a9-11f0-b99c-d8bbc160a611/content/blog/hubspot-xero-importer"
   }
 ],
 "includeScopes": [
   "ENTITY"
 ]
}

Step 2: Create an image item representation

When creating an image the first step is to create it’s representation.

curl -X POST -H "Authorization: Bearer $TOKEN" https://api.baack.co/n/v1/imageitem --data '{"entity":{"urn":"d6d64928-5c9b-4403-b341-db40abfd1313"},"sortOrder":0,"name":"banner"}'

{
 "urn": "157146f1-71de-4daf-bed6-88ebf3a24f7d",
 "url": "/n/v1/imageitem/157146f1-71de-4daf-bed6-88ebf3a24f7d",
 "name": "banner",
 "sortOrder": 0,
 "altText": "",
 "src": "",
 "largeSrc": "",
 "mediumSrc": "",
 "entity": {
   "urn": "d6d64928-5c9b-4403-b341-db40abfd1313",
   "url": "/n/v1/entity/d6d64928-5c9b-4403-b341-db40abfd1313"
 }
}

Now that we have a representation of the image metadata we can post the actual file content.

Step 3: Upload file content associated with the image

Using our existing image item representation we can now associate a file with the image item:

curl -X POST -H "Authorization: Bearer $TOKEN" https://api.baack.co/n/v1/imageitemfile -F imageItemUrn=157146f1-71de-4daf-bed6-88ebf3a24f7d -F imageItemSize=DEFAULT -F "src=@./Xero-to-HubSpot.png"
  
{"urn":"157146f1-71de-4daf-bed6-88ebf3a24f7d","url":"/n/v1/imageitem/157146f1-71de-4daf-bed6-88ebf3a24f7d","name":"banner","sortOrder":0,"altText":"","src":"157146f1-71de-4daf-bed6-88ebf3a24f7d/Xero_to_HubSpot.png","largeSrc":"","medium
Src":"","entity":{"urn":"d6d64928-5c9b-4403-b341-db40abfd1313","url":"/n/v1/entity/d6d64928-5c9b-4403-b341-db40abfd1313"}}

Let’s confirm the image details on the associated image item:

curl -X GET -H "Authorization: Bearer $TOKEN" https://api.baack.co/n/v1/imageitem/157146f1-71de-4daf-bed6-88ebf3a24f7d

{
 "urn": "157146f1-71de-4daf-bed6-88ebf3a24f7d",
 "url": "/n/v1/imageitem/157146f1-71de-4daf-bed6-88ebf3a24f7d",
 "name": "banner",
 "sortOrder": 0,
 "altText": "",
 "src": "157146f1-71de-4daf-bed6-88ebf3a24f7d/Xero_to_HubSpot.png",
 "largeSrc": "",
 "mediumSrc": "",
 "entity": {
   "urn": "d6d64928-5c9b-4403-b341-db40abfd1313",
   "url": "/n/v1/entity/d6d64928-5c9b-4403-b341-db40abfd1313"
 }
}

From here the domain setup and personalisation for your account will determine where the content will be located.

<your static domain>/157146f1-71de-4daf-bed6-88ebf3a24f7d/Xero_to_HubSpot.png now serves the image.