# Conversations

The Directory API gives you access to Organizations, Accounts, Employees and Groups. Every Entity within the subsequent API calls must have an Organization attached and API calls must be made with a User specific JWT.

## GET /api/v1/agent/conversations

> List active conversations for the current user.

```json
{"openapi":"3.0.3","info":{"title":"Peoplelogic Agent API","version":"1.0.0"},"tags":[{"name":"Conversations","description":"The Directory API gives you access to Organizations, Accounts, Employees and Groups.  Every Entity within the subsequent API calls must have an Organization attached and API calls must be made with a User specific JWT."}],"servers":[{"url":"https://api.peoplelogic.dev"}],"paths":{"/api/v1/agent/conversations":{"get":{"summary":"List active conversations for the current user.","tags":["Conversations"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Conversation"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"schemas":{"Conversation":{"type":"object","properties":{"id":{"type":"string","description":"Conversation unique identifier."},"userId":{"type":"string","description":"ID of the user who owns this conversation."},"tenant":{"type":"string","description":"Tenant/workspace identifier to which this conversation belongs."},"timestamp":{"type":"string","format":"date-time","description":"Timestamp when the conversation was created."},"name":{"type":"string","description":"Friendly name of the conversation."}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"type":"string"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"string"}}}}}}}
```

## POST /api/v1/agent/conversations/start

> Start a new conversation.

```json
{"openapi":"3.0.3","info":{"title":"Peoplelogic Agent API","version":"1.0.0"},"tags":[{"name":"Conversations","description":"The Directory API gives you access to Organizations, Accounts, Employees and Groups.  Every Entity within the subsequent API calls must have an Organization attached and API calls must be made with a User specific JWT."}],"servers":[{"url":"https://api.peoplelogic.dev"}],"paths":{"/api/v1/agent/conversations/start":{"post":{"summary":"Start a new conversation.","tags":["Conversations"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversation"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"schemas":{"Conversation":{"type":"object","properties":{"id":{"type":"string","description":"Conversation unique identifier."},"userId":{"type":"string","description":"ID of the user who owns this conversation."},"tenant":{"type":"string","description":"Tenant/workspace identifier to which this conversation belongs."},"timestamp":{"type":"string","format":"date-time","description":"Timestamp when the conversation was created."},"name":{"type":"string","description":"Friendly name of the conversation."}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"type":"string"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"string"}}}}}}}
```

## PUT /api/v1/agent/conversations/{id}

> Update a conversation's details.

```json
{"openapi":"3.0.3","info":{"title":"Peoplelogic Agent API","version":"1.0.0"},"tags":[{"name":"Conversations","description":"The Directory API gives you access to Organizations, Accounts, Employees and Groups.  Every Entity within the subsequent API calls must have an Organization attached and API calls must be made with a User specific JWT."}],"servers":[{"url":"https://api.peoplelogic.dev"}],"paths":{"/api/v1/agent/conversations/{id}":{"put":{"summary":"Update a conversation's details.","tags":["Conversations"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Conversation ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversation"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversation"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"schemas":{"Conversation":{"type":"object","properties":{"id":{"type":"string","description":"Conversation unique identifier."},"userId":{"type":"string","description":"ID of the user who owns this conversation."},"tenant":{"type":"string","description":"Tenant/workspace identifier to which this conversation belongs."},"timestamp":{"type":"string","format":"date-time","description":"Timestamp when the conversation was created."},"name":{"type":"string","description":"Friendly name of the conversation."}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"type":"string"}}}},"NotFound":{"description":"Not Found","content":{"application/json":{"schema":{"type":"string"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"string"}}}}}}}
```

## DELETE /api/v1/agent/conversations/{id}

> Delete a conversation.

