openapi: 3.1.0
info:
  title: Jay Shah AI Systems & Research API
  version: 1.0.0
  description: 'Self-describing programmatic API and LLM function calling surface for jayshah.dev. Access technical writings on LLM evaluations, entity resolution, keyed text watermarking, open-source projects, and research profiles. API Versioning: Endpoints are versioned under /api/v1/ (with legacy /api/ aliases maintained for backward compatibility). Deprecation policy: Breaking changes are published 6 months in advance with Sunset response headers and OpenAPI specification updates.'
  contact:
    name: Jay Shah
    email: contact@jayshah.dev
    url: https://jayshah.dev
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: https://jayshah.dev/api/v1
    description: Production API v1 Server
  - url: https://jayshah.dev
    description: Production Base Server
paths:
  /api/v1/posts.json:
    get:
      operationId: listBlogPosts
      summary: List published blog posts
      description: Retrieve published articles with titles, summaries, tags, reading estimates, publication dates, and direct markdown links.
      parameters:
        - name: tag
          in: query
          required: false
          description: Filter posts by topic tag (e.g., "ai-safety", "rag", "watermarking", "llm", "entity-resolution").
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: Maximum number of items to return.
          schema:
            type: integer
            default: 10
      responses:
        '200':
          description: Successful list of blog posts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostListResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/posts/{slug}.json:
    get:
      operationId: getBlogPostBySlug
      summary: Get single blog post with markdown body
      description: Retrieve complete article details including full raw markdown content, outline headings, publication date, and tags for a given post slug.
      parameters:
        - name: slug
          in: path
          required: true
          description: The unique post slug (e.g. "how-text-watermarks-hide-in-plain-sight", "entity-resolution-dense-retrieval", "memory-architecture").
          schema:
            type: string
      responses:
        '200':
          description: Post details with markdown body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostDetail'
        '404':
          description: Post not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects.json:
    get:
      operationId: listProjects
      summary: List open-source projects
      description: Retrieve open-source AI repositories, tools, and research codebases built by Jay Shah with descriptions, URLs, and tags.
      parameters:
        - name: tag
          in: query
          required: false
          description: Filter projects by topic tag (e.g., "AI AGENTS", "TYPESCRIPT", "PYTHON").
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: Maximum number of projects to return.
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: List of open-source projects
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectListResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/reads.json:
    get:
      operationId: listReadingList
      summary: List curated readings and research notes
      description: Retrieve curated research papers, books, and articles read by Jay Shah with notes, links, and tags.
      parameters:
        - name: tag
          in: query
          required: false
          description: Filter reading list items by topic tag (e.g., "scaling-laws", "llm", "ai-agents").
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: Maximum number of items to return.
          schema:
            type: integer
            default: 30
      responses:
        '200':
          description: List of curated reading items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadListResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/profile.json:
    get:
      operationId: getAuthorProfile
      summary: Get author profile, patents, and contact
      description: Retrieve author career background, patents, honors, social links, contact information, and AI research focus areas.
      parameters:
        - name: fields
          in: query
          required: false
          description: Optional comma-separated fields filter (e.g. "current_role,patents,contact").
          schema:
            type: string
      responses:
        '200':
          description: Author profile information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorProfile'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/tools.json:
    get:
      operationId: listToolDefinitions
      summary: List LLM tool calling declarations
      description: Retrieve function calling definitions formatted for OpenAI, Anthropic, and Gemini LLM agents.
      parameters:
        - name: format
          in: query
          required: false
          description: Tool calling format to return (e.g., "openai", "anthropic", "gemini").
          schema:
            type: string
            enum:
              - openai
              - anthropic
              - gemini
            default: openai
      responses:
        '200':
          description: Tool calling declarations
          content:
            application/json:
              schema:
                type: object
                properties:
                  version:
                    type: string
                  description:
                    type: string
                  tools:
                    type: array
                    items:
                      type: object
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/posts.json:
    get:
      operationId: listBlogPostsLegacy
      summary: List published blog posts (legacy endpoint)
      description: Alias for /api/v1/posts.json.
      responses:
        '200':
          description: List of blog posts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostListResponse'
  /api/posts/{slug}.json:
    get:
      operationId: getBlogPostBySlugLegacy
      summary: Get single blog post (legacy endpoint)
      description: Alias for /api/v1/posts/{slug}.json.
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Post details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostDetail'
  /api/projects.json:
    get:
      operationId: listProjectsLegacy
      summary: List open-source projects (legacy endpoint)
      description: Alias for /api/v1/projects.json.
      responses:
        '200':
          description: List of projects
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectListResponse'
  /api/reads.json:
    get:
      operationId: listReadingListLegacy
      summary: List reading list items (legacy endpoint)
      description: Alias for /api/v1/reads.json.
      responses:
        '200':
          description: List of reading items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadListResponse'
  /api/profile.json:
    get:
      operationId: getAuthorProfileLegacy
      summary: Get author profile (legacy endpoint)
      description: Alias for /api/v1/profile.json.
      responses:
        '200':
          description: Author profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorProfile'
  /api/tools.json:
    get:
      operationId: listToolDefinitionsLegacy
      summary: List tool definitions (legacy endpoint)
      description: Alias for /api/v1/tools.json.
      responses:
        '200':
          description: Tool definitions
          content:
            application/json:
              schema:
                type: object
