{"openapi":"3.1.0","info":{"title":"Spearfishing Naples API","version":"1.0.0","description":"Public read-only API of spearfishingnaples.com: site info, main pages, spearfishing equipment recommended by Simone Ruggiero and blog guides. No authentication.\n\nRate limit: 60 requests per 60 seconds per IP, reported on every response with the IETF RateLimit-Policy and RateLimit headers.\n\nErrors: every 4xx/5xx response is application/problem+json (RFC 9457) with the Problem schema.\n\nVersioning: the major version is in the path (/api/v1). v1 is stable: only backward-compatible changes (new fields, new endpoints). Breaking changes ship as /api/v2. A retired endpoint first returns a Deprecation header (RFC 9745) and a Sunset header (RFC 8594) with the removal date, at least 6 months in advance, and is announced in the docs. Policy: https://spearfishingnaples.com/docs#versioning","contact":{"name":"Simone Ruggiero","email":"simone.ruggiero97@gmail.com","url":"https://spearfishingnaples.com/contact"},"x-api-lifecycle":{"status":"stable","versioning":"url-path","deprecationPolicy":"https://spearfishingnaples.com/docs#versioning","minimumDeprecationNoticeDays":180}},"externalDocs":{"description":"Developer docs","url":"https://spearfishingnaples.com/docs"},"servers":[{"url":"https://spearfishingnaples.com/api/v1","description":"v1 (stable)"}],"security":[],"tags":[{"name":"site","description":"Site information"},{"name":"content","description":"Equipment and guides"}],"paths":{"/":{"get":{"operationId":"getApiIndex","summary":"API index","description":"Version, status and list of the v1 endpoints.","tags":["site"],"responses":{"200":{"description":"API index","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"API-Version":{"$ref":"#/components/headers/API-Version"},"Deprecation":{"$ref":"#/components/headers/Deprecation"},"Sunset":{"$ref":"#/components/headers/Sunset"}},"content":{"application/json":{"schema":{"type":"object","required":["name","version","status","docs","openapi","endpoints"],"properties":{"name":{"type":"string"},"version":{"type":"string"},"status":{"type":"string","enum":["stable","deprecated"]},"docs":{"type":"string","format":"uri"},"openapi":{"type":"string","format":"uri"},"endpoints":{"type":"array","items":{"type":"string","format":"uri"}}}}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in Retry-After.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Unexpected server error.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/info":{"get":{"operationId":"getSiteInfo","summary":"Site info","description":"Who runs Spearfishing Naples, where it operates, services, contact and links.","tags":["site"],"responses":{"200":{"description":"Site info","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"API-Version":{"$ref":"#/components/headers/API-Version"},"Deprecation":{"$ref":"#/components/headers/Deprecation"},"Sunset":{"$ref":"#/components/headers/Sunset"}},"content":{"application/json":{"schema":{"type":"object","required":["name","description","url","founder","email","location","languages","services","social","links"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"url":{"type":"string","format":"uri"},"founder":{"type":"string"},"email":{"type":"string","format":"email"},"location":{"type":"object","required":["locality","region","country","area"],"properties":{"locality":{"type":"string"},"region":{"type":"string"},"country":{"type":"string"},"area":{"type":"string"}}},"languages":{"type":"array","items":{"type":"string"}},"services":{"type":"array","items":{"type":"string"}},"social":{"type":"array","items":{"type":"string","format":"uri"}},"links":{"type":"object","required":["docs","openapi","mcp","llms","sitemap","contact"],"properties":{"docs":{"type":"string","format":"uri"},"openapi":{"type":"string","format":"uri"},"mcp":{"type":"string","format":"uri"},"llms":{"type":"string","format":"uri"},"sitemap":{"type":"string","format":"uri"},"contact":{"type":"string","format":"uri"}}}}}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in Retry-After.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Unexpected server error.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/pages":{"get":{"operationId":"listPages","summary":"List main pages","description":"Main pages of the site with title, description and absolute URL.","tags":["site"],"responses":{"200":{"description":"Pages","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"API-Version":{"$ref":"#/components/headers/API-Version"},"Deprecation":{"$ref":"#/components/headers/Deprecation"},"Sunset":{"$ref":"#/components/headers/Sunset"}},"content":{"application/json":{"schema":{"type":"object","required":["count","pages"],"properties":{"count":{"type":"integer","description":"Number of items."},"pages":{"type":"array","items":{"type":"object","required":["title","description","url"],"properties":{"title":{"type":"string","description":"Page title."},"description":{"type":"string","description":"Short page description."},"url":{"type":"string","format":"uri","description":"Absolute page URL."}}}}}}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in Retry-After.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Unexpected server error.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/equipment":{"get":{"operationId":"listEquipment","summary":"List recommended equipment","description":"Spearfishing equipment recommended by Simone Ruggiero with details, advice and buy link.","tags":["content"],"parameters":[{"name":"lang","in":"query","required":false,"description":"Language of the returned text.","schema":{"type":"string","enum":["it","en"],"default":"it"}}],"responses":{"200":{"description":"Equipment list","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"API-Version":{"$ref":"#/components/headers/API-Version"},"Deprecation":{"$ref":"#/components/headers/Deprecation"},"Sunset":{"$ref":"#/components/headers/Sunset"}},"content":{"application/json":{"schema":{"type":"object","required":["count","lang","equipment"],"properties":{"count":{"type":"integer","description":"Number of items."},"lang":{"type":"string","enum":["it","en"]},"equipment":{"type":"array","items":{"type":"object","required":["slug","name","description","details","advice","image","url","buyUrl"],"properties":{"slug":{"type":"string","description":"Stable identifier."},"name":{"type":"string","description":"Product name."},"description":{"type":"string","description":"Short description."},"details":{"type":"string","description":"Technical details in Markdown."},"advice":{"type":"string","description":"Advice from Simone Ruggiero."},"image":{"type":"string","format":"uri","description":"Product image."},"url":{"type":"string","format":"uri","description":"Product page on spearfishingnaples.com."},"buyUrl":{"type":["string","null"],"format":"uri","description":"Shop link (may be an affiliate link), or null."}}}}}}}}},"400":{"description":"Invalid parameter.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in Retry-After.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Unexpected server error.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/equipment/{slug}":{"get":{"operationId":"getEquipment","summary":"Get one equipment item","description":"One recommended equipment item by slug.","tags":["content"],"parameters":[{"name":"slug","in":"path","required":true,"description":"Item slug from listEquipment.","schema":{"type":"string","pattern":"^[a-z0-9-]+$"}},{"name":"lang","in":"query","required":false,"description":"Language of the returned text.","schema":{"type":"string","enum":["it","en"],"default":"it"}}],"responses":{"200":{"description":"Equipment item","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"API-Version":{"$ref":"#/components/headers/API-Version"},"Deprecation":{"$ref":"#/components/headers/Deprecation"},"Sunset":{"$ref":"#/components/headers/Sunset"}},"content":{"application/json":{"schema":{"type":"object","required":["slug","name","description","details","advice","image","url","buyUrl"],"properties":{"slug":{"type":"string","description":"Stable identifier."},"name":{"type":"string","description":"Product name."},"description":{"type":"string","description":"Short description."},"details":{"type":"string","description":"Technical details in Markdown."},"advice":{"type":"string","description":"Advice from Simone Ruggiero."},"image":{"type":"string","format":"uri","description":"Product image."},"url":{"type":"string","format":"uri","description":"Product page on spearfishingnaples.com."},"buyUrl":{"type":["string","null"],"format":"uri","description":"Shop link (may be an affiliate link), or null."}}}}}},"400":{"description":"Invalid parameter.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Resource not found.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in Retry-After.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Unexpected server error.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/articles":{"get":{"operationId":"listArticles","summary":"List blog guides","description":"Spearfishing and freediving guides published on the blog.","tags":["content"],"parameters":[{"name":"lang","in":"query","required":false,"description":"Language of the returned text.","schema":{"type":"string","enum":["it","en"],"default":"it"}}],"responses":{"200":{"description":"Articles","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"API-Version":{"$ref":"#/components/headers/API-Version"},"Deprecation":{"$ref":"#/components/headers/Deprecation"},"Sunset":{"$ref":"#/components/headers/Sunset"}},"content":{"application/json":{"schema":{"type":"object","required":["count","lang","articles"],"properties":{"count":{"type":"integer","description":"Number of items."},"lang":{"type":"string","enum":["it","en"]},"articles":{"type":"array","items":{"type":"object","required":["slug","title","description","publishedAt","tags","url"],"properties":{"slug":{"type":"string","description":"Stable identifier."},"title":{"type":"string","description":"Article title."},"description":{"type":"string","description":"Article summary."},"publishedAt":{"type":"string","format":"date","description":"Publication date."},"tags":{"type":"array","items":{"type":"string"},"description":"Topics."},"url":{"type":"string","format":"uri","description":"Article URL."}}}}}}}}},"400":{"description":"Invalid parameter.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in Retry-After.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Unexpected server error.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}},"components":{"headers":{"RateLimit-Policy":{"description":"IETF RateLimit-Policy: quota (q) of 60 requests per window (w) of 60 seconds per IP.","schema":{"type":"string","examples":["\"default\";q=60;w=60"]}},"RateLimit":{"description":"IETF RateLimit: remaining requests (r) and seconds until the window resets (t).","schema":{"type":"string","examples":["\"default\";r=59;t=60"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"API-Version":{"description":"Version of the API that served the response.","schema":{"type":"string"}},"Deprecation":{"description":"RFC 9745. Present only on deprecated operations: date since the operation is deprecated.","schema":{"type":"string"}},"Sunset":{"description":"RFC 8594. Present only on deprecated operations: HTTP date after which the operation is removed.","schema":{"type":"string"}}},"schemas":{"Problem":{"type":"object","description":"RFC 9457 problem details. Used by every 4xx and 5xx response.","required":["type","title","status","detail","code","resolution"],"properties":{"type":{"type":"string","format":"uri","description":"Link to the error documentation."},"title":{"type":"string","description":"Short summary of the error."},"status":{"type":"integer","description":"HTTP status code."},"detail":{"type":"string","description":"Explanation of this occurrence."},"code":{"type":"string","description":"Machine-readable error code.","enum":["invalid_lang","equipment_not_found","not_found","rate_limited","internal_error"]},"resolution":{"type":"string","description":"How to fix the request."}}},"Page":{"type":"object","required":["title","description","url"],"properties":{"title":{"type":"string","description":"Page title."},"description":{"type":"string","description":"Short page description."},"url":{"type":"string","format":"uri","description":"Absolute page URL."}}},"Equipment":{"type":"object","required":["slug","name","description","details","advice","image","url","buyUrl"],"properties":{"slug":{"type":"string","description":"Stable identifier."},"name":{"type":"string","description":"Product name."},"description":{"type":"string","description":"Short description."},"details":{"type":"string","description":"Technical details in Markdown."},"advice":{"type":"string","description":"Advice from Simone Ruggiero."},"image":{"type":"string","format":"uri","description":"Product image."},"url":{"type":"string","format":"uri","description":"Product page on spearfishingnaples.com."},"buyUrl":{"type":["string","null"],"format":"uri","description":"Shop link (may be an affiliate link), or null."}}},"Article":{"type":"object","required":["slug","title","description","publishedAt","tags","url"],"properties":{"slug":{"type":"string","description":"Stable identifier."},"title":{"type":"string","description":"Article title."},"description":{"type":"string","description":"Article summary."},"publishedAt":{"type":"string","format":"date","description":"Publication date."},"tags":{"type":"array","items":{"type":"string"},"description":"Topics."},"url":{"type":"string","format":"uri","description":"Article URL."}}},"Info":{"type":"object","required":["name","description","url","founder","email","location","languages","services","social","links"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"url":{"type":"string","format":"uri"},"founder":{"type":"string"},"email":{"type":"string","format":"email"},"location":{"type":"object","required":["locality","region","country","area"],"properties":{"locality":{"type":"string"},"region":{"type":"string"},"country":{"type":"string"},"area":{"type":"string"}}},"languages":{"type":"array","items":{"type":"string"}},"services":{"type":"array","items":{"type":"string"}},"social":{"type":"array","items":{"type":"string","format":"uri"}},"links":{"type":"object","required":["docs","openapi","mcp","llms","sitemap","contact"],"properties":{"docs":{"type":"string","format":"uri"},"openapi":{"type":"string","format":"uri"},"mcp":{"type":"string","format":"uri"},"llms":{"type":"string","format":"uri"},"sitemap":{"type":"string","format":"uri"},"contact":{"type":"string","format":"uri"}}}}},"ApiIndex":{"type":"object","required":["name","version","status","docs","openapi","endpoints"],"properties":{"name":{"type":"string"},"version":{"type":"string"},"status":{"type":"string","enum":["stable","deprecated"]},"docs":{"type":"string","format":"uri"},"openapi":{"type":"string","format":"uri"},"endpoints":{"type":"array","items":{"type":"string","format":"uri"}}}}}}}