ayushrai-site Compare API

openapi: 3.2.0
info:
  title: Ayush Rai public Compare API
  version: 1.0.0
  description: 'Read-only API over the same public content as Ayush Rai''s website. Unverified award metrics are omitted. There is no separate dataset for this API.


    Access: Free and public. No account or API key is needed because every endpoint is read-only over published content. There is no separate test environment or paid tier. Clients may cache responses for five minutes. REST responses grant CORS only to the site''s own origins, so call the REST API from a server, an agent, or the CLI rather than from a browser page on another site. The MCP endpoint and its Server Card allow any origin.


    Rate limits: 60 requests per 60 seconds per client address, counted per server instance. Every response carries RateLimit-Policy and RateLimit headers (draft-ietf-httpapi-ratelimit-headers-11). Over the limit, the API returns 429 with a Retry-After header in seconds and error code rate_limited.


    Errors: every error body is { "error": { "code", "message", "hint", "docs" } }. code is stable; hint says how to fix the request.


    Versioning: Versioned in the URL path. /api/v1 is stable: fields may be added, but none are removed or renamed. Breaking changes ship under a new path such as /api/v2. A replaced version keeps working for at least 90 days; during that window its responses carry Deprecation and Sunset headers and a Link with rel="successor-version", and the dates are listed on /developers. The unversioned /api/search and /api/projects are aliases of v1 and follow the same policy. No version is deprecated today.


    MCP: the same project and search tools are available over Streamable HTTP at POST /api/mcp. Its Server Card is at GET /api/mcp/server-card.'
  contact:
    name: Ayush Rai
    email: ayushrai0211@gmail.com
    url: https://www.ayushrai.site/developers/
servers:
- url: https://www.ayushrai.site
security: []
tags:
- name: Compare
paths:
  /api/v1/compare:
    get:
      operationId: compareProjectsV1
      summary: Compare two to four public projects
      parameters:
      - name: slugs
        in: query
        required: true
        description: Comma-separated slugs, two to four, no duplicates
        schema:
          type: string
      - name: archive
        in: query
        required: false
        description: Pass 1 to include archived projects.
        schema:
          type: string
          enum:
          - '1'
      responses:
        '200':
          description: Projects found, plus slugs that were not
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompareResponse'
        '400':
          description: Invalid query, filter, slug, cursor, or compare list. error.code is one of invalid_query, invalid_slug, invalid_filter, invalid_compare, invalid_cursor.
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '405':
          description: Unsupported HTTP method. error.code is method_not_allowed. REST accepts GET, HEAD, and OPTIONS.
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded. error.code is rate_limited.
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Unexpected server fault, not a problem with the request. error.code is internal_error.
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Compare
components:
  headers:
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: integer
        minimum: 1
    RateLimit:
      description: Remaining quota and seconds until reset, for example "default";r=59;t=60.
      schema:
        type: string
    RateLimitPolicy:
      description: 'Quota policy: "default";q=60;w=60.'
      schema:
        type: string
  schemas:
    CompareResponse:
      type: object
      required:
      - projects
      - missing
      properties:
        projects:
          type: array
          items:
            $ref: '#/components/schemas/PublicProject'
        missing:
          type: array
          items:
            type: string
          description: Requested slugs with no public project
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          - hint
          - docs
          properties:
            code:
              type: string
              enum:
              - invalid_query
              - invalid_slug
              - invalid_filter
              - invalid_compare
              - invalid_cursor
              - not_found
              - route_not_found
              - method_not_allowed
              - rate_limited
              - internal_error
            message:
              type: string
              description: What was wrong with this request
            hint:
              type: string
              description: How to fix the request
            docs:
              type: string
              format: uri
    PublicProject:
      type: object
      required:
      - slug
      - title
      - summary
      - type
      - category
      - status
      - yearStart
      - technologies
      - archive
      - pagePath
      - htmlUrl
      properties:
        slug:
          type: string
        title:
          type: string
        summary:
          type: string
        type:
          type: string
          enum:
          - product
          - project
          - client
          - experiment
          - open-source
        category:
          type: string
          enum:
          - tooling
          - education
          - client
          - studio
          - web
          - personal
          - data
        status:
          type: string
        yearStart:
          type: integer
        yearEnd:
          oneOf:
          - type: integer
          - type: string
            const: present
        technologies:
          type: array
          items:
            type: string
        links:
          type: object
          properties:
            demo:
              type: string
              format: uri
            github:
              type: string
              format: uri
        archive:
          type: boolean
        workPath:
          type: string
          description: On-site case study, when one exists
        pagePath:
          type: string
        htmlUrl:
          type: string
          format: uri
externalDocs:
  description: Developer notes
  url: https://www.ayushrai.site/developers/