dev-agent/API.md

FastAPI Backend Endpoints

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

---

1. Health Checks

GET /health

Verifies server health.

• Response: 200 OK

{
  "status": "ok"
}

---

2. Dev Agent Builder Sessions

POST /api/v1/sessions

Initializes a new Dev Agent conversation session.

• Response: 200 OK

{
  "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:

{
  "message": "I want an agent triggered by API, using a REST API connection"
}

• Response: 200 OK

{
  "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

{
  "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

{
  "valid": false,
  "errors": [
    {
      "code": "MISSING_CONNECTION_CONFIG",
      "message": "API connection requires 'base_url'",
      "path": "connection.config.base_url"
    }
  ],
  "warnings": []
}