AI Prompt Proposal

AIPromptProposal

{
    "id": "<string>",
    "customer_id": "<string>",
    "ai_id": "<string>",
    "audit_ids": ["<string>"],
    "basis_prompt_history_id": "<string>",
    "original_prompt": "<string>",
    "proposed_prompt": "<string>",
    "rationale": "<string>",
    "status": "<string>",
    "error": "<string>",
    "applied_prompt_history_id": "<string>",
    "tm_create": "<string>",
    "tm_update": "<string>",
    "tm_delete": "<string>"
}

• id (UUID): The proposal record’s unique identifier.

• customer_id (UUID): The customer who owns this proposal. Obtained from the id field of GET /customers.

• ai_id (UUID): The AI configuration whose prompt is being improved. Obtained from the id field of GET /ais.

• audit_ids (array of UUIDs): The AI audit records used as evidence for the proposal. Obtained from the id field of GET /aiaudits.

• basis_prompt_history_id (UUID): The prompt history snapshot used as the basis for the proposal. Obtained from the id field of GET /ais/{id}/prompt_histories.

• original_prompt (string): The basis prompt text captured at proposal creation time.

• proposed_prompt (string): The improved prompt generated by the evaluator. Empty until status is completed.

• rationale (string): The evaluator’s explanation for the proposed change. Empty until status is completed.

• status (enum string): The proposal’s current lifecycle state. See Status.

• error (enum string): Machine-readable error code set when status is failed or expired. Empty otherwise. See Error.

• applied_prompt_history_id (UUID): The new prompt history ID created when the proposal was accepted. Empty until status is accepted.

• tm_create (string, ISO 8601): Timestamp when the proposal was created.

• tm_update (string, ISO 8601): Timestamp of the last update.

• tm_delete (string, ISO 8601): Timestamp when the proposal was deleted. Set to 9999-01-01 00:00:00.000000 if not deleted.

Note

Proposal Lifecycle

Proposal generation is asynchronous. After triggering a proposal, poll the record until status changes from progressing to completed or failed. The proposed_prompt and rationale fields are populated only when status is completed. Once completed, the proposal can be accepted (applied to the AI) or rejected. Proposals that are not actioned can later transition to expired if the basis prompt drifts.

Status

All possible values for the status field:

Status	Description
progressing	The proposal evaluation is currently running
completed	The proposal evaluation succeeded; proposed_prompt is available for review
failed	The proposal evaluation could not be completed; see error for the reason
accepted	The proposal was accepted and applied to the AI’s current prompt
rejected	The proposal was explicitly rejected
expired	The basis prompt drifted before the proposal was actioned

Error

All possible values for the error field (non-empty only when status is failed or expired):

Error	Description
invalid_audit_set	The provided audit set was empty, exceeded the limit, or contained mismatched records
audit_prompt_version_mismatch	One or more audits referenced a different prompt version than the AI’s current prompt
prompt_version_drifted	The AI’s prompt changed between proposal creation and accept
evaluator_unavailable	The external evaluator service was unreachable
invalid_evaluator_response	The evaluator returned an unrecognisable response
cancelled	The proposal was cancelled before completion

Example

{
    "id": "e5f6a7b8-c9d0-1234-efab-c12345678901",
    "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "ai_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "audit_ids": [
        "d4e5f6a7-b8c9-0123-defa-b12345678901",
        "d4e5f6a7-b8c9-0123-defa-b12345678902"
    ],
    "basis_prompt_history_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "original_prompt": "You are a helpful support assistant.",
    "proposed_prompt": "You are a helpful and empathetic support assistant. Always confirm the customer's issue before proposing a fix.",
    "rationale": "The audits showed the assistant moved to solutions before fully acknowledging the customer's concern.",
    "status": "completed",
    "error": "",
    "applied_prompt_history_id": "00000000-0000-0000-0000-000000000000",
    "tm_create": "2026-01-15T10:00:00.000000Z",
    "tm_update": "2026-01-15T10:00:45.000000Z",
    "tm_delete": "9999-01-01T00:00:00.000000Z"
}