Foresea Auth API

openapi: 3.2.0
info:
  title: Foresea Intelligence Auth API
  description: '## Overview


    The **Foresea Intelligence API** turns market questions, linked evidence, and

    prediction-market prices into probabilistic forecasts that can sit behind

    trading dashboards, alerting systems, and research workflows. It supports binary, multiple-choice, numeric, and date forecasts. Each response

    includes a structured **rationale**, typed forecast fields, optional evidence

    sources fetched from live news, and optional market-edge analysis when you pass

    a market-implied probability. ---


    ## Quick start


    ```bash

    curl -X POST https://foresea.ink/predict \

    -H "Content-Type: application/json" \

    -d ''{

    "question": "Will the Fed cut rates before September 30, 2026?",

    "question_type": "binary",

    "market_platform": "Polymarket",

    "market_probability": 0.54,

    "variant": "variant0_neutral_baseline"

    }''

    ```


    ---


    ## Question types


    Use `question_type` when your client already knows the shape of the question. If omitted, the model will try to infer it. | Type | Response shape |

    |---|---|

    | `binary` | `predicted_answer` is `Yes`/`No`; `confidence` is 0–1 |

    | `multiple_choice` | `options` contains per-option probabilities; `predicted_answer` is the top option |

    | `numeric` | `range_forecast` contains `p10`, `p50`, `p90`, and optional `unit` |

    | `date` | `range_forecast` contains date percentiles |


    For multiple-choice forecasts, pass `options` when the answer set is known. ---


    ## Prediction-market context


    Pass `market_probability` when you know the current market-implied probability

    for the target outcome. For binary markets this defaults to the `Yes` side; set

    `market_outcome` to compare against `No` or a named multiple-choice outcome. Foresea returns `market_analysis` with model probability, market probability,

    percentage-point edge, and a stance (`model_above_market`, `model_below_market`,

    `in_line`, or `not_comparable`). ---


    ## Trading execution


    Foresea can preview and submit guarded orders for Kalshi and Polymarket:


    | Endpoint | Purpose |

    |---|---|

    | `GET /trading/accounts` | Return configured/not-configured server-account status without exposing secrets |

    | `POST /trading/accounts/check` | Validate caller-supplied own-account (BYO) credentials without storing them |

    | `POST /trading/preview` | Normalize and validate an order without placing it |

    | `POST /trading/orders` | Submit a live order after explicit confirmation |


    Live trading is disabled unless `FORESEA_ENABLE_TRADING=true`. Every live order

    requires a signed-in user session, `execute=true`, and the exact confirmation

    phrase `PLACE REAL ORDER`. Market/IOC/FOK-style orders are separately blocked

    unless `FORESEA_ALLOW_MARKET_ORDERS=true`. Exchange credentials come from a shared server account (environment variables /

    Secret Manager mounts) or an authenticated user''s **encrypted account

    connection**. The connection endpoint accepts a user''s credentials once, validates

    them with a unique data-encryption key wrapped by Cloud KMS, and never returns

    them to the browser. Inline `venue_credentials` are rejected on public preview

    and order calls; encrypted own-account trading remains gated by

    `FORESEA_ENABLE_BYO_TRADING=true` (independent of `FORESEA_ENABLE_TRADING`). `/agent/analyze` may return a directional recommendation, but it never places an

    order. Use `/trading/preview` first, review the normalized order, then call

    `/trading/orders` only when you intend to submit a real order. ---


    ## Prompt variants


    The `variant` field controls how the LLM is prompted.'
  contact:
    name: Pareel Amre
    url: https://foresea.ink/
    email: pareel.amre@gmail.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  version: 1.0.0
