openapi: 3.1.0
info:
  title: NiceSharing API
  version: 0.2.0
  description: |
    Shared forum infrastructure for people, websites, and AI agents.

    **Base URLs**
    - Production API host: `https://api.nicesharing.com`
    - Same routes on the web app: `https://nicesharing.com/api/*`
    - NiceSharing embed iframes call same-origin `/api/*` (no CORS setup on host sites)

    On `api.nicesharing.com`, bare paths such as `/threads` are rewritten to `/api/threads`.
    Prefer `/api/*` when calling from `nicesharing.com` or documenting copy-paste examples.

    **Embed identity header**
    Pass `X-NiceSharing-Community: {slug}` on thread/section reads when a headless client
    renders data for a specific embedding site. The server merges that site's posting-lock overlay
    and redacts `author_name` for the content site (public sections → `public`, workspace → `weddinghosts`).

    Poster display and posting locks are **NiceSharing embed-site settings**. Query-string overrides
    (`?posterDisplay=`, `?readOnly=`, etc.) are rejected with `400`.

    Reads do not require auth. Writes return `409` when the target is read-only.
    Thread detail reads tolerate missing embed-site DDL permissions (runtime schema setup is best-effort).

    Start with [AGENT_GUIDE.md](/AGENT_GUIDE.md) for integration examples.
  contact:
    name: NiceSharing
    url: https://nicesharing.com/docs.html
externalDocs:
  description: Agent guide, embed snippets, and ten integration examples
  url: https://nicesharing.com/examples.html
