Workspace Agent Chat

The workspace agent is Postsiva’s conversational interface to social management. One turn can list accounts, generate content, publish posts, read analytics, reply to comments, and more — the agent picks tools automatically. The website chat endpoint uses the same LangGraph agent as WhatsApp, Instagram DM, and Facebook Messenger, with channel=website.

Authentication

Method	Headers
API key (recommended)	`X-API-Key: psk_live_YOUR_KEY`
JWT session	`Authorization: Bearer YOUR_JWT` + `X-Workspace-Id: YOUR_WORKSPACE_UUID`

With an API key, workspace is inferred from the key. Optional workspace_id in the request body must match the authenticated workspace.

Agent turns consume AI credits (agent_turn = 2 credits, plus per-tool costs). Requires a plan with agent access (Pro for WhatsApp; website chat follows workspace AI composer limits).

Send a message

`POST /workspace-agent/website/chat`

Run one agent turn. Provide at least one of: text, image_url, video_url, image_media_id, video_media_id. Request body

Field	Type	Required	Description
`text`	string	No*	User message
`image_url`	string	No*	Public HTTPS image URL
`video_url`	string	No*	Public HTTPS video URL
`image_media_id`	UUID	No*	Postsiva unified media ID (image from media library)
`video_media_id`	UUID	No*	Postsiva unified media ID (video)
`workspace_id`	UUID	No	Must match authenticated workspace if sent

* At least one field must be non-empty.

curl -X POST "https://backend.postsiva.com/workspace-agent/website/chat" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: psk_live_YOUR_KEY" \
  -d '{"text": "What social accounts are connected to my workspace?"}'

With media

curl -X POST "https://backend.postsiva.com/workspace-agent/website/chat" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: psk_live_YOUR_KEY" \
  -d '{
    "text": "Write an Instagram caption for this photo and save as draft",
    "image_url": "https://cdn.example.com/launch.jpg"
  }'

Response example

{
  "success": true,
  "agent_response_json": "{\"response\": \"You have LinkedIn and Instagram connected.\", \"append_footer\": false}",
  "parsed": {
    "response": "You have LinkedIn and Instagram connected.",
    "tables_markdown": null,
    "charts_markdown": null,
    "mermaid_diagrams": null,
    "image_urls": [],
    "video_urls": [],
    "append_footer": false
  }
}

parsed

object

Convenience parse of agent_response_json. Primary field is response (markdown-friendly text). Optional: tables_markdown, charts_markdown, mermaid_diagrams, image_urls, video_urls, append_footer.

Agent tools

The agent has access to the same tool layer as MCP (minus web_search_duckduckgo on some channels):

Tool	Capability
`get_accounts`	List connected platforms or load one profile
`get_queued_posts`	Scheduled posts and drafts
`get_user_posts`	Recent posts per platform
`get_unified_analytics`	Cross-platform analytics
`get_comments`	Comments on recent posts
`reply_to_comment`	Reply to a comment thread
`manage_platform_connection`	OAuth connect/disconnect
`idea_to_content`	Idea → post copy
`content_to_image`	Copy → images
`media_to_content`	Image/video URL → captions
`analyze_media`	Describe image/video URL
`publish`	Publish, draft, or schedule
`clear_workspace_chat_history`	Clear agent memory (WhatsApp/website; not on MCP)

See the full MCP tool catalog for argument details.

List chat history

`GET /user-agent-chats`

Returns archived user/assistant turns stored in user_agent_chats. Newest first. Query parameters

Parameter	Type	Default	Description
`channel`	string	—	Filter by surface: `whatsapp`, `instagram_dm`, `facebook_messenger`, `website`, `mobile`
`since`	ISO 8601	—	Include turns with `created_at >= since`
`until`	ISO 8601	—	Include turns with `created_at <= until`
`limit`	integer	`20`	Page size (1–100)
`offset`	integer	`0`	Pagination offset

curl -G "https://backend.postsiva.com/user-agent-chats" \
  -H "X-API-Key: psk_live_YOUR_KEY" \
  --data-urlencode "channel=website" \
  --data-urlencode "limit=20" \
  --data-urlencode "offset=0"

Response example

{
  "success": true,
  "items": [
    {
      "id": 42,
      "workspace_id": "aaa01a56-e769-44a6-87bf-cf6dfb9e7a27",
      "created_at": "2026-04-04T12:00:00",
      "turn": {
        "channel": "website",
        "user": {
          "text": "Text:\nWhat accounts are connected?",
          "at": "2026-04-04T11:59:58.123456+00:00"
        },
        "assistant": {
          "text": "You have LinkedIn and Instagram connected.",
          "raw": "{\"response\": \"You have LinkedIn and Instagram connected.\"}",
          "at": "2026-04-04T12:00:01.000000+00:00"
        }
      }
    }
  ],
  "total": 150,
  "limit": 20,
  "offset": 0
}

total

integer

Count of rows matching filters (ignores limit/offset).

Clear chat history

`DELETE /user-agent-chats`

Deletes all archived turns for the workspace (every channel) and clears LangGraph thread memory. Equivalent to asking the agent to run clear_workspace_chat_history.

curl -X DELETE "https://backend.postsiva.com/user-agent-chats" \
  -H "X-API-Key: psk_live_YOUR_KEY"

Response example

{
  "success": true,
  "deleted_archived_turns": 42
}

This is destructive and cannot be undone. The agent will not remember prior turns on the next message.

Voice transcription (optional)

`POST /workspace-agent/website/transcribe`

Upload audio (e.g. audio/webm) to get a text transcript. Send the transcript as text in /chat. Requires server-side Pollinations configuration.

Errors

Status	Meaning
`401`	Invalid or revoked API key / JWT
`403`	`workspace_id` body mismatch
`422`	No text or media fields in body
`500`	Agent invocation failed
`502`	Agent returned empty response

REST vs MCP vs agent chat

	Agent chat	MCP	REST
Caller	Your app with natural language	External AI agent	Your code
Tool selection	Agent decides	Client agent decides	You call endpoints
Memory	Per-workspace thread	Stateless	Stateless
Best for	Embedded chat UI, copilots	Cursor, n8n AI Agent	Deterministic pipelines

MCP overview

Connect Cursor or n8n

AI content APIs

Direct generate endpoints

GPT Actions

ChatGPT Custom GPT setup

​Authentication

​Send a message

​POST /workspace-agent/website/chat

​Agent tools

​List chat history

​GET /user-agent-chats

​Clear chat history

​DELETE /user-agent-chats

​Voice transcription (optional)

​POST /workspace-agent/website/transcribe

​Errors

​REST vs MCP vs agent chat

​Next

MCP overview

AI content APIs

GPT Actions

Authentication

Send a message

`POST /workspace-agent/website/chat`

Agent tools

List chat history

`GET /user-agent-chats`

Clear chat history

`DELETE /user-agent-chats`

Voice transcription (optional)

`POST /workspace-agent/website/transcribe`

Errors

REST vs MCP vs agent chat

Next