tags:
- name: Auth
paths:
  /auth/google:
    post:
      tags:
      - Auth
      summary: Sign in with Google
      description: 'Verify a Google One-Tap ID token, create or update the user account, and return a session token.


        The browser should send the `credential` string returned by

        `google.accounts.id.initialize({ callback })` after the user grants consent.

        Store the returned `token` in `localStorage` and include it as

        `Authorization: Bearer ` on subsequent authenticated requests.'
      operationId: auth_google_auth_google_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GoogleAuthRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/github:
    post:
      tags:
      - Auth
      summary: Sign in with GitHub
      description: 'Exchange a GitHub OAuth `code` for the user''s profile and return a session token.


        The browser sends users to GitHub''s authorize URL, then posts the returned

        `code` (and the same `redirect_uri`) here. Store the returned `token` like the

        Google flow.'
      operationId: auth_github_auth_github_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GitHubAuthRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/register:
    post:
      tags:
      - Auth
      summary: Create an account
      description: 'Create an email/password account and return a session token.


        The email becomes the account ID. Passwords are stored as salted

        PBKDF2-HMAC-SHA256 hashes; the plaintext is never persisted.'
      operationId: auth_register_auth_register_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/login:
    post:
      tags:
      - Auth
      summary: Sign in with email and password
      description: Verify an email/password account and return a session token.
      operationId: auth_login_auth_login_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/me:
    get:
      tags:
      - Auth
      summary: Get current user
      description: 'Return the authenticated user decoded from the `Authorization: Bearer` session token.'
      operationId: auth_me_auth_me_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthMeResponse'
  /personal-ledger:
    get:
      tags:
      - Auth
      summary: List Personal Ledger
      description: Return the current user's explicitly saved chat forecasts.
      operationId: list_personal_ledger_personal_ledger_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonalLedgerList'
  /personal-ledger/{entry_id}:
    put:
      tags:
      - Auth
      summary: Save Personal Ledger Entry
      description: Save a forecast to the current user's private personal ledger.
      operationId: save_personal_ledger_entry_personal_ledger__entry_id__put
      parameters:
      - name: entry_id
        in: path
        required: true
        schema:
          type: string
          title: Entry Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonalLedgerEntry'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonalLedgerEntry'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Auth
      summary: Delete Personal Ledger Entry
      description: Remove one saved forecast from the current user's personal ledger.
      operationId: delete_personal_ledger_entry_personal_ledger__entry_id__delete
      parameters:
      - name: entry_id
        in: path
        required: true
        schema:
          type: string
          title: Entry Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: boolean
                title: Response Delete Personal Ledger Entry Personal Ledger  Entry Id  Delete
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /personal-ledger/{entry_id}/verdict:
    patch:
      tags:
      - Auth
      summary: Judge Personal Ledger Entry
      description: Mark one of the current user's saved forecasts correct or wrong.
      operationId: judge_personal_ledger_entry_personal_ledger__entry_id__verdict_patch
      parameters:
      - name: entry_id
        in: path
        required: true
        schema:
          type: string
          title: Entry Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonalLedgerVerdict'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonalLedgerEntry'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /favorites:
    get:
      tags:
      - Auth
      summary: List favourited markets
      description: Return the signed-in user's favourited markets/questions (their watchlist).
      operationId: list_favorites_favorites_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FavoriteList'
  /favorites/{key}:
    put:
      tags:
      - Auth
      summary: Add/update a favourite
      description: Create or replace one favourite for the signed-in user.
      operationId: save_favorite_favorites__key__put
      parameters:
      - name: key
        in: path
        required: true
        schema:
          type: string
          title: Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FavoriteMarket'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FavoriteMarket'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Auth
      summary: Remove a favourite
      description: Delete one favourite for the signed-in user.
      operationId: remove_favorite_favorites__key__delete
      parameters:
      - name: key
        in: path
        required: true
        schema:
          type: string
          title: Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: boolean
                title: Response Remove Favorite Favorites  Key  Delete
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /favorites/prices:
    get:
      tags:
      - Auth
      summary: Live prices for favourited markets
      description: Fetch current market prices for the user's favourited markets (cheap, no LLM).
      operationId: favorite_prices_favorites_prices_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Favorite Prices Favorites Prices Get
