{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/linkdigest-dev/json-schema/linkdigest-dev-search-schema.json",
  "title": "Search",
  "description": "Search results, and the batch over them when one was asked for.",
  "x-generated": "2026-11-17",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/linkdigest-dev-openapi.json#/components/schemas/Search",
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "The topic, as searched."
    },
    "platform": {
      "type": "string",
      "description": "Where it looked."
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "One result.",
        "properties": {
          "url": {
            "type": "string",
            "description": "A post link digest_url can read."
          },
          "title": {
            "type": "string",
            "description": "Its title."
          },
          "snippet": {
            "type": "string",
            "description": "Its summary line."
          },
          "posted_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "douyin and xiaohongshu: the day the post went up (YYYY-MM-DD, UTC), read from its id."
          }
        }
      },
      "description": "The links found, in rank order: on douyin and xiaohongshu, the posts that carry the words searched, newest first."
    },
    "credits": {
      "type": "integer",
      "description": "What the search cost: 4 on douyin and xiaohongshu, 1 elsewhere, 0 when nothing was found."
    },
    "own_browser_url": {
      "type": [
        "string",
        "null"
      ],
      "description": "xiaohongshu only: the same search in the user's own logged-in browser — the whole platform. The extension reads it there; GET /digest/batches?label=<query> picks the batch up."
    },
    "batch_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "With digest: the batch started over the results."
    },
    "batch": {
      "$ref": "#/$defs/Batch"
    }
  },
  "$defs": {
    "Batch": {
      "type": "object",
      "description": "A batch of links.",
      "properties": {
        "batch_id": {
          "type": "string",
          "description": "The batch id."
        },
        "label": {
          "type": [
            "string",
            "null"
          ],
          "description": "What the batch was called, or null."
        },
        "status": {
          "type": "string",
          "description": "running or done."
        },
        "total": {
          "type": "integer",
          "description": "Links in the batch."
        },
        "done": {
          "type": "integer",
          "description": "Finished."
        },
        "failed": {
          "type": "integer",
          "description": "Failed."
        },
        "credits_total": {
          "type": "integer",
          "description": "Credits spent so far."
        },
        "poll": {
          "type": "string",
          "description": "The path to poll."
        },
        "breakdown": {
          "type": "boolean",
          "description": "Whether every link is taken apart."
        },
        "ask": {
          "type": [
            "string",
            "null"
          ],
          "description": "The question every link was asked, or null."
        },
        "insight": {
          "type": "boolean",
          "description": "Whether every link's consumer insight was drawn."
        },
        "depth": {
          "type": "string",
          "description": "full, transcript or script: how every video in the batch is read.",
          "enum": [
            "full",
            "transcript",
            "script"
          ]
        },
        "synthesis": {
          "$ref": "#/$defs/Synthesis"
        },
        "synthesis_credits": {
          "type": "integer",
          "description": "What the comparison cost (only on a batch that asked for synthesis)."
        },
        "synthesis_error": {
          "type": [
            "string",
            "null"
          ],
          "description": "Why the comparison failed, or null (only on a batch that asked for synthesis)."
        },
        "items": {
          "type": "array",
          "items": {
            "type": "object",
            "description": "One link.",
            "properties": {
              "url": {
                "type": "string",
                "description": "The link."
              },
              "status": {
                "type": "string",
                "description": "queued, running, done or error."
              },
              "cache_key": {
                "type": "string",
                "description": "Where the digest is stored."
              },
              "credits": {
                "type": "integer",
                "description": "What it cost."
              },
              "error": {
                "type": "string",
                "description": "Why it failed, if it did."
              }
            }
          },
          "description": "Every link and its state."
        }
      }
    },
    "Synthesis": {
      "type": [
        "object",
        "null"
      ],
      "description": "批量综合 — one comparison over every link the batch read. Present only on a batch that asked for synthesis=true (null while it runs, or when it failed — synthesis_error says why and nothing was charged). 1 credit per started 10 notes, once per batch.",
      "properties": {
        "language": {
          "type": "string",
          "description": "The language the synthesis is written in, e.g. zh-CN or en."
        },
        "notes": {
          "type": "integer",
          "description": "How many notes were compared."
        },
        "summary": {
          "type": "string",
          "description": "The comparison in a paragraph."
        },
        "themes": {
          "type": "array",
          "items": {
            "type": "object",
            "description": "A theme the notes share.",
            "properties": {
              "text": {
                "type": "string",
                "description": "The point, in the synthesis's language."
              },
              "count": {
                "type": "integer",
                "description": "How many of the notes it was seen in."
              }
            }
          },
          "description": "Shared themes."
        },
        "hooks": {
          "type": "array",
          "items": {
            "type": "object",
            "description": "An opening the notes use.",
            "properties": {
              "text": {
                "type": "string",
                "description": "The point, in the synthesis's language."
              },
              "count": {
                "type": "integer",
                "description": "How many of the notes it was seen in."
              }
            }
          },
          "description": "Hooks."
        },
        "formats": {
          "type": "array",
          "items": {
            "type": "object",
            "description": "A format the notes use.",
            "properties": {
              "text": {
                "type": "string",
                "description": "The point, in the synthesis's language."
              },
              "count": {
                "type": "integer",
                "description": "How many of the notes it was seen in."
              }
            }
          },
          "description": "Formats."
        },
        "claims": {
          "type": "array",
          "items": {
            "type": "object",
            "description": "A claim the notes make.",
            "properties": {
              "text": {
                "type": "string",
                "description": "The point, in the synthesis's language."
              },
              "count": {
                "type": "integer",
                "description": "How many of the notes it was seen in."
              }
            }
          },
          "description": "Claims."
        },
        "objections": {
          "type": "array",
          "items": {
            "type": "object",
            "description": "An objection readers raise.",
            "properties": {
              "text": {
                "type": "string",
                "description": "The point, in the synthesis's language."
              },
              "count": {
                "type": "integer",
                "description": "How many of the notes it was seen in."
              }
            }
          },
          "description": "Objections, from the comments when they were read."
        },
        "gaps": {
          "type": "array",
          "items": {
            "type": "object",
            "description": "Something none of the notes cover.",
            "properties": {
              "text": {
                "type": "string",
                "description": "The point, in the synthesis's language."
              },
              "count": {
                "type": "integer",
                "description": "How many of the notes it was seen in."
              }
            }
          },
          "description": "Gaps."
        },
        "missing": {
          "type": "array",
          "items": {
            "type": "string",
            "description": "A section name."
          },
          "description": "The sections the material could not support."
        },
        "raw_markdown": {
          "type": "string",
          "description": "The whole synthesis as Markdown (with the draft appended when one was asked for)."
        },
        "draft": {
          "type": [
            "object",
            "null"
          ],
          "description": "成稿 — the post written from the batch (2026-10-31). Only on a batch that asked for draft=true; null while it runs. Every figure in it is in the notes. +1 credit once.",
          "properties": {
            "language": {
              "type": "string",
              "description": "The language it is written in."
            },
            "platform": {
              "type": "string",
              "description": "xiaohongshu, douyin or en.",
              "enum": [
                "xiaohongshu",
                "douyin",
                "en"
              ]
            },
            "titles": {
              "type": "array",
              "items": {
                "type": "string",
                "description": "A title."
              },
              "description": "Three titles to pick from."
            },
            "body": {
              "type": "string",
              "description": "The post itself, ready to paste."
            },
            "hashtags": {
              "type": "array",
              "items": {
                "type": "string",
                "description": "A hashtag without #."
              },
              "description": "Hashtags."
            },
            "cover_text": {
              "type": "string",
              "description": "The words for the cover image."
            },
            "cites": {
              "type": "array",
              "items": {
                "type": "integer"
              },
              "description": "The notes (1-based, batch order) the draft draws on."
            },
            "made_by": {
              "type": "string",
              "description": "\"model\", \"model_retry\", or \"fallback\" (the notes' own titles and key points, after two drafts carried figures not in the notes)."
            },
            "cut": {
              "type": "integer",
              "description": "Sentences cut because their figure was not in any note."
            }
          }
        }
      }
    }
  }
}