{"openapi":"3.1.0","info":{"title":"KYCLESS Reviews API","version":"1.0.0","description":"Public, original KYCLESS reviews and replies. No credentials required. Initial archive and incremental current-state synchronization share one cursor endpoint. Changes are reflected within 5 seconds plus your polling interval. Imported threads are excluded. See the integration guide for deletion handling and attribution."},"servers":[{"url":"https://kycless.cc"}],"security":[],"externalDocs":{"description":"Integration guide and downloadable Python client","url":"https://kycless.cc/developers/reviews"},"paths":{"/api/v1/reviews":{"get":{"operationId":"listReviewChanges","summary":"Fetch archive or changes since a cursor","parameters":[{"name":"cursor","in":"query","schema":{"type":"string","pattern":"^[0-9]+$","default":"0"},"description":"Opaque decimal revision from pagination.next_cursor. Never increment it yourself; keep a separate cursor per filter. Start at 0 for initial sync."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"type","in":"query","schema":{"type":"string","enum":["all","review","reply"],"default":"all"},"description":"review includes unrated legacy top-level reviews; replies have type=reply."},{"name":"company_id","in":"query","schema":{"type":"integer","minimum":1,"maximum":2147483647},"description":"Stable service ID. Mutually exclusive with service."},{"name":"service","in":"query","schema":{"type":"string"},"description":"Service slug, e.g. mixtum. Prefer company_id for long-lived integrations. Mutually exclusive with company_id."}],"responses":{"200":{"description":"Current-state changes in ascending export revision order.","headers":{"ETag":{"description":"Validator; use If-None-Match to receive 304 when unchanged.","schema":{"type":"string"}},"Access-Control-Allow-Origin":{"schema":{"const":"*"}},"Retry-After":{"description":"On 429 or 503, wait at least this many seconds.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"304":{"description":"Unchanged representation.","headers":{"ETag":{"description":"Validator; use If-None-Match to receive 304 when unchanged.","schema":{"type":"string"}},"Access-Control-Allow-Origin":{"schema":{"const":"*"}},"Retry-After":{"description":"On 429 or 503, wait at least this many seconds.","schema":{"type":"string"}}}},"400":{"description":"Invalid, unknown or duplicate query parameter.","headers":{"ETag":{"description":"Validator; use If-None-Match to receive 304 when unchanged.","schema":{"type":"string"}},"Access-Control-Allow-Origin":{"schema":{"const":"*"}},"Retry-After":{"description":"On 429 or 503, wait at least this many seconds.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown publicly exported review or service.","headers":{"ETag":{"description":"Validator; use If-None-Match to receive 304 when unchanged.","schema":{"type":"string"}},"Access-Control-Allow-Origin":{"schema":{"const":"*"}},"Retry-After":{"description":"On 429 or 503, wait at least this many seconds.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Cursor ahead of server after a restore: rebuild and reconcile from 0.","headers":{"ETag":{"description":"Validator; use If-None-Match to receive 304 when unchanged.","schema":{"type":"string"}},"Access-Control-Allow-Origin":{"schema":{"const":"*"}},"Retry-After":{"description":"On 429 or 503, wait at least this many seconds.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Shared API/feed limit exceeded; obey Retry-After.","headers":{"ETag":{"description":"Validator; use If-None-Match to receive 304 when unchanged.","schema":{"type":"string"}},"Access-Control-Allow-Origin":{"schema":{"const":"*"}},"Retry-After":{"description":"On 429 or 503, wait at least this many seconds.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; obey Retry-After.","headers":{"ETag":{"description":"Validator; use If-None-Match to receive 304 when unchanged.","schema":{"type":"string"}},"Access-Control-Allow-Origin":{"schema":{"const":"*"}},"Retry-After":{"description":"On 429 or 503, wait at least this many seconds.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/reviews/{id}":{"get":{"operationId":"getReview","summary":"Read one review or reply","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9]+$","maxLength":10}}],"responses":{"200":{"description":"Public review or reply.","headers":{"ETag":{"description":"Validator; use If-None-Match to receive 304 when unchanged.","schema":{"type":"string"}},"Access-Control-Allow-Origin":{"schema":{"const":"*"}},"Retry-After":{"description":"On 429 or 503, wait at least this many seconds.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Detail"}}}},"304":{"description":"Unchanged representation.","headers":{"ETag":{"description":"Validator; use If-None-Match to receive 304 when unchanged.","schema":{"type":"string"}},"Access-Control-Allow-Origin":{"schema":{"const":"*"}},"Retry-After":{"description":"On 429 or 503, wait at least this many seconds.","schema":{"type":"string"}}}},"400":{"description":"Invalid, unknown or duplicate query parameter.","headers":{"ETag":{"description":"Validator; use If-None-Match to receive 304 when unchanged.","schema":{"type":"string"}},"Access-Control-Allow-Origin":{"schema":{"const":"*"}},"Retry-After":{"description":"On 429 or 503, wait at least this many seconds.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown publicly exported review or service.","headers":{"ETag":{"description":"Validator; use If-None-Match to receive 304 when unchanged.","schema":{"type":"string"}},"Access-Control-Allow-Origin":{"schema":{"const":"*"}},"Retry-After":{"description":"On 429 or 503, wait at least this many seconds.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Known formerly exported record; remove your local copy.","headers":{"ETag":{"description":"Validator; use If-None-Match to receive 304 when unchanged.","schema":{"type":"string"}},"Access-Control-Allow-Origin":{"schema":{"const":"*"}},"Retry-After":{"description":"On 429 or 503, wait at least this many seconds.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Detail"}}}},"429":{"description":"Shared API/feed limit exceeded; obey Retry-After.","headers":{"ETag":{"description":"Validator; use If-None-Match to receive 304 when unchanged.","schema":{"type":"string"}},"Access-Control-Allow-Origin":{"schema":{"const":"*"}},"Retry-After":{"description":"On 429 or 503, wait at least this many seconds.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; obey Retry-After.","headers":{"ETag":{"description":"Validator; use If-None-Match to receive 304 when unchanged.","schema":{"type":"string"}},"Access-Control-Allow-Origin":{"schema":{"const":"*"}},"Retry-After":{"description":"On 429 or 503, wait at least this many seconds.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/feeds/reviews.xml":{"get":{"operationId":"getReviewsRss","summary":"RSS 2.0 feed of the latest visible publications, not a complete sync feed","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"type","in":"query","schema":{"type":"string","enum":["all","review","reply"],"default":"review"},"description":"review includes unrated legacy top-level reviews; replies have type=reply."},{"name":"company_id","in":"query","schema":{"type":"integer","minimum":1,"maximum":2147483647},"description":"Stable service ID. Mutually exclusive with service."},{"name":"service","in":"query","schema":{"type":"string"},"description":"Service slug, e.g. mixtum. Prefer company_id for long-lived integrations. Mutually exclusive with company_id."}],"responses":{"200":{"description":"RSS 2.0 with content:encoded, dc:creator and KYCLESS metadata.","headers":{"ETag":{"description":"Validator; use If-None-Match to receive 304 when unchanged.","schema":{"type":"string"}},"Access-Control-Allow-Origin":{"schema":{"const":"*"}},"Retry-After":{"description":"On 429 or 503, wait at least this many seconds.","schema":{"type":"string"}}},"content":{"application/rss+xml":{"schema":{"type":"string"}}}},"304":{"description":"Unchanged feed.","headers":{"ETag":{"description":"Validator; use If-None-Match to receive 304 when unchanged.","schema":{"type":"string"}},"Access-Control-Allow-Origin":{"schema":{"const":"*"}},"Retry-After":{"description":"On 429 or 503, wait at least this many seconds.","schema":{"type":"string"}}}},"400":{"description":"Invalid, unknown or duplicate query parameter.","headers":{"ETag":{"description":"Validator; use If-None-Match to receive 304 when unchanged.","schema":{"type":"string"}},"Access-Control-Allow-Origin":{"schema":{"const":"*"}},"Retry-After":{"description":"On 429 or 503, wait at least this many seconds.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown publicly exported review or service.","headers":{"ETag":{"description":"Validator; use If-None-Match to receive 304 when unchanged.","schema":{"type":"string"}},"Access-Control-Allow-Origin":{"schema":{"const":"*"}},"Retry-After":{"description":"On 429 or 503, wait at least this many seconds.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Shared API/feed limit exceeded; obey Retry-After.","headers":{"ETag":{"description":"Validator; use If-None-Match to receive 304 when unchanged.","schema":{"type":"string"}},"Access-Control-Allow-Origin":{"schema":{"const":"*"}},"Retry-After":{"description":"On 429 or 503, wait at least this many seconds.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; obey Retry-After.","headers":{"ETag":{"description":"Validator; use If-None-Match to receive 304 when unchanged.","schema":{"type":"string"}},"Access-Control-Allow-Origin":{"schema":{"const":"*"}},"Retry-After":{"description":"On 429 or 503, wait at least this many seconds.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Review":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9]+$"},"global_id":{"type":"string"},"origin":{"const":"kycless"},"type":{"type":"string","enum":["review","reply"]},"revision":{"type":"string","pattern":"^[0-9]+$"},"exported_at":{"type":"string","format":"date-time"},"status":{"const":"published"},"url":{"type":"string","format":"uri"},"parent_id":{"anyOf":[{"type":"string","pattern":"^[0-9]+$"},{"type":"null"}]},"root_review_id":{"type":"string","pattern":"^[0-9]+$"},"title":{"type":["string","null"],"description":"Currently null: separate review headings are not supported."},"display_title":{"type":"string"},"title_is_generated":{"type":"boolean"},"body":{"type":"object","properties":{"source":{"type":"string"},"source_format":{"const":"kycless-inline-v1"},"text":{"type":"string"},"html":{"type":"string"}},"required":["source","source_format","text","html"],"additionalProperties":true},"rating":{"anyOf":[{"type":"object","properties":{"value":{"type":"integer","minimum":1,"maximum":5},"min":{"const":1},"max":{"const":5}},"required":["value","min","max"],"additionalProperties":true},{"type":"null"}]},"tags":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"},"tone":{"type":"string","enum":["good","bad"]}},"required":["code","label","tone"],"additionalProperties":true}},"order_proof_masked":{"type":["string","null"]},"attachments":{"type":"array","description":"Currently empty; reserved for public attachments.","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"mime_type":{"type":"string"},"name":{"type":"string"}},"required":["url"],"additionalProperties":true}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"author":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9]+$"},"nickname":{"type":"string"},"display_name":{"type":"string"},"profile_url":{"type":"string","format":"uri"},"avatar_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"display_avatar_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]}},"required":["id","nickname","display_name","profile_url","avatar_url","display_avatar_url"],"additionalProperties":true},"is_official":{"type":"boolean"},"company":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9]+$"},"slug":{"type":"string"},"name":{"type":"string"},"url":{"type":"string","format":"uri"},"logo_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"website_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"websites":{"type":"array","items":{"type":"object","properties":{"network":{"type":"string"},"url":{"type":"string","format":"uri"}},"required":["network","url"],"additionalProperties":true}}},"required":["id","slug","name","url","logo_url","website_url","websites"],"additionalProperties":true},"votes":{"type":"object","properties":{"up":{"type":"integer","minimum":0},"down":{"type":"integer","minimum":0}},"required":["up","down"],"additionalProperties":true}},"required":["id","global_id","origin","type","revision","exported_at","status","url","parent_id","root_review_id","title","display_title","title_is_generated","body","rating","tags","order_proof_masked","attachments","created_at","updated_at","author","is_official","company","votes"],"additionalProperties":true},"Tombstone":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9]+$"},"global_id":{"type":"string"},"origin":{"const":"kycless"},"type":{"type":"string","enum":["review","reply"]},"revision":{"type":"string","pattern":"^[0-9]+$"},"exported_at":{"type":"string","format":"date-time"},"status":{"const":"deleted"},"deleted_at":{"type":"string","format":"date-time"}},"required":["id","global_id","origin","type","revision","exported_at","status","deleted_at"],"additionalProperties":false},"Record":{"oneOf":[{"$ref":"#/components/schemas/Review"},{"$ref":"#/components/schemas/Tombstone"}]},"Collection":{"type":"object","properties":{"version":{"const":"1"},"source":{"type":"object","properties":{"name":{"const":"KYCLESS"},"url":{"type":"string","format":"uri"},"origin":{"const":"kycless"}},"required":["name","url","origin"],"additionalProperties":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Record"}},"pagination":{"type":"object","properties":{"has_more":{"type":"boolean"},"next_cursor":{"type":"string","pattern":"^[0-9]+$"},"next_url":{"type":"string","format":"uri"}},"required":["has_more","next_cursor","next_url"],"additionalProperties":true},"sync":{"type":"object","properties":{"watermark":{"type":"string","pattern":"^[0-9]+$"},"refresh_interval_seconds":{"const":5},"mode":{"const":"current_state"}},"required":["watermark","refresh_interval_seconds","mode"],"additionalProperties":true}},"required":["version","source","data","pagination","sync"],"additionalProperties":true},"Detail":{"type":"object","properties":{"version":{"const":"1"},"data":{"$ref":"#/components/schemas/Record"}},"required":["version","data"],"additionalProperties":true},"Error":{"type":"object","properties":{"version":{"const":"1"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":true},"documentation_url":{"type":"string","format":"uri"}},"required":["version","error","documentation_url"],"additionalProperties":true}}}}