Connect. Send. Recover.

1. Create a project and backend key

Sign in with Google, create a project and issue a key. Your project ID is also its reserved namespace. Keep the key on your server.

2. Submit a message

Replace YOUR_NAMESPACE and the hostname. Use one stable idempotency key for each logical operation.

curl https://YOUR_HOST/v1/agents/YOUR_NAMESPACE:demo/messages   -H 'Authorization: Bearer YOUR_API_KEY'   -H 'Content-Type: application/json'   -H 'Idempotency-Key: favorite-city-1'   -d '{"type":"set","payload":{"key":"favorite_city","value":"Madrid"}}'

A 202 response means the inbox accepted the message durably; it does not mean the handler has completed.

3. Read the receipt

GET the Location returned by submission, with the same Authorization header. Status moves from pending/processing to completed or failed. A completed receipt includes the stored reply.

Reuse the same retry key and payload after a lost response. A different payload with that key returns 409. Deduplication ends when the receipt is pruned.

Guarantees and limitations

Successful state-changing execution commits state and receipt together. Process death restores committed state. Handlers can be attempted more than once; external side effects need provider idempotency. A single-server pilot has downtime during replacement and recovery. Disk loss requires backup restore and may lose changes since the backup.

The MemoryAgent accepts set/get/delete/list. Custom Elixir handlers are trusted deployment code. Remote Node/Python handlers, durable scheduling and billing are not implemented.

Support and troubleshooting

For a failed request, retain the message ID, project ID, timestamp, HTTP status and deployment version. Check the receipt and retry guidance first. Never include API keys or private payloads in support reports.

Contact your deployment operator at gibranrodriguezluna@gmail.com.