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

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

POST /api/command/updateAgent
Content-Type: application/json

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

Response: 200 OK

3. Delete Agent

POST /api/command/deleteAgent
Content-Type: application/json

{
  "id": "guid"
}

Response: 200 OK

4. Create Conversation

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

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

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

POST /api/query/health
Content-Type: application/json
{}

Response: 200 OK
true

8. Get Agent

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

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

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

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

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

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

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

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

# 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