AdPlug Users API

openapi: 3.2.0
info:
  title: AdPlug Users API
  description: MCP Ads Platform for Performance Marketers
  version: 0.1.0
tags:
- name: Users
paths:
  /api/users/{user_id}/profile:
    get:
      summary: Get User Profile
      description: 'Get user profile data.


        Enriches the raw profile row with `mcp_client_connected_at`: a

        {client_key: iso_timestamp} map of when each AI client first hit /mcp,

        derived from the earliest `usage_logs.client` row per client_key. Clients

        that connected before the `client` column existed will be missing from

        this map — the frontend falls back to the global

        `mcp_first_authenticated_at` for the user''s first-ever client.


        Also adds `payment_issue` while the user''s subscription, or the team

        owner''s that gives them their plan, is past due (app/paddle/payment_issue.py).'
      operationId: get_user_profile_api_users__user_id__profile_get
      security:
      - HTTPBearer: []
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          title: User Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Users
  /api/users/{user_id}/connections:
    get:
      summary: Get User Connections
      description: Get user's ad platform connections.
      operationId: get_user_connections_api_users__user_id__connections_get
      security:
      - HTTPBearer: []
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          title: User Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Users
  /api/users/{user_id}/checkout-opened:
    post:
      summary: Checkout Opened
      description: 'The browser opened a Paddle checkout for a paid plan.


        Queues the founder note Resend sends a few hours later if the user is still

        on Free (one per account, deduped on the contact). Free users only.'
      operationId: checkout_opened_api_users__user_id__checkout_opened_post
      security:
      - HTTPBearer: []
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          title: User Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              title: Payload
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Users
  /api/users/{user_id}/usage:
    get:
      summary: Get User Usage
      description: 'Get user''s usage stats and recent logs.


        Includes the effective monthly request and edit limits — the dashboard

        can render meters without duplicating tier logic.'
      operationId: get_user_usage_api_users__user_id__usage_get
      security:
      - HTTPBearer: []
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          title: User Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Users
  /api/users/{user_id}/connections/{platform}:
    delete:
      summary: Delete User Connection
      description: Disconnect an ad platform.
      operationId: delete_user_connection_api_users__user_id__connections__platform__delete
      security:
      - HTTPBearer: []
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          title: User Id
      - name: platform
        in: path
        required: true
        schema:
          type: string
          title: Platform
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Users
  /api/users/{user_id}/hubspot-portals:
    get:
      summary: Get Hubspot Portals
      description: The user's connected HubSpot portals and how many their plan covers.
      operationId: get_hubspot_portals_api_users__user_id__hubspot_portals_get
      security:
      - HTTPBearer: []
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          title: User Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Users
  /api/users/{user_id}/hubspot-portals/{hub_id}:
    patch:
      summary: Rename Hubspot Portal
      description: Give a portal the name the user knows it by (the assistant matches it too). Empty clears it.
      operationId: rename_hubspot_portal_api_users__user_id__hubspot_portals__hub_id__patch
      security:
      - HTTPBearer: []
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          title: User Id
      - name: hub_id
        in: path
        required: true
        schema:
          type: integer
          title: Hub Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              title: Payload
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Users
    delete:
      summary: Delete Hubspot Portal
      description: Disconnect one HubSpot portal; the others stay connected.
      operationId: delete_hubspot_portal_api_users__user_id__hubspot_portals__hub_id__delete
      security:
      - HTTPBearer: []
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          title: User Id
      - name: hub_id
        in: path
        required: true
        schema:
          type: integer
          title: Hub Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Users
  /api/users/{user_id}:
    delete:
      summary: Delete User Account
      description: 'Permanently delete a user''s account and all associated data.


        Order matters:

        1. Cancel the account''s Paddle subscriptions. Nothing is deleted unless

        Paddle confirms: without a login the customer could not stop the

        charges themselves.

        2. usage_logs → profiles has NO cascade, so wipe logs first or the

        auth.users delete fails with an FK violation.

        3. auth.users delete cascades to profiles → connections (both have

        ON DELETE CASCADE).

        4. Ask Paddle again. A checkout paid for during steps 1-3 was linked to

        the account after step 1 looked. Anything paid for after this is

        canceled by the webhook, which finds no account.


        If step 3 fails after step 2 succeeded, the account is left with no

        usage history but otherwise intact. We log the partial state loudly so

        ops can reconcile, and return 500 so the client surfaces the error

        instead of signing the user out.'
      operationId: delete_user_account_api_users__user_id__delete
      security:
      - HTTPBearer: []
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          title: User Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Users
  /api/users/{user_id}/rotate-mcp-token:
    post:
      summary: Rotate Mcp Token
      description: 'Regenerate the user''s MCP URL-token.


        Every MCP connection using the prior token URL stops working immediately.

        The client is expected to refresh the user profile after a 200 response

        and prompt the user to update their installed tools.


        Note on the cooldown: enforced in-process via `_rotate_last_at`, so it''s

        per-Cloud-Run-instance rather than global. An authenticated user with

        N instances in rotation could in theory burst through — tracked as a

        follow-up (move to a DB-backed check with `profiles.mcp_token_rotated_at`).'
      operationId: rotate_mcp_token_api_users__user_id__rotate_mcp_token_post
      security:
      - HTTPBearer: []
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          title: User Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Users
  /api/users/{user_id}/paddle-sync-subscription:
    post:
      summary: Sync Paddle Subscription
      description: 'Browser-triggered subscription sync.


        The dashboard calls this from Paddle.js''s `checkout.completed` callback so

        the user sees their new tier instantly — no need to wait for the webhook

        to round-trip through Paddle''s servers. We re-fetch the canonical

        subscription from Paddle''s API (don''t trust the browser payload alone),

        then route through the same handler the webhook uses. Idempotency at the

        handler layer means a later webhook for the same subscription is a no-op.


        Accepts `{ "subscription_id": "sub_..." }` or `{ "transaction_id": "txn_..." }`.'
      operationId: sync_paddle_subscription_api_users__user_id__paddle_sync_subscription_post
      security:
      - HTTPBearer: []
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          title: User Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              title: Payload
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Users
  /api/users/{user_id}/paddle-subscription:
    get:
      summary: Get Paddle Subscription
      description: 'The live state of the user''s subscription: trial end, next charge, scheduled cancellation.'
      operationId: get_paddle_subscription_api_users__user_id__paddle_subscription_get
      security:
      - HTTPBearer: []
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          title: User Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Users
  /api/users/{user_id}/paddle-portal-session:
    post:
      summary: Create Paddle Portal Session
      description: 'Create a Paddle customer-portal session and return the overview URL.


        The dashboard''s "Manage billing" button calls this and then redirects the

        browser to the returned URL. The session token is short-lived; the

        response must not be cached.'
      operationId: create_paddle_portal_session_api_users__user_id__paddle_portal_session_post
      security:
      - HTTPBearer: []
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          title: User Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Users
  /api/users/{user_id}/paddle-change-plan:
    post:
      summary: Paddle Change Plan
      description: 'Change the user''s existing Paddle subscription in place (prorated).


        Users with a live subscription must never go through checkout again —

        Paddle happily creates a parallel second subscription (2026-07-13

        double-billing incident). This endpoint swaps the subscription''s price

        instead, keeping the same subscription id so the webhook ownership guards

        stay coherent. Upgrades charge the prorated difference today; downgrades

        turn the unused higher-plan time into customer balance credit that covers

        future renewals.'
      operationId: paddle_change_plan_api_users__user_id__paddle_change_plan_post
      security:
      - HTTPBearer: []
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          title: User Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              title: Payload
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Users
  /api/users/{user_id}/paddle-cancel-current-sub:
    post:
      summary: Paddle Cancel Current Sub
      description: 'Cancel the user''s active Paddle subscription immediately.


        Sandbox-only: gated on the API key prefix. Returns 403 on live accounts.

        Built for Playwright lifecycle tests to clean up the `sub_…` they create —

        without it, every successful test run leaves a lingering active sub that

        breaks subsequent runs (Paddle''s Checkout overlay routes "already-subscribed"

        customers through a different flow).


        Production users cancel via the Paddle customer portal — this endpoint is

        NOT a public cancel UX; the response intentionally exposes the underlying

        Paddle state so test failures are diagnosable from the spec output.'
      operationId: paddle_cancel_current_sub_api_users__user_id__paddle_cancel_current_sub_post
      security:
      - HTTPBearer: []
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          title: User Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Users
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer