MockCity API Reference

Spawn a new cloud worker

POST /v1/workers
Spawns a new cloud worker and loads the PSD from the given psd.url. Each worker can load one PSD and you can have hundreds of concurrent workers with the same or different PSDs. Workers go to sleep automatically after a period of inactivity configurable with the timeout parameter. To awaken a worker and resume where you left off, simply interact with it via any of the API endpoints. Workers are ephemeral and their id should not be stored in persistent storage. 72 hours after a worker is first spawned its state is lost.
Body parameters
psd.name string required
To speed up worker spawn times and reduce bandwidth costs we cache worker PSDs. PSDs are automatically deleted after 3 days of inactivity. When loading the same PSD make sure to use the same name so that it can be retrieved from cache. If you make changes to your PSD, make sure to use a different name so that the old version is not retrieved from cache.
psd.url string required
URL used to load the PSD. File must be a PSD or a ZIP containing a PSD. Unless your PSD files are intentionally public facing, we suggest storing them with an object storage provider that supports presigned URLs. We suggest Cloudflare R2 because egress is free.
timeout number default: 60
Number of seconds of inactivity before worker sleeps automatically.
Returns
id string
Unique worker ID.
psd.id string
The PSD inherits the ID of the worker that loads it into cache.
psd.name string
To speed up worker spawn times and reduce bandwidth costs we cache worker PSDs. PSDs are automatically deleted after 3 days of inactivity. When loading the same PSD make sure to use the same name so that it can be retrieved from cache. If you make changes to your PSD, make sure to use a different name so that the old version is not retrieved from cache.
psd.url string
URL used to load the PSD. File must be a PSD or a ZIP containing a PSD. Unless your PSD files are intentionally public facing, we suggest storing them with an object storage provider that supports presigned URLs. We suggest Cloudflare R2 because egress is free.
psd.width number
Width in pixels of PSD document
psd.height number
Height in pixels of PSD document
Sample Request
const data = {
	"psd": {
		"name": "studio-model-tshirt-v1",
		"url": "https://mockups.printondemand.tools/pexels-mart-production-9558724.zip"
	},
	"timeout": 60
}

fetch(`https://api.mockcity.com/v1/workers`, {
	method: 'POST',
	body: JSON.stringify(data),
	headers: {
		'Content-Type': 'application/json',
		Authorization: `Bearer ${API_KEY}`
	}
}).then((r) => r.json())
Sample Response
{
	"id": "59128b48-fef2-4ed5-908d-d621cdbb0840",
	"psd": {
		"id": "59128b48-fef2-4ed5-908d-d621cdbb0840",
		"name": "studio-model-tshirt-v1",
		"url": "https://mockups.printondemand.tools/pexels-mart-production-9558724.zip",
		"width": 1920,
		"height": 1920
	},
	"timeout": 60
}

Sleep a worker

DELETE /v1/workers/{workerId}
Sleeps the worker with the given workerId. To awaken a worker and resume where you left off, simply interact with it via any of the API endpoints. 72 hours after a worker is first spawned its state is lost. Workers are ephemeral by nature and their ids should not be stored in persistent storage such as a database.
Sample Request
fetch(`https://api.mockcity.com/v1/workers/${workerId}`, {
	method: 'DELETE',
	headers: {
		Authorization: `Bearer ${API_KEY}`
	}
})

List all SmartObjects

