This project is a work in progress and is not ready for production use.
MeMesh

REST API Reference

Complete reference for the MeMesh Cloud REST API. The V2 primary surface is the agent workspace: dispatch targets, orchestrator runs, local execution control, approvals, runtime health, and compatibility retirement. All endpoints require authentication via the x-api-key header.

Base URL: https://api.memesh.ai/v1

Authentication Header

x-api-key: mk_your_api_key_here

All requests must include a valid API key. Create keys from Setup > Agent Access Keys.

Agent Workspace

Tenant-scoped dispatch targets and target-level governance truth.

GET
/agents/dispatch-targets

List tenant-scoped local and remote dispatch targets with dispatch eligibility, runtime policy, controls, and compatibility/runtime summaries.

Query: search?, targetKind? (LOCAL_AGENT|REMOTE_A2A), state?, limit?, offset?

GET
/agents/dispatch-targets/:id

Get one dispatch target detail including remote control capability or local runtime summary.

GET
/agents/dispatch-targets/:id/governance

Governance drill-down with runtime policy, review state, provider-incident handoff, recent runs, recent audit, impacted work, and timeline.

POST
/agents/dispatch-targets/:id/hold

Place a manual hold on a dispatch target. Requires expectedRuntimeUpdatedAt CAS token.

Body: { reason, releaseAfter?, expectedRuntimeUpdatedAt }

POST
/agents/dispatch-targets/:id/release

Release a manual hold and recompute effective policy in one CAS-protected mutation.

Body: { note?, expectedRuntimeUpdatedAt }

POST
/agents/dispatch-targets/:id/review/acknowledge

Acknowledge the active governance review for the current policy epoch.

Body: { note?, expectedRuntimeUpdatedAt }

POST
/agents/dispatch-targets/:id/incident/handoff

Record provider-incident handoff for the active incident epoch.

Body: { externalIncidentId, owner, note?, expectedRuntimeUpdatedAt }

Memory

Store and search memories with semantic search via pgvector embeddings.

POST
/memory/write

Write a new memory with optional metadata. Memories are automatically embedded for semantic search.

Body: { content, space?, summary?, tags?, sensitivity?, source? }

GET
/memory/search

Semantic search across stored memories using a natural language query.

Query: query (required), spaces?, limit?

POST
/memory/search

Semantic search with structured request body. Recommended for complex queries.

Body: { query, spaces?, limit? }

GET
/memory/count

Get total memory count for the authenticated user.

POST
/memory/batch

Batch write up to 100 memories. Supports transactional (all-or-nothing) or partial success modes.

Body: { memories[], transactional? }

POST
/memory/batch/search

Execute up to 50 search queries in parallel with optional cross-query deduplication.

Body: { queries[], deduplicate? }

GET
/memory/spaces

List all memory spaces for the authenticated user.

POST
/memory/query

Natural language query with hybrid filtering. Supports temporal, tags, and semantic search.

Body: { query, limit?, offset?, similarityThreshold? }

POST
/memory/context-window

Select memories for LLM context window within a token budget.

Body: { query, tokenBudget }

SSE
/memory/stream/export

Stream memory export using Server-Sent Events. No timeout for large exports.

Query: spaces?

Orchestrator Runtime

Persisted runs, control truth, reconcile, retry-cancel, and runtime health.

GET
/orchestrator/runs

List recent runs with target kind, control truth, approval links, and operator guidance.

GET
/orchestrator/runs/:id

Get run detail including events, approvals, remote control state, and suggested operator action.

GET
/orchestrator/runs/:id/control

Return control capability truth, block reasons, and operator guidance for one run.

POST
/orchestrator/runs/:id/reconcile

Force-poll remote state and reconcile late terminal truth.

POST
/orchestrator/runs/:id/retry-cancel

Retry a remote cancel after timeout or transient failure.

POST
/orchestrator/runs/:id/resolve-remote

Guarded operator resolution for remote runs after recovery exhaustion.

GET
/orchestrator/runtime-health

Operator health summary for local compatibility, remote escalation, target governance, and attention backlog.

Local Agent Execution

Claim-token based local execution queue with leases, heartbeat, recovery, and cancel acknowledgement.

GET
/agents/executions

List pending local executions available to the current agent.

POST
/agents/executions/:id/claim

Claim a local execution using a caller-supplied claimToken.

Body: { claimToken, workerId? }

POST
/agents/executions/:id/heartbeat

Extend the active lease and optionally report progress.

Body: { claimToken, progressMessage? }

POST
/agents/executions/:id/complete

Complete the claimed execution.

Body: { claimToken, result?, idempotencyKey? }

POST
/agents/executions/:id/ack-cancel

Acknowledge cancel after the runtime requests local interruption.

Body: { claimToken, note? }

Team

Team member management, invitations, and role-based access control.

GET
/team/members

List all team members for the current tenant.

POST
/team/members/invite

Invite a new team member by email. Requires OWNER or ADMIN role.

Body: { email, role? }

PATCH
/team/members/:userId/role

Change a team member's role.

Body: { role }

DELETE
/team/members/:userId

Remove a member from the team.

Audit

Query audit logs for security monitoring and compliance.

GET
/audit/logs

Query audit logs with optional filters by action, resource, date range, and limit.

Query: action?, resource?, startDate?, endDate?, limit? (default: 100)

Billing & Usage

Subscription plans, usage statistics, and quota management.

GET
/billing/plan

Get the current user's subscription plan (free, pro, or enterprise).

GET
/usage/summary

Get complete usage statistics including memory, API keys, agents, seats, and rate limits.

API Keys

Create, list, and revoke API keys for programmatic access.

POST
/keys

Create a new API key. The key value is only shown once in the response.

Body: { name }

GET
/keys

List all API keys for the current user (values are masked).

DELETE
/keys/:id

Permanently revoke an API key.

Device Authorization

OAuth 2.0 Device Authorization flow (RFC 8628) for CLI and MCP clients.

POST
/auth/device

Initiate device authorization flow. Returns device_code, user_code, and verification_uri. Public endpoint.

Body: { client_id, scope? }

POST
/auth/device/token

Poll for token after user authorizes the device. Public endpoint.

Body: { grant_type: "urn:ietf:params:oauth:grant-type:device_code", device_code }

Example Requests

List workspace dispatch targetsbash
curl "https://api.memesh.ai/v1/agents/dispatch-targets?targetKind=REMOTE_A2A&limit=10" \
  -H "x-api-key: mk_your_api_key"
Force-poll remote run statebash
curl -X POST https://api.memesh.ai/v1/orchestrator/runs/run_123/reconcile \
  -H "x-api-key: mk_your_api_key" \
  -H "Content-Type: application/json"
Place a manual hold on a dispatch targetbash
curl -X POST https://api.memesh.ai/v1/agents/dispatch-targets/{targetId}/hold \
  -H "x-api-key: mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "provider maintenance",
    "releaseAfter": "2026-03-22T09:00:00.000Z",
    "expectedRuntimeUpdatedAt": "2026-03-20T09:00:00.000Z"
  }'

HTTP Status Codes

CodeDescription
200Success
201Created (resource created)
400Bad Request (validation error, invalid Agent Card)
401Unauthorized (invalid or missing API key)
403Forbidden (self-review blocked, insufficient permissions)
404Not Found (agent or resource does not exist)
409Conflict (stale policy epoch, stale runtime snapshot, duplicate claim)
429Too Many Requests (rate limit exceeded)