Beyond the notes.
Now AI can act.

Set up Tiro REST API access in this environment.

  Base URL    :  https://api.tiro.ooo
  Auth        :  Bearer token (API key = id + "." + secret)
  Content     :  application/json

IMPORTANT: You (the AI) cannot create the API key. The user must
generate it themselves and paste it back. Walk them through it.

Steps:
  1. Tell the user to open
     https://platform.tiro.ooo/dashboard/api-keys, create a new key,
     and copy the FULL string — id, dot, and secret together. The
     secret is shown only once. Using only the id portion will fail
     with 401.

  2. When the user pastes the key, store it as an environment
     variable. Never hardcode. Pick the right target:
       · Project-scoped: write to .env.local (or .env) and add it
         to .gitignore.
       · Shell-scoped: append to ~/.zshrc (or ~/.bashrc) so it
         persists across sessions.
     Example:
       export TIRO_API_KEY="<paste-id.secret-here>"

  3. Test the first call (list notes):
       curl https://api.tiro.ooo/v1/external/notes \
         -H "Authorization: Bearer $TIRO_API_KEY" \
         -H "Content-Type: application/json" \
         -w "\n%{http_code}\n"

     Expected response: JSON with `content[]` array of notes,
     each containing `guid`, title, createdAt, status. Pagination
     via `nextCursor`.

If you get 401, check the Bearer string contains the dot separator.
If you get 429, you hit the hourly rate limit — wait before retry.
Show the user the exact error payload — do not retry silently.

Full reference: https://docs.tiro.ooo/fundamentals/api-overview

Install the Tiro CLI in this environment and sign me in.

  Package    :  @theplato/tiro-cli  (Node.js 20+)
  Platforms  :  macOS, Linux, Windows
  Auth       :  OAuth (Authorization Code + PKCE) — opens a browser
                and stores the token in the OS keychain.

Steps:
  1. Install globally with whichever package manager is already in
     use here. For npm, that is:
       npm install -g @theplato/tiro-cli
     (Use pnpm / yarn / bun equivalents if those are the active
     package manager — do not switch tooling. If no lockfile is
     present, default to npm.)

  2. Verify the install:
       tiro --version            # expect 0.3.1 or later

  3. Detect environment:
       · If `$DISPLAY` is set OR `open`/`xdg-open` is available:
         treat as interactive → proceed to OAuth.
       · If `$SSH_TTY` is set, or `$CI` is set, or no display open
         command exists: treat as headless → skip OAuth.

  4. Interactive path — sign in:
       tiro auth login           # opens a browser for OAuth
       tiro auth status          # confirm: shows user + token prefix

  5. Headless path — ask the user for a token instead:
       export TIRO_TOKEN="<paste-token-here>"
     The token is generated by visiting the same login URL in a
     browser-equipped machine and copying the result.

  6. Prove the CLI works:
       tiro notes list --limit 3 --json

     Show me the output. Exit code 0 = success, 4 = auth required
     (go back to step 4 or 5), other = report the JSON error
     envelope verbatim.

Set up a Tiro webhook endpoint to receive note events.

  Method     :  POST with application/json body
  Auth       :  Bearer token in Authorization header
                Tiro sends:  Authorization: Bearer <WEBHOOK_SECRET>
                You compare it against your stored secret using a
                constant-time compare (e.g. crypto.timingSafeEqual).
  Timeout    :  60 seconds per delivery
  Retries    :  Up to 5 with exponential backoff over ~2 hours

IMPORTANT: You (the AI) cannot register the endpoint in the dashboard.
The user must do step 1 themselves and paste the secret back.

Steps:
  1. Tell the user to register their HTTPS endpoint at
     https://platform.tiro.ooo, copy the WEBHOOK_SECRET shown after
     registration, and paste it here. Store it as an env var (use
     .env.local for project scope; never commit):
       export WEBHOOK_SECRET="<paste-here>"

  2. Build an HTTP POST handler that:
       a. Reads the Authorization header.
       b. Strips "Bearer " and constant-time-compares the remainder
          to WEBHOOK_SECRET. Return 401 on mismatch.
       c. Parses the JSON body into { id, type, createdAt, data }.
       d. Routes by `data.resourceType`:
            - Note                (note.created/updated/deleted)
            - NoteSummary         (noteSummary.created)
            - NoteDocument        (noteDocument.created/updated)
            - FolderNoteRelation  (folderNoteRelation.created/deleted)
       e. Tracks event.id in a durable processed-set for idempotency
          (Redis / DB in production; in-memory only for local dev).
          Retries with the same id are EXPECTED — return 200 with
          { status: "duplicate" } on repeat.
       f. Returns 2xx on success, 5xx for transient (will retry),
          4xx for permanent (no retry).

  3. Pick one language (Node / Python / Go / Kotlin+Spring) the user
     is already on, write the receiver code, and show how a
     `note.created` event flows end-to-end.

  4. Test:
       curl -X POST <endpoint> \
         -H "Authorization: Bearer $WEBHOOK_SECRET" \
         -H "Content-Type: application/json" \
         -d '{"id":"evt_test","type":"note.created","createdAt":"2026-05-18T00:00:00Z","data":{"resourceType":"Note","id":"n_1"}}'

     Expect 200 within 60 seconds.

Full reference:
  Events: https://docs.tiro.ooo/webhooks/events/schema
  Best practices: https://docs.tiro.ooo/webhooks/best-practices