API Endpoints

All endpoints are served by the Astromesh daemon (astromeshd) and are prefixed with /v1. The default base URL is http://localhost:8000.

Core API

GET /v1/health

Health check endpoint. Returns 200 if the daemon is running.

Response:

{
  "status": "healthy",
  "version": "0.35.0",
  "uptime_seconds": 8072
}

---

GET /v1/agents

List all loaded agents.

Response:

{
  "agents": [
    {
      "name": "assistant",
      "description": "General-purpose assistant",
      "model": "openai/gpt-4o",
      "orchestration": "react",
      "status": "ready"
    },
    {
      "name": "researcher",
      "description": "Research and analysis agent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "orchestration": "plan_and_execute",
      "status": "ready"
    }
  ]
}

---

GET /v1/agents/{name}

Get details for a specific agent.

Path parameters:

Parameter	Type	Description
name	string	Agent name as defined in YAML

Response:

{
  "name": "assistant",
  "description": "General-purpose assistant",
  "model": {
    "primary": { "provider": "openai", "model": "gpt-4o" },
    "fallback": { "provider": "anthropic", "model": "claude-sonnet-4-20250514" },
    "routing": "cost_optimized"
  },
  "orchestration": { "pattern": "react", "max_iterations": 10, "timeout": 120 },
  "tools": ["web_search", "knowledge_base"],
  "memory": { "conversational": "redis", "semantic": "chroma" },
  "status": "ready"
}

Errors:

Status	Description
404	Agent not found

---

POST /v1/agents/{name}/run

Execute an agent with a user query.

Path parameters:

Parameter	Type	Description
name	string	Agent name

Request body:

{
  "query": "What are the latest trends in AI?",
  "session_id": "sess_abc123"
}

Field	Type	Required	Description
query	string	Yes	User input text
session_id	string	No	Session ID for memory continuity. Auto-generated if omitted
connections	object	No	Per-run credential bundle for integration tools. Takes priority over config/connections.yaml; the runtime never stores it

A run that uses integrations supplies their credentials here:

{
  "query": "how much does customer 42 owe?",
  "connections": {
    "praxis_main": { "api_key": "...", "base_url": "https://erp.example.com" }
  }
}

Response:

{
  "answer": "Based on my research, the latest trends in AI include...",
  "steps": [ ... ],
  "usage": {
    "tokens_in": 1250,
    "tokens_out": 430,
    "model": "gpt-4o",
    "by_model": [
      {
        "provider": "openai",
        "model": "gpt-4o",
        "role": "default",
        "calls": 2,
        "tokens_in": 1250,
        "tokens_out": 430,
        "tokens_cached": 1024,
        "cost": 0.0074
      }
    ]
  },
  "trace": { ... },
  "data": null,
  "chain": null,
  "propuestas": []
}

Field	Description
answer	The agent’s final answer
steps	Orchestration steps (thought / action / observation)
usage	Token usage summed from the run’s trace. null when no provider reported tokens
usage.model	First model seen, kept for compatibility. Use by_model on multi-model runs
usage.by_model[]	One entry per (provider, model, role), ordered by total tokens descending
usage.by_model[].tokens_cached	Part of tokens_in the provider served from its prompt cache (0 when the provider reports none). Available since astromesh v0.54.0
trace	The run’s trace (spans)
data	Validated structured output when the agent declares output_schema
chain	Chain block when the agent declares spec.chain
propuestas	Writes proposed by mode: propose tools, not executed (see Tenant APIs and MCP). Empty when there were none. Available since astromesh v0.59.0

Errors:

Status	Description
404	Agent not found
502	Model provider error: detail is {error, message, hint}. OpenAI-compatible providers include their response body in message (truncated to 800 characters)
503	Runtime not initialized
500	Any other failure

---

GET /v1/memory/{agent}/history/{session}

Retrieve conversational history for an agent session.

Path parameters:

Parameter	Type	Description
agent	string	Agent name
session	string	Session ID

Response:

{
  "agent": "assistant",
  "session_id": "sess_abc123",
  "messages": [
    { "role": "user", "content": "Hello" },
    { "role": "assistant", "content": "Hi! How can I help?" },
    { "role": "user", "content": "What is Astromesh?" },
    { "role": "assistant", "content": "Astromesh is..." }
  ]
}

---

DELETE /v1/memory/{agent}/history/{session}

Clear conversational history for an agent session.

Path parameters:

Parameter	Type	Description
agent	string	Agent name
session	string	Session ID

Response:

{
  "status": "cleared",
  "agent": "assistant",
  "session_id": "sess_abc123"
}

---

GET /v1/memory/{agent}/semantic

Query semantic memory for an agent.

Path parameters:

Parameter	Type	Description
agent	string	Agent name

Query parameters:

Parameter	Type	Default	Description
query	string	(required)	Text to search for semantically similar entries
top_k	integer	5	Number of results to return

Response:

{
  "results": [
    {
      "text": "Previous conversation about deployment...",
      "score": 0.92,
      "metadata": { "session_id": "sess_xyz", "timestamp": "2026-03-08T14:30:00Z" }
    }
  ]
}

