@browsercash/chase 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (24) hide show
  1. package/.claude/settings.local.json +14 -0
  2. package/.dockerignore +34 -0
  3. package/README.md +256 -0
  4. package/api-1 (3).json +831 -0
  5. package/dist/browser-cash.js +128 -0
  6. package/dist/claude-runner.js +285 -0
  7. package/dist/cli-install.js +104 -0
  8. package/dist/cli.js +503 -0
  9. package/dist/codegen/bash-generator.js +104 -0
  10. package/dist/config.js +112 -0
  11. package/dist/errors/error-classifier.js +351 -0
  12. package/dist/hooks/capture-hook.js +57 -0
  13. package/dist/index.js +180 -0
  14. package/dist/iterative-tester.js +407 -0
  15. package/dist/logger/command-log.js +38 -0
  16. package/dist/prompts/agentic-prompt.js +78 -0
  17. package/dist/prompts/fix-prompt.js +477 -0
  18. package/dist/prompts/helpers.js +214 -0
  19. package/dist/prompts/system-prompt.js +282 -0
  20. package/dist/script-runner.js +429 -0
  21. package/dist/server.js +1934 -0
  22. package/dist/types/iteration-history.js +139 -0
  23. package/openapi.json +1131 -0
  24. package/package.json +44 -0
