AdsOverAI GPT Integration Documentation

Overview

AdsOverAI provides contextual product recommendations through a safe, read-only API designed specifically for GPT integration. The API is marked as non-consequential, meaning it's safe for automatic invocation without requiring user confirmation. This allows your custom GPT to naturally recommend products within conversations without interrupting the user experience.

Prerequisites

ChatGPT Plus or ChatGPT Enterprise account
AdsOverAI developer account (we'll create this in Step 1)
Basic understanding of API authentication
Access to create custom GPTs in ChatGPT

Complete Setup Guide

Step 1: Create Your AdsOverAI Developer Account

Visit www.adsoverai.com
Navigate to the Developers section or go directly to /developers
Click on "Sign Up for Developers" or "Join as AI Builder"
Complete the developer registration form:
- Enter your full name
- Provide your email address
- Create a secure password
- Select "AI Builder" or "Developer" as your account type
Agree to the Terms of Service and Privacy Policy
Click "Create Developer Account"
Check your email inbox for a verification email
Click the verification link in the email to activate your account
Log in to your new developer account

Note: The developer account gives you access to:

API key generation and management
Developer dashboard with analytics
Integration documentation
Usage analytics and monitoring
Sandbox environment for testing

Step 2: Generate Your Developer API Key

Once logged in to your developer account:

Go to your Developer Dashboard
Navigate to Settings → API Keys (or Developer section)
Click the "Generate New API Key" button
Give your API key a name (e.g., "My GPT Integration" or "Product Recommender Bot")
Copy your API key immediately - it will look something like: ak_1234567890abcdefghijklmnop
Store it securely in a password manager or secure location

Important: You may not be able to see this key again, so save it now!

Security Best Practices:

⚠️ Never:

Share your API key publicly
Commit it to GitHub or version control
Expose it in client-side code
Share it in screenshots or videos

✅ Always:

Store it in a password manager
Treat it like a password
Regenerate it if you suspect it's been compromised

Step 3: Create Your Custom GPT

Now let's create your custom GPT in ChatGPT:

Open ChatGPT at chat.openai.com
Click on your profile picture in the top-right corner
Select "My GPTs" from the dropdown menu
Click the "Create a GPT" button (or "+ Create")
You'll see two tabs: Create and Configure
In the Create tab, you can use the GPT Builder to:
- Give your GPT a name (e.g., "Shopping Assistant", "Product Recommender", "Smart Shopper")
- Add a description (e.g., "I help you find the perfect products based on your needs")
- Set the tone and personality
Click on the "Configure" tab to proceed with technical setup

Step 4: Add the Action

In the Configure tab:

Scroll down to the "Actions" section
Click "Create new action"
You'll see an OpenAPI schema editor with a text area
Delete any default text in the editor
Copy the entire OpenAPI schema from below (see "OpenAPI Schema" section)
Paste it into the schema editor
The system will automatically validate your schema
If valid, you'll see a green checkmark or success message

What this does: The schema tells your GPT how to communicate with the AdsOverAI API, what data to send, and what to expect back.

Step 5: Configure Authentication

This is the most important step for security. Below the schema editor, you'll see the Authentication section:

Click on the Authentication dropdown/section
Select "API Key" as the Authentication Type (click the radio button)
For "Auth Type", select "Custom" (click the radio button)
In the "Custom Header Name" field, enter exactly: X-API-Key
- ⚠️ This is case-sensitive! Must be exactly X-API-Key
In the "API Key" field, paste your API key from Step 2
- It should show as [HIDDEN] after you paste it for security
The field will be masked/hidden for security

Visual Reference (what you should see):

Authentication Type: ● API Key  ○ OAuth  ○ None

API Key: [HIDDEN]

Auth Type: ○ Basic  ○ Bearer  ● Custom

Custom Header Name: X-API-Key

Step 6: Configure Privacy Policy

Still in the Authentication section:

Look for the "Privacy Policy" field (usually below the API key settings)
Enter exactly: https://www.adsoverai.com/privacy

This is required by OpenAI for all GPT actions that connect to external APIs.

Why this matters: OpenAI requires all GPTs with external actions to have a privacy policy link so users know how their data is handled.

Step 7: Test Your Integration

Before publishing, let's make sure everything works:

Look for a "Test" button in the action editor (usually near the bottom or top-right)
Click "Test"
In the test interface, try a sample query like:
- running shoes
- laptop for students
- winter jacket
You should see a JSON response with product recommendations
The response should look like:

{
  "success": true,
  "data": {
    "matches": [
      {
        "ad_id": "12345",
        "brand_name": "Nike",
        "product_name": "Air Zoom Pegasus",
        "description": "Comfortable running shoes...",
        "cta_link": "https://...",
        "price_range": "$120-$140"
      }
    ]
  }
}

If you get errors:

"Authentication failed" → Double-check your API key, make sure no extra spaces
"Invalid schema" → Make sure you copied the entire YAML schema
"404 Not Found" → Verify the server URL is https://www.adsoverai.com
"Invalid header" → Ensure Custom Header Name is exactly X-API-Key

Step 8: Configure GPT Instructions (Optional but Recommended)

Back in the Configure tab, add instructions for how your GPT should use the recommendations:

Example Instructions:

You are a helpful shopping assistant. When users ask about products or express 
needs, use the getProductRecommendations action to find relevant products. 

Present recommendations naturally in conversation. Include:
- Why the product matches their needs
- Key features and benefits
- Price range
- Direct link to learn more

Always be helpful and honest. If products don't perfectly match, say so.

Step 9: Customize Your GPT (Optional)

Make your GPT more engaging:

Profile Picture: Upload an icon or image that represents your GPT
Conversation Starters: Add sample questions users can click:
- "Help me find running shoes"
- "I need a new laptop"
- "Recommend winter clothing"
- "Find me kitchen gadgets"
Capabilities: Enable/disable:
- Web Browsing (optional)
- DALL-E Image Generation (optional)
- Code Interpreter (usually not needed)

Step 10: Publish Your GPT

Once everything is configured and tested:

Click "Save" in the top-right corner
Choose your sharing settings:
- "Only me" - Private, only you can use it
- "Anyone with a link" - Share with specific people
- "Public" - Anyone can find and use it (requires verification)
Click "Confirm"
Your GPT is now live! 🎉

Share your GPT:

Copy the link and share with others
If public, it will appear in the GPT store

OpenAPI Schema

Copy this entire schema exactly as shown and paste it into the Action schema editor in Step 4:

openapi: 3.1.0
info:
  title: AdsOverAI API
  description: |
    Safe, read-only API that provides contextual product recommendations.
    This endpoint does not modify or store any user data and has no side effects.
    It is safe for automatic invocation by GPT without requiring confirmation.
  version: 1.0.0
servers:
  - url: https://www.adsoverai.com
paths:
  /api/content/match:
    post:
      operationId: getProductRecommendations
      summary: Safe read-only product recommendations lookup
      description: |
        Returns public product recommendation results based on a query.
        This endpoint is strictly read-only, has no side effects, 
        does not store user data, and is safe for automatic calls 
        without prompting the user for confirmation.
      x-openai-isConsequential: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - query
              properties:
                query:
                  type: string
                  description: User's search query or question
                max_ads:
                  type: integer
                  description: Maximum number of ads to return
                  default: 3
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      matches:
                        type: array
                        items:
                          type: object
                          properties:
                            ad_id:
                              type: string
                              description: Unique identifier for the ad
                            brand_name:
                              type: string
                              description: Name of the brand
                            product_name:
                              type: string
                              description: Name of the product
                            description:
                              type: string
                              description: Product description
                            cta_link:
                              type: string
                              description: Call-to-action link
                            price_range:
                              type: string
                              description: Price range of the product
        "400":
          description: Bad request - invalid query
        "401":
          description: Unauthorized - invalid API key
        "500":
          description: Server error

Authentication Configuration Summary

Quick Reference:

Field	Value
Authentication Type	API Key
Auth Type	Custom
Custom Header Name	X-API-Key
API Key	Your generated key from Step 2
Privacy Policy	https://www.adsoverai.com/privacy

How It Works

Here's what happens behind the scenes:

User asks a question → "I need running shoes for marathon training"
Your GPT analyzes the query → Determines product recommendations would be helpful
GPT calls AdsOverAI API → Sends query with your API key in the X-API-Key header
AdsOverAI processes the request → Finds relevant products using semantic matching
API returns recommendations → JSON response with product details
GPT formats the response → Naturally weaves recommendations into conversation
User sees helpful suggestions → Gets relevant products without breaking conversation flow

All of this happens automatically in milliseconds!

Support

For questions or issues:

Email: hello@adsoverai.com
Website: www.adsoverai.com
Documentation: www.adsoverai.com/documentation

Documentation

Ready to integrate?