openapi.yaml

openapi: 3.1.0
info:
  title: WREN
  version: 0.1.0
  description: |
    WREN is a self-hosted versioned JSON storage service.
    Every mutation creates a version. Versions can be labeled (e.g. `published`, `draft`).
    All responses are streamed. Security and multi-tenancy are built in.

    **Clean public URLs:** `/orgs/{slug}/...` is a short alias for `/api/v1/orgs/{slug}/...`,
    intended for browser-facing URLs. For example, `/orgs/acme/tree/site/index.html` opens
    directly in a browser without needing to know the `/api/v1` prefix.

    **Caching.** Public read endpoints emit `Cache-Control: public, max-age=60,
    stale-while-revalidate=86400` — browsers and CDNs can serve responses for a minute without
    checking, and may serve stale responses for up to a day while revalidating in the background.
    Tree and raw-asset responses also emit `Vary: Accept` so content-negotiated URLs (the ones
    that can return either JSON metadata or raw bytes) are cached separately per Accept header —
    a JSON probe cannot poison the HTML response for the same URL. WREN dispatches an explicit
    cache purge to its configured CDN backend (default: no-op) after every successful mutation,
    so edits are visible to readers within the freshness window.

    **HEAD requests.** Every `GET` endpoint also responds to `HEAD` with the same status and
    headers and an empty body (per RFC 7231). Useful for probing existence, cache validation, or
    checking `Content-Length` without downloading the payload.

servers:
  - url: http://localhost:4000
    description: Local sandbox

tags:
  - name: auth
    description: Authentication — email/password and OAuth providers (handled by Better Auth)
  - name: documents
    description: Create, read, update and delete JSON documents
  - name: versions
    description: Version history, rollback and time-travel
  - name: labels
    description: Named pointers into version history
  - name: diff
    description: Compare versions
  - name: schemas
    description: JSON Schema enforcement per collection
  - name: query
    description: Filter, project, and aggregate documents — replaces hand-built index docs
  - name: materialized
    description: Named, persisted query results that auto-refresh on write
  - name: assets
    description: Binary asset upload, versioning and download for collections with `collectionType=binary`
  - name: keys
    description: API key management for server-to-server authentication
  - name: org
    description: Read and switch the active org for the current session
  - name: invites
    description: Invite collaborators to share your workspace
  - name: members
    description: Manage members of your org
  - name: projects
    description: Public project directory — lists all orgs with public permissions
  - name: system
    description: Health and metadata
  - name: discovery
    description: LLM and crawler discovery endpoints

