MockCity REST 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:

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. Values from 0 to 1.

[number]imageParams.rotation number

Defines the image's rotation in degrees.

[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. Values from 0 to 1.

imageParams.rotation number

Defines the image's rotation in degrees.

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:

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:

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:

Defines the image's opacity. Values from 0 to 1.

imageParams.rotation number

Defines the image's rotation in degrees.

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. Values from 0 to 1.

imageParams.rotation number

Defines the image's rotation in degrees.

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())

MockCity API Reference

Spawn a new cloud worker

Sleep a worker

List all SmartObjects

Retrieve a SmartObject

Update SmartObject parameters

Place an image in a SmartObject

Generate a mockup