---

GET /v1/tools

List all registered tools across all agents.

Response:

{
  "tools": [
    {
      "name": "web_search",
      "type": "internal",
      "description": "Search the web for current information",
      "agents": ["assistant", "researcher"]
    },
    {
      "name": "mcp_filesystem",
      "type": "mcp",
      "description": "File system operations",
      "agents": ["assistant"]
    }
  ]
}

---

POST /v1/tools/execute

Execute a tool directly (outside of an agent context).

Request body:

{
  "tool": "web_search",
  "input": {
    "query": "Astromesh documentation",
    "max_results": 3
  }
}

Response:

{
  "tool": "web_search",
  "output": {
    "results": [
      { "title": "Astromesh Docs", "url": "https://..." }
    ]
  },
  "timing_ms": 320
}

---

POST /v1/rag/ingest

Ingest documents into a RAG collection.

Request body:

{
  "collection": "product_docs",
  "documents": [
    {
      "text": "Astromesh supports multiple LLM providers...",
      "metadata": { "source": "docs", "page": 1 }
    }
  ],
  "chunk_size": 512,
  "chunk_overlap": 50
}

Field	Type	Required	Default	Description
collection	string	Yes	—	Target collection name
documents	array	Yes	—	Documents to ingest (text + metadata)
chunk_size	integer	No	512	Characters per chunk for splitting
chunk_overlap	integer	No	50	Overlap between chunks

Response:

{
  "collection": "product_docs",
  "documents_ingested": 1,
  "chunks_created": 4
}

---

POST /v1/rag/query

Query a RAG collection.

Request body:

{
  "collection": "product_docs",
  "query": "How does the model router work?",
  "top_k": 5,
  "score_threshold": 0.7
}

Field	Type	Required	Default	Description
collection	string	Yes	—	Collection to search
query	string	Yes	—	Natural language query
top_k	integer	No	5	Maximum results
score_threshold	float	No	0.0	Minimum similarity score

Response:

{
  "results": [
    {
      "text": "The Model Router selects which LLM provider...",
      "score": 0.89,
      "metadata": { "source": "docs", "page": 3 }
    }
  ]
}

GET /v1/tools/builtin

List all available built-in tools with metadata.

Response:

{
  "tools": [
    {
      "name": "datetime_now",
      "description": "Get the current date and time with optional timezone",
      "parameters": {
        "type": "object",
        "properties": {
          "timezone": {
            "type": "string",
            "description": "Timezone name (e.g. 'UTC', 'US/Eastern')"
          }
        }
      }
    }
  ],
  "count": 17
}

---

GET /v1/integrations

List the integration catalog: what each manifest reaches, and which credential material a connection has to supply. Never returns credential values — this is what a control plane reads to draw its connections UI.

Response:

{
  "integrations": [
    {
      "slug": "google_sheets",
      "version": "0.1.0",
      "description": "Read, overwrite and append rows on Google Sheets.",
      "base_url": "https://sheets.googleapis.com/v4",
      "auth": { "scheme": "bearer", "credential": "access_token" },
      "action_count": 4
    }
  ],
  "count": 12
}

---

GET /v1/integrations/{slug}

The same payload for one integration, plus every action with its JSON Schema.

Response:

{
  "slug": "google_sheets",
  "version": "0.1.0",
  "base_url": "https://sheets.googleapis.com/v4",
  "auth": { "scheme": "bearer", "credential": "access_token" },
  "action_count": 4,
  "actions": [
    {
      "name": "append_values",
      "description": "Append rows to the end of a sheet range.",
      "writes": true,
      "paginated": false,
      "parameters": {
        "type": "object",
        "properties": { "spreadsheet_id": { "type": "string" } },
        "required": ["spreadsheet_id"]
      }
    }
  ]
}

Errors:

Status	Description
404	No integration with that slug in the catalog

---

Observability API

GET /v1/traces/

List collected traces with optional filtering.

Query parameters:

Parameter	Type	Default	Description
agent	string	—	Filter by agent name
limit	integer	20	Max traces to return (1-100)

Response:

{
  "traces": [
    {
      "trace_id": "abc123",
      "agent": "assistant",
      "session_id": "sess_xyz",
      "spans": [
        {
          "name": "agent.run",
          "span_id": "s1",
          "duration_ms": 2340,
          "attributes": {"agent": "assistant"},
          "status": "OK"
        }
      ]
    }
  ]
}

---

GET /v1/traces/{trace_id}

Get a specific trace by ID.

Path parameters:

Parameter	Type	Description
trace_id	string	Trace identifier

Errors:

Status	Description
404	Trace not found

---

GET /v1/metrics/

Get in-memory counters and histograms.

Response:

{
  "counters": {
    "agent.runs": 150,
    "tool.executions": 420
  },
  "histograms": {
    "agent.latency_ms": {
      "count": 150,
      "sum": 345000,
      "avg": 2300,
      "min": 450,
      "max": 8900
    }
  }
}

