{"components":{"schemas":{"PublicArticle":{"properties":{"author":{"type":"string"},"correctedAt":{"format":"date-time","type":["string","null"]},"correctionNote":{"type":["string","null"]},"dek":{"type":"string"},"headline":{"type":"string"},"modifiedAt":{"format":"date-time","type":"string"},"publishedAt":{"format":"date-time","type":["string","null"]},"section":{"type":"string"},"slug":{"type":"string"},"sources":{"items":{"properties":{"note":{"maxLength":500,"type":"string"},"publisher":{"maxLength":160,"type":"string"},"title":{"maxLength":240,"minLength":2,"type":"string"},"url":{"format":"uri","maxLength":2000,"pattern":"^https://","type":"string"}},"required":["title","url"],"type":"object"},"maxItems":30,"type":"array"},"url":{"format":"uri","type":"string"}},"required":["author","correctedAt","correctionNote","dek","headline","modifiedAt","publishedAt","section","slug","sources","url"],"type":"object"}},"securitySchemes":{"bearerAuth":{"bearerFormat":"opaque","description":"Agent access token from WorkOS auth.md v0.6.0 service_auth. POST /api/agent/identity, complete /agent/claim, then POST /api/agent/token with grant_type=urn:workos:agent-auth:grant-type:claim. Scopes: article:draft and article:edit only.","scheme":"bearer","type":"http"}}},"info":{"description":"Public markdown, MCP discovery, auth.md service_auth, Streamable HTTP MCP, and editorial write routes.","title":"ConstructionMagazine.ai","version":"0.1.0"},"openapi":"3.1.0","paths":{"/":{"get":{"description":"HTML for browsers. Markdown or JSON when Accept asks for text/markdown or application/json.","operationId":"getHomepage","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"articles":{"type":"array"},"description":{"type":"string"},"name":{"type":"string"},"openapi":{"type":"string"}},"type":"object"}},"text/html":{"schema":{"type":"string"}},"text/markdown":{"schema":{"type":"string"}}},"description":"Magazine homepage."}}}},"/.well-known/mcp.json":{"get":{"description":"MCP discovery card. endpoint is the Streamable HTTP MCP server at /api/mcp.","operationId":"getMcpDiscoveryCard","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"description":{"type":"string"},"endpoint":{"type":"string"},"name":{"type":"string"},"transport":{"enum":["streamable-http"],"type":"string"}},"required":["name","description","endpoint","transport"],"type":"object"}}},"description":"MCP discovery card JSON."}}}},"/{section}/{slug}":{"get":{"description":"HTML for browsers. Markdown when Accept contains text/markdown; proxy rewrites that request to the public markdown route.","operationId":"getPublicArticle","parameters":[{"description":"Public desk slug.","in":"path","name":"section","required":true,"schema":{"enum":["field-operations","robotics","software","benchmarks","people"],"type":"string"}},{"description":"Public article slug.","in":"path","name":"slug","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Published article as HTML or markdown."},"404":{"description":"Unknown desk or unpublished article."}}}},"/api":{"get":{"description":"Public API index with links to OpenAPI, llms.txt, and MCP.","operationId":"getApiIndex","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"articles":{"type":"string"},"description":{"type":"string"},"llms":{"type":"string"},"mcp":{"type":"string"},"name":{"type":"string"},"openapi":{"type":"string"},"resource_metadata":{"type":"string"},"sitemap":{"type":"string"}},"required":["name","openapi","articles"],"type":"object"}}},"description":"API catalog JSON."}}}},"/api/admin/articles":{"post":{"description":"Create an article draft. Requires article:draft. Same body as createArticleSchema.","operationId":"createAdminArticle","requestBody":{"content":{"application/json":{"schema":{"properties":{"authorId":{"format":"uuid","type":"string"},"bodyBlocks":{"items":{"properties":{"id":{"type":"string"},"text":{"type":"string"},"type":{"enum":["paragraph","heading","subheading","quote","list"],"type":"string"}},"required":["id","text","type"],"type":"object"},"minItems":1,"type":"array"},"correctionNote":{"maxLength":2000,"minLength":20,"type":["string","null"]},"dek":{"maxLength":240,"minLength":1,"type":"string"},"editorialPacket":{"properties":{"claimsReview":{"type":"string"},"editorialStatus":{"type":"string"},"factCheckNotes":{"type":"string"},"heroBrief":{"type":"string"},"reportingGaps":{"type":"string"},"seoDescription":{"type":"string"},"seoTitle":{"type":"string"},"socialExcerpt":{"type":"string"},"sourceNotes":{"type":"string"}},"type":"object"},"headline":{"maxLength":110,"minLength":1,"type":"string"},"heroAssetId":{"format":"uuid","type":["string","null"]},"section":{"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","type":"string"},"slug":{"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","type":"string"},"sources":{"items":{"properties":{"note":{"maxLength":500,"type":"string"},"publisher":{"maxLength":160,"type":"string"},"title":{"maxLength":240,"minLength":2,"type":"string"},"url":{"format":"uri","maxLength":2000,"pattern":"^https://","type":"string"}},"required":["title","url"],"type":"object"},"maxItems":30,"type":"array"},"sponsorshipDisclosure":{"maxLength":1000,"type":["string","null"]},"tagIds":{"items":{"format":"uuid","type":"string"},"maxItems":20,"type":"array"}},"required":["bodyBlocks","dek","headline","section","slug"],"type":"object"}}},"required":true},"responses":{"201":{"description":"Created article draft."},"401":{"description":"Missing or invalid bearer or cookie session."}},"security":[{"bearerAuth":[]}]}},"/api/admin/articles/{articleId}/revisions":{"post":{"description":"Save an article revision. Requires article:edit. Same body as saveRevisionSchema, including baseRevision.","operationId":"saveAdminArticleRevision","parameters":[{"description":"Article id.","in":"path","name":"articleId","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"authorId":{"format":"uuid","type":"string"},"bodyBlocks":{"items":{"properties":{"id":{"type":"string"},"text":{"type":"string"},"type":{"enum":["paragraph","heading","subheading","quote","list"],"type":"string"}},"required":["id","text","type"],"type":"object"},"minItems":1,"type":"array"},"correctionNote":{"maxLength":2000,"minLength":20,"type":["string","null"]},"dek":{"maxLength":240,"minLength":1,"type":"string"},"editorialPacket":{"properties":{"claimsReview":{"type":"string"},"editorialStatus":{"type":"string"},"factCheckNotes":{"type":"string"},"heroBrief":{"type":"string"},"reportingGaps":{"type":"string"},"seoDescription":{"type":"string"},"seoTitle":{"type":"string"},"socialExcerpt":{"type":"string"},"sourceNotes":{"type":"string"}},"type":"object"},"headline":{"maxLength":110,"minLength":1,"type":"string"},"heroAssetId":{"format":"uuid","type":["string","null"]},"section":{"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","type":"string"},"slug":{"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","type":"string"},"sources":{"items":{"properties":{"note":{"maxLength":500,"type":"string"},"publisher":{"maxLength":160,"type":"string"},"title":{"maxLength":240,"minLength":2,"type":"string"},"url":{"format":"uri","maxLength":2000,"pattern":"^https://","type":"string"}},"required":["title","url"],"type":"object"},"maxItems":30,"type":"array"},"sponsorshipDisclosure":{"maxLength":1000,"type":["string","null"]},"tagIds":{"items":{"format":"uuid","type":"string"},"maxItems":20,"type":"array"},"baseRevision":{"minimum":0,"type":"integer"}},"required":["baseRevision","bodyBlocks","dek","headline","section","slug"],"type":"object"}}},"required":true},"responses":{"201":{"description":"Saved revision."},"401":{"description":"Missing or invalid bearer or cookie session."}},"security":[{"bearerAuth":[]}]}},"/api/agent/identity":{"post":{"description":"WorkOS auth.md v0.6.0 service_auth identity. Creates a registration and claim attempt. login_hint is optional.","operationId":"createAgentIdentity","requestBody":{"content":{"application/json":{"schema":{"properties":{"login_hint":{"type":"string"},"type":{"enum":["service_auth"],"type":"string"}},"required":["type"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"claim_token":{"type":"string"},"expires_in":{"type":"integer"},"interval":{"type":"integer"},"user_code":{"type":"string"},"verification_uri":{"type":"string"}},"required":["claim_token","user_code","verification_uri","interval","expires_in"],"type":"object"}}},"description":"Claim attempt for the editor to complete at /agent/claim."}}}},"/api/agent/token":{"post":{"description":"Issues a 15-minute Bearer token after the editor completes the claim. grant_type must be the auth.md claim grant. device_code is rejected.","operationId":"createAgentToken","requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"properties":{"claim_token":{"type":"string"},"grant_type":{"enum":["urn:workos:agent-auth:grant-type:claim"],"type":"string"}},"required":["grant_type","claim_token"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"access_token":{"type":"string"},"expires_in":{"enum":[900],"type":"integer"},"scope":{"type":"string"},"token_type":{"enum":["Bearer"],"type":"string"}},"required":["access_token","token_type","expires_in","scope"],"type":"object"}}},"description":"Bearer access token with article:draft and article:edit."},"400":{"description":"authorization_pending while the editor has not claimed, or slow_down when polled early."}}}},"/api/mcp":{"post":{"description":"Streamable HTTP MCP. JSON-RPC 2.0 methods initialize, notifications/initialized, tools/list, and tools/call. Tools: list_articles, get_article, create_article, save_revision. No publish or approve.","operationId":"postEditorialMcp","requestBody":{"content":{"application/json":{"schema":{"properties":{"id":{"description":"JSON-RPC request id."},"jsonrpc":{"enum":["2.0"],"type":"string"},"method":{"type":"string"},"params":{"type":"object"}},"required":["jsonrpc","method"],"type":"object"}}},"required":true},"responses":{"200":{"description":"JSON-RPC result."},"401":{"description":"Missing or invalid bearer. WWW-Authenticate: Bearer resource_metadata=\"https://constructionmagazine.ai/.well-known/oauth-protected-resource\"."}},"security":[{"bearerAuth":[]},{"bearerAuth":[]}]}},"/api/public/articles":{"get":{"description":"Published articles as JSON. Missing API paths return {code, error, hint}.","operationId":"listPublicArticles","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"articles":{"items":{"$ref":"#/components/schemas/PublicArticle"},"type":"array"}},"required":["articles"],"type":"object"}}},"description":"Published article index."}}}},"/api/public/articles/{section}/{slug}":{"get":{"description":"One published article as JSON, including public sources and correction metadata.","operationId":"getPublicJsonArticle","parameters":[{"description":"Public desk slug.","in":"path","name":"section","required":true,"schema":{"enum":["field-operations","robotics","software","benchmarks","people"],"type":"string"}},{"description":"Public article slug.","in":"path","name":"slug","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicArticle"}}},"description":"Published article JSON."},"404":{"description":"Unpublished or unknown article."}}}},"/api/public/markdown/{section}/{slug}":{"get":{"description":"Published article as text/markdown. Missing articles return HTTP 404 markdown that points at /llms.txt and /sitemap.xml.","operationId":"getPublicMarkdownArticle","parameters":[{"description":"Public desk slug.","in":"path","name":"section","required":true,"schema":{"enum":["field-operations","robotics","software","benchmarks","people"],"type":"string"}},{"description":"Public article slug.","in":"path","name":"slug","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"text/markdown":{"schema":{"type":"string"}}},"description":"Published article markdown.","headers":{"Vary":{"description":"Accept","schema":{"type":"string"}}}},"404":{"content":{"text/markdown":{"schema":{"type":"string"}}},"description":"Unpublished or unknown article."}}}}},"servers":[{"url":"https://constructionmagazine.ai"}]}