{ "openapi": "3.1.0", "info": { "title": "Blossom AI public read API", "version": "1.0.0", "description": "Read-only access to the published content of blossomai.co: company facts, product links and journal posts.\n\nOnly published content is served — drafts, reviews and withdrawn posts are indistinguishable from unknown slugs (404).\n\nA publish or withdrawal shows up within 60 s end to end: the server memo plus `Cache-Control: max-age` never exceed that budget (max-age = 60 s minus the memo TTL, must-revalidate).\n\nNo authentication, no write operations. Be gentle: there is no rate-limit guarantee.\n\nUse and attribution are governed by /ai.txt; being machine-readable grants no additional rights.", "contact": { "email": "hello@blossomai.co" } }, "servers": [ { "url": "https://blossomai.co" } ], "security": [], "paths": { "/api/public/v1": { "get": { "operationId": "getIndex", "summary": "Links to every public machine-readable resource", "responses": { "200": { "description": "Index", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Index" } } } } } } }, "/api/public/v1/site": { "get": { "operationId": "getSite", "summary": "Company facts, offices, contact, products and key pages", "responses": { "200": { "description": "Site facts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Site" } } } } } } }, "/api/public/v1/posts": { "get": { "operationId": "listPosts", "summary": "Published posts, newest display date first", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "cursor", "in": "query", "description": "Opaque; pass `nextCursor` from the previous page unchanged.", "schema": { "type": "string" } }, { "name": "category", "in": "query", "description": "Exact category name, case-insensitive (e.g. `Research`).", "schema": { "type": "string", "maxLength": 64 } } ], "responses": { "200": { "description": "One page of posts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostList" } } } }, "400": { "description": "Invalid `limit`, `category` or `cursor` (`invalid_parameter`, `invalid_cursor`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Content backend unavailable (`content_unavailable`); retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/public/v1/posts/{slug}": { "get": { "operationId": "getPost", "summary": "One published post with its Markdown body", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,127}$" } } ], "responses": { "200": { "description": "The post", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } }, "404": { "description": "No published post at this slug (`not_found`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Content backend unavailable (`content_unavailable`); retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/public/v1/openapi.json": { "get": { "operationId": "getOpenApi", "summary": "This document", "responses": { "200": { "description": "OpenAPI 3.1", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/llms.txt": { "get": { "operationId": "getLlmsTxt", "summary": "Site index for language models (llmstxt.org proposal), with the newest posts", "responses": { "200": { "description": "llms.txt", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/index.md": { "get": { "operationId": "getHomeMarkdown", "summary": "Home page summary as Markdown", "responses": { "200": { "description": "Markdown", "content": { "text/markdown": { "schema": { "type": "string" } } } } } } }, "/products/index.md": { "get": { "operationId": "getProductsMarkdown", "summary": "Products page as Markdown", "responses": { "200": { "description": "Markdown", "content": { "text/markdown": { "schema": { "type": "string" } } } } } } }, "/blog/index.md": { "get": { "operationId": "getArchiveMarkdown", "summary": "Every published post, newest first, as Markdown", "responses": { "200": { "description": "Markdown", "content": { "text/markdown": { "schema": { "type": "string" } } } } } } }, "/blog/{slug}/index.md": { "get": { "operationId": "getPostMarkdown", "summary": "One published post as Markdown with YAML front matter", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Markdown", "content": { "text/markdown": { "schema": { "type": "string" } } } }, "404": { "description": "Not found", "content": { "text/plain": { "schema": { "type": "string" } } } } } } } }, "components": { "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_parameter", "invalid_cursor", "not_found", "content_unavailable" ] }, "message": { "type": "string" } } } } }, "Index": { "type": "object", "required": [ "name", "version", "site", "links" ], "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "site": { "type": "string", "format": "uri" }, "links": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } } } }, "Byline": { "type": "object", "required": [ "name", "kind", "role" ], "properties": { "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "person", "organization" ] }, "role": { "type": [ "string", "null" ], "description": "Public job title of a named author" } } }, "PostSummary": { "type": "object", "required": [ "slug", "title", "excerpt", "category", "tags", "byline", "date", "modifiedAt", "publishedVersion", "readingTime", "image", "links" ], "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "titleJa": { "type": [ "string", "null" ] }, "excerpt": { "type": "string" }, "excerptJa": { "type": [ "string", "null" ] }, "category": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "byline": { "$ref": "#/components/schemas/Byline" }, "date": { "type": "string", "format": "date", "description": "Editorial display date, as shown on the page" }, "modifiedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last change to the published content; null = unchanged since `date`" }, "publishedVersion": { "type": [ "integer", "null" ], "description": "Revision number of the published content; null when unversioned" }, "readingTime": { "type": "string" }, "image": { "type": [ "string", "null" ], "format": "uri" }, "links": { "type": "object", "required": [ "html", "markdown", "api" ], "properties": { "html": { "type": "string", "format": "uri" }, "markdown": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" } } } } }, "Post": { "allOf": [ { "$ref": "#/components/schemas/PostSummary" }, { "type": "object", "required": [ "body" ], "properties": { "body": { "type": "object", "required": [ "format", "markdown" ], "properties": { "format": { "const": "markdown" }, "markdown": { "type": "string" } } } } } ] }, "PostList": { "type": "object", "required": [ "data", "nextCursor", "limit" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PostSummary" } }, "nextCursor": { "type": [ "string", "null" ] }, "limit": { "type": "integer" } } }, "Site": { "type": "object", "required": [ "name", "legalName", "url", "tagline", "description", "offices", "contact", "sameAs", "pages", "products", "relatedSites", "policies" ], "properties": { "name": { "type": "string", "description": "Brand and business name" }, "legalName": { "type": "string", "description": "The company (legal entity)" }, "url": { "type": "string", "format": "uri" }, "tagline": { "type": "string" }, "description": { "type": "string" }, "offices": { "type": "array", "items": { "type": "object", "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "role": { "type": "string" } } } }, "contact": { "type": "object", "properties": { "email": { "type": "string" }, "languages": { "type": "array", "items": { "type": "string" } } } }, "sameAs": { "type": "array", "items": { "type": "string", "format": "uri" } }, "pages": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "markdownUrl": { "type": [ "string", "null" ], "format": "uri" } } } }, "products": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "nameJa": { "type": "string" }, "status": { "type": "string" }, "summary": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } }, "relatedSites": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "description": { "type": "string" } } } }, "policies": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } } } } } } }