From a60c02576f9a733d8f5a49762f79dd88e2b86b15 Mon Sep 17 00:00:00 2001
From: Ajax Davis <thomasalwyndavis@gmail.com>
Date: Sun, 14 Dec 2025 13:43:51 +1000
Subject: [PATCH] docs: add execution API documentation to /docs page
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Document POST /api/tools/execute/[...slug] endpoint
- Show URL formats (by tool ID and by package/export name)
- Document request body parameters (prompt, parameters)
- List SSE events (chunk, tokens, complete, error)
- Add curl and JavaScript code examples
- Document rate limiting (10 requests/minute per IP)
- Add to sidebar navigation

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 apps/web/src/app/docs/page.tsx | 120 +++++++++++++++++++++++++++++++++
 1 file changed, 120 insertions(+)

diff --git a/apps/web/src/app/docs/page.tsx b/apps/web/src/app/docs/page.tsx
index e6f239b..80ecc2c 100644
--- a/apps/web/src/app/docs/page.tsx
+++ b/apps/web/src/app/docs/page.tsx
@@ -33,6 +33,7 @@ const NAV_SECTIONS = [
       { id: 'api-tools', label: 'GET /api/tools' },
       { id: 'api-tools-search', label: 'GET /api/tools/search' },
       { id: 'api-tool-detail', label: 'GET /api/tools/[id]' },
+      { id: 'api-execute', label: 'POST /api/tools/execute' },
     ],
   },
   {
@@ -682,6 +683,125 @@ const result = streamText({
               </DocSubSection>
             </DocSection>
 
+            <DocSection id="api-execute" title="POST /api/tools/execute/[...slug]">
+              <p className="text-foreground-secondary mb-6">
+                Execute a tool with an AI agent and receive streaming results via Server-Sent Events
+                (SSE). This endpoint allows you to run any TPMJS tool remotely without installing
+                it.
+              </p>
+              <DocSubSection title="URL Formats">
+                <div className="space-y-2 text-foreground-secondary text-sm mb-4">
+                  <p>
+                    <strong className="text-foreground">By tool ID:</strong>{' '}
+                    <code className="text-primary">/api/tools/execute/clx123abc</code>
+                  </p>
+                  <p>
+                    <strong className="text-foreground">By package and export:</strong>{' '}
+                    <code className="text-primary">
+                      /api/tools/execute/@tpmjs/hello/helloWorldTool
+                    </code>
+                  </p>
+                </div>
+              </DocSubSection>
+              <DocSubSection title="Request Body">
+                <ParamTable
+                  params={[
+                    {
+                      name: 'prompt',
+                      type: 'string',
+                      required: true,
+                      description: 'Natural language prompt for the AI agent (max 2000 chars)',
+                    },
+                    {
+                      name: 'parameters',
+                      type: 'object',
+                      required: false,
+                      description: 'Optional tool parameters to pass directly',
+                    },
+                  ]}
+                />
+              </DocSubSection>
+              <DocSubSection title="SSE Events">
+                <div className="space-y-4">
+                  <div className="p-3 border border-border rounded-lg bg-surface">
+                    <code className="text-primary font-mono">chunk</code>
+                    <p className="text-sm text-foreground-secondary mt-1">
+                      Streaming text chunks from the AI agent response
+                    </p>
+                  </div>
+                  <div className="p-3 border border-border rounded-lg bg-surface">
+                    <code className="text-primary font-mono">tokens</code>
+                    <p className="text-sm text-foreground-secondary mt-1">
+                      Token usage updates during execution
+                    </p>
+                  </div>
+                  <div className="p-3 border border-border rounded-lg bg-surface">
+                    <code className="text-primary font-mono">complete</code>
+                    <p className="text-sm text-foreground-secondary mt-1">
+                      Final result with output, token breakdown, and execution time
+                    </p>
+                  </div>
+                  <div className="p-3 border border-border rounded-lg bg-surface">
+                    <code className="text-primary font-mono">error</code>
+                    <p className="text-sm text-foreground-secondary mt-1">
+                      Error message if execution fails
+                    </p>
+                  </div>
+                </div>
+              </DocSubSection>
+              <DocSubSection title="Example Request">
+                <CodeBlock
+                  language="bash"
+                  code={`curl -X POST https://tpmjs.com/api/tools/execute/@tpmjs/hello/helloWorldTool \\
+  -H "Content-Type: application/json" \\
+  -d '{"prompt": "Say hello to the world"}'`}
+                />
+              </DocSubSection>
+              <DocSubSection title="JavaScript Example">
+                <CodeBlock
+                  language="typescript"
+                  code={`const response = await fetch(
+  'https://tpmjs.com/api/tools/execute/@tpmjs/hello/helloWorldTool',
+  {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ prompt: 'Say hello to the world' }),
+  }
+);
+
+const reader = response.body?.getReader();
+const decoder = new TextDecoder();
+
+while (true) {
+  const { done, value } = await reader.read();
+  if (done) break;
+
+  const chunk = decoder.decode(value);
+  const lines = chunk.split('\\n');
+
+  for (const line of lines) {
+    if (line.startsWith('event: ')) {
+      const event = line.slice(7);
+      console.log('Event:', event);
+    }
+    if (line.startsWith('data: ')) {
+      const data = JSON.parse(line.slice(6));
+      console.log('Data:', data);
+    }
+  }
+}`}
+                />
+              </DocSubSection>
+              <DocSubSection title="Rate Limiting">
+                <InfoCard icon="clock" title="Rate Limits">
+                  The execute endpoint is rate limited to 10 requests per minute per IP address.
+                  Rate limit headers are included in the response:
+                  <code className="block mt-2 text-sm">X-RateLimit-Limit: 10</code>
+                  <code className="block text-sm">X-RateLimit-Remaining: 9</code>
+                </InfoCard>
+              </DocSubSection>
+            </DocSection>
+
             {/* ==================== PUBLISHING TOOLS ==================== */}
             <DocSection id="publish-overview" title="Publishing Overview">
               <p className="text-foreground-secondary mb-6">