stipple-sh Auth API
Sign-in sessions for the web app (magic link + Google).
Sign-in sessions for the web app (magic link + Google).
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/stipple-sh:stipple-sh-auth-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
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