Foreplay Public API

https://docs.foreplay.co/
Admin
This API empowers users to programmatically search, filter, and analyze a vast database of ads and...
Tokens:3,878
Snippets:37
Trust Score:9.3
Update:6 months ago
Show doc for...
Tokens:
Raw
### GET /api/spyder/brands

Source: https://docs.foreplay.co

Fetches a list of brands from the Spyder endpoint. This is an example of how to make your first API call.

```APIDOC
## GET /api/spyder/brands

### Description
Fetches a list of brands available through the Spyder feature. This endpoint is useful for retrieving a focused view of brands you are subscribed to.

### Method
GET

### Endpoint
https://public.api.foreplay.co/api/spyder/brands

### Query Parameters
- **offset** (integer) - Optional - The number of brands to skip before starting to collect the result set.
- **limit** (integer) - Optional - The maximum number of brands to return. Defaults to 10.

### Request Example
```bash
curl -X GET "https://public.api.foreplay.co/api/spyder/brands?offset=0&limit=10" \
  -H "Authorization: YOUR_API_KEY"
```

### Response
#### Success Response (200)
- **data** (array) - An array of brand objects.
  - **id** (string) - The unique identifier for the brand.
  - **name** (string) - The name of the brand.
- **metadata** (object) - Metadata about the request.
  - **success** (boolean) - Indicates if the request was successful.
  - **status_code** (integer) - The HTTP status code of the response.
  - **count** (integer) - The number of items returned in the data array.

#### Response Example
```json
{
  "data": [
    {
      "id": "brand_123456",
      "name": "Example Brand Inc."
      // ... other brand details
    }
  ],
  "metadata": {
    "success": true,
    "status_code": 200,
    "count": 1
    // ... other metadata
  }
}
```
```

--------------------------------

### Example API Response

Source: https://docs.foreplay.co

The structure of a successful API response containing data and metadata.

```json
{
  "data": [
    {
      "id": "brand_123456",
      "name": "Example Brand Inc.",
      // ... other brand details
    }
  ],
  "metadata": {
    "success": true,
    "status_code": 200,
    "count": 1
    // ... other metadata
  }
}
```

--------------------------------

### Get SwipeFile Ads using Shell Curl

Source: https://docs.foreplay.co

Use this command to retrieve user's swipefile ads. Ensure you have the correct authentication headers and query parameters set.

```Shell
curl -X GET "https://public.api.foreplay.co/api/swipefile/ads?start_date=2024-11-12%2000:00:00&end_date=2024-11-12%2023:59:59&live=true&display_format=video&publisher_platform=facebook&niches=%5B%22accessories%22%5D&market_target=b2c&languages=en&video_duration_min=5&video_duration_max=60&running_duration_min_days=1&running_duration_max_days=7&offset=0&limit=10&order=saved_newest" \
     -H "accept: application/json" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

--------------------------------

### Retrieve 401 Unauthorized Error Response

Source: https://docs.foreplay.co

Example JSON structure returned when an API request fails due to authentication issues.

```json
{
  "metadata": {
    "success": false,
    "message": "Authentication failed.",
    "status_code": 401,
    "processed_at": 1756488402833
  },
  "error": {
    "message": "Invalid or missing API key"
  },
  "data": []
}
```

--------------------------------

### Fetch Brands with Python

Source: https://docs.foreplay.co

Use the requests library to retrieve brand data.

```python
import requests

# Fetches the first 10 brands from the Spyder endpoint.
r = requests.get(
    "https://public.api.foreplay.co/api/spyder/brands",
    params={"offset": 0, "limit": 10},
    headers={"Authorization": "YOUR_API_KEY"},
)
```

--------------------------------

### Fetch Brands via cURL

Source: https://docs.foreplay.co

Retrieve a list of brands using the Spyder endpoint.

```bash
# This command requests the first 10 brands from the Spyder endpoint.
curl -X GET "https://public.api.foreplay.co/api/spyder/brands?offset=0&limit=10" 
  -H "Authorization: YOUR_API_KEY"
```

--------------------------------

### Response Headers

Source: https://docs.foreplay.co

All responses from the Foreplay API include several helpful headers for tracking request processing and credit usage.

```APIDOC
## Response Headers

### Description
All responses from the Foreplay API include the following headers for your convenience:

- **X-Process-Time** (string) - The server time taken to process the request.
- **X-Trace-ID** (string) - A unique ID for each request, useful for support and debugging.
- **X-Credits-Remaining** (integer) - The number of credits left on your plan.
- **X-Credit-Cost** (integer) - The credit cost of the specific request you just made.
```

--------------------------------

### Fetch Brands with JavaScript

Source: https://docs.foreplay.co

Use the fetch API to retrieve brand data.

```javascript
// Fetches the first 10 brands from the Spyder endpoint.
await fetch("https://public.api.foreplay.co/api/spyder/brands?offset=0&limit=10", {
  headers: { Authorization: "YOUR_API_KEY" }
});
```

--------------------------------

### Authentication

Source: https://docs.foreplay.co

All requests to the Foreplay API require authentication using an API key provided in the Authorization header.

```APIDOC
## Authentication

### Description
Every request to the Foreplay API must include your API key in the `Authorization` header for authentication.

### Header
`Authorization: YOUR_API_KEY`

_Replace `YOUR_API_KEY` with the actual API key generated from your account dashboard._

