{"openapi":"3.1.0","info":{"title":"MyScanity Public API","version":"0.5.0","summary":"Agent API for setups, trade plans, portfolio, and watchlist.","description":"Curated public surface of MyScanity (#1222). Agent routes use `Authorization: Bearer mys_...`; human routes use the session cookie and exist so an account owner can mint or revoke tokens. The agent surface never exposes raw OHLCV, scan triggers, settings, or admin routes. Human documentation: https://www.myscanity.de/entwickler/api.","contact":{"url":"https://www.myscanity.de/impressum"},"license":{"name":"Proprietary — informational tool, not investment advice"}},"servers":[{"url":"https://www.myscanity.de","description":"Production"}],"tags":[{"name":"agent","description":"Read-first agent endpoints. Bearer token only; no raw OHLCV, no scan triggers, no settings writes."},{"name":"auth","description":"Human account sessions (cookie). Agents need an account owner to create a token first."},{"name":"tokens","description":"Personal access tokens. The human mints/revokes them in Settings → Agent access."},{"name":"billing","description":"Subscription endpoints. Payment always requires the human (Stripe Checkout / SCA)."}],"paths":{"/api/v1/auth/register":{"post":{"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"operationId":"post_api_v1_auth_register","summary":"Create an account","description":"E-Mail, Benutzername und Passwort; startet den kostenlosen Testzeitraum.","tags":["auth"],"security":[],"x-myscanity-scope":"-"}},"/api/v1/auth/login":{"post":{"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"operationId":"post_api_v1_auth_login","summary":"Log in (sets the session cookie)","tags":["auth"],"security":[],"x-myscanity-scope":"-"}},"/api/v1/auth/logout":{"post":{"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"operationId":"post_api_v1_auth_logout","summary":"Log out","tags":["auth"],"security":[{"cookieAuth":[]}],"x-myscanity-scope":"-"}},"/api/v1/auth/me":{"get":{"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"operationId":"get_api_v1_auth_me","summary":"Current user and billing status","tags":["auth"],"security":[{"cookieAuth":[]}],"x-myscanity-scope":"-"}},"/api/v1/tokens":{"get":{"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"operationId":"get_api_v1_tokens","summary":"List agent tokens (prefixes only)","tags":["tokens"],"security":[{"cookieAuth":[]}],"x-myscanity-scope":"-"},"post":{"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenCreate"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"operationId":"post_api_v1_tokens","summary":"Mint an agent token — the raw secret is returned once","description":"Body: client, password, optional name, scopes, expires_days (max. 5 aktive Tokens).","tags":["tokens"],"security":[{"cookieAuth":[]}],"x-myscanity-scope":"-"}},"/api/v1/tokens/{token_id}":{"delete":{"parameters":[{"name":"token_id","in":"path","required":true,"schema":{"type":"integer","title":"Token Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"operationId":"delete_api_v1_tokens_token_id","summary":"Revoke an agent token","tags":["tokens"],"security":[{"cookieAuth":[]}],"x-myscanity-scope":"-"}},"/api/v1/agent/me":{"get":{"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"operationId":"get_api_v1_agent_me","summary":"Token probe: identity and scopes","tags":["agent"],"security":[{"bearerAuth":[]}],"x-myscanity-scope":"any"}},"/api/v1/agent/setups":{"get":{"parameters":[{"name":"setup_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Setup Type"}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"operationId":"get_api_v1_agent_setups","summary":"Ranked stored setups with status and plan","description":"Optional ?status=tradeable|no_plan|in_portfolio|pending|blacklisted und ?setup_type=…","tags":["agent"],"security":[{"bearerAuth":[]}],"x-myscanity-scope":"setups:read"}},"/api/v1/agent/trade-plan/{ticker}":{"get":{"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","title":"Ticker"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"operationId":"get_api_v1_agent_trade-plan_ticker","summary":"Trade plan for one ticker (or the skip reason)","tags":["agent"],"security":[{"bearerAuth":[]}],"x-myscanity-scope":"setups:read"}},"/api/v1/agent/portfolio":{"get":{"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"operationId":"get_api_v1_agent_portfolio","summary":"Pending, open, and closed positions","tags":["agent"],"security":[{"bearerAuth":[]}],"x-myscanity-scope":"portfolio:read"}},"/api/v1/agent/watchlist":{"get":{"parameters":[{"name":"profile_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Profile Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"operationId":"get_api_v1_agent_watchlist","summary":"Custom watchlist of the active profile","description":"Optional ?profile_id=…","tags":["agent"],"security":[{"bearerAuth":[]}],"x-myscanity-scope":"watchlist:write"},"put":{"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentWatchlistUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"operationId":"put_api_v1_agent_watchlist","summary":"Add, remove, or replace watchlist tickers","description":"Body: add / remove / replace (replace nicht mit add/remove kombinieren). Optional Idempotency-Key.","tags":["agent"],"security":[{"bearerAuth":[]}],"x-myscanity-scope":"watchlist:write"}},"/api/v1/agent/book-review":{"post":{"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookReviewRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"operationId":"post_api_v1_agent_book-review","summary":"Ephemeral overlay of an external depot on the rotation board","description":"Wird nicht gespeichert; Antwort ist eine Momentaufnahme.","tags":["agent"],"security":[{"bearerAuth":[]}],"x-myscanity-scope":"book:review"}},"/api/v1/billing/status":{"get":{"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"operationId":"get_api_v1_billing_status","summary":"Subscription and trial status","tags":["billing"],"security":[{"cookieAuth":[]}],"x-myscanity-scope":"-"}},"/api/v1/billing/checkout":{"post":{"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"operationId":"post_api_v1_billing_checkout","summary":"Create a Stripe Checkout session (payment confirmed by the human)","description":"Liefert eine Checkout-URL; die Karte wird nie im Namen des Agenten belastet.","tags":["billing"],"security":[{"cookieAuth":[]}],"x-myscanity-scope":"-"}},"/api/v1/billing/portal":{"post":{"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"operationId":"post_api_v1_billing_portal","summary":"Open the Stripe customer portal","tags":["billing"],"security":[{"cookieAuth":[]}],"x-myscanity-scope":"-"}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"mys_<secret>","description":"Personal access token minted under Settings → Agent access. Send as `Authorization: Bearer mys_...`. New tokens also send `X-MyScanity-Client`."},"cookieAuth":{"type":"apiKey","in":"cookie","name":"trend_scanner_session","description":"Human dashboard session cookie (HttpOnly, SameSite=Lax)."}},"schemas":{"TokenCreate":{"properties":{"name":{"type":"string","maxLength":80,"title":"Name","default":""},"client":{"type":"string","maxLength":16,"minLength":1,"title":"Client"},"password":{"type":"string","minLength":1,"title":"Password"},"scopes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Scopes"},"expires_days":{"anyOf":[{"type":"integer","maximum":365.0,"minimum":1.0},{"type":"null"}],"title":"Expires Days"}},"type":"object","required":["client","password"],"title":"TokenCreate"},"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"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"LoginRequest":{"properties":{"username":{"type":"string","title":"Username"},"password":{"type":"string","title":"Password"}},"type":"object","required":["username","password"],"title":"LoginRequest"},"AgentWatchlistUpdate":{"properties":{"profile_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Profile Id"},"add":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":950},{"type":"null"}],"title":"Add"},"remove":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":950},{"type":"null"}],"title":"Remove"},"replace":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":950},{"type":"null"}],"title":"Replace"}},"type":"object","title":"AgentWatchlistUpdate","description":"Add, remove, or replace tickers on one scanner profile's watchlist."},"RegisterRequest":{"properties":{"username":{"type":"string","title":"Username"},"email":{"type":"string","title":"Email"},"password":{"type":"string","title":"Password"},"agree_tos":{"type":"boolean","title":"Agree Tos","default":false},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language"},"ref":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ref"}},"type":"object","required":["username","email","password"],"title":"RegisterRequest"},"BookReviewRequest":{"properties":{"positions":{"items":{"$ref":"#/components/schemas/BookReviewPositionIn"},"type":"array","maxItems":50,"minItems":1,"title":"Positions"}},"type":"object","required":["positions"],"title":"BookReviewRequest"},"BookReviewPositionIn":{"properties":{"ticker":{"type":"string","maxLength":32,"minLength":1,"title":"Ticker"},"weight_pct":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Weight Pct"}},"type":"object","required":["ticker"],"title":"BookReviewPositionIn"}}},"externalDocs":{"description":"Human-readable API guide","url":"https://www.myscanity.de/entwickler/api"}}