# FastAPI Backend Endpoints

All endpoints are hosted under `http://localhost:8000`.

---

## 1. Health Checks

### `GET /health`
Verifies server health.
* **Response**: `200 OK`
```json
{
  "status": "ok"
}
```

---

## 2. Dev Agent Builder Sessions

### `POST /api/v1/sessions`
Initializes a new Dev Agent conversation session.
* **Response**: `200 OK`
```json
{
  "session_id": "4fc710be-c21d-44b4-82a1-a47781b2a95c"
}
```

### `POST /api/v1/sessions/{session_id}/messages`
Sends a user message to the builder, advances the LangGraph state machine, and returns the updated build status.
* **Request Body**:
```json
{
  "message": "I want an agent triggered by API, using a REST API connection"
}
```
* **Response**: `200 OK`
```json
{
  "session_id": "4fc710be-c21d-44b4-82a1-a47781b2a95c",
  "status": "awaiting_clarification",
  "message": "Processed successfully",
  "questions": [
    {
      "question": "What is the base URL of the REST API connection?",
      "field": "connection_base_url",
      "options": null
    }
  ],
  "agent_spec": null,
  "validation": null
}
```

### `GET /api/v1/sessions/{session_id}`
Retrieves session history, current requirements state, draft specifications, and validation results.
* **Response**: `200 OK`
```json
{
  "session_id": "4fc710be-c21d-44b4-82a1-a47781b2a95c",
  "status": "completed",
  "extracted_requirements": { ... },
  "missing_information": [],
  "clarification_questions": [],
  "draft_spec": { ... },
  "validation_result": { "valid": true, "errors": [], "warnings": [] },
  "messages": [
    { "role": "user", "content": "..." },
    { "role": "assistant", "content": "..." }
  ]
}
```

---

## 3. Agent Specifications & Versions

### `POST /api/v1/agents/`
Stores a validated Agent Spec in the database.
* **Request Body**: (JSON matching Agent Spec schema)
* **Response**: `200 OK`

### `GET /api/v1/agents/{agent_id}`
Retrieves the active version of an Agent Spec by ID.
* **Response**: `200 OK`

### `PUT /api/v1/agents/{agent_id}`
Updates an Agent Spec, auto-incrementing the version number and adding to history.
* **Request Body**: (JSON matching Agent Spec schema)
* **Response**: `200 OK`

### `GET /api/v1/agents/{agent_id}/versions`
Lists all historic versions of the Agent Spec, ordered sequentially.
* **Response**: `200 OK`

### `POST /api/v1/agents/validate`
Performs immediate schema and semantic validation on a raw JSON Agent Spec without storing it.
* **Request Body**: (JSON matching Agent Spec schema)
* **Response**: `200 OK`
```json
{
  "valid": false,
  "errors": [
    {
      "code": "MISSING_CONNECTION_CONFIG",
      "message": "API connection requires 'base_url'",
      "path": "connection.config.base_url"
    }
  ],
  "warnings": []
}
```