{ "openapi": "3.1.0", "info": { "title": "Brendan Irvine-Broque Personal API", "version": "1.0.0", "description": "Personal API providing access to curated recommendations for movies, places, music, videos, podcasts, tweets, code activity, photos, books, and reading links.\n\n## Standards Compliance\n\nThis API implements the following standards:\n\n| Standard | Purpose |\n|----------|---------|\n| RFC 8288 | Web Linking (Link headers, pagination) |\n| RFC 9652 | Link-Template Header Field |\n| RFC 8631 | Service Discovery |\n| RFC 9727 | API Catalog |\n| RFC 9457 | Problem Details (errors) |\n| RFC 9309 | robots.txt policy publication |\n| RFC 9116 | security.txt vulnerability disclosure policy |\n| RFC 9745 | Deprecation Header Field |\n| RFC 8594 | Sunset Header Field |\n| RFC 9110 | Conditional Requests |\n| RFC 9111 | HTTP Caching |\n| RFC 3339 | Date/Time Format |\n| RFC 7231 | Content Negotiation |\n\n## Content Negotiation\n\nAll endpoints support:\n- `application/json` (default)\n- `text/csv` (set Accept header)\n- `application/geo+json` (places and photos endpoints)\n\nList endpoints also expose an RFC 9652 `Link-Template` response header so clients can discover query parameter templates.\n\n## Conditional Requests\n\nUse `If-None-Match` or `If-Modified-Since` headers to receive 304 Not Modified responses.", "contact": { "name": "Brendan Irvine-Broque", "email": "brendanib@gmail.com", "url": "https://irvinebroque.com" }, "license": { "name": "MIT" } }, "servers": [ { "url": "https://irvinebroque.com", "description": "Production server" } ], "tags": [ { "name": "movies", "description": "Film recommendations" }, { "name": "places", "description": "Restaurant and location recommendations" }, { "name": "music", "description": "Albums, playlists, and DJ mixes" }, { "name": "videos", "description": "YouTube video recommendations" }, { "name": "podcasts", "description": "Podcast episode recommendations" }, { "name": "tweets", "description": "Curated tweet recommendations" }, { "name": "code", "description": "Public GitHub activity timeline" }, { "name": "photos", "description": "Personal photography" }, { "name": "books", "description": "Book recommendations" }, { "name": "reading", "description": "Saved links with metadata previews" }, { "name": "blog", "description": "blog list surface" }, { "name": "writing", "description": "writing list surface" }, { "name": "search", "description": "search list surface" }, { "name": "feed-items", "description": "feed-items list surface" }, { "name": "meta", "description": "API metadata and service discovery" } ], "paths": { "/api/movies.json": { "get": { "operationId": "getMovies", "summary": "List movie recommendations", "tags": [ "movies" ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of items to return (default: 50, max: 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor for fetching next page", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sort field and direction (e.g., \"year:desc\", \"addedAt:asc\")", "schema": { "type": "string", "pattern": "^[\\w.-]+:(asc|desc)(,[\\w.-]+:(asc|desc))*$" } }, { "name": "facets", "in": "query", "description": "Include facet metadata in response meta (set to 1)", "schema": { "oneOf": [ { "type": "integer", "enum": [ 1 ] }, { "type": "boolean" }, { "type": "string" } ] } }, { "name": "year", "in": "query", "description": "Filter by release year", "schema": { "type": "integer" } }, { "name": "genre", "in": "query", "description": "Filter by genre", "schema": { "type": "string" } }, { "name": "director", "in": "query", "description": "Filter by director", "schema": { "type": "string" } }, { "name": "actor", "in": "query", "description": "Filter by cast member", "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Case-insensitive title search", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List response for movies", "headers": { "X-Total-Count": { "description": "Total number of items", "schema": { "type": "integer" } }, "ETag": { "description": "Entity tag for conditional requests", "schema": { "type": "string" } }, "Last-Modified": { "description": "Last modification date", "schema": { "type": "string", "format": "date-time" } }, "Link": { "description": "RFC 8288 Web Linking header with pagination links", "schema": { "type": "string" } }, "Link-Template": { "description": "RFC 9652 Link-Template header with query parameter templates", "schema": { "type": "string" } }, "Cache-Control": { "description": "Caching directives", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745 lifecycle deprecation signal", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594 lifecycle sunset date", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Movie" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "required": [ "data", "meta", "links" ] } }, "text/csv": { "schema": { "type": "string" } } } }, "304": { "description": "Not Modified" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "406": { "description": "Not Acceptable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "head": { "operationId": "headMovies", "summary": "Get movies list metadata", "tags": [ "movies" ], "responses": { "200": { "description": "Headers only", "headers": { "X-Total-Count": { "description": "Total number of items", "schema": { "type": "integer" } }, "ETag": { "description": "Entity tag for conditional requests", "schema": { "type": "string" } }, "Last-Modified": { "description": "Last modification date", "schema": { "type": "string", "format": "date-time" } }, "Link": { "description": "RFC 8288 Web Linking header with pagination links", "schema": { "type": "string" } }, "Link-Template": { "description": "RFC 9652 Link-Template header with query parameter templates", "schema": { "type": "string" } }, "Cache-Control": { "description": "Caching directives", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745 lifecycle deprecation signal", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594 lifecycle sunset date", "schema": { "type": "string", "format": "date-time" } } } } } }, "options": { "operationId": "optionsMovies", "summary": "CORS preflight", "tags": [ "movies" ], "responses": { "204": { "description": "CORS preflight response" } } } }, "/api/places.json": { "get": { "operationId": "getPlaces", "summary": "List place recommendations", "tags": [ "places" ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of items to return (default: 50, max: 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor for fetching next page", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sort field and direction (e.g., \"year:desc\", \"addedAt:asc\")", "schema": { "type": "string", "pattern": "^[\\w.-]+:(asc|desc)(,[\\w.-]+:(asc|desc))*$" } }, { "name": "facets", "in": "query", "description": "Include facet metadata in response meta (set to 1)", "schema": { "oneOf": [ { "type": "integer", "enum": [ 1 ] }, { "type": "boolean" }, { "type": "string" } ] } }, { "name": "city", "in": "query", "description": "Filter by city", "schema": { "type": "string" } }, { "name": "country", "in": "query", "description": "Filter by country", "schema": { "type": "string" } }, { "name": "category", "in": "query", "description": "Filter by category", "schema": { "type": "string", "enum": [ "food", "drink", "nature", "shopping", "entertainment", "lodging", "other" ] } }, { "name": "neighborhood", "in": "query", "description": "Filter by neighborhood", "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Case-insensitive search across place name and location metadata", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List response for places", "headers": { "X-Total-Count": { "description": "Total number of items", "schema": { "type": "integer" } }, "ETag": { "description": "Entity tag for conditional requests", "schema": { "type": "string" } }, "Last-Modified": { "description": "Last modification date", "schema": { "type": "string", "format": "date-time" } }, "Link": { "description": "RFC 8288 Web Linking header with pagination links", "schema": { "type": "string" } }, "Link-Template": { "description": "RFC 9652 Link-Template header with query parameter templates", "schema": { "type": "string" } }, "Cache-Control": { "description": "Caching directives", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745 lifecycle deprecation signal", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594 lifecycle sunset date", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Place" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "required": [ "data", "meta", "links" ] } }, "text/csv": { "schema": { "type": "string" } }, "application/geo+json": { "schema": { "$ref": "#/components/schemas/PlaceGeoJsonResponse" } } } }, "304": { "description": "Not Modified" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "406": { "description": "Not Acceptable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "head": { "operationId": "headPlaces", "summary": "Get places list metadata", "tags": [ "places" ], "responses": { "200": { "description": "Headers only", "headers": { "X-Total-Count": { "description": "Total number of items", "schema": { "type": "integer" } }, "ETag": { "description": "Entity tag for conditional requests", "schema": { "type": "string" } }, "Last-Modified": { "description": "Last modification date", "schema": { "type": "string", "format": "date-time" } }, "Link": { "description": "RFC 8288 Web Linking header with pagination links", "schema": { "type": "string" } }, "Link-Template": { "description": "RFC 9652 Link-Template header with query parameter templates", "schema": { "type": "string" } }, "Cache-Control": { "description": "Caching directives", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745 lifecycle deprecation signal", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594 lifecycle sunset date", "schema": { "type": "string", "format": "date-time" } } } } } }, "options": { "operationId": "optionsPlaces", "summary": "CORS preflight", "tags": [ "places" ], "responses": { "204": { "description": "CORS preflight response" } } } }, "/api/music.json": { "get": { "operationId": "getMusic", "summary": "List music recommendations", "tags": [ "music" ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of items to return (default: 50, max: 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor for fetching next page", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sort field and direction (e.g., \"year:desc\", \"addedAt:asc\")", "schema": { "type": "string", "pattern": "^[\\w.-]+:(asc|desc)(,[\\w.-]+:(asc|desc))*$" } }, { "name": "facets", "in": "query", "description": "Include facet metadata in response meta (set to 1)", "schema": { "oneOf": [ { "type": "integer", "enum": [ 1 ] }, { "type": "boolean" }, { "type": "string" } ] } }, { "name": "type", "in": "query", "description": "Filter by music type", "schema": { "type": "string", "enum": [ "album", "playlist", "mix" ] } }, { "name": "q", "in": "query", "description": "Case-insensitive search across title, notes, and URL", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List response for music", "headers": { "X-Total-Count": { "description": "Total number of items", "schema": { "type": "integer" } }, "ETag": { "description": "Entity tag for conditional requests", "schema": { "type": "string" } }, "Last-Modified": { "description": "Last modification date", "schema": { "type": "string", "format": "date-time" } }, "Link": { "description": "RFC 8288 Web Linking header with pagination links", "schema": { "type": "string" } }, "Link-Template": { "description": "RFC 9652 Link-Template header with query parameter templates", "schema": { "type": "string" } }, "Cache-Control": { "description": "Caching directives", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745 lifecycle deprecation signal", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594 lifecycle sunset date", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MusicItem" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "required": [ "data", "meta", "links" ] } }, "text/csv": { "schema": { "type": "string" } } } }, "304": { "description": "Not Modified" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "406": { "description": "Not Acceptable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "head": { "operationId": "headMusic", "summary": "Get music list metadata", "tags": [ "music" ], "responses": { "200": { "description": "Headers only", "headers": { "X-Total-Count": { "description": "Total number of items", "schema": { "type": "integer" } }, "ETag": { "description": "Entity tag for conditional requests", "schema": { "type": "string" } }, "Last-Modified": { "description": "Last modification date", "schema": { "type": "string", "format": "date-time" } }, "Link": { "description": "RFC 8288 Web Linking header with pagination links", "schema": { "type": "string" } }, "Link-Template": { "description": "RFC 9652 Link-Template header with query parameter templates", "schema": { "type": "string" } }, "Cache-Control": { "description": "Caching directives", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745 lifecycle deprecation signal", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594 lifecycle sunset date", "schema": { "type": "string", "format": "date-time" } } } } } }, "options": { "operationId": "optionsMusic", "summary": "CORS preflight", "tags": [ "music" ], "responses": { "204": { "description": "CORS preflight response" } } } }, "/api/videos.json": { "get": { "operationId": "getVideos", "summary": "List video recommendations", "tags": [ "videos" ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of items to return (default: 50, max: 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor for fetching next page", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sort field and direction (e.g., \"year:desc\", \"addedAt:asc\")", "schema": { "type": "string", "pattern": "^[\\w.-]+:(asc|desc)(,[\\w.-]+:(asc|desc))*$" } }, { "name": "facets", "in": "query", "description": "Include facet metadata in response meta (set to 1)", "schema": { "oneOf": [ { "type": "integer", "enum": [ 1 ] }, { "type": "boolean" }, { "type": "string" } ] } }, { "name": "category", "in": "query", "description": "Filter by category", "schema": { "type": "string", "enum": [ "music-video", "live-performance", "skate", "basketball", "tech-talk", "documentary", "comedy", "other" ] } }, { "name": "q", "in": "query", "description": "Case-insensitive title search", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List response for videos", "headers": { "X-Total-Count": { "description": "Total number of items", "schema": { "type": "integer" } }, "ETag": { "description": "Entity tag for conditional requests", "schema": { "type": "string" } }, "Last-Modified": { "description": "Last modification date", "schema": { "type": "string", "format": "date-time" } }, "Link": { "description": "RFC 8288 Web Linking header with pagination links", "schema": { "type": "string" } }, "Link-Template": { "description": "RFC 9652 Link-Template header with query parameter templates", "schema": { "type": "string" } }, "Cache-Control": { "description": "Caching directives", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745 lifecycle deprecation signal", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594 lifecycle sunset date", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Video" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "required": [ "data", "meta", "links" ] } }, "text/csv": { "schema": { "type": "string" } } } }, "304": { "description": "Not Modified" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "406": { "description": "Not Acceptable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "head": { "operationId": "headVideos", "summary": "Get videos list metadata", "tags": [ "videos" ], "responses": { "200": { "description": "Headers only", "headers": { "X-Total-Count": { "description": "Total number of items", "schema": { "type": "integer" } }, "ETag": { "description": "Entity tag for conditional requests", "schema": { "type": "string" } }, "Last-Modified": { "description": "Last modification date", "schema": { "type": "string", "format": "date-time" } }, "Link": { "description": "RFC 8288 Web Linking header with pagination links", "schema": { "type": "string" } }, "Link-Template": { "description": "RFC 9652 Link-Template header with query parameter templates", "schema": { "type": "string" } }, "Cache-Control": { "description": "Caching directives", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745 lifecycle deprecation signal", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594 lifecycle sunset date", "schema": { "type": "string", "format": "date-time" } } } } } }, "options": { "operationId": "optionsVideos", "summary": "CORS preflight", "tags": [ "videos" ], "responses": { "204": { "description": "CORS preflight response" } } } }, "/api/podcasts.json": { "get": { "operationId": "getPodcasts", "summary": "List podcast recommendations", "tags": [ "podcasts" ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of items to return (default: 50, max: 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor for fetching next page", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sort field and direction (e.g., \"year:desc\", \"addedAt:asc\")", "schema": { "type": "string", "pattern": "^[\\w.-]+:(asc|desc)(,[\\w.-]+:(asc|desc))*$" } }, { "name": "facets", "in": "query", "description": "Include facet metadata in response meta (set to 1)", "schema": { "oneOf": [ { "type": "integer", "enum": [ 1 ] }, { "type": "boolean" }, { "type": "string" } ] } }, { "name": "show", "in": "query", "description": "Filter by podcast show name", "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Case-insensitive search across podcast text fields", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List response for podcasts", "headers": { "X-Total-Count": { "description": "Total number of items", "schema": { "type": "integer" } }, "ETag": { "description": "Entity tag for conditional requests", "schema": { "type": "string" } }, "Last-Modified": { "description": "Last modification date", "schema": { "type": "string", "format": "date-time" } }, "Link": { "description": "RFC 8288 Web Linking header with pagination links", "schema": { "type": "string" } }, "Link-Template": { "description": "RFC 9652 Link-Template header with query parameter templates", "schema": { "type": "string" } }, "Cache-Control": { "description": "Caching directives", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745 lifecycle deprecation signal", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594 lifecycle sunset date", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Podcast" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "required": [ "data", "meta", "links" ] } }, "text/csv": { "schema": { "type": "string" } } } }, "304": { "description": "Not Modified" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "406": { "description": "Not Acceptable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "head": { "operationId": "headPodcasts", "summary": "Get podcasts list metadata", "tags": [ "podcasts" ], "responses": { "200": { "description": "Headers only", "headers": { "X-Total-Count": { "description": "Total number of items", "schema": { "type": "integer" } }, "ETag": { "description": "Entity tag for conditional requests", "schema": { "type": "string" } }, "Last-Modified": { "description": "Last modification date", "schema": { "type": "string", "format": "date-time" } }, "Link": { "description": "RFC 8288 Web Linking header with pagination links", "schema": { "type": "string" } }, "Link-Template": { "description": "RFC 9652 Link-Template header with query parameter templates", "schema": { "type": "string" } }, "Cache-Control": { "description": "Caching directives", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745 lifecycle deprecation signal", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594 lifecycle sunset date", "schema": { "type": "string", "format": "date-time" } } } } } }, "options": { "operationId": "optionsPodcasts", "summary": "CORS preflight", "tags": [ "podcasts" ], "responses": { "204": { "description": "CORS preflight response" } } } }, "/api/tweets.json": { "get": { "operationId": "getTweets", "summary": "List tweet recommendations", "tags": [ "tweets" ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of items to return (default: 50, max: 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor for fetching next page", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sort field and direction (e.g., \"year:desc\", \"addedAt:asc\")", "schema": { "type": "string", "pattern": "^[\\w.-]+:(asc|desc)(,[\\w.-]+:(asc|desc))*$" } }, { "name": "facets", "in": "query", "description": "Include facet metadata in response meta (set to 1)", "schema": { "oneOf": [ { "type": "integer", "enum": [ 1 ] }, { "type": "boolean" }, { "type": "string" } ] } }, { "name": "author", "in": "query", "description": "Filter by tweet author", "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Case-insensitive search across tweet text fields", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List response for tweets", "headers": { "X-Total-Count": { "description": "Total number of items", "schema": { "type": "integer" } }, "ETag": { "description": "Entity tag for conditional requests", "schema": { "type": "string" } }, "Last-Modified": { "description": "Last modification date", "schema": { "type": "string", "format": "date-time" } }, "Link": { "description": "RFC 8288 Web Linking header with pagination links", "schema": { "type": "string" } }, "Link-Template": { "description": "RFC 9652 Link-Template header with query parameter templates", "schema": { "type": "string" } }, "Cache-Control": { "description": "Caching directives", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745 lifecycle deprecation signal", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594 lifecycle sunset date", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Tweet" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "required": [ "data", "meta", "links" ] } }, "text/csv": { "schema": { "type": "string" } } } }, "304": { "description": "Not Modified" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "406": { "description": "Not Acceptable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "head": { "operationId": "headTweets", "summary": "Get tweets list metadata", "tags": [ "tweets" ], "responses": { "200": { "description": "Headers only", "headers": { "X-Total-Count": { "description": "Total number of items", "schema": { "type": "integer" } }, "ETag": { "description": "Entity tag for conditional requests", "schema": { "type": "string" } }, "Last-Modified": { "description": "Last modification date", "schema": { "type": "string", "format": "date-time" } }, "Link": { "description": "RFC 8288 Web Linking header with pagination links", "schema": { "type": "string" } }, "Link-Template": { "description": "RFC 9652 Link-Template header with query parameter templates", "schema": { "type": "string" } }, "Cache-Control": { "description": "Caching directives", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745 lifecycle deprecation signal", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594 lifecycle sunset date", "schema": { "type": "string", "format": "date-time" } } } } } }, "options": { "operationId": "optionsTweets", "summary": "CORS preflight", "tags": [ "tweets" ], "responses": { "204": { "description": "CORS preflight response" } } } }, "/api/code.json": { "get": { "operationId": "getCode", "summary": "List public code activity highlights", "tags": [ "code" ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of items to return (default: 50, max: 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor for fetching next page", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sort field and direction (e.g., \"year:desc\", \"addedAt:asc\")", "schema": { "type": "string", "pattern": "^[\\w.-]+:(asc|desc)(,[\\w.-]+:(asc|desc))*$" } }, { "name": "facets", "in": "query", "description": "Include facet metadata in response meta (set to 1)", "schema": { "oneOf": [ { "type": "integer", "enum": [ 1 ] }, { "type": "boolean" }, { "type": "string" } ] } }, { "name": "kind", "in": "query", "description": "Filter by activity kind", "schema": { "type": "string" } }, { "name": "repo", "in": "query", "description": "Filter by repository full name (owner/repo)", "schema": { "type": "string" } }, { "name": "year", "in": "query", "description": "Filter by activity year", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "description": "Case-insensitive search across title, repo, and reasons", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List response for code", "headers": { "X-Total-Count": { "description": "Total number of items", "schema": { "type": "integer" } }, "ETag": { "description": "Entity tag for conditional requests", "schema": { "type": "string" } }, "Last-Modified": { "description": "Last modification date", "schema": { "type": "string", "format": "date-time" } }, "Link": { "description": "RFC 8288 Web Linking header with pagination links", "schema": { "type": "string" } }, "Link-Template": { "description": "RFC 9652 Link-Template header with query parameter templates", "schema": { "type": "string" } }, "Cache-Control": { "description": "Caching directives", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745 lifecycle deprecation signal", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594 lifecycle sunset date", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Code" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "required": [ "data", "meta", "links" ] } }, "text/csv": { "schema": { "type": "string" } } } }, "304": { "description": "Not Modified" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "406": { "description": "Not Acceptable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "head": { "operationId": "headCode", "summary": "Get code list metadata", "tags": [ "code" ], "responses": { "200": { "description": "Headers only", "headers": { "X-Total-Count": { "description": "Total number of items", "schema": { "type": "integer" } }, "ETag": { "description": "Entity tag for conditional requests", "schema": { "type": "string" } }, "Last-Modified": { "description": "Last modification date", "schema": { "type": "string", "format": "date-time" } }, "Link": { "description": "RFC 8288 Web Linking header with pagination links", "schema": { "type": "string" } }, "Link-Template": { "description": "RFC 9652 Link-Template header with query parameter templates", "schema": { "type": "string" } }, "Cache-Control": { "description": "Caching directives", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745 lifecycle deprecation signal", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594 lifecycle sunset date", "schema": { "type": "string", "format": "date-time" } } } } } }, "options": { "operationId": "optionsCode", "summary": "CORS preflight", "tags": [ "code" ], "responses": { "204": { "description": "CORS preflight response" } } } }, "/api/photos.json": { "get": { "operationId": "getPhotos", "summary": "List photos", "tags": [ "photos" ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of items to return (default: 50, max: 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor for fetching next page", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sort field and direction (e.g., \"year:desc\", \"addedAt:asc\")", "schema": { "type": "string", "pattern": "^[\\w.-]+:(asc|desc)(,[\\w.-]+:(asc|desc))*$" } }, { "name": "facets", "in": "query", "description": "Include facet metadata in response meta (set to 1)", "schema": { "oneOf": [ { "type": "integer", "enum": [ 1 ] }, { "type": "boolean" }, { "type": "string" } ] } }, { "name": "year", "in": "query", "description": "Filter by year", "schema": { "type": "integer" } }, { "name": "month", "in": "query", "description": "Filter by month (1-12)", "schema": { "type": "integer", "minimum": 1, "maximum": 12 } } ], "responses": { "200": { "description": "List response for photos", "headers": { "X-Total-Count": { "description": "Total number of items", "schema": { "type": "integer" } }, "ETag": { "description": "Entity tag for conditional requests", "schema": { "type": "string" } }, "Last-Modified": { "description": "Last modification date", "schema": { "type": "string", "format": "date-time" } }, "Link": { "description": "RFC 8288 Web Linking header with pagination links", "schema": { "type": "string" } }, "Link-Template": { "description": "RFC 9652 Link-Template header with query parameter templates", "schema": { "type": "string" } }, "Cache-Control": { "description": "Caching directives", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745 lifecycle deprecation signal", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594 lifecycle sunset date", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Photo" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "required": [ "data", "meta", "links" ] } }, "text/csv": { "schema": { "type": "string" } }, "application/geo+json": { "schema": { "$ref": "#/components/schemas/PhotoGeoJsonResponse" } } } }, "304": { "description": "Not Modified" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "406": { "description": "Not Acceptable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "head": { "operationId": "headPhotos", "summary": "Get photos list metadata", "tags": [ "photos" ], "responses": { "200": { "description": "Headers only", "headers": { "X-Total-Count": { "description": "Total number of items", "schema": { "type": "integer" } }, "ETag": { "description": "Entity tag for conditional requests", "schema": { "type": "string" } }, "Last-Modified": { "description": "Last modification date", "schema": { "type": "string", "format": "date-time" } }, "Link": { "description": "RFC 8288 Web Linking header with pagination links", "schema": { "type": "string" } }, "Link-Template": { "description": "RFC 9652 Link-Template header with query parameter templates", "schema": { "type": "string" } }, "Cache-Control": { "description": "Caching directives", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745 lifecycle deprecation signal", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594 lifecycle sunset date", "schema": { "type": "string", "format": "date-time" } } } } } }, "options": { "operationId": "optionsPhotos", "summary": "CORS preflight", "tags": [ "photos" ], "responses": { "204": { "description": "CORS preflight response" } } } }, "/api/books.json": { "get": { "operationId": "getBooks", "summary": "List book recommendations", "tags": [ "books" ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of items to return (default: 50, max: 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor for fetching next page", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sort field and direction (e.g., \"year:desc\", \"addedAt:asc\")", "schema": { "type": "string", "pattern": "^[\\w.-]+:(asc|desc)(,[\\w.-]+:(asc|desc))*$" } }, { "name": "facets", "in": "query", "description": "Include facet metadata in response meta (set to 1)", "schema": { "oneOf": [ { "type": "integer", "enum": [ 1 ] }, { "type": "boolean" }, { "type": "string" } ] } }, { "name": "author", "in": "query", "description": "Filter by author", "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Case-insensitive search across book fields", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List response for books", "headers": { "X-Total-Count": { "description": "Total number of items", "schema": { "type": "integer" } }, "ETag": { "description": "Entity tag for conditional requests", "schema": { "type": "string" } }, "Last-Modified": { "description": "Last modification date", "schema": { "type": "string", "format": "date-time" } }, "Link": { "description": "RFC 8288 Web Linking header with pagination links", "schema": { "type": "string" } }, "Link-Template": { "description": "RFC 9652 Link-Template header with query parameter templates", "schema": { "type": "string" } }, "Cache-Control": { "description": "Caching directives", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745 lifecycle deprecation signal", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594 lifecycle sunset date", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Book" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "required": [ "data", "meta", "links" ] } }, "text/csv": { "schema": { "type": "string" } } } }, "304": { "description": "Not Modified" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "406": { "description": "Not Acceptable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "head": { "operationId": "headBooks", "summary": "Get books list metadata", "tags": [ "books" ], "responses": { "200": { "description": "Headers only", "headers": { "X-Total-Count": { "description": "Total number of items", "schema": { "type": "integer" } }, "ETag": { "description": "Entity tag for conditional requests", "schema": { "type": "string" } }, "Last-Modified": { "description": "Last modification date", "schema": { "type": "string", "format": "date-time" } }, "Link": { "description": "RFC 8288 Web Linking header with pagination links", "schema": { "type": "string" } }, "Link-Template": { "description": "RFC 9652 Link-Template header with query parameter templates", "schema": { "type": "string" } }, "Cache-Control": { "description": "Caching directives", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745 lifecycle deprecation signal", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594 lifecycle sunset date", "schema": { "type": "string", "format": "date-time" } } } } } }, "options": { "operationId": "optionsBooks", "summary": "CORS preflight", "tags": [ "books" ], "responses": { "204": { "description": "CORS preflight response" } } } }, "/api/reading.json": { "get": { "operationId": "getReading", "summary": "List reading links", "tags": [ "reading" ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of items to return (default: 50, max: 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor for fetching next page", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sort field and direction (e.g., \"year:desc\", \"addedAt:asc\")", "schema": { "type": "string", "pattern": "^[\\w.-]+:(asc|desc)(,[\\w.-]+:(asc|desc))*$" } }, { "name": "facets", "in": "query", "description": "Include facet metadata in response meta (set to 1)", "schema": { "oneOf": [ { "type": "integer", "enum": [ 1 ] }, { "type": "boolean" }, { "type": "string" } ] } }, { "name": "q", "in": "query", "description": "Case-insensitive title search", "schema": { "type": "string" } }, { "name": "domain", "in": "query", "description": "Filter by normalized link domain", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List response for reading", "headers": { "X-Total-Count": { "description": "Total number of items", "schema": { "type": "integer" } }, "ETag": { "description": "Entity tag for conditional requests", "schema": { "type": "string" } }, "Last-Modified": { "description": "Last modification date", "schema": { "type": "string", "format": "date-time" } }, "Link": { "description": "RFC 8288 Web Linking header with pagination links", "schema": { "type": "string" } }, "Link-Template": { "description": "RFC 9652 Link-Template header with query parameter templates", "schema": { "type": "string" } }, "Cache-Control": { "description": "Caching directives", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745 lifecycle deprecation signal", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594 lifecycle sunset date", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Reading" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "required": [ "data", "meta", "links" ] } }, "text/csv": { "schema": { "type": "string" } } } }, "304": { "description": "Not Modified" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "406": { "description": "Not Acceptable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "head": { "operationId": "headReading", "summary": "Get reading list metadata", "tags": [ "reading" ], "responses": { "200": { "description": "Headers only", "headers": { "X-Total-Count": { "description": "Total number of items", "schema": { "type": "integer" } }, "ETag": { "description": "Entity tag for conditional requests", "schema": { "type": "string" } }, "Last-Modified": { "description": "Last modification date", "schema": { "type": "string", "format": "date-time" } }, "Link": { "description": "RFC 8288 Web Linking header with pagination links", "schema": { "type": "string" } }, "Link-Template": { "description": "RFC 9652 Link-Template header with query parameter templates", "schema": { "type": "string" } }, "Cache-Control": { "description": "Caching directives", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745 lifecycle deprecation signal", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594 lifecycle sunset date", "schema": { "type": "string", "format": "date-time" } } } } } }, "options": { "operationId": "optionsReading", "summary": "CORS preflight", "tags": [ "reading" ], "responses": { "204": { "description": "CORS preflight response" } } } }, "/api/blog.json": { "get": { "operationId": "getBlog", "summary": "List blog posts", "tags": [ "blog" ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of items to return (default: 50, max: 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor for fetching next page", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sort field and direction (e.g., \"year:desc\", \"addedAt:asc\")", "schema": { "type": "string", "pattern": "^[\\w.-]+:(asc|desc)(,[\\w.-]+:(asc|desc))*$" } }, { "name": "facets", "in": "query", "description": "Include facet metadata in response meta (set to 1)", "schema": { "oneOf": [ { "type": "integer", "enum": [ 1 ] }, { "type": "boolean" }, { "type": "string" } ] } }, { "name": "q", "in": "query", "description": "Case-insensitive search across blog title and description", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List response for blog", "headers": { "X-Total-Count": { "description": "Total number of items", "schema": { "type": "integer" } }, "ETag": { "description": "Entity tag for conditional requests", "schema": { "type": "string" } }, "Last-Modified": { "description": "Last modification date", "schema": { "type": "string", "format": "date-time" } }, "Link": { "description": "RFC 8288 Web Linking header with pagination links", "schema": { "type": "string" } }, "Link-Template": { "description": "RFC 9652 Link-Template header with query parameter templates", "schema": { "type": "string" } }, "Cache-Control": { "description": "Caching directives", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745 lifecycle deprecation signal", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594 lifecycle sunset date", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BlogItem" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "required": [ "data", "meta", "links" ] } }, "text/csv": { "schema": { "type": "string" } } } }, "304": { "description": "Not Modified" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "406": { "description": "Not Acceptable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "head": { "operationId": "headBlog", "summary": "Get blog list metadata", "tags": [ "blog" ], "responses": { "200": { "description": "Headers only", "headers": { "X-Total-Count": { "description": "Total number of items", "schema": { "type": "integer" } }, "ETag": { "description": "Entity tag for conditional requests", "schema": { "type": "string" } }, "Last-Modified": { "description": "Last modification date", "schema": { "type": "string", "format": "date-time" } }, "Link": { "description": "RFC 8288 Web Linking header with pagination links", "schema": { "type": "string" } }, "Link-Template": { "description": "RFC 9652 Link-Template header with query parameter templates", "schema": { "type": "string" } }, "Cache-Control": { "description": "Caching directives", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745 lifecycle deprecation signal", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594 lifecycle sunset date", "schema": { "type": "string", "format": "date-time" } } } } } }, "options": { "operationId": "optionsBlog", "summary": "CORS preflight", "tags": [ "blog" ], "responses": { "204": { "description": "CORS preflight response" } } } }, "/api/writing.json": { "get": { "operationId": "getWriting", "summary": "List external writing links", "tags": [ "writing" ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of items to return (default: 50, max: 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor for fetching next page", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sort field and direction (e.g., \"year:desc\", \"addedAt:asc\")", "schema": { "type": "string", "pattern": "^[\\w.-]+:(asc|desc)(,[\\w.-]+:(asc|desc))*$" } }, { "name": "facets", "in": "query", "description": "Include facet metadata in response meta (set to 1)", "schema": { "oneOf": [ { "type": "integer", "enum": [ 1 ] }, { "type": "boolean" }, { "type": "string" } ] } }, { "name": "source", "in": "query", "description": "Filter by publication source", "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Case-insensitive search across writing fields", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List response for writing", "headers": { "X-Total-Count": { "description": "Total number of items", "schema": { "type": "integer" } }, "ETag": { "description": "Entity tag for conditional requests", "schema": { "type": "string" } }, "Last-Modified": { "description": "Last modification date", "schema": { "type": "string", "format": "date-time" } }, "Link": { "description": "RFC 8288 Web Linking header with pagination links", "schema": { "type": "string" } }, "Link-Template": { "description": "RFC 9652 Link-Template header with query parameter templates", "schema": { "type": "string" } }, "Cache-Control": { "description": "Caching directives", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745 lifecycle deprecation signal", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594 lifecycle sunset date", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WritingItem" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "required": [ "data", "meta", "links" ] } }, "text/csv": { "schema": { "type": "string" } } } }, "304": { "description": "Not Modified" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "406": { "description": "Not Acceptable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "head": { "operationId": "headWriting", "summary": "Get writing list metadata", "tags": [ "writing" ], "responses": { "200": { "description": "Headers only", "headers": { "X-Total-Count": { "description": "Total number of items", "schema": { "type": "integer" } }, "ETag": { "description": "Entity tag for conditional requests", "schema": { "type": "string" } }, "Last-Modified": { "description": "Last modification date", "schema": { "type": "string", "format": "date-time" } }, "Link": { "description": "RFC 8288 Web Linking header with pagination links", "schema": { "type": "string" } }, "Link-Template": { "description": "RFC 9652 Link-Template header with query parameter templates", "schema": { "type": "string" } }, "Cache-Control": { "description": "Caching directives", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745 lifecycle deprecation signal", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594 lifecycle sunset date", "schema": { "type": "string", "format": "date-time" } } } } } }, "options": { "operationId": "optionsWriting", "summary": "CORS preflight", "tags": [ "writing" ], "responses": { "204": { "description": "CORS preflight response" } } } }, "/api/search.json": { "get": { "operationId": "getSearch", "summary": "List full-site search results", "tags": [ "search" ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of items to return (default: 50, max: 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor for fetching next page", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sort field and direction (e.g., \"year:desc\", \"addedAt:asc\")", "schema": { "type": "string", "pattern": "^[\\w.-]+:(asc|desc)(,[\\w.-]+:(asc|desc))*$" } }, { "name": "facets", "in": "query", "description": "Include facet metadata in response meta (set to 1)", "schema": { "oneOf": [ { "type": "integer", "enum": [ 1 ] }, { "type": "boolean" }, { "type": "string" } ] } }, { "name": "q", "in": "query", "description": "Search query text", "schema": { "type": "string" } }, { "name": "type", "in": "query", "description": "Filter by comma-separated content type values", "schema": { "type": "string" } }, { "name": "source", "in": "query", "description": "Filter by comma-separated source values", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List response for search", "headers": { "X-Total-Count": { "description": "Total number of items", "schema": { "type": "integer" } }, "ETag": { "description": "Entity tag for conditional requests", "schema": { "type": "string" } }, "Last-Modified": { "description": "Last modification date", "schema": { "type": "string", "format": "date-time" } }, "Link": { "description": "RFC 8288 Web Linking header with pagination links", "schema": { "type": "string" } }, "Link-Template": { "description": "RFC 9652 Link-Template header with query parameter templates", "schema": { "type": "string" } }, "Cache-Control": { "description": "Caching directives", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745 lifecycle deprecation signal", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594 lifecycle sunset date", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResultItem" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "required": [ "data", "meta", "links" ] } }, "text/csv": { "schema": { "type": "string" } } } }, "304": { "description": "Not Modified" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "406": { "description": "Not Acceptable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "head": { "operationId": "headSearch", "summary": "Get search list metadata", "tags": [ "search" ], "responses": { "200": { "description": "Headers only", "headers": { "X-Total-Count": { "description": "Total number of items", "schema": { "type": "integer" } }, "ETag": { "description": "Entity tag for conditional requests", "schema": { "type": "string" } }, "Last-Modified": { "description": "Last modification date", "schema": { "type": "string", "format": "date-time" } }, "Link": { "description": "RFC 8288 Web Linking header with pagination links", "schema": { "type": "string" } }, "Link-Template": { "description": "RFC 9652 Link-Template header with query parameter templates", "schema": { "type": "string" } }, "Cache-Control": { "description": "Caching directives", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745 lifecycle deprecation signal", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594 lifecycle sunset date", "schema": { "type": "string", "format": "date-time" } } } } } }, "options": { "operationId": "optionsSearch", "summary": "CORS preflight", "tags": [ "search" ], "responses": { "204": { "description": "CORS preflight response" } } } }, "/api/feed-items.json": { "get": { "operationId": "getFeedItems", "summary": "List unified feed items", "tags": [ "feed-items" ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of items to return (default: 50, max: 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor for fetching next page", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sort field and direction (e.g., \"year:desc\", \"addedAt:asc\")", "schema": { "type": "string", "pattern": "^[\\w.-]+:(asc|desc)(,[\\w.-]+:(asc|desc))*$" } }, { "name": "facets", "in": "query", "description": "Include facet metadata in response meta (set to 1)", "schema": { "oneOf": [ { "type": "integer", "enum": [ 1 ] }, { "type": "boolean" }, { "type": "string" } ] } }, { "name": "kind", "in": "query", "description": "Filter by comma-separated kind values", "schema": { "type": "string" } }, { "name": "source", "in": "query", "description": "Filter by comma-separated source values", "schema": { "type": "string" } }, { "name": "year", "in": "query", "description": "Filter by feed content year", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "description": "Case-insensitive search across feed item fields", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List response for feed-items", "headers": { "X-Total-Count": { "description": "Total number of items", "schema": { "type": "integer" } }, "ETag": { "description": "Entity tag for conditional requests", "schema": { "type": "string" } }, "Last-Modified": { "description": "Last modification date", "schema": { "type": "string", "format": "date-time" } }, "Link": { "description": "RFC 8288 Web Linking header with pagination links", "schema": { "type": "string" } }, "Link-Template": { "description": "RFC 9652 Link-Template header with query parameter templates", "schema": { "type": "string" } }, "Cache-Control": { "description": "Caching directives", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745 lifecycle deprecation signal", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594 lifecycle sunset date", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FeedItem" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "required": [ "data", "meta", "links" ] } }, "text/csv": { "schema": { "type": "string" } } } }, "304": { "description": "Not Modified" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "406": { "description": "Not Acceptable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "head": { "operationId": "headFeedItems", "summary": "Get feed-items list metadata", "tags": [ "feed-items" ], "responses": { "200": { "description": "Headers only", "headers": { "X-Total-Count": { "description": "Total number of items", "schema": { "type": "integer" } }, "ETag": { "description": "Entity tag for conditional requests", "schema": { "type": "string" } }, "Last-Modified": { "description": "Last modification date", "schema": { "type": "string", "format": "date-time" } }, "Link": { "description": "RFC 8288 Web Linking header with pagination links", "schema": { "type": "string" } }, "Link-Template": { "description": "RFC 9652 Link-Template header with query parameter templates", "schema": { "type": "string" } }, "Cache-Control": { "description": "Caching directives", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745 lifecycle deprecation signal", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594 lifecycle sunset date", "schema": { "type": "string", "format": "date-time" } } } } } }, "options": { "operationId": "optionsFeedItems", "summary": "CORS preflight", "tags": [ "feed-items" ], "responses": { "204": { "description": "CORS preflight response" } } } }, "/api/meta.json": { "get": { "operationId": "getMeta", "summary": "Get API metadata", "description": "Returns service metadata including collection counts and capabilities (RFC 8631 service-meta)", "tags": [ "meta" ], "responses": { "200": { "description": "API metadata", "headers": { "ETag": { "description": "Entity tag for conditional requests", "schema": { "type": "string" } }, "Last-Modified": { "description": "Last modification date", "schema": { "type": "string", "format": "date-time" } }, "Cache-Control": { "description": "Caching directives", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceMeta" } } } }, "304": { "description": "Not Modified" }, "412": { "description": "Precondition Failed" } } }, "head": { "operationId": "headMeta", "summary": "Get metadata headers only", "tags": [ "meta" ], "responses": { "200": { "description": "Headers only", "headers": { "ETag": { "description": "Entity tag for conditional requests", "schema": { "type": "string" } }, "Last-Modified": { "description": "Last modification date", "schema": { "type": "string", "format": "date-time" } }, "Cache-Control": { "description": "Caching directives", "schema": { "type": "string" } } } } } }, "options": { "operationId": "optionsMeta", "summary": "CORS preflight", "tags": [ "meta" ], "responses": { "204": { "description": "CORS preflight response" } } } }, "/api/status.json": { "get": { "operationId": "getStatus", "summary": "Get service status", "description": "Returns service health and status information (RFC 8631 status)", "tags": [ "meta" ], "responses": { "200": { "description": "Service is healthy", "headers": { "ETag": { "description": "Entity tag for conditional requests", "schema": { "type": "string" } }, "Last-Modified": { "description": "Last modification date", "schema": { "type": "string", "format": "date-time" } }, "Cache-Control": { "description": "Caching directives", "schema": { "type": "string" } } }, "content": { "application/health+json": { "schema": { "$ref": "#/components/schemas/ServiceStatus" } } } }, "304": { "description": "Not Modified" }, "412": { "description": "Precondition Failed" }, "503": { "description": "Service is degraded", "headers": { "ETag": { "description": "Entity tag for conditional requests", "schema": { "type": "string" } }, "Last-Modified": { "description": "Last modification date", "schema": { "type": "string", "format": "date-time" } }, "Cache-Control": { "description": "Caching directives", "schema": { "type": "string" } } }, "content": { "application/health+json": { "schema": { "$ref": "#/components/schemas/ServiceStatus" } } } } } }, "head": { "operationId": "headStatus", "summary": "Get status headers only", "tags": [ "meta" ], "responses": { "200": { "description": "Headers only", "headers": { "ETag": { "description": "Entity tag for conditional requests", "schema": { "type": "string" } }, "Last-Modified": { "description": "Last modification date", "schema": { "type": "string", "format": "date-time" } }, "Cache-Control": { "description": "Caching directives", "schema": { "type": "string" } } } } } }, "options": { "operationId": "optionsStatus", "summary": "CORS preflight", "tags": [ "meta" ], "responses": { "204": { "description": "CORS preflight response" } } } } }, "components": { "schemas": { "Movie": { "type": "object", "properties": { "id": { "type": "string" }, "canonicalId": { "type": "string", "pattern": "^itm_[a-f0-9]{24,32}$" }, "itemPath": { "type": "string" }, "title": { "type": "string" }, "year": { "type": [ "integer", "null" ], "minimum": 1888, "maximum": 2100 }, "releaseDate": { "type": [ "string", "null" ], "format": "date-time" }, "genres": { "type": [ "array", "null" ], "items": { "type": "string" } }, "directors": { "type": [ "array", "null" ], "items": { "type": "string" } }, "cast": { "type": [ "array", "null" ], "items": { "type": "string" } }, "youtubeTrailerUrl": { "type": [ "string", "null" ], "format": "uri" }, "notes": { "type": [ "string", "null" ] }, "addedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "canonicalId", "itemPath", "title", "year", "releaseDate", "genres", "directors", "cast", "youtubeTrailerUrl", "notes", "addedAt" ], "additionalProperties": false }, "Place": { "type": "object", "properties": { "id": { "type": "string" }, "canonicalId": { "type": "string", "pattern": "^itm_[a-f0-9]{24,32}$" }, "itemPath": { "type": "string" }, "name": { "type": "string" }, "placeId": { "type": "string" }, "category": { "enum": [ "food", "drink", "nature", "shopping", "entertainment", "lodging", "other" ], "type": "string" }, "address": { "type": [ "string", "null" ] }, "neighborhood": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 }, "website": { "type": [ "string", "null" ], "format": "uri" }, "notes": { "type": [ "string", "null" ] } }, "required": [ "id", "canonicalId", "itemPath", "name", "placeId", "category", "address", "neighborhood", "city", "country", "latitude", "longitude", "website", "notes" ], "additionalProperties": false }, "MusicItem": { "type": "object", "properties": { "id": { "type": "string" }, "canonicalId": { "type": "string", "pattern": "^itm_[a-f0-9]{24,32}$" }, "itemPath": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "type": { "type": "string", "enum": [ "album", "playlist", "mix" ] }, "releaseDate": { "type": [ "string", "null" ], "format": "date-time" }, "addedAt": { "type": [ "string", "null" ], "format": "date-time" }, "notes": { "type": [ "string", "null" ] } }, "required": [ "id", "canonicalId", "itemPath", "title", "url", "type", "releaseDate", "addedAt", "notes" ], "additionalProperties": false }, "Video": { "type": "object", "properties": { "id": { "type": "string" }, "canonicalId": { "type": "string", "pattern": "^itm_[a-f0-9]{24,32}$" }, "itemPath": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" }, "category": { "enum": [ "music-video", "live-performance", "skate", "basketball", "tech-talk", "documentary", "comedy", "other", null ], "type": [ "string", "null" ] }, "releaseDate": { "type": [ "string", "null" ], "format": "date-time" }, "addedAt": { "type": [ "string", "null" ], "format": "date-time" }, "notes": { "type": [ "string", "null" ] } }, "required": [ "id", "canonicalId", "itemPath", "title", "description", "url", "category", "releaseDate", "addedAt", "notes" ], "additionalProperties": false }, "Podcast": { "type": "object", "properties": { "id": { "type": "string" }, "canonicalId": { "type": "string", "pattern": "^itm_[a-f0-9]{24,32}$" }, "itemPath": { "type": "string" }, "title": { "type": "string" }, "showName": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "appleUrl": { "type": "string", "format": "uri" }, "spotifyUrl": { "type": "string", "format": "uri" }, "releaseDate": { "type": [ "string", "null" ], "format": "date-time" }, "addedAt": { "type": [ "string", "null" ], "format": "date-time" }, "notes": { "type": [ "string", "null" ] } }, "required": [ "id", "canonicalId", "itemPath", "title", "showName", "description", "appleUrl", "spotifyUrl", "releaseDate", "addedAt", "notes" ], "additionalProperties": false }, "Tweet": { "type": "object", "properties": { "id": { "type": "string" }, "canonicalId": { "type": "string", "pattern": "^itm_[a-f0-9]{24,32}$" }, "itemPath": { "type": "string" }, "title": { "type": "string" }, "author": { "type": "string" }, "authorName": { "type": [ "string", "null" ] }, "authorUsername": { "type": [ "string", "null" ] }, "authorProfileImageUrl": { "type": [ "string", "null" ], "format": "uri" }, "text": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "media": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "type": { "enum": [ "photo", "video", "animated_gif" ], "type": "string" }, "url": { "type": "string", "format": "uri" }, "previewImageUrl": { "type": "string", "format": "uri" }, "altText": { "type": "string" }, "width": { "type": "integer", "minimum": 0 }, "height": { "type": "integer", "minimum": 0 } }, "required": [ "type" ], "additionalProperties": false } }, "addedAt": { "type": [ "string", "null" ], "format": "date-time" }, "notes": { "type": [ "string", "null" ] } }, "required": [ "id", "canonicalId", "itemPath", "title", "author", "authorName", "authorUsername", "authorProfileImageUrl", "text", "description", "url", "createdAt", "media", "addedAt", "notes" ], "additionalProperties": false }, "Code": { "type": "object", "properties": { "id": { "type": "string" }, "canonicalId": { "type": "string", "pattern": "^itm_[a-f0-9]{24,32}$" }, "itemPath": { "type": "string" }, "activityId": { "type": "string" }, "kind": { "enum": [ "release-published", "pull-request-merged", "pull-request-reviewed", "repository-created", "repository-publicized", "repository-starred", "other" ], "type": "string" }, "title": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "repo": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "addedAt": { "type": [ "string", "null" ], "format": "date-time" }, "source": { "enum": [ "events-api", "graphql", "manual" ], "type": "string" }, "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "reasons": { "type": "array", "items": { "type": "string" } }, "notes": { "type": [ "string", "null" ] } }, "required": [ "id", "canonicalId", "itemPath", "activityId", "kind", "title", "url", "repo", "occurredAt", "addedAt", "source", "score", "reasons", "notes" ], "additionalProperties": false }, "Photo": { "type": "object", "properties": { "id": { "type": "string" }, "canonicalId": { "type": "string", "pattern": "^itm_[a-f0-9]{24,32}$" }, "itemPath": { "type": "string" }, "date": { "type": "string", "format": "date-time" }, "image": { "type": "string" }, "alt": { "type": [ "string", "null" ] }, "caption": { "type": [ "string", "null" ] }, "latitude": { "type": [ "number", "null" ], "minimum": -90, "maximum": 90 }, "longitude": { "type": [ "number", "null" ], "minimum": -180, "maximum": 180 }, "camera": { "type": [ "string", "null" ] } }, "required": [ "id", "canonicalId", "itemPath", "date", "image", "alt", "caption", "latitude", "longitude", "camera" ], "additionalProperties": false }, "Book": { "type": "object", "properties": { "id": { "type": "string" }, "canonicalId": { "type": "string", "pattern": "^itm_[a-f0-9]{24,32}$" }, "itemPath": { "type": "string" }, "title": { "type": "string" }, "author": { "type": "string" }, "year": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 2100 }, "url": { "type": [ "string", "null" ], "format": "uri" }, "addedAt": { "type": [ "string", "null" ], "format": "date-time" }, "notes": { "type": [ "string", "null" ] } }, "required": [ "id", "canonicalId", "itemPath", "title", "author", "year", "url", "addedAt", "notes" ], "additionalProperties": false }, "Reading": { "type": "object", "properties": { "id": { "type": "string" }, "canonicalId": { "type": "string", "pattern": "^itm_[a-f0-9]{24,32}$" }, "itemPath": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "normalizedUrl": { "type": "string", "format": "uri" }, "siteName": { "type": [ "string", "null" ] }, "domain": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "image": { "type": [ "string", "null" ], "format": "uri" }, "author": { "type": [ "string", "null" ] }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "addedAt": { "type": [ "string", "null" ], "format": "date-time" }, "metadataSource": { "enum": [ "open_graph", "twitter_card", "semantic", "fallback", null ], "type": [ "string", "null" ] }, "fetchedAt": { "type": [ "string", "null" ], "format": "date-time" }, "tags": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "required": [ "id", "canonicalId", "itemPath", "title", "url", "normalizedUrl", "siteName", "domain", "description", "image", "author", "publishedAt", "addedAt", "metadataSource", "fetchedAt", "tags" ], "additionalProperties": false }, "BlogItem": { "type": "object", "properties": { "id": { "type": "string" }, "canonicalId": { "type": "string", "pattern": "^itm_[a-f0-9]{24}$" }, "slug": { "type": "string" }, "itemPath": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "date": { "type": "string", "format": "date-time" } }, "required": [ "id", "canonicalId", "slug", "itemPath", "title", "description", "date" ], "additionalProperties": false }, "WritingItem": { "type": "object", "properties": { "id": { "type": "string" }, "canonicalId": { "type": "string", "pattern": "^itm_[a-f0-9]{24}$" }, "itemPath": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "normalizedUrl": { "type": "string", "format": "uri" }, "source": { "type": "string" }, "siteName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "domain": { "type": "string" }, "date": { "type": "string", "format": "date-time" }, "publishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "addedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadataSource": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fetchedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "tags": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "id", "canonicalId", "itemPath", "title", "url", "normalizedUrl", "source", "siteName", "domain", "date", "publishedAt", "addedAt", "description", "image", "author", "metadataSource", "fetchedAt", "tags" ], "additionalProperties": false }, "SearchResultItem": { "type": "object", "properties": { "id": { "type": "string" }, "canonicalId": { "type": "string", "pattern": "^itm_[a-f0-9]{24}$" }, "source": { "type": "string" }, "type": { "type": "string" }, "title": { "type": "string" }, "subtitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "itemPath": { "type": "string" }, "url": { "type": "string" }, "score": { "type": "number" } }, "required": [ "id", "canonicalId", "source", "type", "title", "subtitle", "itemPath", "url", "score" ], "additionalProperties": false }, "FeedItem": { "type": "object", "properties": { "id": { "type": "string" }, "canonicalId": { "type": "string", "pattern": "^itm_[a-f0-9]{24}$" }, "kind": { "type": "string" }, "source": { "type": "string" }, "title": { "type": "string" }, "itemPath": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "activityAt": { "type": "string", "format": "date-time" }, "activityYear": { "type": "integer" }, "contentTimestamp": { "type": "string", "format": "date-time" }, "timestamp": { "type": "string", "format": "date-time" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "year": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "slug": { "type": "string" }, "writingSource": { "enum": [ "substack", "cloudflare", "other" ], "type": "string" }, "videoId": { "type": "string" }, "embedUrl": { "type": "string", "format": "uri" }, "category": { "type": "string" }, "playlistId": { "type": "string" }, "mixId": { "type": "string" }, "mixSource": { "enum": [ "youtube", "soundcloud", "unknown" ], "type": "string" }, "albumId": { "type": "string" }, "appleUrl": { "type": "string", "format": "uri" }, "spotifyUrl": { "type": "string", "format": "uri" }, "tweetId": { "type": "string" }, "author": { "type": "string" }, "eventType": { "type": "string" }, "repo": { "type": "string" }, "score": { "type": "number" }, "reasons": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "string" }, "domain": { "type": "string" }, "siteName": { "type": "string" }, "description": { "type": "string" }, "image": { "type": "string" }, "alt": { "type": "string" }, "caption": { "type": "string" }, "bookAuthor": { "type": "string" }, "displayYear": { "type": "integer" } }, "required": [ "id", "canonicalId", "kind", "source", "title", "itemPath", "url", "activityAt", "activityYear", "contentTimestamp", "timestamp", "summary", "year" ], "additionalProperties": false }, "PaginationMeta": { "type": "object", "properties": { "totalCount": { "type": "integer" }, "pageSize": { "type": "integer" }, "timestamp": { "type": "string", "format": "date-time" }, "facets": { "type": "object", "additionalProperties": true } }, "required": [ "totalCount", "pageSize", "timestamp" ], "additionalProperties": false }, "PaginationLinks": { "type": "object", "properties": { "self": { "type": "string", "format": "uri" }, "first": { "type": "string", "format": "uri" }, "next": { "type": "string", "format": "uri" }, "prev": { "type": "string", "format": "uri" }, "last": { "type": "string", "format": "uri" } }, "required": [ "self", "first", "last" ], "additionalProperties": false }, "CollectionsMetadata": { "type": "object", "properties": { "movies": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0 }, "endpoint": { "const": "/api/movies.json" }, "filters": { "type": "array", "items": { "enum": [ "year", "genre", "director", "actor", "q" ], "type": "string" } }, "sortable": { "type": "array", "items": { "enum": [ "releaseDate", "year", "addedAt", "title" ], "type": "string" } } }, "required": [ "count", "endpoint", "filters", "sortable" ], "additionalProperties": false }, "places": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0 }, "endpoint": { "const": "/api/places.json" }, "filters": { "type": "array", "items": { "enum": [ "city", "country", "category", "neighborhood", "q" ], "type": "string" } }, "sortable": { "type": "array", "items": { "enum": [ "name" ], "type": "string" } } }, "required": [ "count", "endpoint", "filters", "sortable" ], "additionalProperties": false }, "music": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0 }, "endpoint": { "const": "/api/music.json" }, "filters": { "type": "array", "items": { "enum": [ "type", "q" ], "type": "string" } }, "sortable": { "type": "array", "items": { "enum": [ "addedAt", "releaseDate", "title" ], "type": "string" } } }, "required": [ "count", "endpoint", "filters", "sortable" ], "additionalProperties": false }, "videos": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0 }, "endpoint": { "const": "/api/videos.json" }, "filters": { "type": "array", "items": { "enum": [ "category", "q" ], "type": "string" } }, "sortable": { "type": "array", "items": { "enum": [ "addedAt", "releaseDate", "title" ], "type": "string" } } }, "required": [ "count", "endpoint", "filters", "sortable" ], "additionalProperties": false }, "podcasts": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0 }, "endpoint": { "const": "/api/podcasts.json" }, "filters": { "type": "array", "items": { "enum": [ "show", "q" ], "type": "string" } }, "sortable": { "type": "array", "items": { "enum": [ "addedAt", "releaseDate" ], "type": "string" } } }, "required": [ "count", "endpoint", "filters", "sortable" ], "additionalProperties": false }, "tweets": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0 }, "endpoint": { "const": "/api/tweets.json" }, "filters": { "type": "array", "items": { "enum": [ "author", "q" ], "type": "string" } }, "sortable": { "type": "array", "items": { "enum": [ "createdAt", "addedAt" ], "type": "string" } } }, "required": [ "count", "endpoint", "filters", "sortable" ], "additionalProperties": false }, "code": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0 }, "endpoint": { "const": "/api/code.json" }, "filters": { "type": "array", "items": { "enum": [ "kind", "repo", "year", "q" ], "type": "string" } }, "sortable": { "type": "array", "items": { "enum": [ "occurredAt", "addedAt", "score", "title" ], "type": "string" } } }, "required": [ "count", "endpoint", "filters", "sortable" ], "additionalProperties": false }, "photos": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0 }, "endpoint": { "const": "/api/photos.json" }, "filters": { "type": "array", "items": { "enum": [ "year", "month" ], "type": "string" } }, "sortable": { "type": "array", "items": { "enum": [ "date" ], "type": "string" } } }, "required": [ "count", "endpoint", "filters", "sortable" ], "additionalProperties": false }, "books": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0 }, "endpoint": { "const": "/api/books.json" }, "filters": { "type": "array", "items": { "enum": [ "author", "q" ], "type": "string" } }, "sortable": { "type": "array", "items": { "enum": [ "addedAt", "year", "title", "author" ], "type": "string" } } }, "required": [ "count", "endpoint", "filters", "sortable" ], "additionalProperties": false }, "reading": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0 }, "endpoint": { "const": "/api/reading.json" }, "filters": { "type": "array", "items": { "enum": [ "q", "domain" ], "type": "string" } }, "sortable": { "type": "array", "items": { "enum": [ "publishedAt", "addedAt", "title", "domain" ], "type": "string" } } }, "required": [ "count", "endpoint", "filters", "sortable" ], "additionalProperties": false } }, "required": [ "movies", "places", "music", "videos", "podcasts", "tweets", "code", "photos", "books", "reading" ], "additionalProperties": false }, "ServiceMeta": { "type": "object", "properties": { "name": { "const": "Brendan Irvine-Broque Personal API" }, "version": { "const": "1.0.0" }, "lastUpdated": { "type": "string", "format": "date-time" }, "documentation": { "const": "/api/" }, "openapi": { "const": "/api/openapi.json" }, "skillsIndex": { "const": "/.well-known/skills/index.json" }, "apiCatalog": { "const": "/.well-known/api-catalog" }, "capnweb": { "type": "object", "properties": { "endpoint": { "const": "/api/rpc" }, "transport": { "const": "http-batch" }, "stability": { "const": "experimental" }, "methods": { "type": "array", "items": { "enum": [ "query", "getMeta", "getStatus" ], "type": "string" }, "minItems": 3, "maxItems": 3 } }, "required": [ "endpoint", "transport", "stability", "methods" ], "additionalProperties": false }, "mcp": { "type": "object", "properties": { "endpoint": { "const": "/mcp" }, "serverCard": { "const": "/.well-known/mcp/server-card.json" }, "discovery": { "const": "/.well-known/mcp.json" }, "protocolVersion": { "const": "2025-11-25" } }, "required": [ "endpoint", "serverCard", "discovery", "protocolVersion" ], "additionalProperties": false }, "collections": { "$ref": "#/components/schemas/CollectionsMetadata" } }, "required": [ "name", "version", "lastUpdated", "documentation", "openapi", "skillsIndex", "apiCatalog", "capnweb", "mcp", "collections" ], "additionalProperties": false }, "ServiceStatus": { "type": "object", "properties": { "status": { "enum": [ "healthy", "degraded" ], "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "version": { "const": "1.0.0" }, "checks": { "type": "object", "properties": { "collections": { "type": "object", "properties": { "status": { "enum": [ "pass", "fail" ], "type": "string" }, "componentType": { "const": "datastore" }, "observedValue": { "type": "integer", "minimum": 0 }, "observedUnit": { "const": "items" } }, "required": [ "status", "componentType", "observedValue", "observedUnit" ], "additionalProperties": false } }, "required": [ "collections" ], "additionalProperties": false }, "metrics": { "type": "object", "properties": { "responseTimeMs": { "type": "integer", "minimum": 1 } }, "required": [ "responseTimeMs" ], "additionalProperties": false }, "links": { "type": "object", "properties": { "self": { "const": "/api/status.json" }, "meta": { "const": "/api/meta.json" }, "docs": { "const": "/api/" }, "capnweb": { "const": "/api/rpc" }, "mcp": { "const": "/mcp" } }, "required": [ "self", "meta", "docs", "capnweb", "mcp" ], "additionalProperties": false } }, "required": [ "status", "timestamp", "version", "checks", "metrics", "links" ], "additionalProperties": false }, "GeoJsonPointGeometry": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "Point" ] }, "coordinates": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } }, "required": [ "type", "coordinates" ] }, "PlaceGeoJsonResponse": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "FeatureCollection" ] }, "features": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "Feature" ] }, "id": { "type": [ "string", "number" ] }, "geometry": { "oneOf": [ { "$ref": "#/components/schemas/GeoJsonPointGeometry" }, { "type": "null" } ] }, "properties": { "$ref": "#/components/schemas/Place" } }, "required": [ "type", "geometry", "properties" ] } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "required": [ "type", "features", "meta", "links" ] }, "PhotoGeoJsonResponse": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "FeatureCollection" ] }, "features": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "Feature" ] }, "id": { "type": [ "string", "number" ] }, "geometry": { "oneOf": [ { "$ref": "#/components/schemas/GeoJsonPointGeometry" }, { "type": "null" } ] }, "properties": { "$ref": "#/components/schemas/Photo" } }, "required": [ "type", "geometry", "properties" ] } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "required": [ "type", "features", "meta", "links" ] }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "format": "uri", "description": "Problem type URI (see /problems/)", "examples": [ "https://irvinebroque.com/problems/invalid-cursor", "https://irvinebroque.com/problems/invalid-limit", "https://irvinebroque.com/problems/invalid-offset", "https://irvinebroque.com/problems/invalid-sort", "https://irvinebroque.com/problems/invalid-filter-value", "https://irvinebroque.com/problems/not-acceptable" ] }, "title": { "type": "string", "description": "Short human-readable summary" }, "status": { "type": "integer", "description": "HTTP status code" }, "detail": { "type": "string", "description": "Human-readable explanation" }, "instance": { "type": "string", "format": "uri", "description": "URI reference for this occurrence" } }, "required": [ "type", "title", "status", "detail" ] } }, "parameters": { "limitParam": { "name": "limit", "in": "query", "description": "Maximum number of items to return", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "cursorParam": { "name": "cursor", "in": "query", "description": "Pagination cursor", "schema": { "type": "string" } }, "sortParam": { "name": "sort", "in": "query", "description": "Sort field and direction (e.g., \"year:desc\")", "schema": { "type": "string", "pattern": "^[\\w.-]+:(asc|desc)(,[\\w.-]+:(asc|desc))*$" } }, "facetsParam": { "name": "facets", "in": "query", "description": "Include facet metadata in response meta (set to 1)", "schema": { "oneOf": [ { "type": "integer", "enum": [ 1 ] }, { "type": "boolean" }, { "type": "string" } ] } } }, "headers": { "X-Total-Count": { "description": "Total number of items", "schema": { "type": "integer" } }, "ETag": { "description": "Entity tag for conditional requests", "schema": { "type": "string" } }, "Last-Modified": { "description": "Last modification date", "schema": { "type": "string", "format": "date-time" } }, "Link": { "description": "RFC 8288 Web Linking header with pagination links", "schema": { "type": "string" } }, "Link-Template": { "description": "RFC 9652 Link-Template header with query parameter templates", "schema": { "type": "string" } }, "Cache-Control": { "description": "Caching directives", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745 lifecycle deprecation signal", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594 lifecycle sunset date", "schema": { "type": "string", "format": "date-time" } } } } }