---
title: "Api Explain Paper Position"
method: GET
path: "/api/ai/explain-position"
---

# Api Explain Paper Position

`GET /api/ai/explain-position`

## Request

- Base URL: `https://www.oxfordledge.com` (the document declares no server; this is the origin it was published from)
- URL: `https://www.oxfordledge.com/api/ai/explain-position`
- Auth: none declared

Return an explanation of why the user's paper position in
`ticker` is up/down. Auth-gated (per-user portfolio data). No
CSRF dep — read-only GET, no mutation. Cost cap enforced in
the service layer.

## Query parameters

- `ticker` string, required

## Response `200`

Successful Response

- PaperPositionExplainerResponse: `GET /api/ai/explain-position` — paper-position AI explainer. Required fields: ok, ticker, explanation, disclosure, source. Frontend dereferences these without null-check; declared REQUIRED so the error envelope can't drift to a shape that NPEs the UI. `source` is the discriminator the FE uses for visual treatment: "deterministic" → templated paragraph (no LLM available) "llm_polished" → Anthropic Haiku rewrite (PLATFORM_AI_KEY set) "rate_limited" → user hit daily cap; explanation describes why "no_position" → user doesn't hold this ticker "error" → generation failed; explanation has the reason
  - `ok` boolean, required: True on successful explanation; False on cap-hit / no-position / error.
  - `ticker` string, required: Resolved + uppercased ticker (empty on validation error).
  - `explanation` string, required: Multi-paragraph plain-text explanation.
  - `disclosure` string, required: Mandatory advice-disclosure footer.
  - `source` string, required: deterministic | llm_polished | rate_limited | no_position | error.
  - `calls_today` integer, required: User's explainer call count today (post-increment).
  - `daily_cap` integer, required: Per-user daily cap on explainer calls.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/oxfordledge/apis/oxford-ledge-api.md) · [All operations](https://skmtc.dev/oxfordledge/apis/oxford-ledge-api/llms.txt) · [OpenAPI document](https://skmtc.dev/oxfordledge/apis/oxford-ledge-api/revisions/e832a1260f0b?raw)