API Reference

REST API Endpoints

Sound Suite exposes a REST API on the same port as the dashboard (default: 3000). All endpoints return JSON.

Health & Status

`GET /api/health`

Returns system health status including all service states.

Response:

{
  "status": "healthy",
  "uptime": "1d 22h 10m",
  "services": {
    "fileWatcher": { "status": "running", "watchedPaths": 2 },
    "jobQueue": { "status": "idle", "pending": 0, "active": 0 },
    "mcpServer": { "status": "running", "port": 3001 },
    "database": { "status": "connected" },
    "redis": { "status": "connected", "memory": "1.66M", "keys": 33 }
  },
  "documents": {
    "total": 49,
    "indexed": 17,
    "queued": 0,
    "processing": 0,
    "error": 0
  }
}

Cases

`GET /api/cases`

List all cases.

Response:

{
  "cases": [
    {
      "id": "uuid",
      "name": "Case Name",
      "caseNumber": "XX-XXX-XXXXX-CV",
      "directoryPath": "/path/to/case/files",
      "documentCount": 25,
      "indexedCount": 11,
      "createdAt": "2025-01-15T10:00:00Z"
    }
  ]
}

`POST /api/cases`

Create a new case.

Body:

{
  "name": "My Case",
  "caseNumber": "2025-CV-001",
  "directoryPath": "/path/to/case/files"
}

`GET /api/cases/:id`

Get details for a specific case including all documents.

`DELETE /api/cases/:id`

Delete a case and optionally its associated documents and vectors.

Documents

`GET /api/documents`

List documents, optionally filtered by case.

Query Parameters:

Parameter	Type	Description
`caseId`	string	Filter by case ID
`status`	string	Filter by status: `QUEUED`, `PROCESSING`, `INDEXED`, `PARTIAL`, `ERROR`
`limit`	number	Results per page (default: 50)
`offset`	number	Pagination offset

`GET /api/documents/:id`

Get document details including processing status, page count, chunk count, and exhibits.

`POST /api/documents/:id/reprocess`

Queue a document for re-processing. Resets status to QUEUED.

Search

`POST /api/search`

Perform vector similarity search.

Body:

{
  "query": "search text",
  "caseId": "optional-case-id",
  "limit": 10,
  "threshold": 0.5
}

Response:

{
  "results": [
    {
      "text": "Matching text chunk...",
      "score": 0.87,
      "document": { "id": "uuid", "name": "document.pdf" },
      "page": 15,
      "chunkIndex": 3,
      "type": "text"
    }
  ]
}

`POST /api/search/pattern`

Perform regex pattern matching across documents.

Body:

{
  "pattern": "\\d{4}-CV-\\d+",
  "caseId": "optional-case-id"
}

Admin

`GET /api/admin/config`

Get current system configuration.

`PUT /api/admin/config`

Update configuration values.

`POST /api/admin/reindex`

Trigger re-indexing of all documents or a specific case.

`GET /api/admin/jobs`

List processing jobs with status and timing information.

`GET /api/admin/action-log`

Get the action log showing system events.

MCP Protocol (HTTP)

The MCP server accepts HTTP POST requests at the MCP endpoint.

Endpoint

POST http://{host}:{port}/api/mcp/execute

The exact URL is shown on the Admin > General page in the dashboard.

Request Format

{
  "tool": "tool_name",
  "params": {
    "param1": "value1",
    "param2": "value2"
  }
}

Listing Available Tools

{
  "tool": "list_tools",
  "params": {}
}

Response:

{
  "tools": [
    {
      "name": "query_case_knowledge",
      "description": "Perform semantic search on legal documents",
      "category": "search",
      "enabled": true,
      "parameters": {
        "query": { "type": "string", "required": true },
        "case_id": { "type": "string", "required": false },
        "limit": { "type": "number", "required": false, "default": 10 }
      }
    }
  ]
}

Error Responses

{
  "error": {
    "code": "TOOL_NOT_FOUND",
    "message": "Tool 'invalid_tool' not found",
    "available_tools": ["query_case_knowledge", "scan_for_pattern", "..."]
  }
}

Common error codes:

Code	HTTP Status	Description
`TOOL_NOT_FOUND`	404	Invalid tool name
`INVALID_PARAMS`	400	Missing or invalid parameters
`TOOL_DISABLED`	403	Tool is disabled in Tool Manager
`AUTH_REQUIRED`	401	Authentication required
`RATE_LIMITED`	429	Too many requests
`INTERNAL_ERROR`	500	Server-side error

Authentication

No Auth Mode

Default mode. No authentication headers required.

API Key Mode

Include the API key in the Authorization header:

curl -X POST http://localhost:3000/api/mcp/execute \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{"tool": "list_tools", "params": {}}'

OAuth Mode

OAuth mode supports standard OAuth 2.0 bearer tokens. Configure your OAuth provider settings in the Admin panel.

Webhooks (Future)

Webhook support is planned for a future release. Webhooks will notify external services when:

New documents are discovered
Document processing completes
Errors occur during processing
Search queries are executed
Tool calls are made via MCP

Stay tuned for updates on the GitHub repository.