openapi: 3.0.3
info:
  title: Seamline Public API
  version: "1.1"
  description: >
    Public discovery endpoints for Seamline creator hubs.


    Seamline is creator portfolio infrastructure — a public hub at

    seamline.now/@handle listing a creator's projects, bio, and email capture.

    Every hub embeds JSON-LD structured data (ProfilePage + Person + CreativeWork[]).


    **Privacy:** Subscriber emails and lead data are never available through any

    public endpoint. Only creator-authored project descriptions and public hub

    content are accessible.


    Public read-only agent contract. Authenticated account access and delegated writes are unavailable. A
    human creator session is not an agent permission grant. Pre-launch product; signup for early creators does
    not establish public-launch or external service readiness.
  contact:
    email: support@seamline.now
  license:
    name: All rights reserved — VaultSpark Studios LLC
servers:
  - url: https://seamline.now
    description: Production
paths:
  /@{handle}:
    get:
      operationId: getCreatorHub
      summary: Get a creator's public hub
      description: |
        Returns the creator's public portfolio hub — projects, bio, and email
        capture widget. The response HTML includes machine-readable JSON-LD:
        ProfilePage (root), Person (mainEntity), and CreativeWork[] (hasPart).
        Parse the JSON-LD script tag for structured data; do not scrape layout.
      parameters:
        - name: handle
          in: path
          required: true
          description: Creator handle (without the @ prefix)
          schema:
            type: string
            example: janedoe
      responses:
        "200":
          description: Creator hub HTML with embedded JSON-LD structured data
          content:
            text/html:
              schema:
                type: string
        "404":
          description: No creator with this handle
  /@{handle}/llms.txt:
    get:
      operationId: getCreatorHubLlms
      summary: Plain-text summary of a creator hub for AI assistants
      description: |
        Name, bio and public projects from the creator's hub, as Markdown-style
        plain text. Restates only what the public hub shows; never subscriber
        data or audience counts. Cached 1 hour at the edge.
      parameters:
        - name: handle
          in: path
          required: true
          description: Creator handle (without the @ prefix)
          schema:
            type: string
            example: janedoe
      responses:
        "200":
          description: Hub summary
          content:
            text/plain:
              schema:
                type: string
        "404":
          description: No creator with this handle
        "503":
          description: Temporary source failure; no empty summary is substituted.
          headers:
            Retry-After:
              schema:
                type: integer
                example: 60
          content:
            text/plain:
              schema:
                type: string
              example: Temporarily unavailable. Retry after 60 seconds.
  /@{handle}/persona.json:
    get:
      operationId: getCreatorPersona
      summary: Versioned public hub profile for read-only agent discovery
      description: |
        Built from the same published hub view as the page and per-hub llms.txt.
        Includes only creator-visible name, bio and live/coming-soon projects.
        It does not expose private drafts, voice settings, lead identities or
        audience counts. The demo handle is explicitly marked as an example.
        This endpoint is read-only; no agent mutation API is available.
      parameters:
        - name: handle
          in: path
          required: true
          description: Creator handle (without the @ prefix)
          schema:
            type: string
            example: janedoe
      responses:
        "200":
          description: Creator persona JSON
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicProfile"
              examples:
                fictional:
                  summary: Published fictional profile
                  value:
                    schemaVersion: seamline-public-hub/v2
                    availability: published
                    id: https://seamline.now/@demo
                    canonicalUrl: https://seamline.now/@demo
                    updatedAt: "2026-09-26T00:00:00Z"
                    name: Ashwake Worksroom
                    handle: demo
                    bio: >-
                      A serialized dark-fantasy RPG about inheritance, ruin, and dangerous promises made under
                      pressure.
                    projects:
                      - id: https://seamline.now/@demo/ashwake
                        name: Ashwake
                        description: >-
                          A city of oaths and ash. The prologue pack gives subscribers the first factions, the
                          inherited ruin, and one dangerous promise.
                        status: live
                        url: null
                        updatedAt: "2026-09-26T00:00:00Z"
                      - id: https://seamline.now/@demo/midnight-drafts
                        name: Midnight Drafts
                        description: >-
                          A weekly author newsletter. Worldbuilding notes, reading paths, and the parts of the
                          story we haven't shown.
                        status: live
                        url: null
                        updatedAt: "2026-09-18T00:00:00Z"
                    example: true
        "404":
          description: Do not enumerate handles or infer hidden content. Ask the creator for their published URL.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicProfileError"
              example:
                code: not_found
                retryable: false
        "503":
          description: >-
            Respect Retry-After and use bounded retries. Keep the previous result labelled stale; do not
            substitute an empty profile or zero counts.
          headers:
            Retry-After:
              description: Bounded retry delay in seconds
              schema:
                type: integer
                example: 60
            Cache-Control:
              schema:
                type: string
                example: no-store
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicProfileError"
              example:
                code: temporarily_unavailable
                retryable: true
  /sitemap.xml:
    get:
      operationId: listCreators
      summary: List all public creator hubs
      description: |
        XML sitemap enumerating all public creator hub URLs.
        Use to discover creator handles or build a creator index.
      responses:
        "200":
          description: XML sitemap
          content:
            application/xml:
              schema:
                type: string
  /agents.json:
    get:
      operationId: getAgentManifest
      summary: Machine-readable product capability contract
      description: |
        Returns the Seamline agent manifest (schemaVersion 2.0) — full capability
        matrix, pricing tiers, intent types, and agent guidance. Read this before
        building any agent integration against Seamline.
      responses:
        "200":
          description: Agent manifest JSON
          content:
            application/json:
              schema:
                type: object
  /.well-known/llms.txt:
    get:
      operationId: getLlmsGuide
      summary: LLM discovery guide
      description: |
        Plain-text guide for large language models — capability matrix, privacy
        posture, recommended actions, and do-not-do list. Read before answering
        questions about Seamline on behalf of a user.
      responses:
        "200":
          description: LLM-readable plain text guide
          content:
            text/plain:
              schema:
                type: string
  /api/health:
    get:
      operationId: healthCheck
      summary: API health check
      description: Returns OK when the Seamline API is reachable.
      responses:
        "200":
          description: API is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
  /stats.json:
    get:
      operationId: getPublicPlatformStatistics
      summary: Precomputed privacy-banded aggregate with explicit availability
      description: >-
        Read feedVersion, period, freshness and each metric status. Suppressed, stale and unavailable values
        are not zero. No individual subscriber records.
      responses:
        "200":
          description: Measured, suppressed, stale or unavailable aggregate feed; inspect the payload status.
        "503":
          description: Aggregate source unavailable; never substitute zero counts.
