A message from
your agent.

POST /api/agent-enquiries accepts a required subject and message, with optional representative and agent objects. This example uses illustrative identities.

{
  "subject": "Private AI system for field work",
  "message": "My user would like to discuss an AI system that can work at remote sites. What information would help you assess the assignment?",
  "representative": {
    "name": "Alex Example",
    "email": "alex@example.org",
    "organisation": "Example Organisation",
    "role": "Project lead"
  },
  "agent": {
    "name": "Research assistant",
    "software": "Your agent software"
  }
}

# Save the JSON example as enquiry.json; use only details you know.
# Run this key-generation line ONCE, before the first send (requires openssl).
umask 077
openssl rand -base64 32 | tr '+/' '-_' | tr -d '=\n' > enquiry-key.txt
# Keep enquiry-key.txt and enquiry.json private. On retry, skip key generation.
IDEMPOTENCY_KEY="$(cat enquiry-key.txt)"
curl --silent --show-error --fail-with-body \
  --request POST 'https://freelifeai.com/api/agent-enquiries' \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --header 'Content-Type: application/json' \
  --data-binary @enquiry.json \
  --output receipt.json

Before sending, generate 32 random bytes encoded as unpadded base64url and save this 43-character secret. Send it in the required Idempotency-Key header with your saved JSON submission.

A new enquiry returns 201 with reference, access_token, status, status_url, follow_up_url, poll_after_seconds: 60, duplicate: false and expires_at.

If delivery is uncertain, repeat the same key and submission. An identical retry returns 200 with duplicate: true and the same access token. Different content with the same key returns 409. Keep both the request key and receipt private; never make a new key just because a response was lost.

Use GET /api/agent-enquiries/{reference} with the bearer token. Keep the token in the Authorization header, never in a URL or public log.

# Read these values from the private receipt (requires jq).
REFERENCE="$(jq -r '.reference' receipt.json)"
ACCESS_TOKEN="$(jq -r '.access_token' receipt.json)"
curl --silent --show-error --fail-with-body \
  'https://freelifeai.com/api/agent-enquiries/'"$REFERENCE" \
  --header "Authorization: Bearer $ACCESS_TOKEN"

The response includes the original submission, followups, published replies and current status: received, under_review, replied or closed. Poll no more often than once every 60 seconds.

If a larger history returns next_history_cursor, wait for the polling interval, then read the same endpoint with ?history_cursor={next_history_cursor}. Append its messages until the cursor is empty. Keep the bearer token in the header.

Enquiries expire after 180 days without a new sender message or published reply. Reading does not extend the period. Your response includes the current expires_at date.

Send a message and a client_message_id UUID. Choose a new UUID for each new message and save it before sending.

# Choose a new UUID for each new message; reuse it and the exact body on retry.
curl --silent --show-error --fail-with-body \
  --request POST 'https://freelifeai.com/api/agent-enquiries/'"$REFERENCE"'/messages' \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"message":"The system needs to work without internet access.","client_message_id":"8d5bfdda-6645-45bc-a9e4-4a00a4914dd2"}'

If delivery is uncertain, resend the same UUID and exact message. The first delivery returns 201; an identical retry returns 200 with duplicate: true. Reusing a UUID for different content returns 409. Closed enquiries reject follow-ups.

Errors use {"error":{"code":"…","message":"…"}}. Respect Retry-After on rate-limit responses. Only conversation reads accept the documented history_cursor query parameter; keep credentials in headers.