> ## Documentation Index > Fetch the complete documentation index at: https://docs.joinyellowbrick.com/llms.txt > Use this file to discover all available pages before exploring further. # List pitches > Paginated write-ups. Narrow with `companyId` or `authorUsername` from search, catalog slugs or typed quality params (`authorBadge`, `authorReturn`, `winRateGte`, `pitchReturn`), and `filterSetIds`. All of those constraints AND together. Within extraTags, slugs OR within a type and AND across types. Several filter sets OR together. Paywalled pitches the key owner cannot read stay in the page with `is_locked: true` and write-up fields cleared. ## OpenAPI ````yaml /openapi.json get /api/v1/pitches openapi: 3.1.0 info: title: Yellowbrick API version: 1.0.0 description: >- Find companies and authors, read the tag vocabulary, reuse saved filter sets, then list or fetch pitches. The key identifies a Premium account. That account's access still applies on every request. servers: - url: https://www.joinyellowbrick.com description: Production - url: https://yellowbrick-staging.vercel.app description: Staging security: - bearerAuth: [] tags: - name: Search description: >- Look up companies and authors by name, ticker, username, or display name. Use the ids you get on the pitch list. - name: Tags description: >- Catalog of filter slugs and type keys, including author badge, author return, win rate, and pitch return. Send `slug` as `extraTags` or use the typed pitch-list parameters. - name: Filter Sets description: >- Saved tag combinations on the key owner's account. Pass an `id` as `filterSetIds` on the pitch list. - name: Pitches description: >- List write-ups that match search ids, tags, and filter sets, or fetch one pitch by id. paths: /api/v1/pitches: get: tags: - Pitches summary: List pitches description: >- Paginated write-ups. Narrow with `companyId` or `authorUsername` from search, catalog slugs or typed quality params (`authorBadge`, `authorReturn`, `winRateGte`, `pitchReturn`), and `filterSetIds`. All of those constraints AND together. Within extraTags, slugs OR within a type and AND across types. Several filter sets OR together. Paywalled pitches the key owner cannot read stay in the page with `is_locked: true` and write-up fields cleared. operationId: listPitches parameters: - name: x-vercel-protection-bypass in: query required: false description: >- Optional. Vercel Protection Bypass for Automation — use when calling the Staging server. schema: type: string - name: limit in: query required: false description: Page size. 1–50. Default 20. schema: default: 20 description: Page size. 1–50. Default 20. type: integer minimum: 1 maximum: 50 - name: cursor in: query required: false description: >- Opaque cursor from the previous page's `next_cursor`. Must be used with the same `sort`. schema: description: >- Opaque cursor from the previous page's `next_cursor`. Must be used with the same `sort`. type: string minLength: 1 - name: sort in: query required: false description: >- `post_date` is when Yellowbrick added the pitch. `pitch_returns` is the write-up's realized return. `investor_returns` is the author's return. schema: default: post_date description: >- `post_date` is when Yellowbrick added the pitch. `pitch_returns` is the write-up's realized return. `investor_returns` is the author's return. type: string enum: - post_date - pitch_returns - investor_returns - name: extraTags in: query required: false description: >- Tag slugs this request must match. Get every slug from GET /api/v1/tags, including author badge, author return, win rate, pitch return, sentiment, position, and paywall. Repeat the parameter or comma-separate. Slugs are grouped by type: OR within a type, AND across types. Invert a type with `extraTagsNoneOf`. Quality filters also have typed parameters (`authorBadge`, `authorReturn`, `winRateGte`, `pitchReturn`) which compile to these slugs. schema: default: [] description: >- Tag slugs this request must match. Get every slug from GET /api/v1/tags, including author badge, author return, win rate, pitch return, sentiment, position, and paywall. Repeat the parameter or comma-separate. Slugs are grouped by type: OR within a type, AND across types. Invert a type with `extraTagsNoneOf`. Quality filters also have typed parameters (`authorBadge`, `authorReturn`, `winRateGte`, `pitchReturn`) which compile to these slugs. type: array items: type: string minLength: 1 style: form explode: true - name: extraTagsNoneOf in: query required: false description: >- Tag type keys to invert in `extraTags`, not slugs. Use `tagTypeKey` from GET /api/v1/tags `sections` (for example `pitch_category`, `strategy`, `author_return`, `badge`). Pitches that match that type's extraTags slugs are excluded. schema: default: [] description: >- Tag type keys to invert in `extraTags`, not slugs. Use `tagTypeKey` from GET /api/v1/tags `sections` (for example `pitch_category`, `strategy`, `author_return`, `badge`). Pitches that match that type's extraTags slugs are excluded. type: array items: type: string minLength: 1 style: form explode: true - name: authorBadge in: query required: false description: >- Author badge: `elite` or `rising`. Repeat to include both (OR). Same filter as the `badge` slugs in GET /api/v1/tags. schema: default: [] description: >- Author badge: `elite` or `rising`. Repeat to include both (OR). Same filter as the `badge` slugs in GET /api/v1/tags. type: array items: type: string enum: - elite - rising style: form explode: true - name: authorReturn in: query required: false description: >- Author return floor. `{period}_{abs|excess}_gte_{0|10|25|50}` where period is `6m`, `1y`, or `2y`. `abs` is absolute return; `excess` is versus the market. Repeat to OR. Same values as GET /api/v1/tags `author_return` (without the `col_author_return_` prefix). schema: default: [] description: >- Author return floor. `{period}_{abs|excess}_gte_{0|10|25|50}` where period is `6m`, `1y`, or `2y`. `abs` is absolute return; `excess` is versus the market. Repeat to OR. Same values as GET /api/v1/tags `author_return` (without the `col_author_return_` prefix). type: array items: type: string enum: - 6m_abs_gte_0 - 6m_abs_gte_10 - 6m_abs_gte_25 - 6m_abs_gte_50 - 6m_excess_gte_0 - 6m_excess_gte_10 - 6m_excess_gte_25 - 6m_excess_gte_50 - 1y_abs_gte_0 - 1y_abs_gte_10 - 1y_abs_gte_25 - 1y_abs_gte_50 - 1y_excess_gte_0 - 1y_excess_gte_10 - 1y_excess_gte_25 - 1y_excess_gte_50 - 2y_abs_gte_0 - 2y_abs_gte_10 - 2y_abs_gte_25 - 2y_abs_gte_50 - 2y_excess_gte_0 - 2y_excess_gte_10 - 2y_excess_gte_25 - 2y_excess_gte_50 style: form explode: true - name: winRateGte in: query required: false description: >- Author 1-year win rate floor in percent: `50`, `60`, or `75`. Requires at least 8 pitches. Repeat to OR. schema: default: [] description: >- Author 1-year win rate floor in percent: `50`, `60`, or `75`. Requires at least 8 pitches. Repeat to OR. type: array items: type: string enum: - '50' - '60' - '75' style: form explode: true - name: pitchReturn in: query required: false description: >- Pitch return floor. `{period}_{abs|excess}_gte_pct{0|25|50|100}` or `{period}_{abs|excess}_gte_x{2|3|4|10}`. Repeat to OR. Same values as GET /api/v1/tags `pitch_return` (without the `col_pitch_return_` prefix). schema: default: [] description: >- Pitch return floor. `{period}_{abs|excess}_gte_pct{0|25|50|100}` or `{period}_{abs|excess}_gte_x{2|3|4|10}`. Repeat to OR. Same values as GET /api/v1/tags `pitch_return` (without the `col_pitch_return_` prefix). type: array items: type: string enum: - 6m_abs_gte_pct0 - 6m_abs_gte_pct25 - 6m_abs_gte_pct50 - 6m_abs_gte_pct100 - 6m_abs_gte_x2 - 6m_abs_gte_x3 - 6m_abs_gte_x4 - 6m_abs_gte_x10 - 6m_excess_gte_pct0 - 6m_excess_gte_pct25 - 6m_excess_gte_pct50 - 6m_excess_gte_pct100 - 6m_excess_gte_x2 - 6m_excess_gte_x3 - 6m_excess_gte_x4 - 6m_excess_gte_x10 - 1y_abs_gte_pct0 - 1y_abs_gte_pct25 - 1y_abs_gte_pct50 - 1y_abs_gte_pct100 - 1y_abs_gte_x2 - 1y_abs_gte_x3 - 1y_abs_gte_x4 - 1y_abs_gte_x10 - 1y_excess_gte_pct0 - 1y_excess_gte_pct25 - 1y_excess_gte_pct50 - 1y_excess_gte_pct100 - 1y_excess_gte_x2 - 1y_excess_gte_x3 - 1y_excess_gte_x4 - 1y_excess_gte_x10 - 2y_abs_gte_pct0 - 2y_abs_gte_pct25 - 2y_abs_gte_pct50 - 2y_abs_gte_pct100 - 2y_abs_gte_x2 - 2y_abs_gte_x3 - 2y_abs_gte_x4 - 2y_abs_gte_x10 - 2y_excess_gte_pct0 - 2y_excess_gte_pct25 - 2y_excess_gte_pct50 - 2y_excess_gte_pct100 - 2y_excess_gte_x2 - 2y_excess_gte_x3 - 2y_excess_gte_x4 - 2y_excess_gte_x10 style: form explode: true - name: sentiment in: query required: false description: 'Pitch sentiment: `bullish`, `bearish`, or `neutral`. Repeat to OR.' schema: default: [] description: 'Pitch sentiment: `bullish`, `bearish`, or `neutral`. Repeat to OR.' type: array items: type: string enum: - bullish - bearish - neutral style: form explode: true - name: positionDecision in: query required: false description: >- Extracted position action, such as `initiate_long` or `hold`. Repeat to OR. Full list is GET /api/v1/tags `position_decision`. schema: default: [] description: >- Extracted position action, such as `initiate_long` or `hold`. Repeat to OR. Full list is GET /api/v1/tags `position_decision`. type: array items: type: string enum: - initiate_long - initiate_short - increase_long - increase_short - reduce_long - reduce_short - close_long - close_short - hold - monitor - pass_idea - not_specified style: form explode: true - name: isPremiumPitch in: query required: false description: '`true` for paywalled write-ups, `false` for free ones.' schema: description: '`true` for paywalled write-ups, `false` for free ones.' type: string enum: - 'true' - 'false' - name: followingOnly in: query required: false description: When true, only authors the key owner follows. schema: default: false description: When true, only authors the key owner follows. type: boolean - name: authorUsername in: query required: false description: >- Author username without `@`. Get it from GET /api/v1/search (`authors[].username`). Limits the list to that author. schema: description: >- Author username without `@`. Get it from GET /api/v1/search (`authors[].username`). Limits the list to that author. type: string minLength: 1 - name: companyId in: query required: false description: >- Company id from GET /api/v1/search (`companies[].companyId`). Limits the list to pitches on that company. schema: description: >- Company id from GET /api/v1/search (`companies[].companyId`). Limits the list to pitches on that company. type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - name: addedOnFrom in: query required: false description: >- Inclusive start date (`YYYY-MM-DD`) for when Yellowbrick added the pitch. If you send only one bound, both ends use that day. schema: description: >- Inclusive start date (`YYYY-MM-DD`) for when Yellowbrick added the pitch. If you send only one bound, both ends use that day. type: string pattern: ^\d{4}-\d{2}-\d{2}$ - name: addedOnTo in: query required: false description: >- Inclusive end date (`YYYY-MM-DD`) for when Yellowbrick added the pitch. schema: description: >- Inclusive end date (`YYYY-MM-DD`) for when Yellowbrick added the pitch. type: string pattern: ^\d{4}-\d{2}-\d{2}$ - name: filterSetIds in: query required: false description: >- Saved filter set ids for the key owner. List them with GET /api/v1/filter-sets. Repeat the parameter or comma-separate. A pitch matches if it matches any listed set (OR). Combined with extraTags and the other filters using AND. Maximum 100 ids. schema: default: [] description: >- Saved filter set ids for the key owner. List them with GET /api/v1/filter-sets. Repeat the parameter or comma-separate. A pitch matches if it matches any listed set (OR). Combined with extraTags and the other filters using AND. Maximum 100 ids. maxItems: 100 type: array items: type: string minLength: 1 style: form explode: true responses: '200': description: Pitch page content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: data: type: array items: type: object properties: pitch_id: type: string description: Pitch id. Pass it to GET /api/v1/pitches/{id}. pitch_date: description: Date the author published the write-up, if known. type: - string - 'null' added_on: description: Date Yellowbrick added the pitch. type: - string - 'null' pitch: type: object properties: pitch_id: type: string pitch_date: type: - string - 'null' added_on: type: - string - 'null' pitch_title: description: Title. Null when `is_locked` is true. type: - string - 'null' pitch_summary: description: Short summary. Null when `is_locked` is true. type: - string - 'null' author_user_id: type: - string - 'null' author_username: description: Username without `@`. type: - string - 'null' author_display_name: type: - string - 'null' author_tier: description: Author tier, such as Elite or Rising. type: - string - 'null' ticker_symbol: description: Primary ticker. Null when `is_locked` is true. type: - string - 'null' company_name: description: Company name. Null when `is_locked` is true. type: - string - 'null' is_premium_pitch: type: boolean description: True when the author charges for this write-up. is_locked: type: boolean description: >- True when the write-up is paywalled and the key owner cannot read it. Title, summary, and other write-up fields are withheld. sentiment: description: Bullish, bearish, or similar. type: - string - 'null' position_decision_type: description: >- Position action extracted from the write-up, if any. type: - string - 'null' slugs: type: array items: type: string description: >- Tag slugs on the pitch. Locked items keep sector slugs only. required: - pitch_id - pitch_date - added_on - pitch_title - pitch_summary - author_user_id - author_username - author_display_name - author_tier - ticker_symbol - company_name - is_premium_pitch - is_locked - sentiment - position_decision_type - slugs additionalProperties: false required: - pitch_id - pitch_date - added_on - pitch additionalProperties: false has_more: type: boolean description: True when another page is available. next_cursor: description: Pass as `cursor` to fetch the next page. type: string head_cursor: description: Cursor for the first item on this page. type: string required: - data - has_more additionalProperties: false '400': description: Problem details (`type`, `title`, `status`, `detail`). content: application/problem+json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: type: type: string description: Stable error code, such as `premium-required`. title: type: string description: Short label for the error. status: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: HTTP status code. detail: type: string description: Human-readable explanation. required: - type - title - status - detail additionalProperties: false '401': description: Problem details (`type`, `title`, `status`, `detail`). content: application/problem+json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: type: type: string description: Stable error code, such as `premium-required`. title: type: string description: Short label for the error. status: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: HTTP status code. detail: type: string description: Human-readable explanation. required: - type - title - status - detail additionalProperties: false '403': description: Problem details (`type`, `title`, `status`, `detail`). content: application/problem+json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: type: type: string description: Stable error code, such as `premium-required`. title: type: string description: Short label for the error. status: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: HTTP status code. detail: type: string description: Human-readable explanation. required: - type - title - status - detail additionalProperties: false components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key description: 'Key from Profile. Send `Authorization: Bearer yb_...`.' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.