# Mpalo API Documentation

Canonical documentation origin: https://api.mpalo.com
API contract: v1
Implementation status: mock

Use the page status and implementation fields as authoritative. The current customer path is a production-shaped deterministic text-memory contract fixture. It does not execute Palo Bloom, create customer-facing embeddings, perform semantic vector search, train a shared model, or perform aggregate learning.
Current runtime: execution_mode=mock, provider=mpalo-local-mock, model_version=deterministic-lexical-v1, model_execution=false.
BYO storage and Mpalo-managed external LLM connections are not runtime capabilities in the current customer path. The application manages its downstream model.

Prefer JSON output for automation. Never infer undocumented capabilities. Never expose credentials. Treat destructive operations and billing actions as state-changing operations.

## Documentation pages

- [Documentation home](https://api.mpalo.com/) [status=preview, audience=all]
- [Get started](https://api.mpalo.com/get-started) [status=preview, audience=developer]
- [Core concepts](https://api.mpalo.com/concepts) [status=preview, audience=developer]
- [Infrastructure](https://api.mpalo.com/infrastructure) [status=mock, audience=developer]
- [SDKs](https://api.mpalo.com/sdks) [status=preview, audience=developer]
- [Python SDK](https://api.mpalo.com/sdks/python) [status=preview, audience=developer]
- [HTTP API reference](https://api.mpalo.com/reference/http) [status=preview, audience=developer]
- [Production integration guide](https://api.mpalo.com/guides/production) [status=preview, audience=developer]
- [Agents and automation guide](https://api.mpalo.com/guides/agents) [status=preview, audience=agent]
- [Errors and retries](https://api.mpalo.com/reference/errors) [status=preview, audience=developer]
- [Palo Bloom](https://api.mpalo.com/bloom) [status=preview, audience=researcher]
- [Palo CLI](https://api.mpalo.com/cli) [status=preview, audience=developer]
- [Use cases](https://api.mpalo.com/use-cases) [status=preview, audience=all]
- [System status](https://api.mpalo.com/status) [status=live, audience=all]

## Page content

### Documentation home

URL: https://api.mpalo.com/
Status: preview

Current runtime: mock API contract v1
These pages document a production-shaped interface while the hosted runtime is in mock mode. Mock calls do not execute Palo Bloom, do not perform aggregate learning, and use sandbox billing. Use test data only.
Check system status before treating an operation as production-ready.
Welcome
Mpalo API documentation
The API is a production-shaped interface for Mpalo's experience-aware memory infrastructure. These docs distinguish the current deterministic runtime from the Palo Bloom architecture in development, so you can build against what exists and see what is not yet available.
Get started Inspect infrastructure
What is available today
The hosted v1 customer path currently runs a deterministic text-memory runtime. It accepts text, persists submitted text when the required storage and consent conditions are met, retrieves related records with tenant-scoped lexical ranking, renders selected stored text as context, and exposes request, usage, billing, export, deletion, health, and anomaly surfaces.
Inspectable runtime
See provider, execution mode, capability status, request quality, and operational history.
Versioned API
Use the same request and response contract from HTTP, the SDK, or the Palo CLI.
Clear boundaries
Separate control-plane configuration, memory operations, observability, and research direction.
Data and model boundary
The current mock runtime is a service fixture for testing the API path. It does not execute Palo Bloom, create customer-facing embeddings, perform semantic vector search, train a shared model, or perform aggregate learning. Its usage and charge records are sandbox records.
What a current memory request means
A write may store the submitted text in the managed mock path after authentication, storage attachment, consent, and policy checks. A recall ranks stored records lexically and may return selected stored text as context. The response identifies the provider, execution mode, model version, capability status, retention state, and usage state. An unspecified model variant means that no Palo model executed.
See Infrastructure for the current capability matrix and Mpalo's trust materials for policy and legal terms. Claims about encryption, retention, ownership, provider execution, or universal erasure must be read from the applicable policy and contract, not inferred from this preview.
Start with a real contract
The quickest route is to read the current state, install an interface, authenticate, attach an active storage connection, and run the mock example with its provenance and usage receipt visible.
Get started
Install the Python SDK or Palo CLI and make the first authenticated request.
SDKs
Use typed Python resources with the same response contracts as the HTTP API.
Palo CLI
Operate memory, Mind Platform, infrastructure, profiles, and JSON automation output.
Capability status
A route can exist before the intended learned capability behind it is deployed. The documentation uses explicit statuses so a contract fixture is never presented as Palo Bloom execution.
Area | Current status | Meaning
Text persistence | available_mock | Current managed mock behavior, subject to storage and consent checks.
Lexical retrieval | available_mock | Deterministic tenant-scoped ranking over retained text.
Embeddings and vector search | not_deployed | No customer-facing vector index is attached to the current path.
Traversal and mapping | contract_stage | Response and attribution shapes exist for testing, not learned behavior.
BYO storage execution | control_plane_only | Connections can be configured, but v1 memory requests do not dispatch to them.
Palo Bloom execution | not_deployed | The model adapter is in development and is not used by the hosted customer path.
Developer hub
Follow the path that matches your work. The public pages stay focused on current behavior and documented contracts. The unresolved infrastructure roadmap remains an internal engineering record.
Production integration
Plan authentication, idempotency, deletion, error handling, and environment separation.
Agents and automation
Keep machine output stable, preserve provenance, and avoid scraping terminal presentation.
Errors and retries
Use error envelopes, request IDs, retryable flags, and idempotency keys correctly.
System status
Check public service availability separately from tenant-scoped infrastructure telemetry.

### Get started

URL: https://api.mpalo.com/get-started
Status: preview

Current runtime: mock API contract v1
These pages document a production-shaped interface while the hosted runtime is in mock mode. Mock calls do not execute Palo Bloom, do not perform aggregate learning, and use sandbox billing. Use test data only.
Check system status before treating an operation as production-ready.
Start here
Build your first Palo integration
The Palo API gives an application a memory boundary. Your application supplies the text, identity, namespace, and external model workflow. The API returns a versioned memory result, provenance, usage, and an explicit state.
Use the SDK
Typed request and response handling for application code.
Use the CLI
Interactive operations, diagnostics, exports, and agent-friendly JSON.
Use HTTP
Direct integration against the stable v1 contract.
1. Install a client
Choose the interface that matches the job. The Python package and the Palo CLI share the same API boundary, credentials, idempotency rules, and response states.
python -m pip install mpalo-sdk
python -m pip install palo-spring
palo --version
2. Authenticate without exposing secrets
Create an API key in the Mind Platform and store it in your process environment or a secret manager. The CLI also supports a browser session for control-plane actions. A session is not a substitute for an API key on metered memory operations.
export PALO_API_KEY='mpalo_...'
export PALO_BASE_URL='https://api.mpalo.com'
Never put a live key in source control, issue text, screenshots, URLs, or browser-side JavaScript.
If a key is exposed, revoke it and create a replacement. The full secret is shown only at creation time.
For a local CLI session, run palo auth login. A browser callback saves a session credential in the local keyring or Palo credential file. Run palo auth to inspect the local credential state.
3. Make a first request
Memory writes require an active memory storage connection attached to the credential. The current v1 contract accepts a text event, namespace, timestamp, and idempotency key. The result tells you whether the event was retained.
from palo import Palo

client = Palo(api_key="your-api-key")
result = client.memory.write(
    "The user changed the appointment to Monday afternoon.",
    namespace="conversation",
    idempotency_key="conversation-42-message-7",
)
print(result.state, result.decision)
curl 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","event":{"event_id":"message_7","occurred_at":"2026-08-28T10:00:00Z","content":{"text":"The user changed the appointment to Monday afternoon."}}}'
palo memory write "The user changed the appointment to Monday afternoon" \\
  --namespace conversation \\
  --idempotency-key conversation-42-message-7
Deterministic contract fixture output:
Next steps
Learn the model
Understand storage, scope, provenance, usage, and lifecycle states.
Use Python
Read typed memory and infrastructure examples.
Operate from the terminal
Configure profiles, inspect health, export JSON, and automate safely.

### Core concepts

URL: https://api.mpalo.com/concepts
Status: preview

Current runtime: mock API contract v1
These pages document a production-shaped interface while the hosted runtime is in mock mode. Mock calls do not execute Palo Bloom, do not perform aggregate learning, and use sandbox billing. Use test data only.
Check system status before treating an operation as production-ready.
Foundations
One contract, three interfaces
The SDK, CLI, and direct HTTP client are different ways to reach the same tenant-scoped API. They should not invent separate semantics. The server derives account scope from the verified credential, validates the request, executes the configured runtime, records usage, and returns provenance with the result.
Control plane
Account, API keys, memory storage connections, limits, usage, billing, and settings.
Data plane
Memory write, recall, and delete operations, with rendering and future stages reported in the response when the runtime supports them.
Observability plane
Health, capabilities, events, metrics, anomaly signals, and exports.
Credentials and scope
API keys are application credentials for memory calls and tenant-scoped telemetry. A browser session is an account credential for interactive Mind Platform control-plane work. The API never treats a browser session as an API key for a data-plane memory call, and an operator capability is separately required for privileged simulation.
Credential | Typical use | Do not assume
API key | Memory operations, application integrations, metered requests. | It can perform account administration without the required role.
Browser session | CLI login and Mind Platform controls. | It can replace an API key on data-plane or tenant telemetry routes.
Simulation token | Authorized operator simulations in an explicitly enabled environment. | It bypasses consent, authorization, billing policy, or production controls.
Credential precedence is observable.
Use palo auth or --json to see which local source is selected without revealing the secret. Never log full authorization headers.
Memory stores, namespaces, and scope
A memory operation needs an active storage connection. The storage connection identifies where retained memory state lives. A namespace separates application data within that connection. User and organization scope are derived from the authenticated account, not accepted as an arbitrary cross-tenant parameter.
Managed storage
Mpalo-managed memory storage selected through the Mind Platform or CLI.
BYO storage
A customer-controlled storage connection represented in the control plane. Current v1 memory requests do not execute against it.
Namespace
A caller-selected logical partition, such as conversation or support.
Decision
The write result states whether the event was retained and why. A successful HTTP response is not identical to retained memory.
The mock runtime uses deterministic lexical fixtures for predictable tests. It can exercise the request, persistence, retrieval, response, usage, and deletion path, but it is not evidence of Palo Bloom model quality, embeddings, semantic vector search, or production latency.
Usage and billing
Every accepted customer request should have a request record, operation attribution, usage units when measurable, and a billing state. The CLI and Mind Platform read these records from the backend. In the current mock environment, charges are sandbox records and model execution is disabled. A fixture may return no units or no charge when the operation did not run a model.
State | Meaning | Operator action
observed | A request was measured, including failures and blocked attempts where policy allows. | Inspect request count, errors, latency, and event history.
billable | The accepted operation produced billable usage under the active pricing version. | Compare usage records with immutable charge records.
no_data | No measurable requests or pricing data exist in the selected window. | Do not interpret it as zero cost for a different window.
void | A previously recorded charge was voided through the billing ledger. | Keep the original request and charge history for auditability.
Reliability vocabulary
Clients should preserve request IDs, send idempotency keys on retried writes, respect retryable flags, and keep response state separate from transport status. A 200 response can describe a retained event, a safe replay, or a no-data result. A 503 response means the caller should follow the documented retry policy and inspect the request ID.
try:
    result = client.memory.write(text, idempotency_key="event-42")
except TimeoutError:
    # Retry with the same idempotency key.
    result = client.memory.write(text, idempotency_key="event-42")

### Infrastructure

URL: https://api.mpalo.com/infrastructure
Status: mock

Current runtime: mock API contract v1
These pages document a production-shaped interface while the hosted runtime is in mock mode. Mock calls do not execute Palo Bloom, do not perform aggregate learning, and use sandbox billing. Use test data only.
Check system status before treating an operation as production-ready.
Operations
Inspectable Infrastructure
The infrastructure surface answers a practical question: what happened to a request, where did it run, what did it use, and can the result be trusted? The API, SDK, and CLI expose the same status model so a developer can move from a local test to a deployed service without changing the meaning of telemetry.
The request path
1. Verify
Resolve the API key or session, tenant scope, role, and request identity.
2. Authorize
Check route permission, storage attachment, consent, rate limits, and simulation policy.
3. Execute
Run the enabled memory operation. The current hosted path provides deterministic text persistence, lexical retrieval, stored-text rendering, deletion, or an explicit contract fixture.
4. Record
Persist request, provenance, operations, usage, charge state, anomaly inputs, and audit information.
5. Respond
Return a stable response envelope with request ID, state, retryability, and operation-specific fields.
A control-plane operation such as listing keys uses the Mind Platform routes. A data-plane memory operation uses the memory contract. Infrastructure routes report the state of both paths without giving a caller a way to invent tenant scope.
Runtime modes and capability truth
Do not infer implementation from a command name or a successful HTTP status. Read execution_mode, provider, model_version, and capability_status from the response. The capabilities endpoint is the source of truth for what the deployment can currently execute.
Field | What it answers | Mock example
execution_mode | Which runtime path accepted the request. | mock
provider | Which runtime provider produced the response. | mpalo-local-mock
model_version | Which implementation version was attributed. | deterministic-lexical-v1
capability_status | Whether the result is a live capability, contract fixture, or unavailable operation. | contract_fixture
An unspecified model variant in a mock response means no Palo model executed. It is not a hidden model selection and it must not be billed as model usage. When a deployed model executes, its variant and measured operation units belong in provenance and usage.
Capability status
The deployment status and the API contract are related but not identical. A response shape can exist before the implementation it describes. Check the capability status before treating a field as evidence of model execution.
Capability | Status | Current evidence
Text persistence | available_mock | Submitted text can be retained after storage, consent, and policy checks.
Lexical retrieval | available_mock | Deterministic tenant-scoped ranking over retained text.
Stored-text rendering | available_mock | Selected retained text can be returned as context.
Embeddings and vector search | not_deployed | No customer-facing vector representation or index is attached.
Traversal and mapping | contract_stage | Response and attribution shapes exist for wiring, not learned behavior.
BYO storage execution | control_plane_only | Connections can be configured, but memory requests do not dispatch to them.
Mpalo-managed external LLM | not_available | The integration route is disabled. Applications manage downstream models.
Physical inputs | research | No public capture, subject-consent, or safety contract exists.
Memory operations
The v1 infrastructure contract covers the current memory path used by the SDK and CLI. Write returns the retention decision and representation status. Recall returns related retained records, a rendered context when available, and the ranking basis. Delete reports the affected namespace and retained state. Traversal and mapping have contract-stage fields for compatibility, but are not learned capabilities in the current runtime.
Recall
Find related memories and return the retrieval outcome.
Traversal
Follow related memory structure when the runtime enables it.
Mapping
Relate memory representations to the operation that produced them.
curl https://api.mpalo.com/api/v1/infrastructure/status \\
  -H "Authorization: Bearer $PALO_API_KEY"
palo infra status
palo infra health
palo infra metrics
palo infra anomalies
Deterministic status fixture:
Health, metrics, anomalies, and events
Use health for service availability and deployment metadata. Use status for the combined snapshot. Use metrics or usage for measured request quality and ledger state. Use anomalies for thresholded signals. Use events for redacted history and pagination. These views share a backend record but answer different questions: health describes readiness, metrics aggregate request history, anomalies interpret thresholds, and events preserve individual operational records.
Surface | CLI | Use it when
Capabilities | palo infra capabilities | You need to discover enabled operations and declared limitations before calling.
Health | palo infra health | You need to know whether required services and storage are reachable.
Metrics | palo infra metrics | You need deployment attribution, latency percentiles, request quality, and operation mix.
Anomalies | palo infra anomalies | You need thresholded signals with severity, observed value, and threshold.
Events | palo infra events --limit 100 --offset 0 | You need redacted request history beyond the first page.
Export | palo infra export | You need a JSON snapshot for an incident, audit, or offline analysis.
Events are paginated. The default page is limited for terminal safety. Increase --limit up to the API maximum, use --offset for the next page, or request JSON and paginate in a script. The CLI interactive view supports keyboard navigation where a full-screen event browser is available. Automation should use JSON rather than scraping designed terminal output.
Usage and billing are part of the infrastructure path
An operation is not complete from an infrastructure perspective until its usage and billing state are explainable. The request record is the source for accepted calls. Operation records explain units. Charge records explain recorded, invoiced, unbilled, or void state. Pricing is resolved at request acceptance and must remain attributable to its pricing version.
Mock billing.
The mock runtime can exercise ledger aggregation with sandbox records. No live customer charge should be inferred from a mock response. A response with no operation units means that no billable model operation was measured for that request.
palo infra usage --lookback-minutes 15 --json
palo mind usage summary --json
  palo mind billing --json
Readiness and declared limitations
Limitations should be returned by the deployment capability and status contract, not treated as permanent folklore in a client. A client may present them in a friendly design, but it must preserve the machine-readable values. When the runtime changes, its provider, version, capabilities, limitations, and readiness state change together.
Readiness signal | Interpretation
available: true | The required service answered the health check. This does not prove model quality or billing readiness.
state: no_data | The selected window has no measured records. It is not the same as a healthy zero-volume production period unless the window and source are known.
anomaly_count: 0 | No configured signal crossed its threshold in the selected history. It is not a security or correctness guarantee.
production_ready: false | The documentation or deployment is not authorized to represent itself as public paid production.
For a release review, record the status snapshot, contract version, deployment version, schema version, test results, and database health result together. A green mock smoke test is valuable for wiring and regression detection. It is not a production launch gate by itself.

### SDKs

URL: https://api.mpalo.com/sdks
Status: preview

Current runtime: mock API contract v1
These pages document a production-shaped interface while the hosted runtime is in mock mode. Mock calls do not execute Palo Bloom, do not perform aggregate learning, and use sandbox billing. Use test data only.
Check system status before treating an operation as production-ready.
Build with Palo
SDKs that preserve the API contract
The SDK is a typed convenience layer over the Mpalo HTTP API. It validates common inputs, resolves credentials, sends request identifiers, parses the response contract, and exposes both raw and structured values where that is useful for an application.
Client lifecycle
Instantiate one client per application configuration and reuse it. Configure the API key through a secret manager or environment variable. Set an explicit base URL only for a controlled test environment. Configure timeout and retry behavior for your workload, then close the client when the language runtime requires it.
from palo import Palo

client = Palo(
    api_key="your-api-key",
    timeout=30,
    max_retries=2,
)

health = client.infrastructure.health()
print(health.status, health.execution_mode)
from palo import AsyncPalo

async with AsyncPalo(api_key="your-api-key") as client:
    health = await client.infrastructure.health()
    print(health.status, health.execution_mode)
The package also contains a compatibility PaloClient and AsyncPaloClient surface. Use it for existing integrations while moving new code to the versioned resource surface documented here.
Memory API
The versioned resource is client.memory. It exposes write, recall, and delete for the infrastructure v1 contract. The memory store connection is configured on the API key or account. The request does not select an arbitrary external LLM and cannot cross tenant scope.
write = client.memory.write(
    "The user prefers a quiet workspace.",
    namespace="preferences",
    idempotency_key="preferences-user-42-1",
)

if write.decision.get("memorized"):
    related = client.memory.recall(
        "What kind of workspace does the user prefer?",
        namespace="preferences",
        top_k=3,
    )
    print(related.context)

deleted = client.memory.delete(namespace="preferences")
Inspect the state.
Check write.state, write.decision, write.provenance, and write.usage. Recall exposes retrieval_outcome and proximity. Do not treat an accepted request as proof that memory was retained.
Retries, idempotency, and errors
Only retry a write when its request is safe to repeat. Supply the same idempotency key for every retry of the same logical event. Preserve the request ID in logs and support tickets. The SDK raises typed errors for authentication, validation, conflicts, rate limits, timeouts, connection failures, and server responses.
Situation | Client behavior
Validation failure | Fix the request. Do not retry unchanged input.
401 or 403 | Refresh or replace credentials, then verify storage attachment and account permission.
409 with an idempotency key | Read the conflict and decide whether the original request already completed.
429 or retryable 5xx | Use bounded exponential backoff and respect server guidance.
Timeout or connection error | Retry only with the same idempotency key for a write, and keep the original request ID if known.
Language guides and integrations
Python
The supported typed client with sync and async resource surfaces.
HTTP
Use the versioned contract from any language or runtime.
CLI
Operate the same resources interactively or as JSON automation.
Framework adapters should pass memory context into your application model call. Mpalo does not represent the external model call, provider key, prompt policy, or output as part of the memory API contract.

### Python SDK

URL: https://api.mpalo.com/sdks/python
Status: preview

Current runtime: mock API contract v1
These pages document a production-shaped interface while the hosted runtime is in mock mode. Mock calls do not execute Palo Bloom, do not perform aggregate learning, and use sandbox billing. Use test data only.
Check system status before treating an operation as production-ready.
Python
Python SDK
Use the Python SDK when you want typed resource objects, synchronous or asynchronous calls, parsed provenance, and consistent error handling. The examples use the public v1 resource surface.
python -m pip install mpalo-sdk
Create a client
The constructor reads PALO_API_KEY when no key is supplied. It also resolves the configured base URL and validates key format. Pass an explicit key only when the value comes from a secure runtime source.
import os
from palo import Palo

client = Palo(
    api_key=os.environ["PALO_API_KEY"],
    timeout=30,
    max_retries=2,
)
from palo import AsyncPalo

async with AsyncPalo() as client:
    result = await client.memory.recall("What is relevant?", top_k=3)
Write, recall, and delete
The SDK validates non-empty text, namespace length, top-k bounds, and response contract fields before returning typed objects. Use a stable idempotency key for a logical event. Use namespaces to separate unrelated application contexts.
write = client.memory.write(
    "The user moved the appointment to Monday afternoon.",
    namespace="conversation",
    event_id="message_7",
    occurred_at="2026-08-28T10:00:00Z",
    idempotency_key="conversation-42-message-7",
)
print(write.state)
print(write.decision)
print(write.provenance.execution_mode)
print(write.usage.billing_state)

recall = client.memory.recall(
    "When is the current appointment?",
    namespace="conversation",
    top_k=3,
    as_of="2026-08-28T12:00:00Z",
)
print(recall.state, recall.proximity)

receipt = client.memory.delete(namespace="conversation")
print(receipt.state, receipt.deleted)
Infrastructure resources
Infrastructure methods return the deployment and measurement context that produced the response. Use them for startup checks, dashboards, incident investigation, and release verification.
capabilities = client.infrastructure.capabilities()
health = client.infrastructure.health()
status = client.infrastructure.status()
usage = client.infrastructure.usage(lookback_minutes=15)
events = client.infrastructure.events(limit=100, offset=0)

print(capabilities.operations)
print(health.deployment_version, health.environment)
print(status["monitoring"]["anomalies"])
print(usage["recorded_charge_usd"])
print(len(events["data"]))
The SDK also exposes metrics, anomalies, monitoring, and export. The async resource mirrors these methods.
Errors and safe retries
from palo import APIConnectionError, APITimeoutError, RateLimitError

try:
    result = client.memory.write(text, idempotency_key="event-42")
except (APITimeoutError, APIConnectionError):
    result = client.memory.write(text, idempotency_key="event-42")
except RateLimitError as error:
    print(error, error.retry_after)
Do not retry blindly.
A timeout means the server outcome may be unknown. Reuse the same idempotency key for a write and inspect the returned idempotency outcome.

### HTTP API reference

URL: https://api.mpalo.com/reference/http
Status: preview

Current runtime: mock API contract v1
These pages document a production-shaped interface while the hosted runtime is in mock mode. Mock calls do not execute Palo Bloom, do not perform aggregate learning, and use sandbox billing. Use test data only.
Check system status before treating an operation as production-ready.
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.
Base URL
https://api.mpalo.com
Contract
v1
Content type
application/json
Request identity
X-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"}
}
State is part of the contract.
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.
OpenAPI v1
Download the machine-readable API description.
Docs index
Stable page metadata for tooling and crawlers.
LLM context
Plain-text documentation with status and safety instructions.

### Production integration guide

URL: https://api.mpalo.com/guides/production
Status: preview

Current runtime: mock API contract v1
These pages document a production-shaped interface while the hosted runtime is in mock mode. Mock calls do not execute Palo Bloom, do not perform aggregate learning, and use sandbox billing. Use test data only.
Check system status before treating an operation as production-ready.
Guide
From contract test to controlled deployment
A production integration is more than a successful memory request. It needs a credential boundary, an attached storage connection, bounded retries, durable usage attribution, observable health, and a release record that can be audited after the fact.
Provision the control plane
Create the storage connection first, then create an API key and attach the storage. Keep the key scoped to the application or environment that will use it. Do not put a model provider key in the Mpalo control plane when the application is responsible for its own model call.
palo auth login
palo mind storage create
palo mind keys create
palo mind keys list
palo mind me
The key creation flow asks whether to create a managed storage or attach an existing connection. BYO storage is configured as a connection resource, not as an unvalidated request parameter.
Deploy with explicit configuration
Inject secrets through the deployment platform. Pin the API contract version in the client. Keep the base URL at the canonical origin in production and use a separate profile or environment for local testing.
PALO_BASE_URL=https://api.mpalo.com
PALO_API_KEY=managed-by-secret-store
from palo import Palo

client = Palo(
    api_key=secret_manager.get("MPALO_API_KEY"),
    base_url="https://api.mpalo.com",
    timeout=30,
    max_retries=2,
)
Verify before traffic
Record the deployment version, contract version, capability manifest, health response, and one safe test operation. Verify that the operation's provenance and billing state match the environment you intended to test.
palo infra capabilities --json
palo infra health --json
palo infra status --json
palo infra metrics --json
palo memory write "synthetic release check" --namespace release-check --json
palo memory delete --namespace release-check --confirm-namespace release-check --json
In the current mock environment, a release check proves transport, authentication, storage attachment, response parsing, and telemetry wiring. It does not prove model behavior, model quality, or production charge settlement.
Operate the integration
Signal | Record | Response
Availability | Health status, deployment version, checked timestamp. | Page or route traffic only when required services are unavailable.
Request quality | Request count, errors, timeouts, latency percentiles, blocked rate. | Investigate changes against a known baseline, not against a single sample.
Runtime truth | Execution mode, provider, model version, capability status. | Do not report mock success as model execution.
Cost truth | Operation units, pricing version, recorded and invoiced charge state. | Reconcile usage before making billing or quota decisions.
Use the SDK or API for durable monitoring. Use the CLI for an operator view and JSON export. Alert on sustained error rate, timeout rate, latency regression, blocked requests, unexpected provider or model changes, and billing reconciliation gaps.
Rollback and incident evidence
A rollback should preserve evidence. Export the relevant namespace and redacted infrastructure state before deleting or rotating resources. Revoke a compromised key, create a replacement, and verify that the old key no longer authenticates.
palo infra export --namespace release-check --json > incident-export.json
palo infra events --limit 500 --offset 0 --json > incident-events.json
palo mind keys list --json
# Rotate or revoke through the explicit key management command.
Do not use broad deletion.
The CLI requires exact resource identity for destructive confirmation. Keep the exported evidence in an approved incident location and treat it according to the data policy for that namespace.

### Agents and automation guide

URL: https://api.mpalo.com/guides/agents
Status: preview

Current runtime: mock API contract v1
These pages document a production-shaped interface while the hosted runtime is in mock mode. Mock calls do not execute Palo Bloom, do not perform aggregate learning, and use sandbox billing. Use test data only.
Check system status before treating an operation as production-ready.
Guide for agents
Automate without scraping the terminal
Agents should use documented JSON contracts, not parse colored tables or human-oriented status boxes. The CLI keeps the designed output for people and provides --json for scripts. The SDK returns typed objects and raw contract data where needed.
Use JSON and exit codes
Ask the CLI for JSON on every command used by an agent. Check the process exit code before reading fields. On success, inspect state, request ID, provenance, and usage. On failure, parse the error field and retain the request ID if supplied.
set -o pipefail
palo infra status --json > status.json
status_code=$?
if [ "$status_code" -ne 0 ]; then
  jq -r '.error // "unknown failure"' status.json
  exit "$status_code"
fi
jq '{state: .monitoring.state, provider, model_version}' status.json
For long event histories, page with --limit and --offset. Never assume the default 100 rows is the complete history.
Separate read, write, and destructive actions
Class | Examples | Agent rule
Read | palo auth, palo infra status, palo mind keys list | Safe to automate with scoped credentials and bounded timeouts.
Write | palo memory write, palo mind keys create | Supply stable identity and idempotency where supported. Capture the response.
Destructive | palo memory delete, key revoke, storage delete | Require explicit resource identity and a separate approval decision.
Operator simulation | palo infra smoke-test with simulation controls | Use only with an authorized operator capability. It cannot override consent or production policy.
Make monitoring actionable
A good agent does not report a green badge alone. It compares the current status to the requested window, checks whether data exists, identifies the provider and deployment version, enumerates anomalies, and states whether billing data was measured.
palo infra metrics --lookback-minutes 15 --json
palo infra anomalies --json
palo infra usage --lookback-minutes 15 --json
Treat no_data as an information state. It is not proof that the system had zero historical usage outside the requested window.
Use authoritative context sources
llms.txt
Short routing context, status boundary, and page links.
llms-full.txt
Plain-text page content for retrieval and offline agent context.
docs-index.json
Stable metadata, URLs, audiences, and page status.
Credential rule.
Documentation is public. Credentials are not. Never ask a user to paste a live API key into a documentation prompt, never echo one in output, and never store one in agent memory.

### Errors and retries

URL: https://api.mpalo.com/reference/errors
Status: preview

Current runtime: mock API contract v1
These pages document a production-shaped interface while the hosted runtime is in mock mode. Mock calls do not execute Palo Bloom, do not perform aggregate learning, and use sandbox billing. Use test data only.
Check system status before treating an operation as production-ready.
Reference
Errors should be actionable
Every failure has a transport status and a stable human-readable error field. SDKs turn common failures into typed exceptions. The CLI presents the failure for a person or emits the same contract as JSON for an agent.
{
  "error": "Authentication required. Provide an API Key or session token.",
  "details": {"request_id": "req_123"}
}
Failures use error, never a success-shaped message field. Details are optional and must not contain stack traces, secrets, or internal identifiers.
Status code decisions
Status | Meaning | Decision
400 | Malformed or invalid request. | Correct input. Do not retry unchanged input.
401 | Credential missing, invalid, or expired. | Resolve the right credential source. Do not keep retrying the same secret.
403 | Credential is valid but policy, role, consent, or capability denies the operation. | Ask for the required account action or use a permitted route.
404 | Resource or route is unavailable to the caller. | Verify the target and resource scope.
409 | Conflict, duplicate, or idempotency mismatch. | Read the response and reconcile the original logical operation.
429 | Rate or usage limit. | Back off and follow the retry hint.
5xx | Service or upstream failure. | Retry only when the operation is safe and the response is retryable.
Retry policy
Use bounded exponential backoff with jitter for transient failures. Respect Retry-After and any SDK retry metadata. Do not retry authentication, validation, consent, or permission failures until the underlying condition changes.
for attempt in range(3):
    try:
        response = client.memory.write(text, idempotency_key="event-42")
        break
    except (APITimeoutError, APIConnectionError):
        sleep(backoff_with_jitter(attempt))
else:
    raise RuntimeError("Mpalo request did not become reachable")
Idempotency
An idempotency key identifies one logical write, not one network attempt. Generate it from your event identity, store it with your application event, and reuse it after timeouts. A replay should return the original outcome or a clear conflict, never create an accidental duplicate.
Do not reuse keys across events.
A key collision can make a new event look like a replay. Use a namespace or application identifier in the key when multiple producers share a storage connection.
Troubleshooting sequence
Keep the request ID, target, contract version, and timestamp.
Run palo auth or inspect the SDK credential source without exposing the secret.
Run palo infra health --json and palo infra capabilities --json.
Check storage attachment, consent, role, rate limits, and the selected profile.
Compare events and usage for the same time window.
If the result is still unexplained, provide the request ID and redacted JSON output to support. Do not provide the API key, session token, raw private memory, or an unredacted export.

### Palo Bloom

URL: https://api.mpalo.com/bloom
Status: preview

Current runtime: mock API contract v1
These pages document a production-shaped interface while the hosted runtime is in mock mode. Mock calls do not execute Palo Bloom, do not perform aggregate learning, and use sandbox billing. Use test data only.
Check system status before treating an operation as production-ready.
In development
Palo Bloom
Palo Bloom is Mpalo's experience-aware memory architecture. It is intended to help applications represent and retrieve experience across interaction, identity, and time. The architecture is not the same thing as the current customer runtime.
Current implementation
Mpalo currently operates an early text-memory runtime with durable submitted-text persistence, deterministic lexical retrieval, stored-text context rendering, deletion, and inspectable usage. The hosted path uses mpalo-local-mock and deterministic-lexical-v1. It does not execute a Palo Bloom model, produce customer-facing embeddings, or perform semantic vector search.
For the public product overview and broader direction of Palo, read Meet Palo.
Architecture direction
The research architecture explores a learned representation and decoding system closer to a modified variational autoencoder than to a wrapped conversational model. The intended system separates the representation of an event from the value later rendered for an application. It may also represent episodic structure, temporal relationships, and context across events.
Recall
The current runtime provides lexical retrieval. Learned semantic recall is a research question.
Traversal
The API can represent a future stage. A learned episodic traversal capability is not deployed.
Mapping
The API can report attribution for testing. A learned memory map is not deployed.
What the API can show
A memory write returns a retention state, representation status, provenance, and usage state. In the current mock path, representation is unavailable because no model ran, and the retention decision does not evaluate learned surprise or salience. A recall returns lexical candidates and may render selected stored text as context. It does not claim a semantic similarity score.
Response signal | Current meaning
execution_mode: mock | The deterministic service fixture accepted the request.
model_variant: Unspecified | No Palo model executed for that request.
representation.status: not_available | No customer-facing embedding or learned representation was produced.
score_kind: mock_lexical_overlap | Candidate ranking used lexical overlap rather than model confidence.
capability_status: contract_fixture | The response shape is exercised for compatibility, not proof of the intended capability.
Storage, models, and data boundaries
Managed storage
The current mock path can retain submitted text after storage and consent checks. This is storage and retrieval, not training.
BYO storage
Mind can represent a custom connection. Runtime execution against customer storage is not deployed.
Downstream model
The application can use returned context with its own model. Mpalo does not provide that downstream response in this v1 path.
Managed external LLMs
Mpalo-managed external LLM connections are currently unavailable. Re-enabling them requires provider, legal, privacy, billing, and security controls.
The current mock runtime does not train or employ Palo Bloom and does not perform aggregate learning. It is a deterministic fixture for testing the API, SDK, CLI, usage ledger, and operational surfaces.
What must be proven next
Bloom moves from architecture direction to product capability only when a reproducible evaluation shows what the model executed and how it behaves. The evidence must cover representation version and dimensions, separate stored values, retrieval and rendering quality, latency, cost, tenant isolation, correction, deletion, failure behavior, and model artifact provenance. Learned behavior must be compared with lexical, random, untrained, and simpler baselines under the same context budget.
Capability status
Read the runtime provider, capability status, limitations, and observability contract.
Use the current API
Run the current deterministic path and inspect its provenance instead of assuming Bloom execution.

### Palo CLI

URL: https://api.mpalo.com/cli
Status: preview

Current runtime: mock API contract v1
These pages document a production-shaped interface while the hosted runtime is in mock mode. Mock calls do not execute Palo Bloom, do not perform aggregate learning, and use sandbox billing. Use test data only.
Check system status before treating an operation as production-ready.
Terminal reference
Palo CLI
The Palo CLI is the terminal interface to the same account, memory, infrastructure, usage, and billing surfaces exposed by the SDK and HTTP API. It is designed for a human at a shell, an agent that needs structured output, and a CI job that needs stable exit codes.
python -m pip install palo-spring
palo --version
palo
palo auth
palo --help
A bare command shows its generated reference when that command is a command group. For example, palo auth shows credential state and auth actions, while palo auth --help shows the formal option reference.
Command map
Surface | Examples | Purpose
Auth | palo auth, palo auth login, palo logout | Inspect, create, and remove local credentials.
Settings | palo settings, palo settings profiles, palo settings set | Manage target, output, transport, and local profiles.
Mind | palo mind me, palo mind keys, palo mind storage | Manage account resources, API keys, storage connections, usage, and billing.
Memory | palo memory write, palo memory recall, palo memory delete | Use the data plane with an API key attached to an active storage connection.
Infrastructure | palo infra status, palo infra metrics, palo infra events | Inspect capabilities, health, request quality, anomalies, event history, and exports.
Short aliases are supported for frequently used surfaces. The canonical words remain valid and appear in help output so scripts remain readable.
Authentication
Run palo auth to see local state. Run palo auth login for the browser flow. The callback returns to the CLI's loopback listener, not to the Mind Platform dashboard. Run palo auth logout or its root alias palo logout to remove saved API key and session credentials.
palo auth
palo auth login
palo auth logout
  palo logout
Credential selection.
A saved session is appropriate for interactive control-plane work. Memory writes and other API-key-only operations require PALO_API_KEY or a saved API key. palo auth reports the selected source without exposing the full secret.
Memory operations
Before writing, create or select a memory storage connection and attach it to the API key. The CLI asks for an exact confirmation on destructive actions. A bare memory command prints command help instead of attempting a request with missing input.
palo mind storage create
palo mind keys create
# Follow the prompts to attach an existing or managed storage.
palo memory write "The appointment moved to Monday" \\
  --namespace conversation \\
  --idempotency-key conversation-42-message-7
palo memory recall "When is the appointment?" \\
  --namespace conversation \\
  --top-k 3

palo memory delete --namespace conversation \\
  --confirm-namespace conversation
The write result distinguishes accepted, retained, not retained, and failed states. It includes decision, representation, related recall when requested, provenance, usage, and request ID. Recall calls its input a cue because it is the signal used to retrieve related memories, not a hidden model parameter.
Infrastructure and monitoring
Use read-only infrastructure commands to inspect the current deployment. The default target comes from the active profile. These commands report backend state and do not require the repository on the operator's computer. A smoke test is an authorized diagnostic request against the configured deployment, not a local server startup command.
palo infra capabilities
palo infra health
palo infra status
palo infra metrics
palo infra anomalies
palo infra events --limit 100 --offset 0
  palo infra export
For a deployed runtime, palo infra smoke-test requires the operator capability, active consent, and the target's policy. It does not bypass customer consent. Use palo infra monitor --iterations 0 for a bounded live view and stop it with Ctrl+C.
Automation, JSON, and destructive actions
Designed terminal output is for people. Agents and CI should use --json, check the process exit code, and parse documented response keys. Commands that mutate state should be explicit and should never accept an unqualified confirmation shortcut.
palo infra metrics --json > metrics.json
palo infra events --limit 500 --offset 0 --json
palo mind keys list --json
  palo mind usage summary --json
Confirmation policy.
Key deletion requires the exact key name. Storage deletion requires the exact storage name. Memory namespace deletion requires --confirm-namespace with the exact namespace. A bare --yes is rejected because it removes the resource identity from the confirmation step.
Completion scripts are generated by the CLI. Run palo install completion --help for shell-specific installation, or palo show completion --help to print a script without modifying shell files.

### Use cases

URL: https://api.mpalo.com/use-cases
Status: preview

Current runtime: mock API contract v1
These pages document a production-shaped interface while the hosted runtime is in mock mode. Mock calls do not execute Palo Bloom, do not perform aggregate learning, and use sandbox billing. Use test data only.
Check system status before treating an operation as production-ready.
Scope
Use cases and research boundaries
The current API supports a deterministic text-memory workflow. The examples below show where that workflow can be integrated now and where the Palo Bloom architecture may lead later. A use case is not a product guarantee. Each section names its implementation status and the missing evidence.
Current integration patterns
Software agents
Persist selected text events, retrieve related retained records, and pass returned context to a model managed by your application.
Current mock contract
Project and support context
Use namespaces and idempotency keys to keep a text history inspectable across sessions and safe to retry.
Current mock contract
Operational analysis
Inspect request quality, usage, charge state, events, health, and anomaly signals for the API path.
Available in the current service
Research directions
These directions depend on a deployed learned runtime and reproducible evidence. The current API does not provide them merely because it has names or response fields for them.
Experience-aware retrieval
A learned representation could test whether retrieval improves when an event is considered in relation to prior experience, time, and identity. The required model, baselines, dimensions, quality threshold, and cost are not yet established.
Personalization
Applications may eventually evaluate learned episodic structure for continuity and personalization. Current lexical results must not be described as learned user modeling or prediction.
Traversal and mapping
The contract can identify these stages, but a useful distinction between retrieval, traversal, and mapping still needs an executable research definition and independent evaluation.
Recommendations and forecasting
Recommendation and forecasting are possible application research areas. No current Mpalo API claim establishes predictive behavior, real-time adaptation, or a performance advantage.
Multimodal and physical inputs
The public v1 memory schema is text-only. Images, audio, sensor streams, and other physical inputs are research and planning topics. They require a capture boundary, subject and bystander consent, reliable provenance, raw-data retention rules, redaction, deletion, asynchronous processing, and modality-specific evaluation before they can become API capabilities.
Robotics boundary
Memory may eventually inform an embodied application, but it cannot become an unverified source of truth for physical action. Authoritative control state must remain separate from probabilistic memory. Missing, stale, contradictory, or uncertain memory must lead to a safe application-defined fallback.
Choose the next page
Get started
Run the current text-memory contract with the SDK, CLI, or HTTP API.
Infrastructure
Inspect what is deployed, recorded, billable, and still a contract stage.
Palo Bloom
Read the architecture direction and the evidence required for promotion.

### System status

URL: https://api.mpalo.com/status
Status: live

Current runtime: mock API contract v1
These pages document a production-shaped interface while the hosted runtime is in mock mode. Mock calls do not execute Palo Bloom, do not perform aggregate learning, and use sandbox billing. Use test data only.
Check system status before treating an operation as production-ready.
System Status
Checking services...
Planned Maintenance
Services
Loading...
Operational Partial outage Major outage No data
Recent Incidents
Loading...
Latency
Sampled hourly by the monitoring cron. “Last” is the most recent live check.
API / Inference
Avg -- Min -- Max -- Last --
Database
Avg -- Min -- Max -- Last --