sudhanva-me Posts API

openapi: 3.2.0
info:
  title: sudhanva.me Public Posts API
  version: 1.2.0
  summary: Read Sudhanva Narayana's public profile and writing metadata, send batch reads, and create profile-insight jobs.
  description: A public API with no authentication for agents, search tools, feed readers, and small integrations. Retrieval and batch operations return only information that is already published on sudhanva.me. The profile-insights operation runs asynchronously and uses the same public data to make temporary, deterministic guidance. It does not accept free-form text, secrets, or private data. The URL carries the stable API version. A breaking change uses a new major path. The API announces the retirement of a version at least 90 days in advance, and it sends Deprecation and Sunset response headers.
  x-api-status: stable
  x-read-only: false
  x-authentication: none
  x-idempotency-policy: POST /profile-insights requires Idempotency-Key. A key is retained for the 24-hour lifetime of its job; replaying the same request returns the same job, while reusing the key with a different request returns 422.
  x-async-jobs: true
  x-versioning-strategy: URL major version
  x-deprecation-policy: https://sudhanva.me/developers/versioning/
  contact:
    name: Sudhanva Narayana
    url: https://sudhanva.me/contact/
    email: nsudhanva@gmail.com
  license:
    name: MIT
    identifier: MIT
servers:
- url: https://sudhanva.me/api/v1
  description: Production API, version 1
- url: https://sudhanva.me/api/sandbox/v1
  description: Sandbox. A free, stateless test environment with the same contract. It needs no credentials and stores no profile-insight jobs. It has no batch endpoint.
security: []
tags:
- name: Posts
  description: Read metadata for published writing.
paths:
  /posts:
    get:
      operationId: listPublishedPosts
      summary: List published posts
      description: Returns metadata for published posts, newest first. You can filter by an exact tag and set the number of results.
      tags:
      - Posts
      parameters:
      - name: limit
        in: query
        required: false
        description: Maximum number of posts to return. Defaults to 20.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: tag
        in: query
        required: false
        description: Post tag to match, such as kubernetes or machine-learning. The case-insensitive.
        schema:
          type: string
          minLength: 1
          pattern: ^\s*[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*\s*$
      - name: cursor
        in: query
        required: false
        description: Opaque cursor from the next_cursor value of the previous page.
        schema:
          type: string
          minLength: 1
      responses:
        '200':
          description: A filtered page of published post metadata.
          headers:
            Link:
              $ref: '#/components/headers/DeprecationPolicyLink'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          description: An unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          $ref: '#/components/responses/UnexpectedError'
  /posts/{slug}:
    get:
      operationId: getPublishedPost
      summary: Get one published post
      description: Returns metadata for the published post that has this canonical URL slug.
      tags:
      - Posts
      parameters:
      - name: slug
        in: path
        required: true
        description: Canonical lowercase, hyphen-separated post slug.
        schema:
          type: string
          minLength: 1
          pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          description: An unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        default:
          $ref: '#/components/responses/UnexpectedError'
components:
  responses:
    BadRequest:
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    NotFound:
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    UnexpectedError:
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    ServiceUnavailable:
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    MethodNotAllowed:
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
  headers:
    DeprecationPolicyLink:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
  schemas:
    Post:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    PostList:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    ErrorEnvelope:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
externalDocs:
  description: Sudhanva API developer documentation
  url: https://sudhanva.me/docs/