API Overview

Introduction to the PraktickAI platform APIs — base URL, authentication, rate limits, and error handling. Early access.

On this page

Early access / preview. The PraktickAI APIs are in active development and available to design partners. Endpoints, fields, and limits may change before general availability. Request access from the admin console.

The PraktickAI platform gives your product two grounded AI services behind a single, consistent API: the Email API for reading a mailbox and drafting or auto-sending replies, and the Agent API for answering questions from your connected knowledge. Both share the same authentication, base URL, error format, and rate limits described on this page.

Base URL

All API requests are made to a single base URL over HTTPS. Requests over plain HTTP are rejected.

https://api.praktickai.app

The 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.