API And Data Reference

This page mirrors the checked-in route table and is protected by a documentation-freshness test. For a deployed revision, the machine-readable live route inventory, bounded OpenAPI contract, and version record are the runtime evidence.

Trust and tenancy boundary

• Public routes expose product documentation and redacted capability evidence, never tenant knowledge.
• Legacy protected routes require a workspace bearer key. Connector pairing uses a narrower connector-and-exact-agent bearer; human approval uses an authenticated account session, and administrative revocation requires a company master.
• The durable hierarchy is project to workspace to company. Accounts and users join companies through many-to-many membership and do not own knowledge trees.
• Protected mutations use Idempotency-Key. Exact retries replay; key reuse with a different body returns a conflict-safe no-op.
• Public-safe summaries, citations, receipts, and audit metadata may persist. Raw credentials, private payloads, hidden prompts, private model assets, and credential-bearing URLs do not.
• The full virtual UAIX package is a narrow accountless-browser exception. Ordinary filesystem agents keep local .uai bodies local and use only hash heads and edit claims for concurrency coordination.

Public routes

Setup and recovery contract. GET returns setup metadata and POST creates one free account/company/workspace/project hierarchy. The company master credential is created there and shown once. The public-safe companyMasterStorageGuidance contract names the default file as <project-root>/.local-secrets/memoryendpoints-company-master.json. Browser setup uses Save to project secret folder; agent-driven setup uses scripts/setup_memoryendpoints_company.py. If the file is missing, a company-scoped top-level agent can run scripts/recover_memoryendpoints_company_master.py with MEMORYENDPOINTS_AGENT_TOKEN; an existing company master can use MEMORYENDPOINTS_COMPANY_MASTER_TOKEN. The helper writes a client-generated candidate to a protected pending file, registers only its verifier through POST /api/matm/access/company-master-credentials, verifies it through /api/matm/me, and promotes the final file atomically without printing a credential or identifier. Lower-scoped agents ask a top-level agent or human administrator. Human owners and credential admins can disable top-level-agent creation through the human console; the direct database override is matm_companies.top_level_agent_master_credential_enabled. Keep the master secret unavailable to disposable agents through distinct OS/vault identities or secret mounts; API authorization cannot isolate processes sharing one unrestricted filesystem identity. Initial setup remains intentionally non-idempotent, so clients must not automatically retry an uncertain setup outcome.

LocalEndpoint connector pairing v1

The desktop validates the exact https://memoryendpoints.com root, fetches same-origin discovery without redirects, generates 256-bit state and PKCE S256 values, and creates an idempotent request for exact localendpoint-agent plus the closed four-scope set. The authorization URL contains only publicRequestRef (pairref_ plus 43 base64url characters), which is public, tenant-neutral, and non-authorizing. The human approves the exact agent, scopes, and an opaque existing-workspace reference or provisional labels. Approval returns only status approved_awaiting_connector_claim and a parameter-free wakeUpUrl; opening it is an explicit human action, grants no authority, and is never automatic.

The exact ordered scopes are connector:self:readback, agent:self:register, memory:public-safe:submit, and memory:search:read. No omission, reordering, substitution, or expansion is accepted.

The desktop claims a 60-second one-use code through JSON POST /api/matm/connector-pairings/authorization-code-claims using its body-only request proof, state, client, redirect URI, and idempotency binding. Pending approval returns 202 with Retry-After, stateVerified=true, exact requestedScopes, scopeDigest, idempotencyKeyReserved=false, and a redacted receipt without binding the key. Exact approved retry rederives one body-only code before PKCE exchange; changed body or any different key returns 409 idempotency_conflict. Request and pending-grant TTLs are 600 seconds. The server persists only verifiers and bounded derivation inputs, never raw proof, state, code, PKCE verifier, credential, request body, or secret-bearing retry response.

Discovery is bounded to 16 KiB, every connector JSON request body is bounded to 32 KiB, and sensitive JSON responses are bounded to 64 KiB with no-store/no-referrer headers. Credential-partitioned operating limits are 5 self-registration confirmations per 10 minutes, 60 public-safe submissions per minute, and 120 searches per minute. The exact ordered scopes have digest sha256-v1:1358698c6ddba1a74a688d3718a739f78e4ef50d0773b22c96e025b38aa86594. Activation atomically registers the bound agent and commits any provisional hierarchy. Readback must prove the exact workspace, exact agent, credentialType=connector_agent, ordered scopes, digest, active state, and non-revocation before Connected. The deny-by-default connector can read itself/workspace/status/inventory, confirm self-registration, submit only public-safe memory, perform body-only read-only search, and use intrinsic lifecycle routes. Human APIs, access administration, other agents, meetings, audit/history, export, knowledge mutation, review, sync, and every unlisted route return 403 connector_scope_forbidden.

Connector errors use the exact redacted problem shape ok=false, safeNoOp=true, valuesRedacted=true, rawCredentialExposed=false, rawPayloadExposed=false, and nested error.{code,title,detail,safeNoOp,valuesRedacted}. There is no error.message alias. Stable codes include invalid_request, pairing_verification_failed, and the 409 pairing_unavailable returned when a different terminal lifecycle action already won.

