openapi: 3.2.0
info:
  title: Parlay Agent API
  description: Real-time sports odds aggregation from **33 books and data sources** updated every 2-120 seconds depending on source cadence.
  version: 3.2.0
  x-credit-currency: credits
  x-credit-cost-catalogue-url: /v1/meta/credit-costs
  x-pricing-url: /v1/pricing
  x-usage-url: /v1/usage
  contact:
    name: ParlayAPI support
    url: https://parlay-api.com/support
    email: support@parlay-api.com
  license:
    name: ParlayAPI Terms of Service
    url: https://parlay-api.com/terms
  termsOfService: https://parlay-api.com/terms
servers:
- url: https://parlay-api.com
  description: Production (primary; HTTP/2, TLS 1.3).
- url: https://api.parlay-api.com
  description: Production (high-volume; bypasses Cloudflare edge for trading bots above 30 req/min). Same origin, same auth, same endpoints.
tags:
- name: Agent
paths:
  /v1/agent/signup:
    post:
      tags:
      - Agent
      summary: Agent Signup
      description: 'Create a free-tier account for an email and return an API key

        plus a magic-link claim URL the user clicks to verify and access

        the dashboard.


        Idempotent on email: if an account already exists, the API key is

        NOT returned (security), only a login URL the user can use to recover.'
      operationId: agent_signup_v1_agent_signup_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /v1/agent/magic-link:
    post:
      tags:
      - Agent
      summary: Agent Magic Link
      description: 'Send a magic login link to an email. Always returns 200 so callers

        cannot enumerate which emails have accounts.'
      operationId: agent_magic_link_v1_agent_magic_link_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /v1/agent/checkout-link:
    post:
      tags:
      - Agent
      summary: Agent Checkout Link
      description: 'Generate a Stripe Checkout URL for a tier upgrade.


        Two modes, picked by whether the caller can prove they control the

        target email:


        1. **Authenticated agent flow.** Caller sends X-API-Key or

        ?apiKey= and the key''s email matches body["email"]. We

        return the Stripe Checkout URL synchronously so the agent

        can paste it to the user. This is the documented happy path

        for an MCP/agent helping the key''s owner upgrade.


        2. **Unauthenticated request.** No API key, or the key''s email

        doesn''t match. We DON''T return a checkout URL. Instead we

        email a one-shot signed link to body["email"] that lands on

        /dashboard?checkout_tier= after magic-link login. The

        recipient has to actually open their inbox and click; an

        attacker can''t generate a Stripe-Checkout-bound-to-victim

        URL without controlling the victim''s email.


        This closes the phishing vector flagged in the 2026-05-20 audit

        P0 1.12: previously the route returned a Stripe URL for ANY email

        after passing only the per-IP signup throttle.'
      operationId: agent_checkout_link_v1_agent_checkout_link_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
components:
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key passed in the X-API-Key header. Recommended.
    apiKeyQuery:
      type: apiKey
      in: query
      name: apiKey
      description: API key passed as the ?apiKey= query parameter. Useful for browser fetch() and webhooks where header control is limited. Equivalent to X-API-Key.
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: APIKey
      description: 'API key passed via Authorization: Bearer <key>. Equivalent to X-API-Key for compatibility with auth libraries that expect bearer tokens.'