docs: add first‑class API Reference to Jan docs (Local + Server)

.github/workflows/jan-astro-docs.yml

@@ -14,6 +14,18 @@ on:
     # Review gh actions docs if you want to further define triggers, paths, etc
     # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on
   workflow_dispatch:
+    inputs:
+      update_cloud_spec:
+        description: 'Update Jan Server API specification'
+        required: false
+        default: 'false'
+        type: choice
+        options:
+          - 'true'
+          - 'false'
+  schedule:
+    # Run daily at 2 AM UTC to sync with Jan Server updates
+    - cron: '0 2 * * *'
 
 jobs:
   deploy:
@@ -56,9 +68,44 @@ jobs:
       - name: Install dependencies
         working-directory: website
         run: bun install
+
+      - name: Update Jan Server API Spec (Scheduled/Manual)
+        if: github.event_name == 'schedule' || (github.event_name == 'workflow_dispatch' && github.event.inputs.update_cloud_spec == 'true')
+        working-directory: website
+        continue-on-error: true
+        run: |
+          echo "📡 Updating Jan Server API specification..."
+          bun run generate:cloud-spec
+
+          # Check if the spec file was updated
+          if git diff --quiet public/openapi/cloud-openapi.json; then
+            echo "✅ No changes to API specification"
+          else
+            echo "📝 API specification updated"
+            # Commit the changes if this is a scheduled run on main branch
+            if [ "${{ github.event_name }}" = "schedule" ] && [ "${{ github.ref }}" = "refs/heads/dev" ]; then
+              git config --local user.email "github-actions[bot]@users.noreply.github.com"
+              git config --local user.name "github-actions[bot]"
+              git add public/openapi/cloud-openapi.json
+              git commit -m "chore: update Jan Server API specification [skip ci]"
+              git push
+            fi
+          fi
+        env:
+          JAN_SERVER_SPEC_URL: ${{ secrets.JAN_SERVER_SPEC_URL || 'https://api.jan.ai/api/swagger/doc.json' }}
+          JAN_SERVER_PROD_URL: ${{ secrets.JAN_SERVER_PROD_URL || 'https://api.jan.ai/v1' }}
       - name: Build website
         working-directory: website
-        run: bun run build
+        run: |
+          # For PR and regular pushes, skip cloud spec generation in prebuild
+          # It will use the existing committed spec or fallback
+          if [ "${{ github.event_name }}" = "pull_request" ] || [ "${{ github.event_name }}" = "push" ]; then
+            echo "Using existing cloud spec for build"
+            export SKIP_CLOUD_SPEC_UPDATE=true
+          fi
+          bun run build
+        env:
+          SKIP_CLOUD_SPEC_UPDATE: ${{ github.event_name == 'pull_request' || github.event_name == 'push' }}
 
       - name: copy redirects and headers
         continue-on-error: true

.github/workflows/update-cloud-api-spec.yml

