{"openapi":"3.1.0","info":{"title":"Pinnn Public API","version":"1.0.0","description":"Public-safe discovery endpoints for published Pinnn creator profiles."},"servers":[{"url":"https://pinnn.me"}],"paths":{"/api/healthz":{"get":{"operationId":"getHealth","summary":"Check public service health","responses":{"200":{"description":"Service is available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}}}},"/api/creators":{"get":{"operationId":"listCreators","summary":"List all published public creators (legacy unpaginated response)","deprecated":true,"responses":{"200":{"description":"Published creators","content":{"application/json":{"schema":{"type":"object","required":["creators"],"properties":{"creators":{"type":"array","items":{"$ref":"#/components/schemas/PublicCreator"}}}}}}}}}},"/api/v1/creators":{"get":{"operationId":"listCreatorDirectoryPage","summary":"List public creator discovery records with cursor pagination","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor returned by the previous response.","schema":{"type":"string"}},{"name":"updated_after","in":"query","required":false,"description":"Return records updated after this ISO 8601 timestamp.","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Bounded public creator directory page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatorDirectoryResponse"}}}},"400":{"description":"Invalid cursor, limit, or updated_after value"}}}},"/api/creators/{handle}":{"get":{"operationId":"getCreator","summary":"Get one published public creator","parameters":[{"name":"handle","in":"path","required":true,"schema":{"type":"string"},"description":"Creator handle with or without the @ prefix."}],"responses":{"200":{"description":"Published creator","content":{"application/json":{"schema":{"type":"object","required":["creator"],"properties":{"creator":{"$ref":"#/components/schemas/PublicCreator"}}}}}},"404":{"description":"Creator is not published or does not exist"}}}},"/api/creators/search":{"get":{"operationId":"searchCreators","summary":"Search published creators by name, handle, alias, or topic","parameters":[{"name":"q","in":"query","required":true,"description":"Search query. At least two normalized characters.","schema":{"type":"string","minLength":2,"maxLength":120}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":10}},{"name":"semantic","in":"query","required":false,"description":"Set false for lexical-only, read-only search.","schema":{"type":"boolean","default":true}}],"responses":{"200":{"description":"Ranked creator search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatorSearchResponse"}}}}}}}},"components":{"schemas":{"Health":{"type":"object","required":["ok","service","checkedAt"],"properties":{"ok":{"type":"boolean"},"service":{"type":"string"},"checkedAt":{"type":"string","format":"date-time"}}},"PublicCreator":{"type":"object","required":["handle","name","bioShort","category","location","language","profileUrl","markdownUrl","updatedAt","verifiedAt","topics","links","pinpageElements","pinpageContent","officialProfiles","discovery","publicEvidenceCount"],"additionalProperties":false,"properties":{"handle":{"type":"string"},"name":{"type":"string"},"bioShort":{"type":"string"},"category":{"type":"string"},"location":{"type":"string"},"language":{"type":"string"},"profileUrl":{"type":"string","format":"uri"},"markdownUrl":{"type":"string","format":"uri"},"updatedAt":{"type":"string","format":"date-time"},"verifiedAt":{"type":["string","null"],"format":"date-time"},"topics":{"type":"array","items":{"type":"object","required":["slug","name"],"additionalProperties":false,"properties":{"slug":{"type":"string"},"name":{"type":"string"}}}},"links":{"type":"array","items":{"type":"object","required":["title","description","url","kind"],"additionalProperties":false,"properties":{"title":{"type":"string"},"description":{"type":"string"},"url":{"type":"string","format":"uri"},"kind":{"type":"string"}}}},"pinpageElements":{"type":"array","items":{"type":"object","required":["id","type","title","url","order"],"additionalProperties":false,"properties":{"id":{"type":"string"},"type":{"type":"string","const":"LINK"},"title":{"type":"string"},"url":{"type":"string","format":"uri"},"order":{"type":"integer"}}}},"pinpageContent":{"type":"array","items":{"type":"object","required":["id","type","kind","title","text","semanticMarker","order"],"additionalProperties":false,"properties":{"id":{"type":"string"},"type":{"type":"string"},"kind":{"type":"string"},"title":{"type":"string"},"text":{"type":"string"},"semanticMarker":{"type":["string","null"]},"order":{"type":"integer"}}}},"officialProfiles":{"type":"array","items":{"type":"object","required":["platform","label","url","handle"],"additionalProperties":false,"properties":{"platform":{"type":"string"},"label":{"type":"string"},"url":{"type":"string","format":"uri"},"handle":{"type":["string","null"]}}}},"discovery":{"type":"object","required":["displayName","aliases","summary","directContactEmail","directContactHref"],"additionalProperties":false,"properties":{"displayName":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}},"summary":{"type":"string"},"directContactEmail":{"type":["string","null"],"format":"email"},"directContactHref":{"type":["string","null"],"format":"uri"}}},"publicEvidenceCount":{"type":"integer","minimum":0}}},"CreatorSearchResult":{"type":"object","required":["handle","displayName","canonicalPath","canonicalUrl","profileMarkdownUrl","summary","matchedAliases","score","scoreReasons","snippet"],"additionalProperties":false,"properties":{"handle":{"type":"string"},"displayName":{"type":"string"},"canonicalPath":{"type":"string"},"canonicalUrl":{"type":"string","format":"uri"},"profileMarkdownUrl":{"type":"string","format":"uri"},"summary":{"type":"string"},"matchedAliases":{"type":"array","items":{"type":"string"}},"score":{"type":"number"},"scoreReasons":{"type":"array","items":{"type":"string"}},"snippet":{"type":"string"}}},"CreatorSearchResponse":{"type":"object","required":["query","normalizedQuery","results"],"additionalProperties":false,"properties":{"query":{"type":"string"},"normalizedQuery":{"type":"string"},"results":{"type":"array","items":{"$ref":"#/components/schemas/CreatorSearchResult"}}}},"CreatorDirectoryEntry":{"type":"object","required":["handle","displayName","canonicalPath","canonicalUrl","profileMarkdownUrl","summary","aliases","topics","updatedAt"],"additionalProperties":false,"properties":{"handle":{"type":"string"},"displayName":{"type":"string"},"canonicalPath":{"type":"string"},"canonicalUrl":{"type":"string","format":"uri"},"profileMarkdownUrl":{"type":"string","format":"uri"},"summary":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}},"topics":{"type":"array","items":{"type":"string"}},"updatedAt":{"type":"string","format":"date-time"}}},"CreatorDirectoryResponse":{"type":"object","required":["schemaVersion","total","updatedAt","items","pageInfo","links"],"additionalProperties":false,"properties":{"schemaVersion":{"type":"integer","const":1},"total":{"type":"integer","minimum":0},"updatedAt":{"type":"string","format":"date-time"},"items":{"type":"array","items":{"$ref":"#/components/schemas/CreatorDirectoryEntry"}},"pageInfo":{"type":"object","required":["limit","hasMore","nextCursor"],"additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"maximum":500},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}},"links":{"type":"object","required":["self","next","manifest","openapi"],"additionalProperties":false,"properties":{"self":{"type":"string","format":"uri"},"next":{"type":["string","null"],"format":"uri"},"manifest":{"type":"string","format":"uri"},"openapi":{"type":"string","format":"uri"}}}}}}}}