{
  "openapi": "3.1.0",
  "info": {
    "title": "SigPulse Agent API",
    "version": "1.1.0",
    "description": "Read-only data endpoints for AI agents. SigPulse publishes field-verified reporting on four machine-served beats: (1) AI & Compute — China’s models measured on real consumer GPUs (VRAM, tokens/sec, power draw, exact runtime flags); (2) China AI Watch — translated, source-linked entries from Chinese AI discourse; (3) Industrial AI — open-source tools deployed against factory-floor problems, with versions, commands and pitfalls preserved; (4) China Decoder — ten-room mechanism explainers, each aggregating several Chinese-language originals into one piece about how something in China works.\n\nStandard call pattern: call a list endpoint, pick a slug, fetch the raw markdown at md_url for the full document (frontmatter + body incl. the replication details — exact configs, commands and matrices; section titles vary by piece).\n\nCitation rules: (1) cite the canonical article URL; (2) any measurement must carry its measured_on date and hardware (the same rig string appears as verified_hardware in /posts.json and hardware in /data.json); (3) Watch, Papers and Decoder entries are reported commentary/aggregation, never measurements — /data.json is the authoritative first-party measurement ledger and the only place those numbers live; never mix commentary figures into it; (4) content is CC BY 4.0.\n\nThe same tools are callable via MCP at https://sigpulse.com/api/mcp and listed in the capability catalog at /.well-known/ai-catalog.json. Agent operations manual: /agents.md.",
    "contact": {
      "name": "SigPulse Research",
      "email": "intel@sigpulse.com",
      "url": "https://sigpulse.com/about/"
    },
    "license": {
      "name": "CC BY 4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    }
  },
  "servers": [
    {
      "url": "https://sigpulse.com"
    }
  ],
  "security": [],
  "externalDocs": {
    "description": "Agent operations manual (how to search, cite, and stay within the data contract)",
    "url": "https://sigpulse.com/agents.md"
  },
  "paths": {
    "/posts.json": {
      "get": {
        "operationId": "listDispatches",
        "summary": "Index of all measured dispatches (metadata + 3-takeaway executive summaries)",
        "description": "Start here. Returns the dispatch index: slug, title, description, category, tags, date, measured_on, verified_hardware, key_takeaways (3-sentence executive summary), url (HTML) and md_url (raw markdown). Episodes of a field-report series additionally carry series / series_order / arc — filter and sort by them for reading order. Pick a slug, then call getDispatchRaw for the full article. Every number must be cited with measured_on and verified_hardware.",
        "responses": {
          "200": {
            "description": "Dispatch index envelope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DispatchIndex"
                }
              }
            }
          },
          "404": {
            "description": "Index file missing (static build artifact)"
          }
        }
      }
    },
    "/posts/{slug}.md": {
      "get": {
        "operationId": "getDispatchRaw",
        "summary": "Full dispatch as a self-contained markdown document",
        "description": "Returns one dispatch as a complete markdown document — YAML frontmatter (all metadata incl. measuredOn and FAQ) + verbatim body carrying the replication details (exact configs, commands, matrices; some pieces formalize them as a \"Replication appendix\" section, others weave them into the narrative). slug values come from listDispatches, e.g. 2026-08-26-infinitetalk-14b-dual-gpu-measured.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Dispatch slug from listDispatches (the YYYY-MM-DD-slug file name)."
          }
        ],
        "responses": {
          "200": {
            "description": "Markdown document",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Unknown slug"
          }
        }
      }
    },
    "/watch.json": {
      "get": {
        "operationId": "listWatchEntries",
        "summary": "Index of translated China AI Watch entries with full provenance",
        "description": "China AI Watch: translated, source-linked entries from Chinese AI discourse. Reported commentary with provenance (original_date, original_title, cross-checked sources[]) — NEVER measurements. Do not mix these figures with the /data.json ledger; the envelope notice restates this contract.",
        "responses": {
          "200": {
            "description": "Watch index envelope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WatchIndex"
                }
              }
            }
          },
          "404": {
            "description": "Index file missing (static build artifact)"
          }
        }
      }
    },
    "/watch/{slug}.md": {
      "get": {
        "operationId": "getWatchEntryRaw",
        "summary": "Full Watch entry as markdown with dual dates and sources in frontmatter",
        "description": "Returns one Watch entry as a complete markdown document — frontmatter carries the provenance payload (originalDate, originalTitle, issue, sources[]) and the body is the translated commentary with the provenance statement. slug values come from listWatchEntries.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Watch slug from listWatchEntries."
          }
        ],
        "responses": {
          "200": {
            "description": "Markdown document",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Unknown slug"
          }
        }
      }
    },
    "/papers.json": {
      "get": {
        "operationId": "listPaperDigests",
        "summary": "Index of periodic arXiv paper digests with full provenance and paper IDs",
        "description": "Papers: periodically updated digests of new arXiv work as read by our Chinese-language column. Same provenance contract as Watch (original_date, original_title, sources[]) plus a papers[] array — the arXiv IDs covered, with canonical abstract links. Translated commentary, NEVER measurements.",
        "responses": {
          "200": {
            "description": "Papers index envelope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PapersIndex"
                }
              }
            }
          },
          "404": {
            "description": "Index file missing (static build artifact)"
          }
        }
      }
    },
    "/papers/{slug}.md": {
      "get": {
        "operationId": "getPaperDigestRaw",
        "summary": "Full paper digest as markdown with dual dates and arXiv IDs in frontmatter",
        "description": "Returns one paper digest as a complete markdown document — frontmatter carries the provenance payload (originalDate, originalTitle, issue, papers[] with arXiv IDs, sources[]) and the body is the translated digest. slug values come from listPaperDigests.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Papers slug from listPaperDigests."
          }
        ],
        "responses": {
          "200": {
            "description": "Markdown document",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Unknown slug"
          }
        }
      }
    },
    "/data.json": {
      "get": {
        "operationId": "getMeasurements",
        "summary": "The authoritative first-party measurement ledger",
        "description": "THE authoritative source for every number SigPulse itself measured — there is no other. Flat array, one object per measurement: id (stable positional reference, <source-post>#<n> within the source ledger YAML), subject, metric, value, unit, hardware (the rig string; same value as verified_hardware in /posts.json), conditions, measured_on (the date the number was produced — distinct from the article's publication date), category, source (article URL), source_markdown (raw markdown with the replication details), license. First-party measurements only — figures from Watch, Papers and Decoder never enter this ledger. When citing, quote value + unit + hardware + measured_on together and link the source article.",
        "responses": {
          "200": {
            "description": "Measurement ledger envelope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MeasurementLedger"
                }
              }
            }
          },
          "404": {
            "description": "Ledger file missing (static build artifact)"
          }
        }
      }
    },
    "/decoder.json": {
      "get": {
        "operationId": "listDecoderPieces",
        "summary": "Index of China Decoder mechanism explainers with full aggregation provenance",
        "description": "China Decoder: ten-room mechanism explainers — each piece aggregates several Chinese-language originals into one explainer of how something in China works. Every entry carries its room (the ten-room map key), every aggregated original (date + headline) and cross-checked sources[]. Reported aggregation, NEVER measurements — figures here never enter the /data.json ledger; the envelope notice restates this contract.",
        "responses": {
          "200": {
            "description": "Decoder index envelope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DecoderIndex"
                }
              }
            }
          },
          "404": {
            "description": "Index file missing (static build artifact)"
          }
        }
      }
    },
    "/decoder/{slug}.md": {
      "get": {
        "operationId": "getDecoderPieceRaw",
        "summary": "Full Decoder piece as markdown with room and originals in frontmatter",
        "description": "Returns one China Decoder piece as a complete markdown document — frontmatter carries the provenance payload (room, issue, originals[] with every aggregated Chinese source, sources[]) and the body is the mechanism explainer. slug values come from listDecoderPieces.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Decoder slug from listDecoderPieces."
          }
        ],
        "responses": {
          "200": {
            "description": "Markdown document",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Unknown slug"
          }
        }
      }
    },
    "/decoder/rss.xml": {
      "get": {
        "operationId": "getDecoderFeed",
        "summary": "Full-content RSS feed of China Decoder pieces",
        "description": "Full-text RSS feed of China Decoder pieces, each with the aggregation provenance and raw-markdown pointer.",
        "responses": {
          "200": {
            "description": "RSS 2.0 XML",
            "content": {
              "application/rss+xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Feed file missing (static build artifact)"
          }
        }
      }
    },
    "/rss.xml": {
      "get": {
        "operationId": "getDispatchFeed",
        "summary": "Full-content RSS feed of dispatches",
        "description": "Full-text RSS feed of dispatches (rendered HTML + provenance footer per item). For per-article raw markdown prefer getDispatchRaw.",
        "responses": {
          "200": {
            "description": "RSS 2.0 XML",
            "content": {
              "application/rss+xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Feed file missing (static build artifact)"
          }
        }
      }
    },
    "/watch/rss.xml": {
      "get": {
        "operationId": "getWatchFeed",
        "summary": "Full-content RSS feed of China AI Watch entries",
        "description": "Full-text RSS feed of Watch entries, each with the dual-date + AI-assisted translation disclosure and raw-markdown pointer.",
        "responses": {
          "200": {
            "description": "RSS 2.0 XML",
            "content": {
              "application/rss+xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Feed file missing (static build artifact)"
          }
        }
      }
    },
    "/papers/rss.xml": {
      "get": {
        "operationId": "getPapersFeed",
        "summary": "Full-content RSS feed of paper digests",
        "description": "Full-text RSS feed of Papers digests, each listing the arXiv IDs covered with the dual-date + AI-assisted translation disclosure and raw-markdown pointer.",
        "responses": {
          "200": {
            "description": "RSS 2.0 XML",
            "content": {
              "application/rss+xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Feed file missing (static build artifact)"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "DispatchIndex": {
        "type": "object",
        "description": "Envelope for /posts.json.",
        "properties": {
          "site": {
            "type": "string",
            "format": "uri"
          },
          "license": {
            "type": "string"
          },
          "citation_rule": {
            "type": "string"
          },
          "count": {
            "type": "integer"
          },
          "dispatches": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "slug": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "category": {
                  "type": "string",
                  "enum": [
                    "AI & Compute",
                    "Expat Playbook",
                    "Industrial AI"
                  ]
                },
                "tags": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "series": {
                  "type": "string",
                  "description": "Series name, present only on series episodes (e.g. \"One Man One Legion\")."
                },
                "series_order": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "description": "Reading order within the series (0 = the anchor/map)."
                },
                "arc": {
                  "type": "string",
                  "description": "Arc (chapter) grouping within the series; anchor omits it."
                },
                "date": {
                  "type": "string",
                  "format": "date",
                  "description": "Publication date (YYYY-MM-DD)."
                },
                "measured_on": {
                  "type": "string",
                  "format": "date",
                  "description": "Date the measurements were actually run; cite this with any number."
                },
                "verified_hardware": {
                  "type": "string",
                  "description": "The rig the numbers were produced on."
                },
                "key_takeaways": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "minItems": 3,
                  "maxItems": 3
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                },
                "md_url": {
                  "type": "string",
                  "format": "uri",
                  "description": "Raw markdown for the full document."
                }
              }
            }
          }
        }
      },
      "WatchIndex": {
        "type": "object",
        "description": "Envelope for /watch.json.",
        "properties": {
          "site": {
            "type": "string",
            "format": "uri"
          },
          "license": {
            "type": "string"
          },
          "notice": {
            "type": "string",
            "description": "Commentary-not-measurements contract."
          },
          "count": {
            "type": "integer"
          },
          "entries": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "slug": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "issue": {
                  "type": "string",
                  "description": "Issue grouping, e.g. \"Issue 1\"."
                },
                "tags": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "date": {
                  "type": "string",
                  "format": "date",
                  "description": "English translation date."
                },
                "original_date": {
                  "type": "string",
                  "format": "date",
                  "description": "Chinese original publication date."
                },
                "original_title": {
                  "type": "string"
                },
                "sources": {
                  "type": "array",
                  "description": "Cross-checked arbitration sources.",
                  "items": {
                    "type": "object",
                    "properties": {
                      "label": {
                        "type": "string"
                      },
                      "url": {
                        "type": "string",
                        "format": "uri"
                      }
                    }
                  }
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                },
                "md_url": {
                  "type": "string",
                  "format": "uri"
                }
              }
            }
          }
        }
      },
      "PapersIndex": {
        "type": "object",
        "description": "Envelope for /papers.json.",
        "properties": {
          "site": {
            "type": "string",
            "format": "uri"
          },
          "license": {
            "type": "string"
          },
          "notice": {
            "type": "string",
            "description": "Commentary-not-measurements contract."
          },
          "count": {
            "type": "integer"
          },
          "papers_covered": {
            "type": "integer",
            "description": "Total distinct papers across digests."
          },
          "entries": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "slug": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "issue": {
                  "type": "string",
                  "description": "Batch grouping, e.g. \"Batch 1\"."
                },
                "tags": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "date": {
                  "type": "string",
                  "format": "date",
                  "description": "English translation date."
                },
                "original_date": {
                  "type": "string",
                  "format": "date",
                  "description": "Chinese original publication date."
                },
                "original_title": {
                  "type": "string"
                },
                "papers": {
                  "type": "array",
                  "description": "The arXiv papers this digest covers.",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "description": "arXiv ID, e.g. \"2608.27449\"."
                      },
                      "title": {
                        "type": "string"
                      },
                      "url": {
                        "type": "string",
                        "format": "uri",
                        "description": "Canonical arXiv abstract link."
                      }
                    }
                  }
                },
                "sources": {
                  "type": "array",
                  "description": "Cross-checked arbitration sources.",
                  "items": {
                    "type": "object",
                    "properties": {
                      "label": {
                        "type": "string"
                      },
                      "url": {
                        "type": "string",
                        "format": "uri"
                      }
                    }
                  }
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                },
                "md_url": {
                  "type": "string",
                  "format": "uri"
                }
              }
            }
          }
        }
      },
      "DecoderIndex": {
        "type": "object",
        "description": "Envelope for /decoder.json.",
        "properties": {
          "site": {
            "type": "string",
            "format": "uri"
          },
          "license": {
            "type": "string"
          },
          "notice": {
            "type": "string",
            "description": "Aggregation-not-measurements contract."
          },
          "count": {
            "type": "integer"
          },
          "entries": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "slug": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "room": {
                  "type": "string",
                  "description": "One of the ten fixed room keys: work, governance, justice, industry-tech, trust-safety, education, daily, economy, generations, china-world."
                },
                "room_name": {
                  "type": "string",
                  "description": "Display name of the room."
                },
                "issue": {
                  "type": "string",
                  "description": "Piece numbering, e.g. \"Decoder 1\"."
                },
                "tags": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "date": {
                  "type": "string",
                  "format": "date",
                  "description": "English adaptation date."
                },
                "originals": {
                  "type": "array",
                  "description": "Every Chinese original aggregated into this piece.",
                  "items": {
                    "type": "object",
                    "properties": {
                      "date": {
                        "type": "string",
                        "format": "date",
                        "description": "Chinese original publication date."
                      },
                      "title": {
                        "type": "string"
                      }
                    }
                  }
                },
                "sources": {
                  "type": "array",
                  "description": "Cross-checked arbitration sources.",
                  "items": {
                    "type": "object",
                    "properties": {
                      "label": {
                        "type": "string"
                      },
                      "url": {
                        "type": "string",
                        "format": "uri"
                      }
                    }
                  }
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                },
                "md_url": {
                  "type": "string",
                  "format": "uri"
                }
              }
            }
          }
        }
      },
      "MeasurementLedger": {
        "type": "object",
        "description": "Envelope for /data.json — the authoritative first-party measurement ledger. Numbers sourced from Watch, Papers or Decoder never appear here.",
        "properties": {
          "site": {
            "type": "string",
            "format": "uri"
          },
          "license": {
            "type": "string"
          },
          "citation_rule": {
            "type": "string",
            "description": "How to cite a measurement."
          },
          "count": {
            "type": "integer"
          },
          "measurements": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Stable positional id: <source-post-slug>#<n>, the nth entry in that post’s ledger YAML — cite it to reference one exact number."
                },
                "subject": {
                  "type": "string",
                  "description": "What was measured, full name incl. model + quant where applicable."
                },
                "metric": {
                  "type": "string",
                  "description": "What the number is."
                },
                "value": {
                  "type": "string",
                  "description": "Display value; ranges allowed."
                },
                "unit": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "hardware": {
                  "type": "string",
                  "description": "The rig the number was produced on (verified_hardware in /posts.json)."
                },
                "conditions": {
                  "type": "string",
                  "description": "Placement/context/sample size that pin the number."
                },
                "measured_on": {
                  "type": "string",
                  "format": "date",
                  "description": "Date the measurement was run — not the article publication date."
                },
                "category": {
                  "type": "string",
                  "enum": [
                    "AI & Compute",
                    "Expat Playbook",
                    "Industrial AI"
                  ]
                },
                "source": {
                  "type": "string",
                  "format": "uri",
                  "description": "Canonical article URL."
                },
                "source_markdown": {
                  "type": "string",
                  "format": "uri",
                  "description": "Raw markdown incl. the replication details."
                },
                "license": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "subject",
                "metric",
                "value",
                "hardware",
                "conditions",
                "measured_on",
                "source",
                "source_markdown"
              ]
            }
          }
        }
      }
    }
  }
}