logo

Publishers

API Documentation

Everything you need to integrate Madgic into your AI applications

1. API Key Generation

To use Madgic's API services, you'll need to generate an API key from your dashboard. This key is used to authenticate your requests and track your usage for billing purposes.

Your API key should be kept confidential and secure. Do not share your key publicly or commit it to public repositories.

2. Integration Methods

Madgic offers two primary methods to integrate with our ad service: through the Model Context Protocol (MCP) or through our REST API. MCP is recommended for most use cases, as it provides a more seamless integration with AI applications. For chat-based applications, we recommend using API before returning the response to the user. For example:

javascript

          // Generate the response from the model
          const response = await model.generateText({
            prompt: 'Recommend a nice hotel in Italy',
          });
          
          // Add ads to the response
          const responseWithAds = await api.integrateAds(response);
          
          // Return the response to the user
          return responseWithAds;

You can choose the method that best fits your needs.

2.1 Model Context Protocol (MCP) Integration

The Model Context Protocol allows for a more seamless integration with AI applications using a streaming communication model.

Endpoint:

http
https://mcp.madgic.ai/mcp

Headers:

http
{
  "mcpServers": {
    "madgic-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.madgic.ai/mcp",
        "--header",
        "Authorization: Bearer YOUR_API_KEY"
      ]
    }
  }
}

Make sure to include in the system prompt of the model, that would ask for ads when applicable.

2.2 REST API Integration

Our REST API allows you to integrate ads into your content programmatically. We provide two main endpoints:

Contextual Ads Endpoint

This endpoint returns relevant ads based on your content without integrating them into the text.

Endpoint:

http
POST https://adserver.madgic.ai/api/ads/contextual

Headers:

http
Authorization: Bearer YOUR_API_KEY

Request Body:

json
{
  "context": "Your content text that needs relevant ads",
  "adCount": 2  // Optional, defaults to 2. Max 3.
}

Response:

json
{
  "status": "success | error",
  "message": "error message, if any",
  "data": [
    {
      "phrase": "Ad phrase",
      "link": "http://adserver.madgic.ai/link",
      "description": "Ad description"
    }
  ]
}
Ad Integration Endpoint

This endpoint analyzes your content and returns the same content with relevant ads integrated into it.

Endpoint:

http
POST https://adserver.madgic.ai/api/ads/integrate

Headers:

http
Authorization: Bearer YOUR_API_KEY

Request Body:

json
{
  "text": "Your content that needs ad integration",
  "adCount": 2  // Optional, defaults to 2. Max 3.
}

Response:

json
{
  "status": "success | error",
  "message": "error message, if any",
  "data": "Your content with integrated ads"
}

3. Integration Best Practices

For optimal results, consider these best practices:

  • Provide sufficient content context to ensure relevant ad matching

  • Implement proper error handling in your integration

  • Monitor your dashboard for performance metrics and revenue tracking

  • Consider caching strategies to optimize performance while respecting ad freshness

4. Support

If you encounter any issues or have questions about the API integration, please contact our support team through your dashboard or email support@madgic.ai.