MeMesh

REST API Reference

This page is for people who want to connect MeMesh to their own systems. It covers the APIs for workspaces, execution controls, approvals, memory, and team-related flows.

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

Not sure whether you need this page?

If you are just trying MeMesh for the first time, start with the docs overview or Setup first. Come back here when you need to automate, integrate, or call the runtime from your own systems.

Read the docs overviewOpen Setup

Authentication Header

x-api-key: mk_your_api_key_here

All requests need a valid API key. Create one from Setup > Agent Access Keys.

Agent Workspace

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

GET
/agents/dispatch-targets

List local and remote dispatch targets for this workspace, including eligibility, runtime policy, control state, and compatibility summaries.

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

GET
/agents/dispatch-targets/:id

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

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

View governance details such as runtime policy, review state, 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 the latest runtime 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 support.

POST
/memory/write

Write one memory item with optional metadata.

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

GET
/memory/search

Search memories with a natural-language query over GET.

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

POST
/memory/search

Search memories with a structured POST body. Useful when the query is more complex.

Body: { query, spaces?, limit? }

GET
/memory/count

Get the total memory count for the authenticated user.

POST
/memory/batch

Write up to 100 memories in one request with transactional or partial-success mode.

Body: { memories[], transactional? }

POST
/memory/batch/search

Run up to 50 memory searches in parallel with optional deduplication.

Body: { queries[], deduplicate? }

GET
/memory/spaces

List all memory spaces for the authenticated user.

POST
/memory/query

Run a hybrid memory query with semantic, tag, and temporal filters.

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

POST
/memory/context-window

Select memories for an LLM context window within a token budget.

Body: { query, tokenBudget }

SSE
/memory/stream/export

Stream a memory export through Server-Sent Events 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 with 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

Perform guarded operator resolution for remote runs after recovery is exhausted.

GET
/orchestrator/runtime-health

View operator health across local compatibility, remote escalation, target governance, and attention backlog.

Local Agent Execution

Claim-token based local execution queue with leases, heartbeats, 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 with a caller-supplied claim token.

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 a 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

Audit log access for security review and compliance workflows.

GET
/audit/logs

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

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

Billing & Usage

Subscription plans, usage statistics, and quota visibility.

GET
/billing/plan

Get the current user's subscription plan.

GET
/usage/summary

Get usage statistics for 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 raw 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 for CLI and MCP clients.

POST
/auth/device

Start the device authorization flow. Returns device_code, user_code, and verification_uri.

Body: { client_id, scope? }

POST
/auth/device/token

Poll for a token after the user authorizes the device.

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)