[Feature] API support for automation

[iamvince]

Api support to call chat sessions through api. GROUP CHAT sessions as nested projects in workspace for monorepo workspace.

[SNTL84]

🚀 Proposed API Design Spec — Velocity Automation API

Hey @ishandutta2007 and team! 👋 I'm Golden Lotus (@3goldenlotusroots-droid), an AI Workflow Developer actively using N8N + automation pipelines. This feature request is directly in my domain and I'd love to contribute toward building it. Here's a proposed API design spec for your review.

---

🎯 Goal

Enable external tools (N8N, Zapier, custom scripts, CI/CD pipelines) to:

1. Create & manage chat sessions programmatically
2. Support GROUP CHAT for monorepo workspaces (nested project sessions)
3. Stream / poll responses from Velocity's AI

---

📦 Base URL (proposed)

https://api.velocity.dev/v1

or self-hosted:

http://localhost:PORT/api/v1

---

🔑 Auth

{
  "Authorization": "Bearer <VELOCITY_API_KEY>"
}

---

📡 Endpoint Design

1. Create a Chat Session

POST /sessions

Request:

{
  "workspace_id": "ws_abc123",
  "project_id": "proj_xyz456",
  "session_name": "Refactor Auth Module",
  "mode": "single",
  "model": "velocity-default",
  "context_files": ["src/auth/index.ts", "src/auth/middleware.ts"],
  "system_prompt": "You are a senior engineer reviewing this monorepo."
}

Response:

{
  "session_id": "sess_789",
  "created_at": "2026-06-23T10:00:00Z",
  "status": "active"
}

---

2. Send a Message to a Session

POST /sessions/{session_id}/messages

Request:

{
  "role": "user",
  "content": "Review the authentication flow and suggest improvements.",
  "attachments": ["src/auth/index.ts"]
}

Response:

{
  "message_id": "msg_001",
  "role": "assistant",
  "content": "Here are my suggestions...",
  "tokens_used": 820,
  "timestamp": "2026-06-23T10:01:00Z"
}

---

3. GROUP CHAT — Monorepo Workspace Sessions

POST /workspaces/{workspace_id}/group-sessions

Request:

{
  "group_name": "Monorepo Sprint Review",
  "participants": [
    { "project_id": "proj_frontend", "role": "UI Team" },
    { "project_id": "proj_backend", "role": "API Team" },
    { "project_id": "proj_shared", "role": "Shared Libs" }
  ],
  "mode": "group",
  "broadcast_message": "Audit cross-project dependencies and flag breaking changes."
}

Response:

{
  "group_session_id": "gsess_999",
  "sessions": [
    { "project_id": "proj_frontend", "session_id": "sess_101" },
    { "project_id": "proj_backend",  "session_id": "sess_102" },
    { "project_id": "proj_shared",   "session_id": "sess_103" }
  ],
  "status": "running"
}

---

4. Stream Response (SSE)

GET /sessions/{session_id}/stream

Returns text/event-stream — compatible with N8N's HTTP SSE node.

---

5. List Sessions

GET /sessions?workspace_id=ws_abc123&project_id=proj_xyz456&status=active

---

6. Close / Archive Session

DELETE /sessions/{session_id}

---

🔧 N8N / Automation Workflow Integration Example

[Webhook Trigger]
     ↓
[HTTP Request: POST /sessions] → create session with repo context
     ↓
[HTTP Request: POST /sessions/{id}/messages] → send prompt
     ↓
[Parse Response JSON]
     ↓
[Slack/Email/GitHub PR Comment] → send AI output back

This would allow full CI/CD-aware AI reviews triggered on PR events, issue creation, etc.

---

📋 Why This Matters

• Monorepo teams can run parallel AI reviews per sub-project in a single group session
• Automation developers (N8N, Make, Zapier) get a clean REST interface to embed Velocity into any pipeline
• IDE context awareness via context_files means AI responses are code-grounded, not generic

---

✅ Questions for @ishandutta2007 Before Building

1. Is there an existing internal session/message model we can expose, or does this need a new layer?
2. Should the API key be workspace-scoped or user-scoped?
3. Is SSE streaming already supported internally, or would this need implementation?
4. For GROUP CHAT — should sub-sessions share memory/context across projects, or remain isolated?

Happy to take this further and submit a PR once you give the green light on the design direction! 🙌

---

👤 Repo Owner @ishandutta2007 — I'd love your feedback on this spec. If this direction looks good, I can start building it out. Feel free to also check out my work at github.com/3goldenlotusroots-droid and reach me on LinkedIn or via WhatsApp. Looking forward to collaborating! 🚀

[ishandutta2007]

@SNTL84 sounds good