components:
  schemas:
    PostSummary:
      type: object
      required:
        - slug
        - title
        - description
        - date
        - tags
        - url
        - markdown_url
      properties:
        slug:
          type: string
          example: how-text-watermarks-hide-in-plain-sight
        title:
          type: string
          example: How Text Watermarks Hide in Plain Sight
        description:
          type: string
          example: Statistical analysis of keyed LLM watermarking
        date:
          type: string
          format: date-time
          example: '2026-08-16T00:00:00.000Z'
        tags:
          type: array
          items:
            type: string
          example:
            - ai-safety
            - watermarking
            - llm
        reading_time:
          type: string
          example: 12 min read
        url:
          type: string
          format: uri
          example: https://jayshah.dev/posts/how-text-watermarks-hide-in-plain-sight/
        markdown_url:
          type: string
          format: uri
          example: https://jayshah.dev/posts/how-text-watermarks-hide-in-plain-sight.md
        json_url:
          type: string
          format: uri
          example: https://jayshah.dev/api/v1/posts/how-text-watermarks-hide-in-plain-sight.json
        image:
          type: string
          format: uri
    PostDetail:
      type: object
      required:
        - slug
        - title
        - description
        - date
        - tags
        - url
        - markdown_url
        - content_markdown
      properties:
        slug:
          type: string
          example: how-text-watermarks-hide-in-plain-sight
        title:
          type: string
          example: How Text Watermarks Hide in Plain Sight
        description:
          type: string
          example: Statistical analysis of keyed LLM watermarking
        date:
          type: string
          format: date-time
          example: '2026-08-16T00:00:00.000Z'
        tags:
          type: array
          items:
            type: string
          example:
            - ai-safety
            - watermarking
            - llm
        reading_time:
          type: string
          example: 12 min read
        url:
          type: string
          format: uri
          example: https://jayshah.dev/posts/how-text-watermarks-hide-in-plain-sight/
        markdown_url:
          type: string
          format: uri
          example: https://jayshah.dev/posts/how-text-watermarks-hide-in-plain-sight.md
        image:
          type: string
          format: uri
        headings:
          type: array
          items:
            type: object
            properties:
              depth:
                type: integer
                example: 2
              text:
                type: string
                example: Statistical Detection
              slug:
                type: string
                example: statistical-detection
        content_markdown:
          type: string
          description: Raw markdown body of the post
    Project:
      type: object
      required:
        - title
        - description
        - url
        - tags
      properties:
        title:
          type: string
          example: Pi Agent Extensions
        description:
          type: string
          example: A collection of extensions and themes for the Pi coding agent.
        url:
          type: string
          format: uri
          example: https://github.com/jayshah5696/pi-agent-extensions
        tags:
          type: array
          items:
            type: string
          example:
            - AI AGENTS
            - TYPESCRIPT
    ReadItem:
      type: object
      required:
        - slug
        - title
        - url
        - date
        - tags
      properties:
        slug:
          type: string
          example: scaling-laws-carefully
        title:
          type: string
          example: Scaling Laws Carefully
        url:
          type: string
          format: uri
          example: https://arxiv.org/abs/2401.00000
        date:
          type: string
          format: date-time
          example: '2026-06-15T00:00:00.000Z'
        tags:
          type: array
          items:
            type: string
          example:
            - scaling-laws
            - llm
        notes_markdown:
          type: string
        site_url:
          type: string
          format: uri
          example: https://jayshah.dev/reads/
    AuthorProfile:
      type: object
      required:
        - name
        - headline
        - description
        - current_role
        - contact
      properties:
        name:
          type: string
          example: Jay Shah
        headline:
          type: string
          example: Senior Data Scientist | AI Applications & Foundational Models
        description:
          type: string
        current_role:
          type: object
          properties:
            title:
              type: string
              example: Senior Data Scientist
            organization:
              type: string
              example: 6sense
            url:
              type: string
              format: uri
              example: https://6sense.com
            focus_areas:
              type: array
              items:
                type: string
        education:
          type: array
          items:
            type: object
        patents:
          type: array
          items:
            type: object
        honors:
          type: array
          items:
            type: string
        contact:
          type: object
          properties:
            email:
              type: string
              example: contact@jayshah.dev
            contact_point_type:
              type: string
              example: technical support
            website:
              type: string
              format: uri
              example: https://jayshah.dev
        social_profiles:
          type: object
        same_as:
          type: array
          items:
            type: string
        agent_resources:
          type: object
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - status
            - resolution
          properties:
            code:
              type: string
              example: NOT_FOUND
            message:
              type: string
              example: The requested API resource was not found.
            status:
              type: integer
              example: 404
            resolution:
              type: string
              example: Check available endpoints at https://jayshah.dev/openapi.json or consult https://jayshah.dev/llms.txt
            documentation_url:
              type: string
              format: uri
              example: https://jayshah.dev/openapi.json
    PostListResponse:
      type: object
      required:
        - total
        - posts
      properties:
        total:
          type: integer
          example: 10
        posts:
          type: array
          items:
            $ref: '#/components/schemas/PostSummary'
    ProjectListResponse:
      type: object
      required:
        - total
        - projects
      properties:
        total:
          type: integer
          example: 14
        projects:
          type: array
          items:
            $ref: '#/components/schemas/Project'
    ReadListResponse:
      type: object
      required:
        - total
        - reads
      properties:
        total:
          type: integer
          example: 25
        reads:
          type: array
          items:
            $ref: '#/components/schemas/ReadItem'