socweb/backend/doc/api.md

SOC Backend API Reference

Base URL

http://localhost:8000   (dev)
https://soc-backend.azurewebsites.net   (production)

---

Health

GET /health

Returns server status.

Response 200

{"status": "ok"}

---

Chat

POST /api/chat/stream

SSE streaming chat endpoint. Returns text/event-stream.

Request Body

{
  "message": "your question",
  "conversation_id": "conv-abc123",
  "tools": ["search", "knowledge"],
  "model": "flash"
}

Field	Type	Required	Description
message	string	yes	User message (min 1 char)
conversation_id	string	yes	Conversation thread ID
tools	string[]	no	Tool keys: knowledge, tickets, search, document, sandbox
model	string	no	flash (default) or pro

SSE Events

data: {"type": "token", "content": "Hello"}
data: {"type": "tool_start", "tool": "web_search"}
data: {"type": "tool_end", "tool": "web_search"}
data: {"type": "done"}

---

Conversations

GET /api/conversations

List all conversations.

Response 200 -- ConversationOut[]

POST /api/conversations

Create a new conversation.

Request Body

{"title": "My conversation"}

GET /api/conversations/{id}

Get conversation with messages.

Response 200 -- ConversationDetail

PATCH /api/conversations/{id}

Update conversation title.

Request Body

{"title": "Updated title"}

DELETE /api/conversations/{id}

Delete a conversation and all its messages.

Response 204

---

Tickets

GET /api/tickets/summary

Aggregated ticket statistics.

Response 200

{
  "total": 42,
  "by_status": {"pending": 10, "processing": 20, "resolved": 12},
  "by_priority": {"P0": 2, "P1": 5, "P2": 25, "P3": 10}
}

GET /api/tickets

List tickets (proxied from Gongdan API).

Query Parameters

Param	Type	Default
page	int	1
page_size	int	20

Response 200 -- TicketData[]

[
  {
    "id": "uuid",
    "ticketNumber": "TK-001",
    "title": "Issue description",
    "status": "pending",
    "priority": "P1",
    "createdAt": "2025-01-15T10:00:00Z"
  }
]

GET /api/tickets/{ticket_id}

Get a single ticket detail.

---

Attachments

POST /api/attachments/upload

Upload a file to Azure Blob Storage.

Content-Type: multipart/form-data

Field	Type	Required	Description
data	file	yes	The file to upload (max 50 MB)
conversation_id	string (query)	no	Link attachment to a conversation
message_id	string (query)	no	Link attachment to a message

Request Example (curl)

curl -X POST http://localhost:8000/api/attachments/upload \
  -F "data=@report.pdf" \
  -G -d "conversation_id=conv-abc123"

Response 201

{
  "id": "a1b2c3d4-...",
  "filename": "report.pdf",
  "content_type": "application/pdf",
  "blob_url": "https://authdatablol.blob.core.windows.net/soc-files/attachments/conv-abc123/a1b2c3d4_report.pdf",
  "size_bytes": 1048576,
  "conversation_id": "conv-abc123",
  "message_id": null,
  "created_at": "2025-04-08T12:00:00+00:00"
}

Error 413 -- File exceeds 50 MB limit.

Side Effect: If the file type is parseable (PDF, images, CSV, DOCX, XLSX), a parse_attachment task is dispatched to Azure Service Bus for async processing.

GET /api/attachments/{id}

Get attachment metadata.

Response 200 -- AttachmentOut

{
  "id": "a1b2c3d4-...",
  "filename": "report.pdf",
  "content_type": "application/pdf",
  "blob_url": "https://...",
  "size_bytes": 1048576,
  "conversation_id": "conv-abc123",
  "message_id": null,
  "created_at": "2025-04-08T12:00:00+00:00"
}

Error 404 -- Attachment not found.

GET /api/attachments/{id}/download

Redirect to a time-limited SAS URL (valid for 1 hour).

Response 302 with Location header pointing to the SAS URL.

Error 404 -- Attachment not found.

Request Example

# Follow redirect to download
curl -L http://localhost:8000/api/attachments/a1b2c3d4/download -o report.pdf

DELETE /api/attachments/{id}

Delete an attachment (removes both the blob from Azure Storage and the database record).

Response 204 -- No content.

Error 404 -- Attachment not found.

Request Example

curl -X DELETE http://localhost:8000/api/attachments/a1b2c3d4

---

Service Bus Task Message Format

When an attachment with a parseable content type is uploaded, a task message is published to the soc-tasks Service Bus queue:

{
  "task_id": "hex-uuid",
  "task_type": "parse_attachment",
  "conversation_id": "conv-abc123",
  "payload": {
    "attachment_id": "a1b2c3d4-...",
    "content_type": "application/pdf",
    "blob_name": "attachments/conv-abc123/a1b2c3d4_report.pdf",
    "filename": "report.pdf"
  },
  "created_at": "2025-04-08T12:00:00"
}

Parseable content types:

• application/pdf
• image/png, image/jpeg, image/webp, image/gif
• text/csv
• application/vnd.openxmlformats-officedocument.spreadsheetml.sheet (XLSX)
• application/vnd.openxmlformats-officedocument.wordprocessingml.document (DOCX)