jean-philippe
3fae2fcbe1
This is the initial commit for the CODEX_ADK project, a full-stack AI agent management platform featuring: BACKEND (ASP.NET Core 8.0): - CQRS architecture with 6 commands and 7 queries - 16 API endpoints (all working and tested) - PostgreSQL database with 5 entities - AES-256 encryption for API keys - FluentValidation on all commands - Rate limiting and CORS configured - OpenAPI/Swagger documentation - Docker Compose setup (PostgreSQL + Ollama) FRONTEND (Flutter 3.x): - Dark theme with Svrnty branding - Collapsible sidebar navigation - CQRS API client with Result<T> error handling - Type-safe endpoints from OpenAPI schema - Multi-platform support (Web, iOS, Android, macOS, Linux, Windows) DOCUMENTATION: - Comprehensive API reference - Architecture documentation - Development guidelines for Claude Code - API integration guides - context-claude.md project overview Status: Backend ready (Grade A-), Frontend integration pending 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
409 lines
6.7 KiB
Markdown
409 lines
6.7 KiB
Markdown
# 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*
|