GET /v1/workers/{workerId}/smartobjects
Returns all the SmartObjects in the PSD as a tree. Each SmartObject has a children property with nested SmartObjects.
Returns
[number]id string
String ID for the SmartObject. The id is a deterministic and based on the the position of the SmartObject layer in the PSD.
[number]parentId string | null
String ID of parent SmartObject. null if the SmartObject is not nested in another SmartObject's document and is instead found the main PSD document.
[number]name string
Name of SmartObject document.
[number]width number
Width in pixels of SmartObject document.
[number]height number
Height in pixels of SmartObject document.
[number]imageParams number
Height in pixels of SmartObject document.
[number]bgColor string
The SmartObject's background color.
[number]imageParams.anchor.x number
Sets the x origin point of the image. The default is 0.5, the centre of the image.
[number]imageParams.anchor.y number
Sets the y origin point of the image. The default is 0.5, the centre of the image.
[number]imageParams.fit string
Valid values are inside, outside, width and height. Describes how the image should fit the box defined by imageParams.width and imageParams.height. Loosely based on Sharp's resize fit option. Tip: If you want to cover the entire SmartObject with your image, use fit outside and make sure to keep the image centered and imageParams.width and imageParams.height set to 1.
[number]imageParams.width number
Defines the width as a percentage of the SmartObject's available width. Example: For a SmartObject document with a width of 500px and a imageParams.width value of 0.5: 500px × 0.5 = 250px
[number]imageParams.height number
Defines the height as a percentage of the SmartObject's available height. Example: For a SmartObject document with a height of 400px and a imageParams.height value of 0.5: 400px × 0.5 = 200px
[number]imageParams.x number
Defines the x position as a percentage of the SmartObject's available width. The image is positioned relative to the SmartObject's top left corner. Refer to the example for imageParams.width.
[number]imageParams.y number
Defines the y position as a percentage of the SmartObject's available height. The image is positioned relative to the SmartObject's top left corner. Refer to the example for imageParams.height.
[number]imageParams.opacity number
Defines the image's opacity.
[number]children array
Array of SmartObjects that appear in this SmartObject's document. Each SmartObject in this array has its own children array, resulting in a tree of SmartObjects.
Sample Request
fetch(`https://api.mockcity.com/v1/workers/${workerId}/smartobjects`, {
	method: 'GET',
	headers: {
		Authorization: `Bearer ${API_KEY}`
	}
}).then((r) => r.json())
Sample Response
[
	{
		"id": "0",
		"parentId": null,
		"name": "Layer 1.psd",
		"width": 1269,
		"height": 1514,
		"bgColor": "#d1d5db",
		"imageParams": {
			"anchor": {
				"x": 0,
				"y": 0
			},
			"fit": "outside",
			"height": 1,
			"width": 1,
			"x": 0,
			"y": 0,
			"opacity": 1,
			"rotation": 0
		},
		"children": [
			{
				"id": "1",
				"parentId": "0",
				"name": "Nested Layer 1.psd",
				"width": 500,
				"height": 500,
				"bgColor": "transparent",
				"imageParams": {
					"anchor": {
						"x": 0.5,
						"y": 0.5
					},
					"fit": "inside",
					"height": 1,
					"width": 1,
					"x": 0.5,
					"y": 0.5,
					"opacity": 1,
					"rotation": 0
				},
				"children": []
			}
		]
	}
]

Retrieve a SmartObject

GET /v1/workers/{workerId}/smartobjects/{smartObjectId}
Retrieves the SmartObject with the given smartObjectId. Nested SmartObjects can be accessed through the children property.
URL parameters
workerId string required
A unique ID used to reference the cloud worker.
smartObjectId string required
A string ID used to reference a SmartObject in the PSD.
Returns
id string
String ID for the SmartObject. The id is a deterministic and based on the the position of the SmartObject layer in the PSD.
parentId string | null
String ID of parent SmartObject. null if the SmartObject is not nested in another SmartObject's document and is instead found the main PSD document.
name string
Name of SmartObject document.
width number
Width in pixels of SmartObject document.
height number
Height in pixels of SmartObject document.
imageParams number
Height in pixels of SmartObject document.
bgColor string
The SmartObject's background color.
imageParams.anchor.x number
Sets the x origin point of the image. The default is 0.5, the centre of the image.
imageParams.anchor.y number
Sets the y origin point of the image. The default is 0.5, the centre of the image.
imageParams.fit string
Valid values are inside, outside, width and height. Describes how the image should fit the box defined by imageParams.width and imageParams.height. Loosely based on Sharp's resize fit option. Tip: If you want to cover the entire SmartObject with your image, use fit outside and make sure to keep the image centered and imageParams.width and imageParams.height set to 1.
imageParams.width number
Defines the width as a percentage of the SmartObject's available width. Example: For a SmartObject document with a width of 500px and a imageParams.width value of 0.5: 500px × 0.5 = 250px
imageParams.height number
Defines the height as a percentage of the SmartObject's available height. Example: For a SmartObject document with a height of 400px and a imageParams.height value of 0.5: 400px × 0.5 = 200px
imageParams.x number
Defines the x position as a percentage of the SmartObject's available width. The image is positioned relative to the SmartObject's top left corner. Refer to the example for imageParams.width.
imageParams.y number
Defines the y position as a percentage of the SmartObject's available height. The image is positioned relative to the SmartObject's top left corner. Refer to the example for imageParams.height.
imageParams.opacity number
Defines the image's opacity.
children array
Array of SmartObjects that appear in this SmartObject's document. Each SmartObject in this array has its own children array, resulting in a tree of SmartObjects.
Sample Request
fetch(`https://api.mockcity.com/v1/workers/${workerId}/smartobjects/${smartObjectId}`, {
	method: 'GET',
	headers: {
		Authorization: `Bearer ${API_KEY}`
	}
}).then((r) => r.json())
Sample Response
{
	"id": "0",
	"parentId": null,
	"name": "Layer 1.psd",
	"width": 1269,
	"height": 1514,
	"bgColor": "#d1d5db",
	"imageParams": {
		"anchor": {
			"x": 0,
			"y": 0
		},
		"fit": "outside",
		"height": 1,
		"width": 1,
		"x": 0,
		"y": 0,
		"opacity": 1,
		"rotation": 0
	},
	"children": [
		{
			"id": "1",
			"parentId": "0",
			"name": "Nested Layer 1.psd",
			"width": 500,
			"height": 500,
			"bgColor": "transparent",
			"imageParams": {
				"anchor": {
					"x": 0.5,
					"y": 0.5
				},
				"fit": "inside",
				"height": 1,
				"width": 1,
				"x": 0.5,
				"y": 0.5,
				"opacity": 1,
				"rotation": 0
			},
			"children": []
		}
	]
}