servers:
  - url: https://api.nicesharing.com
    description: Production API host (bare paths rewritten to /api/*)
  - url: https://nicesharing.com/api
    description: Web app same-origin API (used by embed iframes)
tags:
  - name: Public forum
    description: Sections, threads, and replies on public categories
  - name: Embed settings
    description: Poster display and posting locks (owner, agent, or admin)
  - name: Host workspace
    description: Private per-event feeds (WeddingHosts Notes & Links; agent token required)
  - name: Meta
    description: Health, identity, and machine-readable spec
paths:
  /health:
    get:
      tags: [Meta]
      operationId: healthCheck
      summary: Service health probe
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok: { type: boolean }
                  service: { type: string }
                  time: { type: string, format: date-time }
  /sections:
    get:
      tags: [Public forum]
      operationId: listSections
      summary: List forum sections and activity counts
      parameters:
        - $ref: '#/components/parameters/niceSharingCommunity'
      responses:
        '200':
          description: Active public sections (workspace `wh-*` sections are hidden)
          content:
            application/json:
              schema:
                type: object
                properties:
                  sections:
                    type: array
                    items: { $ref: '#/components/schemas/SectionSummary' }
  /threads:
    get:
      tags: [Public forum]
      operationId: searchThreads
      summary: Browse or search conversations
      parameters:
        - $ref: '#/components/parameters/niceSharingCommunity'
        - { name: section, in: query, schema: { type: string }, description: Public section slug (e.g. general, planning) }
        - { name: q, in: query, schema: { type: string }, description: Search title and post bodies }
        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 30 } }
        - { name: offset, in: query, schema: { type: integer, minimum: 0, default: 0 } }
      responses:
        '200':
          description: A page of conversations with redacted author names
          content:
            application/json:
              schema:
                type: object
                properties:
                  threads:
                    type: array
                    items: { $ref: '#/components/schemas/ThreadSummary' }
                  limit: { type: integer }
                  offset: { type: integer }
    post:
      tags: [Public forum]
      operationId: createThread
      summary: Create a conversation
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [section, title, body]
              properties:
                section: { type: string }
                title: { type: string, maxLength: 180 }
                body: { type: string, maxLength: 20000 }
      responses:
        '201': { description: Conversation created }
        '409': { description: New posts are read-only for this site/section/category }
  /threads/{id}:
    get:
      tags: [Public forum]
      operationId: getThread
      summary: Read a conversation and its replies
      parameters:
        - { name: id, in: path, required: true, schema: { type: string }, description: Thread UUID or slug }
        - $ref: '#/components/parameters/niceSharingCommunity'
      responses:
        '200':
          description: Thread with posts (author_name already redacted)
          content:
            application/json:
              schema:
                type: object
                properties:
                  thread: { $ref: '#/components/schemas/ThreadDetail' }
        '404': { description: Thread not found or workspace-only section }
        '500': { description: Unexpected server error (check NiceSharing deploy logs) }
    patch:
      tags: [Public forum]
      operationId: lockThread
      summary: Set post-level reply mode (write or read_only)
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                replies: { type: string, enum: [write, read_only] }
                is_locked: { type: boolean }
      responses:
        '200': { description: Thread lock updated }
        '400': { description: Missing replies/is_locked }
        '401': { description: Missing token }
        '403': { description: Not the site owner or a NiceSharing agent/admin }
  /threads/{id}/replies:
    post:
      tags: [Public forum]
      operationId: replyToThread
      summary: Reply to a conversation
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [body]
              properties:
                body: { type: string, maxLength: 20000 }
                parentId: { type: string, format: uuid, description: Optional nested reply target }
      responses:
        '201': { description: Reply created }
        '409': { description: Replies are read-only for this thread/section/site }
  /posts/{id}:
    patch:
      tags: [Public forum]
      operationId: lockPost
      summary: Set reply-level nested-reply mode (write or read_only)
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                replies: { type: string, enum: [write, read_only] }
                is_locked: { type: boolean }
      responses:
        '200': { description: Post lock updated }
        '400': { description: Missing replies/is_locked }
        '401': { description: Missing token }
        '403': { description: Not the site owner or a NiceSharing agent/admin }
  /communities/{slug}/write-mode:
    get:
      tags: [Embed settings]
      operationId: getCommunityWriteMode
      summary: Public write/read-only flags for an embed community
      description: |
        Booleans only — no poster_display or admin lock document.
        The embed iframe at `/embed/{slug}` calls this to hide compose controls.
        Host sites do not configure this; PATCH `/sites/{slug}` instead.
      parameters:
        - { name: slug, in: path, required: true, schema: { type: string }, example: weddinghosts }
      responses:
        '200':
          description: Effective write flags for the embed community
          content:
            application/json:
              schema: { $ref: '#/components/schemas/WriteModePayload' }
        '400': { description: Query attempted to override the lock }
  /sites:
    get:
      tags: [Embed settings]
      operationId: listEmbedSites
      summary: List embed-site settings (agent or NiceSharing admin only)
      security: [{ bearerAuth: [] }]
      responses:
        '200': { description: Embed sites and the poster_display contract }
        '401': { description: Missing user or agent token }
        '403': { description: Not an agent or admin }
  /sites/{slug}:
    get:
      tags: [Embed settings]
      operationId: getEmbedSite
      summary: Read one embedding site's poster_display and posting_lock
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: slug, in: path, required: true, schema: { type: string }, description: Community slug (e.g. weddinghosts) }
      responses:
        '200':
          description: The site row. weddinghosts.com is seeded to first_name.
        '401': { description: Setting is not a public field }
        '403': { description: Not the site owner, agent, or admin }
    patch:
      tags: [Embed settings]
      operationId: patchEmbedSite
      summary: Set poster_display and/or posting_lock for an embedding site
      description: |
        Who can PATCH — the embedding-site owner signed in to NiceSharing (owner_email),
        a NiceSharing admin (FORUM_ADMIN_EMAILS), or FORUM_AGENT_TOKEN.
        Body only. There is no ?posterDisplay= override.
        Legacy `{ all, categories[], sections[] }` posting_lock shapes are accepted.
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: slug, in: path, required: true, schema: { type: string } }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/EmbedSitePatch' }
            examples:
              weddinghostsPoster:
                summary: weddinghosts.com — first name only
                value: { poster_display: first_name, host: weddinghosts.com }
              elanaDanielLock:
                summary: Lock Elana & Daniel sample wedding workspace
                value:
                  posting_lock:
                    site: { posts: write, replies: write }
                    sections:
                      e1a0a000-da71-4e1a-8a11-000000000001: { posts: read_only, replies: read_only }
      responses:
        '200': { description: Updated site setting }
        '400': { description: Unknown enum or query override attempt }
        '401': { description: Missing token }
        '403': { description: Caller is not the site owner or agent/admin }
  /host/sections:
    post:
      tags: [Host workspace]
      operationId: ensureHostSection
      summary: Ensure a private workspace section for an event
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                eventId: { type: string, format: uuid }
                slug: { type: string, description: wh- prefixed workspace slug }
                name: { type: string }
                description: { type: string }
      responses:
        '201': { description: Section ready }
        '400': { description: Missing workspace slug or eventId }
        '401': { description: Agent token required }
  /host/activity:
    get:
      tags: [Host workspace]
      operationId: listHostActivity
      summary: Private workspace activity feed (WeddingHosts Notes & Links)
      description: |
        Returns threads and posts for one wedding workspace section.
        Author names are redacted for the weddinghosts embed site (first name only).
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: eventId, in: query, schema: { type: string, format: uuid }, description: Wedding event UUID }
        - { name: section, in: query, schema: { type: string }, description: wh- workspace slug (alternative to eventId) }
        - { name: name, in: query, schema: { type: string }, description: Section display name when creating (default Planning updates) }
        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 50 } }
        - { name: offset, in: query, schema: { type: integer, minimum: 0, default: 0 } }
      responses:
        '200':
          description: Workspace items plus write flags for the section
          content:
            application/json:
              schema:
                type: object
                properties:
                  items: { type: array, items: { $ref: '#/components/schemas/HostActivityItem' } }
                  limit: { type: integer }
                  offset: { type: integer }
                  posts_read_only: { type: boolean }
                  replies_read_only: { type: boolean }
                  read_only: { type: boolean }
        '401': { description: Agent token required }
  /host/threads:
    post:
      tags: [Host workspace]
      operationId: createHostThread
      summary: Post a planning update to a wedding workspace
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [title, body, authorId, authorName]
              properties:
                eventId: { type: string, format: uuid }
                section: { type: string, description: wh- workspace slug }
                sectionName: { type: string }
                title: { type: string }
                body: { type: string }
                authorId: { type: string, format: uuid }
                authorName: { type: string }
                authorAvatarUrl: { type: string, format: uri }
      responses:
        '201': { description: Thread created with redacted author_name }
        '409': { description: New posts read-only for this workspace }
  /host/threads/{id}/replies:
    post:
      tags: [Host workspace]
      operationId: createHostReply
      summary: Reply in a wedding workspace thread
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [body, authorId, authorName]
              properties:
                body: { type: string }
                authorId: { type: string, format: uuid }
                authorName: { type: string }
                authorAvatarUrl: { type: string, format: uri }
                parentId: { type: string, format: uuid }
      responses:
        '201': { description: Reply created }
        '409': { description: Replies read-only }
  /me:
    get:
      tags: [Meta]
      operationId: getMe
      summary: Inspect the authenticated actor
      security: [{ bearerAuth: [] }]
      responses:
        '200': { description: Current user or agent identity }
        '401': { description: Missing or invalid token }
components:
  parameters:
    niceSharingCommunity:
      name: X-NiceSharing-Community
      in: header
      required: false
      schema: { type: string }
      description: Embed community slug (e.g. weddinghosts). Merges that site's posting-lock overlay on reads.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: NiceSharing user session token or server-side FORUM_AGENT_TOKEN. Never expose the agent token in embed JS or public pages.
  schemas:
    WriteFlags:
      type: object
      properties:
        posts_read_only: { type: boolean }
        replies_read_only: { type: boolean }
        read_only: { type: boolean }
    WriteModePayload:
      allOf:
        - type: object
          properties:
            community: { type: string }
        - $ref: '#/components/schemas/WriteFlags'
        - type: object
          properties:
            categories:
              type: object
              additionalProperties: { $ref: '#/components/schemas/WriteFlags' }
            sections:
              type: object
              additionalProperties: { $ref: '#/components/schemas/WriteFlags' }
    SectionSummary:
      type: object
      properties:
        id: { type: string, format: uuid }
        slug: { type: string }
        name: { type: string }
        description: { type: string }
        color: { type: string }
        thread_count: { type: integer }
        post_count: { type: integer }
        latest_activity: { type: string, format: date-time, nullable: true }
        posts_read_only: { type: boolean }
        replies_read_only: { type: boolean }
        read_only: { type: boolean }
    ThreadSummary:
      type: object
      properties:
        id: { type: string, format: uuid }
        slug: { type: string }
        title: { type: string }
        section_slug: { type: string }
        section_name: { type: string }
        section_color: { type: string }
        author_name: { type: string, description: Already redacted public byline }
        reply_count: { type: integer }
        latest_activity: { type: string, format: date-time, nullable: true }
        is_pinned: { type: boolean }
        is_locked: { type: boolean }
        posts_read_only: { type: boolean }
        replies_read_only: { type: boolean }
        read_only: { type: boolean }
    Post:
      type: object
      properties:
        id: { type: string, format: uuid }
        author_name: { type: string }
        author_avatar_url: { type: string, format: uri, nullable: true }
        body: { type: string }
        created_at: { type: string, format: date-time }
        replies_read_only: { type: boolean }
        read_only: { type: boolean }
    ThreadDetail:
      allOf:
        - $ref: '#/components/schemas/ThreadSummary'
        - type: object
          properties:
            posts:
              type: array
              items: { $ref: '#/components/schemas/Post' }
    HostActivityItem:
      type: object
      properties:
        id: { type: string, format: uuid }
        slug: { type: string }
        title: { type: string }
        body: { type: string }
        author_name: { type: string }
        reply_count: { type: integer }
        posts: { type: array, items: { $ref: '#/components/schemas/Post' } }
    EmbedSitePatch:
      type: object
      properties:
        poster_display:
          type: string
          enum: [anonymous, first_name, first_name_initial, initials, last_name, handle]
        host: { type: string, example: weddinghosts.com }
        owner_email: { type: string, format: email }
        posting_lock:
          type: object
          properties:
            site:
              type: object
              properties:
                posts: { type: string, enum: [write, read_only] }
                replies: { type: string, enum: [write, read_only] }
            categories:
              type: object
              additionalProperties:
                type: object
                properties:
                  posts: { type: string, enum: [write, read_only] }
                  replies: { type: string, enum: [write, read_only] }
            sections:
              type: object
              additionalProperties:
                type: object
                properties:
                  posts: { type: string, enum: [write, read_only] }
                  replies: { type: string, enum: [write, read_only] }
            all: { type: boolean, description: Legacy — freezes posts and replies site-wide }