HTTP API v1

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 executable storage connection. A configured BYO connection is rejected before the current runtime can touch data or ledgers.

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

The memory endpoints run the reference runtime: submitted text is stored encrypted, recall ranks stored memories by word overlap with the cue, and the rendered context is the selected memories' own text. No model runs, and responses say so in provenance and data_policy. They require an API key. A write returns not_retained until the account owner turns on Store memories sent through the API in Mind settings.

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."},
      "source": {"type": "external_application", "id": "conversation-42-message-7"}
    }
  }'

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

Not available yet. The infrastructure endpoints are part of contract v1 and described here so integrations can be built against it, but the hosted API does not serve them today. Calls return an error. Each row changes to Available when its route ships.

The health response requires provider, model_version, deployment_version (which may be null when no deployment identifier is available), and environment. Consumers should fail closed when any of these identity fields is missing or malformed.

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. v1 failure responses use error, code, request_id, retryable, and bounded details together with the correct HTTP status. Error bodies do not contain stack traces, secrets, or internal database identifiers.

{
  "error": "Authentication required. Provide an API Key or session token.",
  "code": "AUTHENTICATION_REQUIRED",
  "request_id": "req_123",
  "retryable": false,
  "details": {}
}

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.