Supercharge your ads workflow with the Swipekit API
Swipekit API
Welcome to the Swipekit API. If you're just getting started, you're in the right place. Quick start: 1. Generate an API key in Swipekit workspace settings. 2. Add the header: Authorization: Bearer sk_xxxxxxxxxxxxxxxx 3. Call /api/v1 endpoints. Response shape: public endpoints return an object with a data field, and data is an array. Paginated endpoints also return a pagination object. Workspace access: use the API with trial or active paid workspaces. Deactivated workspaces are blocked. Rate limits: up to 120 requests/min before delay, and a hard cap at 200 requests/min.
Base URL: https://api.swipekit.app
Asset base URL: https://file.swipekit.app
/api/v1/ad/{id}Get one ad by id
Get one ad by id
Fetch a specific saved ad by id from your workspace. Authentication: - Header: `Authorization: Bearer sk_<16_lowercase_alnum>` Workspace requirements: - Use this API with trial or active paid workspaces. - Deactivated workspaces receive `403`. Rate limits: - Up to 120 requests/min before delay. - Hard cap at 200 requests/min (`429`).
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
id | path | Yes | string | Ad id. |
Request Body
No request body.
Responses
| Status | Description | Content types | Schema |
|---|---|---|---|
200 | Ad returned successfully. | application/json | object(1 fields) |
401 | Missing or invalid API key. | application/json | object(1 fields) |
403 | Workspace is deactivated. | application/json | object(1 fields) |
429 | Rate limit exceeded. | application/json | object(1 fields) |
500 | Internal server error. | application/json | object(1 fields) |
Response 200 (application/json)
{
"data": [
{
"id": "9f24b6d1-3e82-43bf-bf27-7f6a9b3e7a10",
"blockId": "9f24b6d1-3e82-43bf-bf27-7f6a9b3e7a10",
"userId": 91,
"createdAt": "2026-03-10T03:42:15.220Z",
"updatedAt": "2026-03-10T03:42:15.220Z",
"block": {
"id": "9f24b6d1-3e82-43bf-bf27-7f6a9b3e7a10",
"title": "Coastal Bay Retreat",
"type": "facebook",
"assetType": "image",
"status": "INACTIVE",
"metaId": "590012345678900",
"assets": [
{
"type": "image",
"ratio": 0.6665,
"assetPath": "fb-590012345678900-a1b2c3d4-1.jpeg"
}
],
"meta": {
"cta": "MESSAGE_PAGE",
"isEuAd": false,
"displayFormat": "image"
},
"createdAt": "2026-03-10T03:42:15.211Z",
"brand": {
"id": 30110,
"name": "Coastal Bay Retreat",
"slug": "coastal-bay-retreat",
"logo": "coastal-bay-retreat-avatar.jpeg"
}
}
}
]
}
Response 401 (application/json)
{
"error": "Missing Bearer token"
}
Response 403 (application/json)
{
"error": "Workspace is deactivated. Please select a plan to use the API."
}
Response 429 (application/json)
{
"error": "Rate limit exceeded"
}
Response 500 (application/json)
{
"error": "Internal server error"
}/api/v1/ai-generationList AI generations
List AI generations
Get AI generations created in your workspace. Authentication: - Header: `Authorization: Bearer sk_<16_lowercase_alnum>` Workspace requirements: - Use this API with trial or active paid workspaces. - Deactivated workspaces receive `403`. Rate limits: - Up to 120 requests/min before delay. - Hard cap at 200 requests/min (`429`).
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
page | query | No | integer | Page number (default 1). Page size is fixed at 100. |
Request Body
No request body.
Responses
| Status | Description | Content types | Schema |
|---|---|---|---|
200 | AI generations returned successfully. | application/json | object(2 fields) |
401 | Missing or invalid API key. | application/json | object(1 fields) |
403 | Workspace is deactivated. | application/json | object(1 fields) |
429 | Rate limit exceeded. | application/json | object(1 fields) |
500 | Internal server error. | application/json | object(1 fields) |
Response 200 (application/json)
{
"data": [
{
"id": 974,
"sourceAdId": "9f24b6d1-3e82-43bf-bf27-7f6a9b3e7a10",
"type": "VIDEOTOSTORYBOARD",
"briefId": null,
"form": {
"isTrusted": true
},
"result": [
{
"type": "Clip",
"description": "Close-up of hands placing a tracker on a food item at a beach.",
"details": [
"Close-up shot",
"Ocean and sand in background",
"Natural sunlight"
]
},
{
"type": "Screen Recording",
"description": "Phone map view showing movement from sea to land.",
"details": [
"Map zoom effect",
"Location pin animation"
]
},
{
"type": "Graphic",
"description": "Contact card with property details and agent info.",
"details": [
"Address and name",
"Brand logo lockup"
]
}
],
"status": "DONE",
"creditsUsed": 4,
"workspaceId": 412,
"userId": 91,
"createdAt": "2026-03-05T01:00:10.993Z"
},
{
"id": 963,
"sourceAdId": "9f24b6d1-3e82-43bf-bf27-7f6a9b3e7a10",
"type": "VIDEOTOSTORYBOARD",
"briefId": null,
"form": {
"isTrusted": true
},
"result": null,
"status": "FAILED",
"creditsUsed": 0,
"workspaceId": 412,
"userId": 91,
"createdAt": "2026-03-04T08:20:11.762Z"
},
{
"id": 944,
"sourceAdId": "ab4f7e00-7f8c-4a8f-a84d-8d20f0a877ab",
"type": "COPY",
"briefId": 3,
"form": {
"isTrusted": true
},
"result": {
"copy": "We launched our ad library in days and now our team can search ads, tags, and transcripts in one place."
},
"status": "DONE",
"creditsUsed": 1,
"workspaceId": 412,
"userId": 91,
"createdAt": "2025-10-17T08:21:08.274Z"
}
],
"pagination": {
"page": 1,
"pageSize": 100,
"count": 8,
"total": 8,
"totalPages": 1
}
}
Response 401 (application/json)
{
"error": "Missing Bearer token"
}
Response 403 (application/json)
{
"error": "Workspace is deactivated. Please select a plan to use the API."
}
Response 429 (application/json)
{
"error": "Rate limit exceeded"
}
Response 500 (application/json)
{
"error": "Internal server error"
}/api/v1/boardsList boards
List boards
Get boards in your workspace. This is useful for building simple UI dropdowns and board pickers. Authentication: - Header: `Authorization: Bearer sk_<16_lowercase_alnum>` Workspace requirements: - Use this API with trial or active paid workspaces. - Deactivated workspaces receive `403`. Rate limits: - Up to 120 requests/min before delay. - Hard cap at 200 requests/min (`429`).
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
page | query | No | integer | Page number (default 1). Page size is fixed at 100. |
Request Body
No request body.
Responses
| Status | Description | Content types | Schema |
|---|---|---|---|
200 | Boards returned successfully. | application/json | object(2 fields) |
401 | Missing or invalid API key. | application/json | object(1 fields) |
403 | Workspace is deactivated. | application/json | object(1 fields) |
429 | Rate limit exceeded. | application/json | object(1 fields) |
500 | Internal server error. | application/json | object(1 fields) |
Response 200 (application/json)
{
"data": [
{
"id": 901,
"name": "Winning Concepts",
"slug": "winning-concepts-2a4f71-board",
"description": null,
"public": true,
"shareable": false,
"order": 0,
"folderId": 400,
"createdAt": "2025-08-11T06:46:25.794Z",
"updatedAt": "2025-09-01T09:13:07.801Z"
},
{
"id": 905,
"name": "Secret Competitor Notes",
"slug": "secret-competitor-notes-8f92d1-board",
"description": null,
"public": false,
"shareable": false,
"order": 7,
"folderId": 400,
"createdAt": "2025-03-19T01:33:25.420Z",
"updatedAt": "2025-09-01T08:25:52.882Z"
},
{
"id": 909,
"name": "Static Ad Vault",
"slug": "static-ad-vault-31cc8a-board",
"description": "High-performing static ads from Facebook and Instagram.",
"public": true,
"shareable": false,
"order": 4,
"folderId": 400,
"createdAt": "2024-07-12T06:54:25.361Z",
"updatedAt": "2025-09-01T08:25:52.882Z"
}
],
"pagination": {
"page": 1,
"pageSize": 100,
"count": 22,
"total": 22,
"totalPages": 1
}
}
Response 401 (application/json)
{
"error": "Missing Bearer token"
}
Response 403 (application/json)
{
"error": "Workspace is deactivated. Please select a plan to use the API."
}
Response 429 (application/json)
{
"error": "Rate limit exceeded"
}
Response 500 (application/json)
{
"error": "Internal server error"
}/api/v1/foldersList folders
List folders
Get folders in your workspace. Authentication: - Header: `Authorization: Bearer sk_<16_lowercase_alnum>` Workspace requirements: - Use this API with trial or active paid workspaces. - Deactivated workspaces receive `403`. Rate limits: - Up to 120 requests/min before delay. - Hard cap at 200 requests/min (`429`).
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
page | query | No | integer | Page number (default 1). Page size is fixed at 100. |
Request Body
No request body.
Responses
| Status | Description | Content types | Schema |
|---|---|---|---|
200 | Folders returned successfully. | application/json | object(2 fields) |
401 | Missing or invalid API key. | application/json | object(1 fields) |
403 | Workspace is deactivated. | application/json | object(1 fields) |
429 | Rate limit exceeded. | application/json | object(1 fields) |
500 | Internal server error. | application/json | object(1 fields) |
Response 200 (application/json)
{
"data": [
{
"id": 47931,
"name": "Seasonal Concepts",
"default": false,
"hidden": false,
"order": 2,
"createdAt": "2025-09-30T01:25:17.559Z"
},
{
"id": 400,
"name": "Default",
"default": true,
"hidden": false,
"order": 1,
"createdAt": "2025-04-26T06:53:28.772Z"
}
],
"pagination": {
"page": 1,
"pageSize": 100,
"count": 2,
"total": 2,
"totalPages": 1
}
}
Response 401 (application/json)
{
"error": "Missing Bearer token"
}
Response 403 (application/json)
{
"error": "Workspace is deactivated. Please select a plan to use the API."
}
Response 429 (application/json)
{
"error": "Rate limit exceeded"
}
Response 500 (application/json)
{
"error": "Internal server error"
}/api/v1/libraryList library ads
List library ads
Get saved ads from your Swipekit library. This endpoint is great for beginners because it supports simple pagination and optional filters. Keep it simple at first: just call it with no filters, then add filters as you need them. Authentication: - Header: `Authorization: Bearer sk_<16_lowercase_alnum>` Workspace requirements: - Use this API with trial or active paid workspaces. - Deactivated workspaces receive `403`. Rate limits: - Up to 120 requests/min before delay. - Hard cap at 200 requests/min (`429`).
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
page | query | No | integer | Page number (default 1). Uses library default page size when take is not supplied. |
query | query | No | string | Search text. |
skip | query | No | integer | Result offset. |
take | query | No | integer | Number of records to return. |
platform | query | No | string | Platform filter. |
mediaType | query | No | string | Media type filter. |
activeAds | query | No | enum(0, 1, 2) | Active ad filter. |
sort | query | No | string | Sort mode. |
tag | query | No | string | Return ads linked to this exact saved tag. |
brands | query | No | array<string> | Brand name filters. Pass as repeated params (`brands=nike&brands=adidas`) or as comma-separated text. |
networks | query | No | array<string> | Network filters (for example `facebook`, `instagram`, `tiktok`). |
categories | query | No | array<string> | Category filters. Uses the same input format as `brands`. |
Request Body
No request body.
Responses
| Status | Description | Content types | Schema |
|---|---|---|---|
200 | Library ads returned successfully. | application/json | object(2 fields) |
401 | Missing or invalid API key. | application/json | object(1 fields) |
403 | Workspace is deactivated. | application/json | object(1 fields) |
429 | Rate limit exceeded. | application/json | object(1 fields) |
500 | Internal server error. | application/json | object(1 fields) |
Response 200 (application/json)
{
"data": [
{
"id": "9f24b6d1-3e82-43bf-bf27-7f6a9b3e7a10",
"workspaceId": 412,
"userId": 91,
"blockId": "9f24b6d1-3e82-43bf-bf27-7f6a9b3e7a10",
"tags": null,
"createdAt": "2026-03-10T03:42:15.220Z",
"block": {
"id": "9f24b6d1-3e82-43bf-bf27-7f6a9b3e7a10",
"title": "Coastal Bay Retreat",
"metaId": "590012345678900",
"type": "facebook",
"tags": [
"Travel"
],
"assets": [
{
"type": "image",
"ratio": 0.6665,
"assetPath": "fb-590012345678900-a1b2c3d4-1.jpeg"
}
],
"source": "https://www.facebook.com/coastalbayretreat/",
"searchable": "Coastal Bay Retreat",
"assetRatio": 1,
"adCopy": "Sunrise walks, ocean views, and family time that actually feels like a holiday.",
"assetType": "image",
"endDate": "2026-03-09T08:00:00.000Z",
"adTitle": "Your next family getaway starts here.",
"categories": [
"Travel"
],
"networks": [
"facebook",
"instagram"
],
"status": "INACTIVE",
"statusCheckAt": "2026-03-11T12:17:20.100Z",
"meta": {
"cta": "MESSAGE_PAGE",
"isEuAd": false,
"displayFormat": "image"
},
"brandId": 30110,
"rating": 1,
"activeDays": 12,
"ctaLink": null,
"createdAt": "2026-03-10T03:42:15.211Z",
"transcriptId": null,
"brand": {
"name": "Coastal Bay Retreat",
"slug": "coastal-bay-retreat",
"logo": "coastal-bay-retreat-avatar.jpeg"
}
},
"boards": []
},
{
"id": "7bde2f10-f8e9-4aa9-9d31-08f40c5d3d66",
"workspaceId": 412,
"userId": 91,
"blockId": "7bde2f10-f8e9-4aa9-9d31-08f40c5d3d66",
"tags": null,
"createdAt": "2026-03-10T03:41:04.805Z",
"block": {
"id": "7bde2f10-f8e9-4aa9-9d31-08f40c5d3d66",
"title": "Sparkle Soda AU",
"metaId": "777001234560111",
"type": "facebook",
"tags": [
"Brand"
],
"assets": [
{
"type": "video",
"cover": {
"type": "image",
"assetPath": "fb-777001234560111-b7c8d9-cover-1.webp"
},
"ratio": null,
"assetPath": "fb-777001234560111-b7c8d9-1-video.mp4"
}
],
"source": "https://www.facebook.com/sparklesodaaustralia/",
"searchable": "Sparkle Soda AU",
"assetRatio": 1,
"adCopy": "When the heat kicks in, turn up the refreshment.",
"assetType": "video",
"endDate": "2026-03-09T08:00:00.000Z",
"adTitle": "Sparkle Summer",
"categories": [
"Brand"
],
"networks": [
"facebook"
],
"status": "INACTIVE",
"statusCheckAt": "2026-03-11T12:19:53.202Z",
"meta": {
"cta": "SHOP_NOW",
"isEuAd": false,
"displayFormat": "video"
},
"brandId": 30111,
"rating": 1,
"activeDays": 64,
"ctaLink": "https://shop.example.com/products/sparkle-soda",
"createdAt": "2026-03-10T03:41:04.799Z",
"transcriptId": null,
"brand": {
"name": "Sparkle Soda AU",
"slug": "sparkle-soda-au",
"logo": "sparkle-soda-au-avatar.jpeg"
}
},
"boards": []
},
{
"id": "5c220aa9-17d0-4cf9-aaf6-2ec1b75eb5e1",
"workspaceId": 412,
"userId": 91,
"blockId": "5c220aa9-17d0-4cf9-aaf6-2ec1b75eb5e1",
"tags": [],
"createdAt": "2026-03-10T03:38:20.019Z",
"block": {
"id": "5c220aa9-17d0-4cf9-aaf6-2ec1b75eb5e1",
"title": "www.instagram.com",
"metaId": "DQ2xyZ8LmN1",
"type": "instagram-feed",
"tags": null,
"assets": [
{
"type": "video",
"cover": {
"type": "image",
"assetPath": "DQ2xyZ8LmN1-0-cover.webp"
},
"ratio": 1.7777,
"assetPath": "DQ2xyZ8LmN1-0-video.mp4"
}
],
"searchable": "www.instagram.com",
"assetRatio": 1.7777,
"adCopy": "A quick storytelling hook that drove high engagement.",
"assetType": "video",
"networks": [
"instagram-feed",
"instagram-reel"
],
"comments": 210,
"likes": 4821,
"views": 145900,
"status": "ACTIVE",
"statusCheckAt": "2026-03-10T03:38:20.010Z",
"meta": {
"advertiser": {
"name": "North Star Studio"
}
},
"brandId": 30112,
"rating": 1,
"activeDays": 0,
"ctaLink": null,
"createdAt": "2026-03-10T03:38:20.010Z",
"transcriptId": null,
"brand": {
"name": "North Star Studio",
"slug": "north-star-studio",
"logo": "north-star-studio-avatar.jpeg"
}
},
"boards": [
901,
905
]
}
],
"pagination": {
"page": 1,
"pageSize": 20,
"count": 20
}
}
Response 401 (application/json)
{
"error": "Missing Bearer token"
}
Response 403 (application/json)
{
"error": "Workspace is deactivated. Please select a plan to use the API."
}
Response 429 (application/json)
{
"error": "Rate limit exceeded"
}
Response 500 (application/json)
{
"error": "Internal server error"
}/api/v1/trackersList trackers
List trackers
Get trackers for your workspace. Each tracker includes its related brand details. Authentication: - Header: `Authorization: Bearer sk_<16_lowercase_alnum>` Workspace requirements: - Use this API with trial or active paid workspaces. - Deactivated workspaces receive `403`. Rate limits: - Up to 120 requests/min before delay. - Hard cap at 200 requests/min (`429`).
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
page | query | No | integer | Page number (default 1). Page size is fixed at 100. |
Request Body
No request body.
Responses
| Status | Description | Content types | Schema |
|---|---|---|---|
200 | Trackers returned successfully. | application/json | object(2 fields) |
401 | Missing or invalid API key. | application/json | object(1 fields) |
403 | Workspace is deactivated. | application/json | object(1 fields) |
429 | Rate limit exceeded. | application/json | object(1 fields) |
500 | Internal server error. | application/json | object(1 fields) |
Response 200 (application/json)
{
"data": [
{
"id": 8101,
"workspaceId": 412,
"brandId": 70001,
"status": "ACTIVE",
"lastCheckedAt": "2026-03-11T09:02:14.431Z",
"createdAt": "2026-01-29T03:11:42.528Z",
"brand": {
"id": 70001,
"name": "Metro One Department Store",
"slug": "metro-one-department-store",
"category": "Shopping Mall",
"logo": "metro-one-department-store-avatar.jpeg",
"fbId": "230746680338335",
"url": null
}
},
{
"id": 8102,
"workspaceId": 412,
"brandId": 70002,
"status": "ACTIVE",
"lastCheckedAt": "2026-03-11T15:42:09.303Z",
"createdAt": "2026-01-29T03:03:12.259Z",
"brand": {
"id": 70002,
"name": "SkinLab Co",
"slug": "skinlab-co",
"category": "Shopping",
"logo": "skinlab-co-avatar.jpeg",
"fbId": "108012461717543",
"url": "skinlab.example"
}
},
{
"id": 8103,
"workspaceId": 412,
"brandId": 70003,
"status": "ACTIVE",
"lastCheckedAt": "2026-03-08T18:14:21.083Z",
"createdAt": "2026-01-29T02:47:55.440Z",
"brand": {
"id": 70003,
"name": "Luno Apparel",
"slug": "luno-apparel",
"category": "Clothing",
"logo": "luno-apparel-avatar.jpeg",
"fbId": "655031701026626",
"url": "luno.example"
}
}
],
"pagination": {
"page": 1,
"pageSize": 100,
"count": 9,
"total": 9,
"totalPages": 1
}
}
Response 401 (application/json)
{
"error": "Missing Bearer token"
}
Response 403 (application/json)
{
"error": "Workspace is deactivated. Please select a plan to use the API."
}
Response 429 (application/json)
{
"error": "Rate limit exceeded"
}
Response 500 (application/json)
{
"error": "Internal server error"
}/api/v1/usageGet usage summary
Get usage summary
Get a simple usage payload for your workspace. The shape is intentionally straightforward for junior developers. Authentication: - Header: `Authorization: Bearer sk_<16_lowercase_alnum>` Workspace requirements: - Use this API with trial or active paid workspaces. - Deactivated workspaces receive `403`. Rate limits: - Up to 120 requests/min before delay. - Hard cap at 200 requests/min (`429`).
Parameters
No parameters.
Request Body
No request body.
Responses
| Status | Description | Content types | Schema |
|---|---|---|---|
200 | Usage returned successfully. | application/json | object(1 fields) |
401 | Missing or invalid API key. | application/json | object(1 fields) |
403 | Workspace is deactivated. | application/json | object(1 fields) |
429 | Rate limit exceeded. | application/json | object(1 fields) |
500 | Internal server error. | application/json | object(1 fields) |
Response 200 (application/json)
{
"data": [
{
"your_email": "[email protected]",
"plan_type": "Basic",
"billing_frequency": "monthly",
"workspace_name": "Acme Growth",
"account_activated": "Yes",
"member_since": "2023-01-01T05:48:02.674Z",
"total_ads_in_your_library": 665,
"total_boards_in_your_workspace": 22,
"total_folders_in_your_workspace": 2,
"tracker_limit": 20,
"ai_credits_used": 62,
"ai_credits_on_your_plan": 150,
"ai_credits_reset_date": "2026-01-13",
"total_credits": 150,
"remaining_credits": 88,
"user": {
"id": "91",
"email": "[email protected]"
}
}
]
}
Response 401 (application/json)
{
"error": "Missing Bearer token"
}
Response 403 (application/json)
{
"error": "Workspace is deactivated. Please select a plan to use the API."
}
Response 429 (application/json)
{
"error": "Rate limit exceeded"
}
Response 500 (application/json)
{
"error": "Internal server error"
}