{ "openapi": "3.1.0", "info": { "title": "Lights On API", "version": "1.0.0", "description": "Is this team still shipping? Nightly project status decided by published rules over verified evidence and attested on Base with EAS. Read endpoints need no auth, answer JSON, send open CORS and are cached for 5 minutes. The same data is available over MCP at /api/mcp." }, "servers": [ { "url": "https://lights-on-watch.vercel.app" } ], "paths": { "/api/v1/projects": { "get": { "operationId": "listProjects", "summary": "All listed projects with latest status and record (community-added watches are unlisted)", "parameters": [ { "name": "with", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "lastNight", "history" ] } }, "description": "lastNight fields are always included. history adds the last 90 nights as one 90-letter string (oldest first, last = today, UTC): S shipped, B building, Q quiet, D down, U unavailable, . no night. Other query params are answered with a 308 to the canonical URL." } ], "responses": { "200": { "description": "Projects (hidden ones excluded)", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "public, s-maxage=300" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "generatedAt", "projects" ], "properties": { "generatedAt": { "type": "string", "format": "date-time" }, "projects": { "type": "array", "items": { "type": "object", "required": [ "slug", "name", "tagline", "source", "bay", "status", "confirmedAt", "summary", "record" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "tagline": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "vibestarter", "vibeathon01", "base", "community" ] }, "bay": { "type": [ "integer", "null" ], "description": "Stable window position in the tower (1 = top left); kept across nights" }, "status": { "type": [ "string", "null" ], "enum": [ "shipped", "building", "quiet", "down", "unavailable", null ], "description": "Latest observed night, else latest reconstructed (see statusSource)" }, "statusSource": { "type": "string", "enum": [ "reconstructed" ], "description": "Present only when status is not from an observed night" }, "confirmedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the latest observed night was recorded" }, "summary": { "type": [ "string", "null" ] }, "record": { "type": "object", "required": [ "streak", "lit30", "lastShip" ], "properties": { "streak": { "type": "integer", "description": "Consecutive shipped or building nights ending at the latest night" }, "lit30": { "type": "integer", "description": "Shipped or building nights among the last 30" }, "lastShip": { "type": [ "integer", "null" ], "minimum": 20200101, "maximum": 20991231, "description": "Latest night with status shipped (yyyymmdd), or null" } } }, "history": { "type": "string", "minLength": 90, "maxLength": 90, "pattern": "^[SBQDU.]{90}$", "description": "Present with ?with=history. Oldest first, last letter = today (UTC): S shipped, B building, Q quiet, D down, U unavailable, . no night" } } } } } } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "internal" ] } } } } } } } } }, "/api/v1/projects/{slug}": { "get": { "operationId": "getProject", "summary": "One project: details, record, latest night, Vibestarter tranche summary", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,79}$" } } ], "responses": { "200": { "description": "Project", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "public, s-maxage=300" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "tagline": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "source": { "type": "string" }, "bay": { "type": [ "integer", "null" ] }, "liveUrl": { "type": [ "string", "null" ] }, "repoHost": { "type": [ "string", "null" ] }, "repo": { "type": [ "string", "null" ] }, "contracts": { "type": "array", "items": { "type": "object" } }, "claimed": { "type": "boolean" }, "communityAdded": { "const": true, "description": "Present for projects added via /watch: unlisted, served by slug only" }, "status": { "type": [ "string", "null" ], "enum": [ "shipped", "building", "quiet", "down", "unavailable", null ] }, "statusSource": { "type": "string", "enum": [ "reconstructed" ] }, "record": { "type": "object", "required": [ "streak", "lit30", "lastShip" ], "properties": { "streak": { "type": "integer", "description": "Consecutive shipped or building nights ending at the latest night" }, "lit30": { "type": "integer", "description": "Shipped or building nights among the last 30" }, "lastShip": { "type": [ "integer", "null" ], "minimum": 20200101, "maximum": 20991231, "description": "Latest night with status shipped (yyyymmdd), or null" } } }, "latestNight": { "oneOf": [ { "type": "object", "required": [ "night", "observed", "status", "reasons", "summary", "evidenceHash", "evidenceUri", "attestationUid", "attestTx", "attestProof", "attestLeaf", "attestRoot", "attestLit30", "manifestHash", "manifestUri" ], "properties": { "night": { "type": "integer", "minimum": 20200101, "maximum": 20991231, "description": "UTC date as yyyymmdd" }, "observed": { "type": "boolean", "description": "false = reconstructed afterwards from history" }, "status": { "type": "string", "enum": [ "shipped", "building", "quiet", "down", "unavailable" ] }, "reasons": { "type": "array", "items": { "type": "string" }, "description": "Stable machine strings, e.g. liveapp.new_deploy" }, "summary": { "type": [ "string", "null" ] }, "evidenceHash": { "type": [ "string", "null" ] }, "evidenceUri": { "type": [ "string", "null" ], "format": "uri" }, "attestationUid": { "type": [ "string", "null" ], "description": "EAS attestation uid on Base. Nightly rows: the night's ROOT attestation (one per night, shared by every project-night it covers)." }, "attestTx": { "type": [ "string", "null" ] }, "attestProof": { "type": [ "array", "null" ], "items": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" }, "description": "Merkle proof (sibling hashes, leaf to root, sorted-pair keccak256) of this project-night into attestRoot; empty for a one-leaf root" }, "attestLeaf": { "type": [ "string", "null" ], "pattern": "^0x[0-9a-f]{64}$", "description": "keccak256(abi.encode(bytes32 keccak256(slug), uint32 night, uint8 0, uint8 status, uint16 attestLit30, bytes32 evidenceHash))" }, "attestRoot": { "type": [ "string", "null" ], "pattern": "^0x[0-9a-f]{64}$", "description": "The Merkle root carried by the root attestation" }, "attestLit30": { "type": [ "integer", "null" ], "description": "The lit30 this leaf commits to (the record when it was attested)" }, "manifestHash": { "type": [ "string", "null" ], "pattern": "^0x[0-9a-f]{64}$", "description": "keccak256 of the night manifest that lists every leaf of the root" }, "manifestUri": { "type": [ "string", "null" ], "format": "uri" } } }, { "type": "null" } ], "description": "Observed night preferred" }, "vibestarter": { "type": [ "object", "null" ], "properties": { "campaignId": { "type": "string" }, "escrow": { "type": "string" }, "tranches": { "type": "array", "items": { "type": "object" } }, "openWindow": { "type": [ "object", "null" ] } } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "not_found" ] } } } } } } } } }, "/api/v1/projects/{slug}/nights": { "get": { "operationId": "getProjectNights", "summary": "Nights of one project (observed and reconstructed rows)", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,79}$" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 20200101, "maximum": 20991231, "description": "UTC date as yyyymmdd" }, "description": "Default: 89 days before `to`" }, { "name": "to", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 20200101, "maximum": 20991231, "description": "UTC date as yyyymmdd" }, "description": "Default: today (UTC). At most 366 days are returned." } ], "responses": { "200": { "description": "Nights, oldest first", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "public, s-maxage=300" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string" }, "from": { "type": "integer", "minimum": 20200101, "maximum": 20991231, "description": "UTC date as yyyymmdd" }, "to": { "type": "integer", "minimum": 20200101, "maximum": 20991231, "description": "UTC date as yyyymmdd" }, "nights": { "type": "array", "items": { "type": "object", "required": [ "night", "observed", "status", "reasons", "summary", "evidenceHash", "evidenceUri", "attestationUid", "attestTx", "attestProof", "attestLeaf", "attestRoot", "attestLit30", "manifestHash", "manifestUri" ], "properties": { "night": { "type": "integer", "minimum": 20200101, "maximum": 20991231, "description": "UTC date as yyyymmdd" }, "observed": { "type": "boolean", "description": "false = reconstructed afterwards from history" }, "status": { "type": "string", "enum": [ "shipped", "building", "quiet", "down", "unavailable" ] }, "reasons": { "type": "array", "items": { "type": "string" }, "description": "Stable machine strings, e.g. liveapp.new_deploy" }, "summary": { "type": [ "string", "null" ] }, "evidenceHash": { "type": [ "string", "null" ] }, "evidenceUri": { "type": [ "string", "null" ], "format": "uri" }, "attestationUid": { "type": [ "string", "null" ], "description": "EAS attestation uid on Base. Nightly rows: the night's ROOT attestation (one per night, shared by every project-night it covers)." }, "attestTx": { "type": [ "string", "null" ] }, "attestProof": { "type": [ "array", "null" ], "items": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" }, "description": "Merkle proof (sibling hashes, leaf to root, sorted-pair keccak256) of this project-night into attestRoot; empty for a one-leaf root" }, "attestLeaf": { "type": [ "string", "null" ], "pattern": "^0x[0-9a-f]{64}$", "description": "keccak256(abi.encode(bytes32 keccak256(slug), uint32 night, uint8 0, uint8 status, uint16 attestLit30, bytes32 evidenceHash))" }, "attestRoot": { "type": [ "string", "null" ], "pattern": "^0x[0-9a-f]{64}$", "description": "The Merkle root carried by the root attestation" }, "attestLit30": { "type": [ "integer", "null" ], "description": "The lit30 this leaf commits to (the record when it was attested)" }, "manifestHash": { "type": [ "string", "null" ], "pattern": "^0x[0-9a-f]{64}$", "description": "keccak256 of the night manifest that lists every leaf of the root" }, "manifestUri": { "type": [ "string", "null" ], "format": "uri" } } } } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "bad_request" ] } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "not_found" ] } } } } } } } } }, "/api/v1/evidence/{hash}": { "get": { "operationId": "getEvidence", "summary": "The canonical evidence bundle behind a night", "description": "The exact JSON whose hash is the attested evidenceHash. Re-run the published rules over it to reproduce the status.", "parameters": [ { "name": "hash", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } ], "responses": { "200": { "description": "Evidence bundle (v1)", "content": { "application/json": { "schema": { "type": "object", "required": [ "v", "rulesVersion", "project", "night", "kind", "window", "sources" ], "properties": { "v": { "const": 1 }, "rulesVersion": { "type": "string" }, "project": { "type": "string" }, "night": { "type": "integer", "minimum": 20200101, "maximum": 20991231, "description": "UTC date as yyyymmdd" }, "kind": { "type": "string", "enum": [ "nightly", "live" ] }, "window": { "type": "object", "properties": { "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" } } }, "sources": { "type": "object", "description": "Adapter results per source (repo, liveapp, chain, vibestarter); null when a source does not apply.", "additionalProperties": { "type": [ "object", "null" ] } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "not_found" ] } } } } } } } } }, "/api/v1/manifest/{hash}": { "get": { "operationId": "getNightManifest", "summary": "The manifest behind a nightly root attestation", "description": "The exact canonical JSON whose keccak256 is the hash in the root attestation's manifestURI: every leaf of the night's Merkle root with its slug, status, lit30 and evidence hash. Rebuild the tree from the leaves to get the attested root.", "parameters": [ { "name": "hash", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } ], "responses": { "200": { "description": "Night manifest (v1)", "content": { "application/json": { "schema": { "type": "object", "required": [ "v", "schema", "night", "count", "leaves", "root", "agentId" ], "properties": { "v": { "const": 1 }, "schema": { "const": "lights-on/night-manifest" }, "night": { "type": "integer", "minimum": 20200101, "maximum": 20991231, "description": "UTC date as yyyymmdd" }, "count": { "type": "integer" }, "root": { "type": "string" }, "agentId": { "type": "string", "description": "ERC-8004 agent id, decimal" }, "leaves": { "type": "array", "description": "Sorted ascending by leaf", "items": { "type": "object", "properties": { "slug": { "type": [ "string", "null" ], "description": "null for an unlisted (community-added or hidden) project" }, "projectKey": { "type": "string", "description": "keccak256 of the slug" }, "night": { "type": "integer", "minimum": 20200101, "maximum": 20991231, "description": "UTC date as yyyymmdd" }, "kind": { "const": 0 }, "status": { "type": "string", "enum": [ "shipped", "building", "quiet", "down", "unavailable" ] }, "statusCode": { "type": "integer", "minimum": 1, "maximum": 5 }, "lit30": { "type": "integer" }, "evidenceHash": { "type": "string" }, "leaf": { "type": "string" } } } } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "invalid_hash" ] } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "not_found" ] } } } } } } } } }, "/api/v1/briefing/{address}": { "get": { "operationId": "getBriefing", "summary": "Morning briefing for a wallet address or .eth name", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string" }, "description": "0x address or ENS name" } ], "responses": { "200": { "description": "Projects the wallet backs or holds and a short briefing", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "public, s-maxage=300" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string" }, "displayName": { "type": "string" }, "degraded": { "type": "boolean" }, "projects": { "type": "array", "items": { "type": "object" } }, "briefing": { "type": "object", "properties": { "text": { "type": "string" }, "aiOk": { "type": "boolean" } } } } } } } }, "308": { "description": "Redirect to the checksummed address" }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "invalid_address", "ens_unavailable" ] } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "ens_not_found" ] } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] } } } } } } } } }, "/api/v1/watch": { "post": { "operationId": "watchProject", "summary": "Ask Lights On to watch a new project", "description": "Rate-limited: 3 per day per caller, 50 per day overall. The URL must answer. The project is created hidden; after its first check succeeds it is reachable by slug (unlisted: never in /api/v1/projects). If the check fails it stays hidden, and watching the same URL again re-queues it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "liveUrl" ], "properties": { "liveUrl": { "type": "string", "format": "uri", "description": "Public http(s) URL" }, "repo": { "type": "string", "description": "owner/name, or a github.com / gitlab.com URL" }, "contract": { "type": "string", "description": "Base contract address (0x...)" } } } } } }, "responses": { "202": { "description": "Accepted (status exists = this URL is already watched)", "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "slug": { "type": "string", "description": "Omitted when a hidden project with this URL is re-queued" }, "status": { "type": "string", "enum": [ "queued", "exists" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_url", "invalid_repo", "invalid_contract", "blocked_url", "unreachable" ] } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "misconfigured" ] } } } } } } } } } } }