{ "openapi": "3.1.0", "info": { "title": "DistroCool operating API", "version": "1.3.0", "description": "DistroCool discovery, content operations and self-service sponsorship. Payment availability is returned by GET /api/sponsors." }, "servers": [ { "url": "https://distrocool.com" } ], "paths": { "/api/opportunities": { "get": { "operationId": "findOpportunities", "summary": "Search published opportunities", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid input" }, "401": { "description": "Required role key missing or invalid" }, "409": { "description": "Revision conflict" }, "503": { "description": "Service unavailable" } }, "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "category", "in": "query", "schema": { "type": "string" } }, { "name": "track", "in": "query", "schema": { "type": "string" } } ] } }, "/api/agent/opportunities": { "get": { "operationId": "listAllOpportunities", "summary": "List records including drafts", "security": [ { "writeKey": [] } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid input" }, "401": { "description": "Required role key missing or invalid" }, "409": { "description": "Revision conflict" }, "503": { "description": "Service unavailable" } } }, "put": { "operationId": "saveOpportunity", "summary": "Save a complete opportunity as a draft", "security": [ { "writeKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "title", "org", "category", "track", "description", "reward", "location", "eligibility", "deadline", "deadlineLabel", "sourceUrl", "verifiedAt", "tags", "expectedRevision" ], "properties": { "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{2,79}$" }, "title": { "type": "string", "minLength": 3, "maxLength": 160 }, "org": { "type": "string", "minLength": 2, "maxLength": 100 }, "category": { "type": "string", "enum": [ "Hackathon", "Grant", "Bounty", "Startup program", "Credits" ] }, "track": { "type": "string", "enum": [ "AI", "Web3", "AI + Web3" ] }, "description": { "type": "string", "minLength": 20, "maxLength": 1000 }, "reward": { "type": "string", "minLength": 2, "maxLength": 120 }, "location": { "type": "string", "minLength": 2, "maxLength": 120 }, "eligibility": { "type": "string", "minLength": 15, "maxLength": 1500 }, "deadline": { "type": [ "string", "null" ], "format": "date-time" }, "deadlineLabel": { "type": "string", "minLength": 3, "maxLength": 120 }, "sourceUrl": { "type": "string", "format": "uri", "pattern": "^https://" }, "verifiedAt": { "type": "string", "format": "date" }, "tags": { "type": "array", "maxItems": 8, "items": { "type": "string", "minLength": 1, "maxLength": 35 } }, "expectedRevision": { "type": "integer", "minimum": 0 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid input" }, "401": { "description": "Required role key missing or invalid" }, "409": { "description": "Revision conflict" }, "503": { "description": "Service unavailable" } } } }, "/api/agent/publish": { "post": { "operationId": "publishOpportunity", "summary": "Publish or archive an existing revision", "security": [ { "publishKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "expectedRevision", "status" ], "properties": { "id": { "type": "string" }, "expectedRevision": { "type": "integer" }, "status": { "type": "string", "enum": [ "published", "archived" ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid input" }, "401": { "description": "Required role key missing or invalid" }, "409": { "description": "Revision conflict" }, "503": { "description": "Service unavailable" } } } }, "/api/agent/newsletters": { "get": { "operationId": "listNewsletterDrafts", "summary": "Read newsletter drafts", "security": [ { "writeKey": [] } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid input" }, "401": { "description": "Required role key missing or invalid" }, "409": { "description": "Revision conflict" }, "503": { "description": "Service unavailable" } } }, "put": { "operationId": "saveNewsletterDraft", "summary": "Save a draft without sending", "security": [ { "writeKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "subject", "body" ], "properties": { "id": { "type": "string", "pattern": "^[a-z0-9-]{3,80}$" }, "subject": { "type": "string", "minLength": 3, "maxLength": 200 }, "body": { "type": "string", "minLength": 20, "maxLength": 30000 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid input" }, "401": { "description": "Required role key missing or invalid" }, "409": { "description": "Revision conflict" }, "503": { "description": "Service unavailable" } } } }, "/api/agent/status": { "get": { "operationId": "getOperatingStatus", "summary": "Get aggregate counts and recent audit log", "security": [ { "writeKey": [] } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid input" }, "401": { "description": "Required role key missing or invalid" }, "409": { "description": "Revision conflict" }, "503": { "description": "Service unavailable" } } } }, "/api/workflows": { "get": { "operationId": "findWorkflows", "summary": "Search published workflow templates", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "agent", "in": "query", "schema": { "type": "string" } }, { "name": "topic", "in": "query", "schema": { "type": "string" } }, { "name": "difficulty", "in": "query", "schema": { "type": "string" } }, { "name": "new", "in": "query", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid input" }, "401": { "description": "Role key required" }, "409": { "description": "Revision conflict" }, "503": { "description": "Unavailable" } } } }, "/api/agent/workflows": { "get": { "operationId": "listWorkflowDrafts", "security": [ { "writeKey": [] } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid input" }, "401": { "description": "Role key required" }, "409": { "description": "Revision conflict" }, "503": { "description": "Unavailable" } } }, "put": { "operationId": "saveWorkflowDraft", "security": [ { "writeKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "id", "title", "summary", "topic", "agents", "difficulty", "setup", "inputs", "steps", "prompt", "outcome", "review", "addedAt", "evidence", "sourceUrl", "expectedRevision" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "topic": { "type": "string", "enum": [ "Opportunity research", "Content & newsletters", "Build & ship", "Growth & operations" ] }, "agents": { "type": "array", "items": { "type": "string", "enum": [ "ChatGPT", "Claude", "Codex", "Grok Bot", "Hermes" ] } }, "difficulty": { "type": "string", "enum": [ "Beginner", "Intermediate" ] }, "setup": { "type": "string" }, "inputs": { "type": "array", "items": { "type": "string" } }, "steps": { "type": "array", "items": { "type": "string" } }, "prompt": { "type": "string" }, "outcome": { "type": "string" }, "review": { "type": "string" }, "addedAt": { "type": "string", "format": "date" }, "evidence": { "type": "string", "enum": [ "Original template", "Source-backed example" ] }, "sourceUrl": { "type": [ "string", "null" ], "format": "uri" }, "expectedRevision": { "type": "integer", "minimum": 0 } } } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid input" }, "401": { "description": "Role key required" }, "409": { "description": "Revision conflict" }, "503": { "description": "Unavailable" } } } }, "/api/agent/workflows/publish": { "post": { "operationId": "publishWorkflow", "security": [ { "publishKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "expectedRevision", "status" ], "properties": { "id": { "type": "string" }, "expectedRevision": { "type": "integer" }, "status": { "type": "string", "enum": [ "published", "archived" ] } } } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid input" }, "401": { "description": "Role key required" }, "409": { "description": "Revision conflict" }, "503": { "description": "Unavailable" } } } }, "/api/agent/submissions": { "get": { "operationId": "listPrivateSubmissions", "security": [ { "writeKey": [] } ], "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "reviewed", "rejected" ] } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid input" }, "401": { "description": "Role key required" }, "409": { "description": "Revision conflict" }, "503": { "description": "Unavailable" } } }, "patch": { "operationId": "reviewSubmission", "security": [ { "publishKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "status" ], "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "reviewed", "rejected" ] } } } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid input" }, "401": { "description": "Role key required" }, "409": { "description": "Revision conflict" }, "503": { "description": "Unavailable" } } } }, "/api/mcp": { "post": { "operationId": "discoverReadOnlyTools", "summary": "Read-only JSON-RPC discovery for opportunities, workflows and journal entries", "requestBody": { "required": true, "content": { "application/json": { "schema": {"type": "object", "required": ["jsonrpc", "method"], "properties": {"jsonrpc": {"const": "2.0"}, "id": {"type": ["string", "integer", "null"]}, "method": {"type": "string"}, "params": {"type": "object"}}} } } }, "responses": {"200": {"description": "JSON-RPC result"}, "204": {"description": "Initialized notification"}} } }, "/api/brief": { "get": { "operationId": "findBriefEditions", "summary": "Search published DistroCool Brief editions with original-source evidence", "parameters": [{"name":"q","in":"query","schema":{"type":"string"}}], "responses": {"200":{"description":"Published edition list, newest first"},"503":{"description":"Temporarily unavailable"}} } }, "/api/brief/{id}": { "get": { "operationId": "readBriefEdition", "summary": "Read one published edition by permanent ID", "parameters": [{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^brief-\\d{4}-\\d{2}-\\d{2}$"}}], "responses": {"200":{"description":"Edition content and source ledger"},"404":{"description":"Edition not found"}} } }, "/api/agent/brief": { "get": {"operationId":"listBriefDrafts","summary":"List draft and published editions","security":[{"writeKey":[]}],"responses":{"200":{"description":"Edition inventory"}}}, "put": {"operationId":"saveBriefDraft","summary":"Save a complete source-backed edition draft with expectedRevision; identical retries are idempotent","security":[{"writeKey":[]}],"responses":{"200":{"description":"Draft saved or unchanged"},"409":{"description":"Revision conflict or immutable edition"}}} }, "/api/agent/brief/publish": { "post": {"operationId":"publishBriefEdition","summary":"Publish a verified Monday, Wednesday or Friday edition with matching date and current source checks","security":[{"publishKey":[]}],"responses":{"200":{"description":"Published or already published"},"400":{"description":"Source or date checks failed"},"409":{"description":"Revision conflict"}}} }, "/brief/feed.xml": {"get":{"operationId":"readBriefFeed","responses":{"200":{"description":"Brief RSS 2.0 feed"}}}}, "/feed.xml": { "get": { "operationId": "readFeed", "responses": { "200": { "description": "Public RSS 2.0 feed" } } } }, "/api/journal": { "get": { "operationId": "findJournalEntries", "summary": "Search published discoveries; dates are first publication dates in Europe/Berlin", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "kind", "in": "query", "schema": { "type": "string" } }, { "name": "date", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid input" }, "401": { "description": "Role key required" }, "409": { "description": "Revision conflict" }, "503": { "description": "Service unavailable" } } } }, "/api/agent/journal": { "get": { "operationId": "listJournalDrafts", "security": [ { "writeKey": [] } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid input" }, "401": { "description": "Role key required" }, "409": { "description": "Revision conflict" }, "503": { "description": "Service unavailable" } } }, "put": { "operationId": "saveJournalDraft", "security": [ { "writeKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "id", "title", "kind", "summary", "whyItMatters", "tryThis", "sourceUrl", "sourceLabel", "evidence", "relatedWorkflowId", "tags", "expectedRevision" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "kind": { "type": "string", "enum": [ "Launch", "Tool", "Use case", "Opportunity", "News", "Open models" ] }, "summary": { "type": "string" }, "whyItMatters": { "type": "string" }, "tryThis": { "type": "string" }, "sourceUrl": { "type": [ "string", "null" ], "format": "uri" }, "sourceLabel": { "type": "string" }, "evidence": { "type": "string", "enum": [ "Official source", "Original template", "Community report" ] }, "relatedWorkflowId": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "expectedRevision": { "type": "integer", "minimum": 0 } } } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid input" }, "401": { "description": "Role key required" }, "409": { "description": "Revision conflict" }, "503": { "description": "Service unavailable" } } } }, "/api/agent/journal/publish": { "post": { "operationId": "publishJournalEntry", "security": [ { "publishKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "expectedRevision", "status" ], "properties": { "id": { "type": "string" }, "expectedRevision": { "type": "integer" }, "status": { "type": "string", "enum": [ "published", "archived" ] } } } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid input" }, "401": { "description": "Role key required" }, "409": { "description": "Revision conflict" }, "503": { "description": "Service unavailable" } } } }, "/api/sponsors": { "get": { "operationId": "getSponsorOffer", "summary": "Get the free seven-day launch offer and unexpired rotating sponsors", "responses": { "200": { "description": "price=0, freeLaunch=true, days=7, rotationSeconds=8, checkoutAvailable=true, nextAvailable, active and sponsors" }, "503": { "description": "Temporarily unavailable" } } } }, "/api/sponsors/free": { "post": { "operationId": "publishFreeSponsorRibbon", "summary": "Publish a free seven-day ribbon placement during launch; one active placement per hostname", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": ["requestId", "brand", "pitch", "url"], "properties": { "requestId": {"type": "string", "format": "uuid"}, "brand": {"type": "string", "minLength": 1, "maxLength": 32}, "pitch": {"type": "string", "minLength": 1, "maxLength": 40}, "url": {"type": "string", "format": "uri", "description": "Public HTTPS website"} } } } } }, "responses": { "201": {"description": "Placement published immediately; private receiptUrl returned"}, "400": {"description": "Invalid brand, pitch or URL"}, "409": {"description": "This hostname already has an active free placement"}, "410": {"description": "Free launch has ended"}, "429": {"description": "Global limit of 60 bookings per hour reached"}, "503": {"description": "Service unavailable"} } } }, "/api/sponsors/checkout": { "post": { "operationId": "bookSponsorRibbon", "summary": "Paid checkout is disabled while free launch is active", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "requestId", "brand", "pitch", "url" ], "properties": { "requestId": { "type": "string", "format": "uuid" }, "brand": { "type": "string", "minLength": 1, "maxLength": 32 }, "pitch": { "type": "string", "minLength": 1, "maxLength": 40 }, "url": { "type": "string", "format": "uri", "description": "Public HTTPS website" } } } } } }, "responses": { "201": { "description": "PayPal checkoutUrl and private receiptUrl; buyer authorization still required" }, "400": { "description": "Invalid input" }, "409": { "description": "Request ID already used with different details" }, "429": { "description": "Retry later" }, "503": { "description": "Checkout not connected or temporarily unavailable; never treat as payment" } } } }, "/api/sponsors/receipt": { "post": { "operationId": "confirmSponsorReceipt", "summary": "Confirm approved payment and read private placement dates", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "receipt" ], "properties": { "receipt": { "type": "string", "format": "uuid", "description": "Private token from receiptUrl" } } } } } }, "responses": { "200": { "description": "Payment state and start/end dates" }, "404": { "description": "Unknown receipt" }, "503": { "description": "Payment confirmation pending or unavailable" } } } } }, "components": { "securitySchemes": { "writeKey": { "type": "http", "scheme": "bearer", "description": "AGENT_WRITE_KEY" }, "publishKey": { "type": "http", "scheme": "bearer", "description": "AGENT_PUBLISH_KEY" } } } }