Folders API — save ad creatives to MTWSPY folders

GET, POST, PATCH, DELETE /folders — list your folders, create, rename and delete them, add and remove creatives.

These are the same folders as in the Folders section of the dashboard: what you create through the API shows up on the website right away, and the other way round.

Method	Path	Purpose
`GET`	`/folders`	List your folders
`POST`	`/folders`	Create a folder
`GET`	`/folders/{id}`	A folder and the creative ids in it
`PATCH`	`/folders/{id}`	Rename, change color or icon
`DELETE`	`/folders/{id}`	Delete a folder
`POST`	`/folders/{id}/creatives`	Add a creative
`DELETE`	`/folders/{id}/creatives/{creative_id}`	Remove a creative

Your folders only, free

The API sees and changes only the key owner's folders. Teammates' team folders aren't available; someone else's folder returns 404, the same as one that doesn't exist. Folders don't spend views.

POST and PATCH take a JSON body with Content-Type: application/json (form-urlencoded works too).

List folders

curl https://app.mtwspy.com/public/v1/folders \
  -H "Authorization: Bearer mtw_live_your_key"

{
  "data": [
    {
      "id": "6f1c2a90-3b1e-4c8d-9a52-1e0f7b6c4d21",
      "name": "MX nutra hooks",
      "color": "#3b82f6",
      "icon": "🎯",
      "privacy": "private",
      "creatives_count": 12,
      "created_at": "2026-11-09T12:00:00+03:00"
    }
  ],
  "meta": { "charged": 0 }
}

Field	Description
`id`	Folder uuid — goes into `/folders/{id}` paths
`privacy`	`private`, `public` (by link) or `team` (visible to the team). Only changeable in the dashboard
`creatives_count`	Number of creatives in the folder

Create a folder

curl -X POST https://app.mtwspy.com/public/v1/folders \
  -H "Authorization: Bearer mtw_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "MX nutra hooks", "color": "#3b82f6", "icon": "🎯"}'

Field	Values
`name`	Required. 1–50 characters, no HTML
`color`	`#22c55e` (default), `#3b82f6`, `#f59e0b`, `#ef4444`, `#8b5cf6`, `#ec4899`
`icon`	`📁` (default), `🎯`, `⭐`, `🚀`, `💼`, `📊`

New folders are private. The response is the folder object. Up to 100 folders per user.

A folder and its contents

curl https://app.mtwspy.com/public/v1/folders/6f1c2a90-3b1e-4c8d-9a52-1e0f7b6c4d21 \
  -H "Authorization: Bearer mtw_live_your_key"

Returns the folder object plus creative_ids: creative ids, most recently added first (up to 1000). Creative cards aren't included — open them with /creatives/{id}.

{
  "data": {
    "id": "6f1c2a90-3b1e-4c8d-9a52-1e0f7b6c4d21",
    "name": "MX nutra hooks",
    "...": "...",
    "creative_ids": [48211773, 48190455]
  }
}

Rename

curl -X PATCH https://app.mtwspy.com/public/v1/folders/6f1c2a90-3b1e-4c8d-9a52-1e0f7b6c4d21 \
  -H "Authorization: Bearer mtw_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "MX nutra — top"}'

Send any of name, color, icon; the rest stay as they are.

Delete a folder

curl -X DELETE https://app.mtwspy.com/public/v1/folders/6f1c2a90-3b1e-4c8d-9a52-1e0f7b6c4d21 \
  -H "Authorization: Bearer mtw_live_your_key"

Deletes the folder with its contents and tags. The creatives stay in the database. This can't be undone.

{ "data": { "id": "6f1c2a90-3b1e-4c8d-9a52-1e0f7b6c4d21", "deleted": true } }

Add a creative to a folder

curl -X POST https://app.mtwspy.com/public/v1/folders/6f1c2a90-3b1e-4c8d-9a52-1e0f7b6c4d21/creatives \
  -H "Authorization: Bearer mtw_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"creative_id": 48211773}'

{ "data": { "folder_id": "6f1c2a90-3b1e-4c8d-9a52-1e0f7b6c4d21", "creative_id": 48211773, "added": true } }

You can add creatives your account received from /creatives or /creatives/{id} in the last 7 days. A folder holds up to 1000 creatives added through the API.

Remove a creative from a folder

curl -X DELETE https://app.mtwspy.com/public/v1/folders/6f1c2a90-3b1e-4c8d-9a52-1e0f7b6c4d21/creatives/48211773 \
  -H "Authorization: Bearer mtw_live_your_key"

{ "data": { "folder_id": "6f1c2a90-3b1e-4c8d-9a52-1e0f7b6c4d21", "creative_id": 48211773, "removed": true } }

Query forms

If your client prefers passing ids as parameters:

Path	Query form
`/folders/{id}`	`/folder?id={id}`
`/folders/{id}/creatives`	`/folder_creatives?folder_id={id}`
`/folders/{id}/creatives/{creative_id}`	`/folder_creatives?folder_id={id}&creative_id={creative_id}`

Limits

Creating, changing and deleting folders and changing their contents count together: up to 30 per minute and 500 per day per account. Reads fall under the key's general rate limit.

Errors

`code`	HTTP	When
`invalid_parameter`	422	Invalid folder uuid, creative id, name, color or icon
`invalid_body`	400	A body sent with `Content-Type: application/json` isn't a JSON object
`not_found`	404	The folder doesn't exist or isn't yours; the creative isn't in the database or the folder
`folder_limit`	409	You already have 100 folders
`already_in_folder`	409	The creative is already in the folder
`folder_full`	409	The folder has 1000 creatives
`creative_not_served`	403	The creative was never returned to your account through the API
`method_not_allowed`	405	The path doesn't support this method
`rate_limited`	429	More than 30 changes per minute, or the general rate limit
`daily_limit_reached`	429	500 changes in a day

Folders

On this page