components:
  schemas:
    PublicProject:
      type: object
      additionalProperties: false
      required:
        - id
        - name
        - description
        - status
        - url
        - updatedAt
      properties:
        id:
          type: string
          format: uri
        name:
          type: string
        description:
          type: string
          nullable: true
        status:
          type: string
          enum:
            - live
            - coming_soon
        url:
          type: string
          nullable: true
        updatedAt:
          type: string
          format: date-time
    PublicProfile:
      type: object
      additionalProperties: false
      required:
        - schemaVersion
        - availability
        - id
        - canonicalUrl
        - updatedAt
        - name
        - handle
        - bio
        - projects
      properties:
        schemaVersion:
          type: string
          enum:
            - seamline-public-hub/v2
        availability:
          type: string
          enum:
            - published
        id:
          type: string
          format: uri
        canonicalUrl:
          type: string
          format: uri
        updatedAt:
          type: string
          format: date-time
          nullable: true
        name:
          type: string
        handle:
          type: string
        bio:
          type: string
          nullable: true
        projects:
          type: array
          items:
            $ref: "#/components/schemas/PublicProject"
        example:
          type: boolean
          description: True only on the fictional demo.
    PublicProfileError:
      type: object
      additionalProperties: false
      required:
        - code
        - retryable
      properties:
        code:
          type: string
          enum:
            - not_found
            - temporarily_unavailable
        retryable:
          type: boolean
x-seamline-capability-contract: seamline-public-discovery/v1
x-agent-scope: public-read-only