{ "openapi": "3.1.0", "info": { "title": "Ravicha Suksawasdi Na Ayuthaya — Portfolio Agent API", "version": "1.0.0", "summary": "The machine-readable surface of a systems-engineering portfolio: discovery, context, and identity documents.", "description": "A read-only, publicly reachable collection of documents for agents, served as static files from GitHub Pages.\n\nEverything here belongs to Ravicha Suksawasdi Na Ayuthaya (Palm), an applied AI and backend systems engineer. The API answers three questions: what this site is (discovery), what the work is (context), and who made it (identity).\n\n**There is no authentication and no write surface.** Nothing here mutates state, so there is nothing to protect and no key to issue. `POST`, `PUT`, `PATCH` and `DELETE` are not implemented on any path and the origin answers them the same way it answers any unknown request.\n\n**Versioning.** The document carries a semantic `info.version`. The paths are stable; a breaking change to a documented shape increments the major version and is announced in `/llms.txt`, which is the changelog agents are told to watch.\n\n**Errors.** Every operation documents the 404 it really returns: the site 404 document as `text/html`, for every `Accept`. The `application/problem+json` envelope is described under `x-error-model` and `components.schemas.Problem` but is not served and cannot be on static hosting. ADR 0004 records the decision to accept the limitation and state it rather than add an edge layer.", "contact": { "name": "Ravicha Suksawasdi Na Ayuthaya", "email": "palm.ravicha@outlook.com", "url": "https://ravicha2.github.io/contact/" }, "license": { "name": "Content published for reference and citation.", "identifier": "CC-BY-4.0" } }, "servers": [ { "url": "https://ravicha2.github.io", "description": "Production. Static files on GitHub Pages; every operation is a GET of a real document." } ], "tags": [ { "name": "discovery", "description": "Documents that tell an agent what is here." }, { "name": "context", "description": "Documents that tell an agent what the work is." }, { "name": "meta", "description": "The API description itself." } ], "paths": { "/openapi.json": { "get": { "tags": [ "meta" ], "operationId": "getOpenApiDocument", "summary": "The OpenAPI document for this API", "description": "Returns this document. An agent that has found it can enumerate every other operation without fetching anything else.", "responses": { "200": { "description": "This document, as JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "This OpenAPI 3.1 document." } } } }, "404": { "description": "No such document. GitHub Pages answers with the site 404 document as text/html; the request also lands in the SPA, which renders the same message.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/.well-known/mcp/server-card.json": { "get": { "tags": [ "discovery" ], "operationId": "getMcpServerCard", "summary": "MCP Server Card for the published MCP server", "description": "A Server Card describing how to reach the first-party MCP server, per the server-card extension chartered by SEP-2127. Contains no tools: agents read those from the server itself with tools/list. The card is a real file here; the bare SEP-2127 namespace path /.well-known/mcp is a directory on GitHub Pages and carries the same bytes from its index, reached through a trailing-slash redirect.", "responses": { "200": { "description": "A Server Card.", "content": { "application/json": { "schema": { "type": "object", "description": "An MCP Server Card, per the server-card extension chartered by SEP-2127.", "required": [ "$schema", "name", "version", "description" ], "properties": { "$schema": { "type": "string", "format": "uri" }, "name": { "type": "string", "description": "Reverse-DNS identity, exactly one slash between namespace and server name.", "pattern": "^[a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+$" }, "title": { "type": "string" }, "description": { "type": "string", "maxLength": 100 }, "version": { "type": "string" }, "websiteUrl": { "type": "string", "format": "uri" }, "repository": { "type": "object", "required": [ "source", "url" ], "properties": { "source": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "subfolder": { "type": "string" } } }, "remotes": { "type": "array", "description": "Where the server can be reached. Each entry names its transport.", "items": { "type": "object", "required": [ "type", "url" ], "properties": { "type": { "type": "string", "enum": [ "sse", "streamable-http" ] }, "url": { "type": "string" }, "supportedProtocolVersions": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "404": { "description": "No such document. GitHub Pages answers with the site 404 document as text/html; the request also lands in the SPA, which renders the same message.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/.well-known/agent-skills/index.json": { "get": { "tags": [ "discovery" ], "operationId": "getAgentSkillsIndex", "summary": "Agent Skills index", "description": "Lists the skills this origin can be asked for, each with a name, a description, and the URL that serves it.", "responses": { "200": { "description": "The skills index.", "content": { "application/json": { "schema": { "type": "object", "description": "An Agent Skills discovery index (v0.2.0): the skills this origin offers, each with a description and the URL that serves it.", "required": [ "$schema", "skills" ], "properties": { "$schema": { "type": "string", "format": "uri", "description": "The discovery schema this index conforms to, version 0.2.0." }, "skills": { "type": "array", "items": { "type": "object", "required": [ "name", "type", "description", "url", "digest" ], "properties": { "name": { "type": "string" }, "type": { "type": "string", "description": "The kind of document the entry points at; skill-md here." }, "description": { "type": "string" }, "url": { "type": "string", "description": "The path that serves the skill document." }, "digest": { "type": "string", "description": "The SHA-256 of the skill document bytes, written as sha256:." } } } } } } } } }, "404": { "description": "No such document. GitHub Pages answers with the site 404 document as text/html; the request also lands in the SPA, which renders the same message.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/.well-known/agent-card.json": { "get": { "tags": [ "discovery" ], "operationId": "getAgentCard", "summary": "A2A agent card", "description": "The Agent2Agent card: who this is, and the tasks an agent can delegate. Every skill is read-only research over published material. No A2A interface is served — this origin is static — so supportedInterfaces is empty and capabilities declares nothing.", "responses": { "200": { "description": "The agent card.", "content": { "application/json": { "schema": { "type": "object", "description": "An Agent2Agent agent card, in the v1.0 shape. The endpoint lives in supportedInterfaces[], not in a top-level url, and there is no top-level protocolVersion.", "required": [ "name", "description", "supportedInterfaces", "version", "capabilities", "defaultInputModes", "defaultOutputModes", "skills" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "version": { "type": "string" }, "supportedInterfaces": { "type": "array", "description": "Where the agent is reachable, in preference order. Empty here: no A2A interface is served.", "items": { "type": "object", "required": [ "url", "protocolBinding", "protocolVersion" ], "properties": { "url": { "type": "string", "format": "uri" }, "protocolBinding": { "type": "string" }, "protocolVersion": { "type": "string" }, "tenant": { "type": "string" } } } }, "provider": { "type": "object", "properties": { "organization": { "type": "string" }, "url": { "type": "string", "format": "uri" } } }, "capabilities": { "type": "object", "description": "What the agent can do beyond a plain request/response. Empty: nothing beyond a static read.", "properties": { "streaming": { "type": "boolean" }, "pushNotifications": { "type": "boolean" }, "extendedAgentCard": { "type": "boolean" }, "extensions": { "type": "array", "items": { "type": "object" } } } }, "defaultInputModes": { "type": "array", "items": { "type": "string" } }, "defaultOutputModes": { "type": "array", "items": { "type": "string" } }, "skills": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "description", "tags" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "404": { "description": "No such document. GitHub Pages answers with the site 404 document as text/html; the request also lands in the SPA, which renders the same message.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/.well-known/api-catalog": { "get": { "tags": [ "discovery" ], "operationId": "getApiCatalog", "summary": "RFC 9727 API catalog", "description": "An RFC 9264 linkset, profiled by RFC 9727, pointing at this document and the other machine-readable service descriptions on the origin. The document is a linkset, and RFC 9727 asks for the application/linkset+json media type; GitHub Pages derives the content type from the file extension, and this path has none, so the origin cannot send that type and serves the document as application/octet-stream instead. A static host cannot set the header, so the document states the gap rather than claiming the type. ADR 0005 decision 5 records the rule.", "responses": { "200": { "description": "A linkset with one item per service description.", "content": { "application/octet-stream": { "schema": { "type": "object", "description": "An RFC 9264 linkset, as profiled for API discovery by RFC 9727.", "required": [ "linkset" ], "properties": { "linkset": { "type": "array", "items": { "type": "object", "required": [ "anchor", "item" ], "properties": { "anchor": { "type": "string", "format": "uri", "description": "The context these links describe." }, "item": { "type": "array", "items": { "type": "object", "required": [ "href" ], "properties": { "href": { "type": "string", "format": "uri" }, "type": { "type": "string", "description": "The media type of the target." }, "title": { "type": "string" } } } } } } } } } } } }, "404": { "description": "No such document. GitHub Pages answers with the site 404 document as text/html; the request also lands in the SPA, which renders the same message.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/.well-known/oauth-protected-resource": { "get": { "tags": [ "discovery" ], "operationId": "getProtectedResourceMetadata", "summary": "OAuth 2.0 protected resource metadata", "description": "RFC 9728 metadata for this resource. It is public and read-only, so no authorization server is advertised and no scope is required. RFC 9728 asks for the application/json media type, but GitHub Pages derives the content type from the file extension and this path has none, so the origin cannot send that type and serves the document as application/octet-stream instead. The document states the gap rather than claiming the type. ADR 0005 decision 5 records the rule.", "responses": { "200": { "description": "Protected resource metadata.", "content": { "application/octet-stream": { "schema": { "type": "object", "description": "RFC 9728 OAuth 2.0 protected resource metadata.", "required": [ "resource" ], "properties": { "resource": { "type": "string", "format": "uri" }, "authorization_servers": { "type": "array", "items": { "type": "string", "format": "uri" } }, "scopes_supported": { "type": "array", "items": { "type": "string" } }, "bearer_methods_supported": { "type": "array", "items": { "type": "string" } } } } } } }, "404": { "description": "No such document. GitHub Pages answers with the site 404 document as text/html; the request also lands in the SPA, which renders the same message.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/.well-known/ard.json": { "get": { "tags": [ "discovery" ], "operationId": "getArdCatalog", "summary": "Agentic Resource Discovery catalog", "description": "The ARD catalog, listing the agentic resources this origin publishes — its MCP server, its skill index, and its API description — each with a URN identity.", "responses": { "200": { "description": "The ARD catalog.", "content": { "application/json": { "schema": { "type": "object", "description": "An ARD catalog document." } } } }, "404": { "description": "No such document. GitHub Pages answers with the site 404 document as text/html; the request also lands in the SPA, which renders the same message.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/llms.txt": { "get": { "tags": [ "context" ], "operationId": "getLlmsTxt", "summary": "Concise agent guide", "description": "The llmstxt.org index: who this is, what they have built, and when to use the material. The shortest correct answer to \"what is this site\".", "responses": { "200": { "description": "A plain-text markdown index.", "content": { "text/plain": { "schema": { "type": "string", "description": "The llms.txt index.", "x-content-type": "text/plain" } } } }, "404": { "description": "No such document. GitHub Pages answers with the site 404 document as text/html; the request also lands in the SPA, which renders the same message.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/llms-full.txt": { "get": { "tags": [ "context" ], "operationId": "getLlmsFullTxt", "summary": "Full agent dossier", "description": "The long-form dossier behind llms.txt: complete project histories, trade-offs, and verification detail in one document.", "responses": { "200": { "description": "A plain-text markdown dossier.", "content": { "text/plain": { "schema": { "type": "string", "description": "The full dossier.", "x-content-type": "text/plain" } } } }, "404": { "description": "No such document. GitHub Pages answers with the site 404 document as text/html; the request also lands in the SPA, which renders the same message.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/agents.md": { "get": { "tags": [ "context" ], "operationId": "getAgentsMd", "summary": "When to use this site, and how", "description": "The use-case guide: the jobs this material is right for, the jobs it is wrong for, and the order to read it in. Read this before llms.txt if you are deciding whether to use it at all.", "responses": { "200": { "description": "A markdown guide.", "content": { "text/markdown": { "schema": { "type": "string", "description": "The agent use-case guide.", "x-content-type": "text/markdown" } } } }, "404": { "description": "No such document. GitHub Pages answers with the site 404 document as text/html; the request also lands in the SPA, which renders the same message.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/auth.md": { "get": { "tags": [ "context" ], "operationId": "getAuthMd", "summary": "How to authenticate, as prose", "description": "A markdown walkthrough of the auth situation written to the WorkOS auth.md shape. The surface is public and read-only, so the walkthrough concludes that no credential is needed — which is the answer an agent needs before it starts hunting for one.", "responses": { "200": { "description": "A markdown walkthrough.", "content": { "text/markdown": { "schema": { "type": "string", "description": "The auth walkthrough.", "x-content-type": "text/markdown" } } } }, "404": { "description": "No such document. GitHub Pages answers with the site 404 document as text/html; the request also lands in the SPA, which renders the same message.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/index.md": { "get": { "tags": [ "context" ], "operationId": "getMarkdownHome", "summary": "The homepage as markdown", "description": "The site root in markdown, so an agent that lands on the homepage can fetch the same page without parsing HTML. Every content route has a twin at the same path with .md appended.", "responses": { "200": { "description": "A markdown rendering of the homepage.", "content": { "text/markdown": { "schema": { "type": "string", "description": "The homepage as markdown.", "x-content-type": "text/markdown" } } } }, "404": { "description": "No such document. GitHub Pages answers with the site 404 document as text/html; the request also lands in the SPA, which renders the same message.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/.well-known/agent-skills/portfolio/SKILL.md": { "get": { "tags": [ "context" ], "operationId": "getPortfolioSkill", "summary": "The portfolio knowledge skill, as markdown", "description": "The skill document behind the Agent Skills index, served as markdown: what this portfolio contains, how to cite it, and when it is the wrong source. It is the document getAgentSkillsIndex digests and points at, so an agent can read the skill directly instead of resolving it through the index first.", "responses": { "200": { "description": "A markdown skill document.", "content": { "text/markdown": { "schema": { "type": "string", "description": "The portfolio skill document.", "x-content-type": "text/markdown" } } } }, "404": { "description": "No such document. GitHub Pages answers with the site 404 document as text/html; the request also lands in the SPA, which renders the same message.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/sitemap.xml": { "get": { "tags": [ "context" ], "operationId": "getSitemap", "summary": "Sitemap", "description": "Every URL the site answers, with the date its content last changed.", "responses": { "200": { "description": "A sitemap.", "content": { "application/xml": { "schema": { "type": "string", "description": "A sitemap XML document." } } } }, "404": { "description": "No such document. GitHub Pages answers with the site 404 document as text/html; the request also lands in the SPA, which renders the same message.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/cv.pdf": { "get": { "tags": [ "context" ], "operationId": "getCurriculumVitae", "summary": "Curriculum vitae as PDF", "description": "The CV in its printable form, for a caller that wants a file rather than a page.", "responses": { "200": { "description": "A PDF.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary", "description": "A PDF document." } } } }, "404": { "description": "No such document. GitHub Pages answers with the site 404 document as text/html; the request also lands in the SPA, which renders the same message.", "content": { "text/html": { "schema": { "type": "string" } } } } } } } }, "components": { "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details. Described for completeness and deliberately not served: GitHub Pages answers an unmatched path with the 404.html document as text/html for every Accept, and offers no way to set a response header or override the body per media type. See x-error-model and ADR 0004.", "required": [ "type", "title", "status" ], "properties": { "type": { "type": "string", "format": "uri", "description": "A URI identifying the problem type." }, "title": { "type": "string", "description": "A short, human-readable summary." }, "status": { "type": "integer", "description": "The HTTP status code." }, "detail": { "type": "string", "description": "A human-readable explanation of this occurrence." }, "instance": { "type": "string", "format": "uri", "description": "The URI of this occurrence." }, "code": { "type": "string", "description": "A stable machine-readable code, so an agent can branch without parsing prose." }, "hint": { "type": "string", "description": "What to do next." } } }, "McpServerCard": { "type": "object", "description": "An MCP Server Card, per the server-card extension chartered by SEP-2127.", "required": [ "$schema", "name", "version", "description" ], "properties": { "$schema": { "type": "string", "format": "uri" }, "name": { "type": "string", "description": "Reverse-DNS identity, exactly one slash between namespace and server name.", "pattern": "^[a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+$" }, "title": { "type": "string" }, "description": { "type": "string", "maxLength": 100 }, "version": { "type": "string" }, "websiteUrl": { "type": "string", "format": "uri" }, "repository": { "type": "object", "required": [ "source", "url" ], "properties": { "source": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "subfolder": { "type": "string" } } }, "remotes": { "type": "array", "description": "Where the server can be reached. Each entry names its transport.", "items": { "type": "object", "required": [ "type", "url" ], "properties": { "type": { "type": "string", "enum": [ "sse", "streamable-http" ] }, "url": { "type": "string" }, "supportedProtocolVersions": { "type": "array", "items": { "type": "string" } } } } } } }, "Linkset": { "type": "object", "description": "An RFC 9264 linkset, as profiled for API discovery by RFC 9727.", "required": [ "linkset" ], "properties": { "linkset": { "type": "array", "items": { "type": "object", "required": [ "anchor", "item" ], "properties": { "anchor": { "type": "string", "format": "uri", "description": "The context these links describe." }, "item": { "type": "array", "items": { "type": "object", "required": [ "href" ], "properties": { "href": { "type": "string", "format": "uri" }, "type": { "type": "string", "description": "The media type of the target." }, "title": { "type": "string" } } } } } } } } }, "AgentSkillsIndex": { "type": "object", "description": "An Agent Skills discovery index (v0.2.0): the skills this origin offers, each with a description and the URL that serves it.", "required": [ "$schema", "skills" ], "properties": { "$schema": { "type": "string", "format": "uri", "description": "The discovery schema this index conforms to, version 0.2.0." }, "skills": { "type": "array", "items": { "type": "object", "required": [ "name", "type", "description", "url", "digest" ], "properties": { "name": { "type": "string" }, "type": { "type": "string", "description": "The kind of document the entry points at; skill-md here." }, "description": { "type": "string" }, "url": { "type": "string", "description": "The path that serves the skill document." }, "digest": { "type": "string", "description": "The SHA-256 of the skill document bytes, written as sha256:." } } } } } }, "AgentCard": { "type": "object", "description": "An Agent2Agent agent card, in the v1.0 shape. The endpoint lives in supportedInterfaces[], not in a top-level url, and there is no top-level protocolVersion.", "required": [ "name", "description", "supportedInterfaces", "version", "capabilities", "defaultInputModes", "defaultOutputModes", "skills" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "version": { "type": "string" }, "supportedInterfaces": { "type": "array", "description": "Where the agent is reachable, in preference order. Empty here: no A2A interface is served.", "items": { "type": "object", "required": [ "url", "protocolBinding", "protocolVersion" ], "properties": { "url": { "type": "string", "format": "uri" }, "protocolBinding": { "type": "string" }, "protocolVersion": { "type": "string" }, "tenant": { "type": "string" } } } }, "provider": { "type": "object", "properties": { "organization": { "type": "string" }, "url": { "type": "string", "format": "uri" } } }, "capabilities": { "type": "object", "description": "What the agent can do beyond a plain request/response. Empty: nothing beyond a static read.", "properties": { "streaming": { "type": "boolean" }, "pushNotifications": { "type": "boolean" }, "extendedAgentCard": { "type": "boolean" }, "extensions": { "type": "array", "items": { "type": "object" } } } }, "defaultInputModes": { "type": "array", "items": { "type": "string" } }, "defaultOutputModes": { "type": "array", "items": { "type": "string" } }, "skills": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "description", "tags" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } } } } } }, "ProtectedResourceMetadata": { "type": "object", "description": "RFC 9728 OAuth 2.0 protected resource metadata.", "required": [ "resource" ], "properties": { "resource": { "type": "string", "format": "uri" }, "authorization_servers": { "type": "array", "items": { "type": "string", "format": "uri" } }, "scopes_supported": { "type": "array", "items": { "type": "string" } }, "bearer_methods_supported": { "type": "array", "items": { "type": "string" } } } } } }, "x-error-model": { "status": "not-supported", "decision": "ADR 0004 accepts the HTML 404 and states the limitation, instead of adding an edge layer or changing the host.", "served": { "404": { "description": "GitHub Pages serves the site 404.html document, as text/html, for every unmatched path. It ignores Accept, so a caller that sends text/markdown or application/problem+json gets the same HTML body. The body carries no machine-readable code; an agent has to branch on the 404 status.", "content": { "text/html": { "schema": { "type": "string", "description": "The 404.html document, as HTML." } } } } }, "unsupported": { "application/problem+json": "The RFC 9457 envelope declared as components.schemas.Problem. A static host cannot set a response content type or vary a body by Accept, so this shape is describable but unreachable here.", "vary": "Accept. GitHub Pages varies only on Accept-Encoding and offers no way to add Vary: Accept." }, "note": "The 404 documented on each operation is the text/html document GitHub Pages serves for an unmatched path; the request also lands in the SPA, which renders the same message for a browser. RFC 9457 application/problem+json is described by components.schemas.Problem but is not served, and cannot be on static hosting: the origin cannot set a response content type or vary a body by Accept. ADR 0004 records the decision to accept this and state it." }, "x-authentication": { "required": false, "schemes": [], "note": "Public and read-only. See /auth.md for the walkthrough." } }