{ "openapi": "3.1.0", "info": { "title": "Hotfix Content API", "version": "1.0.0", "summary": "Read-only public JSON API over the Hotfix podcast catalog.", "description": "Hotfix is a Hebrew-language engineering podcast by Imagen AI. This API exposes its catalog - episodes, internal meetup talks, and speaker profiles - as static JSON.\n\n## Authentication\n\n**None.** Every operation is an unauthenticated `GET`. There is no API key, no signup, no OAuth client, and no `Authorization` header. `security: []` is declared on every operation to state this explicitly. Full rationale: https://hotfix.co.il/auth.md\n\n## Versioning and deprecation\n\nThe major version is in the path (`/api/v1/`). Breaking changes ship under a new path (`/api/v2/`). When a version is retired it is announced on the developer portal and served for **at least 6 months** alongside its replacement, carrying `Deprecation` and `Sunset` response headers (RFC 9745 / RFC 8594) plus a `Link: rel=\"successor-version\"` header pointing at the new path. Additive, non-breaking changes - new fields, new endpoints - ship in place without a version bump, so clients must ignore unknown fields.\n\n## Rate limits\n\nResponses carry `RateLimit-Policy`. Requests are limited at the origin; the CDN absorbs the rest. On `429`, honour `Retry-After`.\n\n## Errors\n\nAll non-2xx responses are `application/problem+json` (RFC 9457), never HTML.\n\n## Write operations\n\nThere are none. The API is read-only by design, so idempotency keys, batch mutations, and async job polling do not apply - a retried `GET` is inherently safe.\n\n## Caching\n\nStatic JSON behind a CDN. `ETag` and `Last-Modified` are served; conditional requests are cheap. Use `lastmod` in https://hotfix.co.il/sitemap-index.xml to decide what to re-read.", "termsOfService": "https://hotfix.co.il/terms/", "contact": { "name": "Imagen AI", "email": "support@imagen-ai.com", "url": "https://hotfix.co.il/developers/" }, "license": { "name": "Content: all rights reserved. Metadata may be reused with attribution to https://hotfix.co.il/", "url": "https://hotfix.co.il/terms/" }, "x-deprecation-policy": { "policyUrl": "https://hotfix.co.il/developers/#versioning", "versioning": "url-path", "currentVersion": "v1", "deprecatedVersions": [], "minimumNoticePeriodMonths": 6, "signals": [ "Deprecation response header (RFC 9745)", "Sunset response header (RFC 8594)", "Link rel=\"successor-version\" response header (RFC 8288)", "Announcement on https://hotfix.co.il/developers/" ], "breakingChangePolicy": "Breaking changes ship under a new URL path (/api/v2/). Additive changes ship in place; clients must ignore unknown fields." }, "x-sandbox": { "available": true, "baseUrl": "https://hotfix.co.il/api/v1/sandbox", "credentialsRequired": false, "notes": "Read-only alias of the live endpoints. Identical payloads, no side effects, no signup." } }, "servers": [ { "url": "https://hotfix.co.il", "description": "Production." }, { "url": "https://hotfix.co.il/api/v1/sandbox", "description": "Sandbox / test path. Serves the same read-only documents as /api/v1 under an explicitly-labelled sandbox prefix. The API has no write operations, so there is no production data a test call can affect and no separate test dataset to seed. Example: GET https://hotfix.co.il/api/v1/sandbox/episodes.json" } ], "externalDocs": { "description": "Developer portal", "url": "https://hotfix.co.il/developers/" }, "security": [], "tags": [ { "name": "service", "description": "Service metadata and endpoint discovery." }, { "name": "episodes", "description": "Podcast episodes." }, { "name": "meetups", "description": "Internal meetup talks." }, { "name": "voices", "description": "Speaker profiles." } ], "paths": { "/api/v1/index.json": { "get": { "operationId": "getServiceIndex", "summary": "Service index", "description": "Return API metadata and the full endpoint map. Start here to discover the surface without reading this specification.", "tags": ["service"], "security": [], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "ETag": { "$ref": "#/components/headers/ETag" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/SuccessorVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceIndexResponse" } } } }, "404": { "description": "Not Found. RFC 9457 problem detail, never an HTML error page.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hotfix.co.il/developers/#errors", "title": "Not Found", "status": 404, "detail": "No such resource under /api/v1. Re-read the matching list endpoint; slugs change only when content is renamed.", "instance": "/api/v1/episodes/no-such-episode.json" } } } }, "405": { "description": "Method Not Allowed. RFC 9457 problem detail, never an HTML error page.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hotfix.co.il/developers/#errors", "title": "Method Not Allowed", "status": 405, "detail": "The Hotfix Content API is read-only. Retry the request as GET or HEAD.", "instance": "/api/v1/episodes/no-such-episode.json" } } } }, "429": { "description": "Too Many Requests. RFC 9457 problem detail, never an HTML error page.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hotfix.co.il/developers/#errors", "title": "Too Many Requests", "status": 429, "detail": "Origin rate limit exceeded. Honour the Retry-After response header.", "instance": "/api/v1/episodes/no-such-episode.json" } } } }, "500": { "description": "Internal Server Error. RFC 9457 problem detail, never an HTML error page.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hotfix.co.il/developers/#errors", "title": "Internal Server Error", "status": 500, "detail": "Origin or CDN fault. The payload is static, so retrying with backoff is safe.", "instance": "/api/v1/episodes/no-such-episode.json" } } } } }, "parameters": [] } }, "/api/v1/episodes.json": { "get": { "operationId": "listEpisodes", "summary": "List episodes", "description": "Return every published podcast episode, newest first, with Hebrew title and show notes, tags, guest pointers, audio and YouTube links, takeaways, and FAQ pairs.", "tags": ["episodes"], "security": [], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "ETag": { "$ref": "#/components/headers/ETag" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/SuccessorVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EpisodeListResponse" } } } }, "404": { "description": "Not Found. RFC 9457 problem detail, never an HTML error page.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hotfix.co.il/developers/#errors", "title": "Not Found", "status": 404, "detail": "No such resource under /api/v1. Re-read the matching list endpoint; slugs change only when content is renamed.", "instance": "/api/v1/episodes/no-such-episode.json" } } } }, "405": { "description": "Method Not Allowed. RFC 9457 problem detail, never an HTML error page.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hotfix.co.il/developers/#errors", "title": "Method Not Allowed", "status": 405, "detail": "The Hotfix Content API is read-only. Retry the request as GET or HEAD.", "instance": "/api/v1/episodes/no-such-episode.json" } } } }, "429": { "description": "Too Many Requests. RFC 9457 problem detail, never an HTML error page.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hotfix.co.il/developers/#errors", "title": "Too Many Requests", "status": 429, "detail": "Origin rate limit exceeded. Honour the Retry-After response header.", "instance": "/api/v1/episodes/no-such-episode.json" } } } }, "500": { "description": "Internal Server Error. RFC 9457 problem detail, never an HTML error page.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hotfix.co.il/developers/#errors", "title": "Internal Server Error", "status": 500, "detail": "Origin or CDN fault. The payload is static, so retrying with backoff is safe.", "instance": "/api/v1/episodes/no-such-episode.json" } } } } }, "parameters": [] } }, "/api/v1/episodes/{slug}.json": { "get": { "operationId": "getEpisode", "summary": "Get an episode", "description": "Return a single podcast episode by slug. Resolve each entry in `guests` against `getVoice` for the speaker's role and biography.", "tags": ["episodes"], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "URL slug of the resource, as returned in the `slug` field of the matching list endpoint.", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$", "maxLength": 128 }, "example": "ep09-deleted-production-survived" } ], "security": [], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "ETag": { "$ref": "#/components/headers/ETag" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/SuccessorVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EpisodeResponse" } } } }, "404": { "description": "Not Found. RFC 9457 problem detail, never an HTML error page.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hotfix.co.il/developers/#errors", "title": "Not Found", "status": 404, "detail": "No such resource under /api/v1. Re-read the matching list endpoint; slugs change only when content is renamed.", "instance": "/api/v1/episodes/no-such-episode.json" } } } }, "405": { "description": "Method Not Allowed. RFC 9457 problem detail, never an HTML error page.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hotfix.co.il/developers/#errors", "title": "Method Not Allowed", "status": 405, "detail": "The Hotfix Content API is read-only. Retry the request as GET or HEAD.", "instance": "/api/v1/episodes/no-such-episode.json" } } } }, "429": { "description": "Too Many Requests. RFC 9457 problem detail, never an HTML error page.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hotfix.co.il/developers/#errors", "title": "Too Many Requests", "status": 429, "detail": "Origin rate limit exceeded. Honour the Retry-After response header.", "instance": "/api/v1/episodes/no-such-episode.json" } } } }, "500": { "description": "Internal Server Error. RFC 9457 problem detail, never an HTML error page.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hotfix.co.il/developers/#errors", "title": "Internal Server Error", "status": 500, "detail": "Origin or CDN fault. The payload is static, so retrying with backoff is safe.", "instance": "/api/v1/episodes/no-such-episode.json" } } } } } } }, "/api/v1/meetups.json": { "get": { "operationId": "listMeetups", "summary": "List meetup talks", "description": "Return every published internal meetup talk, newest first, with Hebrew title and abstract, tags, speaker pointers, and the YouTube recording.", "tags": ["meetups"], "security": [], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "ETag": { "$ref": "#/components/headers/ETag" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/SuccessorVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeetupListResponse" } } } }, "404": { "description": "Not Found. RFC 9457 problem detail, never an HTML error page.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hotfix.co.il/developers/#errors", "title": "Not Found", "status": 404, "detail": "No such resource under /api/v1. Re-read the matching list endpoint; slugs change only when content is renamed.", "instance": "/api/v1/episodes/no-such-episode.json" } } } }, "405": { "description": "Method Not Allowed. RFC 9457 problem detail, never an HTML error page.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hotfix.co.il/developers/#errors", "title": "Method Not Allowed", "status": 405, "detail": "The Hotfix Content API is read-only. Retry the request as GET or HEAD.", "instance": "/api/v1/episodes/no-such-episode.json" } } } }, "429": { "description": "Too Many Requests. RFC 9457 problem detail, never an HTML error page.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hotfix.co.il/developers/#errors", "title": "Too Many Requests", "status": 429, "detail": "Origin rate limit exceeded. Honour the Retry-After response header.", "instance": "/api/v1/episodes/no-such-episode.json" } } } }, "500": { "description": "Internal Server Error. RFC 9457 problem detail, never an HTML error page.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hotfix.co.il/developers/#errors", "title": "Internal Server Error", "status": 500, "detail": "Origin or CDN fault. The payload is static, so retrying with backoff is safe.", "instance": "/api/v1/episodes/no-such-episode.json" } } } } }, "parameters": [] } }, "/api/v1/meetups/{slug}.json": { "get": { "operationId": "getMeetup", "summary": "Get a meetup talk", "description": "Return a single meetup talk by slug, including speakers and the YouTube recording id.", "tags": ["meetups"], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "URL slug of the resource, as returned in the `slug` field of the matching list endpoint.", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$", "maxLength": 128 }, "example": "ep09-deleted-production-survived" } ], "security": [], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "ETag": { "$ref": "#/components/headers/ETag" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/SuccessorVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeetupResponse" } } } }, "404": { "description": "Not Found. RFC 9457 problem detail, never an HTML error page.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hotfix.co.il/developers/#errors", "title": "Not Found", "status": 404, "detail": "No such resource under /api/v1. Re-read the matching list endpoint; slugs change only when content is renamed.", "instance": "/api/v1/episodes/no-such-episode.json" } } } }, "405": { "description": "Method Not Allowed. RFC 9457 problem detail, never an HTML error page.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hotfix.co.il/developers/#errors", "title": "Method Not Allowed", "status": 405, "detail": "The Hotfix Content API is read-only. Retry the request as GET or HEAD.", "instance": "/api/v1/episodes/no-such-episode.json" } } } }, "429": { "description": "Too Many Requests. RFC 9457 problem detail, never an HTML error page.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hotfix.co.il/developers/#errors", "title": "Too Many Requests", "status": 429, "detail": "Origin rate limit exceeded. Honour the Retry-After response header.", "instance": "/api/v1/episodes/no-such-episode.json" } } } }, "500": { "description": "Internal Server Error. RFC 9457 problem detail, never an HTML error page.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hotfix.co.il/developers/#errors", "title": "Internal Server Error", "status": 500, "detail": "Origin or CDN fault. The payload is static, so retrying with backoff is safe.", "instance": "/api/v1/episodes/no-such-episode.json" } } } } } } }, "/api/v1/voices.json": { "get": { "operationId": "listVoices", "summary": "List speakers", "description": "Return every speaker profile - podcast guests and meetup speakers - sorted by Hebrew name, with role, Hebrew biography, tech stack, and LinkedIn URL.", "tags": ["voices"], "security": [], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "ETag": { "$ref": "#/components/headers/ETag" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/SuccessorVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceListResponse" } } } }, "404": { "description": "Not Found. RFC 9457 problem detail, never an HTML error page.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hotfix.co.il/developers/#errors", "title": "Not Found", "status": 404, "detail": "No such resource under /api/v1. Re-read the matching list endpoint; slugs change only when content is renamed.", "instance": "/api/v1/episodes/no-such-episode.json" } } } }, "405": { "description": "Method Not Allowed. RFC 9457 problem detail, never an HTML error page.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hotfix.co.il/developers/#errors", "title": "Method Not Allowed", "status": 405, "detail": "The Hotfix Content API is read-only. Retry the request as GET or HEAD.", "instance": "/api/v1/episodes/no-such-episode.json" } } } }, "429": { "description": "Too Many Requests. RFC 9457 problem detail, never an HTML error page.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hotfix.co.il/developers/#errors", "title": "Too Many Requests", "status": 429, "detail": "Origin rate limit exceeded. Honour the Retry-After response header.", "instance": "/api/v1/episodes/no-such-episode.json" } } } }, "500": { "description": "Internal Server Error. RFC 9457 problem detail, never an HTML error page.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hotfix.co.il/developers/#errors", "title": "Internal Server Error", "status": 500, "detail": "Origin or CDN fault. The payload is static, so retrying with backoff is safe.", "instance": "/api/v1/episodes/no-such-episode.json" } } } } }, "parameters": [] } }, "/api/v1/voices/{slug}.json": { "get": { "operationId": "getVoice", "summary": "Get a speaker", "description": "Return a single speaker profile by slug, with role, Hebrew biography, tech stack, and LinkedIn URL.", "tags": ["voices"], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "URL slug of the resource, as returned in the `slug` field of the matching list endpoint.", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$", "maxLength": 128 }, "example": "ep09-deleted-production-survived" } ], "security": [], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "ETag": { "$ref": "#/components/headers/ETag" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/SuccessorVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceResponse" } } } }, "404": { "description": "Not Found. RFC 9457 problem detail, never an HTML error page.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hotfix.co.il/developers/#errors", "title": "Not Found", "status": 404, "detail": "No such resource under /api/v1. Re-read the matching list endpoint; slugs change only when content is renamed.", "instance": "/api/v1/episodes/no-such-episode.json" } } } }, "405": { "description": "Method Not Allowed. RFC 9457 problem detail, never an HTML error page.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hotfix.co.il/developers/#errors", "title": "Method Not Allowed", "status": 405, "detail": "The Hotfix Content API is read-only. Retry the request as GET or HEAD.", "instance": "/api/v1/episodes/no-such-episode.json" } } } }, "429": { "description": "Too Many Requests. RFC 9457 problem detail, never an HTML error page.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hotfix.co.il/developers/#errors", "title": "Too Many Requests", "status": 429, "detail": "Origin rate limit exceeded. Honour the Retry-After response header.", "instance": "/api/v1/episodes/no-such-episode.json" } } } }, "500": { "description": "Internal Server Error. RFC 9457 problem detail, never an HTML error page.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hotfix.co.il/developers/#errors", "title": "Internal Server Error", "status": 500, "detail": "Origin or CDN fault. The payload is static, so retrying with backoff is safe.", "instance": "/api/v1/episodes/no-such-episode.json" } } } } } } }, "/api/v1/all.json": { "get": { "operationId": "getEverything", "summary": "Bulk read: the entire catalog", "description": "Return every episode, meetup talk, and speaker profile in a single response. Use instead of looping the three list endpoints when you need the whole catalog; roughly 60KB today.", "tags": ["service"], "parameters": [], "security": [], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "ETag": { "$ref": "#/components/headers/ETag" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/SuccessorVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EverythingResponse" } } } }, "404": { "description": "Not Found. RFC 9457 problem detail, never an HTML error page.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hotfix.co.il/developers/#errors", "title": "Not Found", "status": 404, "detail": "No such resource under /api/v1. Re-read the matching list endpoint; slugs change only when content is renamed.", "instance": "/api/v1/episodes/no-such-episode.json" } } } }, "405": { "description": "Method Not Allowed. RFC 9457 problem detail, never an HTML error page.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hotfix.co.il/developers/#errors", "title": "Method Not Allowed", "status": 405, "detail": "The Hotfix Content API is read-only. Retry the request as GET or HEAD.", "instance": "/api/v1/episodes/no-such-episode.json" } } } }, "429": { "description": "Too Many Requests. RFC 9457 problem detail, never an HTML error page.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hotfix.co.il/developers/#errors", "title": "Too Many Requests", "status": 429, "detail": "Origin rate limit exceeded. Honour the Retry-After response header.", "instance": "/api/v1/episodes/no-such-episode.json" } } } }, "500": { "description": "Internal Server Error. RFC 9457 problem detail, never an HTML error page.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hotfix.co.il/developers/#errors", "title": "Internal Server Error", "status": 500, "detail": "Origin or CDN fault. The payload is static, so retrying with backoff is safe.", "instance": "/api/v1/episodes/no-such-episode.json" } } } } } } } }, "components": { "securitySchemes": {}, "headers": { "RateLimitPolicy": { "description": "Advertised request quota for this endpoint (RFC 9331 style), e.g. `hotfix;q=600;w=60`.", "schema": { "type": "string" } }, "ETag": { "description": "Strong entity tag. Send it back as `If-None-Match` to get a `304`.", "schema": { "type": "string" } }, "RetryAfter": { "description": "Seconds to wait before retrying after a `429`.", "schema": { "type": "integer" } }, "Deprecation": { "description": "Present only once this API version is deprecated (RFC 9745). An HTTP-date marking when deprecation was announced. Absent while the version is current.", "required": false, "schema": { "type": "string" }, "example": "Wed, 01 Jul 2026 00:00:00 GMT" }, "Sunset": { "description": "Present only once this API version is deprecated (RFC 8594). An HTTP-date after which the version stops being served - never sooner than 6 months after the Deprecation date. Absent while the version is current.", "required": false, "schema": { "type": "string" }, "example": "Sat, 02 Jan 2027 00:00:00 GMT" }, "SuccessorVersion": { "description": "Present only once this API version is deprecated. An RFC 8288 Link header with rel=\"successor-version\" pointing at the replacement path, so a client can migrate without reading the changelog.", "required": false, "schema": { "type": "string" }, "example": "; rel=\"successor-version\"" } }, "schemas": { "Pagination": { "type": "object", "description": "Cursor pagination envelope. The catalog currently fits in a single page, so `next_cursor` is null and `has_more` is false; the shape is declared so a client can page without guessing if the catalog grows.", "required": [ "limit", "count", "total", "has_more", "next_cursor", "next" ], "properties": { "limit": { "type": "integer", "description": "Number of items requested for this page.", "example": 12 }, "count": { "type": "integer", "description": "Number of items actually returned in `data`.", "example": 12 }, "total": { "type": "integer", "description": "Total items in the collection across all pages.", "example": 12 }, "has_more": { "type": "boolean", "description": "True when a further page exists.", "example": false }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor to pass as `cursor` for the next page, or null at the end of the collection.", "example": null }, "next": { "type": ["string", "null"], "format": "uri", "description": "Absolute URL of the next page, or null at the end of the collection.", "example": null } } }, "Problem": { "type": "object", "description": "RFC 9457 problem detail. Every non-2xx response uses this shape; the API never returns an HTML error page.", "required": ["type", "title", "status"], "properties": { "type": { "type": "string", "format": "uri", "description": "Stable URI identifying the problem type. Dereference it for guidance.", "example": "https://hotfix.co.il/developers/#errors" }, "title": { "type": "string", "description": "Short, human-readable summary of the problem type.", "example": "Not Found" }, "status": { "type": "integer", "description": "HTTP status code, repeated for clients that only parse the body.", "example": 404 }, "detail": { "type": "string", "description": "Human-readable explanation specific to this occurrence, including how to recover.", "example": "No such resource under /api/v1. See /api/openapi.json for the endpoint list." }, "instance": { "type": "string", "description": "Path of the request that produced the problem.", "example": "/api/v1/episodes/no-such-episode.json" } } }, "PersonRef": { "type": "object", "description": "Pointer to a speaker profile. Resolve `api_url` for the full record.", "required": ["slug", "url", "api_url"], "properties": { "slug": { "type": "string", "description": "Speaker slug.", "example": "dan-linenberg" }, "url": { "type": "string", "format": "uri", "description": "Canonical human-readable profile page. Cite this URL, not the API URL." }, "api_url": { "type": "string", "format": "uri", "description": "API record for this speaker." } } }, "Episode": { "type": "object", "description": "A published Hotfix podcast episode. Title and description are Hebrew.", "required": [ "slug", "url", "api_url", "title", "description", "language", "published_date", "tags" ], "properties": { "slug": { "type": "string", "description": "URL slug, stable unless the episode is renamed.", "example": "ep09-deleted-production-survived" }, "url": { "type": "string", "format": "uri", "description": "Canonical episode page. Cite this URL." }, "api_url": { "type": "string", "format": "uri", "description": "This episode's API record." }, "episode_number": { "type": ["integer", "null"], "description": "Sequential episode number parsed from the slug, or null for unnumbered entries.", "example": 9 }, "title": { "type": "string", "description": "Episode title, in Hebrew." }, "description": { "type": "string", "description": "Show-notes summary, in Hebrew." }, "language": { "type": "string", "description": "BCP 47 language tag of the content.", "example": "he" }, "published_date": { "type": "string", "format": "date", "description": "Publication date, ISO 8601 (YYYY-MM-DD).", "example": "2026-06-01" }, "tags": { "type": "array", "description": "Topic tags in English, lowercase.", "items": { "type": "string" }, "example": ["production", "ai", "ownership"] }, "guests": { "type": "array", "description": "Speakers appearing in this episode.", "items": { "type": "object", "description": "Pointer to a speaker profile. Resolve `api_url` for the full record.", "required": ["slug", "url", "api_url"], "properties": { "slug": { "type": "string", "description": "Speaker slug.", "example": "dan-linenberg" }, "url": { "type": "string", "format": "uri", "description": "Canonical human-readable profile page. Cite this URL, not the API URL." }, "api_url": { "type": "string", "format": "uri", "description": "API record for this speaker." } } } }, "audio_url": { "type": ["string", "null"], "format": "uri", "description": "Direct audio enclosure URL, or null when audio is not yet published." }, "youtube_id": { "type": ["string", "null"], "description": "YouTube video id, or null." }, "youtube_url": { "type": ["string", "null"], "format": "uri", "description": "Full YouTube watch URL, or null." }, "apple_podcasts_url": { "type": ["string", "null"], "format": "uri", "description": "Apple Podcasts episode URL, or null." }, "image_url": { "type": ["string", "null"], "format": "uri", "description": "Square cover image (WebP, 800x800), or null." }, "takeaways": { "type": "array", "description": "Key takeaways in Hebrew, empty when none are recorded.", "items": { "type": "string" } }, "faq": { "type": "array", "description": "Question and answer pairs in Hebrew, empty when none are recorded.", "items": { "type": "object", "required": ["question", "answer"], "properties": { "question": { "type": "string" }, "answer": { "type": "string" } } } }, "feed_url": { "type": "string", "format": "uri", "description": "Canonical podcast RSS feed." } } }, "Meetup": { "type": "object", "description": "An internal Imagen AI meetup talk published on the site. Title and abstract are Hebrew.", "required": [ "slug", "url", "api_url", "title", "language", "published_date", "speakers", "youtube_id" ], "properties": { "slug": { "type": "string", "description": "URL slug.", "example": "generative-observability" }, "url": { "type": "string", "format": "uri", "description": "Canonical talk page. Cite this URL." }, "api_url": { "type": "string", "format": "uri", "description": "This talk's API record." }, "title": { "type": "string", "description": "Talk title, in Hebrew." }, "abstract": { "type": ["string", "null"], "description": "Talk abstract in Hebrew, or null." }, "language": { "type": "string", "description": "BCP 47 language tag.", "example": "he" }, "published_date": { "type": "string", "format": "date", "description": "Talk date, ISO 8601." }, "tags": { "type": "array", "description": "Topic tags in English.", "items": { "type": "string" } }, "audience": { "type": "array", "description": "Intended audience labels.", "items": { "type": "string" } }, "speakers": { "type": "array", "description": "Speakers who gave the talk.", "items": { "type": "object", "description": "Pointer to a speaker profile. Resolve `api_url` for the full record.", "required": ["slug", "url", "api_url"], "properties": { "slug": { "type": "string", "description": "Speaker slug.", "example": "dan-linenberg" }, "url": { "type": "string", "format": "uri", "description": "Canonical human-readable profile page. Cite this URL, not the API URL." }, "api_url": { "type": "string", "format": "uri", "description": "API record for this speaker." } } } }, "youtube_id": { "type": "string", "description": "YouTube video id of the recording." }, "youtube_url": { "type": "string", "format": "uri", "description": "Full YouTube watch URL." }, "image_url": { "type": ["string", "null"], "format": "uri", "description": "Wide thumbnail (WebP, 800x450), or null." } } }, "Voice": { "type": "object", "description": "A speaker profile: a podcast guest or meetup speaker. Bio is Hebrew.", "required": [ "slug", "url", "api_url", "name", "role", "bio", "language" ], "properties": { "slug": { "type": "string", "description": "URL slug.", "example": "ofek-azulay" }, "url": { "type": "string", "format": "uri", "description": "Canonical profile page. Cite this URL." }, "api_url": { "type": "string", "format": "uri", "description": "This speaker's API record." }, "name": { "type": "string", "description": "Full name, in Hebrew." }, "role": { "type": "string", "description": "Job title and company, in English." }, "bio": { "type": "string", "description": "Short biography, in Hebrew." }, "language": { "type": "string", "description": "BCP 47 language tag of the bio.", "example": "he" }, "tech_stack": { "type": "array", "description": "Technologies the speaker works with.", "items": { "type": "string" } }, "linkedin_url": { "type": ["string", "null"], "format": "uri", "description": "LinkedIn profile, or null." }, "image_url": { "type": ["string", "null"], "format": "uri", "description": "Headshot (WebP, 400x400), or null." } } }, "ServiceIndex": { "type": "object", "description": "API metadata and endpoint map.", "required": ["name", "version", "authentication", "endpoints"], "properties": { "name": { "type": "string", "description": "Human-readable API name." }, "description": { "type": "string", "description": "What the API covers." }, "version": { "type": "string", "description": "Major version served at this path.", "example": "v1" }, "language": { "type": "string", "description": "Primary content language.", "example": "he" }, "authentication": { "type": "string", "description": "Authentication scheme in force. Always the literal string `none`.", "example": "none" }, "auth_documentation": { "type": "string", "format": "uri", "description": "Prose walkthrough of the (absent) auth requirements." }, "documentation": { "type": "string", "format": "uri", "description": "Developer portal." }, "openapi": { "type": "string", "format": "uri", "description": "This specification." }, "terms_of_service": { "type": "string", "format": "uri", "description": "Terms of use." }, "contact": { "type": "string", "description": "Contact email for API questions and abuse reports." }, "feed_url": { "type": "string", "format": "uri", "description": "Canonical podcast RSS feed." }, "endpoints": { "type": "object", "description": "Map of logical endpoint name to URL template.", "additionalProperties": { "type": "string" } } } }, "ServiceIndexResponse": { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/ServiceIndex" } } }, "EpisodeListResponse": { "type": "object", "required": ["data", "pagination"], "properties": { "data": { "type": "array", "description": "The episodes in this page.", "items": { "$ref": "#/components/schemas/Episode" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "EpisodeResponse": { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/Episode" } } }, "MeetupListResponse": { "type": "object", "required": ["data", "pagination"], "properties": { "data": { "type": "array", "description": "The meetup talks in this page.", "items": { "$ref": "#/components/schemas/Meetup" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "MeetupResponse": { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/Meetup" } } }, "VoiceListResponse": { "type": "object", "required": ["data", "pagination"], "properties": { "data": { "type": "array", "description": "The speakers in this page.", "items": { "$ref": "#/components/schemas/Voice" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "VoiceResponse": { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/Voice" } } }, "EverythingResponse": { "type": "object", "description": "The whole catalog in one payload.", "required": ["data", "counts"], "properties": { "data": { "type": "object", "required": ["episodes", "meetups", "voices"], "properties": { "episodes": { "type": "array", "description": "Every published episode, newest first.", "items": { "$ref": "#/components/schemas/Episode" } }, "meetups": { "type": "array", "description": "Every published meetup talk, newest first.", "items": { "$ref": "#/components/schemas/Meetup" } }, "voices": { "type": "array", "description": "Every speaker profile, sorted by Hebrew name.", "items": { "$ref": "#/components/schemas/Voice" } } } }, "counts": { "type": "object", "description": "Item count per collection.", "required": ["episodes", "meetups", "voices"], "properties": { "episodes": { "type": "integer" }, "meetups": { "type": "integer" }, "voices": { "type": "integer" } } } } } }, "responses": { "NotFound": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hotfix.co.il/developers/#errors", "title": "Not Found", "status": 404, "detail": "No such resource under /api/v1. Re-read the matching list endpoint; slugs change only when content is renamed." } } } }, "MethodNotAllowed": { "description": "Method Not Allowed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hotfix.co.il/developers/#errors", "title": "Method Not Allowed", "status": 405, "detail": "This API is read-only. Retry the request as GET or HEAD." } } } }, "TooManyRequests": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hotfix.co.il/developers/#errors", "title": "Too Many Requests", "status": 429, "detail": "Origin rate limit exceeded. Honour the Retry-After response header." } } } }, "ServerError": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hotfix.co.il/developers/#errors", "title": "Internal Server Error", "status": 500, "detail": "Origin or CDN fault. The payload is static, so retrying with backoff is safe." } } } } } } }