components:
  schemas:
    PersonalLedgerEntry:
      properties:
        id:
          type: string
          maxLength: 120
          minLength: 1
          pattern: ^[A-Za-z0-9:_\-]+$
          title: Id
        conversation_id:
          type: string
          maxLength: 120
          title: Conversation Id
          default: ''
        message_id:
          type: string
          maxLength: 120
          title: Message Id
          default: ''
        question:
          type: string
          maxLength: 800
          minLength: 1
          title: Question
        predicted_answer:
          type: string
          maxLength: 120
          title: Predicted Answer
          default: ''
        probability:
          type: number
          maximum: 1.0
          minimum: 0.0
          title: Probability
        rationale:
          type: string
          maxLength: 8000
          title: Rationale
          default: ''
        model:
          type: string
          maxLength: 160
          title: Model
          default: ''
        createdAt:
          type: integer
          minimum: 0.0
          title: Createdat
        user_verdict:
          anyOf:
          - type: string
            enum:
            - correct
            - wrong
          - type: 'null'
          title: User Verdict
        judgedAt:
          anyOf:
          - type: integer
            minimum: 0.0
          - type: 'null'
          title: Judgedat
      type: object
      required:
      - id
      - question
      - probability
      - createdAt
      title: PersonalLedgerEntry
      description: One forecast a signed-in user explicitly saved from a chat response.
    GoogleAuthRequest:
      properties:
        credential:
          type: string
          maxLength: 8192
          title: Credential
      type: object
      required:
      - credential
      title: GoogleAuthRequest
      description: Google One-Tap credential submitted by the browser.
    PersonalLedgerList:
      properties:
        entries:
          items:
            $ref: '#/components/schemas/PersonalLedgerEntry'
          type: array
          title: Entries
      type: object
      required:
      - entries
      title: PersonalLedgerList
    SessionResponse:
      properties:
        token:
          type: string
          title: Token
        user_id:
          type: string
          title: User Id
        email:
          type: string
          title: Email
        name:
          type: string
          title: Name
        picture:
          type: string
          title: Picture
      type: object
      required:
      - token
      - user_id
      - email
      - name
      - picture
      title: SessionResponse
      description: Issued after a successful Google sign-in.
    LoginRequest:
      properties:
        email:
          type: string
          maxLength: 254
          title: Email
        password:
          type: string
          maxLength: 128
          title: Password
      type: object
      required:
      - email
      - password
      title: LoginRequest
      description: Email + password sign-in submitted by the browser.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PersonalLedgerVerdict:
      properties:
        verdict:
          type: string
          enum:
          - correct
          - wrong
          title: Verdict
      type: object
      required:
      - verdict
      title: PersonalLedgerVerdict
      description: A user's explicit assessment of one of their saved forecasts.
    RegisterRequest:
      properties:
        email:
          type: string
          maxLength: 254
          title: Email
          description: Account email address.
        password:
          type: string
          maxLength: 128
          minLength: 8
          title: Password
          description: At least 8 characters.
        name:
          type: string
          maxLength: 120
          title: Name
          description: Optional display name.
          default: ''
      type: object
      required:
      - email
      - password
      title: RegisterRequest
      description: Email + password sign-up submitted by the browser.
    AuthMeResponse:
      properties:
        user_id:
          type: string
          title: User Id
        email:
          type: string
          title: Email
        name:
          type: string
          title: Name
        picture:
          type: string
          title: Picture
      type: object
      required:
      - user_id
      - email
      - name
      - picture
      title: AuthMeResponse
      description: Current user decoded from a session token.
    GitHubAuthRequest:
      properties:
        code:
          type: string
          maxLength: 512
          title: Code
        redirect_uri:
          anyOf:
          - type: string
            maxLength: 2000
          - type: 'null'
          title: Redirect Uri
      type: object
      required:
      - code
      title: GitHubAuthRequest
      description: GitHub OAuth authorization code returned to the browser.
    FavoriteList:
      properties:
        favorites:
          items:
            $ref: '#/components/schemas/FavoriteMarket'
          type: array
          title: Favorites
      type: object
      required:
      - favorites
      title: FavoriteList
    FavoriteMarket:
      properties:
        key:
          type: string
          maxLength: 160
          minLength: 1
          pattern: ^[A-Za-z0-9:_\-./]+$
          title: Key
        question:
          type: string
          maxLength: 500
          title: Question
          default: ''
        platform:
          anyOf:
          - type: string
            maxLength: 40
          - type: 'null'
          title: Platform
        ident:
          anyOf:
          - type: string
            maxLength: 160
          - type: 'null'
          title: Ident
        market_url:
          anyOf:
          - type: string
            maxLength: 500
          - type: 'null'
          title: Market Url
        model_probability:
          anyOf:
          - type: number
            maximum: 1.0
            minimum: 0.0
          - type: 'null'
          title: Model Probability
        market_probability:
          anyOf:
          - type: number
            maximum: 1.0
            minimum: 0.0
          - type: 'null'
          title: Market Probability
        notify:
          type: boolean
          title: Notify
          default: false
        createdAt:
          anyOf:
          - type: integer
            minimum: 0.0
          - type: 'null'
          title: Createdat
        updatedAt:
          anyOf:
          - type: integer
            minimum: 0.0
          - type: 'null'
          title: Updatedat
      type: object
      required:
      - key
      title: FavoriteMarket
      description: 'A market or question a signed-in user has favourited to watch.


        `key` identifies the favourite (`{platform}:{ident}` for a market, or a

        client-chosen slug for a bare question). `notify` opts the favourite into the

        periodic email digest (`scripts/favorites_digest.py`).'
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError