Documentation Index
Fetch the complete documentation index at: https://docs.meshai.dev/llms.txt
Use this file to discover all available pages before exploring further.
Send Heartbeat
Report that an agent is alive. Updates the agent’s last_heartbeat timestamp and sets status to healthy.
curl -X POST https://api.meshai.dev/heartbeat \
-H "Authorization: Bearer msh_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "agt_abc123"
}'
{
"success": true,
"data": {
"agent_id": "agt_abc123",
"status": "healthy",
"last_heartbeat": "2026-03-17T10:30:00Z"
}
}
Status Transitions
| Condition | Status |
|---|
| Heartbeat received within 2 minutes | healthy |
| No heartbeat for 2–5 minutes | degraded |
| No heartbeat for 5+ minutes | down |
| Never sent a heartbeat | unknown |
Report Single Usage
Report a single LLM API call with token counts and optional cost.
curl -X POST https://api.meshai.dev/telemetry/usage \
-H "Authorization: Bearer msh_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "agt_abc123",
"model_provider": "openai",
"model_name": "gpt-4o",
"input_tokens": 1500,
"output_tokens": 800,
"request_type": "chat.completions",
"cost_usd": 0.035
}'
Request Body
| Field | Type | Required | Description |
|---|
agent_id | string | Yes | Agent ID |
model_provider | string | Yes | openai, anthropic, google, nvidia, bedrock |
model_name | string | Yes | Model identifier (e.g., gpt-4o) |
input_tokens | integer | Yes | Input/prompt token count |
output_tokens | integer | Yes | Output/completion token count |
request_type | string | No | e.g., chat.completions, embeddings |
cost_usd | float | No | Explicit cost. If omitted, calculated from pricing tables. |
{
"success": true,
"data": {
"id": "usg_abc123",
"agent_id": "agt_abc123",
"model_provider": "openai",
"model_name": "gpt-4o",
"input_tokens": 1500,
"output_tokens": 800,
"cost_usd": 0.035,
"recorded_at": "2026-03-17T10:30:00Z"
}
}
Report Batch Usage
Report multiple usage events in a single request. More efficient than sending individual events.
curl -X POST https://api.meshai.dev/telemetry/usages \
-H "Authorization: Bearer msh_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"usages": [
{
"agent_id": "agt_abc123",
"model_provider": "openai",
"model_name": "gpt-4o",
"input_tokens": 1500,
"output_tokens": 800
},
{
"agent_id": "agt_abc123",
"model_provider": "openai",
"model_name": "gpt-4o-mini",
"input_tokens": 500,
"output_tokens": 200
},
{
"agent_id": "agt_def456",
"model_provider": "anthropic",
"model_name": "claude-sonnet-4-20250514",
"input_tokens": 2000,
"output_tokens": 1200
}
]
}'
{
"success": true,
"data": {
"accepted": 3,
"rejected": 0,
"errors": []
}
}
errors array but do not block the rest of the batch.
