Skip to main content
POST /v1/agents/runs Invoke any of your account’s agents by passing the agent identifier in the request body,

​
Request

{
  "agent": "agt_06F7557C5CM18FNXB2V5D4V72R",
  "input": "What does the privacy spec promise?",
  "conversation_id": null
}
FieldTypeRequiredNotes
agentstringyesAgent identifier (agt_…) from the portal or POST /v1/agents.
inputstringyesEnd-user message. Up to 8000 chars.
conversation_idstringnoContinue an existing conversation. Omit to auto-create one.
To stream the response, append ?stream=true and read the body as Server-Sent Events. See Streaming below.

​
Response

{
  "id": "msg_…",
  "agent_id": "agt_…",
  "conversation_id": "conv_…",
  "output": "MESH classifies every call into one of four privacy classes…",
  "sources": [{ "documentId": "doc_…", "chunkId": "chk_…", "score": 0.82 }],
  "usage": {
    "input_tokens": 142,
    "output_tokens": 318
  },
  "route": {
    "tier": "auto",
    "model": "mesh/claude-sonnet-4"
  }
}

​
Examples

​
curl

curl -X POST https://api.meshrouter.app/v1/agents/runs \
  -H "Authorization: Bearer $MESH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "agt_06F7557C5CM18FNXB2V5D4V72R",
    "input": "Your question here"
  }'

​
TypeScript (@meshrouter/sdk ≥ 0.2.0)

import { Mesh } from '@meshrouter/sdk';

const mesh = new Mesh({ apiKey: process.env.MESH_API_KEY! });

const run = await mesh.agents.run({
  agent: 'agt_06F7557C5CM18FNXB2V5D4V72R',
  input: 'Your question here',
});

console.log(run.output);

​
Python (meshrouter ≥ 0.2.0)

import os
from meshrouter import MeshClient

mesh = MeshClient(api_key=os.environ["MESH_API_KEY"])

run = mesh.invoke_agent(
    agent="agt_06F7557C5CM18FNXB2V5D4V72R",
    input="Your question here",
)

print(run.data["output"])

​
Streaming

Add ?stream=true to receive Server-Sent Events as the agent generates output. Events are line-delimited; each carries event: and data: lines in the standard SSE format.

​
TypeScript

for await (const chunk of mesh.agents.stream({
  agent: 'agt_…',
  input: 'Your question here',
})) {
  if (chunk.delta) process.stdout.write(chunk.delta);
}

​
Python

for event in mesh.stream_agent(
    agent="agt_…",
    input="Your question here",
):
    print(event.event, event.data)

​
Authentication

Send the API key with Authorization: Bearer mesh_live_…. The key must carry the chat scope. Issue keys from the portal under API keys.

​
Errors

StatuscodeWhen
400invalid_requestMissing agent or input, or body is not valid JSON.
401unauthorizedAPI key missing or rejected.
402insufficient_fundsAccount credit balance can’t cover the reserved estimate for this call.
404not_foundAgent id does not belong to this account, or the supplied conversation_id does not exist.
429conversation_limit_exceededAgent has reached its per-agent conversation cap.

​
Legacy endpoint

POST /v1/agents/{agentId}/chat (agent id in URL, no agent body field) still works for the moment. Responses carry a Deprecation: true header and a Sunset date — switch your clients to POST /v1/agents/runs before the sunset to avoid breakage.