stipple-sh Auth API

openapi: 3.2.0
info:
  title: Stipple Sh Auth API
  version: 0.6.0
  contact:
    name: Stipple
    url: https://www.stipple.sh/contact
  license:
    name: Security & terms
    url: https://www.stipple.sh/security
  description: 'Operations tagged Auth across 2 of this provider''s published API definitions: www.stipple.sh-openapi.json, stipple-sh-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://www.stipple.sh
  description: Production
tags:
- name: Auth
  description: Sign-in sessions for the web app (magic link + Google).
paths:
  /v1/account/onboarding:
    post:
      tags:
      - Auth
      summary: Mark Account Onboarding
      operationId: mark_account_onboarding_v1_account_onboarding_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OnboardingBody'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Mark Account Onboarding V1 Account Onboarding Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: https://www.stipple.sh
      description: Production
  /v1/account/overview:
    get:
      tags:
      - Auth
      summary: Account Overview
      operationId: account_overview_v1_account_overview_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Account Overview V1 Account Overview Get
    servers:
    - url: https://www.stipple.sh
      description: Production
  /v1/account/marketing:
    get:
      tags:
      - Auth
      summary: Get Marketing Consent
      description: 'Read from the store, not the 60-second session cache, so Settings shows a change

        the moment it is made. ``prompt_due`` says whether the one-time product-news prompt

        may be shown (api/auth.py prompt_due).'
      operationId: get_marketing_consent_v1_account_marketing_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Get Marketing Consent V1 Account Marketing Get
    post:
      tags:
      - Auth
      summary: Set Marketing Consent
      description: 'Settings'' switch (owner 2026-09-30) and the prompt''s buttons (owner 2026-10-03): one

        call turns tender tips and news on or off. Turning it off never fails on the version,

        so unsubscribing is always one click.'
      operationId: set_marketing_consent_v1_account_marketing_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MarketingConsentBody'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Set Marketing Consent V1 Account Marketing Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: https://www.stipple.sh
      description: Production
  /v1/account/marketing/prompt-dismissed:
    post:
      tags:
      - Auth
      summary: Marketing Prompt Dismissed
      description: 'The product-news prompt was closed without an answer (owner 2026-10-03). It is not

        shown again for a week, and not at all after a second dismissal.'
      operationId: marketing_prompt_dismissed_v1_account_marketing_prompt_dismissed_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Marketing Prompt Dismissed V1 Account Marketing Prompt Dismissed Post
    servers:
    - url: https://www.stipple.sh
      description: Production
  /v1/account/shortlist:
    get:
      tags:
      - Auth
      summary: Get Shortlist
      description: The signed-in account's shortlist, newest last, each tender read again.
      operationId: get_shortlist_v1_account_shortlist_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Get Shortlist V1 Account Shortlist Get
    post:
      tags:
      - Auth
      summary: Add To Shortlist
      description: Mark one tender "Worth bidding". Adding one already there changes nothing.
      operationId: add_to_shortlist_v1_account_shortlist_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShortlistBody'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Add To Shortlist V1 Account Shortlist Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: https://www.stipple.sh
      description: Production
  /v1/account/shortlist/{page_key}:
    delete:
      tags:
      - Auth
      summary: Remove From Shortlist
      description: 'Unmark one tender. Removing one that is not there is fine.


        One tender can sit under an older key: a row''s "f" address stays valid after it gains

        an entity key, and tender_match.tender resolves both to one canonical page. So an item

        goes when its key is the one given, or resolves to the same canonical page.'
      operationId: remove_from_shortlist_v1_account_shortlist__page_key__delete
      parameters:
      - name: page_key
        in: path
        required: true
        schema:
          type: string
          title: Page Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Remove From Shortlist V1 Account Shortlist  Page Key  Delete
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: https://www.stipple.sh
      description: Production
  /v1/auth/request-link:
    post:
      tags:
      - Auth
      summary: Auth Request Link
      description: 'Email a single-use sign-in link.


        ALWAYS returns 202 with the same body, whether or not the address has an account and

        whether or not delivery succeeded. Any difference here — status, timing, wording — turns

        this endpoint into an account-enumeration oracle, which is the standard flaw in

        self-serve login. The caller learns nothing about who has an account.


        The email link''s marketing cookie is set whenever the box was sent, account or not, so

        it tells the caller nothing either.'
      operationId: auth_request_link_v1_auth_request_link_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestLinkBody'
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Auth Request Link V1 Auth Request Link Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: https://www.stipple.sh
      description: Production
  /v1/auth/magic:
    get:
      tags:
      - Auth
      summary: Auth Magic
      description: 'Redeem a magic link: consume the token, start a session, set the cookie, redirect.'
      operationId: auth_magic_v1_auth_magic_get
      parameters:
      - name: token
        in: query
        required: true
        schema:
          type: string
          title: Token
      - name: next
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Next
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: https://www.stipple.sh
      description: Production
  /v1/auth/marketing-intent:
    post:
      tags:
      - Auth
      summary: Auth Marketing Intent
      description: 'The sign-in page calls this just before sending someone to Google (see

        GOOGLE_MARKETING_COOKIE): the box they saw rides in a cookie that lives 120 s and is

        consumed by the very next /v1/auth/google/start. A version this service never shipped

        is refused rather than stored against the wrong sentence.'
      operationId: auth_marketing_intent_v1_auth_marketing_intent_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MarketingIntentBody'
        required: true
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: https://www.stipple.sh
      description: Production
  /v1/auth/google/start:
    get:
      tags:
      - Auth
      summary: Auth Google Start
      description: 'Begin the Google authorization-code flow.


        `marketing=1` says the page that sent this browser here showed the sign-up box; the

        box''s VALUE comes only from GOOGLE_MARKETING_COOKIE, which this route always deletes.

        A start without the flag (a header or docs button, or the sign-in probe) therefore

        discards any tick left in this browser, and a crafted link with the flag but no cookie

        carries nothing.'
      operationId: auth_google_start_v1_auth_google_start_get
      parameters:
      - name: next
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Next
      - name: marketing
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Marketing
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: https://www.stipple.sh
      description: Production
  /v1/auth/google/callback:
    get:
      tags:
      - Auth
      summary: Auth Google Callback
      operationId: auth_google_callback_v1_auth_google_callback_get
      parameters:
      - name: code
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Code
      - name: state
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: State
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: https://www.stipple.sh
      description: Production
  /v1/auth/me:
    get:
      tags:
      - Auth
      summary: Auth Me
      description: 'The signed-in user, or 401. The only fields a browser needs — never the session token,

        never the API keys, never internal flags.'
      operationId: auth_me_v1_auth_me_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Auth Me V1 Auth Me Get
    servers:
    - url: https://www.stipple.sh
      description: Production
  /v1/scans:
    get:
      tags:
      - Auth
      summary: List Scans
      description: 'This account''s scan history, newest first. Requires a session — history is keyed to an

        account and there is no anonymous variant.


        Rows carry the VERDICT, not the input: no submitted text, no uploaded file, no extracted

        content. Signing in buys you a record of what you checked, not a repository of the

        documents themselves.'
      operationId: list_scans_v1_scans_get
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 50
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response List Scans V1 Scans Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: https://www.stipple.sh
      description: Production
  /v1/auth/logout:
    post:
      tags:
      - Auth
      summary: Auth Logout
      description: 'Delete the session server-side, then clear the cookie. Server-side first: clearing only

        the cookie would leave a token that still works if it was captured.'
      operationId: auth_logout_v1_auth_logout_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
    servers:
    - url: https://www.stipple.sh
      description: Production
  /v1/news/unsubscribe:
    get:
      tags:
      - Auth
      summary: News Unsubscribe
      operationId: news_unsubscribe_v1_news_unsubscribe_get
      parameters:
      - name: u
        in: query
        required: false
        schema:
          type: string
          default: ''
          title: U
      - name: t
        in: query
        required: false
        schema:
          type: string
          default: ''
          title: T
      responses:
        '200':
          description: Successful Response
          content:
            text/html:
              schema:
                type: string
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - Auth
      summary: News Unsubscribe One Click
      operationId: news_unsubscribe_one_click_v1_news_unsubscribe_post
      parameters:
      - name: u
        in: query
        required: false
        schema:
          type: string
          default: ''
          title: U
      - name: t
        in: query
        required: false
        schema:
          type: string
          default: ''
          title: T
      responses:
        '200':
          description: Successful Response
          content:
            text/html:
              schema:
                type: string
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: https://www.stipple.sh
      description: Production
