Reference
HTTP API v1
The HTTP API is the canonical wire contract beneath the Palo SDK and CLI. Requests are JSON. Responses include an explicit contract version and operation state. Tenant and user scope come from the verified credential context.
https://api.mpalo.comv1application/jsonX-Request-Id and Idempotency-Key where supported.Authentication and headers
Send an API key as a bearer credential or in the API-key header accepted by the deployment. Read-only infrastructure routes also accept a signed browser session. Memory operations and metered smoke tests require an API key and an active storage connection.
Authorization: Bearer $PALO_API_KEY Content-Type: application/json X-Request-Id: request-optional-client-id Idempotency-Key: logical-write-event-42
Do not send session cookies or API keys to third-party logging services. The server must return neutral authentication failures and must not reveal internal identifiers or stack traces.
Memory endpoints
| Method | Path | Purpose | Retry note |
|---|---|---|---|
| POST | /api/v1/memory/write | Accept one memory event when storage, consent, and policy allow. | Use the same idempotency key for an uncertain retry. |
| POST | /api/v1/memory/recall | Retrieve and render related memories for a cue. | Retry according to retryable response and timeout policy. |
| DELETE | /api/v1/memory | Delete retained private-memory state for one namespace. | Confirm the namespace in the caller's workflow. |
curl -X POST https://api.mpalo.com/api/v1/memory/write \\
-H "Authorization: Bearer $PALO_API_KEY" \\
-H "Content-Type: application/json" \\
-H "Idempotency-Key: conversation-42-message-7" \\
-d '{
"contract_version": "v1",
"operation": "memory.write",
"namespace": "conversation",
"idempotency_key": "conversation-42-message-7",
"event": {"event_id": "message_7", "content": {"text": "The appointment moved to Monday."}}
}'curl -X POST https://api.mpalo.com/api/v1/memory/recall \\
-H "Authorization: Bearer $PALO_API_KEY" \\
-H "Content-Type: application/json" \\
-d '{"contract_version":"v1","operation":"memory.recall","namespace":"conversation","cue":{"text":"When is the appointment?"},"top_k":3}'Infrastructure endpoints
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/infrastructure/capabilities | Return enabled operations, guarantees, and limitations. |
| GET | /api/v1/infrastructure/health | Return required service and deployment readiness. |
| GET | /api/v1/infrastructure/status | Return combined health, monitoring, anomaly, and consent state. |
| GET | /api/v1/infrastructure/events | Return redacted event history with limit and offset. |
| GET | /api/v1/infrastructure/usage | Return request volume, operations, charges, and source-of-truth metadata. |
| GET | /api/v1/infrastructure/export | Return a JSON export for the selected namespace. |
curl "https://api.mpalo.com/api/v1/infrastructure/status" \\ -H "Authorization: Bearer $PALO_API_KEY" curl "https://api.mpalo.com/api/v1/infrastructure/events?limit=100&offset=100" \\ -H "Authorization: Bearer $PALO_API_KEY"
Responses and errors
Success responses contain operation-specific payload keys. Failure responses use an error string and the correct HTTP status. Optional details contains field-level information. Error bodies do not contain stack traces, secrets, or internal database identifiers.
{
"error": "Authentication required. Provide an API Key or session token.",
"details": {"request_id": "req_123"}
}A 200 response may be retained, not_retained, or no_data. Check the operation state, provenance, and usage before treating the call as complete.
OpenAPI and schemas
Use the published OpenAPI document to generate clients or validate requests. The document and response schemas are versioned with the infrastructure contract.
Was this page helpful?
Your feedback helps us improve our documentation.