paths:
  /api/auth/sign-up/email:
    post:
      summary: Register with email and password
      tags: [auth]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, password, name]
              properties:
                email:
                  type: string
                  format: email
                password:
                  type: string
                name:
                  type: string
      responses:
        "200":
          description: User created and session started
        "422":
          description: Validation error or email already in use

  /api/auth/sign-in/email:
    post:
      summary: Sign in with email and password
      tags: [auth]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, password]
              properties:
                email:
                  type: string
                  format: email
                password:
                  type: string
      responses:
        "200":
          description: Session created
        "401":
          description: Invalid credentials

  /api/auth/sign-out:
    post:
      summary: Sign out and invalidate session
      tags: [auth]
      responses:
        "200":
          description: Session invalidated

  /api/auth/get-session:
    get:
      summary: Get current session and user info
      tags: [auth]
      responses:
        "200":
          description: Current session
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    type: object
                    properties:
                      id:
                        type: string
                      email:
                        type: string
                      name:
                        type: string
                      role:
                        type: string
                      orgId:
                        type: string
                  session:
                    type: object
        "401":
          description: Not authenticated

  /api/auth/sign-in/social:
    post:
      summary: Initiate OAuth sign-in (Google, Apple, GitHub)
      tags: [auth]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [provider, callbackURL]
              properties:
                provider:
                  type: string
                  enum: [google, apple, github]
                callbackURL:
                  type: string
      responses:
        "200":
          description: Redirect URL for OAuth flow

  /login:
    get:
      summary: Login and registration UI
      tags: [auth]
      responses:
        "200":
          description: HTML login/register page
          content:
            text/html:
              schema:
                type: string

  /profile:
    get:
      summary: Get current user's profile
      tags: [auth]
      security:
        - cookieAuth: []
      responses:
        "200":
          description: Authenticated user profile
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    type: object
                    properties:
                      id:
                        type: string
                      email:
                        type: string
                      name:
                        type: string
                      role:
                        type: string
                      orgId:
                        type: string
                        nullable: true
                      emailVerified:
                        type: boolean
        "302":
          description: "Redirect to /login?redirect=/profile (browser requests only)"
        "401":
          description: "Not authenticated (API requests with Accept: application/json)"

  /health:
    get:
      summary: Health check
      tags: [system]
      responses:
        "200":
          description: Service is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok

  /api/v1/collections:
    get:
      summary: List all collections with document counts
      tags: [documents]
      security:
        - cookieAuth: []
      responses:
        "200":
          description: List of collections
          content:
            application/json:
              schema:
                type: object
                properties:
                  collections:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        count:
                          type: integer
                        updatedAt:
                          type: string
                          format: date-time
        "401":
          description: Not authenticated

  /api/v1/{collection}:
    get:
      summary: List documents
      tags: [documents]
      security:
        - cookieAuth: []
      parameters:
        - $ref: "#/components/parameters/collection"
        - name: filter
          in: query
          description: JSON path-based filter expression
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
        - name: cursor
          in: query
          description: Pagination cursor from previous response
          schema:
            type: string
        - name: facets
          in: query
          description: Comma-separated list of fields to facet on
          schema:
            type: string
        - name: label
          in: query
          description: Return documents at the state of this label
          schema:
            type: string
      responses:
        "200":
          description: Paginated list of documents
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DocumentList"

    post:
      summary: Create a document or upload a binary asset
      description: |
        For JSON collections send `Content-Type: application/json`.
        For binary collections (`collectionType=binary`) send `Content-Type: multipart/form-data`
        with a single `file` field containing the binary file.
      tags: [documents, assets]
      security:
        - cookieAuth: []
      parameters:
        - $ref: "#/components/parameters/collection"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file:
                  type: string
                  format: binary
                  description: The binary file to upload
      responses:
        "201":
          description: Document created / asset uploaded
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DocumentResponse"
        "400":
          description: Missing file field (binary upload)
        "422":
          $ref: "#/components/responses/SchemaValidationError"

  /api/v1/{collection}/{id}:
    get:
      summary: Get current state of a document
      tags: [documents]
      security:
        - cookieAuth: []
      parameters:
        - $ref: "#/components/parameters/collection"
        - $ref: "#/components/parameters/id"
        - name: label
          in: query
          description: Return state at this label instead of latest
          schema:
            type: string
      responses:
        "200":
          description: Document found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DocumentResponse"
        "404":
          $ref: "#/components/responses/NotFound"

    put:
      summary: Update a document or replace a binary asset (creates a new version)
      description: |
        For JSON collections send `Content-Type: application/json`.
        For binary collections (`collectionType=binary`) send `Content-Type: multipart/form-data`
        with a single `file` field containing the new binary file.
      tags: [documents, assets]
      security:
        - cookieAuth: []
      parameters:
        - $ref: "#/components/parameters/collection"
        - $ref: "#/components/parameters/id"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file:
                  type: string
                  format: binary
                  description: The new binary file to store as the next version
      responses:
        "200":
          description: Document updated / new asset version stored
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DocumentResponse"
        "400":
          description: Missing file field (binary upload)
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/SchemaValidationError"

    delete:
      summary: Soft delete a document (creates a tombstone version)
      tags: [documents]
      security:
        - cookieAuth: []
      parameters:
        - $ref: "#/components/parameters/collection"
        - $ref: "#/components/parameters/id"
      responses:
        "200":
          description: Document deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  deleted:
                    type: boolean
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v1/{collection}/by-key/{keyValue}:
    get:
      summary: Get a document by its natural key
      description: |
        Fetches a document by its configured natural key value (e.g. a `slug`). The collection
        must have a `naturalKey` field set on its schema, otherwise this endpoint returns `400`.

        The lookup uses a unique index on `(collection, natural_key)`, so it's as fast as a
        by-ID lookup.
      tags: [documents]
      security:
        - cookieAuth: []
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/collection"
        - name: keyValue
          in: path
          required: true
          schema:
            type: string
          description: The natural-key value (URL-encoded if it contains reserved characters)
          example: "about"
        - name: label
          in: query
          description: Return state at this label instead of latest
          schema:
            type: string
      responses:
        "200":
          description: Document found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DocumentResponse"
        "400":
          description: Collection has no `naturalKey` configured
        "404":
          description: No document with that natural key

    put:
      summary: Upsert a document by natural key (create if missing, update if present)
      description: |
        The headline operation. In a single transactional call, either creates a new document
        with the given natural key or updates the existing one. Replaces the
        list-then-find-then-put idiom that every ingestion script otherwise reinvents.

        The request body should be a JSON document. If the body contains a value for the
        natural-key field (e.g. `{"slug": "about", ...}`), it must match `{keyValue}` in the
        URL — otherwise the request is rejected with `400` to surface the client-side bug
        where the URL and the content disagree. If the body omits the key field, the server
        fills it in automatically from the URL so the stored doc stays in sync with its
        addressable identity.

        Returns `201` on insert, `200` on update. The response body contains the document's
        stable UUID `id` (which clients may or may not care about), the current version, and
        the `naturalKey` value used.

        Requires `write` access to `collection:{collection}`. Schema validation still applies.
      tags: [documents]
      security:
        - cookieAuth: []
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/collection"
        - name: keyValue
          in: path
          required: true
          schema:
            type: string
          example: "about"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: The document data. May include the natural-key field (must match URL) or omit it (server fills it in).
      responses:
        "200":
          description: Existing document updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DocumentResponse"
        "201":
          description: New document created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DocumentResponse"
        "400":
          description: Collection has no `naturalKey` configured, or URL key mismatches body field
        "409":
          description: Unique-key conflict (race under unusual isolation; should not happen in normal use)
        "422":
          $ref: "#/components/responses/SchemaValidationError"

    delete:
      summary: Delete a document by its natural key
      description: |
        Soft-deletes the document whose natural-key value matches `{keyValue}`. The key slot
        is released on delete (the partial unique index excludes soft-deleted rows), so you
        can recreate a document under the same key afterwards.
      tags: [documents]
      security:
        - cookieAuth: []
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/collection"
        - name: keyValue
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Document deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  deleted:
                    type: boolean
        "400":
          description: Collection has no `naturalKey` configured
        "404":
          description: No document with that natural key

  /api/v1/{collection}/{id}/raw:
    get:
      summary: Download the binary content of an asset document
      description: |
        Returns the raw binary data for the latest version of an asset in a `collectionType=binary`
        collection. Pass `?version=N` to retrieve a specific historical version.
        The response `Content-Type` matches the MIME type recorded at upload time.

        An optional filename suffix can be appended to the URL path for better download naming
        in browsers and tools — the server ignores the suffix but the browser uses it:
        ```
        GET /api/v1/images/{id}/raw/photo.jpg
        ```
      tags: [assets]
      security:
        - cookieAuth: []
      parameters:
        - $ref: "#/components/parameters/collection"
        - $ref: "#/components/parameters/id"
        - name: version
          in: query
          required: false
          schema:
            type: integer
          description: Version number to retrieve (defaults to latest)
      responses:
        "200":
          description: Binary file content
          headers:
            Content-Type:
              schema:
                type: string
              description: MIME type recorded at upload time
            Content-Disposition:
              schema:
                type: string
              description: "`inline; filename=\"<original-filename>\"`"
            Cache-Control:
              schema:
                type: string
              description: "`public, max-age=31536000, immutable`"
          content:
            "*/*":
              schema:
                type: string
                format: binary
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v1/{collection}/{id}/paths:
    get:
      summary: List all tree paths this document is assigned to
      tags: [documents]
      security:
        - cookieAuth: []
      parameters:
        - $ref: "#/components/parameters/collection"
        - $ref: "#/components/parameters/id"
      responses:
        "200":
          description: Tree path assignments for this document
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  collection:
                    type: string
                  paths:
                    type: array
                    items:
                      type: object
                      properties:
                        tree:
                          type: string
                          example: main
                        path:
                          type: string
                          example: /site/about
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v1/{collection}/{id}/versions:
    get:
      summary: List version history of a document
      tags: [versions]
      security:
        - cookieAuth: []
      parameters:
        - $ref: "#/components/parameters/collection"
        - $ref: "#/components/parameters/id"
      responses:
        "200":
          description: Version history
          content:
            application/json:
              schema:
                type: object
                properties:
                  collection:
                    type: string
                  id:
                    type: string
                  versions:
                    type: array
                    items:
                      $ref: "#/components/schemas/VersionMeta"

  /api/v1/{collection}/{id}/versions/{version}:
    get:
      summary: Get document state at a specific version
      tags: [versions]
      security:
        - cookieAuth: []
      parameters:
        - $ref: "#/components/parameters/collection"
        - $ref: "#/components/parameters/id"
        - $ref: "#/components/parameters/version"
      responses:
        "200":
          description: Document at specified version
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DocumentResponse"
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v1/{collection}/{id}/rollback/{version}:
    post:
      summary: Rollback document to a previous version (creates a new version)
      description: |
        Copies the data from version `{version}` into a new version at the head of the document.
        The old versions are preserved — rollback is just another write, not a delete.

        **Schema is not enforced on rollback.** If the collection's schema has been tightened
        since the target version was written, the rollback still succeeds — the old data is
        written verbatim as a new version without being run through the validator. The next
        `PUT` on that document, however, must satisfy the current schema. This is intentional
        (rollback is a history replay, not a new edit) but worth knowing before you rely on
        schemas for hard invariants.
      tags: [versions]
      security:
        - cookieAuth: []
      parameters:
        - $ref: "#/components/parameters/collection"
        - $ref: "#/components/parameters/id"
        - $ref: "#/components/parameters/version"
      responses:
        "200":
          description: Rollback successful — a new version is created with the old content
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  version:
                    type: integer
                    description: The new version number created by the rollback
                  rolledBackTo:
                    type: integer
                    description: The source version whose content was restored

  /api/v1/{collection}/{id}/labels:
    post:
      summary: Set a label on the current version
      tags: [labels]
      security:
        - cookieAuth: []
      parameters:
        - $ref: "#/components/parameters/collection"
        - $ref: "#/components/parameters/id"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [label]
              properties:
                label:
                  type: string
                  example: published
                version:
                  type: integer
                  description: Version to label (defaults to current version if omitted)
      responses:
        "200":
          description: Label set
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  label:
                    type: string
                  version:
                    type: integer
                    description: The version the label now points to

  /api/v1/{collection}/{id}/diff:
    get:
      summary: Diff between two versions or labels
      tags: [diff]
      security:
        - cookieAuth: []
      parameters:
        - $ref: "#/components/parameters/collection"
        - $ref: "#/components/parameters/id"
        - name: v1
          in: query
          required: true
          description: Version number
          schema:
            type: integer
        - name: v2
          in: query
          required: true
          description: Version number
          schema:
            type: integer
      responses:
        "200":
          description: Diff result
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  collection:
                    type: string
                  v1:
                    type: integer
                  v2:
                    type: integer
                  diff:
                    type: array
                    items:
                      $ref: "#/components/schemas/DiffEntry"

  /api/v1/{collection}/_schema:
    get:
      summary: Get the JSON Schema, display name rule and collection type
      tags: [schemas]
      security:
        - cookieAuth: []
      parameters:
        - $ref: "#/components/parameters/collection"
      responses:
        "200":
          description: Schema found
          content:
            application/json:
              schema:
                type: object
                properties:
                  collection:
                    type: string
                  collectionType:
                    type: string
                    enum: [json, binary]
                    description: "`json` (default) stores JSON documents; `binary` stores file uploads."
                  schema:
                    type: object
                    nullable: true
                    description: A JSON Schema object. `null` for binary collections.
                  displayName:
                    type: string
                    nullable: true
                    description: |
                      Template for building a human-readable display name from document fields.
                      Use `{fieldName}` placeholders, e.g. `"{title}"` or `"{first} {last}"`.
                    example: "{title}"
                  listColumns:
                    type: array
                    nullable: true
                    items:
                      type: string
                    description: |
                      Field names to display as extra columns in the Admin UI document list.
                      e.g. `["date", "venue", "status"]`
                    example: ["date", "venue"]
                  naturalKey:
                    type: string
                    nullable: true
                    description: |
                      The top-level field in document data whose value becomes the document's
                      addressable natural key. Enables `/by-key/{value}` lookups and upsert-by-key.
                      Example: `"slug"` — then `PUT /api/v1/pages/by-key/about` upserts the doc
                      whose `data.slug === "about"`.
                    example: "slug"
                  updatedAt:
                    type: string
                    format: date-time
        "404":
          $ref: "#/components/responses/NotFound"

    put:
      summary: Set the JSON Schema, display name rule, list columns and/or collection type
      description: |
        Accepts a wrapper object with optional `schema`, `displayName`, `listColumns` and `collectionType` fields,
        or a raw JSON Schema object (backward-compatible plain form).
        Set `collectionType` to `"binary"` to mark a collection as a binary asset store —
        validation is skipped and uploads use `multipart/form-data`.

        **Existing documents are not re-validated.** Setting or changing a schema only affects
        subsequent writes. Existing documents that no longer match the new schema are
        grandfathered — reads continue to return them as-is, but any `PUT` to one of those
        documents must bring it into compliance or it will be rejected with `422`. Rollback is
        also unvalidated: `POST /api/v1/{collection}/{id}/rollback/{v}` writes a new version
        containing the old data without checking the current schema, so you can roll a document
        back to a pre-schema version even after tightening the rules. There is currently no
        bulk re-validation or migration tool; tighten schemas with care on collections that
        already hold data.
      tags: [schemas]
      security:
        - cookieAuth: []
      parameters:
        - $ref: "#/components/parameters/collection"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - description: "Wrapper form — schema + optional displayName + optional listColumns + optional naturalKey + optional collectionType"
                  type: object
                  properties:
                    schema:
                      type: object
                      description: A valid JSON Schema object (omit for binary collections)
                    displayName:
                      type: string
                      nullable: true
                      description: Display name template, e.g. "{title}" or "{first} {last}"
                      example: "{title}"
                    listColumns:
                      type: array
                      nullable: true
                      items:
                        type: string
                      description: Field names to show as columns in the Admin UI document list
                      example: ["date", "venue"]
                    naturalKey:
                      type: string
                      nullable: true
                      description: |
                        The top-level data field whose value becomes each document's stable
                        addressable identity. Enables the `/by-key/{value}` routes and the
                        upsert-by-key operation. Pass an empty string or omit to disable.
                      example: "slug"
                    collectionType:
                      type: string
                      enum: [json, binary]
                      description: "`json` (default) or `binary`"
                - description: "Plain form — raw JSON Schema (displayName, listColumns, naturalKey, and collectionType unchanged)"
                  type: object
      responses:
        "200":
          description: Schema saved
          content:
            application/json:
              schema:
                type: object
                properties:
                  collection:
                    type: string
                  collectionType:
                    type: string
                    enum: [json, binary]
                  schema:
                    type: object
                    nullable: true
                  displayName:
                    type: string
                    nullable: true
                  listColumns:
                    type: array
                    nullable: true
                    items:
                      type: string
                  naturalKey:
                    type: string
                    nullable: true
        "422":
          description: Invalid JSON Schema

    delete:
      summary: Remove the JSON Schema from a collection
      tags: [schemas]
      security:
        - cookieAuth: []
      parameters:
        - $ref: "#/components/parameters/collection"
      responses:
        "200":
          description: Schema removed
          content:
            application/json:
              schema:
                type: object
                properties:
                  collection:
                    type: string
                  deleted:
                    type: boolean
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v1/{collection}/_schema/validate:
    get:
      summary: Dry-run the current schema against every existing document
      description: |
        Runs the collection's currently-stored JSON Schema against every existing document at
        its current version and reports which documents would fail. This is a read-only
        operation — nothing is mutated, no new version is created, and the stored schema is
        untouched.

        Use `POST` with a request body instead to dry-run a **proposed** schema that is not
        yet set, which is the intended "what happens if I tighten this" safety check before
        calling `PUT /api/v1/{collection}/_schema`.

        Requires `read` access to `collection:{name}`. Schema changes still require `admin`.
      tags: [schemas]
      security:
        - cookieAuth: []
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/collection"
        - name: max
          in: query
          description: Max documents to check (default 10000, capped at 50000)
          schema:
            type: integer
            default: 10000
            minimum: 1
            maximum: 50000
        - name: limit
          in: query
          description: Max failure details to return (default 100, capped at 1000)
          schema:
            type: integer
            default: 100
            minimum: 1
            maximum: 1000
      responses:
        "200":
          description: Validation report
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidateSchemaReport"
        "400":
          description: Binary collection — validation not applicable
        "404":
          description: No schema set on this collection (and no proposed schema provided)

    post:
      summary: Dry-run a proposed schema against every existing document
      description: |
        Same as `GET /api/v1/{collection}/_schema/validate`, but validates against a
        **proposed** schema supplied in the request body instead of the currently-stored
        one. Use this to answer "what breaks if I set this schema?" before actually
        calling `PUT /api/v1/{collection}/_schema`.

        Nothing is mutated. The stored schema is not touched, no new document version is
        created, and the request does not count as a schema change.

        The body may be either a wrapper (`{"schema": {...}}`) matching `handleSetSchema`'s
        format or a plain JSON Schema object. If the body is omitted or empty, the endpoint
        behaves exactly like the `GET` variant and uses the currently-stored schema.
      tags: [schemas]
      security:
        - cookieAuth: []
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/collection"
        - name: max
          in: query
          schema:
            type: integer
            default: 10000
            minimum: 1
            maximum: 50000
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
            minimum: 1
            maximum: 1000
      requestBody:
        required: false
        content:
          application/json:
            schema:
              oneOf:
                - description: Wrapper form — proposed schema under `schema`
                  type: object
                  properties:
                    schema:
                      type: object
                      description: A valid JSON Schema object to dry-run
                - description: Plain form — the body itself is the JSON Schema
                  type: object
      responses:
        "200":
          description: Validation report
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidateSchemaReport"
        "400":
          description: Binary collection — validation not applicable
        "422":
          description: The proposed schema is not a valid JSON Schema

  /api/v1/{collection}/_query:
    get:
      summary: Query documents (cacheable GET form)
      description: |
        GET form of the query endpoint — CDN and browser cacheable. Two modes:

        - **Individual params:** `?select=a,b&where=x:y&limit=10` for simple projection + filter.
        - **Encoded JSON:** `?q=<base64url-encoded JSON>` for complex queries including aggregation.

        The anonymous org-scoped variant (`/api/v1/orgs/{slug}/{collection}/_query`) works
        identically when a `principal='*'` read rule exists on the collection.
      tags: [query]
      security:
        - bearerAuth: []
        - cookieAuth: []
      parameters:
        - $ref: "#/components/parameters/collection"
        - name: select
          in: query
          schema:
            type: string
          description: Comma-separated field paths for projection
        - name: where
          in: query
          schema:
            type: string
          description: Filter expression (e.g. "category:news")
        - name: q
          in: query
          schema:
            type: string
          description: Full query body as base64url-encoded JSON (for aggregation)
        - name: label
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
        - name: cursor
          in: query
          schema:
            type: string
      responses:
        "200":
          description: Query results
    post:
      summary: Query documents with filter, projection, and aggregation
      description: |
        POST form of the query endpoint. Supports the full query body including aggregation.
        Not CDN-cacheable (use GET for cacheable queries).

        The anonymous org-scoped variant (`/api/v1/orgs/{slug}/{collection}/_query`) works
        identically when a `principal='*'` read rule exists on the collection.
      tags: [query]
      security:
        - bearerAuth: []
        - cookieAuth: []
      parameters:
        - $ref: "#/components/parameters/collection"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                where:
                  type: string
                  description: Filter expression (e.g. "category:news", "count>5")
                select:
                  type: array
                  items:
                    type: string
                  description: Field paths to return (projection)
                aggregate:
                  type: object
                  properties:
                    groupBy:
                      type: array
                      items:
                        type: string
                      description: Group by field paths or $documentId, $path, $collection
                    metrics:
                      type: object
                      additionalProperties:
                        type: object
                        description: "Metric definition: { count|countDistinct|sum|min|max|avg: 'path' }"
                label:
                  type: string
                  description: Read at this label version
                limit:
                  type: integer
                  default: 100
                  maximum: 1000
                cursor:
                  type: string
                  description: Pagination cursor from previous response
      responses:
        "200":
          description: Query results (items for projection, rows for aggregation)
        "400":
          $ref: "#/components/responses/BadRequest"
        "408":
          description: Query timed out (max 5 seconds)

  /api/v1/{collection}/_materialized:
    get:
      summary: List materialized queries
      tags: [materialized]
      security:
        - bearerAuth: []
        - cookieAuth: []
      parameters:
        - $ref: "#/components/parameters/collection"
      responses:
        "200":
          description: List of materialized queries for this collection

  /api/v1/{collection}/_materialized/{name}:
    get:
      summary: Read materialized query result
      description: Returns the latest result document for this materialized query.
      tags: [materialized]
      security:
        - bearerAuth: []
        - cookieAuth: []
      parameters:
        - $ref: "#/components/parameters/collection"
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Materialized query result
        "404":
          description: Materialized query not found or no result yet
    put:
      summary: Create or update a materialized query
      description: |
        Stores a query definition that auto-refreshes on every write to the source
        collection. The result is stored as a versioned document.
      tags: [materialized]
      security:
        - bearerAuth: []
        - cookieAuth: []
      parameters:
        - $ref: "#/components/parameters/collection"
        - name: name
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [query]
              properties:
                query:
                  type: object
                  description: Query body (same shape as POST /_query)
                refreshOn:
                  type: string
                  enum: [write, manual]
                  default: write
      responses:
        "200":
          description: Materialized query saved and initial refresh triggered
    delete:
      summary: Delete a materialized query
      tags: [materialized]
      security:
        - bearerAuth: []
        - cookieAuth: []
      parameters:
        - $ref: "#/components/parameters/collection"
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Deleted
        "404":
          description: Not found

  /api/v1/tree:
    get:
      summary: List all named trees for this tenant
      tags: [documents]
      security:
        - cookieAuth: []
      responses:
        "200":
          description: List of trees
          content:
            application/json:
              schema:
                type: object
                properties:
                  trees:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        count:
                          type: integer

  /api/v1/tree/{treeName}:
    get:
      summary: Get full tree — all paths with their assigned documents
      description: |
        When `full=true` is passed, returns every path in the named tree together with
        the assigned document's current data. Useful for rendering a site map or diff
        between two environments. Without `full=true` this endpoint is not used (path
        traversal goes through `/api/v1/tree/{treeName}/{path}`).
      tags: [documents]
      security:
        - cookieAuth: []
      parameters:
        - name: treeName
          in: path
          required: true
          schema:
            type: string
          example: main
        - name: full
          in: query
          required: true
          schema:
            type: string
            enum: ["true"]
          description: Must be "true" to retrieve the full tree snapshot
      responses:
        "200":
          description: Full tree snapshot
          content:
            application/json:
              schema:
                type: object
                properties:
                  tree:
                    type: string
                    example: main
                  nodes:
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          example: /site/en/about
                        documentId:
                          type: string
                        document:
                          type: object
                          properties:
                            id:
                              type: string
                            collection:
                              type: string
                            version:
                              type: integer
                            data:
                              type: object
        "401":
          description: Unauthorized

  /api/v1/tree/{treeName}/{path}:
    get:
      summary: Get document at path and list immediate children in a named tree
      description: |
        Returns the document assigned at `path` and its immediate children.
        Supports content negotiation for binary assets: when the resolved document is a binary
        asset (`_binary: true`), the default response is the raw file bytes with the stored
        `Content-Type` — matching what browsers expect for `<script>`, `<link>`, `<img>`, and
        ESM imports. To get the JSON metadata envelope instead, send `Accept: application/json`
        explicitly.
      tags: [documents]
      security:
        - cookieAuth: []
      parameters:
        - name: treeName
          in: path
          required: true
          schema:
            type: string
          example: main
        - name: path
          in: path
          required: true
          schema:
            type: string
          example: /site/en/about
        - name: label
          in: query
          required: false
          schema:
            type: string
          description: |
            Return the document at the version pinned to this label instead of the
            current version. When a permission rule has a `labelFilter`, it is applied
            automatically — this parameter overrides it for authenticated callers.
            Useful for preview/published workflows: deploy new versions, label them
            "preview", then promote to "published" when ready.
          example: published
      responses:
        "200":
          description: Node found
          content:
            application/json:
              schema:
                type: object
                properties:
                  path:
                    type: string
                  document:
                    nullable: true
                    allOf:
                      - $ref: "#/components/schemas/DocumentResponse"
                  pathExists:
                    type: boolean
                    description: Whether this path has an explicit entry in the tree (true for both folders and document assignments)
                  assignmentDocId:
                    type: string
                    nullable: true
                    description: ID of the _paths document tracking assignment history for this path
                  children:
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                        documentId:
                          type: string
        "404":
          $ref: "#/components/responses/NotFound"

    put:
      summary: Assign a document to a tree path, or create an empty folder
      description: |
        If `documentId` is provided, assigns that document to the path.
        If `documentId` is omitted or null, creates an empty folder (a path entry with no
        document). Empty folders appear in the tree browser and can have children assigned
        to them later.

        **First-write hint.** When this call creates a path in a tree that didn't exist before,
        the response includes a one-off `hint` object explaining whether the tree is publicly
        readable. If no `principal='*'` read rule covers the tree, the hint includes a copy-pastable
        permission rule to make it public. Subsequent PUTs against the same tree do not include
        the hint.

        **Cache invalidation.** Any successful PUT on a tree path triggers a cache purge for
        every public URL that could reference the path (the path itself, the short alias,
        ancestors, and `?full=true` bundles of the tree). The purge is dispatched to whatever
        CDN backend is configured via `CACHE_PURGE_BACKEND` (default: no-op; see tutorial).
      tags: [documents]
      security:
        - cookieAuth: []
      parameters:
        - name: treeName
          in: path
          required: true
          schema:
            type: string
        - name: path
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                documentId:
                  type: string
                  nullable: true
                  description: Document ID to assign. Omit to create an empty folder.
      responses:
        "200":
          description: Path assigned or folder created
          content:
            application/json:
              schema:
                type: object
                properties:
                  tree:
                    type: string
                  path:
                    type: string
                  documentId:
                    type: string
                    nullable: true
                  hint:
                    type: object
                    description: |
                      Included only on the first PUT that creates a new tree. Tells the caller
                      that the tree is not publicly readable by default and provides a ready-to-run
                      permission rule. Omitted on subsequent PUTs against an existing tree.
                    properties:
                      created_tree:
                        type: string
                        description: Name of the tree that was just created.
                      message:
                        type: string
                        description: Human-readable explanation of the tree's current read state.
                      public_read_example:
                        type: object
                        nullable: true
                        description: |
                          A copy-pastable example of a permission rule that would make the tree
                          publicly readable. Null if a covering rule already exists.
                        properties:
                          method:
                            type: string
                            example: POST
                          url:
                            type: string
                            example: /api/v1/permissions
                          body:
                            type: object
                            properties:
                              principal:
                                type: string
                                example: "*"
                              resource:
                                type: string
                                example: "tree:events"
                              access:
                                type: string
                                example: "read"
        "404":
          description: Document not found

    delete:
      summary: Remove a document from a tree path (does not delete the document)
      tags: [documents]
      security:
        - cookieAuth: []
      parameters:
        - name: treeName
          in: path
          required: true
          schema:
            type: string
        - name: path
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Path removed
          content:
            application/json:
              schema:
                type: object
                properties:
                  path:
                    type: string
                  removed:
                    type: boolean
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v1/keys:
    get:
      summary: List API keys
      description: Returns all API keys for the authenticated user. Key values are never returned — only the prefix for identification.
      tags: [keys]
      security:
        - cookieAuth: []
        - bearerAuth: []
      responses:
        "200":
          description: List of API keys
          content:
            application/json:
              schema:
                type: object
                properties:
                  keys:
                    type: array
                    items:
                      $ref: "#/components/schemas/ApiKey"
        "401":
          $ref: "#/components/responses/Unauthorized"
    post:
      summary: Create an API key
      description: |
        Creates a new API key. The full key value is returned **once only** in this response
        and never stored in plaintext. Store it immediately.
      tags: [keys]
      security:
        - cookieAuth: []
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name:
                  type: string
                  description: Human-readable label for this key, e.g. "marketing-site"
      responses:
        "201":
          description: Key created — full key returned once
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiKey"
                  - type: object
                    properties:
                      key:
                        type: string
                        description: The full API key value. Shown once only.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/v1/keys/{keyId}:
    delete:
      summary: Revoke an API key
      description: Marks the key as revoked. Any subsequent requests using this key will receive 401.
      tags: [keys]
      security:
        - cookieAuth: []
        - bearerAuth: []
      parameters:
        - name: keyId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Key revoked
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  revoked:
                    type: boolean
        "404":
          $ref: "#/components/responses/NotFound"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/v1/projects:
    get:
      summary: List public projects
      description: |
        Public, no authentication required. Returns every org that has at least one
        `principal='*'` permission rule. For each tree, includes an `entryUrl` if the
        tree has an `/index.html` path, indicating it serves a browsable site or app.
        A human-friendly HTML view is available at `/projects`.
      tags: [projects]
      security: []
      responses:
        "200":
          description: List of public projects
          content:
            application/json:
              schema:
                type: object
                properties:
                  projects:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          description: Org owner's display name
                        slug:
                          type: string
                          description: Org URL slug
                        url:
                          type: string
                          format: uri
                          description: Base URL for this org's public API
                        collections:
                          type: array
                          items:
                            type: object
                            properties:
                              name:
                                type: string
                              access:
                                type: string
                              labelFilter:
                                type: string
                                nullable: true
                              url:
                                type: string
                                format: uri
                        trees:
                          type: array
                          items:
                            type: object
                            properties:
                              name:
                                type: string
                              url:
                                type: string
                                format: uri
                                description: Full tree snapshot URL
                              entryUrl:
                                type: string
                                format: uri
                                nullable: true
                                description: URL to /index.html if the tree serves a browsable site, null otherwise

  /api/v1/me:
    get:
      summary: Identity & scope of the calling principal
      description: |
        Returns the calling principal, the org this request is scoped to, the role of
        the calling user in that org, and the permission rules that apply to this
        principal. Designed as a self-check endpoint for agents and clients holding
        an API key — call this once on startup to confirm you are authenticated,
        understand your scope, and avoid 403-by-surprise on downstream requests.

        Works with both Bearer API keys and browser session cookies. The response
        shape is identical; only `authMethod`, `apiKey`, and `principal` differ.
      tags: [auth]
      security:
        - bearerAuth: []
        - cookieAuth: []
      responses:
        "200":
          description: Principal, org, role, and applicable permission rules
          content:
            application/json:
              schema:
                type: object
                properties:
                  principal:
                    type: string
                    description: Permission-rule principal for this caller
                    example: "key:a3f4e5d2"
                  authMethod:
                    type: string
                    enum: [api_key, session]
                  user:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      email:
                        type: string
                        format: email
                  org:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      slug:
                        type: string
                        nullable: true
                        example: "swift-river-peak"
                      role:
                        type: string
                        description: |
                          Single source of truth for the caller's access in this org.
                          `owner` — the caller's personal workspace or an org they own.
                          `admin` / `member` / other — role from org_members.
                          `none` — authenticated but not a member (rare).
                        example: "owner"
                  apiKey:
                    type: object
                    nullable: true
                    description: Present only when authMethod is "api_key"
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      prefix:
                        type: string
                        example: "wren_a3f4e5"
                      lastUsedAt:
                        type: string
                        format: date-time
                        nullable: true
                  permissions:
                    type: array
                    description: |
                      Permission rules that apply to this principal, including public
                      (`principal: "*"`) rules. Agents can use this to check what they
                      can access before making a request.
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        principal:
                          type: string
                        resource:
                          type: string
                        access:
                          type: string
                        labelFilter:
                          type: string
                          nullable: true
                        filterLang:
                          type: string
                          nullable: true
                        filterExpr:
                          type: string
                          nullable: true
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/v1/org:
    get:
      summary: Get active org
      description: |
        Returns the org the current session is scoped to, plus all orgs accessible to the user.
        The active org determines which tenant schema is used for all data operations.
        API key requests always use the key owner's own org — switching requires a browser session.
      tags: [org]
      security:
        - cookieAuth: []
        - bearerAuth: []
      responses:
        "200":
          description: Active org and available orgs
          content:
            application/json:
              schema:
                type: object
                properties:
                  current:
                    type: string
                    description: The org_id (owner's userId) currently active for this session
                  orgs:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        email:
                          type: string
                          format: email
                        own:
                          type: boolean
                          description: True if this is the user's own org
                        slug:
                          type: string
                          example: "swift-river-peak"
        "401":
          $ref: "#/components/responses/Unauthorized"
    put:
      summary: Switch active org
      description: |
        Sets the active org for the current browser session. Only valid for cookie-based sessions —
        API key requests cannot switch orgs. The user must be the owner or a member of the target org.
      tags: [org]
      security:
        - cookieAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [orgId]
              properties:
                orgId:
                  type: string
      responses:
        "200":
          description: Org switched
          content:
            application/json:
              schema:
                type: object
                properties:
                  current:
                    type: string
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: Not a member of that org

  /api/v1/org/slug:
    put:
      summary: Set org slug
      description: |
        Set a custom URL slug for the authenticated user's own organisation. Only the org owner
        can change their slug. Slugs must be 3–40 characters: lowercase alphanumeric and hyphens,
        no leading/trailing hyphens.
      tags: [org]
      security:
        - bearerAuth: []
        - cookieAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [slug]
              properties:
                slug:
                  type: string
                  pattern: "^[a-z0-9][a-z0-9-]{1,38}[a-z0-9]$"
                  example: "swift-river-peak"
      responses:
        "200":
          description: Slug updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  slug:
                    type: string
        "400":
          description: Invalid slug format
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: Not own org
        "409":
          description: Slug already taken

  /api/v1/org/usage:
    get:
      summary: Get org usage
      description: |
        Returns disk usage and request read/write counts for the authenticated user's active org.

        - **disk.bytes** — total size of all tenant schema tables, from `pg_relation_size()`. Cached for 5 minutes.
        - **requests.last30Days** — aggregate reads and writes over the last 30 days.
        - **requests.daily** — per-day breakdown, most recent first. Includes today's in-memory (not-yet-flushed) counts.

        Request counters are accumulated in memory and flushed to the database hourly.
      tags: [org]
      security:
        - bearerAuth: []
        - cookieAuth: []
      responses:
        "200":
          description: Org usage statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  disk:
                    type: object
                    properties:
                      bytes:
                        type: integer
                        description: Total storage used by all tenant tables, in bytes
                  requests:
                    type: object
                    properties:
                      last30Days:
                        type: object
                        properties:
                          reads:
                            type: integer
                          writes:
                            type: integer
                      daily:
                        type: array
                        items:
                          type: object
                          properties:
                            date:
                              type: string
                              format: date
                            reads:
                              type: integer
                            writes:
                              type: integer
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/v1/invites:
    get:
      summary: List invites
      description: Returns all invites sent from the authenticated user's org.
      tags: [invites]
      security:
        - cookieAuth: []
        - bearerAuth: []
      responses:
        "200":
          description: List of invites
          content:
            application/json:
              schema:
                type: object
                properties:
                  invites:
                    type: array
                    items:
                      $ref: "#/components/schemas/Invite"
        "401":
          $ref: "#/components/responses/Unauthorized"
    post:
      summary: Create an invite
      description: |
        Creates a new invite for the given email address. The full invite token is returned
        **once only** and never stored in plaintext. Use it to construct the accept link:
        `{base}/admin#/invites/accept?token={token}`
      tags: [invites]
      security:
        - cookieAuth: []
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email]
              properties:
                email:
                  type: string
                  format: email
                role:
                  type: string
                  default: member
      responses:
        "201":
          description: Invite created — token returned once
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Invite"
                  - type: object
                    properties:
                      token:
                        type: string
                        description: The full invite token. Shown once only.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/v1/invites/received:
    get:
      summary: List received invites
      description: Returns all invites sent to the authenticated user's email address.
      tags: [invites]
      security:
        - cookieAuth: []
        - bearerAuth: []
      responses:
        "200":
          description: List of received invites
          content:
            application/json:
              schema:
                type: object
                properties:
                  invites:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        orgId:
                          type: string
                        orgName:
                          type: string
                        orgEmail:
                          type: string
                          format: email
                        role:
                          type: string
                        createdAt:
                          type: string
                          format: date-time
                        expiresAt:
                          type: string
                          format: date-time
                        acceptedAt:
                          type: string
                          format: date-time
                          nullable: true
                        revokedAt:
                          type: string
                          format: date-time
                          nullable: true
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/v1/invites/{inviteId}/accept:
    post:
      summary: Accept a received invite by ID
      description: |
        Accepts an invite using only the invite ID. No token required — the server verifies
        that the authenticated user's email matches the invite. Useful when the user is already
        logged in and can see their received invites via `GET /api/v1/invites/received`.
      tags: [invites]
      security:
        - cookieAuth: []
        - bearerAuth: []
      parameters:
        - name: inviteId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Invite accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  accepted:
                    type: boolean
                  orgId:
                    type: string
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: Invite is for a different email address
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: Invite already accepted
        "410":
          description: Invite expired or revoked

  /api/v1/invites/accept:
    post:
      summary: Accept an invite
      description: |
        Accepts an invite using the raw token. The authenticated user is added to the
        org as a member. Requires the user to be signed in first.
      tags: [invites]
      security:
        - cookieAuth: []
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [token]
              properties:
                token:
                  type: string
      responses:
        "200":
          description: Invite accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  accepted:
                    type: boolean
                  orgId:
                    type: string
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          description: Invalid token
        "409":
          description: Invite already accepted
        "410":
          description: Invite expired or revoked

  /api/v1/invites/{inviteId}:
    delete:
      summary: Revoke an invite
      description: Revokes a pending invite. Has no effect once accepted.
      tags: [invites]
      security:
        - cookieAuth: []
        - bearerAuth: []
      parameters:
        - name: inviteId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Invite revoked
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  revoked:
                    type: boolean
        "404":
          $ref: "#/components/responses/NotFound"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/v1/members:
    get:
      summary: List org members
      description: Returns all members of the authenticated user's org.
      tags: [members]
      security:
        - cookieAuth: []
        - bearerAuth: []
      responses:
        "200":
          description: List of members
          content:
            application/json:
              schema:
                type: object
                properties:
                  members:
                    type: array
                    items:
                      $ref: "#/components/schemas/Member"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/v1/members/{memberId}:
    delete:
      summary: Remove a member
      description: Removes a member from the org. The removed user will revert to their own tenant schema.
      tags: [members]
      security:
        - cookieAuth: []
        - bearerAuth: []
      parameters:
        - name: memberId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Member removed
          content:
            application/json:
              schema:
                type: object
                properties:
                  userId:
                    type: string
                  removed:
                    type: boolean
        "404":
          $ref: "#/components/responses/NotFound"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/v1/permissions:
    get:
      summary: List permission rules
      description: Returns all permission rules for the active org. Only the org owner can call this.
      tags: [permissions]
      security:
        - cookieAuth: []
        - bearerAuth: []
      responses:
        "200":
          description: Permission list
          content:
            application/json:
              schema:
                type: object
                properties:
                  permissions:
                    type: array
                    items:
                      $ref: "#/components/schemas/Permission"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
    post:
      summary: Create or upsert a permission rule
      description: |
        Creates a permission rule for a principal on a resource. If a rule for the same
        (principal, resource) pair already exists it is updated in place.
        Only the org owner can call this.
      tags: [permissions]
      security:
        - cookieAuth: []
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [principal, resource, access]
              properties:
                principal:
                  type: string
                  description: "`member:<userId>` or `key:<keyId>`"
                  example: "member:abc123"
                resource:
                  type: string
                  description: "`*` | `collection:<name>` | `collection:*` | `tree:<name>` | `tree:*`"
                  example: "collection:golf-magazine"
                access:
                  type: string
                  enum: [none, read, write, admin]
                labelFilter:
                  type: string
                  nullable: true
                  description: If set, reads are silently scoped to documents carrying this label
                filterLang:
                  type: string
                  nullable: true
                  enum: [jq, jmespath, jsonata]
                  description: Language for the data filter expression
                filterExpr:
                  type: string
                  nullable: true
                  description: Expression applied to document `data` before returning to the principal
                auditReads:
                  type: boolean
                  default: false
                auditWrites:
                  type: boolean
                  default: false
      responses:
        "201":
          description: Permission created/updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Permission"
        "400":
          description: Validation error
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  /api/v1/permissions/{permissionId}:
    put:
      summary: Update a permission rule
      description: Partially updates an existing permission rule. Only the org owner can call this.
      tags: [permissions]
      security:
        - cookieAuth: []
        - bearerAuth: []
      parameters:
        - name: permissionId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                access:
                  type: string
                  enum: [none, read, write, admin]
                labelFilter:
                  type: string
                  nullable: true
                filterLang:
                  type: string
                  nullable: true
                  enum: [jq, jmespath, jsonata]
                filterExpr:
                  type: string
                  nullable: true
                auditReads:
                  type: boolean
                auditWrites:
                  type: boolean
      responses:
        "200":
          description: Updated permission
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Permission"
        "404":
          $ref: "#/components/responses/NotFound"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
    delete:
      summary: Delete a permission rule
      description: Permanently removes a permission rule. Only the org owner can call this.
      tags: [permissions]
      security:
        - cookieAuth: []
        - bearerAuth: []
      parameters:
        - name: permissionId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Permission deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  deleted:
                    type: boolean
        "404":
          $ref: "#/components/responses/NotFound"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  /api/v1/orgs/{slug}/tree/{treeName}:
    get:
      summary: Get a public tree node (with content negotiation)
      description: |
        Returns the tree node at the root of `treeName`, or at a specific path when the path
        is appended to the URL (e.g. `/api/v1/orgs/{slug}/tree/{treeName}/sports/tennis`).
        Access is gated by a `principal='*'` read rule on `tree:{treeName}`. No authentication
        required. Append `?full=true` to return the entire subtree as a nested object.

        **Content negotiation for binary assets:** when the resolved document is a binary asset
        (`_binary: true`), the default response is the raw file bytes with the stored
        `Content-Type`. This means `<script src="…">`, `<link href="…">`, `<img src="…">`,
        ESM `import`, `curl`, and `fetch()` all work out of the box — no special headers needed.

        To get the JSON metadata envelope instead, send `Accept: application/json` explicitly.
      tags: [trees]
      security: {}
      parameters:
        - name: slug
          in: path
          required: true
          schema: { type: string }
          description: Org slug
        - name: treeName
          in: path
          required: true
          schema: { type: string }
          description: Tree name
        - name: full
          in: query
          schema: { type: boolean }
          description: Return the entire subtree instead of a single node
        - name: label
          in: query
          schema: { type: string }
          description: Filter by label (only applies when `?full=true`)
      responses:
        "200":
          description: Tree node, subtree, or raw binary asset (content-negotiated)
          content:
            application/json:
              schema:
                type: object
            "*/*":
              schema:
                type: string
                format: binary
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Org slug or tree path not found

  /api/v1/orgs/{slug}/{collection}:
    get:
      summary: List public documents in a collection
      description: |
        Lists documents in a collection that is publicly accessible (has a `principal='*'` read
        permission rule). No authentication required. Supports `?label=`, `?limit=`, `?cursor=`
        query parameters. Data filters and label filters defined on the permission rule are applied.
      tags: [documents]
      parameters:
        - name: slug
          in: path
          required: true
          schema: { type: string }
          description: Org slug
        - name: collection
          in: path
          required: true
          schema: { type: string }
          description: Collection name
        - name: label
          in: query
          schema: { type: string }
        - name: limit
          in: query
          schema: { type: integer }
        - name: cursor
          in: query
          schema: { type: string }
      responses:
        "200":
          description: Document list
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items: { $ref: "#/components/schemas/Document" }
                  total:
                    type: integer
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Org slug not found

  /api/v1/orgs/{slug}/{collection}/{id}:
    get:
      summary: Get a public document
      description: |
        Returns a single document from a publicly accessible collection. No authentication
        required. Supports `?label=` to fetch a specific labelled version.
      tags: [documents]
      parameters:
        - name: slug
          in: path
          required: true
          schema: { type: string }
        - name: collection
          in: path
          required: true
          schema: { type: string }
        - name: id
          in: path
          required: true
          schema: { type: string }
        - name: label
          in: query
          schema: { type: string }
      responses:
        "200":
          description: Document
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Document" }
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v1/orgs/{slug}/{collection}/{id}/raw:
    get:
      summary: Serve a public binary asset
      description: |
        Streams the raw binary content (image, PDF, etc.) of a document in a binary collection
        that is publicly accessible (has a `principal='*'` read rule). No authentication required.
        Ideal for serving images directly in `<img src="...">` tags. Supports `?version=N`.

        Append the original filename to the URL for reliable naming in browsers, download
        managers, and command-line tools (`curl`, `wget`). The server ignores the suffix:
        ```
        GET /api/v1/orgs/coral-tide-fox/images/{id}/raw/hero-photo.jpg
        ```
      tags: [assets]
      parameters:
        - name: slug
          in: path
          required: true
          schema: { type: string }
        - name: collection
          in: path
          required: true
          schema: { type: string }
        - name: id
          in: path
          required: true
          schema: { type: string }
        - name: version
          in: query
          schema: { type: integer }
          description: Specific version to serve (defaults to current version)
      responses:
        "200":
          description: Raw binary content
          content:
            "*/*":
              schema:
                type: string
                format: binary
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

  /.well-known/llms.txt:
    get:
      summary: Instance owner public data context (llms.txt)
      description: |
        Returns the public data context for the instance owner's organisation (the
        earliest-registered user). Follows the well-known URI convention (RFC 8615).
        Same format as /api/v1/orgs/{slug}/llms.txt.
      tags: [discovery]
      responses:
        "200":
          description: Plain-text Markdown data context
          content:
            text/plain:
              schema:
                type: string

  /api/v1/orgs/{slug}/llms.txt:
    get:
      summary: Org data context (llms.txt) — context-aware
      description: |
        Returns a plain-text Markdown document describing the organisation's collections,
        schemas, labels, sample documents, and tree structure.

        **Context-aware:** authentication is optional.
        - No session / API key → only data covered by `principal='*'` read rules is included
        - Valid session / API key → full context visible to the authenticated caller

        Intended for LLM crawlers (unauthenticated) and AI agents (authenticated).
      tags: [discovery]
      security:
        - {}
        - bearerAuth: []
        - cookieAuth: []
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
          description: Org slug
      responses:
        "200":
          description: Plain-text Markdown data context
          content:
            text/plain:
              schema:
                type: string
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: No access to this org
        "404":
          description: Org slug not found