```json
{"openapi":"3.0.3","info":{"title":"Peoplelogic Agent API","version":"1.0.0"},"tags":[{"name":"Conversations","description":"The Directory API gives you access to Organizations, Accounts, Employees and Groups.  Every Entity within the subsequent API calls must have an Organization attached and API calls must be made with a User specific JWT."}],"servers":[{"url":"https://api.peoplelogic.dev"}],"paths":{"/api/v1/agent/conversations/{id}":{"delete":{"summary":"Delete a conversation.","tags":["Conversations"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Conversation ID"}],"responses":{"200":{"description":"Success (conversation deleted)"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"responses":{"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"string"}}}},"NotFound":{"description":"Not Found","content":{"application/json":{"schema":{"type":"string"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"string"}}}}}}}
```

## Get agent task assignments (follow-up).

> Retrieve the list of tasks assigned by the agent for the user's last question. Requires an existing conversation (conversationId must be provided).

```json
{"openapi":"3.0.3","info":{"title":"Peoplelogic Agent API","version":"1.0.0"},"tags":[{"name":"Conversations","description":"The Directory API gives you access to Organizations, Accounts, Employees and Groups.  Every Entity within the subsequent API calls must have an Organization attached and API calls must be made with a User specific JWT."}],"servers":[{"url":"https://api.peoplelogic.dev"}],"paths":{"/api/v1/agent/assign":{"post":{"summary":"Get agent task assignments (follow-up).","tags":["Conversations"],"description":"Retrieve the list of tasks assigned by the agent for the user's last question. Requires an existing conversation (conversationId must be provided).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseAssignmentHolder"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"schemas":{"UserRequest":{"type":"object","properties":{"question":{"type":"string","description":"User's question or message."},"maxResults":{"type":"integer","description":"Max number of results or steps (defaults to 5)."},"additionalInstructions":{"type":"string","description":"Additional instructions or context for the agent."},"conversationId":{"type":"string","description":"ID of an existing conversation (for follow-ups; omit for new questions)."},"since":{"type":"string","format":"date-time","description":"If provided, get history messages since this timestamp (used in history request)."}}},"BaseAssignmentHolder":{"type":"object","properties":{"response":{"type":"string","description":"Agent's response summary or prompt to the user (e.g., asking for confirmation)."},"needsConfirmation":{"type":"boolean","description":"True if the agent is awaiting user confirmation or input to proceed."},"newWorkflow":{"type":"boolean","description":"True if the agent is proposing a new scheduled workflow."},"scheduleFrequency":{"$ref":"#/components/schemas/WorkflowScheduleFrequency"},"hourOfWorkflow":{"type":"integer","description":"Hour of day (0-23) for scheduled workflow execution (if applicable)."},"dayOfWorkflow":{"type":"integer","description":"Day of week or month for scheduled workflow (if applicable)."},"minuteOfWorkflow":{"type":"integer","description":"Minute of hour for scheduled workflow (if applicable)."},"timeZone":{"type":"string","description":"Time zone identifier for the scheduled workflow (if applicable)."},"agents":{"type":"array","items":{"$ref":"#/components/schemas/BaseAssignmentResponse"},"description":"List of assigned tasks (agents) to be executed."},"subscriptionActive":{"type":"boolean","description":"Indicates if the user's subscription is active (true) or if execution is limited due to subscription issues."},"notificationChannel":{"$ref":"#/components/schemas/CompletionNotificationChannel"},"notificationTo":{"type":"string","description":"Target identifier for completion notification (e.g., email address or Slack channel, if provided)."},"userId":{"type":"string","description":"Identifier of the user for whom the tasks are assigned."}}},"WorkflowScheduleFrequency":{"type":"string","description":"Frequency for scheduled workflow execution.","enum":["DAILY","WEEKDAY","MONTHLY","WEEKLY","QUARTERLY","YEARLY","CUSTOM","ONCE","NONE","INVALID"]},"BaseAssignmentResponse":{"type":"object","properties":{"agent":{"$ref":"#/components/schemas/AgentProfile"},"specificTask":{"type":"string","description":"Specific action that this task should perform."},"step":{"type":"integer","description":"Zero-based index of this task in the sequence."},"dependsOn":{"type":"integer","description":"Index of the task this one depends on (-1 if none)."},"workflowAssignment":{"type":"boolean","description":"True if this task is the top-level workflow being executed, false otherwise."},"tasksDependingOnThis":{"type":"array","items":{"$ref":"#/components/schemas/BaseAssignmentResponse"},"description":"Tasks that depend on this task."}}},"AgentProfile":{"type":"object","properties":{"name":{"type":"string","description":"Agent name."},"persona":{"type":"string","description":"Short description of the agent's role/persona."},"avatar":{"type":"string","description":"URL or identifier for agent's avatar image."},"bio":{"type":"string","description":"Full biography of the agent."},"title":{"type":"string","description":"Agent title or designation."},"shortBio":{"type":"string","description":"Short bio snippet for quick reference."},"coordinator":{"type":"boolean","description":"Whether this agent is a coordinator (primary agent)."},"beanName":{"type":"string","description":"Internal bean name of the agent (context identifier)."}}},"CompletionNotificationChannel":{"type":"string","description":"Channel for completion notification.","enum":["NONE","EMAIL","SLACK","IMMEDIATE"]}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"type":"string"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"string"}}}}}}}
```