---

POST /v1/metrics/reset

Clear all in-memory metrics.

Response:

{
  "status": "reset"
}

---

System API (Astromesh Node)

GET /v1/system/status

System status including version, uptime, and resource usage.

Response:

{
  "version": "0.35.0",
  "status": "running",
  "mode": "standalone",
  "pid": 48291,
  "uptime_seconds": 8072,
  "agents_loaded": 3,
  "providers": {
    "healthy": 2,
    "degraded": 0,
    "unavailable": 0
  }
}

---

GET /v1/system/doctor

Run health checks on all subsystems.

Response:

{
  "checks": [
    { "name": "runtime", "status": "healthy", "message": null },
    { "name": "openai", "status": "healthy", "message": "avg latency: 420ms" },
    { "name": "redis", "status": "healthy", "message": null },
    { "name": "chromadb", "status": "failing", "message": "connection refused on localhost:8000" }
  ],
  "summary": {
    "healthy": 3,
    "degraded": 0,
    "failing": 1
  }
}

Mesh API (Maia)

These endpoints are only available when mesh mode is enabled (ASTROMESH_MESH_ENABLED=true).

GET /v1/mesh/state

Get the full mesh state as seen by this node.

Response:

{
  "this_node": "node-beta",
  "leader": "node-alpha",
  "nodes": [
    {
      "node_id": "node-alpha",
      "address": "10.0.1.10:8000",
      "state": "alive",
      "heartbeat": 4521,
      "agents": ["assistant", "support"],
      "active_requests": 12
    },
    {
      "node_id": "node-beta",
      "address": "10.0.1.11:8000",
      "state": "alive",
      "heartbeat": 4519,
      "agents": ["researcher"],
      "active_requests": 5
    }
  ]
}

---

POST /v1/mesh/join

Request to join the cluster. Called by new nodes during startup.

Request body:

{
  "node_id": "node-gamma",
  "address": "10.0.1.12:8000",
  "agents": ["assistant"],
  "meta": { "version": "0.35.0" }
}

Response:

{
  "status": "joined",
  "leader": "node-alpha",
  "cluster_size": 3
}

---

POST /v1/mesh/leave

Gracefully leave the cluster. Notifies peers and drains requests.

Request body:

{
  "node_id": "node-gamma"
}

Response:

{
  "status": "left",
  "drained_requests": 2
}

---

POST /v1/mesh/heartbeat

Receive a heartbeat from a peer node.

Request body:

{
  "node_id": "node-alpha",
  "heartbeat": 4522,
  "active_requests": 14
}

Response:

{
  "ack": true
}

---

POST /v1/mesh/gossip

Exchange gossip state with a peer. Push-pull: receives the sender’s state and returns this node’s state.

Request body:

{
  "sender": "node-alpha",
  "state": [
    { "node_id": "node-alpha", "heartbeat": 4522, "state": "alive", "agents": ["assistant"] },
    { "node_id": "node-beta", "heartbeat": 4519, "state": "alive", "agents": ["researcher"] }
  ]
}

Response:

{
  "sender": "node-beta",
  "state": [
    { "node_id": "node-alpha", "heartbeat": 4520, "state": "alive", "agents": ["assistant"] },
    { "node_id": "node-beta", "heartbeat": 4520, "state": "alive", "agents": ["researcher"] },
    { "node_id": "node-gamma", "heartbeat": 4510, "state": "suspect", "agents": ["assistant"] }
  ]
}

---

POST /v1/mesh/election

Trigger or participate in a leader election.

Request body:

{
  "type": "election",
  "sender": "node-beta"
}

type Value	Description
election	Initiate election. Higher-ID nodes respond with ok
ok	Response from a higher-ID node (it will take over the election)
coordinator	Announcement from the new leader

Response:

{
  "type": "ok",
  "sender": "node-gamma"
}

WebSocket

ws://host:port/v1/ws/agent/{name}

Stream agent responses in real-time over WebSocket.

Path parameters:

Parameter	Type	Description
name	string	Agent name

Query parameters: session_id (default "default").

Client sends:

{
  "query": "Explain quantum computing"
}

Server sends (multiple messages):

Status:

{ "type": "status", "status": "processing", "agent": "assistant" }

Model text:

{ "type": "token", "content": "Quantum computing uses..." }

Tool call notification:

{
  "type": "tool_call",
  "id": "call_1",
  "name": "web_search",
  "arguments": { "query": "quantum computing basics" }
}

Tool result:

{ "type": "tool_result", "id": "call_1", "ok": true }

Completion — usage has the same shape as in POST /v1/agents/{name}/run, including by_model[].tokens_cached:

{
  "type": "done",
  "answer": "Quantum computing uses...",
  "session_id": "sess_abc123",
  "usage": { "tokens_in": 800, "tokens_out": 350, "model": "gpt-4o", "by_model": [ ... ] },
  "propuestas": []
}

Error:

{
  "type": "error",
  "message": "Provider unavailable"
}