The PD AI Assistant API accepts a question or an agent goal from an authorised system. Use the endpoint displayed by this installation and keep the module API key in a header, not in the request URL.

Prepare the caller

Open PD Modules → PD AI Assistant → Settings → Advanced → API and copy the displayed Endpoint. Confirm the module key is configured and the intended provider is ready. These are separate requirements: a valid module key does not supply a provider account or quota.

Configure an HTTPS POST with Content-Type: application/json. Send the module key through X-Api-Key, or through Authorization: Bearer followed by that key. Do not send the provider’s API credential in its place.

Choose the intended request

1. For one question, send action: ask and a non-empty prompt.
2. For an agent task, send action: agent and a non-empty goal.
3. Keep the task specific and within what the caller is authorised to access.
4. Read the JSON result rather than treating any HTTP page as an answer.
5. Verify important facts or proposed actions against the actual record before relying on the response.

An ask response uses answer, while an agent response uses report when successful. Each request starts its own conversation input rather than continuing the staff chat transcript. Shared configured Memory can still influence the result.

Native reply and note proposals can require staff review, and unattended notifications can be proposals rather than sends. Additional tools have their own controls. A successful answer or report is not proof that a proposed business action has been completed.

Interpret a refusal

401 unauthorized calls for checking the module key and supported header. 400 no_prompt or no_goal needs the required body field. 429 rate_limited calls for pausing repeated calls. 503 not_configured points to provider configuration; 402 subscription_lapsed requires reviewing the module’s licence state. For 500 server_error, retain the original time and redacted symptom while your hosting team checks the failed stage.

An HTML login or challenge response is not the module’s successful JSON API result. Ask the network administrator to inspect the specific endpoint rather than disabling broad protections. Before retrying an ambiguous action, reconcile its actual outcome; repeated requests do not automatically share a deduplication token.

See the PD AI Assistant Blesta guide for related tasks, or explore PD AI Assistant.