openapi: 3.1.0
info:
  title: LongkouSource Public Directory API
  version: 1.0.0
  description: Read-only API for published industry-chain, category, company and product directory records. Personal contacts, buyer leads, claim evidence, drafts and internal notes are excluded.
servers:
  - url: /
paths:
  /api/v1/chains:
    get:
      operationId: listChains
      parameters:
        - $ref: '#/components/parameters/locale'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Published industry chains
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Page' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /api/v1/categories:
    get:
      operationId: listCategories
      parameters: [{ $ref: '#/components/parameters/locale' }, { $ref: '#/components/parameters/limit' }, { $ref: '#/components/parameters/offset' }]
      responses:
        '200': { description: Published product categories, content: { application/json: { schema: { $ref: '#/components/schemas/Page' } } } }
        '429': { $ref: '#/components/responses/RateLimited' }
  /api/v1/companies:
    get:
      operationId: listCompanies
      parameters: [{ $ref: '#/components/parameters/locale' }, { $ref: '#/components/parameters/limit' }, { $ref: '#/components/parameters/offset' }]
      responses:
        '200': { description: Published company profiles with public sources and separate review statuses, content: { application/json: { schema: { $ref: '#/components/schemas/Page' } } } }
        '429': { $ref: '#/components/responses/RateLimited' }
  /api/v1/products:
    get:
      operationId: listProducts
      parameters: [{ $ref: '#/components/parameters/locale' }, { $ref: '#/components/parameters/limit' }, { $ref: '#/components/parameters/offset' }]
      responses:
        '200': { description: Published products and source-linked category relationships, content: { application/json: { schema: { $ref: '#/components/schemas/Page' } } } }
        '429': { $ref: '#/components/responses/RateLimited' }
components:
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      description: Optional higher-quota API key. Keys have allowlisted read scopes and may be revoked immediately.
  parameters:
    locale:
      name: locale
      in: query
      schema: { type: string, enum: [zh, en, ru, es, ar, ja, ko, fr, de, pt, id, hi], default: zh }
    limit:
      name: limit
      in: query
      schema: { type: integer, minimum: 1, maximum: 100, default: 50 }
    offset:
      name: offset
      in: query
      schema: { type: integer, minimum: 0, maximum: 50000, default: 0 }
  responses:
    RateLimited:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            type: object
            properties: { error: { type: string } }
  schemas:
    Page:
      type: object
      required: [apiVersion, resource, locale, total, limit, offset, data]
      properties:
        apiVersion: { type: string, const: v1 }
        resource: { type: string }
        locale: { type: string }
        total: { type: integer }
        limit: { type: integer }
        offset: { type: integer }
        nextOffset: { type: [integer, 'null'] }
        data: { type: array, items: { type: object, additionalProperties: true } }
security:
  - ApiKey: []
  - {}