> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mrdoge.co/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Recommendations

> Get AI-generated value betting recommendations with confidence levels and edge analysis

<Warning>
  **Costs 2 credits** per request
</Warning>

Returns AI-generated betting recommendations for individual markets. Each recommendation includes:

* Confidence level (High/Medium/Low)
* Statistical edge percentage
* Kelly Criterion stake sizing
* Detailed rationale
* Risk factors
* Data support

Use this endpoint to find value betting opportunities across all events and markets.

## Authorization

<ParamField header="Authorization" type="string" required default="Bearer " placeholder="Bearer sk_live_...">
  Your API key for authentication
</ParamField>

## Query Parameters

<ParamField query="eventId" type="string">
  Filter recommendations for a specific event
</ParamField>

<ParamField query="confidence" type="string">
  Filter by confidence level

  Values: `High`, `Medium`, `Low`
</ParamField>

<ParamField query="minEdge" type="string">
  Minimum edge percentage

  Example: `5` for 5% minimum edge
</ParamField>

<ParamField query="limit" type="string" default="10">
  Maximum number of recommendations
</ParamField>

<ParamField query="regionId" type="string">
  Filter by region
</ParamField>

<ParamField query="competitionId" type="string">
  Filter by competition
</ParamField>

<ParamField query="timezone" type="string">
  Timezone for date filtering
</ParamField>

## Response

Returns an array of betting recommendation objects.

<ResponseField name="id" type="string">
  Unique recommendation ID
</ResponseField>

<ResponseField name="eventId" type="string">
  Event this recommendation is for
</ResponseField>

<ResponseField name="marketId" type="string">
  Market ID
</ResponseField>

<ResponseField name="betItemId" type="string">
  Specific bet item ID
</ResponseField>

<ResponseField name="outcome" type="string">
  Recommended outcome

  Examples: `"Home Win"`, `"Over 2.5"`, `"BTTS Yes"`, `"Lakers -5.5"`
</ResponseField>

<ResponseField name="odds" type="number">
  Current decimal odds

  Example: `2.10`
</ResponseField>

<ResponseField name="confidence" type="string">
  AI confidence level

  * **High**: Edge > 5%, expected 60-65% win rate
  * **Medium**: Edge 3-5%, expected 55-60% win rate
  * **Low**: Edge \< 3%, expected 50-55% win rate
</ResponseField>

<ResponseField name="edgePercentage" type="number">
  Statistical edge over market odds

  Example: `6.8` means 6.8% edge

  **How edge is calculated:**

  ```
  Edge = AI Probability - Implied Probability
  ```

  Example: If AI gives 52% probability and odds of 2.10 imply 47.6%, edge is 4.4%
</ResponseField>

<ResponseField name="kellyFraction" type="number">
  Optimal stake size using Kelly Criterion (10% fractional Kelly)

  Example: `0.032` means 3.2% of bankroll

  **Full Kelly formula:**

  ```
  Kelly % = (Edge × Odds - 1) / (Odds - 1)
  ```

  We recommend **10% fractional Kelly** for safer bankroll management.
</ResponseField>

<ResponseField name="rationale" type="array">
  Array of strings explaining why this bet has value

  Example:

  ```json theme={null}
  [
    "Home team's excellent form (8 wins in last 10)",
    "Away team struggling defensively (10 goals conceded in 3 games)"
  ]
  ```
</ResponseField>

<ResponseField name="riskFactors" type="array">
  Array of potential risks to consider

  Example:

  ```json theme={null}
  [
    "Away team has key players returning from injury",
    "Weather forecast shows heavy rain"
  ]
  ```
</ResponseField>

<ResponseField name="dataSupport" type="array">
  Statistical data supporting this recommendation

  Example:

  ```json theme={null}
  [
    "Simulation gives 52% home win probability vs 47.6% implied by odds",
    "Expected goals: Home 1.8, Away 1.1"
  ]
  ```
</ResponseField>

<ResponseField name="settled" type="boolean">
  Whether the bet has been settled
</ResponseField>

<ResponseField name="result" type="string">
  Settlement result (if settled)

  Values: `won`, `lost`, `push`
