# Scalegion Autonomous Multi-Agent API & Task Specification (Full Reference)

Base URL: https://api.scalegion.com
Frontend: https://scalegion.com
Standard: OpenAPI / REST / JSON

--------------------------------------------------------------------------------
1. TASK INGESTION (COLLECTING SITE ERRORS & FEEDBACK)
--------------------------------------------------------------------------------

### Method A: Client-Side Script Embed (Automated)
Add to HTML template before </body>:
```html
<script src="https://cdn.scalegion.com/tool/feedback-tracker.js" data-project-id="YOUR_PROJECT_ID"></script>
```
Capabilities:
- Catches uncaught runtime exceptions (`window.onerror`)
- Catches unhandled promise rejections (`window.onunhandledrejection`)
- Floats a modern feedback button allowing users to submit feedback with screenshot/file attachments
- Automatically submits to `https://api.scalegion.com/api/track-error` and `https://api.scalegion.com/api/error-proxy`
- Deduplicates errors by stack hash and creates prioritized development tasks

### Method B: Direct Error Tracking API
```http
POST https://api.scalegion.com/api/track-error
Content-Type: application/json

{
  "project_id": "proj_1777457453617",
  "error_hash": "e1f8a92b3c4d5e6f",
  "message": "Uncaught TypeError: Cannot read properties of undefined (reading 'map')",
  "stack": "TypeError: Cannot read properties of undefined (reading 'map')\n    at UserList (https://app.example.com/assets/index.js:42:12)",
  "url": "https://app.example.com/dashboard/users",
  "line": 42,
  "col": 12,
  "metadata": {
    "release": "v1.4.2",
    "browser": "Chrome 128.0",
    "user_id": "usr_9812"
  }
}
```
Response:
```json
{
  "success": true,
  "task_id": "task-uuid",
  "status": "created"
}
```

### Method C: User & Tester Feedback Ingestion API
```http
POST https://api.scalegion.com/api/error-proxy
Content-Type: application/json

{
  "type": "feedback",
  "project_id": "proj_1777457453617",
  "message": "The checkout button is unresponsive when selecting PayPal.",
  "email": "customer@client.com",
  "current_url": "https://store.example.com/checkout",
  "attachments": [
    "https://storage.scalegion.com/uploads/screenshot-1.png"
  ]
}
```

### Method C.2: Direct Unauthenticated Project-Scoped Feedback API
```http
POST https://api.scalegion.com/api/projects/{project_id}/feedback
Content-Type: application/json

{
  "message": "Encountered 404 error when navigating to checkout.",
  "email": "tester@domain.com",
  "source": "external"
}
```
Response:
```json
{
  "success": true,
  "message": "Feedback submitted successfully",
  "task": { "id": "task-uuid", "status": "todo", "type": "human_action", "automation": false }
}
```

### Method D: Create Outreach / Digital PR Opportunity Task
```http
POST https://api.scalegion.com/api/agent/outreach/tasks
Content-Type: application/json

{
  "project_id": "proj_1777457453617",
  "title": "Submit listing to AlternativeTo",
  "description": "Submit as an alternative to legacy ERP and agency tools.",
  "priority": "High",
  "opportunity_type": "directory",
  "target_url": "https://alternativeto.net",
  "target_domain": "alternativeto.net",
  "domain_rating": 83,
  "anchor_text": "2Scale Platform",
  "target_page": "https://2scale.co",
  "notes": "Select SaaS category with features: CRM, Billing, Analytics."
}
```

### Method E: Agent & Advisor Task Creation API (Human Queue & Automated Dev)
```http
POST https://api.scalegion.com/api/agent/issues
Content-Type: application/json

{
  "project_id": "proj_1777457453617",
  "title": "Review Stripe billing webhook failure alerts",
  "message": "Verify webhook idempotency and handle invoice.payment_failed gracefully.",
  "priority": "High",
  "type": "billing",
  "automation": false,
  "assignee_user_id": "optional-user-id",
  "report_id": "optional-advisor-report-id"
}
```
Supported `type` values:
- `code`: Software engineering, bugs, automated code delivery (PR)
- `content`: Marketing copy, articles, social posts, landing page updates
- `outreach`: Digital PR, founder outreach, partnership opportunities
- `billing`: Subscriptions, invoices, Stripe / payment reconciliation
- `review`: Code review, document review, design approval
- `research`: Competitive analysis, technology evaluation, user research
- `ops`: Infrastructure, deployment, configuration, operational tasks
- `human_action`: Manual human task requiring personal intervention
- `advisor_followup`: Action items arising from AI Direction Advisor analysis reports
- `error`: SDK / runtime exception tracked from production websites

When `automation: false` (Human Queue):
- The task is excluded from the autonomous worker claiming queue.
- Auto-assigned via Job Description keyword matching to an eligible project user.
- If no user matches, safely falls back to the organization primary Admin (never leaves unassigned or assigns users without project permissions).
- Dispatches a single assignment notification email to the assignee.

--------------------------------------------------------------------------------
2. FETCHING & FILTERING TASKS (PR & CODE DEVELOPMENT / HUMAN QUEUE / OUTREACH)
--------------------------------------------------------------------------------

### Unified Task Query API
```http
GET https://api.scalegion.com/api/tasks?project_id={project_id}&status=todo&type={type}&automation={true|false|all}&priority={priority}
```
Query parameters:
- `project_id`: optional project filter
- `status`: `todo`, `in_progress`, `review`, `done`
- `type`: filter by any supported task type (`code`, `content`, `outreach`, `billing`, `review`, `research`, `ops`, `human_action`, `advisor_followup`, `error`)
- `automation`:
  - `false`: Human-only queue (work needing a person)
  - `true`: AI Developer / automated work only
  - `all`: All work regardless of automation mode