Update SmartObject parameters

PATCH /v1/workers/{workerId}/smartobjects/{smartObjectId}
Modifies the SmartObject parameters including backgroud color and image parameters like size and position.
URL parameters
workerId string required
A unique ID used to reference the cloud worker.
smartObjectId string required
A string ID used to reference a SmartObject in the PSD.
Body parameters
bgColor string default: transparent
The SmartObject's background color.
imageParams.anchor.x number default: 0.5
Sets the x origin point of the image. The default is 0.5, the centre of the image.
imageParams.anchor.y number default: 0.5
Sets the y origin point of the image. The default is 0.5, the centre of the image.
imageParams.fit string default: inside
Valid values are inside, outside, width and height. Describes how the image should fit the box defined by imageParams.width and imageParams.height. Loosely based on Sharp's resize fit option. Tip: If you want to cover the entire SmartObject with your image, use fit outside and make sure to keep the image centered and imageParams.width and imageParams.height set to 1.
imageParams.width number default: 1
Defines the width as a percentage of the SmartObject's available width. Example: For a SmartObject document with a width of 500px and a imageParams.width value of 0.5: 500px × 0.5 = 250px
imageParams.height number default: 1
Defines the height as a percentage of the SmartObject's available height. Example: For a SmartObject document with a height of 400px and a imageParams.height value of 0.5: 400px × 0.5 = 200px
imageParams.x number default: 0.5
Defines the x position as a percentage of the SmartObject's available width. The image is positioned relative to the SmartObject's top left corner. Refer to the example for imageParams.width.
imageParams.y number default: 0.5
Defines the y position as a percentage of the SmartObject's available height. The image is positioned relative to the SmartObject's top left corner. Refer to the example for imageParams.height.
imageParams.opacity number default: 1
Defines the image's opacity.
Returns
id string
String ID for the SmartObject. The id is a deterministic and based on the the position of the SmartObject layer in the PSD.
parentId string | null
String ID of parent SmartObject. null if the SmartObject is not nested in another SmartObject's document and is instead found the main PSD document.
name string
Name of SmartObject document.
width number
Width in pixels of SmartObject document.
height number
Height in pixels of SmartObject document.
imageParams number
Height in pixels of SmartObject document.
bgColor string
The SmartObject's background color.
imageParams.anchor.x number
Sets the x origin point of the image. The default is 0.5, the centre of the image.
imageParams.anchor.y number
Sets the y origin point of the image. The default is 0.5, the centre of the image.
imageParams.fit string
Valid values are inside, outside, width and height. Describes how the image should fit the box defined by imageParams.width and imageParams.height. Loosely based on Sharp's resize fit option. Tip: If you want to cover the entire SmartObject with your image, use fit outside and make sure to keep the image centered and imageParams.width and imageParams.height set to 1.
imageParams.width number
Defines the width as a percentage of the SmartObject's available width. Example: For a SmartObject document with a width of 500px and a imageParams.width value of 0.5: 500px × 0.5 = 250px
imageParams.height number
Defines the height as a percentage of the SmartObject's available height. Example: For a SmartObject document with a height of 400px and a imageParams.height value of 0.5: 400px × 0.5 = 200px
imageParams.x number
Defines the x position as a percentage of the SmartObject's available width. The image is positioned relative to the SmartObject's top left corner. Refer to the example for imageParams.width.
imageParams.y number
Defines the y position as a percentage of the SmartObject's available height. The image is positioned relative to the SmartObject's top left corner. Refer to the example for imageParams.height.
imageParams.opacity number
Defines the image's opacity.
children array
Array of SmartObjects that appear in this SmartObject's document. Each SmartObject in this array has its own children array, resulting in a tree of SmartObjects.
Sample Request
const data = {
	bgColor: '#d1d5db',
	// make image cover entire SmartObject document
	imageParams: {
		// set top left of image as its origin
		anchor: {
			x: 0,
			y: 0
		},
		fit: 'outside', // refer to Sharp's resize 'fit' option to understand how 'outside' works
		width: 1, // 100% of SmartObject width
		height: 1, // 100% of SmartObject height
		// position image at top left corner of SmartObject document
		x: 0, // 0% of SmartObject width
		y: 0 // 0% of SmartObject height
	}
}

