{
  "openapi": "3.1.0",
  "info": {
    "title": "Sam Gammon public reference API",
    "version": "1.0.0",
    "description": "Free public read-only API. No authentication, API key, signup, or payment required. API v1 uses /api/v1/ paths. Additive fields and new records may be added within v1. Breaking contract changes require a new major path; any planned v1 retirement will be announced at /docs at least 90 days in advance with Deprecation and Sunset response headers. No retirement is scheduled."
  },
  "servers": [
    {
      "url": "https://sam-cv.elide.dev"
    }
  ],
  "security": [],
  "externalDocs": {
    "description": "Examples, authentication, versioning, and usage guidance",
    "url": "https://sam-cv.elide.dev/docs"
  },
  "paths": {
    "/api/v1/search": {
      "get": {
        "operationId": "searchExperience",
        "summary": "Search experience, topics, and talks",
        "description": "Public, free, read-only search. All query words must match; results include citation URLs. Filter by topic or kind and use nextOffset for pagination.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 500
            }
          },
          {
            "name": "topic",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "networking",
                "linux",
                "jvm",
                "kotlin",
                "java",
                "javascript",
                "typescript",
                "python",
                "rust",
                "runtimes",
                "agentic-engineering",
                "product-strategy",
                "developer-experience",
                "build-systems",
                "leadership",
                "operations",
                "open-source",
                "speaking",
                "engineering"
              ]
            }
          },
          {
            "name": "kind",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "experience",
                "software",
                "contribution",
                "talk",
                "profile",
                "reference"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Search experience, topics, and talks",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "query",
                    "topic",
                    "kind",
                    "total",
                    "offset",
                    "limit",
                    "nextOffset",
                    "records"
                  ],
                  "properties": {
                    "query": {
                      "type": "string"
                    },
                    "topic": {
                      "type": "string"
                    },
                    "kind": {
                      "type": "string"
                    },
                    "total": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "offset": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "limit": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "nextOffset": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "description": "Pass as offset for the next page; null means the last page."
                    },
                    "records": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "id",
                          "title",
                          "kind",
                          "summary",
                          "details",
                          "tags",
                          "sources"
                        ],
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "kind": {
                            "type": "string"
                          },
                          "summary": {
                            "type": "string"
                          },
                          "details": {
                            "type": "string"
                          },
                          "date": {
                            "type": "string"
                          },
                          "provenance": {
                            "type": "string"
                          },
                          "verification": {
                            "type": "string"
                          },
                          "url": {
                            "type": "string",
                            "format": "uri"
                          },
                          "tags": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "topics": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "required": [
                                "id",
                                "label",
                                "url"
                              ],
                              "properties": {
                                "id": {
                                  "type": "string"
                                },
                                "label": {
                                  "type": "string"
                                },
                                "url": {
                                  "type": "string",
                                  "format": "uri"
                                }
                              }
                            }
                          },
                          "sources": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "required": [
                                "label",
                                "url",
                                "type"
                              ],
                              "properties": {
                                "label": {
                                  "type": "string"
                                },
                                "url": {
                                  "type": "string",
                                  "format": "uri-reference"
                                },
                                "type": {
                                  "type": "string"
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters; detail explains how to recover.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Unknown API route.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed; use GET or HEAD.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/records": {
      "get": {
        "operationId": "allRecords",
        "summary": "List all public reference records",
        "description": "Returns the full public archive with canonical URLs, topic labels, and source references. Missing dates are intentionally omitted; do not infer them.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "List all public reference records",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": [
                      "id",
                      "title",
                      "kind",
                      "summary",
                      "details",
                      "tags",
                      "sources"
                    ],
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "title": {
                        "type": "string"
                      },
                      "kind": {
                        "type": "string"
                      },
                      "summary": {
                        "type": "string"
                      },
                      "details": {
                        "type": "string"
                      },
                      "date": {
                        "type": "string"
                      },
                      "provenance": {
                        "type": "string"
                      },
                      "verification": {
                        "type": "string"
                      },
                      "url": {
                        "type": "string",
                        "format": "uri"
                      },
                      "tags": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "topics": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "required": [
                            "id",
                            "label",
                            "url"
                          ],
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "label": {
                              "type": "string"
                            },
                            "url": {
                              "type": "string",
                              "format": "uri"
                            }
                          }
                        }
                      },
                      "sources": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "required": [
                            "label",
                            "url",
                            "type"
                          ],
                          "properties": {
                            "label": {
                              "type": "string"
                            },
                            "url": {
                              "type": "string",
                              "format": "uri-reference"
                            },
                            "type": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters; detail explains how to recover.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Unknown API route.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed; use GET or HEAD.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/topics": {
      "get": {
        "operationId": "listTopics",
        "summary": "List supported topic identifiers",
        "description": "Returns a map from stable topic IDs to human-readable labels. Use a key as the search topic parameter.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "List supported topic identifiers",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters; detail explains how to recover.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Unknown API route.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed; use GET or HEAD.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/search": {
      "get": {
        "operationId": "searchExperienceAlias",
        "summary": "Search experience using the original route",
        "description": "Compatibility alias for GET /api/v1/search, with identical parameters and responses.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 500
            }
          },
          {
            "name": "topic",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "networking",
                "linux",
                "jvm",
                "kotlin",
                "java",
                "javascript",
                "typescript",
                "python",
                "rust",
                "runtimes",
                "agentic-engineering",
                "product-strategy",
                "developer-experience",
                "build-systems",
                "leadership",
                "operations",
                "open-source",
                "speaking",
                "engineering"
              ]
            }
          },
          {
            "name": "kind",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "experience",
                "software",
                "contribution",
                "talk",
                "profile",
                "reference"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Search experience using the original route",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "query",
                    "topic",
                    "kind",
                    "total",
                    "offset",
                    "limit",
                    "nextOffset",
                    "records"
                  ],
                  "properties": {
                    "query": {
                      "type": "string"
                    },
                    "topic": {
                      "type": "string"
                    },
                    "kind": {
                      "type": "string"
                    },
                    "total": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "offset": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "limit": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "nextOffset": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "description": "Pass as offset for the next page; null means the last page."
                    },
                    "records": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "id",
                          "title",
                          "kind",
                          "summary",
                          "details",
                          "tags",
                          "sources"
                        ],
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "kind": {
                            "type": "string"
                          },
                          "summary": {
                            "type": "string"
                          },
                          "details": {
                            "type": "string"
                          },
                          "date": {
                            "type": "string"
                          },
                          "provenance": {
                            "type": "string"
                          },
                          "verification": {
                            "type": "string"
                          },
                          "url": {
                            "type": "string",
                            "format": "uri"
                          },
                          "tags": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "topics": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "required": [
                                "id",
                                "label",
                                "url"
                              ],
                              "properties": {
                                "id": {
                                  "type": "string"
                                },
                                "label": {
                                  "type": "string"
                                },
                                "url": {
                                  "type": "string",
                                  "format": "uri"
                                }
                              }
                            }
                          },
                          "sources": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "required": [
                                "label",
                                "url",
                                "type"
                              ],
                              "properties": {
                                "label": {
                                  "type": "string"
                                },
                                "url": {
                                  "type": "string",
                                  "format": "uri-reference"
                                },
                                "type": {
                                  "type": "string"
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters; detail explains how to recover.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Unknown API route.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed; use GET or HEAD.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/records.json": {
      "get": {
        "operationId": "downloadRecords",
        "summary": "Download the archive as JSON",
        "description": "Static public records export. Source URLs may be relative to the site origin. For resolved citation URLs use /api/v1/records.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Download the archive as JSON",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": [
                      "id",
                      "title",
                      "kind",
                      "summary",
                      "details",
                      "tags",
                      "sources"
                    ],
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "title": {
                        "type": "string"
                      },
                      "kind": {
                        "type": "string"
                      },
                      "summary": {
                        "type": "string"
                      },
                      "details": {
                        "type": "string"
                      },
                      "date": {
                        "type": "string"
                      },
                      "provenance": {
                        "type": "string"
                      },
                      "verification": {
                        "type": "string"
                      },
                      "url": {
                        "type": "string",
                        "format": "uri"
                      },
                      "tags": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "topics": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "required": [
                            "id",
                            "label",
                            "url"
                          ],
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "label": {
                              "type": "string"
                            },
                            "url": {
                              "type": "string",
                              "format": "uri"
                            }
                          }
                        }
                      },
                      "sources": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "required": [
                            "label",
                            "url",
                            "type"
                          ],
                          "properties": {
                            "label": {
                              "type": "string"
                            },
                            "url": {
                              "type": "string",
                              "format": "uri-reference"
                            },
                            "type": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters; detail explains how to recover.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Unknown API route.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed; use GET or HEAD.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/topics.json": {
      "get": {
        "operationId": "downloadTopics",
        "summary": "Download the topic taxonomy",
        "description": "Static topic ID to label mapping; equivalent to /api/v1/topics.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Download the topic taxonomy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters; detail explains how to recover.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Unknown API route.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed; use GET or HEAD.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Problem": {
        "type": "object",
        "required": [
          "type",
          "status",
          "title",
          "detail",
          "documentation"
        ],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri"
          },
          "status": {
            "type": "integer"
          },
          "title": {
            "type": "string"
          },
          "detail": {
            "type": "string"
          },
          "documentation": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Record": {
        "type": "object",
        "required": [
          "id",
          "title",
          "kind",
          "summary",
          "details",
          "tags",
          "sources"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "kind": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "details": {
            "type": "string"
          },
          "date": {
            "type": "string"
          },
          "provenance": {
            "type": "string"
          },
          "verification": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "topics": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "id",
                "label",
                "url"
              ],
              "properties": {
                "id": {
                  "type": "string"
                },
                "label": {
                  "type": "string"
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                }
              }
            }
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "label",
                "url",
                "type"
              ],
              "properties": {
                "label": {
                  "type": "string"
                },
                "url": {
                  "type": "string",
                  "format": "uri-reference"
                },
                "type": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "SearchResults": {
        "type": "object",
        "required": [
          "query",
          "topic",
          "kind",
          "total",
          "offset",
          "limit",
          "nextOffset",
          "records"
        ],
        "properties": {
          "query": {
            "type": "string"
          },
          "topic": {
            "type": "string"
          },
          "kind": {
            "type": "string"
          },
          "total": {
            "type": "integer",
            "minimum": 0
          },
          "offset": {
            "type": "integer",
            "minimum": 0
          },
          "limit": {
            "type": "integer",
            "minimum": 0
          },
          "nextOffset": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Pass as offset for the next page; null means the last page."
          },
          "records": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "id",
                "title",
                "kind",
                "summary",
                "details",
                "tags",
                "sources"
              ],
              "properties": {
                "id": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                },
                "kind": {
                  "type": "string"
                },
                "summary": {
                  "type": "string"
                },
                "details": {
                  "type": "string"
                },
                "date": {
                  "type": "string"
                },
                "provenance": {
                  "type": "string"
                },
                "verification": {
                  "type": "string"
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                },
                "tags": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "topics": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": [
                      "id",
                      "label",
                      "url"
                    ],
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "label": {
                        "type": "string"
                      },
                      "url": {
                        "type": "string",
                        "format": "uri"
                      }
                    }
                  }
                },
                "sources": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": [
                      "label",
                      "url",
                      "type"
                    ],
                    "properties": {
                      "label": {
                        "type": "string"
                      },
                      "url": {
                        "type": "string",
                        "format": "uri-reference"
                      },
                      "type": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}