package/openapi.json ADDED
@@ -0,0 +1,1131 @@
1
+ {
2
+ "openapi": "3.0.0",
3
+ "info": {
4
+ "version": "1.0.0",
5
+ "title": "Claude-Gen API",
6
+ "description": "AI-powered browser automation API. Generate reusable scripts or perform tasks directly using Claude and Browser.cash managed browsers.",
7
+ "contact": {
8
+ "name": "Browser.cash",
9
+ "email": "hello@browser.cash",
10
+ "url": "https://browser.cash"
11
+ }
12
+ },
13
+ "servers": [
14
+ {
15
+ "url": "https://claude-gen-api-264851422957.us-central1.run.app",
16
+ "description": "Production server"
17
+ }
18
+ ],
19
+ "externalDocs": {
20
+ "url": "https://github.com/anthropics/claude-gen",
21
+ "description": "GitHub Repository"
22
+ },
23
+ "components": {
24
+ "schemas": {
25
+ "BrowserOptions": {
26
+ "type": "object",
27
+ "description": "Browser session configuration options when using browserCashApiKey.",
28
+ "properties": {
29
+ "country": {
30
+ "type": "string",
31
+ "minLength": 2,
32
+ "maxLength": 2,
33
+ "description": "2-letter ISO country code for browser location.",
34
+ "example": "US"
35
+ },
36
+ "type": {
37
+ "type": "string",
38
+ "enum": ["consumer_distributed", "hosted", "testing"],
39
+ "description": "Type of browser node to use.",
40
+ "example": "consumer_distributed"
41
+ },
42
+ "proxyUrl": {
43
+ "type": "string",
44
+ "description": "SOCKS5 proxy URL for the browser session.",
45
+ "example": "socks5://user:pass@proxy.com:1080"
46
+ },
47
+ "windowSize": {
48
+ "type": "string",
49
+ "description": "Browser window size in WIDTHxHEIGHT format.",
50
+ "example": "1920x1080"
51
+ },
52
+ "adblock": {
53
+ "type": "boolean",
54
+ "description": "Enable ad-blocking in the browser.",
55
+ "example": true
56
+ },
57
+ "captchaSolver": {
58
+ "type": "boolean",
59
+ "description": "Enable automatic CAPTCHA solving.",
60
+ "example": true
61
+ }
62
+ }
63
+ },
64
+ "ScriptMetadata": {
65
+ "type": "object",
66
+ "properties": {
67
+ "id": {
68
+ "type": "string",
69
+ "description": "Unique script identifier.",
70
+ "example": "script-ml5jh1mk-zqby45"
71
+ },
72
+ "ownerId": {
73
+ "type": "string",
74
+ "description": "Hashed API key identifying the owner.",
75
+ "example": "a1b2c3d4e5f6g7h8"
76
+ },
77
+ "task": {
78
+ "type": "string",
79
+ "description": "The task description used to generate this script.",
80
+ "example": "Go to https://news.ycombinator.com and extract the top 5 stories"
81
+ },
82
+ "createdAt": {
83
+ "type": "string",
84
+ "format": "date-time",
85
+ "description": "ISO 8601 timestamp when the script was created."
86
+ },
87
+ "iterations": {
88
+ "type": "integer",
89
+ "description": "Number of test iterations performed.",
90
+ "example": 1
91
+ },
92
+ "success": {
93
+ "type": "boolean",
94
+ "description": "Whether the script passed testing."
95
+ },
96
+ "scriptSize": {
97
+ "type": "integer",
98
+ "description": "Size of the script in bytes.",
99
+ "example": 1011
100
+ }
101
+ },
102
+ "required": ["id", "ownerId", "task", "createdAt", "iterations", "success", "scriptSize"]
103
+ },
104
+ "TaskRecord": {
105
+ "type": "object",
106
+ "properties": {
107
+ "taskId": {
108
+ "type": "string",
109
+ "description": "Unique task identifier.",
110
+ "example": "task-ml5oby0v-4fh3mh"
111
+ },
112
+ "ownerId": {
113
+ "type": "string",
114
+ "description": "Hashed API key identifying the owner.",
115
+ "example": "a1b2c3d4e5f6g7h8"
116
+ },
117
+ "type": {
118
+ "type": "string",
119
+ "enum": ["generate", "automate", "run_script"],
120
+ "description": "Type of task."
121
+ },
122
+ "status": {
123
+ "type": "string",
124
+ "enum": ["pending", "running", "completed", "error"],
125
+ "description": "Current status of the task."
126
+ },
127
+ "task": {
128
+ "type": "string",
129
+ "description": "The task description."
130
+ },
131
+ "createdAt": {
132
+ "type": "string",
133
+ "format": "date-time",
134
+ "description": "ISO 8601 timestamp when the task was created."
135
+ },
136
+ "updatedAt": {
137
+ "type": "string",
138
+ "format": "date-time",
139
+ "description": "ISO 8601 timestamp when the task was last updated."
140
+ },
141
+ "browserSessionId": {
142
+ "type": "string",
143
+ "nullable": true,
144
+ "description": "Browser.cash session ID if a browser was used."
145
+ },
146
+ "scriptId": {
147
+ "type": "string",
148
+ "nullable": true,
149
+ "description": "Script ID for generate tasks."
150
+ },
151
+ "script": {
152
+ "type": "string",
153
+ "nullable": true,
154
+ "description": "Generated script content for generate tasks."
155
+ },
156
+ "iterations": {
157
+ "type": "integer",
158
+ "nullable": true,
159
+ "description": "Number of test iterations for generate tasks."
160
+ },
161
+ "result": {
162
+ "type": "object",
163
+ "nullable": true,
164
+ "description": "Extracted data for automate tasks."
165
+ },
166
+ "summary": {
167
+ "type": "string",
168
+ "nullable": true,
169
+ "description": "Summary of the task result."
170
+ },
171
+ "exitCode": {
172
+ "type": "integer",
173
+ "nullable": true,
174
+ "description": "Exit code for run_script tasks."
175
+ },
176
+ "output": {
177
+ "type": "string",
178
+ "nullable": true,
179
+ "description": "Script output for run_script tasks."
180
+ },
181
+ "error": {
182
+ "type": "string",
183
+ "nullable": true,
184
+ "description": "Error message if the task failed."
185
+ }
186
+ },
187
+ "required": ["taskId", "ownerId", "type", "status", "task", "createdAt", "updatedAt"]
188
+ },
189
+ "SSEEvent": {
190
+ "type": "object",
191
+ "properties": {
192
+ "type": {
193
+ "type": "string",
194
+ "enum": ["start", "log", "claude_output", "script_extracted", "iteration_result", "complete", "error", "output", "script_saved"],
195
+ "description": "Type of SSE event."
196
+ },
197
+ "data": {
198
+ "type": "object",
199
+ "description": "Event payload data."
200
+ },
201
+ "timestamp": {
202
+ "type": "string",
203
+ "format": "date-time",
204
+ "description": "ISO 8601 timestamp of the event."
205
+ }
206
+ },
207
+ "required": ["type", "data", "timestamp"]
208
+ },
209
+ "Error": {
210
+ "type": "object",
211
+ "properties": {
212
+ "error": {
213
+ "type": "string",
214
+ "description": "Error message"
215
+ }
216
+ },
217
+ "required": ["error"]
218
+ }
219
+ }
220
+ },
221
+ "paths": {
222
+ "/health": {
223
+ "get": {
224
+ "summary": "Health Check",
225
+ "description": "Check if the API server is running.",
226
+ "tags": ["System"],
227
+ "responses": {
228
+ "200": {
229
+ "description": "Server is healthy.",
230
+ "content": {
231
+ "application/json": {
232
+ "schema": {
233
+ "type": "object",
234
+ "properties": {
235
+ "status": {
236
+ "type": "string",
237
+ "enum": ["ok", "error"],
238
+ "example": "ok"
239
+ },
240
+ "timestamp": {
241
+ "type": "string",
242
+ "format": "date-time"
243
+ },
244
+ "version": {
245
+ "type": "string",
246
+ "example": "1.0.0"
247
+ }
248
+ },
249
+ "required": ["status", "timestamp", "version"]
250
+ }
251
+ }
252
+ }
253
+ }
254
+ }
255
+ }
256
+ },
257
+ "/test-cdp": {
258
+ "post": {
259
+ "summary": "Test CDP Connectivity",
260
+ "description": "Test connectivity to a Chrome DevTools Protocol URL.",
261
+ "tags": ["System"],
262
+ "requestBody": {
263
+ "required": true,
264
+ "content": {
265
+ "application/json": {
266
+ "schema": {
267
+ "type": "object",
268
+ "properties": {
269
+ "cdpUrl": {
270
+ "type": "string",
271
+ "description": "WebSocket CDP URL to test.",
272
+ "example": "wss://example.com/devtools/browser/uuid"
273
+ },
274
+ "testNavigation": {
275
+ "type": "boolean",
276
+ "default": true,
277
+ "description": "Also test if the browser can navigate to URLs."
278
+ },
279
+ "testUrl": {
280
+ "type": "string",
281
+ "default": "https://example.com",
282
+ "description": "URL to test navigation with."
283
+ }
284
+ },
285
+ "required": ["cdpUrl"]
286
+ }
287
+ }
288
+ }
289
+ },
290
+ "responses": {
291
+ "200": {
292
+ "description": "CDP connectivity test result.",
293
+ "content": {
294
+ "application/json": {
295
+ "schema": {
296
+ "type": "object",
297
+ "properties": {
298
+ "success": {
299
+ "type": "boolean"
300
+ },
301
+ "connected": {
302
+ "type": "boolean"
303
+ },
304
+ "pageTitle": {
305
+ "type": "string",
306
+ "nullable": true
307
+ },
308
+ "currentUrl": {
309
+ "type": "string",
310
+ "nullable": true
311
+ },
312
+ "error": {
313
+ "type": "string",
314
+ "nullable": true
315
+ },
316
+ "diagnostics": {
317
+ "type": "object",
318
+ "properties": {
319
+ "cdpConnected": {
320
+ "type": "boolean"
321
+ },
322
+ "browserResponsive": {
323
+ "type": "boolean"
324
+ },
325
+ "canNavigate": {
326
+ "type": "boolean"
327
+ },
328
+ "dnsWorking": {
329
+ "type": "boolean"
330
+ }
331
+ }
332
+ }
333
+ }
334
+ }
335
+ }
336
+ }
337
+ }
338
+ }
339
+ }
340
+ },
341
+ "/generate": {
342
+ "post": {
343
+ "summary": "Generate Script (JSON)",
344
+ "description": "Generate a browser automation script. Returns JSON response (use /generate/stream for real-time updates). Requires either browserCashApiKey or cdpUrl for browser access.",
345
+ "tags": ["Script Generation"],
346
+ "requestBody": {
347
+ "required": true,
348
+ "content": {
349
+ "application/json": {
350
+ "schema": {
351
+ "type": "object",
352
+ "properties": {
353
+ "task": {
354
+ "type": "string",
355
+ "description": "Description of the automation task.",
356
+ "example": "Go to https://news.ycombinator.com and extract the top 10 story titles"
357
+ },
358
+ "browserCashApiKey": {
359
+ "type": "string",
360
+ "description": "Browser.cash API key for managed browser sessions (recommended). Either this or cdpUrl is required."
361
+ },
362
+ "cdpUrl": {
363
+ "type": "string",
364
+ "description": "Direct Chrome DevTools Protocol WebSocket URL for user-provided browsers. Either this or browserCashApiKey is required.",
365
+ "example": "ws://localhost:9222/devtools/browser/..."
366
+ },
367
+ "browserOptions": {
368
+ "$ref": "#/components/schemas/BrowserOptions"
369
+ },
370
+ "skipTest": {
371
+ "type": "boolean",
372
+ "default": false,
373
+ "description": "Skip iterative testing of the generated script."
374
+ }
375
+ },
376
+ "required": ["task"]
377
+ }
378
+ }
379
+ }
380
+ },
381
+ "responses": {
382
+ "200": {
383
+ "description": "Script generation result.",
384
+ "content": {
385
+ "application/json": {
386
+ "schema": {
387
+ "type": "object",
388
+ "properties": {
389
+ "success": {
390
+ "type": "boolean"
391
+ },
392
+ "script": {
393
+ "type": "string",
394
+ "nullable": true
395
+ },
396
+ "iterations": {
397
+ "type": "integer",
398
+ "nullable": true
399
+ },
400
+ "scriptPath": {
401
+ "type": "string",
402
+ "nullable": true
403
+ },
404
+ "scriptId": {
405
+ "type": "string",
406
+ "nullable": true
407
+ },
408
+ "error": {
409
+ "type": "string",
410
+ "nullable": true
411
+ }
412
+ }
413
+ }
414
+ }
415
+ }
416
+ },
417
+ "400": {
418
+ "description": "Invalid request.",
419
+ "content": {
420
+ "application/json": {
421
+ "schema": {
422
+ "$ref": "#/components/schemas/Error"
423
+ }
424
+ }
425
+ }
426
+ },
427
+ "500": {
428
+ "description": "Server error.",
429
+ "content": {
430
+ "application/json": {
431
+ "schema": {
432
+ "$ref": "#/components/schemas/Error"
433
+ }
434
+ }
435
+ }
436
+ }
437
+ }
438
+ }
439
+ },
440
+ "/generate/stream": {
441
+ "post": {
442
+ "summary": "Generate Script (SSE Streaming)",
443
+ "description": "Generate a browser automation script with real-time SSE streaming updates. Returns a taskId that can be used to retrieve results if disconnected. Requires either browserCashApiKey or cdpUrl for browser access.",
444
+ "tags": ["Script Generation"],
445
+ "requestBody": {
446
+ "required": true,
447
+ "content": {
448
+ "application/json": {
449
+ "schema": {
450
+ "type": "object",
451
+ "properties": {
452
+ "task": {
453
+ "type": "string",
454
+ "description": "Description of the automation task.",
455
+ "example": "Go to https://news.ycombinator.com and extract the top 10 story titles"
456
+ },
457
+ "browserCashApiKey": {
458
+ "type": "string",
459
+ "description": "Browser.cash API key for managed browser sessions (recommended). Either this or cdpUrl is required."
460
+ },
461
+ "cdpUrl": {
462
+ "type": "string",
463
+ "description": "Direct Chrome DevTools Protocol WebSocket URL for user-provided browsers. Either this or browserCashApiKey is required.",
464
+ "example": "ws://localhost:9222/devtools/browser/..."
465
+ },
466
+ "browserOptions": {
467
+ "$ref": "#/components/schemas/BrowserOptions"
468
+ },
469
+ "skipTest": {
470
+ "type": "boolean",
471
+ "default": false,
472
+ "description": "Skip iterative testing of the generated script."
473
+ }
474
+ },
475
+ "required": ["task"]
476
+ },
477
+ "examples": {
478
+ "basic": {
479
+ "summary": "Basic usage",
480
+ "value": {
481
+ "task": "Go to https://news.ycombinator.com and extract the top 5 story titles",
482
+ "browserCashApiKey": "your-api-key"
483
+ }
484
+ },
485
+ "with-options": {
486
+ "summary": "With browser options",
487
+ "value": {
488
+ "task": "Go to https://news.ycombinator.com and extract the top 5 story titles",
489
+ "browserCashApiKey": "your-api-key",
490
+ "browserOptions": {
491
+ "country": "US",
492
+ "adblock": true
493
+ }
494
+ }
495
+ }
496
+ }
497
+ }
498
+ }
499
+ },
500
+ "responses": {
501
+ "200": {
502
+ "description": "SSE stream of generation events.",
503
+ "content": {
504
+ "text/event-stream": {
505
+ "schema": {
506
+ "type": "string",
507
+ "description": "Server-Sent Events stream. Events include: start (with taskId), log, claude_output, script_extracted, iteration_result, script_saved, complete, error."
508
+ },
509
+ "examples": {
510
+ "stream": {
511
+ "value": "data: {\"type\":\"start\",\"data\":{\"taskId\":\"task-abc123\",\"task\":\"...\",\"model\":\"claude-opus-4-5-20251101\"},\"timestamp\":\"2026-02-02T21:00:00.000Z\"}\n\ndata: {\"type\":\"complete\",\"data\":{\"taskId\":\"task-abc123\",\"success\":true,\"script\":\"#!/bin/bash...\",\"scriptId\":\"script-xyz\"},\"timestamp\":\"2026-02-02T21:01:00.000Z\"}\n\n"
512
+ }
513
+ }
514
+ }
515
+ }
516
+ }
517
+ }
518
+ }
519
+ },
520
+ "/automate/stream": {
521
+ "post": {
522
+ "summary": "Agentic Automation (SSE Streaming)",
523
+ "description": "Perform browser automation directly and return results (no script generation). Claude executes the task and returns extracted data. Returns a taskId that can be used to retrieve results if disconnected. Requires either browserCashApiKey or cdpUrl for browser access.",
524
+ "tags": ["Agentic Mode"],
525
+ "requestBody": {
526
+ "required": true,
527
+ "content": {
528
+ "application/json": {
529
+ "schema": {
530
+ "type": "object",
531
+ "properties": {
532
+ "task": {
533
+ "type": "string",
534
+ "description": "Description of the task to perform.",
535
+ "example": "Go to https://news.ycombinator.com and extract the top 5 story titles and URLs"
536
+ },
537
+ "browserCashApiKey": {
538
+ "type": "string",
539
+ "description": "Browser.cash API key for managed browser sessions (recommended). Either this or cdpUrl is required."
540
+ },
541
+ "cdpUrl": {
542
+ "type": "string",
543
+ "description": "Direct Chrome DevTools Protocol WebSocket URL for user-provided browsers. Either this or browserCashApiKey is required.",
544
+ "example": "ws://localhost:9222/devtools/browser/..."
545
+ },
546
+ "browserOptions": {
547
+ "$ref": "#/components/schemas/BrowserOptions"
548
+ }
549
+ },
550
+ "required": ["task"]
551
+ },
552
+ "examples": {
553
+ "extract-stories": {
554
+ "summary": "Extract data from Hacker News",
555
+ "value": {
556
+ "task": "Go to https://news.ycombinator.com and extract the top 5 story titles and URLs",
557
+ "browserCashApiKey": "your-api-key"
558
+ }
559
+ },
560
+ "get-page-info": {
561
+ "summary": "Get page information",
562
+ "value": {
563
+ "task": "Go to https://example.com and return the page title and main heading",
564
+ "browserCashApiKey": "your-api-key",
565
+ "browserOptions": {
566
+ "country": "US"
567
+ }
568
+ }
569
+ }
570
+ }
571
+ }
572
+ }
573
+ },
574
+ "responses": {
575
+ "200": {
576
+ "description": "SSE stream of automation events.",
577
+ "content": {
578
+ "text/event-stream": {
579
+ "schema": {
580
+ "type": "string",
581
+ "description": "Server-Sent Events stream. Events include: start (with taskId and mode:'agentic'), log, claude_output, complete (with result data), error."
582
+ },
583
+ "examples": {
584
+ "stream": {
585
+ "value": "data: {\"type\":\"start\",\"data\":{\"taskId\":\"task-abc123\",\"task\":\"...\",\"mode\":\"agentic\"},\"timestamp\":\"2026-02-02T21:00:00.000Z\"}\n\ndata: {\"type\":\"complete\",\"data\":{\"taskId\":\"task-abc123\",\"success\":true,\"result\":{\"stories\":[{\"title\":\"Story 1\",\"url\":\"https://...\"}]},\"summary\":\"Extracted 5 stories\"},\"timestamp\":\"2026-02-02T21:00:30.000Z\"}\n\n"
586
+ }
587
+ }
588
+ }
589
+ }
590
+ }
591
+ }
592
+ }
593
+ },
594
+ "/tasks": {
595
+ "get": {
596
+ "summary": "List Recent Tasks",
597
+ "description": "List recent tasks for result retrieval. Useful for finding tasks after client disconnect. Requires authentication via x-api-key header or apiKey query parameter.",
598
+ "tags": ["Tasks"],
599
+ "parameters": [
600
+ {
601
+ "name": "x-api-key",
602
+ "in": "header",
603
+ "description": "Browser.cash API key for authentication.",
604
+ "schema": {
605
+ "type": "string"
606
+ }
607
+ },
608
+ {
609
+ "name": "apiKey",
610
+ "in": "query",
611
+ "description": "Browser.cash API key for authentication (alternative to x-api-key header).",
612
+ "schema": {
613
+ "type": "string"
614
+ }
615
+ }
616
+ ],
617
+ "responses": {
618
+ "200": {
619
+ "description": "List of recent tasks.",
620
+ "content": {
621
+ "application/json": {
622
+ "schema": {
623
+ "type": "object",
624
+ "properties": {
625
+ "tasks": {
626
+ "type": "array",
627
+ "items": {
628
+ "$ref": "#/components/schemas/TaskRecord"
629
+ }
630
+ }
631
+ },
632
+ "required": ["tasks"]
633
+ },
634
+ "examples": {
635
+ "tasks-list": {
636
+ "value": {
637
+ "tasks": [
638
+ {
639
+ "taskId": "task-ml5oby0v-4fh3mh",
640
+ "type": "automate",
641
+ "status": "completed",
642
+ "task": "Go to https://example.com and return the page title",
643
+ "createdAt": "2026-02-02T21:20:38.143Z",
644
+ "updatedAt": "2026-02-02T21:21:04.601Z",
645
+ "result": {"title": "Example Domain"},
646
+ "summary": "Successfully extracted the page title"
647
+ }
648
+ ]
649
+ }
650
+ }
651
+ }
652
+ }
653
+ }
654
+ },
655
+ "401": {
656
+ "description": "Authentication required.",
657
+ "content": {
658
+ "application/json": {
659
+ "schema": {
660
+ "$ref": "#/components/schemas/Error"
661
+ },
662
+ "example": {
663
+ "error": "API key required (x-api-key header or apiKey query param)"
664
+ }
665
+ }
666
+ }
667
+ },
668
+ "500": {
669
+ "description": "Server error.",
670
+ "content": {
671
+ "application/json": {
672
+ "schema": {
673
+ "$ref": "#/components/schemas/Error"
674
+ }
675
+ }
676
+ }
677
+ }
678
+ }
679
+ }
680
+ },
681
+ "/tasks/{taskId}": {
682
+ "get": {
683
+ "summary": "Get Task Status and Result",
684
+ "description": "Retrieve a task's status and result by ID. Use this to get results after client disconnect or to poll for completion. Requires authentication via x-api-key header or apiKey query parameter.",
685
+ "tags": ["Tasks"],
686
+ "parameters": [
687
+ {
688
+ "name": "taskId",
689
+ "in": "path",
690
+ "required": true,
691
+ "description": "The task ID returned in the start event.",
692
+ "schema": {
693
+ "type": "string",
694
+ "example": "task-ml5oby0v-4fh3mh"
695
+ }
696
+ },
697
+ {
698
+ "name": "x-api-key",
699
+ "in": "header",
700
+ "description": "Browser.cash API key for authentication.",
701
+ "schema": {
702
+ "type": "string"
703
+ }
704
+ },
705
+ {
706
+ "name": "apiKey",
707
+ "in": "query",
708
+ "description": "Browser.cash API key for authentication (alternative to x-api-key header).",
709
+ "schema": {
710
+ "type": "string"
711
+ }
712
+ }
713
+ ],
714
+ "responses": {
715
+ "200": {
716
+ "description": "Task status and result.",
717
+ "content": {
718
+ "application/json": {
719
+ "schema": {
720
+ "$ref": "#/components/schemas/TaskRecord"
721
+ },
722
+ "examples": {
723
+ "running": {
724
+ "summary": "Task still running",
725
+ "value": {
726
+ "taskId": "task-abc123",
727
+ "type": "automate",
728
+ "status": "running",
729
+ "task": "Extract stories from HN",
730
+ "createdAt": "2026-02-02T21:00:00.000Z",
731
+ "updatedAt": "2026-02-02T21:00:05.000Z",
732
+ "browserSessionId": "session-xyz"
733
+ }
734
+ },
735
+ "completed-automate": {
736
+ "summary": "Completed automate task",
737
+ "value": {
738
+ "taskId": "task-abc123",
739
+ "type": "automate",
740
+ "status": "completed",
741
+ "task": "Extract stories from HN",
742
+ "createdAt": "2026-02-02T21:00:00.000Z",
743
+ "updatedAt": "2026-02-02T21:00:30.000Z",
744
+ "result": {"stories": [{"title": "Story 1", "url": "https://..."}]},
745
+ "summary": "Extracted 5 stories"
746
+ }
747
+ },
748
+ "completed-generate": {
749
+ "summary": "Completed generate task",
750
+ "value": {
751
+ "taskId": "task-def456",
752
+ "type": "generate",
753
+ "status": "completed",
754
+ "task": "Generate script for HN extraction",
755
+ "createdAt": "2026-02-02T21:00:00.000Z",
756
+ "updatedAt": "2026-02-02T21:02:00.000Z",
757
+ "script": "#!/bin/bash\nset -e\n...",
758
+ "scriptId": "script-xyz789",
759
+ "iterations": 1
760
+ }
761
+ },
762
+ "error": {
763
+ "summary": "Failed task",
764
+ "value": {
765
+ "taskId": "task-abc123",
766
+ "type": "automate",
767
+ "status": "error",
768
+ "task": "Extract data from page",
769
+ "createdAt": "2026-02-02T21:00:00.000Z",
770
+ "updatedAt": "2026-02-02T21:00:15.000Z",
771
+ "error": "Failed to extract data - element not found"
772
+ }
773
+ }
774
+ }
775
+ }
776
+ }
777
+ },
778
+ "401": {
779
+ "description": "Authentication required.",
780
+ "content": {
781
+ "application/json": {
782
+ "schema": {
783
+ "$ref": "#/components/schemas/Error"
784
+ },
785
+ "example": {
786
+ "error": "API key required (x-api-key header or apiKey query param)"
787
+ }
788
+ }
789
+ }
790
+ },
791
+ "404": {
792
+ "description": "Task not found.",
793
+ "content": {
794
+ "application/json": {
795
+ "schema": {
796
+ "$ref": "#/components/schemas/Error"
797
+ },
798
+ "example": {
799
+ "error": "Task not found"
800
+ }
801
+ }
802
+ }
803
+ },
804
+ "500": {
805
+ "description": "Server error.",
806
+ "content": {
807
+ "application/json": {
808
+ "schema": {
809
+ "$ref": "#/components/schemas/Error"
810
+ }
811
+ }
812
+ }
813
+ }
814
+ }
815
+ }
816
+ },
817
+ "/scripts": {
818
+ "get": {
819
+ "summary": "List Stored Scripts",
820
+ "description": "List scripts stored in Google Cloud Storage. Returns only scripts owned by the authenticated user. Requires authentication via x-api-key header or apiKey query parameter.",
821
+ "tags": ["Scripts"],
822
+ "parameters": [
823
+ {
824
+ "name": "x-api-key",
825
+ "in": "header",
826
+ "description": "Browser.cash API key for authentication.",
827
+ "schema": {
828
+ "type": "string"
829
+ }
830
+ },
831
+ {
832
+ "name": "apiKey",
833
+ "in": "query",
834
+ "description": "Browser.cash API key for authentication (alternative to x-api-key header).",
835
+ "schema": {
836
+ "type": "string"
837
+ }
838
+ }
839
+ ],
840
+ "responses": {
841
+ "200": {
842
+ "description": "List of stored scripts.",
843
+ "content": {
844
+ "application/json": {
845
+ "schema": {
846
+ "type": "object",
847
+ "properties": {
848
+ "scripts": {
849
+ "type": "array",
850
+ "items": {
851
+ "$ref": "#/components/schemas/ScriptMetadata"
852
+ }
853
+ }
854
+ },
855
+ "required": ["scripts"]
856
+ },
857
+ "examples": {
858
+ "scripts-list": {
859
+ "value": {
860
+ "scripts": [
861
+ {
862
+ "id": "script-ml5jh1mk-zqby45",
863
+ "task": "Go to https://news.ycombinator.com and extract the top 5 stories",
864
+ "createdAt": "2026-02-02T19:04:38.228Z",
865
+ "iterations": 1,
866
+ "success": true,
867
+ "scriptSize": 1011
868
+ }
869
+ ]
870
+ }
871
+ }
872
+ }
873
+ }
874
+ }
875
+ },
876
+ "401": {
877
+ "description": "Authentication required.",
878
+ "content": {
879
+ "application/json": {
880
+ "schema": {
881
+ "$ref": "#/components/schemas/Error"
882
+ },
883
+ "example": {
884
+ "error": "API key required (x-api-key header or apiKey query param)"
885
+ }
886
+ }
887
+ }
888
+ },
889
+ "500": {
890
+ "description": "Server error.",
891
+ "content": {
892
+ "application/json": {
893
+ "schema": {
894
+ "$ref": "#/components/schemas/Error"
895
+ }
896
+ }
897
+ }
898
+ }
899
+ }
900
+ }
901
+ },
902
+ "/scripts/{id}": {
903
+ "get": {
904
+ "summary": "Get Script Details",
905
+ "description": "Retrieve a stored script's content and metadata. Returns 404 if script doesn't exist or belongs to another user. Requires authentication via x-api-key header or apiKey query parameter.",
906
+ "tags": ["Scripts"],
907
+ "parameters": [
908
+ {
909
+ "name": "id",
910
+ "in": "path",
911
+ "required": true,
912
+ "description": "The script ID.",
913
+ "schema": {
914
+ "type": "string",
915
+ "example": "script-ml5jh1mk-zqby45"
916
+ }
917
+ },
918
+ {
919
+ "name": "x-api-key",
920
+ "in": "header",
921
+ "description": "Browser.cash API key for authentication.",
922
+ "schema": {
923
+ "type": "string"
924
+ }
925
+ },
926
+ {
927
+ "name": "apiKey",
928
+ "in": "query",
929
+ "description": "Browser.cash API key for authentication (alternative to x-api-key header).",
930
+ "schema": {
931
+ "type": "string"
932
+ }
933
+ }
934
+ ],
935
+ "responses": {
936
+ "200": {
937
+ "description": "Script content and metadata.",
938
+ "content": {
939
+ "application/json": {
940
+ "schema": {
941
+ "type": "object",
942
+ "properties": {
943
+ "content": {
944
+ "type": "string",
945
+ "description": "The bash script content."
946
+ },
947
+ "metadata": {
948
+ "$ref": "#/components/schemas/ScriptMetadata"
949
+ }
950
+ },
951
+ "required": ["content", "metadata"]
952
+ },
953
+ "examples": {
954
+ "script-details": {
955
+ "value": {
956
+ "content": "#!/bin/bash\nset -e\nCDP=\"${CDP_URL:?Required}\"\n\nagent-browser --cdp \"$CDP\" open \"https://example.com\"\n...",
957
+ "metadata": {
958
+ "id": "script-ml5jh1mk-zqby45",
959
+ "ownerId": "a1b2c3d4e5f6g7h8",
960
+ "task": "Go to https://example.com and get the title",
961
+ "createdAt": "2026-02-02T19:04:38.228Z",
962
+ "iterations": 1,
963
+ "success": true,
964
+ "scriptSize": 1011
965
+ }
966
+ }
967
+ }
968
+ }
969
+ }
970
+ }
971
+ },
972
+ "401": {
973
+ "description": "Authentication required.",
974
+ "content": {
975
+ "application/json": {
976
+ "schema": {
977
+ "$ref": "#/components/schemas/Error"
978
+ },
979
+ "example": {
980
+ "error": "API key required (x-api-key header or apiKey query param)"
981
+ }
982
+ }
983
+ }
984
+ },
985
+ "404": {
986
+ "description": "Script not found.",
987
+ "content": {
988
+ "application/json": {
989
+ "schema": {
990
+ "$ref": "#/components/schemas/Error"
991
+ },
992
+ "example": {
993
+ "error": "Script not found"
994
+ }
995
+ }
996
+ }
997
+ },
998
+ "500": {
999
+ "description": "Server error.",
1000
+ "content": {
1001
+ "application/json": {
1002
+ "schema": {
1003
+ "$ref": "#/components/schemas/Error"
1004
+ }
1005
+ }
1006
+ }
1007
+ }
1008
+ }
1009
+ }
1010
+ },
1011
+ "/scripts/{id}/run": {
1012
+ "post": {
1013
+ "summary": "Run Stored Script (SSE Streaming)",
1014
+ "description": "Execute a stored script with SSE streaming output. Returns a taskId that can be used to retrieve results if disconnected. Script must be owned by the authenticated user. Requires browserCashApiKey for authentication.",
1015
+ "tags": ["Scripts"],
1016
+ "parameters": [
1017
+ {
1018
+ "name": "id",
1019
+ "in": "path",
1020
+ "required": true,
1021
+ "description": "The script ID to run.",
1022
+ "schema": {
1023
+ "type": "string",
1024
+ "example": "script-ml5jh1mk-zqby45"
1025
+ }
1026
+ }
1027
+ ],
1028
+ "requestBody": {
1029
+ "required": true,
1030
+ "content": {
1031
+ "application/json": {
1032
+ "schema": {
1033
+ "type": "object",
1034
+ "properties": {
1035
+ "browserCashApiKey": {
1036
+ "type": "string",
1037
+ "description": "Browser.cash API key for managed browser sessions (recommended). Either this or cdpUrl is required."
1038
+ },
1039
+ "cdpUrl": {
1040
+ "type": "string",
1041
+ "description": "Direct Chrome DevTools Protocol WebSocket URL for user-provided browsers. Either this or browserCashApiKey is required.",
1042
+ "example": "ws://localhost:9222/devtools/browser/..."
1043
+ },
1044
+ "browserOptions": {
1045
+ "$ref": "#/components/schemas/BrowserOptions"
1046
+ }
1047
+ }
1048
+ },
1049
+ "examples": {
1050
+ "basic": {
1051
+ "summary": "Basic usage with Browser.cash",
1052
+ "value": {
1053
+ "browserCashApiKey": "your-api-key"
1054
+ }
1055
+ },
1056
+ "with-options": {
1057
+ "summary": "With browser options",
1058
+ "value": {
1059
+ "browserCashApiKey": "your-api-key",
1060
+ "browserOptions": {
1061
+ "country": "US"
1062
+ }
1063
+ }
1064
+ },
1065
+ "direct-cdp": {
1066
+ "summary": "Direct CDP URL (local development)",
1067
+ "value": {
1068
+ "cdpUrl": "ws://localhost:9222/devtools/browser/..."
1069
+ }
1070
+ }
1071
+ }
1072
+ }
1073
+ }
1074
+ },
1075
+ "responses": {
1076
+ "200": {
1077
+ "description": "SSE stream of script execution events.",
1078
+ "content": {
1079
+ "text/event-stream": {
1080
+ "schema": {
1081
+ "type": "string",
1082
+ "description": "Server-Sent Events stream. Events include: start (with taskId), log, output (stdout/stderr), complete (with exitCode), error."
1083
+ },
1084
+ "examples": {
1085
+ "stream": {
1086
+ "value": "data: {\"type\":\"start\",\"data\":{\"taskId\":\"task-abc123\",\"scriptId\":\"script-xyz\"},\"timestamp\":\"2026-02-02T21:00:00.000Z\"}\n\ndata: {\"type\":\"output\",\"data\":{\"stream\":\"stdout\",\"text\":\"{\\\"items\\\": [...]}\"},\"timestamp\":\"2026-02-02T21:00:30.000Z\"}\n\ndata: {\"type\":\"complete\",\"data\":{\"taskId\":\"task-abc123\",\"exitCode\":0,\"success\":true},\"timestamp\":\"2026-02-02T21:00:31.000Z\"}\n\n"
1087
+ }
1088
+ }
1089
+ }
1090
+ }
1091
+ },
1092
+ "404": {
1093
+ "description": "Script not found or not owned by user.",
1094
+ "content": {
1095
+ "application/json": {
1096
+ "schema": {
1097
+ "$ref": "#/components/schemas/Error"
1098
+ },
1099
+ "example": {
1100
+ "error": "Script not found"
1101
+ }
1102
+ }
1103
+ }
1104
+ }
1105
+ }
1106
+ }
1107
+ }
1108
+ },
1109
+ "tags": [
1110
+ {
1111
+ "name": "System",
1112
+ "description": "System health and connectivity endpoints"
1113
+ },
1114
+ {
1115
+ "name": "Script Generation",
1116
+ "description": "Generate reusable browser automation scripts"
1117
+ },
1118
+ {
1119
+ "name": "Agentic Mode",
1120
+ "description": "Perform tasks directly and return results (no script generation)"
1121
+ },
1122
+ {
1123
+ "name": "Tasks",
1124
+ "description": "Task status and result retrieval (disconnect recovery)"
1125
+ },
1126
+ {
1127
+ "name": "Scripts",
1128
+ "description": "Stored script management and execution"
1129
+ }
1130
+ ]
1131
+ }