## Ask a question (start a new conversation).

> Submit a question to the Peoplelogic agent. Do not include a conversationId (a new conversation will be started).

```json
{"openapi":"3.0.3","info":{"title":"Peoplelogic Agent API","version":"1.0.0"},"tags":[{"name":"Conversations","description":"The Directory API gives you access to Organizations, Accounts, Employees and Groups.  Every Entity within the subsequent API calls must have an Organization attached and API calls must be made with a User specific JWT."}],"servers":[{"url":"https://api.peoplelogic.dev"}],"paths":{"/api/v1/agent/ask":{"post":{"summary":"Ask a question (start a new conversation).","tags":["Conversations"],"description":"Submit a question to the Peoplelogic agent. Do not include a conversationId (a new conversation will be started).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"schemas":{"UserRequest":{"type":"object","properties":{"question":{"type":"string","description":"User's question or message."},"maxResults":{"type":"integer","description":"Max number of results or steps (defaults to 5)."},"additionalInstructions":{"type":"string","description":"Additional instructions or context for the agent."},"conversationId":{"type":"string","description":"ID of an existing conversation (for follow-ups; omit for new questions)."},"since":{"type":"string","format":"date-time","description":"If provided, get history messages since this timestamp (used in history request)."}}},"AgentResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded."},"agent":{"$ref":"#/components/schemas/AgentProfile"},"reply":{"type":"string","description":"The agent's response message."},"sources":{"type":"array","items":{"$ref":"#/components/schemas/ContentSource"},"description":"Content sources (e.g., documents or URLs) cited in the response."},"confirming":{"type":"boolean","description":"True if the agent is asking for confirmation from the user."},"subtasks":{"type":"array","items":{"$ref":"#/components/schemas/AgentResponse"},"description":"Subtasks or follow-up responses (if the agent's response is composed of multiple parts)."},"conversation":{"type":"string","description":"Conversation ID this response is associated with (if any)."}},"required":["success","agent","reply"]},"AgentProfile":{"type":"object","properties":{"name":{"type":"string","description":"Agent name."},"persona":{"type":"string","description":"Short description of the agent's role/persona."},"avatar":{"type":"string","description":"URL or identifier for agent's avatar image."},"bio":{"type":"string","description":"Full biography of the agent."},"title":{"type":"string","description":"Agent title or designation."},"shortBio":{"type":"string","description":"Short bio snippet for quick reference."},"coordinator":{"type":"boolean","description":"Whether this agent is a coordinator (primary agent)."},"beanName":{"type":"string","description":"Internal bean name of the agent (context identifier)."}}},"ContentSource":{"type":"object","properties":{"name":{"type":"string","description":"Name or title of the content source."},"type":{"type":"string","description":"Type of content (e.g., \"document\", \"url\")."},"url":{"type":"string","format":"uri","description":"URL of the content source if applicable."}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"type":"string"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"string"}}}}}}}
```

