Danny Keane Batch API

openapi: 3.2.0
info:
  title: Danny Keane API (dannykeane.com) Batch API
  version: 1.0.0
  description: 'Public HTTP endpoints on dannykeane.com, the personal site of Danny Keane. No authentication on any endpoint.


    Pagination: list endpoints (/api/v1/work) are cursor-paginated. Pass limit for the page size; each page returns next_cursor, null on the last page -- send it back as cursor for the next one. Cursors are opaque tokens.


    Async jobs: send Prefer: respond-async to POST /api/v1/batch for a 202 whose Location (and body status_url) is /api/v1/jobs/{id}; GET it for the result. Jobs are stateless -- the id carries the request, the work runs when you poll, nothing is stored -- and ids expire an hour after creation.


    Versioning: the stable surface is /api/v1/. Breaking changes ship as a new version prefix; a deprecated endpoint answers with Deprecation and Sunset headers (RFC 9745 / RFC 8594) at least six months before removal.


    Deprecation policy: every /api response carries `Link: ; rel="sunset"` (RFC 8594 section 6), pointing at this policy before any Sunset date is set. Nothing is deprecated today.


    Rate limits: every response carries advisory RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, and RateLimit-Policy headers (60 requests per 60-second window per endpoint); a 429 carries Retry-After.


    Errors: every 4xx/5xx body is the ErrorResponse object -- a machine-readable `code`, a human-readable `error`, and an optional `hint`.


    The site also runs a Model Context Protocol server at https://dannykeane.com/mcp (Streamable HTTP, JSON-RPC -- not modeled here; see the server card at /.well-known/mcp/server-card.json), a docs MCP server at https://dannykeane.com/docs/mcp for searching and reading the site''s documents, and publishes llms.txt at https://dannykeane.com/llms.txt.'
  contact:
    name: Danny Keane
    url: https://dannykeane.com/contact
    email: me@dannykeane.co.uk
servers:
- url: https://dannykeane.com
security: []
tags:
- name: Batch
paths:
  /api/v1/batch:
    post:
      operationId: runBatch
      summary: Run several read-only operations in one request
      description: 'Executes up to 10 argument-free GET operations, named by operationId (getStats, getGithubContributions, npcChatHealth), and returns each result with its own status -- one failed item never fails the batch. Optional async mode for clients that don''t want to hold a connection open: send Prefer: respond-async for a 202 and a job to poll at getJob instead. Jobs are stateless -- the id carries the request, the batch runs when you poll, nothing is stored -- and ids expire an hour after creation. In async mode an unknown operationId fails the whole request with a 400.'
      parameters:
      - name: Prefer
        in: header
        required: false
        description: RFC 7240. respond-async returns 202 Accepted with a job to poll instead of the results. Omit for the synchronous 200.
        schema:
          type: string
          enum:
          - respond-async
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                requests:
                  type: array
                  minItems: 1
                  maxItems: 10
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                      operationId:
                        type: string
                        enum:
                        - getStats
                        - getGithubContributions
                        - npcChatHealth
                    required:
                    - operationId
              required:
              - requests
      responses:
        '200':
          description: Per-operation results, in request order
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        operationId:
                          type:
                          - string
                          - 'null'
                        status:
                          type: integer
                        body: {}
                      required:
                      - id
                      - status
                      - body
                required:
                - results
        '202':
          description: 'Prefer: respond-async only. Job accepted; poll Location for the result.'
          headers:
            Location:
              description: The job's status URL, /api/v1/jobs/{id}.
              schema:
                type: string
                format: uri
            Preference-Applied:
              description: 'RFC 7240: confirms respond-async was honoured.'
              schema:
                type: string
                enum:
                - respond-async
            Retry-After:
              description: Seconds to wait before polling.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobAccepted'
        '400':
          description: Invalid body, unknown operationId, or too many operations (in async mode, also a request too large for a job id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Batch
components:
  schemas:
    JobAccepted:
      type: object
      description: 'The 202 body for POST /api/v1/batch with Prefer: respond-async. Nothing has run yet: GET status_url to run the batch and read its result.'
      properties:
        id:
          type: string
          description: 'Job identifier. Stateless: it encodes the request and its creation time, so nothing is stored server-side. Expires an hour after created_at.'
        status:
          type: string
          enum:
          - pending
        status_url:
          type: string
          format: uri
          description: Where to poll -- the same URL as the Location header.
        created_at:
          type: string
          format: date-time
      required:
      - id
      - status
      - status_url
      - created_at
    ErrorResponse:
      type: object
      description: Every 4xx/5xx response body. `code` is stable and machine-readable; `error` is the human-readable message; `hint` says how to fix the request when that is knowable.
      properties:
        code:
          type: string
          enum:
          - invalid_body
          - unknown_event
          - missing_message
          - empty_message
          - message_too_long
          - missing_parameters
          - invalid_parameter
          - rate_limited
          - not_configured
          - upstream_error
          - method_not_allowed
          - not_found
          - internal_error
          - job_expired
        error:
          type: string
        hint:
          type: string
      required:
      - code
      - error
      additionalProperties: true
externalDocs:
  description: 'Danny Keane Developer Docs: API and MCP Server'
  url: https://dannykeane.com/developers