openapi: 3.1.0
info:
  title: ProcureRadar Agent API
  description: |
    Supplier-side buyer intelligence for AI agents (ChatGPT Custom GPT Actions, n8n, ERP).
    Discovery layer (buyer search) is free with a zk_ API key.
    Intelligence and contact unlock use POST /api/ai-ops/skills/execute (Zhimao Points).
  version: "1.0.0"
  contact:
    url: https://www.procureradar.com/enterprise/api-access
servers:
  - url: https://www.procureradar.com
security:
  - BearerAuth: []
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API Key from Workspace → API Key Management (prefix zk_)
  schemas:
    Buyer:
      type: object
      properties:
        id: { type: string }
        company_name: { type: string, nullable: true }
        company_name_en: { type: string, nullable: true }
        country: { type: string, nullable: true, description: ISO 3166-1 alpha-2 }
        city: { type: string, nullable: true }
        quality_grade:
          type: string
          enum: [premium, qualified]
        entity_type: { type: string, nullable: true }
        has_email: { type: boolean }
        has_phone: { type: boolean }
        buyer_profile_url: { type: string, format: uri }
paths:
  /api/agent/v1/buyers:
    get:
      operationId: findBuyers
      summary: Search verified importers by product category and country
      description: Free discovery layer. Returns company profiles without contact details.
      parameters:
        - name: category
          in: query
          required: true
          schema: { type: string }
          description: Product category (e.g. flour, LED lighting)
        - name: country_iso
          in: query
          schema: { type: string }
          description: ISO 3166-1 alpha-2 (e.g. MY, ID, KE)
        - name: quality_grade
          in: query
          schema:
            type: string
            enum: [premium, qualified]
        - name: limit
          in: query
          schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
      responses:
        "200":
          description: Buyer list with coverage metadata
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok: { type: boolean }
                  total: { type: integer }
                  buyers:
                    type: array
                    items: { $ref: "#/components/schemas/Buyer" }
        "400":
          description: Missing category
        "429":
          description: Anonymous rate limit — add Bearer zk_ token
  /api/agent/v1/tasks/{id}:
    get:
      operationId: pollAcquisitionTask
      summary: Poll background buyer acquisition task
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Task status and buyers when completed
  /api/agent/v1/group-buy:
    get:
      operationId: listGroupBuyPools
      summary: List open collective sourcing (联拼宝) projects
      parameters:
        - name: category
          in: query
          schema: { type: string }
        - name: status
          in: query
          schema:
            type: string
            enum: [open, filling]
            default: open
        - name: currency
          in: query
          schema: { type: string, default: USD }
      responses:
        "200":
          description: Pool list
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok: { type: boolean }
                  total: { type: integer }
                  pools: { type: array, items: { type: object } }