## Send a reply in a conversation.

> Send a follow-up message or confirmation in an existing conversation. This is typically used to confirm task execution or ask a clarifying question, using the conversationId from a previous response.

```json
{"openapi":"3.0.3","info":{"title":"Peoplelogic Agent API","version":"1.0.0"},"tags":[{"name":"Conversations","description":"The Directory API gives you access to Organizations, Accounts, Employees and Groups.  Every Entity within the subsequent API calls must have an Organization attached and API calls must be made with a User specific JWT."}],"servers":[{"url":"https://api.peoplelogic.dev"}],"paths":{"/api/v1/agent/reply":{"post":{"summary":"Send a reply in a conversation.","tags":["Conversations"],"description":"Send a follow-up message or confirmation in an existing conversation. This is typically used to confirm task execution or ask a clarifying question, using the conversationId from a previous response.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"schemas":{"UserRequest":{"type":"object","properties":{"question":{"type":"string","description":"User's question or message."},"maxResults":{"type":"integer","description":"Max number of results or steps (defaults to 5)."},"additionalInstructions":{"type":"string","description":"Additional instructions or context for the agent."},"conversationId":{"type":"string","description":"ID of an existing conversation (for follow-ups; omit for new questions)."},"since":{"type":"string","format":"date-time","description":"If provided, get history messages since this timestamp (used in history request)."}}},"AgentResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded."},"agent":{"$ref":"#/components/schemas/AgentProfile"},"reply":{"type":"string","description":"The agent's response message."},"sources":{"type":"array","items":{"$ref":"#/components/schemas/ContentSource"},"description":"Content sources (e.g., documents or URLs) cited in the response."},"confirming":{"type":"boolean","description":"True if the agent is asking for confirmation from the user."},"subtasks":{"type":"array","items":{"$ref":"#/components/schemas/AgentResponse"},"description":"Subtasks or follow-up responses (if the agent's response is composed of multiple parts)."},"conversation":{"type":"string","description":"Conversation ID this response is associated with (if any)."}},"required":["success","agent","reply"]},"AgentProfile":{"type":"object","properties":{"name":{"type":"string","description":"Agent name."},"persona":{"type":"string","description":"Short description of the agent's role/persona."},"avatar":{"type":"string","description":"URL or identifier for agent's avatar image."},"bio":{"type":"string","description":"Full biography of the agent."},"title":{"type":"string","description":"Agent title or designation."},"shortBio":{"type":"string","description":"Short bio snippet for quick reference."},"coordinator":{"type":"boolean","description":"Whether this agent is a coordinator (primary agent)."},"beanName":{"type":"string","description":"Internal bean name of the agent (context identifier)."}}},"ContentSource":{"type":"object","properties":{"name":{"type":"string","description":"Name or title of the content source."},"type":{"type":"string","description":"Type of content (e.g., \"document\", \"url\")."},"url":{"type":"string","format":"uri","description":"URL of the content source if applicable."}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"type":"string"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"string"}}}}}}}
```

## POST /api/v1/agent/add-file-knowledge

> Upload a file to the knowledge base (Admin only).

