Conversation API

Conversation routes manage chat threads. Message generation routes require a conversation ID.

API call order

1. Call POST /conversations to create a thread.
2. Use returned conversation_id with message endpoints.
3. Optionally list, fetch, rename, or delete conversations.

Shared request setup is documented once in API index.

Create conversation

POST /conversations

Create a new conversation for the current user.

Parameters:

Name	Type	Description	Default
request	ConversationCreate	New conversation payload.	required
requesting_user	User	Authenticated user injected by dependency.	Depends(get_current_user)

Returns:

Type	Description
Conversation	Created conversation.

Raises:

Type	Description
HTTPException	500 for server errors.

Usage

resp = requests.post(
    f"{BASE_URL}/conversations",
    json={"name": "Copernicus onboarding"},
    headers=headers,
    timeout=30,
)
resp.raise_for_status()
conversation = resp.json()
CONVERSATION_ID = conversation["id"]
print(conversation)

Explanation

Creates a user-owned conversation thread.

Notes

• Required before calling POST /conversations/{conversation_id}/messages.

List my conversations

GET /conversations?page=1&limit=20

List conversations owned by the current user.

Parameters:

Name	Type	Description	Default
request_user	User	Authenticated user injected by dependency.	Depends(get_current_user)
pagination	Pagination	Pagination parameters.	Depends()

Returns:

Type	Description
PaginatedResponse[Conversation]	Paginated conversations for the user.

Raises:

Type	Description
HTTPException	500 for server errors.

Usage

resp = requests.get(
    f"{BASE_URL}/conversations",
    params={"page": 1, "limit": 20},
    headers=headers,
    timeout=30,
)
resp.raise_for_status()
print(resp.json()["data"])

Explanation

Returns paginated conversations for the current user.

Notes

• Use for chat history screens and conversation selection.

Get one conversation

GET /conversations/{conversation_id}

Get a conversation and its messages.

Parameters:

Name	Type	Description	Default
conversation_id	str	Conversation identifier.	required
requesting_user	User	Authenticated user injected by dependency.	Depends(get_current_user)

Returns:

Type	Description
ConversationDetail	Conversation with messages and metadata.

Raises:

Type	Description
HTTPException	404 if not found; 403 if access is forbidden; 500 for server errors.

Usage

resp = requests.get(
    f"{BASE_URL}/conversations/{CONVERSATION_ID}",
    headers=headers,
    timeout=30,
)
resp.raise_for_status()
detail = resp.json()
print(detail["name"], len(detail["messages"]))

Explanation

Returns conversation metadata with stored messages.

Notes

• Useful for restoring previous chat context.

Rename conversation

PATCH /conversations/{conversation_id}

Update a conversation's name.

Parameters:

Name	Type	Description	Default
conversation_id	str	Conversation identifier.	required
request	ConversationNameUpdate	New name payload.	required
requesting_user	User	Authenticated user injected by dependency.	Depends(get_current_user)

Returns:

Type	Description
Conversation	Updated conversation.

Raises:

Type	Description
HTTPException	404 if not found; 403 if update is forbidden; 500 for server errors.

Usage

resp = requests.patch(
    f"{BASE_URL}/conversations/{CONVERSATION_ID}",
    json={"name": "Copernicus onboarding v2"},
    headers=headers,
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Explanation

Updates conversation display name.

Notes

• Does not change message content.

Delete conversation

DELETE /conversations/{conversation_id}

Delete a conversation and its messages.

Parameters:

Name	Type	Description	Default
conversation_id	str	Conversation identifier.	required
requesting_user	User	Authenticated user injected by dependency.	Depends(get_current_user)

Returns:

Type	Description
dict	Confirmation message.

Raises:

Type	Description
HTTPException	404 if not found; 403 if deletion is forbidden; 500 for server errors.

Usage

resp = requests.delete(
    f"{BASE_URL}/conversations/{CONVERSATION_ID}",
    headers=headers,
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Explanation

Removes the conversation and its related message records.

Notes

• Destructive operation.

Full API reference

For exhaustive schema details, use Swagger API.