CODEX_ADK/BACKEND/docs/COMPLETE-API-REFERENCE.md

# Codex API - Complete Reference (MVP v1.0.0)

## Base URL
- Development: `http://localhost:5246`
- Production: TBD

## Authentication
- Currently: None (MVP)
- Future: Bearer token (JWT)

---

## All Available Endpoints (13 Total)

### Commands (6 endpoints)

#### 1. Create Agent
```http
POST /api/command/createAgent
Content-Type: application/json

{
  "name": "My AI Agent",
  "description": "Agent description",
  "type": 0,
  "modelProvider": "openai",
  "modelName": "gpt-4o",
  "providerType": 0,
  "apiKey": "sk-...",
  "temperature": 0.7,
  "maxTokens": 4000,
  "systemPrompt": "You are a helpful assistant",
  "enableMemory": true,
  "conversationWindowSize": 10
}

Response: 200 OK
```

#### 2. Update Agent
```http
POST /api/command/updateAgent
Content-Type: application/json

{
  "id": "guid",
  "name": "Updated name",
  ...
}

Response: 200 OK
```

#### 3. Delete Agent
```http
POST /api/command/deleteAgent
Content-Type: application/json

{
  "id": "guid"
}

Response: 200 OK
```

#### 4. Create Conversation
```http
POST /api/command/createConversation
Content-Type: application/json

{
  "title": "My conversation",
  "summary": "Optional summary"
}

Response: 200 OK
{
  "id": "c5053b8e-c75a-48e4-ab88-24a0305be63f"
}
```

#### 5. Start Agent Execution
```http
POST /api/command/startAgentExecution
Content-Type: application/json

{
  "agentId": "guid",
  "conversationId": "guid",  // optional
  "userPrompt": "Your prompt here"
}

Response: 200 OK
{
  "id": "execution-guid"
}
```

#### 6. Complete Agent Execution
```http
POST /api/command/completeAgentExecution
Content-Type: application/json

{
  "executionId": "guid",
  "status": 2,  // Completed
  "response": "Agent response",
  "inputTokens": 100,
  "outputTokens": 200,
  "estimatedCost": 0.003
}

Response: 200 OK
```

---

### Queries (7 endpoints)

#### 7. Health Check
```http
POST /api/query/health
Content-Type: application/json
{}

Response: 200 OK
true
```

#### 8. Get Agent
```http
POST /api/query/getAgent
Content-Type: application/json

{
  "id": "guid"
}

Response: 200 OK
{
  "id": "guid",
  "name": "Agent name",
  "description": "...",
  "modelProvider": "openai",
  "modelName": "gpt-4o",
  ...
}
```

#### 9. Get Agent Execution
```http
POST /api/query/getAgentExecution
Content-Type: application/json

{
  "id": "guid"
}

Response: 200 OK
{
  "id": "guid",
  "agentId": "guid",
  "userPrompt": "...",
  "response": "...",
  "status": 2,
  "inputTokens": 100,
  "outputTokens": 200,
  ...
}
```

#### 10. Get Conversation
```http
POST /api/query/getConversation
Content-Type: application/json

{
  "id": "guid"
}

Response: 200 OK
{
  "id": "guid",
  "title": "...",
  "messages": [...],
  "executions": [...],
  ...
}
```

---

### List Endpoints (GET - Simple & Fast)

#### 11. List All Agents
```http
GET /api/agents

Response: 200 OK
[
  {
    "id": "guid",
    "name": "Agent name",
    "description": "...",
    "type": 0,
    "modelProvider": "openai",
    "modelName": "gpt-4o",
    "providerType": 0,
    "modelEndpoint": null,
    "status": 0,
    "createdAt": "2025-10-26T19:20:12.741613Z",
    "updatedAt": "2025-10-26T19:20:12.741613Z",
    "toolCount": 0,
    "executionCount": 0
  }
]

Limit: 100 most recent agents
```

