> ## 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.

# Get a pitch

> One write-up by id. If the author charges for it and the key owner cannot read it, the response is still 200 with `is_locked: true` and the body withheld. Yellowbrick Premium does not unlock an author's pitch. When unlocked, `archive` reports whether a snapshot is ready, which write-up formats can be downloaded, and whether an attachment artifact exists.



## OpenAPI

````yaml /openapi.json get /api/v1/pitches/{id}
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/{id}:
    get:
      tags:
        - Pitches
      summary: Get a pitch
      description: >-
        One write-up by id. If the author charges for it and the key owner
        cannot read it, the response is still 200 with `is_locked: true` and the
        body withheld. Yellowbrick Premium does not unlock an author's pitch.
        When unlocked, `archive` reports whether a snapshot is ready, which
        write-up formats can be downloaded, and whether an attachment artifact
        exists.
      operationId: getPitch
      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: id
          in: path
          required: true
          description: Pitch id from the list (`pitch_id`).
          schema:
            type: string
            minLength: 1
            description: Pitch id from the list (`pitch_id`).
      responses:
        '200':
          description: Pitch detail
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                type: object
                properties:
                  pitch_id:
                    type: string
                  pitch_date:
                    type:
                      - string
                      - 'null'
                  added_on:
                    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.
                  pitch_title:
                    type:
                      - string
                      - 'null'
                  one_liner_text:
                    description: One-line thesis, if extracted.
                    type:
                      - string
                      - 'null'
                  pitch_summary:
                    type:
                      - string
                      - 'null'
                  pitch_full_text:
                    description: Full write-up. Null when `is_locked` is true.
                    type:
                      - string
                      - 'null'
                  source_url:
                    description: Original post URL. May be withheld when locked.
                    type:
                      - string
                      - 'null'
                  archive:
                    anyOf:
                      - type: object
                        properties:
                          available:
                            type: boolean
                            description: True when a signed document download is ready.
                          status:
                            description: >-
                              Archive pipeline status, such as `ok` or
                              `pending`.
                            type:
                              - string
                              - 'null'
                          formats:
                            type: array
                            items:
                              type: string
                              enum:
                                - pdf
                                - mhtml
                                - md
                            description: >-
                              Downloadable write-up formats for the latest
                              snapshot (pdf, mhtml, md).
                          has_attachment:
                            type: boolean
                            description: >-
                              True when the snapshot includes a linked
                              attachment (`document.attachment.pdf`).
                          snapshot:
                            description: Latest snapshot id when an archive exists.
                            type:
                              - string
                              - 'null'
                          request:
                            type: object
                            properties:
                              requested:
                                type: boolean
                                description: True when a reader has requested an archive.
                              requested_by_username:
                                type:
                                  - string
                                  - 'null'
                              requested_at:
                                description: ISO-8601 timestamp of the archive request.
                                type:
                                  - string
                                  - 'null'
                            required:
                              - requested
                              - requested_by_username
                              - requested_at
                            additionalProperties: false
                        required:
                          - available
                          - status
                          - formats
                          - has_attachment
                          - snapshot
                          - request
                        additionalProperties: false
                      - type: 'null'
                    description: Archive availability. Null when the pitch is locked.
                  extracted_data:
                    anyOf:
                      - type: object
                        propertyNames:
                          type: string
                        additionalProperties: {}
                      - type: 'null'
                    description: Structured fields extracted from the write-up.
                  investor_returns:
                    type: object
                    properties:
                      returns_1m:
                        description: >-
                          Return as a decimal or numeric string. Null when
                          unknown.
                        type:
                          - string
                          - number
                          - 'null'
                      returns_3m:
                        description: >-
                          Return as a decimal or numeric string. Null when
                          unknown.
                        type:
                          - string
                          - number
                          - 'null'
                      returns_6m:
                        description: >-
                          Return as a decimal or numeric string. Null when
                          unknown.
                        type:
                          - string
                          - number
                          - 'null'
                      returns_1y:
                        description: >-
                          Return as a decimal or numeric string. Null when
                          unknown.
                        type:
                          - string
                          - number
                          - 'null'
                      returns_2y:
                        description: >-
                          Return as a decimal or numeric string. Null when
                          unknown.
                        type:
                          - string
                          - number
                          - 'null'
                      returns_latest:
                        description: >-
                          Return as a decimal or numeric string. Null when
                          unknown.
                        type:
                          - string
                          - number
                          - 'null'
                    required:
                      - returns_1m
                      - returns_3m
                      - returns_6m
                      - returns_1y
                      - returns_2y
                      - returns_latest
                    additionalProperties: false
                  author:
                    type: object
                    properties:
                      author_user_id:
                        type:
                          - string
                          - 'null'
                      author_username:
                        type:
                          - string
                          - 'null'
                      author_display_name:
                        type:
                          - string
                          - 'null'
                      author_tier:
                        type:
                          - string
                          - 'null'
                      author_profile_image_uri:
                        type:
                          - string
                          - 'null'
                    required:
                      - author_user_id
                      - author_username
                      - author_display_name
                      - author_tier
                      - author_profile_image_uri
                    additionalProperties: false
                  company:
                    type: object
                    properties:
                      company_id:
                        type:
                          - number
                          - 'null'
                      ticker_symbol:
                        type:
                          - string
                          - 'null'
                      company_name:
                        type:
                          - string
                          - 'null'
                      company_logo_url:
                        type:
                          - string
                          - 'null'
                      country_name:
                        type:
                          - string
                          - 'null'
                      iso_country_code:
                        type:
                          - string
                          - 'null'
                      business_description:
                        type:
                          - string
                          - 'null'
                      currency_code:
                        type:
                          - string
                          - 'null'
                    required:
                      - company_id
                      - ticker_symbol
                      - company_name
                      - company_logo_url
                      - country_name
                      - iso_country_code
                      - business_description
                      - currency_code
                    additionalProperties: false
                  industry_description:
                    type:
                      - string
                      - 'null'
                  fundamentals:
                    type: object
                    properties:
                      market_cap:
                        type:
                          - string
                          - 'null'
                      pitch_price:
                        type:
                          - string
                          - 'null'
                      ev_ebitda:
                        type:
                          - string
                          - 'null'
                      pe:
                        type:
                          - string
                          - 'null'
                      ev_sales:
                        type:
                          - string
                          - 'null'
                      sector:
                        type:
                          - string
                          - 'null'
                    required:
                      - market_cap
                      - pitch_price
                      - ev_ebitda
                      - pe
                      - ev_sales
                      - sector
                    additionalProperties: false
                  analytics:
                    type: object
                    properties:
                      sentiment:
                        type:
                          - string
                          - 'null'
                      position_decision_type:
                        type:
                          - string
                          - 'null'
                      return_1w:
                        description: >-
                          Return as a decimal or numeric string. Null when
                          unknown.
                        type:
                          - string
                          - number
                          - 'null'
                      return_1m:
                        description: >-
                          Return as a decimal or numeric string. Null when
                          unknown.
                        type:
                          - string
                          - number
                          - 'null'
                      return_3m:
                        description: >-
                          Return as a decimal or numeric string. Null when
                          unknown.
                        type:
                          - string
                          - number
                          - 'null'
                      return_6m:
                        description: >-
                          Return as a decimal or numeric string. Null when
                          unknown.
                        type:
                          - string
                          - number
                          - 'null'
                      return_1y:
                        description: >-
                          Return as a decimal or numeric string. Null when
                          unknown.
                        type:
                          - string
                          - number
                          - 'null'
                      return_latest:
                        description: >-
                          Return as a decimal or numeric string. Null when
                          unknown.
                        type:
                          - string
                          - number
                          - 'null'
                    required:
                      - sentiment
                      - position_decision_type
                      - return_1w
                      - return_1m
                      - return_3m
                      - return_6m
                      - return_1y
                      - return_latest
                    additionalProperties: false
                  tags:
                    type: array
                    items:
                      type: string
                    description: Tag slugs on this pitch.
                  thesis:
                    type: object
                    properties:
                      thesis_id:
                        description: >-
                          Id grouping this write-up with earlier and later
                          updates.
                        type:
                          - string
                          - 'null'
                      previous_pitches:
                        type: array
                        items:
                          type: object
                          properties:
                            pitch_id:
                              type: string
                            pitch_title:
                              type:
                                - string
                                - 'null'
                            pitch_date:
                              type:
                                - string
                                - 'null'
                            sentiment:
                              type:
                                - string
                                - 'null'
                            position_decision_type:
                              type:
                                - string
                                - 'null'
                            is_premium_pitch:
                              type: boolean
                              description: True when the author charges for this write-up.
                          required:
                            - pitch_id
                            - pitch_title
                            - pitch_date
                            - sentiment
                            - position_decision_type
                            - is_premium_pitch
                          additionalProperties: false
                      next_pitches:
                        type: array
                        items:
                          type: object
                          properties:
                            pitch_id:
                              type: string
                            pitch_title:
                              type:
                                - string
                                - 'null'
                            pitch_date:
                              type:
                                - string
                                - 'null'
                            sentiment:
                              type:
                                - string
                                - 'null'
                            position_decision_type:
                              type:
                                - string
                                - 'null'
                            is_premium_pitch:
                              type: boolean
                              description: True when the author charges for this write-up.
                          required:
                            - pitch_id
                            - pitch_title
                            - pitch_date
                            - sentiment
                            - position_decision_type
                            - is_premium_pitch
                          additionalProperties: false
                    required:
                      - thesis_id
                      - previous_pitches
                      - next_pitches
                    additionalProperties: false
                required:
                  - pitch_id
                  - pitch_date
                  - added_on
                  - is_premium_pitch
                  - is_locked
                  - pitch_title
                  - one_liner_text
                  - pitch_summary
                  - pitch_full_text
                  - source_url
                  - archive
                  - extracted_data
                  - investor_returns
                  - author
                  - company
                  - industry_description
                  - fundamentals
                  - analytics
                  - tags
                  - thesis
                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
        '404':
          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.