xavio-in Stories API

openapi: 3.2.0
info:
  title: Nafafy Public Stories API
  version: 1.0.0
  description: 'Programmatic access to publish stories, manage products and variants, fulfil orders, run bookings and read analytics on Nafafy.


    - **REST** — `Authorization: Bearer nf_live_…` (or `nf_test_…`) with a key of kind **REST API** minted at https://nafafy.com/dashboard/developer. Each Series F operation names the scope it needs (`x-required-scope`); `x:write` implies `x:read`. `customers:pii` and `refunds:write` are standalone and never implied.

    - **MCP** — https://nafafy.com/api/mcp (JSON-RPC 2.0 over HTTP) needs a key of kind **MCP**; a REST key is refused there, and an MCP key is refused on REST (`wrong_kind`).


    Errors use the envelope `components.schemas.V1Error`; branch on `error.code`. Series F operations list every code they can answer in `x-error-codes` and their limit in `x-rate-limit`.'
  contact:
    name: Nafafy support
    url: https://nafafy.com/developers
servers:
- url: https://nafafy.com
  description: Production
security:
- bearerAuth: []
tags:
- name: Stories
  description: Publish + manage stories.
paths:
  /api/v1/stories:
    post:
      summary: Publish a story (or multi-slide cluster) with optional inline overlays
      tags:
      - Stories
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateStoryRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  story_id:
                    type: string
                    format: uuid
                  story_ids:
                    type: array
                    items:
                      type: string
                      format: uuid
                  post_id:
                    type: string
                    format: uuid
        '401':
          description: Unauthorized
        '402':
          description: Tier upgrade required
        '422':
          description: Validation failed
      operationId: postApiV1Stories
      x-operation-id-source: derived
  /api/v1/stories/{id}:
    get:
      summary: Fetch one story (cluster head)
      tags:
      - Stories
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
      operationId: getApiV1StoriesById
      x-operation-id-source: derived
    patch:
      summary: Update mutable fields (caption, audience, etc)
      tags:
      - Stories
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
      operationId: patchApiV1StoriesById
      x-operation-id-source: derived
    delete:
      summary: Soft-delete the cluster
      tags:
      - Stories
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Deleted
      operationId: deleteApiV1StoriesById
      x-operation-id-source: derived
  /api/v1/stories/{id}/components:
    post:
      summary: Attach an overlay component to an existing story
      tags:
      - Stories
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddComponentRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
        '404':
          description: Story not found / not owned
        '422':
          description: Component config invalid
      operationId: postApiV1StoriesByIdComponents
      x-operation-id-source: derived
  /api/v1/components:
    get:
      summary: Catalog filtered by the caller's tier (auth-gated)
      tags:
      - Stories
      responses:
        '200':
          description: OK
      operationId: getApiV1Components
      x-operation-id-source: derived
components:
  schemas:
    CreateStoryRequest:
      type: object
      properties:
        backgrounds:
          type: array
          items:
            $ref: '#/components/schemas/Background'
          minItems: 1
          description: One or more slides.
        caption:
          type: string
          nullable: true
          description: Cluster-wide caption.
        audience:
          type: string
          enum:
          - public
          - followers
          - sponsored
          - flash
          - past_customers
          - cart_abandoners
          - lead_no_purchase
          - custom_segment
          - list
          description: Audience kind — see /api/v1/public/audiences.
        audience_list_id:
          type: string
          format: uuid
          nullable: true
          description: Required when audience='list'.
        expires_at:
          type: string
          format: date-time
          description: ISO timestamp the stories expire.
        category_id:
          type: string
          format: uuid
          nullable: true
          description: Category id — see /api/v1/public/categories.
        is_showcase:
          type: boolean
          description: Pin as a showcase entry (tier-gated).
        overlays:
          type: array
          items:
            $ref: '#/components/schemas/Overlay'
          description: Optional inline components.
      required:
      - backgrounds
      - audience
    Overlay:
      type: object
      properties:
        type:
          type: string
          description: Component id (see /api/v1/public/components).
        config:
          type: object
          description: Component-specific config blob; shape depends on `type`.
        position:
          type: string
          enum:
          - top
          - center
          - bottom
          - custom
          description: Default landing position.
        z_index:
          type: integer
          description: Stacking order within the slide.
        anchor_slide_idx:
          type: integer
          description: 0-based slide index this overlay anchors to (defaults to 0 = cluster head).
      required:
      - type
      - config
    AddComponentRequest:
      type: object
      properties:
        type:
          type: string
          description: Component id — see /api/v1/public/components.
        config:
          type: object
          description: Component-specific config blob; shape depends on `type`.
        position:
          type: string
          enum:
          - top
          - center
          - bottom
          - custom
        z_index:
          type: integer
      required:
      - type
      - config
    Background:
      type: object
      properties:
        type:
          type: string
          enum:
          - image
          - video
          - audio
          - text
          description: Slide media type.
        media_url:
          type: string
          format: uri
          description: URL to the uploaded media (required for image/video/audio).
        duration_ms:
          type: integer
          minimum: 1000
          maximum: 60000
          description: Slide duration in ms (default 5000).
        caption:
          type: string
          nullable: true
          description: Per-slide caption — overrides the cluster-wide caption.
        source_url:
          type: string
          nullable: true
          description: Optional embed URL (e.g. YouTube) for URL-mode video stories.
        source_provider:
          type: string
          nullable: true
          description: Provider key from @/lib/url-video (paired with source_url).
      required:
      - type
      - media_url
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: nf_live_<32-char> | nf_test_<64-char>