openapi: "3.0.3"
info:
  title: Postman Explore API
  description: |
    Undocumented internal API powering the Postman API Network explore site (postman.com/explore).
    All requests go through a proxy endpoint as POST requests with a JSON body containing
    {service, method, path, body?}. This spec models the logical endpoints directly.

    No authentication required for public browsing and search.
  version: "1.0.0"
  contact:
    name: Postman Explore (Community)

servers:
  - url: https://www.postman.com/_api/ws/proxy
    description: Postman web proxy (all requests are POST with service/method/path body)

tags:
  - name: browse
    description: Browse public collections, workspaces, APIs, and flows
  - name: search
    description: Full-text search across the public API network
  - name: categories
    description: API categories for filtering
  - name: teams
    description: Publisher teams on the API network
  - name: stats
    description: Network-wide statistics

paths:
  /v1/api/networkentity:
    get:
      operationId: listNetworkEntities
      summary: Browse public entities on the API network
      description: |
        List public collections, workspaces, APIs, or flows with optional sorting,
        category filtering, and pagination. This is the primary browse endpoint
        powering postman.com/explore/collections.
      tags: [browse]
      parameters:
        - name: entityType
          in: query
          required: true
          description: Type of entity to browse
          schema:
            type: string
            enum: [collection, workspace, api, flow]
        - name: limit
          in: query
          description: Number of results per page
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
        - name: offset
          in: query
          description: Pagination offset
          schema:
            type: integer
            default: 0
            minimum: 0
        - name: sort
          in: query
          description: Sort order for results
          schema:
            type: string
            enum: [popular, recent, featured, new, week, alltime]
            default: popular
        - name: categoryId
          in: query
          description: Filter by category ID (numeric, from categories endpoint)
          schema:
            type: integer
      responses:
        "200":
          description: Paginated list of entities
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NetworkEntityListResponse"
        "400":
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RateLimitError"

  /v1/api/networkentity/count:
    get:
      operationId: getNetworkEntityCounts
      summary: Get total counts of entities on the network
      description: Returns aggregate counts of collections, workspaces, APIs, flows, notebooks, and teams.
      tags: [stats]
      parameters:
        - name: flattenAPIVersions
          in: query
          schema:
            type: boolean
            default: true
      responses:
        "200":
          description: Entity counts
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EntityCountResponse"

  /search-all:
    post:
      operationId: searchAll
      summary: Full-text search across the public API network
      description: |
        Search for collections, workspaces, requests, flows, and teams by text query.
        Supports filtering by entity type via queryIndices and pagination via from/size.
        This powers the search bar at postman.com/search.
      tags: [search]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SearchRequest"
      responses:
        "200":
          description: Search results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchResponse"

  /v2/api/category:
    get:
      operationId: listCategories
      summary: List all API categories
      description: Returns all categories used to organize the API network (e.g., AI, Communication, DevOps).
      tags: [categories]
      parameters:
        - name: sort
          in: query
          description: Sort order
          schema:
            type: string
            enum: [spotlighted]
            default: spotlighted
      responses:
        "200":
          description: List of categories
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CategoryListResponse"

  /v2/api/category/{slug}:
    get:
      operationId: getCategory
      summary: Get details for a specific category
      description: Returns full details for a category by its URL slug.
      tags: [categories]
      parameters:
        - name: slug
          in: path
          required: true
          description: Category URL slug (e.g., artificial-intelligence, devops)
          schema:
            type: string
      responses:
        "200":
          description: Category details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CategoryDetailResponse"

  /v1/api/team:
    get:
      operationId: listTeams
      summary: List publisher teams on the API network
      description: Returns teams that publish collections and APIs on the network.
      tags: [teams]
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
        - name: sort
          in: query
          schema:
            type: string
            enum: [popular]
            default: popular
      responses:
        "200":
          description: List of teams
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TeamListResponse"

