openapi: 3.1.0
info:
  title: Liyu Pinche Readonly API for ChatGPT Actions Candidate
  version: 2026-07-02.five-tool-readonly-candidate
  description: Readonly candidate for Liyu Pinche ride search, ride detail, official group search, and capability discovery. No publish, edit, delete, reserve, call, message, export, or private contact exposure.
servers:
  - url: https://www.pcsfc.com
security:
  - ApiKeyAuth: []
paths:
  /lypinche/capabilities:
    get:
      operationId: getLiyuCapabilities
      x-openai-isConsequential: false
      summary: Get readonly API capabilities
      description: Returns supported readonly tools, data boundaries, privacy limits, and recommended first calls. Use for integration self-checks, not concrete route answers.
      responses:
        "200":
          description: Capability list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StandardResponse"
  /lypinche/smart:
    post:
      operationId: smartRideSearch
      x-openai-isConsequential: false
      summary: Natural language ride search
      description: Searches real Liyu Pinche data from a natural language ride question. Do not invent rides, prices, contacts, groups, success rates, or guarantees.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - query
                - page_size
              properties:
                query:
                  type: string
                  minLength: 1
                  maxLength: 200
                  description: User ride question in natural language, such as route, date, or ride type.
                page_size:
                  type: integer
                  minimum: 1
                  maximum: 5
                  default: 3
                  description: Maximum returned ride count. Keep small for concise model answers.
            examples:
              route:
                value:
                  query: 明天济南到北京有没有顺风车
                  page_size: 3
      responses:
        "200":
          description: Smart search result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StandardResponse"
  /lypinche/search:
    post:
      operationId: searchRides
      x-openai-isConsequential: false
      summary: Structured ride search
      description: Searches public ride records when departure and destination are already known. Treat validity fields as authoritative and never expose full private contact data.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - departure
                - destination
                - type
                - date
                - page
                - page_size
              properties:
                departure:
                  type: string
                  minLength: 1
                  maxLength: 50
                  description: Departure place.
                destination:
                  type: string
                  minLength: 1
                  maxLength: 50
                  description: Destination place.
                type:
                  type:
                    - integer
                    - "null"
                  enum: [1, 2, 3, 4, null]
                  description: Ride type: 1 passenger seeks ride, 2 driver offers seats, 3 vehicle seeks cargo, 4 cargo seeks vehicle; null if unknown.
                date:
                  type:
                    - string
                    - "null"
                  maxLength: 20
                  description: Travel date text or YYYY-MM-DD; null if unknown.
                page:
                  type: integer
                  minimum: 1
                  maximum: 5
                  default: 1
                page_size:
                  type: integer
                  minimum: 1
                  maximum: 5
                  default: 3
            examples:
              route:
                value:
                  departure: 济南
                  destination: 北京
                  type: null
                  date: null
                  page: 1
                  page_size: 3
      responses:
        "200":
          description: Structured ride search result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StandardResponse"
  /lypinche/pcdetail:
    get:
      operationId: getRideDetail
      x-openai-isConsequential: false
      summary: Get public ride detail
      description: Returns public detail for one ride id from search results. Contact fields may be masked or absent; never reconstruct hidden digits or private contact data.
      parameters:
        - name: info_id
          in: query
          required: true
          description: Ride information id returned by smartRideSearch or searchRides.
          schema:
            type: integer
            minimum: 1
      responses:
        "200":
          description: Public ride detail
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StandardResponse"
  /lypinche:
    get:
      operationId: searchGroups
      x-openai-isConsequential: false
      summary: Search official ride groups
      description: Searches official Liyu Pinche group entry pages for a route or place. Return entry_page_url only; do not expose raw QR code paths or private group assets.
      parameters:
        - name: action
          in: query
          required: true
          description: Must be groups for this ChatGPT Actions candidate.
          schema:
            type: string
            enum:
              - groups
        - name: version
          in: query
          required: true
          description: API version.
          schema:
            type: string
            enum:
              - v1
            default: v1
        - name: keyword
          in: query
          required: true
          description: Group search keyword, for example 曹县青岛拼车群.
          schema:
            type: string
            minLength: 1
            maxLength: 80
        - name: departure
          in: query
          required: false
          description: Optional departure place.
          schema:
            type: string
            maxLength: 50
        - name: destination
          in: query
          required: false
          description: Optional destination place.
          schema:
            type: string
            maxLength: 50
        - name: limit
          in: query
          required: true
          description: Maximum returned group count. Keep small for concise model answers.
          schema:
            type: integer
            minimum: 1
            maximum: 5
            default: 3
        - name: include_detail
          in: query
          required: true
          description: Must be 0 to avoid large or sensitive detail payloads in this candidate.
          schema:
            type: string
            enum:
              - "0"
            default: "0"
      responses:
        "200":
          description: Official group search result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StandardResponse"
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Liyu-Api-Key
      description: Readonly API key configured in the platform UI. Do not include this value in prompts, examples, logs, or public files.
  schemas:
    StandardResponse:
      type: object
      additionalProperties: true
      required:
        - code
        - message
        - data
      properties:
        code:
          type: integer
          description: 0 means success; nonzero means business, auth, rate limit, or validation error.
        message:
          type: string
        data:
          type:
            - object
            - "null"
          description: Tool-specific readonly data. Prefer structured fields over natural language when answering.
        meta:
          type:
            - object
            - "null"
          description: Optional freshness, source, cache, or request metadata.
        request_id:
          type:
            - string
            - "null"
          description: Request trace id when provided.