components:
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: better-auth.session_token
    bearerAuth:
      type: http
      scheme: bearer
      description: "API key issued via POST /api/v1/keys. Format — Authorization: Bearer wren_\u2026"

  parameters:
    collection:
      name: collection
      in: path
      required: true
      schema:
        type: string
      example: pages

    id:
      name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid

    version:
      name: version
      in: path
      required: true
      schema:
        type: integer

  schemas:
    ValidateSchemaReport:
      type: object
      description: |
        Result of a dry-run schema validation. `checked` is how many documents the endpoint
        actually looked at (bounded by `?max=`). `valid` + `invalid` always equals `checked`.
        `failures` contains at most `?limit=` entries; `failuresTruncated` is true when more
        invalid documents existed than could be reported.
      properties:
        collection:
          type: string
        schemaSource:
          type: string
          enum: [current, proposed]
          description: Whether validation ran against the stored schema or one from the request body.
        checked:
          type: integer
          description: Number of documents actually examined.
        limitReached:
          type: boolean
          description: True if the collection has more documents than `?max=` — re-run with a larger max to check the rest.
        valid:
          type: integer
          description: Number of documents that passed validation.
        invalid:
          type: integer
          description: Number of documents that failed validation.
        failures:
          type: array
          description: Details of up to `?limit=` failing documents, starting with the most recently created.
          items:
            type: object
            properties:
              id:
                type: string
              version:
                type: integer
                description: The current version number of the document that failed.
              errors:
                type: array
                description: ajv error messages, one per failing constraint.
                items:
                  type: string
        failuresTruncated:
          type: boolean
          description: True if `invalid > failures.length` — the full list was truncated by `?limit=`.

    Invite:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
          format: email
        role:
          type: string
        createdAt:
          type: string
          format: date-time
        expiresAt:
          type: string
          format: date-time
        acceptedAt:
          type: string
          format: date-time
          nullable: true
        revokedAt:
          type: string
          format: date-time
          nullable: true

    Member:
      type: object
      properties:
        userId:
          type: string
        name:
          type: string
        email:
          type: string
          format: email
        role:
          type: string
        joinedAt:
          type: string
          format: date-time

    ApiKey:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        keyPrefix:
          type: string
          description: First 12 characters of the key for identification, e.g. "wren_a3f4e5d2"
        createdAt:
          type: string
          format: date-time
        lastUsedAt:
          type: string
          format: date-time
          nullable: true
        revokedAt:
          type: string
          format: date-time
          nullable: true

    DocumentResponse:
      type: object
      properties:
        collection:
          type: string
        id:
          type: string
          format: uuid
        version:
          type: integer
        labels:
          type: array
          items:
            type: string
          description: Labels currently pointing at any version of this document
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        data:
          type: object
          description: |
            For JSON collections this is the stored JSON object.
            For binary collections the `data` field is a metadata envelope:
            `{ "_binary": true, "filename": "photo.jpg", "mimeType": "image/jpeg", "size": 123456 }`.
            Fetch the actual bytes via `GET /api/v1/{collection}/{id}/raw`.

    DocumentList:
      type: object
      properties:
        collection:
          type: string
        total:
          type: integer
        cursor:
          type: string
          nullable: true
        facets:
          type: object
          additionalProperties:
            type: array
            items:
              type: object
              properties:
                value:
                  type: string
                count:
                  type: integer
        items:
          type: array
          items:
            $ref: "#/components/schemas/DocumentResponse"

    VersionMeta:
      type: object
      properties:
        version:
          type: integer
        labels:
          type: array
          items:
            type: string
          description: Labels pointing at this version
        createdAt:
          type: string
          format: date-time
        createdBy:
          type: string

    DiffEntry:
      type: object
      properties:
        op:
          type: string
          enum: [add, remove, replace]
        path:
          type: string
          description: JSON pointer to changed field
        value:
          description: New value (for add/replace)
        oldValue:
          description: Previous value (for remove/replace)

    Permission:
      type: object
      properties:
        id:
          type: string
        principal:
          type: string
          description: "`member:<userId>` or `key:<keyId>`"
        resource:
          type: string
          description: "`*` | `collection:<name>` | `collection:*` | `tree:<name>` | `tree:*`"
        access:
          type: string
          enum: [none, read, write, admin]
        labelFilter:
          type: string
          nullable: true
          description: If set, reads are silently scoped to this label
        filterLang:
          type: string
          nullable: true
          enum: [jq, jmespath, jsonata]
        filterExpr:
          type: string
          nullable: true
        auditReads:
          type: boolean
        auditWrites:
          type: boolean
        createdAt:
          type: string
          format: date-time

  responses:
    NotFound:
      description: Document not found
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: Not found

    Forbidden:
      description: Forbidden — insufficient permissions
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: Forbidden

    SchemaValidationError:
      description: Document failed JSON Schema validation
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: Schema validation failed
              details:
                type: array
                items:
                  type: string
                example:
                  - "/title must be string"
                  - "/ must have required property 'title'"