Bo Kendell Contacts API

openapi: 3.2.0
info:
  title: Portfolio Contacts API
  version: 1.0.0
  description: 'Portfolio oRPC + REST API

    ## Versioning and deprecation


    The version is in the URL path (`/api/v1/...`). A breaking change ships as a new path segment (`/api/v2`); anything additive lands in place.


    Nothing is removed silently. When an operation is scheduled for removal its responses start carrying a `Deprecation` header (draft-ietf-httpapi-deprecation-header) on the day the decision takes effect, and an RFC 8594 `Sunset` header once a removal date is committed — always at least 90 days out. Both are declared in `components.headers`, so an agent can watch for them mechanically rather than trusting this paragraph.


    Every 4xx and 5xx body is the `Error` schema: a machine-readable `code`, a human-readable `message`, and a `data` object repeating the code and HTTP status. Input-validation failures additionally carry raw Zod `issues`.'
servers:
- url: https://api.bokendell.com
security:
- cookieAuth: []
tags:
- name: Contacts
paths:
  /api/v1/contacts:
    post:
      operationId: v1.contacts.create
      summary: Create contact submission
      description: Stores a contact-form submission (name, email, subject, message) and notifies the site owner. The optional `website` field is a spam honeypot and must be left empty — any value rejects the request as a bot.
      tags:
      - Contacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                email:
                  type: string
                  format: email
                subject:
                  type: string
                  minLength: 1
                message:
                  type: string
                  minLength: 1
                website:
                  type: string
              required:
              - name
              - email
              - subject
              - message
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  name:
                    type: string
                  email:
                    type: string
                  subject:
                    type: string
                  message:
                    type: string
                  createdAt:
                    type: string
                    format: date-time
                required:
                - id
                - name
                - email
                - subject
                - message
                - createdAt
        '401':
          description: UNAUTHORIZED — 401
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: FORBIDDEN — 403
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: NOT_FOUND — 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: CONFLICT — 409
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: INPUT_VALIDATION_FAILED — 422
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: TOO_MANY_REQUESTS — 429
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      title: Error
      description: Every 4xx and 5xx response body. `code` is the machine-readable discriminator; `message` is human-readable and safe to surface. The HTTP status is on the response itself and repeated at `data.httpStatus`.
      required:
      - code
      - message
      - data
      properties:
        code:
          type: string
          description: Machine-readable error code, e.g. NOT_FOUND. Matches `data.code`.
          examples:
          - NOT_FOUND
          - BAD_REQUEST
          - UNAUTHORIZED
          - INTERNAL_SERVER_ERROR
        message:
          type: string
          description: Human-readable explanation.
        data:
          type: object
          description: Structured detail. Always carries `code` and `httpStatus`; typed errors declared by an operation spread their own fields in alongside.
          required:
          - code
          - httpStatus
          properties:
            code:
              type: string
              description: Repeats the top-level `code`.
            httpStatus:
              type: integer
              description: Repeats the response's HTTP status.
            errorCode:
              type: string
              description: The originating domain error code, when the failure came from a domain service.
            details:
              type:
              - object
              - 'null'
              description: Domain-supplied detail, when present.
            path:
              type: string
              description: Dotted procedure path that failed.
          additionalProperties: true
        issues:
          type: array
          description: Raw Zod issues. Present only on input-validation failures.
          items:
            type: object
            additionalProperties: true
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: better-auth.session_token
      description: Better Auth session cookie