openapi: 3.0.1
info:
  title: Z.AI Agents Tools API API
  description: Z.AI API available endpoints
  license:
    name: Z.AI Developer Agreement and Policy
    url: https://chat.z.ai/legal-agreement/terms-of-service
  version: 1.0.0
  contact:
    name: Z.AI Developers
    url: https://chat.z.ai/legal-agreement/privacy-policy
    email: user_feedback@z.ai
servers:
- url: https://api.z.ai/api
  description: Production server
security:
- bearerAuth: []
tags:
- name: Tools API
paths:
  /paas/v4/reader:
    post:
      tags:
      - Tools API
      summary: Web Reader
      description: Reads and parses the content of the specified URL. Supports selectable return formats, cache control, image retention, and summary options.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReaderRequest'
            examples:
              Basic:
                value:
                  url: https://www.example.com
        required: true
      responses:
        '200':
          description: Processing successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReaderResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      required:
      - code
      - message
      type: object
      description: The request has failed.
      properties:
        code:
          type: integer
          format: int32
          description: Error code.
        message:
          type: string
          description: Error message.
    ReaderRequest:
      type: object
      properties:
        url:
          type: string
          description: The URL to retrieve
        timeout:
          type: integer
          description: Request timeout in seconds. Default is 20
          default: 20
        no_cache:
          type: boolean
          description: Whether to disable caching (true/false). Default is false
          default: false
        return_format:
          type: string
          description: Return format (e.g., markdown, text). Default is markdown
          default: markdown
        retain_images:
          type: boolean
          description: Whether to retain images (true/false). Default is true
          default: true
        no_gfm:
          type: boolean
          description: Whether to disable GitHub Flavored Markdown (true/false). Default is false
          default: false
        keep_img_data_url:
          type: boolean
          description: Whether to keep image data URLs (true/false). Default is false
          default: false
        with_images_summary:
          type: boolean
          description: Whether to include image summary (true/false). Default is false
          default: false
        with_links_summary:
          type: boolean
          description: Whether to include links summary (true/false). Default is false
          default: false
      required:
      - url
    ReaderResponse:
      type: object
      properties:
        id:
          type: string
          description: Task ID
        created:
          type: integer
          format: int64
          description: Request creation time as a Unix timestamp in seconds
        request_id:
          type: string
          description: Client-provided unique identifier to distinguish requests. If not provided, the platform will generate one.
        model:
          type: string
          description: Model code
        reader_result:
          type: object
          description: Web reading result
          properties:
            content:
              type: string
              description: Main content parsed from the page (body, images, links, etc.)
            description:
              type: string
              description: Brief description of the page
            title:
              type: string
              description: Page title
            url:
              type: string
              description: Original page URL
            external:
              type: object
              description: External resources referenced by the page
              properties:
                stylesheet:
                  type: object
                  description: Collection of external stylesheets
                  additionalProperties:
                    type: object
                    properties:
                      type:
                        type: string
                        description: Stylesheet MIME type, typically `text/css`
            metadata:
              type: object
              description: Page metadata
              properties:
                keywords:
                  type: string
                  description: Page keywords
                viewport:
                  type: string
                  description: Viewport settings
                description:
                  type: string
                  description: Meta description
                format-detection:
                  type: string
                  description: Format detection settings, e.g., `telephone=no`
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Use the following format for authentication: Bearer [<your api key>](https://z.ai/manage-apikey/apikey-list)'