components:
  schemas:
    NetworkEntity:
      type: object
      description: A public entity (collection, workspace, API, or flow) on the Postman API Network
      properties:
        id:
          type: integer
          description: Internal network entity ID
        entityId:
          type: string
          description: Unique entity identifier (format varies by type)
        entityType:
          type: string
          enum: [collection, workspace, api, flow]
        name:
          type: string
          description: Display name of the entity
        summary:
          type: string
          description: Short summary
        description:
          type: string
          description: Full description (may contain HTML/Markdown)
        type:
          type: string
          enum: [public]
        metrics:
          type: array
          items:
            $ref: "#/components/schemas/Metric"
        publisherType:
          type: string
          enum: [team, user]
        publisherId:
          type: integer
        createdBy:
          type: integer
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        categories:
          type: array
          items:
            $ref: "#/components/schemas/CategorySummary"
        tags:
          type: array
          items:
            type: string
        meta:
          type: object
          properties:
            publisherId:
              type: string
            workspaceId:
              type: string
            publisherType:
              type: string
            workspaceSlug:
              type: string
        redirectURL:
          type: string
          format: uri
          description: URL to view this entity on postman.com
        redirectURLV2:
          type: string
          format: uri
          description: V2 URL with slug-based path

    Metric:
      type: object
      properties:
        metricName:
          type: string
          enum:
            - forkCount
            - monthForkCount
            - monthViewCount
            - monthWatchCount
            - publicViewCount
            - viewCount
            - watchCount
            - weekForkCount
            - weekViewCount
            - weekWatchCount
        metricValue:
          type: integer

    CategorySummary:
      type: object
      properties:
        id:
          type: integer
        slug:
          type: string
        name:
          type: string
        isDeleted:
          type: boolean

    Category:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        summary:
          type: string
        description:
          type: string
        heroImageURL:
          type: string
          format: uri
        iconURL:
          type: string
          format: uri
        slug:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        publicURL:
          type: string
          format: uri

    Team:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        categories:
          type: array
          items:
            $ref: "#/components/schemas/CategorySummary"
        tags:
          type: array
          items:
            type: string
        profileURL:
          type: string
          format: uri
        publicURL:
          type: string
          format: uri
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        metrics:
          type: array
          items:
            type: object
            properties:
              team:
                type: string
              viewCount:
                type: integer
              teamPublisherScore:
                type: integer
              apinetworkentityCount:
                type: integer
              collectionCount:
                type: integer
              apiCount:
                type: integer
              workspaceCount:
                type: integer

    SearchRequest:
      type: object
      required: [queryText, size, queryIndices]
      properties:
        queryText:
          type: string
          description: Search query text
        size:
          type: integer
          description: Number of results to return
          default: 10
        from:
          type: integer
          description: Pagination offset
          default: 0
        domain:
          type: string
          description: Search domain scope
          enum: [all, public]
          default: public
        queryIndices:
          type: array
          description: Entity types to search across
          items:
            type: string
            enum:
              - runtime.collection
              - collaboration.workspace
              - runtime.request
              - flow.flow
              - apinetwork.team
        mergeEntities:
          type: boolean
          default: true
        nested:
          type: boolean
          default: false
        nonNestedRequests:
          type: boolean
          default: true
        filter:
          type: object
          description: Additional filters (empty object for no filters)

    SearchResult:
      type: object
      properties:
        score:
          type: number
          description: Relevance score
        normalizedScore:
          type: number
          description: Normalized relevance score
        document:
          type: object
          properties:
            id:
              type: string
              description: Entity ID
            name:
              type: string
            summary:
              type: string
            entityType:
              type: string
              enum: [collection, workspace, request, flow, team]
            documentType:
              type: string
            isPublic:
              type: boolean
            isPublisherVerified:
              type: boolean
            publisherName:
              type: string
            publisherHandle:
              type: string
            publisherType:
              type: string
              enum: [team, user]
            publisherLogo:
              type: string
            categories:
              type: array
              items:
                type: object
            tags:
              type: array
              items:
                type: string
            views:
              type: integer
            forkCount:
              type: integer
            watcherCount:
              type: integer
            requestCount:
              type: integer
            workspaces:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  slug:
                    type: string
                  visibilityStatus:
                    type: string

    NetworkEntityListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/NetworkEntity"
        meta:
          type: object
          properties:
            limit:
              type: integer
            offset:
              type: integer
            count:
              type: integer
            totalCount:
              type: integer
            publisherInfo:
              type: object
              description: Map of publisher type to array of publisher details
            model:
              type: string
            action:
              type: string

    EntityCountResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            apiCount:
              type: integer
            collectionCount:
              type: integer
            flowCount:
              type: integer
            notebookCount:
              type: integer
            workspaceCount:
              type: integer
            teamCount:
              type: integer
        meta:
          type: object

    CategoryListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Category"

    CategoryDetailResponse:
      type: object
      properties:
        data:
          $ref: "#/components/schemas/Category"

    TeamListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Team"

    SearchResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/SearchResult"
        meta:
          type: object
          properties:
            total:
              type: integer
            nextCursor:
              type: string

    ErrorResponse:
      type: object
      properties:
        name:
          type: string
        message:
          type: string

    RateLimitError:
      type: object
      properties:
        error:
          type: string
          enum: [rateLimited]
        message:
          type: string