API REFERENCE

Create a response

`POST /v1/agents/{agent_id}/responses`

shell

curl --request POST \
  "https://api.inceptiva.com/v1/agents/$INCEPTIVA_AGENT_ID/responses" \
  --header "Authorization: Bearer $INCEPTIVA_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: request-unique-id" \
  --data '{"message":"User question","conversation_id":null,"external_reference":"ticket-4821","metadata":{"source":"helpcenter"}}'

Field	Type	Required	Purpose
`message`	string	Yes	User input
`conversation_id`	UUID or `null`	No	Continue a known conversation
`external_reference`	string or `null`	No	Stable client correlation
`metadata`	object	No	Validated JSON trace data

The response contains conversation_id, response, and public citations. Replaying the same key and payload returns the stored result without charging usage again; a different payload returns 409.