openapi: 3.0.3
info:
  title: Spaceflight News Articles Reports API
  version: 4.30.2
  x-api-version: v4
  x-generated-from: documentation
  x-last-validated: '2026-05-30'
  x-source-url: https://api.spaceflightnewsapi.net/v4/schema/
  description: 'The Spaceflight News API (SNAPI) is a product by [The Space Devs](https://thespacedevs.com) (TSD).

    It is the most complete and up-to-date open spaceflight news API currently available, aggregating

    articles, blog posts, and official reports from 40+ news sites across the space industry.


    While this API is **free to use**, the project encourages developers to support TSD through

    [Patreon](https://www.patreon.com/TheSpaceDevs) to keep the API running.


    ### GraphQL

    A companion GraphQL endpoint is available at [/v4/graphql/](https://api.spaceflightnewsapi.net/v4/graphql/).


    ### Launch Library 2 Integration

    Every article, blog, and report can be linked to a Launch Library 2 launch (UUID) or event (LL2 ID),

    enabling launch tracking apps to surface related news.


    ### FAQs & Tutorials

    - [TheSpaceDevs Tutorials repo](https://github.com/TheSpaceDevs/Tutorials)

    - [SNAPI FAQ](https://github.com/TheSpaceDevs/Tutorials/blob/main/faqs/faq_SNAPI.md)

    - [TSD FAQ](https://github.com/TheSpaceDevs/Tutorials/blob/main/faqs/faq_TSD.md)


    ### Feedback & Support

    Reach the team on the TSD [Discord server](https://discord.gg/p7ntkNA) (#feedback-and-help) or

    email [derk@spaceflightnewsapi.net](mailto:derk@spaceflightnewsapi.net).

    '
  contact:
    name: The Space Devs
    email: derk@spaceflightnewsapi.net
    url: https://spaceflightnewsapi.net
  license:
    name: AGPL-3.0
    url: https://github.com/TheSpaceDevs/spaceflightnewsapi/blob/main/LICENSE
servers:
- url: https://api.spaceflightnewsapi.net/v4
  description: Spaceflight News API production server (v4)
tags:
- name: Reports
  description: Official mission, program, and agency reports.
paths:
  /reports/:
    get:
      operationId: listReports
      summary: Spaceflight News List Reports
      description: List official spaceflight reports (mission reports, program updates, and agency briefings) from participating publishers. Supports full-text search, news-site filtering, published_at/updated_at date range filters, and offset/limit pagination with ordering. Note that reports do not carry launch or event relationships.
      tags:
      - Reports
      security:
      - {}
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/news_site'
      - $ref: '#/components/parameters/news_site_exclude'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/ordering'
      - $ref: '#/components/parameters/published_at_gt'
      - $ref: '#/components/parameters/published_at_gte'
      - $ref: '#/components/parameters/published_at_lt'
      - $ref: '#/components/parameters/published_at_lte'
      - $ref: '#/components/parameters/search'
      - $ref: '#/components/parameters/summary_contains'
      - $ref: '#/components/parameters/summary_contains_all'
      - $ref: '#/components/parameters/summary_contains_one'
      - $ref: '#/components/parameters/title_contains'
      - $ref: '#/components/parameters/title_contains_all'
      - $ref: '#/components/parameters/title_contains_one'
      - $ref: '#/components/parameters/updated_at_gt'
      - $ref: '#/components/parameters/updated_at_gte'
      - $ref: '#/components/parameters/updated_at_lt'
      - $ref: '#/components/parameters/updated_at_lte'
      responses:
        '200':
          description: A paginated list of reports matching the supplied filters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedReportList'
              examples:
                ListReports200Example:
                  summary: Default listReports 200 response
                  x-microcks-default: true
                  value:
                    count: 1415
                    next: https://api.spaceflightnewsapi.net/v4/reports/?limit=1&offset=1
                    previous: null
                    results:
                    - id: 1662
                      title: Starliner arrives safely back on Earth
                      authors: []
                      url: https://starlinerupdates.com/starliner-arrives-safely-back-on-earth/
                      image_url: https://boeing-jtti.s3.amazonaws.com/wp-content/uploads/2023/02/13165520/docking_with_earth_in_background_out_window.png
                      news_site: Boeing
                      summary: Boeing's Starliner landed safely at 12:01 a.m. Eastern time on Saturday, Sept. 7.
                      published_at: '2024-09-07T04:14:32Z'
                      updated_at: '2024-09-07T04:18:06.656360Z'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /reports/{id}/:
    get:
      operationId: retrieveReport
      summary: Spaceflight News Retrieve Report
      description: Retrieve a single report by its unique integer ID.
      tags:
      - Reports
      security:
      - {}
      parameters:
      - in: path
        name: id
        required: true
        description: A unique integer value identifying this report.
        schema:
          type: integer
        example: 1662
      responses:
        '200':
          description: The requested report.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Report'
              examples:
                RetrieveReport200Example:
                  summary: Default retrieveReport 200 response
                  x-microcks-default: true
                  value:
                    id: 1662
                    title: Starliner arrives safely back on Earth
                    authors: []
                    url: https://starlinerupdates.com/starliner-arrives-safely-back-on-earth/
                    image_url: https://boeing-jtti.s3.amazonaws.com/wp-content/uploads/2023/02/13165520/docking_with_earth_in_background_out_window.png
                    news_site: Boeing
                    summary: Boeing's Starliner landed safely at 12:01 a.m. Eastern time on Saturday, Sept. 7.
                    published_at: '2024-09-07T04:14:32Z'
                    updated_at: '2024-09-07T04:18:06.656360Z'
        '404':
          description: Report not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  parameters:
    updated_at_lte:
      in: query
      name: updated_at_lte
      description: Get all documents updated before a given ISO8601 timestamp (included).
      schema:
        type: string
        format: date-time
      example: '2026-12-31T23:59:59Z'
    updated_at_gt:
      in: query
      name: updated_at_gt
      description: Get all documents updated after a given ISO8601 timestamp (excluded).
      schema:
        type: string
        format: date-time
      example: '2025-01-01T00:00:00Z'
    published_at_lt:
      in: query
      name: published_at_lt
      description: Get all documents published before a given ISO8601 timestamp (excluded).
      schema:
        type: string
        format: date-time
      example: '2026-12-31T23:59:59Z'
    published_at_gt:
      in: query
      name: published_at_gt
      description: Get all documents published after a given ISO8601 timestamp (excluded).
      schema:
        type: string
        format: date-time
      example: '2025-01-01T00:00:00Z'
    title_contains:
      in: query
      name: title_contains
      description: Search for all documents with a specific phrase in the title.
      schema:
        type: string
      example: SpaceX
    updated_at_gte:
      in: query
      name: updated_at_gte
      description: Get all documents updated after a given ISO8601 timestamp (included).
      schema:
        type: string
        format: date-time
      example: '2025-01-01T00:00:00Z'
    summary_contains:
      in: query
      name: summary_contains
      description: Search for all documents with a specific phrase in the summary.
      schema:
        type: string
      example: Falcon 9
    summary_contains_all:
      in: query
      name: summary_contains_all
      description: Search for documents with a summary containing all keywords from comma-separated values.
      schema:
        type: string
      example: Starship,booster
    title_contains_one:
      in: query
      name: title_contains_one
      description: Search for documents with a title containing at least one keyword from comma-separated values.
      schema:
        type: string
      example: SpaceX,Blue Origin
    search:
      in: query
      name: search
      required: false
      description: Search for documents with a specific phrase in the title or summary.
      schema:
        type: string
      example: Starship
    summary_contains_one:
      in: query
      name: summary_contains_one
      description: Search for documents with a summary containing at least one keyword from comma-separated values.
      schema:
        type: string
      example: Falcon,Starship,Dragon
    updated_at_lt:
      in: query
      name: updated_at_lt
      description: Get all documents updated before a given ISO8601 timestamp (excluded).
      schema:
        type: string
        format: date-time
      example: '2026-12-31T23:59:59Z'
    published_at_lte:
      in: query
      name: published_at_lte
      description: Get all documents published before a given ISO8601 timestamp (included).
      schema:
        type: string
        format: date-time
      example: '2026-12-31T23:59:59Z'
    news_site:
      in: query
      name: news_site
      description: Search for documents with a news_site name present in a list of comma-separated values. Case insensitive.
      schema:
        type: string
      example: SpaceX,NASA
    news_site_exclude:
      in: query
      name: news_site_exclude
      description: Search for documents with a news_site name NOT present in a list of comma-separated values. Case insensitive.
      schema:
        type: string
      example: TechCrunch
    published_at_gte:
      in: query
      name: published_at_gte
      description: Get all documents published after a given ISO8601 timestamp (included).
      schema:
        type: string
        format: date-time
      example: '2025-01-01T00:00:00Z'
    ordering:
      in: query
      name: ordering
      description: 'Order the result on `published_at, -published_at, updated_at, -updated_at`.


        * `published_at` - Published at

        * `-published_at` - Published at (descending)

        * `updated_at` - Updated at

        * `-updated_at` - Updated at (descending)'
      schema:
        type: array
        items:
          type: string
          enum:
          - -published_at
          - -updated_at
          - published_at
          - updated_at
      explode: false
      style: form
      example:
      - -published_at
    title_contains_all:
      in: query
      name: title_contains_all
      description: Search for documents with a title containing all keywords from comma-separated values.
      schema:
        type: string
      example: Starlink,launch
    offset:
      in: query
      name: offset
      required: false
      description: The initial index from which to return the results.
      schema:
        type: integer
      example: 0
    limit:
      in: query
      name: limit
      required: false
      description: Number of results to return per page.
      schema:
        type: integer
      example: 10
  schemas:
    Report:
      type: object
      description: A spaceflight report (mission report, program update, or agency briefing) from a participating publisher.
      properties:
        id:
          type: integer
          readOnly: true
          description: Unique identifier of the report.
          example: 1662
        title:
          type: string
          maxLength: 250
          description: Title of the report.
          example: Starliner arrives safely back on Earth
        authors:
          type: array
          description: List of authors who contributed to the report.
          items:
            $ref: '#/components/schemas/Author'
        url:
          type: string
          format: uri
          maxLength: 200
          description: Canonical URL of the report on the source publisher.
          example: https://starlinerupdates.com/starliner-arrives-safely-back-on-earth/
        image_url:
          type: string
          format: uri
          maxLength: 200
          description: URL to a cover/header image for the report.
          example: https://boeing-jtti.s3.amazonaws.com/wp-content/uploads/2023/02/docking.png
        news_site:
          type: string
          readOnly: true
          description: Display name of the publisher that produced the report.
          example: Boeing
        summary:
          type: string
          description: Short summary of the report.
          example: Boeing's Starliner landed safely at 12:01 a.m. Eastern time on Saturday.
        published_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the report was originally published.
          example: '2024-09-07T04:14:32Z'
        updated_at:
          type: string
          format: date-time
          readOnly: true
          description: ISO 8601 timestamp when the report was last updated in SNAPI.
          example: '2024-09-07T04:18:06.656360Z'
      required:
      - authors
      - id
      - image_url
      - news_site
      - published_at
      - title
      - updated_at
      - url
    Author:
      type: object
      description: Author byline for an article, blog, or report.
      properties:
        name:
          type: string
          maxLength: 250
          description: Display name of the author.
          example: Will Robinson-Smith
        socials:
          $ref: '#/components/schemas/Socials'
      required:
      - name
    PaginatedReportList:
      type: object
      description: Paginated envelope wrapping a page of reports.
      required:
      - count
      - results
      properties:
        count:
          type: integer
          description: Total number of reports matching the query.
          example: 1415
        next:
          type: string
          nullable: true
          format: uri
          description: URL to fetch the next page of results, or null on the last page.
          example: https://api.spaceflightnewsapi.net/v4/reports/?limit=10&offset=20
        previous:
          type: string
          nullable: true
          format: uri
          description: URL to fetch the previous page of results, or null on the first page.
          example: https://api.spaceflightnewsapi.net/v4/reports/?limit=10&offset=0
        results:
          type: array
          description: The current page of reports.
          items:
            $ref: '#/components/schemas/Report'
    Socials:
      type: object
      description: Social media handles for an author.
      properties:
        x:
          type: string
          format: uri
          maxLength: 200
          description: URL of the author's X (Twitter) profile.
          example: https://x.com/willrobinsons
        youtube:
          type: string
          format: uri
          maxLength: 200
          description: URL of the author's YouTube channel.
          example: https://youtube.com/@author
        instagram:
          type: string
          format: uri
          maxLength: 200
          description: URL of the author's Instagram profile.
          example: https://instagram.com/author
        linkedin:
          type: string
          format: uri
          maxLength: 200
          description: URL of the author's LinkedIn profile.
          example: https://linkedin.com/in/author
        mastodon:
          type: string
          format: uri
          maxLength: 200
          description: URL of the author's Mastodon profile.
          example: https://mastodon.social/@author
        bluesky:
          type: string
          format: uri
          maxLength: 200
          description: URL of the author's Bluesky profile.
          example: https://bsky.app/profile/author.bsky.social