fetch(`https://api.mockcity.com/v1/workers/${workerId}/smartobjects/${smartObjectId}`, {
	method: 'PATCH',
	body: JSON.stringify(data),
	headers: {
		'Content-Type': 'application/json',
		Authorization: `Bearer ${API_KEY}`
	}
}).then((r) => r.json())
Sample Response
{
	"id": "0",
	"parentId": null,
	"name": "Layer 1.psd",
	"width": 1269,
	"height": 1514,
	"bgColor": "#d1d5db",
	"imageParams": {
		"anchor": {
			"x": 0,
			"y": 0
		},
		"fit": "outside",
		"height": 1,
		"width": 1,
		"x": 0,
		"y": 0,
		"opacity": 1,
		"rotation": 0
	},
	"children": [
		{
			"id": "1",
			"parentId": "0",
			"name": "Nested Layer 1.psd",
			"width": 500,
			"height": 500,
			"bgColor": "transparent",
			"imageParams": {
				"anchor": {
					"x": 0.5,
					"y": 0.5
				},
				"fit": "inside",
				"height": 1,
				"width": 1,
				"x": 0.5,
				"y": 0.5,
				"opacity": 1,
				"rotation": 0
			},
			"children": []
		}
	]
}

Place an image in a SmartObject

PUT /v1/workers/{workerId}/smartobjects/{smartObjectId}/image
Adds the image as the top-most layer in the SmartObject. If an image was already added using the API, the previous image will be replaced. The image should be provided as an ArrayBuffer on the request body.
URL parameters
workerId string required
A unique ID used to reference the cloud worker.
smartObjectId string required
A string ID used to reference a SmartObject in the PSD.
Body
ArrayBuffer
Sample Request
let imageArrayBuffer

// get image ArrayBuffer from canvas
let canvas // assign and draw to canvas
imageArrayBuffer = await canvas.toBlob((blob) => blob.arrayBuffer())

// or get image ArrayBuffer from URL
imageArrayBuffer = await fetch('https://mockcity.com/examples/peachy.png').then((res) =>
	res.arrayBuffer()
)

const body = imageArrayBuffer

fetch(`https://api.mockcity.com/v1/workers/${workerId}/smartobjects/${smartObjectId}/image`, {
	method: 'PUT',
	body: body,
	headers: {
		'Content-Type': 'application/octet-stream',
		Authorization: `Bearer ${API_KEY}`
	}
})

Generate a mockup

POST /v1/workers/{workerId}/mockup
Exports and returns the PSD as an image ArrayBuffer. Image dimensions and format can be manipulated by supplying valid Sharp resize and image output options as a sharp array of { method: methodName, params: methodParams } objects.
Body parameters
sharp[number].method string
Name of Sharp method. The methods currently allowed are resize and image formats webp, jpeg and png.
sharp[number].params array
Tuple of Sharp method parameters. Check the Sharp docs for the parameters allowed for each method.
Returns
ArrayBuffer
Sample Request
const data = {
	sharp: [
		{ method: 'resize', params: [{ width: 512, height: 512, fit: 'outside' }] },
		{ method: 'webp', params: [{ quality: 90 }] }
	]
}

fetch(`https://api.mockcity.com/v1/workers/${workerId}/mockup`, {
	method: 'POST',
	body: JSON.stringify(data),
	headers: {
		'Content-Type': 'application/json',
		Authorization: `Bearer ${API_KEY}`
	}
}).then((r) => r.arrayBuffer())