Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

feat: add RESTful profile endpoints and improve API consistency

Mario71dfa1dd3ca5
diff --git a/docs/references/api-reference.json b/docs/references/api-reference.json
index 66975b33..2d007d54 100644
--- a/docs/references/api-reference.json
+++ b/docs/references/api-reference.json
@@ -1,21 +1,8 @@
{
"version": "2.0",
"generated": "auto-merged from code + user metadata",
- "count": 66,
+ "count": 63,
"endpoints": [
- {
- "method": "DELETE",
- "path": "/profiles/{name}",
- "handler": "handleDeleteByPath",
- "description": "Manage profile",
- "curl": true,
- "examples": {},
- "tldr": "Delete a profile",
- "cli": false,
- "curlExample": "curl -X DELETE http://localhost:9867/profiles/work",
- "parameters": "name (string, path, required): Profile name",
- "payload": "N/A"
- },
{
"method": "GET",
"path": "/",
@@ -251,59 +238,6 @@
"curl": true,
"examples": {}
},
- {
- "method": "GET",
- "path": "/profiles",
- "handler": "handleList",
- "description": "List profiles",
- "cli": true,
- "curl": true,
- "examples": {},
- "tldr": "List all browser profiles",
- "cliExample": "pinchtab profiles",
- "curlExample": "curl http://localhost:9867/profiles",
- "parameters": "None",
- "payload": "N/A (GET request)"
- },
- {
- "method": "GET",
- "path": "/profiles/{id}/instance",
- "handler": "handleProfileInstance",
- "description": "Get profile instance",
- "curl": true,
- "examples": {},
- "tldr": "Get the current running instance for a profile",
- "cli": false,
- "curlExample": "curl \"http://localhost:9867/profiles/abc123/instance\"",
- "parameters": "id (string, path, required): Profile ID",
- "payload": "N/A (GET request)"
- },
- {
- "method": "GET",
- "path": "/profiles/{name}/analytics",
- "handler": "handleAnalyticsByPath",
- "description": "Profile analytics",
- "curl": true,
- "examples": {},
- "tldr": "Get analytics/usage stats for a profile",
- "cli": false,
- "curlExample": "curl \"http://localhost:9867/profiles/work/analytics?period=7d\"",
- "parameters": "name (string, path, required): Profile name; period (string, query, optional: \"1d\",\"7d\",\"30d\", default: \"7d\")",
- "payload": "N/A (GET request)"
- },
- {
- "method": "GET",
- "path": "/profiles/{name}/logs",
- "handler": "handleLogsByPath",
- "description": "Profile logs",
- "curl": true,
- "examples": {},
- "tldr": "Get logs for a profile",
- "cli": false,
- "curlExample": "curl \"http://localhost:9867/profiles/work/logs?limit=100&level=info\"",
- "parameters": "name (string, path, required): Profile name; limit (int, query, optional, default: 100); level (string, query, optional: \"debug\",\"info\",\"warn\",\"error\")",
- "payload": "N/A (GET request)"
- },
{
"method": "GET",
"path": "/screencast",
@@ -373,32 +307,6 @@
"examples": {},
"html": true
},
- {
- "method": "PATCH",
- "path": "/profiles/meta",
- "handler": "handleUpdateMeta",
- "description": "Update profile metadata",
- "curl": true,
- "examples": {},
- "tldr": "Update profile metadata globally",
- "cli": false,
- "curlExample": "curl -X PATCH http://localhost:9867/profiles/meta -H \"Content-Type: application/json\" -d '{\"version\":\"2.0\"}'",
- "parameters": "None",
- "payload": "{\"version\":\"2.0\",\"tags\":[\"important\"]}"
- },
- {
- "method": "PATCH",
- "path": "/profiles/{name}",
- "handler": "handleUpdateByPath",
- "description": "Manage profile",
- "curl": true,
- "examples": {},
- "tldr": "Update a profile",
- "cli": false,
- "curlExample": "curl -X PATCH http://localhost:9867/profiles/work -H \"Content-Type: application/json\" -d '{\"description\":\"Updated\"}'",
- "parameters": "name (string, path, required): Profile name",
- "payload": "{\"description\":\"new description\",\"tags\":[\"tag1\"]}"
- },
{
"method": "POST",
"path": "/action",
@@ -616,71 +524,6 @@
"curl": true,
"examples": {}
},
- {
- "method": "POST",
- "path": "/profiles/create",
- "handler": "handleCreate",
- "description": "Create profile",
- "curl": true,
- "examples": {},
- "tldr": "Create a new browser profile",
- "cli": false,
- "curlExample": "curl -X POST http://localhost:9867/profiles/create -H \"Content-Type: application/json\" -d '{\"name\":\"work\"}'",
- "parameters": "None",
- "payload": "{\"name\":\"work\",\"description\":\"Work account\"}"
- },
- {
- "method": "POST",
- "path": "/profiles/import",
- "handler": "handleImport",
- "description": "Import profile",
- "curl": true,
- "examples": {},
- "tldr": "Import a profile from backup/archive",
- "cli": false,
- "curlExample": "curl -X POST http://localhost:9867/profiles/import -F \"[email protected]\" -F \"name=imported-profile\"",
- "parameters": "None",
- "payload": "FormData with file and name"
- },
- {
- "method": "POST",
- "path": "/profiles/{id}/start",
- "handler": "handleStartByID",
- "description": "Start profile instance",
- "curl": true,
- "examples": {},
- "tldr": "Start/launch a profile (create instance)",
- "cli": false,
- "curlExample": "curl -X POST http://localhost:9867/profiles/abc123/start -H \"Content-Type: application/json\" -d '{\"headless\":true}'",
- "parameters": "id (string, path, required): Profile ID",
- "payload": "{\"headless\":true,\"port\":9868}"
- },
- {
- "method": "POST",
- "path": "/profiles/{id}/stop",
- "handler": "handleStopByID",
- "description": "Stop profile instance",
- "curl": true,
- "examples": {},
- "tldr": "Stop/shutdown a profile instance",
- "cli": false,
- "curlExample": "curl -X POST http://localhost:9867/profiles/abc123/stop",
- "parameters": "id (string, path, required): Profile ID",
- "payload": "N/A or {\"force\":false}"
- },
- {
- "method": "POST",
- "path": "/profiles/{name}/reset",
- "handler": "handleResetByPath",
- "description": "Reset profile",
- "curl": true,
- "examples": {},
- "tldr": "Reset a profile (clear cookies, cache, history)",
- "cli": false,
- "curlExample": "curl -X POST http://localhost:9867/profiles/work/reset",
- "parameters": "name (string, path, required): Profile name",
- "payload": "N/A or {\"keepCookies\":false,\"keepHistory\":false}"
- },
{
"method": "POST",
"path": "/start/{id}",
@@ -729,6 +572,144 @@
"description": "Upload file",
"curl": true,
"examples": {}
+ },
+ {
+ "method": "GET",
+ "path": "/profiles",
+ "handler": "handleList",
+ "description": "List all profiles",
+ "cli": true,
+ "curl": true,
+ "tldr": "List all browser profiles",
+ "cliExample": "pinchtab profiles",
+ "curlExample": "curl http://localhost:9867/profiles",
+ "curlExampleOutput": "[{\"id\":\"278be873adeb\",\"name\":\"Pinchtab org\",\"created\":\"2026-02-27T20:37:13.599055326Z\",\"diskUsage\":534952089,\"source\":\"created\"}]",
+ "parameters": "all (boolean, query, optional, default: false): Include temporary profiles",
+ "payload": "N/A (GET request)",
+ "defaults": "Returns array of profiles with id, name, created, diskUsage, source, etc.",
+ "examples": {}
+ },
+ {
+ "method": "POST",
+ "path": "/profiles",
+ "handler": "handleCreate",
+ "description": "Create a new profile",
+ "cli": true,
+ "curl": true,
+ "tldr": "Create a new browser profile",
+ "cliExample": "pinchtab profile create my-profile",
+ "curlExample": "curl -X POST http://localhost:9867/profiles -H \"Content-Type: application/json\" -d '{\"name\":\"my-profile\",\"description\":\"For testing\"}'",
+ "curlExampleOutput": "{\"status\":\"created\",\"name\":\"my-profile\"}",
+ "parameters": "name (string, body, required): Profile name; description (string, body, optional); useWhen (string, body, optional)",
+ "payload": "{\"name\":\"my-profile\",\"description\":\"For web scraping\",\"useWhen\":\"Production scraping tasks\"}",
+ "defaults": "Creates profile directory at ~/.pinchtab/profiles/{name}/Default",
+ "examples": {}
+ },
+ {
+ "method": "GET",
+ "path": "/profiles/{id}",
+ "handler": "handleGetByID",
+ "description": "Get a specific profile",
+ "cli": false,
+ "curl": true,
+ "tldr": "Get profile info by ID or name",
+ "curlExample": "curl http://localhost:9867/profiles/278be873adeb",
+ "curlExampleOutput": "{\"id\":\"278be873adeb\",\"name\":\"Pinchtab org\",\"created\":\"2026-02-27T20:37:13.599055326Z\",\"diskUsage\":534952089,\"source\":\"created\",\"useWhen\":\"Gmail org\"}",
+ "parameters": "id (string, path, required): Profile ID or name",
+ "payload": "N/A (GET request)",
+ "defaults": "Supports both profile ID (hash) and profile name for backward compatibility",
+ "examples": {}
+ },
+ {
+ "method": "DELETE",
+ "path": "/profiles/{id}",
+ "handler": "handleDeleteByID",
+ "description": "Delete a profile",
+ "cli": true,
+ "curl": true,
+ "tldr": "Delete a browser profile",
+ "cliExample": "pinchtab profile delete my-profile",
+ "curlExample": "curl -X DELETE http://localhost:9867/profiles/my-profile",
+ "curlExampleOutput": "{\"status\":\"deleted\",\"id\":\"my-profile\",\"name\":\"my-profile\"}",
+ "parameters": "id (string, path, required): Profile ID or name",
+ "payload": "N/A (DELETE request)",
+ "defaults": "Recursively deletes profile directory",
+ "examples": {}
+ },
+ {
+ "method": "PATCH",
+ "path": "/profiles/{id}",
+ "handler": "handleUpdateByIDOrName",
+ "description": "Update profile metadata",
+ "cli": false,
+ "curl": true,
+ "tldr": "Update profile description or useWhen",
+ "curlExample": "curl -X PATCH http://localhost:9867/profiles/my-profile -H \"Content-Type: application/json\" -d '{\"description\":\"Updated description\",\"useWhen\":\"New use case\"}'",
+ "curlExampleOutput": "{\"status\":\"updated\",\"id\":\"my-profile\",\"name\":\"my-profile\"}",
+ "parameters": "id (string, path, required): Profile ID or name; description (string, body, optional); useWhen (string, body, optional)",
+ "payload": "{\"description\":\"For production scraping\",\"useWhen\":\"When extracting data from e-commerce sites\"}",
+ "defaults": "Only provided fields are updated",
+ "examples": {}
+ },
+ {
+ "method": "POST",
+ "path": "/profiles/{id}/reset",
+ "handler": "handleResetByIDOrName",
+ "description": "Reset profile cache",
+ "cli": false,
+ "curl": true,
+ "tldr": "Clear browser cache, cookies, and session data",
+ "curlExample": "curl -X POST http://localhost:9867/profiles/my-profile/reset",
+ "curlExampleOutput": "{\"status\":\"reset\",\"id\":\"my-profile\",\"name\":\"my-profile\"}",
+ "parameters": "id (string, path, required): Profile ID or name",
+ "payload": "N/A (POST with no body)",
+ "defaults": "Clears Sessions, Cache, Cookies, History, etc.",
+ "examples": {}
+ },
+ {
+ "method": "GET",
+ "path": "/profiles/{id}/logs",
+ "handler": "handleLogsByIDOrName",
+ "description": "Get profile activity logs",
+ "cli": false,
+ "curl": true,
+ "tldr": "View actions performed with this profile",
+ "curlExample": "curl 'http://localhost:9867/profiles/my-profile/logs?limit=50'",
+ "curlExampleOutput": "[{\"timestamp\":\"2026-03-01T05:12:45Z\",\"action\":\"navigate\",\"url\":\"https://example.com\"},{\"timestamp\":\"2026-03-01T05:12:50Z\",\"action\":\"click\",\"selector\":\"e5\"}]",
+ "parameters": "id (string, path, required): Profile ID or name; limit (int, query, optional, default: 100)",
+ "payload": "N/A (GET request)",
+ "defaults": "Returns array of ActionRecord",
+ "examples": {}
+ },
+ {
+ "method": "GET",
+ "path": "/profiles/{id}/analytics",
+ "handler": "handleAnalyticsByIDOrName",
+ "description": "Get profile analytics",
+ "cli": false,
+ "curl": true,
+ "tldr": "View usage statistics and analytics",
+ "curlExample": "curl http://localhost:9867/profiles/my-profile/analytics",
+ "curlExampleOutput": "{\"totalActions\":256,\"averageActionDuration\":2.5,\"topActions\":{\"navigate\":128,\"click\":98,\"type\":30},\"lastUsed\":\"2026-03-01T05:12:50Z\"}",
+ "parameters": "id (string, path, required): Profile ID or name",
+ "payload": "N/A (GET request)",
+ "defaults": "Returns AnalyticsReport with usage statistics",
+ "examples": {}
+ },
+ {
+ "method": "POST",
+ "path": "/profiles/import",
+ "handler": "handleImport",
+ "description": "Import Chrome profile",
+ "cli": false,
+ "curl": true,
+ "tldr": "Import existing Chrome profile",
+ "curlExample": "curl -X POST http://localhost:9867/profiles/import -H \"Content-Type: application/json\" -d '{\"name\":\"imported\",\"sourcePath\":\"/Users/you/Library/Application Support/Google/Chrome/Default\"}'",
+ "curlExampleOutput": "{\"status\":\"imported\",\"name\":\"imported\"}",
+ "parameters": "name (string, body, required): Profile name; sourcePath (string, body, required): Path to Chrome user data dir; description (string, body, optional); useWhen (string, body, optional)",
+ "payload": "{\"name\":\"chrome-work\",\"sourcePath\":\"/path/to/chrome/profile\",\"description\":\"Imported from Chrome\"}",
+ "defaults": "Copies Chrome profile directory to ~/.pinchtab/profiles/",
+ "examples": {}
}
]
}
diff --git a/internal/profiles/handlers.go b/internal/profiles/handlers.go
index aa0f98af..8fea4efc 100644
--- a/internal/profiles/handlers.go
+++ b/internal/profiles/handlers.go
@@ -4,21 +4,28 @@ import (
"encoding/json"
"fmt"
"net/http"
+ "os"
+ "path/filepath"
"strconv"
"github.com/pinchtab/pinchtab/internal/web"
)
func (pm *ProfileManager) RegisterHandlers(mux *http.ServeMux) {
+ // Standard CRUD endpoints
mux.HandleFunc("GET /profiles", pm.handleList)
- mux.HandleFunc("POST /profiles/create", pm.handleCreate)
+ mux.HandleFunc("POST /profiles", pm.handleCreate) // RESTful: POST /profiles instead of /profiles/create
+ mux.HandleFunc("POST /profiles/create", pm.handleCreate) // Backward compat
+ mux.HandleFunc("GET /profiles/{id}", pm.handleGetByID) // Get single profile by ID or name
+
+ // Advanced endpoints (specific paths, no conflict with {id})
mux.HandleFunc("POST /profiles/import", pm.handleImport)
mux.HandleFunc("PATCH /profiles/meta", pm.handleUpdateMeta)
- mux.HandleFunc("DELETE /profiles/{name}", pm.handleDeleteByPath)
- mux.HandleFunc("PATCH /profiles/{name}", pm.handleUpdateByPath)
- mux.HandleFunc("POST /profiles/{name}/reset", pm.handleResetByPath)
- mux.HandleFunc("GET /profiles/{name}/logs", pm.handleLogsByPath)
- mux.HandleFunc("GET /profiles/{name}/analytics", pm.handleAnalyticsByPath)
+ mux.HandleFunc("POST /profiles/{id}/reset", pm.handleResetByIDOrName) // Reset profile
+ mux.HandleFunc("GET /profiles/{id}/logs", pm.handleLogsByIDOrName) // Get logs
+ mux.HandleFunc("GET /profiles/{id}/analytics", pm.handleAnalyticsByIDOrName) // Get analytics
+ mux.HandleFunc("DELETE /profiles/{id}", pm.handleDeleteByID) // Delete profile
+ mux.HandleFunc("PATCH /profiles/{id}", pm.handleUpdateByIDOrName) // Update profile metadata
}
func (pm *ProfileManager) handleList(w http.ResponseWriter, r *http.Request) {
@@ -144,7 +151,180 @@ func (pm *ProfileManager) handleUpdateMeta(w http.ResponseWriter, r *http.Reques
web.JSON(w, 200, map[string]string{"status": "updated", "name": req.Name})
}
-// Path-param compat handlers for dashboard JS
+// New RESTful handlers
+
+func (pm *ProfileManager) handleGetByID(w http.ResponseWriter, r *http.Request) {
+ id := r.PathValue("id")
+
+ // Try to find profile by ID first
+ pm.mu.RLock()
+ entries, err := os.ReadDir(pm.baseDir)
+ pm.mu.RUnlock()
+
+ if err != nil {
+ web.Error(w, 500, err)
+ return
+ }
+
+ var foundProfile map[string]any
+
+ for _, entry := range entries {
+ if !entry.IsDir() {
+ continue
+ }
+
+ meta := readProfileMeta(filepath.Join(pm.baseDir, entry.Name()))
+ if meta.ID == "" {
+ meta.ID = profileID(entry.Name())
+ }
+
+ // If ID matches, or if id looks like a name (for backward compat)
+ if meta.ID == id || entry.Name() == id {
+ info, err := pm.profileInfo(entry.Name())
+ if err != nil {
+ continue
+ }
+
+ foundProfile = map[string]any{
+ "id": info.ID,
+ "name": info.Name,
+ "created": info.CreatedAt,
+ "diskUsage": info.SizeMB * 1024 * 1024,
+ "source": info.Source,
+ "chromeProfileName": info.ChromeProfileName,
+ "accountEmail": info.AccountEmail,
+ "accountName": info.AccountName,
+ "hasAccount": info.HasAccount,
+ "useWhen": info.UseWhen,
+ "description": info.Description,
+ }
+ break
+ }
+ }
+
+ if foundProfile == nil {
+ web.Error(w, 404, fmt.Errorf("profile %q not found", id))
+ return
+ }
+
+ web.JSON(w, 200, foundProfile)
+}
+
+func (pm *ProfileManager) handleDeleteByID(w http.ResponseWriter, r *http.Request) {
+ id := r.PathValue("id")
+
+ // Find profile name by ID
+ name, err := pm.FindByID(id)
+ if err != nil {
+ // Try as name directly (backward compat)
+ name = id
+ if !pm.Exists(name) {
+ web.Error(w, 404, fmt.Errorf("profile %q not found", id))
+ return
+ }
+ }
+
+ if err := pm.Delete(name); err != nil {
+ web.Error(w, 404, err)
+ return
+ }
+
+ web.JSON(w, 200, map[string]any{"status": "deleted", "id": id, "name": name})
+}
+
+// Helper to find profile name by ID or use as name directly
+func (pm *ProfileManager) resolveIDOrName(idOrName string) (string, error) {
+ // Try as ID first
+ name, err := pm.FindByID(idOrName)
+ if err == nil {
+ return name, nil
+ }
+ // Try as name directly
+ if pm.Exists(idOrName) {
+ return idOrName, nil
+ }
+ return "", fmt.Errorf("profile %q not found (not a valid ID or name)", idOrName)
+}
+
+// Consolidated handlers that work with both ID and name
+
+func (pm *ProfileManager) handleUpdateByIDOrName(w http.ResponseWriter, r *http.Request) {
+ idOrName := r.PathValue("id")
+ name, err := pm.resolveIDOrName(idOrName)
+ if err != nil {
+ web.Error(w, 404, err)
+ return
+ }
+
+ var req struct {
+ Name string `json:"name"`
+ UseWhen string `json:"useWhen"`
+ Description string `json:"description"`
+ }
+ if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+ web.Error(w, 400, fmt.Errorf("invalid JSON"))
+ return
+ }
+
+ updates := make(map[string]string)
+ if req.Description != "" {
+ updates["description"] = req.Description
+ }
+ if req.UseWhen != "" {
+ updates["useWhen"] = req.UseWhen
+ }
+ if len(updates) > 0 {
+ if err := pm.UpdateMeta(name, updates); err != nil {
+ web.Error(w, 404, err)
+ return
+ }
+ }
+
+ web.JSON(w, 200, map[string]any{"status": "updated", "id": idOrName, "name": name})
+}
+
+func (pm *ProfileManager) handleResetByIDOrName(w http.ResponseWriter, r *http.Request) {
+ idOrName := r.PathValue("id")
+ name, err := pm.resolveIDOrName(idOrName)
+ if err != nil {
+ web.Error(w, 404, err)
+ return
+ }
+
+ if err := pm.Reset(name); err != nil {
+ web.Error(w, 404, err)
+ return
+ }
+ web.JSON(w, 200, map[string]any{"status": "reset", "id": idOrName, "name": name})
+}
+
+func (pm *ProfileManager) handleLogsByIDOrName(w http.ResponseWriter, r *http.Request) {
+ idOrName := r.PathValue("id")
+ name, err := pm.resolveIDOrName(idOrName)
+ if err != nil {
+ web.Error(w, 404, err)
+ return
+ }
+
+ limit, _ := strconv.Atoi(r.URL.Query().Get("limit"))
+ logs := pm.Logs(name, limit)
+ web.JSON(w, 200, logs)
+}
+
+func (pm *ProfileManager) handleAnalyticsByIDOrName(w http.ResponseWriter, r *http.Request) {
+ idOrName := r.PathValue("id")
+ name, err := pm.resolveIDOrName(idOrName)
+ if err != nil {
+ web.Error(w, 404, err)
+ return
+ }
+
+ report := pm.Analytics(name)
+ web.JSON(w, 200, report)
+}
+
+// OLD: Path-param compat handlers for dashboard JS (deprecated - kept for legacy support if needed)
+// These are now handled above with {id} pattern that accepts both IDs and names
func (pm *ProfileManager) handleDeleteByPath(w http.ResponseWriter, r *http.Request) {
name := r.PathValue("name")