### Request Example (JavaScript)
```javascript
// Fetches the first 10 brands from the Spyder endpoint.
await fetch("https://public.api.foreplay.co/api/spyder/brands?offset=0&limit=10", {
  headers: { Authorization: "YOUR_API_KEY" }
});
```

### Request Example (Python)
```python
import requests

# Fetches the first 10 brands from the Spyder endpoint.
r = requests.get(
    "https://public.api.foreplay.co/api/spyder/brands",
    params={"offset": 0, "limit": 10},
    headers={"Authorization": "YOUR_API_KEY"},
)
```
```

--------------------------------

### API Standards and Data Model

Source: https://docs.foreplay.co

Overview of the API's error handling, pagination, rate limiting, and the structure of the Ad entity.

```APIDOC
## API Standards

### Error Handling
The API uses standard HTTP status codes:
- 400: Bad Request
- 401: Unauthorized
- 402: Payment Required
- 403: Forbidden
- 404: Not Found
- 429: Too Many Requests
- 500: Internal Server Error

### Pagination
- **Cursor-based**: Use `metadata.cursor` for subsequent requests.
- **Offset-based**: Use `offset` and `limit` parameters.

### Rate Limiting
Exceeding limits results in a 429 error. Implement exponential backoff for retries.

## Data Model: Ad
- **id** (string): Unique identifier.
- **ad_id** (string): Platform-specific identifier.
- **name** (string): Ad headline.
- **brand_id** (string): Associated brand.
- **description** (string): Ad text.
- **headline** (string): Main ad text.
- **cta_title** (string): Call-to-action text.
- **categories** (array): Ad categories.
- **creative_targeting** (object): Targeting info.
- **languages** (array): Languages used.
- **market_target** (string): Market segment.
- **niches** (array): Relevant niches.
- **product_category** (string): Product category.
- **timestamped_transcription** (array): Transcription segments.
- **full_transcription** (string): Full text.
- **cards** (array): Carousel/DCO components.
- **avatar** (string): Avatar URL.
- **cta_type** (string): CTA type.
- **display_format** (string): Ad format.
- **emotional_drivers** (array): Detected drivers.
- **link_url** (string): Destination URL.
- **live** (boolean): Status.
- **persona** (object): Target persona.
- **publisher_platform** (array): Platforms.
- **started_running** (timestamp): Start date.
- **thumbnail** (string): Thumbnail URL.
- **video** (string): Video URL.
- **image** (string): Image URL.
- **content_filter** (object): Classification scores.
- **video_duration** (number): Duration in seconds.
- **running_duration** (number): Total running time.
```

--------------------------------

### Set Authorization Header

Source: https://docs.foreplay.co

Include the API key in the Authorization header for all requests.

```http
Authorization: YOUR_API_KEY
```

--------------------------------

### SwipeFile Operations API

Source: https://docs.foreplay.co

This API allows you to retrieve user's swipefile ads, which are all saved ads in the swipefile.

```APIDOC
## GET /api/swipefile/ads

### Description
Get user's swipefile ads, all saved ads in swipefile.

### Method
GET

### Endpoint
https://public.api.foreplay.co/api/swipefile/ads

### Query Parameters
- **start_date** (string) - Optional - Example: 2024-11-12 00:00:00
- **end_date** (string) - Optional - Example: 2024-11-12 23:59:59
- **live** (boolean) - Optional - Example: true
- **display_format** (string) - Optional - Example: video
- **publisher_platform** (string) - Optional - Example: facebook
- **niches** (array) - Optional - Example: [ "accessories" ]
- **market_target** (string) - Optional - Example: b2c
- **languages** (string) - Optional - Example: en
- **video_duration_min** (integer) - Optional - Example: 5
- **video_duration_max** (integer) - Optional - Example: 60
- **running_duration_min_days** (integer) - Optional - Example: 1
- **running_duration_max_days** (integer) - Optional - Example: 7
- **offset** (integer) - Optional - Example: 0
- **limit** (integer) - Optional - Example: 10
- **order** (string) - Optional - Example: saved_newest

### Request Example
None

### Response
#### Success Response (200)
- **ads** (array) - Description of the ads returned.
- **ad_id** (string) - The unique identifier for the ad.
- **creation_date** (string) - The date and time the ad was created.
- **source_url** (string) - The URL of the original ad.
- **thumbnail_url** (string) - The URL of the ad's thumbnail.
- **video_url** (string) - The URL of the ad's video.
- **publisher_platform** (string) - The platform where the ad was published.
- **languages** (array) - The languages associated with the ad.
- **niches** (array) - The niches associated with the ad.
- **market_target** (string) - The market target for the ad.
- **video_duration_sec** (integer) - The duration of the ad video in seconds.
- **running_duration_days** (integer) - The running duration of the ad in days.
- **is_live** (boolean) - Indicates if the ad is currently live.

#### Response Example
{
  "ads": [
    {
      "ad_id": "ad123",
      "creation_date": "2024-11-12T10:00:00Z",
      "source_url": "http://example.com/ad123",
      "thumbnail_url": "http://example.com/thumb123.jpg",
      "video_url": "http://example.com/video123.mp4",
      "publisher_platform": "facebook",
      "languages": ["en"],
      "niches": ["accessories"],
      "market_target": "b2c",
      "video_duration_sec": 30,
      "running_duration_days": 5,
      "is_live": true
    }
  ]
}
```
Tokens:
Raw