{"openapi":"3.1.0","info":{"title":"Vincent Socci Public Discovery API","summary":"Read-only public JSON for Vincent Socci profile, insights, and site discovery.","description":"Read-only public endpoints for agent and machine discovery of profile, insights, and site metadata on vinsocci.com. No authentication required. Optional anonymous Bearer tokens advertise scope public:read.\n\nVersioning: URL path /api/v1. Additive changes stay in v1. Breaking changes ship as /api/v2 with at least 180 days of overlap. Deprecation is signaled with Deprecation and Sunset response headers and documented at /developers#versioning.","version":"1.0.0","contact":{"name":"Vincent Socci","url":"https://vinsocci.com/contact","email":"vinsocci@gmail.com"},"license":{"name":"Site content — see Privacy and Terms","url":"https://vinsocci.com/privacy"},"termsOfService":"https://vinsocci.com/tos"},"servers":[{"url":"https://vinsocci.com","description":"Production (URL versioning via /api/v1)"}],"tags":[{"name":"Status","description":"Liveness and API index"},{"name":"Profile","description":"Vincent Socci biography and facts"},{"name":"Insights","description":"Published articles"},{"name":"Agent content","description":"llms.txt and related agent files"}],"paths":{"/api/v1":{"get":{"operationId":"getApiIndex","summary":"API index","description":"List the public v1 endpoints, documentation URLs, auth model, rate-limit policy, and versioning policy. Call this first when discovering the API.","tags":["Status"],"responses":{"200":{"description":"API index","headers":{"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiIndex"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"405":{"description":"Method not allowed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited. Honor Retry-After and RateLimit headers.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Internal error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/health":{"get":{"operationId":"getHealth","summary":"Service health","description":"Liveness check for the Vincent Socci public discovery API. Returns status, service name, API version, and a timestamp.","tags":["Status"],"responses":{"200":{"description":"Service is healthy","headers":{"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"405":{"description":"Method not allowed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited. Honor Retry-After and RateLimit headers.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Internal error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/profile":{"get":{"operationId":"getProfile","summary":"Public profile of Vincent Socci","description":"Structured biography, key facts, recognition, expertise, education, and contact links for Vincent Socci. Use this when answering questions about his role, firm, or how to contact him.","tags":["Profile"],"responses":{"200":{"description":"Profile payload","headers":{"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Profile"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"405":{"description":"Method not allowed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited. Honor Retry-After and RateLimit headers.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Internal error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/insights":{"get":{"operationId":"listInsights","summary":"List published insight articles","description":"Return every published insight with slug, title, dates, topic, and canonical URL. Use getInsightBySlug for full markdown.","tags":["Insights"],"responses":{"200":{"description":"Insight list","headers":{"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InsightList"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"405":{"description":"Method not allowed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited. Honor Retry-After and RateLimit headers.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Internal error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/insights/{slug}":{"get":{"operationId":"getInsightBySlug","summary":"Get one insight article","description":"Return one published insight by slug, including the markdown body. 404 problem+json if the slug does not exist.","tags":["Insights"],"parameters":[{"name":"slug","in":"path","required":true,"description":"URL slug, e.g. ai-governance-for-brokerages","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Insight document","headers":{"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InsightDocument"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"405":{"description":"Method not allowed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited. Honor Retry-After and RateLimit headers.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Internal error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/llms.txt":{"get":{"operationId":"getLlmsTxt","summary":"LLM-friendly site summary (llms.txt)","description":"Plain-text index of Vincent Socci's site for agents, including when-to-use guidance and developer resource URLs.","tags":["Agent content"],"responses":{"200":{"description":"Plain-text summary","content":{"text/plain":{"schema":{"type":"string"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"405":{"description":"Method not allowed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited. Honor Retry-After and RateLimit headers.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Internal error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/llms-full.txt":{"get":{"operationId":"getLlmsFullTxt","summary":"Full LLM-friendly site content","description":"Longer plain-text dump of biography, company facts, initiatives, and insights.","tags":["Agent content"],"responses":{"200":{"description":"Plain-text full summary","content":{"text/plain":{"schema":{"type":"string"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"405":{"description":"Method not allowed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited. Honor Retry-After and RateLimit headers.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Internal error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}},"components":{"schemas":{"Problem":{"type":"object","additionalProperties":true,"required":["type","title","status","detail","code","hint"],"properties":{"type":{"type":"string","format":"uri","description":"RFC 9457 problem type URI"},"title":{"type":"string","description":"Short, stable summary of the problem type"},"status":{"type":"integer","description":"HTTP status code for this occurrence"},"detail":{"type":"string","description":"Human-readable explanation of this occurrence"},"instance":{"type":"string","format":"uri","description":"URI identifying this occurrence"},"code":{"type":"string","description":"Machine-readable error code (e.g. not_found, rate_limited)"},"hint":{"type":"string","description":"What an agent should do next to recover"}}},"Health":{"type":"object","additionalProperties":false,"required":["status","service","version","apiVersion","url","checkedAt"],"properties":{"status":{"type":"string","enum":["ok"]},"service":{"type":"string"},"version":{"type":"string"},"apiVersion":{"type":"string","description":"URL-path API version"},"url":{"type":"string","format":"uri"},"checkedAt":{"type":"string","format":"date-time"}}},"ProfileContact":{"type":"object","additionalProperties":false,"required":["form","phone","email","linkedin","x","substack","youtube","companyBio"],"properties":{"form":{"type":"string","format":"uri"},"phone":{"type":"string"},"email":{"type":"string","format":"email"},"linkedin":{"type":"string","format":"uri"},"x":{"type":"string","format":"uri"},"substack":{"type":"string","format":"uri"},"youtube":{"type":"string","format":"uri"},"companyBio":{"type":"string","format":"uri"}}},"SiteLink":{"type":"object","additionalProperties":false,"required":["label","url","desc"],"properties":{"label":{"type":"string"},"url":{"type":"string","format":"uri"},"desc":{"type":"string"}}},"ProfileUrls":{"type":"object","additionalProperties":false,"required":["home","about","developers","llmsTxt","llmsFull","apiCatalog","openapi"],"properties":{"home":{"type":"string","format":"uri"},"about":{"type":"string","format":"uri"},"developers":{"type":"string","format":"uri"},"llmsTxt":{"type":"string","format":"uri"},"llmsFull":{"type":"string","format":"uri"},"apiCatalog":{"type":"string","format":"uri"},"openapi":{"type":"string","format":"uri"}}},"Profile":{"type":"object","additionalProperties":false,"required":["name","tagline","about","keyFacts","recognition","expertise","education","contact","siteStructure","lastUpdated","urls"],"properties":{"name":{"type":"string"},"tagline":{"type":"string"},"about":{"type":"array","items":{"type":"string"}},"keyFacts":{"type":"array","items":{"type":"string"}},"recognition":{"type":"array","items":{"type":"string"}},"expertise":{"type":"array","items":{"type":"string"}},"education":{"type":"array","items":{"type":"string"}},"contact":{"$ref":"#/components/schemas/ProfileContact"},"siteStructure":{"type":"array","items":{"$ref":"#/components/schemas/SiteLink"}},"lastUpdated":{"type":"string","format":"date"},"urls":{"$ref":"#/components/schemas/ProfileUrls"}}},"InsightSummary":{"type":"object","additionalProperties":false,"required":["slug","title","description","date","dateISO","dateModifiedISO","topic","readTime","url"],"properties":{"slug":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"date":{"type":"string","description":"Display date"},"dateISO":{"type":"string","format":"date"},"dateModifiedISO":{"type":"string","format":"date"},"topic":{"type":"string"},"readTime":{"type":"string"},"url":{"type":"string","format":"uri"}}},"InsightList":{"type":"object","additionalProperties":false,"required":["count","items"],"properties":{"count":{"type":"integer","minimum":0},"items":{"type":"array","items":{"$ref":"#/components/schemas/InsightSummary"}}}},"InsightDocument":{"type":"object","additionalProperties":false,"required":["slug","title","description","date","dateISO","dateModifiedISO","topic","readTime","url","content"],"properties":{"slug":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"date":{"type":"string","description":"Display date"},"dateISO":{"type":"string","format":"date"},"dateModifiedISO":{"type":"string","format":"date"},"topic":{"type":"string"},"readTime":{"type":"string"},"url":{"type":"string","format":"uri"},"content":{"type":"string","description":"Markdown body of the article"}}},"ApiIndex":{"type":"object","additionalProperties":false,"required":["name","apiVersion","documentation","openapi","auth","rateLimit","versioning","endpoints"],"properties":{"name":{"type":"string"},"apiVersion":{"type":"string"},"documentation":{"type":"string","format":"uri"},"openapi":{"type":"string","format":"uri"},"auth":{"type":"string"},"rateLimit":{"type":"string"},"versioning":{"type":"string"},"endpoints":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["method","path","description"],"properties":{"method":{"type":"string"},"path":{"type":"string"},"description":{"type":"string"}}}}}}},"headers":{"RateLimit":{"description":"IETF RateLimit header. Example: \"public\";r=119;t=58 (remaining, seconds until window reset).","schema":{"type":"string"}},"RateLimitPolicy":{"description":"IETF RateLimit-Policy header. Example: \"public\";q=120;w=60 (quota, window seconds).","schema":{"type":"string"}},"RetryAfter":{"description":"Seconds to wait before retrying a 429.","schema":{"type":"integer"}},"ApiVersion":{"description":"Current URL-path API version (1).","schema":{"type":"string"}}},"securitySchemes":{"optionalBearer":{"type":"http","scheme":"bearer","description":"Optional. All public GET endpoints work unauthenticated. Self-serve tokens: POST /agent/register. See /auth.md."}}},"security":[],"externalDocs":{"description":"Vincent Socci developer portal — quickstart, sandbox, CLI, errors, versioning","url":"https://vinsocci.com/developers"}}