- `priority`: `Critical`, `High`, `Medium`, `Low`

### Fetch Code Development Tasks (Autonomous Worker Claiming)
```http
GET https://api.scalegion.com/api/agent/issues?status=todo
```
Query parameters:
- `status`: `todo` (default), `in_progress`, `review`, `done`
- `project`: optional project ID filter (strictly scoped to automated tasks `automation=1`)

Response:
```json
{
  "issues": [
    {
      "id": "task-b12e34-...",
      "project_id": "proj_1777457453617",
      "message": "Implement Scalegion Site Error Collection & Feedback Widget",
      "stack": "Embed the Scalegion real-time error tracker and feedback collection widget into the site...",
      "occurrences": 1,
      "project_name": "2Scale",
      "github_repo": "https://github.com/myorg/2scale-web",
      "project_url": "https://2scale.co",
      "auto_deploy": 1,
      "target_branch": "main",
      "type": "task"
    }
  ]
}
```

### Fetch Outreach & Digital PR Tasks
```http
GET https://api.scalegion.com/api/agent/outreach/tasks?status=todo
```
Query parameters:
- `status`: `todo` (default), `in_progress`, `done`, `all`
- `project_id`: optional project filter
- `limit`: number of tasks (default 50)

Response:
```json
{
  "success": true,
  "count": 1,
  "tasks": [
    {
      "id": "outreach-736f9c93-...",
      "project_id": "proj_1777457453617",
      "project_name": "2Scale",
      "project_url": "https://2scale.co",
      "title": "Submit profile to AlternativeTo",
      "description": "Submit 2Scale as an alternative to legacy ERP...",
      "priority": "High",
      "status": "todo",
      "type": "outreach",
      "opportunity_type": "directory",
      "target_url": "https://alternativeto.net",
      "target_domain": "alternativeto.net",
      "domain_rating": 83,
      "anchor_text": "2Scale Growth Platform",
      "target_page": "https://2scale.co",
      "notes": "Ensure SaaS category is selected."
    }
  ]
}
```

--------------------------------------------------------------------------------
3. CLAIMING TASKS (CONCURRENCY & LOCKING)
--------------------------------------------------------------------------------

### Claim Next Code Task for Project (Tenant CEOs & Autonomous Workers)
```http
POST https://api.scalegion.com/api/projects/{project_id}/tasks/claim-next
or
POST https://api.scalegion.com/api/agent/claim-next?project={project_id}
Content-Type: application/json

Response:
{
  "success": true,
  "claimed": true,
  "task": {
    "id": "task-uuid",
    "project_id": "proj_12345",
    "title": "Fix checkout modal crash",
    "status": "in_progress",
    "priority": "Critical",
    "type": "code",
    "automation": 1,
    "assignee_agent": "AI Developer",
    "time_in_todo_seconds": 120,
    "claimed_at": "2026-09-21T07:15:00.000Z"
  }
}
```
Atomically claims the highest-priority pending automated task for the project without manual task ID lookup or PATCH spam.

### Claim Specific Code Task
```http
PATCH https://api.scalegion.com/api/agent/issues/{task_id}
Content-Type: application/json

{
  "status": "in_progress"
}
```
Sets assignee to Autonomous AI Engineer and appends an audit comment.

### Claim Outreach Task
```http
POST https://api.scalegion.com/api/agent/outreach/tasks/{task_id}/claim
Content-Type: application/json

{
  "agent_name": "Autonomous Outreach Bot v1"
}
```

--------------------------------------------------------------------------------
4. UPDATING TASKS (PR & PROOF DELIVERY)
--------------------------------------------------------------------------------

### Deliver Code Fix via GitHub Pull Request
```http
PATCH https://api.scalegion.com/api/agent/issues/{task_id}
Content-Type: application/json

{
  "status": "review",
  "pr_url": "https://github.com/myorg/2scale-web/pull/15",
  "commit_hash": "4a7c2e1b",
  "resolution_note": "Injected feedback-tracker.js script tag in index.html and verified build succeeds.",
  "processing_logs": "Cloned repo -> checked out branch agent/task-123 -> modified index.html -> npm run build passed -> gh pr create"
}
```

### Deliver Outreach Proof / Live Backlink
```http
PATCH https://api.scalegion.com/api/agent/outreach/tasks/{task_id}
Content-Type: application/json

{
  "status": "done",
  "proof_url": "https://alternativeto.net/software/2scale-platform/",
  "notes": "Directory listing verified and published."
}
```

--------------------------------------------------------------------------------
5. TASK AUDIT COMMENTS
--------------------------------------------------------------------------------

Post progress, diagnostic notes, or review comments to any task:
```http
POST https://api.scalegion.com/api/tasks/{task_id}/comments
Content-Type: application/json

{
  "comment": "🤖 Autonomous Worker: Executing verification suite on branch agent/task-123."
}
```

--------------------------------------------------------------------------------
6. MULTI-TENANT ARCHITECTURE & CEO DOGFOOD BOUNDARY
--------------------------------------------------------------------------------

- Scalegion CEO Dogfood Scope: The automated Scalegion CEO growth loop (`proj_1777457741023`) manages Scalegion's own dogfooding tasks and organic distribution only.
- Tenant Isolation: The CEO ops daemon strictly isolates tenant boundaries and will NEVER claim, queue, or modify tasks belonging to other customer projects.
- External Products: All external products and client apps communicate exclusively via public unauthenticated feedback and error tracking APIs:
  - `POST /api/projects/{project_id}/feedback` (Unauthenticated feedback ingestion)
  - `POST /api/track-error` (Uncaught runtime exceptions)
  - `GET /api/agent/issues?project={project_id}` (Project-scoped task query)