components:
  schemas:
    RequestLinkBody:
      properties:
        email:
          type: string
          title: Email
        next:
          anyOf:
          - type: string
          - type: 'null'
          title: Next
        marketing_opt_in:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Marketing Opt In
        marketing_consent_version:
          anyOf:
          - type: string
          - type: 'null'
          title: Marketing Consent Version
      type: object
      required:
      - email
      title: RequestLinkBody
    MarketingConsentBody:
      properties:
        opted_in:
          type: boolean
          title: Opted In
        version:
          anyOf:
          - type: string
          - type: 'null'
          title: Version
        via:
          type: string
          enum:
          - settings
          - prompt
          title: Via
          default: settings
      type: object
      required:
      - opted_in
      title: MarketingConsentBody
    OnboardingBody:
      properties:
        milestone:
          type: string
          enum:
          - sample_result
          - first_real_result
          title: Milestone
      type: object
      required:
      - milestone
      title: OnboardingBody
    MarketingIntentBody:
      properties:
        opted_in:
          type: boolean
          title: Opted In
        version:
          type: string
          title: Version
      type: object
      required:
      - opted_in
      - version
      title: MarketingIntentBody
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ShortlistBody:
      properties:
        page_key:
          type: string
          title: Page Key
      type: object
      required:
      - page_key
      title: ShortlistBody
    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
x-refined-from:
- www.stipple.sh-openapi.json
- stipple-sh-openapi.json