Conversation Endpoints

Manage agent conversation sessions. All endpoints are served through the API gateway at http://localhost:8000.

Endpoints

Method	Path	Description
`GET`	`/conversations`	List conversations
`POST`	`/conversations`	Create a new conversation
`GET`	`/conversations/{id}/messages`	Get conversation messages
`PATCH`	`/conversations/{id}`	Update conversation metadata
`DELETE`	`/conversations/{id}`	Delete a conversation

GET /conversations

List all conversations, optionally filtered by agent type.


curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8000/conversations?agent_type=rule_37&limit=20&offset=0"

Parameter	Type	Default	Description
`agent_type`	string	—	Filter by agent type
`limit`	int	20	Number of results
`offset`	int	0	Pagination offset

Response (200):


{
  "conversations": [
    {
      "conversation_id": "conv-abc123",
      "agent_type": "rule_37",
      "title": "Spacing exception for Smith Ranch",
      "created_at": "2026-04-10T14:30:00Z",
      "updated_at": "2026-04-10T14:35:00Z",
      "message_count": 6
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

POST /conversations

Create a new conversation session.


curl -X POST http://localhost:8000/conversations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_type": "rule_37",
    "title": "Spacing exception for Smith Ranch"
  }'

Response (201):


{
  "conversation_id": "conv-new-456",
  "agent_type": "rule_37",
  "title": "Spacing exception for Smith Ranch",
  "created_at": "2026-04-10T15:00:00Z"
}

GET /conversations/{conversation_id}/messages

Retrieve all messages in a conversation.


curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/conversations/conv-abc123/messages

Response (200):


{
  "messages": [
    {
      "role": "user",
      "content": "I need a spacing exception for well 42-383-12345",
      "timestamp": "2026-04-10T14:30:00Z"
    },
    {
      "role": "assistant",
      "content": "I'll analyze the spacing requirements...",
      "timestamp": "2026-04-10T14:30:05Z",
      "tools_called": ["spacing_calculation"]
    }
  ]
}

PATCH /conversations/{conversation_id}

Update conversation metadata (e.g., title).


curl -X PATCH http://localhost:8000/conversations/conv-abc123 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Updated title"}'

DELETE /conversations/{conversation_id}

Delete a conversation and its messages.


curl -X DELETE http://localhost:8000/conversations/conv-abc123 \
  -H "Authorization: Bearer $TOKEN"

Response: 204 No Content