</ResponseField>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "Authorization: Bearer sk_live_..." \
    "https://api.mrdoge.co/v2/ai/betting-recommendations?confidence=High&minEdge=5&limit=5"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.mrdoge.co/v2/ai/betting-recommendations?confidence=High&minEdge=5&limit=5',
    {
      headers: { 'Authorization': 'Bearer sk_live_...' }
    }
  );

  const recommendations = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.mrdoge.co/v2/ai/betting-recommendations',
      headers={'Authorization': 'Bearer sk_live_...'},
      params={'confidence': 'High', 'minEdge': '5', 'limit': '5'}
  )

  recommendations = response.json()
  ```
</CodeGroup>

## Response

<ResponseExample>
  ```json Response theme={null}
  {
    "data": [
      {
        "id": "cmhqld82i0dwts201h1dcxr7a",
        "eventId": "43089384",
        "marketId": "1488408114",
        "betItemId": "6169425387",
        "analysisTimestamp": "2025-11-08T18:01:59.322Z",
        "outcome": "Mais de 3,5",
        "odds": 2.2,
        "point": 3.5,
        "confidence": "Medium",
        "edgePercentage": 8.2,
        "kellyFraction": 0.096,
        "rationale": [
          "Simulation shows a total of 4 goals (3-1)",
          "Both teams have shown the ability to score, with Liverpool scoring in 100% of away games",
          "High offensive ratings for both teams support the expectation of a high-scoring match",
          "Data support: Simulated total of 4 goals aligns with historical scoring patterns; City's average goals per match at home is high, supporting the Over 3.5 bet"
        ],
        "riskFactors": [
          "Potential for a lower-scoring game if Liverpool fails to capitalize on chances"
        ],
        "settled": false,
        "result": null,
        "settlementDate": null,
        "actualReturn": null,
        "createdAt": "2025-11-08T18:01:59.322Z",
        "updatedAt": "2025-11-08T18:01:59.322Z",
        "bookmakerSource": "Novibet",
        "dataSourceId": "novibet"
      }
    ]
  }
  ```
</ResponseExample>

<Note>
  When no recommendations match your filters, the endpoint returns an empty array: `{"data": []}`. Try adjusting your filters (lower `minEdge`, remove `confidence` filter, or increase `limit`) to see more results.
</Note>

## Understanding Confidence Levels

<AccordionGroup>
  <Accordion title="High Confidence (Edge > 5%)" icon="fire">
    **What it means**: Strong statistical advantage over market odds

    **Expected accuracy**: 60-65% win rate

    **When it happens**:

    * Clear form advantage
    * Market inefficiency detected
    * Strong tactical mismatch
    * High data quality

    **Recommendation**: These are our best bets. Consider using suggested Kelly stake.
  </Accordion>

  <Accordion title="Medium Confidence (Edge 3-5%)" icon="scale-balanced">
    **What it means**: Moderate statistical advantage

    **Expected accuracy**: 55-60% win rate

    **When it happens**:

    * Slight market inefficiency
    * Minor form advantage
    * Moderate data quality

    **Recommendation**: Good value bets. Consider using 50% of suggested Kelly stake.
  </Accordion>

  <Accordion title="Low Confidence (Edge < 3%)" icon="triangle-exclamation">
    **What it means**: Marginal edge, higher risk

    **Expected accuracy**: 50-55% win rate

    **Note**: We rarely recommend Low confidence bets

    **Recommendation**: Only for experienced value bettors. Use minimum stakes.
  </Accordion>
</AccordionGroup>

## Kelly Criterion Staking

The `kellyFraction` field tells you the optimal stake size for each bet.

### Example Calculation

**Your Bankroll**: \$1,000
**Recommendation**:

* Odds: 2.10
* Edge: 6.8%
* Kelly Fraction: 0.032 (3.2%)

**Stake Calculation:**

```
Full Kelly: $1,000 × 0.032 = $32
10% Fractional Kelly: $32 × 0.10 = $3.20 ← Recommended
```

<Tip>
  **Start Small**: If you're new to value betting, consider using 5% fractional Kelly (half our recommendation) until you're comfortable with variance.
</Tip>

## Filtering Strategies

<CardGroup cols={2}>
  <Card title="High Confidence Only" icon="star">
    ```
    ?confidence=High&minEdge=5
    ```

    Best for conservative betting
  </Card>

  <Card title="Specific Event" icon="crosshairs">
    ```
    ?eventId=123456
    ```

    Get all recommendations for one match
  </Card>

  <Card title="Premier League" icon="futbol">
    ```
    ?competitionId=1&confidence=High
    ```

    Focus on specific league
  </Card>

  <Card title="High Edge Opportunities" icon="chart-line">
    ```
    ?minEdge=7&limit=3
    ```

    Find the biggest edges
  </Card>
</CardGroup>

## Credit Cost

<Info>
  **2 credits per request** - More affordable than Mr. Doge Picks for getting multiple individual recommendations.
</Info>

## Use Cases

* Find value bets across all events
* Filter by confidence and edge
* Get recommendations for specific matches
* Build your own betting strategies
* Track AI performance

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Value Opportunities" icon="gem" href="/api-reference/ai/value-opportunities">
    Get only the highest-edge opportunities
  </Card>

  <Card title="Mr. Doge Picks" icon="dog" href="/api-reference/ai/mrdoge-picks">
    Get curated picks (singles or parlays)
  </Card>

  <Card title="AI Performance" icon="chart-bar" href="/api-reference/ai/performance">
    See historical recommendation performance
  </Card>
</CardGroup>


## OpenAPI

````yaml /api-reference/openapi.json GET /v2/ai/betting-recommendations
openapi: 3.1.0
info:
  title: Mr. Doge API
  description: >-
    Comprehensive sports betting odds, AI predictions, and live data API
    covering 8 major sports with real-time updates and value betting
    recommendations.
  version: 1.0.0
  contact:
    name: Mr. Doge Support
    email: support@mrdoge.co
    url: https://mrdoge.co
servers:
  - url: https://api.mrdoge.co
    description: Production server
security:
  - bearerAuth: []
tags:
  - name: Odds
    description: Endpoints for accessing sports events, odds, and betting markets
  - name: AI
    description: AI-powered betting recommendations and value opportunities
paths:
  /v2/ai/betting-recommendations:
    get:
      tags:
        - AI
      summary: AI Recommendations
      description: >-
        Get AI-generated value betting recommendations for individual markets.
        Each recommendation includes confidence level, edge percentage, Kelly
        fraction, rationale, and risk factors. Costs 2 credits per request.
      parameters:
        - name: eventId
          in: query
          description: Filter by event ID
          schema:
            type: string
        - name: confidence
          in: query
          description: Filter by confidence level
          schema:
            type: string
            enum:
              - High
              - Medium
              - Low
        - name: minEdge
          in: query
          description: Minimum edge percentage
          schema:
            type: string
            example: '5'
        - name: limit
          in: query
          description: Maximum recommendations
          schema:
            type: string
            default: '10'
        - name: regionId
          in: query
          description: Filter by region
          schema:
            type: string
        - name: competitionId
          in: query
          description: Filter by competition
          schema:
            type: string
        - name: timezone
          in: query
          description: Timezone for date filtering
          schema:
            type: string
      responses:
        '200':
          description: Betting recommendations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BettingRecommendation'
        '403':
          $ref: '#/components/responses/InsufficientCredits'
      security: []
components:
  schemas:
    BettingRecommendation:
      type: object
      properties:
        id:
          type: string
          example: rec_123456
        eventId:
          type: string
          example: '123456'
        marketId:
          type: string
          example: mkt_123456
        betItemId:
          type: string
          example: bet_123456
        outcome:
          type: string
          example: Home Win
        odds:
          type: number
          format: float
          example: 2.1
        confidence:
          type: string
          enum:
            - High
            - Medium
            - Low
          example: High
        edgePercentage:
          type: number
          format: float
          example: 6.8
          description: Statistical edge over market odds
        kellyFraction:
          type: number
          format: float
          example: 0.032
          description: >-
            Optimal stake size using Kelly Criterion (10% fractional Kelly
            recommended)
        rationale:
          type: array
          items:
            type: string
          example:
            - Home team's excellent form (8 wins in last 10)
            - Away team struggling defensively (10 goals conceded in 3 games)
        riskFactors:
          type: array
          items:
            type: string
          example:
            - Away team has key players returning from injury
        dataSupport:
          type: array
          items:
            type: string
          example:
            - Simulation gives 52% home win probability vs 47.6% implied by odds
        settled:
          type: boolean
          example: false
        result:
          type: string
          enum:
            - won
            - lost
            - push
          nullable: true
    Error:
      type: object
      properties:
        statusCode:
          type: integer
          example: 400
        message:
          type: string
          example: Invalid request parameters
        error:
          type: string
          example: Bad Request
  responses:
    InsufficientCredits:
      description: Not enough credits to complete request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            statusCode: 403
            message: Insufficient credits. This endpoint costs 2 credits.
            error: Forbidden
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        Use your API key from the Mr. Doge dashboard. Format: `Bearer
        sk_live_...` or `Bearer sk_test_...`

````