@@ -0,0 +1,186 @@
+name: Update Cloud API Spec
+
+on:
+  # Manual trigger with options
+  workflow_dispatch:
+    inputs:
+      commit_changes:
+        description: 'Commit changes to repository'
+        required: false
+        default: 'true'
+        type: choice
+        options:
+          - 'true'
+          - 'false'
+      spec_url:
+        description: 'Custom API spec URL (optional)'
+        required: false
+        type: string
+      create_pr:
+        description: 'Create pull request for changes'
+        required: false
+        default: 'false'
+        type: choice
+        options:
+          - 'true'
+          - 'false'
+
+  # Scheduled updates - runs daily at 2 AM UTC
+  schedule:
+    - cron: '0 2 * * *'
+
+  # Can be triggered by repository dispatch (webhook from Jan Server)
+  repository_dispatch:
+    types: [update-api-spec]
+
+jobs:
+  update-spec:
+    name: Update Jan Server API Specification
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        working-directory: website
+        run: bun install
+
+      - name: Configure Git
+        run: |
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+          git config --global user.name "github-actions[bot]"
+
+      - name: Update API Specification
+        id: update_spec
+        working-directory: website
+        run: |
+          # Set custom spec URL if provided
+          if [ -n "${{ github.event.inputs.spec_url }}" ]; then
+            export JAN_SERVER_SPEC_URL="${{ github.event.inputs.spec_url }}"
+            echo "📡 Using custom spec URL: $JAN_SERVER_SPEC_URL"
+          elif [ -n "${{ github.event.client_payload.spec_url }}" ]; then
+            export JAN_SERVER_SPEC_URL="${{ github.event.client_payload.spec_url }}"
+            echo "📡 Using webhook spec URL: $JAN_SERVER_SPEC_URL"
+          else
+            export JAN_SERVER_SPEC_URL="${{ secrets.JAN_SERVER_SPEC_URL || 'https://api.jan.ai/api/swagger/doc.json' }}"
+            echo "📡 Using default spec URL: $JAN_SERVER_SPEC_URL"
+          fi
+
+          # Force update the spec
+          export FORCE_UPDATE=true
+          bun run generate:cloud-spec
+
+          # Check if there are changes
+          if git diff --quiet public/openapi/cloud-openapi.json; then
+            echo "✅ No changes to API specification"
+            echo "has_changes=false" >> $GITHUB_OUTPUT
+          else
+            echo "📝 API specification has been updated"
+            echo "has_changes=true" >> $GITHUB_OUTPUT
+
+            # Get summary of changes
+            echo "### Changes Summary" >> $GITHUB_STEP_SUMMARY
+            echo '```diff' >> $GITHUB_STEP_SUMMARY
+            git diff --stat public/openapi/cloud-openapi.json >> $GITHUB_STEP_SUMMARY
+            echo '```' >> $GITHUB_STEP_SUMMARY
+          fi
+        env:
+          JAN_SERVER_PROD_URL: ${{ secrets.JAN_SERVER_PROD_URL || 'https://api.jan.ai/v1' }}
+          JAN_SERVER_STAGING_URL: ${{ secrets.JAN_SERVER_STAGING_URL || 'https://staging-api.jan.ai/v1' }}
+
+      - name: Create Pull Request
+        if: |
+          steps.update_spec.outputs.has_changes == 'true' &&
+          (github.event.inputs.create_pr == 'true' || github.event_name == 'repository_dispatch')
+        uses: peter-evans/create-pull-request@v5
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          commit-message: "chore: update Jan Server API specification"
+          title: "chore: update Jan Server API specification"
+          body: |
+            ## 🤖 Automated API Spec Update
+
+            This PR updates the Jan Server API specification.
+
+            ### Trigger Information
+            - **Event**: ${{ github.event_name }}
+            - **Triggered by**: ${{ github.actor }}
+            - **Timestamp**: ${{ github.event.head_commit.timestamp || github.event.repository.updated_at }}
+
+            ### What's Changed
+            The OpenAPI specification for Jan Server has been updated with the latest endpoints and schemas.
+
+            ### Review Checklist
+            - [ ] API endpoints are correctly documented
+            - [ ] Authentication requirements are accurate
+            - [ ] Model examples are up to date
+            - [ ] Breaking changes are noted (if any)
+
+            ---
+            *This PR was automatically generated by the API spec update workflow.*
+          branch: update-api-spec-${{ github.run_number }}
+          delete-branch: true
+          labels: |
+            documentation
+            api
+            automated
+
+      - name: Commit and Push Changes
+        if: |
+          steps.update_spec.outputs.has_changes == 'true' &&
+          github.event.inputs.commit_changes != 'false' &&
+          github.event.inputs.create_pr != 'true' &&
+          github.event_name != 'repository_dispatch'
+        run: |
+          cd website
+          git add public/openapi/cloud-openapi.json
+          git commit -m "chore: update Jan Server API specification [skip ci]
+
+          Event: ${{ github.event_name }}
+          Triggered by: ${{ github.actor }}"
+
+          # Only push to dev branch if it's a scheduled run
+          if [ "${{ github.event_name }}" = "schedule" ] && [ "${{ github.ref }}" = "refs/heads/dev" ]; then
+            git push origin HEAD:dev
+            echo "✅ Changes committed to dev branch"
+          elif [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            git push origin HEAD:${{ github.ref_name }}
+            echo "✅ Changes committed to ${{ github.ref_name }} branch"
+          else
+            echo "ℹ️ Changes prepared but not pushed (event: ${{ github.event_name }})"
+          fi
+
+      - name: Send Notification
+        if: steps.update_spec.outputs.has_changes == 'true'
+        continue-on-error: true
+        run: |
+          echo "📬 API specification updated successfully"
+
+          # You can add Slack/Discord notification here if needed
+          # Example webhook call:
+          # curl -X POST ${{ secrets.SLACK_WEBHOOK_URL }} \
+          #   -H 'Content-Type: application/json' \
+          #   -d '{"text": "Jan Server API spec has been updated"}'
+
+      - name: Summary
+        if: always()
+        run: |
+          echo "## Workflow Summary" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "- **Status**: ${{ steps.update_spec.outputs.has_changes == 'true' && '✅ Updated' || '⏭️ No changes' }}" >> $GITHUB_STEP_SUMMARY
+          echo "- **Event**: ${{ github.event_name }}" >> $GITHUB_STEP_SUMMARY
+          echo "- **Branch**: ${{ github.ref_name }}" >> $GITHUB_STEP_SUMMARY
+          echo "- **Commit changes**: ${{ github.event.inputs.commit_changes || 'auto' }}" >> $GITHUB_STEP_SUMMARY
+          echo "- **Create PR**: ${{ github.event.inputs.create_pr || 'false' }}" >> $GITHUB_STEP_SUMMARY

.gitignore

@@ -57,3 +57,4 @@ Cargo.lock
 
 ## test
 test-data
+llm-docs