openapi: 3.1.0
info:
  title: Ordentus API — extras (sharing, settings, hidden events)
  description: 'Companion to the Ordentus CORE action. Covers share links, user settings and hiding events. Auth: the same personal API token as a bearer token. Core calendar/task/feed operations are at /ordentus-openapi.yaml. Full reference: https://ordent.us/llms-api.txt'
  version: 1.1.0
servers:
- url: https://ordent.us
paths:
  /api/auth/me:
    get:
      operationId: whoami
      summary: Who the token belongs to, and what it can do. CALL THIS FIRST.
      description: 'Returns an `auth` object with the token''s permissions. ALWAYS call before any write: if `auth.can_write` is false the token is READ-ONLY — skip create/update/delete/putStore and tell the user to issue a read/write token in Account Settings → API Access.

        '
      responses:
        '200':
          description: The current user record, including an `auth` object with `can_write` and `scopes`.
  /api/share-links:
    get:
      operationId: listShareLinks
      summary: List the user's read-only calendar share links.
      responses:
        '200':
          description: A list of share links, each with a public `url`.
    post:
      operationId: createShareLink
      summary: Create a public read-only share link for the calendar.
      description: Requires a write-scoped token. Returns the public URL anyone can open to view the chosen calendars.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                label:
                  type: string
                  default: Shared Calendar
                show_event_details:
                  type: boolean
                  default: true
                  description: If false, viewers see busy/free blocks without titles.
                expires_at:
                  type: string
                  description: ISO datetime; omit for a link that never expires.
                feed_ids:
                  type: array
                  items:
                    type: string
                  description: Which calendars to include; omit for all.
      responses:
        '200':
          description: The created share link, including its public `url`.
  /api/share-links/{link_id}:
    patch:
      operationId: updateShareLink
      summary: Update a share link's label, visibility, expiry, or included feeds.
      description: Requires a write-scoped token.
      parameters:
      - name: link_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                label:
                  type: string
                show_event_details:
                  type: boolean
                expires_at:
                  type: string
                feed_ids:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: The updated share link.
    delete:
      operationId: deleteShareLink
      summary: Revoke a share link.
      description: Requires a write-scoped token. The public URL stops working immediately.
      parameters:
      - name: link_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Revoked.
  /api/settings:
    get:
      operationId: listSettings
      summary: List the user's settings (merged with defaults), e.g. timezone.
      responses:
        '200':
          description: A list of {key, value} settings.
  /api/settings/{key}:
    get:
      operationId: getSetting
      summary: Read one setting by key (e.g. timezone).
      parameters:
      - name: key
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The {key, value}. Unknown keys return an empty value.
    put:
      operationId: setSetting
      summary: Set one setting by key.
      description: Requires a write-scoped token. `timezone` is validated as an IANA name.
      parameters:
      - name: key
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - value
              properties:
                value:
                  type: string
      responses:
        '200':
          description: The saved setting.
  /api/blacklist:
    get:
      operationId: listHiddenEvents
      summary: List events the user has hidden (e.g. society spam, league fixtures).
      description: Hiding suppresses an event from the unified view without modifying its source feed.
      responses:
        '200':
          description: A list of hidden-event entries.
    post:
      operationId: hideEvent
      summary: Hide an event by its UID (suppress it from the calendar view).
      description: Requires a write-scoped token. Use this for remote-feed events you can't delete. Returns 409 if already hidden.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - event_uid
              properties:
                event_uid:
                  type: string
                  description: The event's uid (from listEvents).
                feed_id:
                  type: string
                event_summary:
                  type: string
                  description: Optional label so the hidden entry is recognisable.
                hide_from_share:
                  type: boolean
                  default: true
      responses:
        '200':
          description: The created hidden-event entry.
  /api/blacklist/{entry_id}:
    delete:
      operationId: unhideEvent
      summary: Un-hide an event (by hidden-entry id), restoring it to the view.
      description: Requires a write-scoped token.
      parameters:
      - name: entry_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Un-hidden.
  /api/blacklist/check/{event_uid}:
    get:
      operationId: checkHidden
      summary: Check whether an event UID is currently hidden.
      parameters:
      - name: event_uid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '{hidden: bool, entry_id: string|null}'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Your personal API token (Account Settings → API Access), sent as Authorization: Bearer <token>.'
security:
- bearerAuth: []
