Agent API

Available email drafts and stored-context chat; other features and examples are a future API proposal.

On this page

Future API proposal — not available. The examples after the available-scope summary below are a planned contract, not live endpoints. Gmail/Outlook/IMAP connections, auto-send, live MCP sources, indexing, citations, conversations and streaming are not implemented. The examples, limits and isolation guarantees below do not describe today’s runtime.

Available scope: `POST /api/ai/v1/chat/` generates a response to one question from stored business context. `POST /api/ai/v1/email/draft/` drafts a reply from a manually submitted message and context, without mailbox access or sending. Outputs require human review. Check current fields and authentication in the live OpenAPI schema; do not use the planned examples below as an integration guide.

Proposed contract (not implemented)

https://api.praktickai.app/v1/agent

The agent answers from connected knowledge only. When it cannot find a grounded answer it says so and returns an empty `sources` array rather than guessing — see the `grounded` field below.

Send a message

POST /v1/agent/messages/

Ask the agent a question and receive a grounded answer. Pass a `conversation_id` to continue an existing thread, or omit it to start a new one.

Parameter	Type	Required	Description
message	string	yes	The user's question or instruction.
conversation_id	string	no	Continue a prior conversation for multi-turn context.
stream	boolean	no	When `true`, stream the answer as Server-Sent Events. Default `false`.
source_ids	array	no	Restrict the answer to a subset of connected sources.

curl https://api.praktickai.app/v1/agent/messages/ \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What is our refund window for annual plans?"
  }'

{
  "id": "msg_5f0c",
  "conversation_id": "cnv_2a",
  "answer": "Annual plans can be refunded within 30 days of purchase. After that, plans are non-refundable but you keep access until the end of the billing period.",
  "grounded": true,
  "sources": [
    {
      "source_id": "src_notion_07",
      "title": "Billing & Refund Policy",
      "url": "https://www.notion.so/acme/Billing-Refund-Policy",
      "snippet": "Annual plans are refundable within 30 days...",
      "connector": "notion"
    }
  ],
  "created_at": "2026-07-16T10:04:22Z"
}

Field	Type	Description
id	string	Message identifier, prefixed `msg_`.
conversation_id	string	Thread id — reuse it to keep context across turns.
answer	string	The grounded answer text.
grounded	boolean	`true` if the answer is backed by sources; `false` when the agent had no relevant knowledge.
sources	array	Passages the answer relied on — each with `source_id`, `title`, `url`, `snippet`, and `connector`.

Streaming

For chat-style UIs, set `stream: true` to receive the answer incrementally over Server-Sent Events (`Accept: text/event-stream`). Tokens arrive as `delta` events; a final `done` event carries the resolved `sources` and message id.

curl -N https://api.praktickai.app/v1/agent/messages/ \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{ "message": "Summarize the onboarding checklist", "stream": true }'

event: delta
data: {"text": "The onboarding checklist has "}

event: delta
data: {"text": "four steps: invite, connect, verify, deploy."}

event: done
data: {"id": "msg_77", "conversation_id": "cnv_2a", "grounded": true, "sources": [{"source_id": "src_gdrive_02", "title": "Onboarding Checklist", "connector": "google_drive"}]}

Render `delta` events as they arrive for a live typing effect, then attach the citation links from the final `done` event once the answer completes.

Manage knowledge sources

Sources are the connected content the agent is allowed to read. Connect them via MCP connectors (see the setup guide) and manage them through these endpoints.

GET /v1/agent/knowledge/sources/

List connected sources and their sync status.

curl https://api.praktickai.app/v1/agent/knowledge/sources/ \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx"

{
  "data": [
    {
      "source_id": "src_notion_07",
      "connector": "notion",
      "name": "Help Center",
      "status": "synced",
      "documents": 128,
      "last_synced_at": "2026-07-16T08:00:00Z"
    },
    {
      "source_id": "src_slack_01",
      "connector": "slack",
      "name": "#support channel",
      "status": "syncing",
      "documents": 0
    }
  ]
}

POST /v1/agent/knowledge/sources/

Connect a new source from an authorized MCP connector. Authorize the connector first in the admin console; then reference it here by `connector` and the `resource` you want to expose (a Notion database, a Slack channel, a Drive folder).

Parameter	Type	Required	Description
connector	string	yes	One of `notion`, `slack`, `google_drive` (more via MCP).
resource	string	yes	Connector-specific id of the content to index (database id, channel id, folder id).
name	string	no	A human-friendly label shown in the admin console.
access	string	no	Read scope — currently `read` only. The agent never writes to your sources.

curl https://api.praktickai.app/v1/agent/knowledge/sources/ \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "connector": "notion",
    "resource": "db_9f2c1a",
    "name": "Help Center"
  }'

{
  "source_id": "src_notion_07",
  "connector": "notion",
  "name": "Help Center",
  "status": "syncing",
  "access": "read",
  "created_at": "2026-07-16T10:10:00Z"
}

New sources start in `syncing` and become `synced` once indexed. The agent only uses a source once its status is `synced`.

Best practices

Keep conversations by reusing conversation_id so follow-up questions have context.
Always surface the returned sources in your UI so users can verify answers.
Use source_ids to scope answers when a workflow should only consult specific content.
Check the grounded flag before showing an answer — if false, offer to escalate to a human.