Connector-specific protected audit rows store only the action and domain-separated HMAC correlation references. Their workspace foreign key is null, public request references are pseudonymized, and raw human, tenant, workspace, project, agent, request, pairing, rotation, credential, and master-key identifiers are never copied into audit actor, target, or details fields.

Exact response projections. Public PairingRequest contains exactly publicRequestRef, status, clientDisplayName, agentDisplayName, requestedScopes, approvedScopes, scopeDigest, scopeImpacts, expiresAt, and nullable claimExpiresAt; creation adds expiresInSeconds=600, while cancellation omits it. Base PairingSummary contains exactly pairingId, status, workspaceId, agentId, credentialId, approvedScopes, scopeDigest, and grant. Pending adds only activationExpiresInSeconds; status readback additionally adds workspace.{workspaceId,readable} and agent.{agentId,readable}. The grant contains exactly credentialType, scopeType, scopeId, workspaceId, agentId, approvedScopes, scopeDigest, active, revoked, canInvite=false, and canRevoke=false.

Base RotationSummary contains only rotationId, status, credentialId, approvedScopes, and scopeDigest; pending adds only activationExpiresInSeconds. Pairing and rotation summaries never expose internal request/company/project IDs, reasons, predecessor or supersession identifiers, raw timestamps, or nested redaction flags. Request-proof, approved-code, exchange, and rotation secret responses all attest top-level credentialDeliveredToAuthorizedRecipient=true, rawCredentialPersisted=false, and showCredentialOnce=true. Request creation also carries purpose-specific proofDelivery; exchange and rotation carry purpose-specific credentialDelivery.

Credential inventory. GET /api/matm/connector-pairings/{pairingId}/credentials returns pairingId, exact approvedScopes, scopeDigest, currentCredentialId, items, count, totalCount, hasMore, limit=100, envelope redaction flags, and a deterministic receipt. Each newest-first item contains exactly credentialId, status, isCurrent, approvedScopes, scopeDigest, createdAt, activatedAt, revokedAt, and lastUsedAt; no raw secret, hash, or verifier is returned.

Protected UAIX active memory

These routes expose two separate modes. The full virtual package stores strictly validated protected active-memory records for a registered accountless browser agent that has no durable local filesystem. The local collaboration overlay stores no file body: it coordinates ordinary filesystem agents with project/path hashes, bounded leases, and public-safe summaries.

A virtual record requires typed common headers, role-specific fields, a supported closed required-state role, public-safe content, and no calendar dates or timestamps. Identity must match the registered agent id and name; the startup packet must enumerate every required logical path; progress, short-term state, and long-term pointers have distinct required fields. The long-term human-facing path is the clean https://memoryendpoints.com home page, while protected API routes remain connector metadata. Updating an existing record requires expectedRevision; immutable revision snapshots are retained. Package startup remains incomplete until every required active role is present and valid.

This is a MemoryEndpoints database adaptation of typed UAIX active memory. It does not create a .uaix package file and makes no UAIX hosted-import, automatic-sync, certification, endorsement, or conformance claim.

A local claim requires a real project, registered agent, normalized local .uai path, complete SHA-256 base hash, and public-safe intent. Another owner or stale base returns a conflict-safe 409. Every successful claim mutation returns persisted=true and visibleToSender=true only after exact protected claim/head readback. Completion records only the new hash and summary. Claims do not lock the operating system, replicate content, merge files, or prove that expired work was integrated; agents still reconcile through the project meeting room and source control.

Protected knowledge and memory

Protected coordination and evidence

Coordination retention is deliberately bounded. Anything worth keeping from a direct message or meeting must be explicitly promoted into durable memory or knowledge. Meeting-room metadata and durable routing decisions remain. Optional humans may review, reverse through an applicable control, or download only the history still inside the seven-day human window; purged logs cannot be recovered and never enter agent context.

Protected distributed sync

Sync v1 accepts public-safe memory summaries, uses device epochs and immutable revisions, assigns a monotonic server sequence, and records redacted receipts. It rejects stale parents, revoked devices, wrong authority epochs, and blocked tombstone resurrection instead of silently choosing a winner.

Relational persistence

Production uses the verified MySQL/MariaDB backend. SQLite is the stdlib local relational backend; file storage is an explicit development fallback. The schema separates tenant hierarchy, key hashes, virtual UAIX packages and immutable records, hash-only local .uai collaboration heads and claims, memory and revisions, wiki sources and documents, canonical external links and mentions, meeting rooms and routing decisions, current-message notifications, sync devices and revisions, review state, idempotency, quota, receipts, and audit evidence.

Evidence rules

• Checked-in code and tests prove what a revision implements locally.
• /api/version proves which source SHA a live endpoint serves.
• The route verifier proves the public surface; authenticated dogfood proves protected workflows; the MySQL verifier proves the production backend.
• Tracked reports are point-in-time evidence and must never be mistaken for proof of a later commit.