```json
{"openapi":"3.0.3","info":{"title":"Peoplelogic Agent API","version":"1.0.0"},"tags":[{"name":"Conversations","description":"The Directory API gives you access to Organizations, Accounts, Employees and Groups.  Every Entity within the subsequent API calls must have an Organization attached and API calls must be made with a User specific JWT."}],"servers":[{"url":"https://api.peoplelogic.dev"}],"paths":{"/api/v1/agent/add-file-knowledge":{"post":{"summary":"Upload a file to the knowledge base (Admin only).","tags":["Conversations"],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"schemas":{"AgentResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded."},"agent":{"$ref":"#/components/schemas/AgentProfile"},"reply":{"type":"string","description":"The agent's response message."},"sources":{"type":"array","items":{"$ref":"#/components/schemas/ContentSource"},"description":"Content sources (e.g., documents or URLs) cited in the response."},"confirming":{"type":"boolean","description":"True if the agent is asking for confirmation from the user."},"subtasks":{"type":"array","items":{"$ref":"#/components/schemas/AgentResponse"},"description":"Subtasks or follow-up responses (if the agent's response is composed of multiple parts)."},"conversation":{"type":"string","description":"Conversation ID this response is associated with (if any)."}},"required":["success","agent","reply"]},"AgentProfile":{"type":"object","properties":{"name":{"type":"string","description":"Agent name."},"persona":{"type":"string","description":"Short description of the agent's role/persona."},"avatar":{"type":"string","description":"URL or identifier for agent's avatar image."},"bio":{"type":"string","description":"Full biography of the agent."},"title":{"type":"string","description":"Agent title or designation."},"shortBio":{"type":"string","description":"Short bio snippet for quick reference."},"coordinator":{"type":"boolean","description":"Whether this agent is a coordinator (primary agent)."},"beanName":{"type":"string","description":"Internal bean name of the agent (context identifier)."}}},"ContentSource":{"type":"object","properties":{"name":{"type":"string","description":"Name or title of the content source."},"type":{"type":"string","description":"Type of content (e.g., \"document\", \"url\")."},"url":{"type":"string","format":"uri","description":"URL of the content source if applicable."}}}},"responses":{"NotFound":{"description":"Not Found","content":{"application/json":{"schema":{"type":"string"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"string"}}}}}}}
```

## POST /api/v1/agent/add-url-knowledge

> Add a URL to the knowledge base (Admin only).

```json
{"openapi":"3.0.3","info":{"title":"Peoplelogic Agent API","version":"1.0.0"},"tags":[{"name":"Conversations","description":"The Directory API gives you access to Organizations, Accounts, Employees and Groups.  Every Entity within the subsequent API calls must have an Organization attached and API calls must be made with a User specific JWT."}],"servers":[{"url":"https://api.peoplelogic.dev"}],"paths":{"/api/v1/agent/add-url-knowledge":{"post":{"summary":"Add a URL to the knowledge base (Admin only).","tags":["Conversations"],"requestBody":{"required":true,"content":{"text/plain":{"schema":{"type":"string","format":"uri"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"schemas":{"AgentResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded."},"agent":{"$ref":"#/components/schemas/AgentProfile"},"reply":{"type":"string","description":"The agent's response message."},"sources":{"type":"array","items":{"$ref":"#/components/schemas/ContentSource"},"description":"Content sources (e.g., documents or URLs) cited in the response."},"confirming":{"type":"boolean","description":"True if the agent is asking for confirmation from the user."},"subtasks":{"type":"array","items":{"$ref":"#/components/schemas/AgentResponse"},"description":"Subtasks or follow-up responses (if the agent's response is composed of multiple parts)."},"conversation":{"type":"string","description":"Conversation ID this response is associated with (if any)."}},"required":["success","agent","reply"]},"AgentProfile":{"type":"object","properties":{"name":{"type":"string","description":"Agent name."},"persona":{"type":"string","description":"Short description of the agent's role/persona."},"avatar":{"type":"string","description":"URL or identifier for agent's avatar image."},"bio":{"type":"string","description":"Full biography of the agent."},"title":{"type":"string","description":"Agent title or designation."},"shortBio":{"type":"string","description":"Short bio snippet for quick reference."},"coordinator":{"type":"boolean","description":"Whether this agent is a coordinator (primary agent)."},"beanName":{"type":"string","description":"Internal bean name of the agent (context identifier)."}}},"ContentSource":{"type":"object","properties":{"name":{"type":"string","description":"Name or title of the content source."},"type":{"type":"string","description":"Type of content (e.g., \"document\", \"url\")."},"url":{"type":"string","format":"uri","description":"URL of the content source if applicable."}}}},"responses":{"NotFound":{"description":"Not Found","content":{"application/json":{"schema":{"type":"string"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"string"}}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.peoplelogic.dev/api/agent-api/conversations.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.