#### 12. List All Conversations
```http
GET /api/conversations

Response: 200 OK
[
  {
    "id": "guid",
    "title": "Conversation title",
    "summary": null,
    "startedAt": "2025-10-26T21:33:29.409018Z",
    "lastMessageAt": "2025-10-26T21:33:29.409032Z",
    "messageCount": 0,
    "isActive": true,
    "executionCount": 0
  }
]

Limit: 100 most recent conversations
```

#### 13. List All Executions
```http
GET /api/executions

Response: 200 OK
[
  {
    "id": "guid",
    "agentId": "guid",
    "agentName": "Agent name",
    "conversationId": "guid",
    "userPrompt": "Truncated to 200 chars...",
    "status": 2,
    "startedAt": "2025-10-26T21:33:29Z",
    "completedAt": "2025-10-26T21:33:30Z",
    "inputTokens": 100,
    "outputTokens": 200,
    "estimatedCost": 0.003,
    "messageCount": 2,
    "errorMessage": null
  }
]

Limit: 100 most recent executions
```

---

### Bonus: Filter Executions by Status
```http
GET /api/executions/status/{status}

Valid status values:
- Pending
- Running
- Completed
- Failed
- Cancelled

Example: GET /api/executions/status/running

Response: 200 OK (same format as /api/executions)
```

---

### Bonus: Get Agent-Specific Data
```http
GET /api/agents/{agentId}/conversations
GET /api/agents/{agentId}/executions

Response: 200 OK (filtered lists)
```

---

## Enums Reference

### AgentType
```
0 = CodeGenerator
1 = CodeReviewer
2 = DataAnalyst
3 = Researcher
4 = Custom
```

### ModelProviderType
```
0 = CloudApi
1 = LocalEndpoint
2 = Custom
```

### AgentStatus
```
0 = Active
1 = Inactive
2 = Archived
```

### ExecutionStatus
```
0 = Pending
1 = Running
2 = Completed
3 = Failed
4 = Cancelled
```

---

## Frontend Integration Notes

### Working Endpoints
All 13 endpoints listed above are **live and functional**.

### Swagger Documentation
Currently, only 5 endpoints appear in `/swagger/v1/swagger.json`:
- POST /api/command/createAgent
- POST /api/command/updateAgent
- POST /api/command/deleteAgent
- POST /api/query/getAgent
- POST /api/query/health

**Why?** OpenHarbor.CQRS auto-documents only simple commands/queries. Endpoints with return types and GET endpoints are registered manually and work perfectly, but aren't auto-documented by Swagger.

### Recommended Approach for Frontend
1. Use this document as your API contract
2. Test each endpoint with curl/Postman
3. Generate TypeScript types from the example responses above
4. For production, we'll add proper OpenAPI documentation

### CORS
- Development: Any localhost port allowed
- Production: Configure in `appsettings.json`

### Error Handling
- 200: Success
- 400: Validation error (check request body)
- 404: Resource not found
- 429: Rate limit exceeded (1000 requests/minute)
- 500: Server error

---

## Quick Test Commands

```bash
# Health check
curl -X POST http://localhost:5246/api/query/health \\
  -H "Content-Type: application/json" -d '{}'

# Create conversation
curl -X POST http://localhost:5246/api/command/createConversation \\
  -H "Content-Type: application/json" \\
  -d '{"title":"My First Conversation"}'

# List all agents
curl http://localhost:5246/api/agents

# List all conversations
curl http://localhost:5246/api/conversations

# List all executions
curl http://localhost:5246/api/executions
```

---

## MVP Status: READY FOR FRONTEND

All 13 endpoints are:
- Implemented
- Tested
- Working in development
- Documented (this file)
- CORS enabled
- Rate limited
- Error handling in place

**Frontend team can start integration immediately!**

---

*Last updated: 2025-10-26*
*API Version: v1.0.0-mvp*