API Overview
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)
Base URL
All API requests are made to a single base URL over HTTPS. Requests over plain HTTP are rejected.
https://api.praktickai.appThe API is versioned in the path. The current version is v1, e.g. `https://api.praktickai.app/v1/agent/messages`. We add fields in a backward-compatible way; breaking changes ship under a new version prefix.
Authentication
Authenticate every request with a Bearer API key in the `Authorization` header. Create and rotate keys in the admin console under Settings → API keys. Keys are scoped to a single workspace.
curl https://api.praktickai.app/v1/agent/messages \
-H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ "message": "How do I reset my password?" }'API keys carry full workspace access. Keep them server-side, never ship them in browser or mobile code, and rotate immediately if one leaks. Test keys are prefixed `pk_test_` and only touch sandbox data.
| Prefix | Environment | Notes |
|---|---|---|
| pk_live_ | Production | Operates on real mailboxes and knowledge sources. |
| pk_test_ | Sandbox | Isolated data, no outbound email is actually delivered. |
Requests and responses
Send and receive JSON. Set `Content-Type: application/json` on any request with a body. All URLs end with a trailing slash where a resource collection is addressed. Timestamps are ISO 8601 in UTC, and identifiers are opaque strings you should treat as case-sensitive.
Rate limits
During early access, limits are applied per API key. Every response includes rate-limit headers so you can back off gracefully.
| Header | Description |
|---|---|
| X-RateLimit-Limit | Maximum requests allowed in the current window. |
| X-RateLimit-Remaining | Requests remaining in the current window. |
| X-RateLimit-Reset | Unix timestamp when the window resets. |
| Scope | Default limit |
|---|---|
| Agent messages | 60 requests / minute |
| Email draft & send | 120 requests / minute |
| Knowledge & mailbox management | 30 requests / minute |
When you exceed a limit the API returns HTTP 429. Respect the X-RateLimit-Reset header and retry with exponential backoff. Need higher limits? Ask in the admin console.
Error format
Errors use standard HTTP status codes and a consistent JSON body. Always log the `request_id` — it lets support trace a specific call.
{
"error": {
"type": "invalid_request_error",
"code": "missing_field",
"message": "The 'message' field is required.",
"param": "message",
"request_id": "req_8f2a1c9d4e"
}
}| Status | type | Meaning |
|---|---|---|
| 400 | invalid_request_error | The request was malformed or missing a required field. |
| 401 | authentication_error | Missing or invalid API key. |
| 403 | permission_error | The key is valid but not allowed to perform this action. |
| 404 | not_found_error | The referenced resource does not exist. |
| 429 | rate_limit_error | Too many requests — slow down and retry. |
| 500 | api_error | Something went wrong on our side. Safe to retry. |
Where to go next
- Email API — connect a mailbox and draft or auto-send grounded replies.
- Agent API — send a message and get an answer grounded in your knowledge, with sources.
- Setup guide — connect Notion, Slack, and Google Drive via MCP, then deploy your agent.
Open the Email API reference, the Agent API reference, or follow the setup guide to connect your first knowledge sources.