{"openapi":"3.1.1","info":{"title":"ZIP.tools supporting API","version":"1.0.0","description":"Existing public endpoints for aggregate proposal readership and optional summaries. To read proposal specifications, use normal proposal URLs with Accept: text/markdown. There are no user accounts or credential flows. Summaries are disabled in this deployment. No transaction, wallet, or blockchain-write operation is provided.","contact":{"name":"ZIP.tools issue tracker","url":"https://github.com/megabyte0x/zip-tools/issues"}},"servers":[{"url":"https://zips.tools","description":"ZIP.tools production server"}],"externalDocs":{"description":"Agent guide and source provenance","url":"https://zips.tools/docs"},"security":[],"paths":{"/api/trending":{"get":{"operationId":"listTrendingProposals","summary":"Read aggregate proposal popularity","parameters":[{"name":"X-API-Version","in":"header","required":false,"description":"API contract version. Version 1 is the default when omitted; unsupported versions return 400. Incompatible changes require a new version. If retirement is scheduled, responses will carry Deprecation and Sunset headers and the replacement contract will be linked in this guide. No retirement is currently scheduled.","schema":{"type":"string","enum":["1"],"default":"1"}}],"description":"Return up to twelve proposals ordered by readership count over the last seven UTC days. This is a bounded ranking, not a pageable proposal catalog. It may return an empty list if counters are unavailable. No account or API key is required.","responses":{"200":{"description":"The bounded popularity list.","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","description":"Proposals ordered by decreasing aggregate readership.","maxItems":12,"items":{"type":"object","required":["id","count"],"properties":{"id":{"type":"string","description":"Proposal id in the pinned snapshot."},"count":{"type":"integer","minimum":0,"description":"Aggregated readership count."}}}}}}}}},"400":{"description":"Unsupported API contract version.","content":{"application/problem+json":{"schema":{"type":"object","description":"RFC 9457 problem details with a stable error code and recovery guidance.","required":["type","title","status","detail","instance","code","resolution"],"properties":{"type":{"type":"string","description":"Problem type URI; about:blank uses the HTTP status meaning."},"title":{"type":"string","description":"Short human-readable error title."},"status":{"type":"integer","description":"The HTTP error status.","minimum":400,"maximum":599},"detail":{"type":"string","description":"Explanation of the error without implementation internals."},"instance":{"type":"string","description":"The API path on which the error occurred."},"code":{"type":"string","description":"Stable machine-readable error code."},"resolution":{"type":"string","description":"How to recover or find the correct request contract."},"error":{"type":"string","description":"Optional legacy summary error code, preserved for existing clients."}}}}}},"405":{"description":"Use GET for this endpoint.","content":{"application/problem+json":{"schema":{"type":"object","description":"RFC 9457 problem details with a stable error code and recovery guidance.","required":["type","title","status","detail","instance","code","resolution"],"properties":{"type":{"type":"string","description":"Problem type URI; about:blank uses the HTTP status meaning."},"title":{"type":"string","description":"Short human-readable error title."},"status":{"type":"integer","description":"The HTTP error status.","minimum":400,"maximum":599},"detail":{"type":"string","description":"Explanation of the error without implementation internals."},"instance":{"type":"string","description":"The API path on which the error occurred."},"code":{"type":"string","description":"Stable machine-readable error code."},"resolution":{"type":"string","description":"How to recover or find the correct request contract."},"error":{"type":"string","description":"Optional legacy summary error code, preserved for existing clients."}}}}}},"500":{"description":"The endpoint could not complete the request.","content":{"application/problem+json":{"schema":{"type":"object","description":"RFC 9457 problem details with a stable error code and recovery guidance.","required":["type","title","status","detail","instance","code","resolution"],"properties":{"type":{"type":"string","description":"Problem type URI; about:blank uses the HTTP status meaning."},"title":{"type":"string","description":"Short human-readable error title."},"status":{"type":"integer","description":"The HTTP error status.","minimum":400,"maximum":599},"detail":{"type":"string","description":"Explanation of the error without implementation internals."},"instance":{"type":"string","description":"The API path on which the error occurred."},"code":{"type":"string","description":"Stable machine-readable error code."},"resolution":{"type":"string","description":"How to recover or find the correct request contract."},"error":{"type":"string","description":"Optional legacy summary error code, preserved for existing clients."}}}}}}}}},"/api/views":{"post":{"operationId":"recordProposalView","summary":"Record one proposal reading event","parameters":[{"name":"X-API-Version","in":"header","required":false,"description":"API contract version. Version 1 is the default when omitted; unsupported versions return 400. Incompatible changes require a new version. If retirement is scheduled, responses will carry Deprecation and Sunset headers and the replacement contract will be linked in this guide. No retirement is currently scheduled.","schema":{"type":"string","enum":["1"],"default":"1"}}],"description":"Browser telemetry endpoint. Record a reading of a known proposal; repeated proposal/IP-hash events are suppressed for about thirty minutes. A 204 response does not guarantee persistent recording because counting is best effort. Agents retrieving reference text do not need to call this endpoint. No account or API key is required.","requestBody":{"required":true,"description":"The proposal that was read.","content":{"application/json":{"schema":{"type":"object","required":["id"],"properties":{"id":{"type":"string","minLength":1,"description":"An existing proposal id, for example 32."}}},"example":{"id":"32"}}}},"responses":{"204":{"description":"The event was handled, suppressed as a repeat, or ignored because counters are unavailable. No response body."},"400":{"description":"Malformed JSON, absent id, or an id outside the snapshot.","content":{"application/problem+json":{"schema":{"type":"object","description":"RFC 9457 problem details with a stable error code and recovery guidance.","required":["type","title","status","detail","instance","code","resolution"],"properties":{"type":{"type":"string","description":"Problem type URI; about:blank uses the HTTP status meaning."},"title":{"type":"string","description":"Short human-readable error title."},"status":{"type":"integer","description":"The HTTP error status.","minimum":400,"maximum":599},"detail":{"type":"string","description":"Explanation of the error without implementation internals."},"instance":{"type":"string","description":"The API path on which the error occurred."},"code":{"type":"string","description":"Stable machine-readable error code."},"resolution":{"type":"string","description":"How to recover or find the correct request contract."},"error":{"type":"string","description":"Optional legacy summary error code, preserved for existing clients."}}}}}},"405":{"description":"Use POST for this endpoint.","content":{"application/problem+json":{"schema":{"type":"object","description":"RFC 9457 problem details with a stable error code and recovery guidance.","required":["type","title","status","detail","instance","code","resolution"],"properties":{"type":{"type":"string","description":"Problem type URI; about:blank uses the HTTP status meaning."},"title":{"type":"string","description":"Short human-readable error title."},"status":{"type":"integer","description":"The HTTP error status.","minimum":400,"maximum":599},"detail":{"type":"string","description":"Explanation of the error without implementation internals."},"instance":{"type":"string","description":"The API path on which the error occurred."},"code":{"type":"string","description":"Stable machine-readable error code."},"resolution":{"type":"string","description":"How to recover or find the correct request contract."},"error":{"type":"string","description":"Optional legacy summary error code, preserved for existing clients."}}}}}},"500":{"description":"The endpoint could not complete the request.","content":{"application/problem+json":{"schema":{"type":"object","description":"RFC 9457 problem details with a stable error code and recovery guidance.","required":["type","title","status","detail","instance","code","resolution"],"properties":{"type":{"type":"string","description":"Problem type URI; about:blank uses the HTTP status meaning."},"title":{"type":"string","description":"Short human-readable error title."},"status":{"type":"integer","description":"The HTTP error status.","minimum":400,"maximum":599},"detail":{"type":"string","description":"Explanation of the error without implementation internals."},"instance":{"type":"string","description":"The API path on which the error occurred."},"code":{"type":"string","description":"Stable machine-readable error code."},"resolution":{"type":"string","description":"How to recover or find the correct request contract."},"error":{"type":"string","description":"Optional legacy summary error code, preserved for existing clients."}}}}}}}}},"/api/summary/{id}":{"get":{"operationId":"getProposalSummary","summary":"Read an optional generated proposal summary","description":"This optional feature is currently disabled, so production returns 404 with code disabled. If enabled by the operator, it retrieves or generates a short summary of a source-backed proposal. The summary is not an authoritative specification. Read the proposal directly for protocol details.","parameters":[{"name":"id","in":"path","required":true,"description":"Numbered proposal id or an existing draft slug.","schema":{"type":"string","minLength":1},"example":"32"},{"name":"X-API-Version","in":"header","required":false,"description":"API contract version. Version 1 is the default when omitted; unsupported versions return 400. Incompatible changes require a new version. If retirement is scheduled, responses will carry Deprecation and Sunset headers and the replacement contract will be linked in this guide. No retirement is currently scheduled.","schema":{"type":"string","enum":["1"],"default":"1"}}],"responses":{"200":{"description":"Generated summary when the feature is enabled.","content":{"application/json":{"schema":{"type":"object","required":["text","generated","cached"],"properties":{"text":{"type":"string","description":"Generated summary text."},"generated":{"type":"boolean","const":true,"description":"Identifies text as generated."},"cached":{"type":"boolean","description":"Whether the summary came from the snapshot-keyed cache."}}}}}},"400":{"description":"Unsupported API contract version.","content":{"application/problem+json":{"schema":{"type":"object","description":"RFC 9457 problem details with a stable error code and recovery guidance.","required":["type","title","status","detail","instance","code","resolution"],"properties":{"type":{"type":"string","description":"Problem type URI; about:blank uses the HTTP status meaning."},"title":{"type":"string","description":"Short human-readable error title."},"status":{"type":"integer","description":"The HTTP error status.","minimum":400,"maximum":599},"detail":{"type":"string","description":"Explanation of the error without implementation internals."},"instance":{"type":"string","description":"The API path on which the error occurred."},"code":{"type":"string","description":"Stable machine-readable error code."},"resolution":{"type":"string","description":"How to recover or find the correct request contract."},"error":{"type":"string","description":"Optional legacy summary error code, preserved for existing clients."}}}}}},"404":{"description":"Feature disabled or proposal not found.","content":{"application/problem+json":{"schema":{"type":"object","description":"RFC 9457 problem details with a stable error code and recovery guidance.","required":["type","title","status","detail","instance","code","resolution"],"properties":{"type":{"type":"string","description":"Problem type URI; about:blank uses the HTTP status meaning."},"title":{"type":"string","description":"Short human-readable error title."},"status":{"type":"integer","description":"The HTTP error status.","minimum":400,"maximum":599},"detail":{"type":"string","description":"Explanation of the error without implementation internals."},"instance":{"type":"string","description":"The API path on which the error occurred."},"code":{"type":"string","description":"Stable machine-readable error code."},"resolution":{"type":"string","description":"How to recover or find the correct request contract."},"error":{"type":"string","description":"Optional legacy summary error code, preserved for existing clients."}}}}}},"405":{"description":"Use GET for this endpoint.","content":{"application/problem+json":{"schema":{"type":"object","description":"RFC 9457 problem details with a stable error code and recovery guidance.","required":["type","title","status","detail","instance","code","resolution"],"properties":{"type":{"type":"string","description":"Problem type URI; about:blank uses the HTTP status meaning."},"title":{"type":"string","description":"Short human-readable error title."},"status":{"type":"integer","description":"The HTTP error status.","minimum":400,"maximum":599},"detail":{"type":"string","description":"Explanation of the error without implementation internals."},"instance":{"type":"string","description":"The API path on which the error occurred."},"code":{"type":"string","description":"Stable machine-readable error code."},"resolution":{"type":"string","description":"How to recover or find the correct request contract."},"error":{"type":"string","description":"Optional legacy summary error code, preserved for existing clients."}}}}}},"422":{"description":"No source body is available.","content":{"application/problem+json":{"schema":{"type":"object","description":"RFC 9457 problem details with a stable error code and recovery guidance.","required":["type","title","status","detail","instance","code","resolution"],"properties":{"type":{"type":"string","description":"Problem type URI; about:blank uses the HTTP status meaning."},"title":{"type":"string","description":"Short human-readable error title."},"status":{"type":"integer","description":"The HTTP error status.","minimum":400,"maximum":599},"detail":{"type":"string","description":"Explanation of the error without implementation internals."},"instance":{"type":"string","description":"The API path on which the error occurred."},"code":{"type":"string","description":"Stable machine-readable error code."},"resolution":{"type":"string","description":"How to recover or find the correct request contract."},"error":{"type":"string","description":"Optional legacy summary error code, preserved for existing clients."}}}}}},"503":{"description":"Summary provider unavailable.","content":{"application/problem+json":{"schema":{"type":"object","description":"RFC 9457 problem details with a stable error code and recovery guidance.","required":["type","title","status","detail","instance","code","resolution"],"properties":{"type":{"type":"string","description":"Problem type URI; about:blank uses the HTTP status meaning."},"title":{"type":"string","description":"Short human-readable error title."},"status":{"type":"integer","description":"The HTTP error status.","minimum":400,"maximum":599},"detail":{"type":"string","description":"Explanation of the error without implementation internals."},"instance":{"type":"string","description":"The API path on which the error occurred."},"code":{"type":"string","description":"Stable machine-readable error code."},"resolution":{"type":"string","description":"How to recover or find the correct request contract."},"error":{"type":"string","description":"Optional legacy summary error code, preserved for existing clients."}}}}}}}}}}}