API v1
v1
View as Markdown

Send agent feedback

POST /api/v1/agent-feedback

Tell the administrators of this instance about a problem with a tool. This is what the submit-feedback MCP tool calls. The person the agent works for never sees the report in Monica, only the call in their MCP history.

Send it at most once per task, and only when a tool got in the way. Paraphrase what the person asked, and use placeholders such as <contact> or <date> instead of names, dates and other details from the vault. Never include secrets.

Body parameters

Sent as JSON. Anything not listed here is ignored.

kind string Required

bug when a tool failed or returned something wrong, missing_tool when no tool could do it, unclear_description when a description misled you, improvement for a suggestion.

severity string Required

blocks_task when the task could not be finished, needs_workaround when it was finished another way, minor when it was finished with friction.

title string Required

One line naming the problem, up to 200 characters.

tool string Optional

The tool the report is about, or the name of the tool that is missing, up to 100 characters.

request string Optional

What the person asked, paraphrased, up to 4,000 characters.

steps array Optional

The tool calls tried, in order, at most 20. Each holds tool (required), arguments as a string, outcome (success or error, required) and result.

observed string Required

What happened, up to 4,000 characters. A placeholder such as test, todo or n/a answers 422.

expected string Required

What should have happened, up to 4,000 characters.

proposed_fix string Required

The fix you suggest, up to 4,000 characters.

proposed_code string Optional

Code for the fix, up to 8,000 characters.

model string Optional

The model the agent runs on, up to 100 characters.

Returns

The id of the report and its status.

id uuid

The id of the report.

status string

Always new.

Rate limit

Ten requests per minute, per user. Every answer carries the budget left in X-RateLimit-Remaining.

POST
curl https://my.monicahq.com/api/v1/agent-feedback \
-X POST \
-H "Authorization: Bearer $MONICA_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"kind": "bug",
"severity": "blocks_task",
"title": "Yearly reminders on 29 February are refused",
"tool": "create-contact-reminder",
"steps": [
{
"tool": "create-contact-reminder",
"arguments": "{\"contact\": \"<contact>\", \"day\": 29, \"month\": 2}",
"outcome": "error",
"result": "The date field must be a valid date."
}
],
"observed": "Any reminder on 29 February fails validation, with or without a year.",
"expected": "The reminder is created and falls on 28 February in other years.",
"proposed_fix": "Validate the day against a leap year when no year is given."
}'
const response = await fetch('https://my.monicahq.com/api/v1/agent-feedback', {
method: 'POST',
headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
body: JSON.stringify({
kind: 'bug',
severity: 'blocks_task',
title: 'Yearly reminders on 29 February are refused',
tool: 'create-contact-reminder',
steps: [{"tool":"create-contact-reminder","arguments":"{\"contact\": \"<contact>\", \"day\": 29, \"month\": 2}","outcome":"error","result":"The date field must be a valid date."}],
observed: 'Any reminder on 29 February fails validation, with or without a year.',
expected: 'The reminder is created and falls on 28 February in other years.',
proposed_fix: 'Validate the day against a leap year when no year is given.',
}),
})
const data = await response.json()
$response = Http::withToken($token)->post('https://my.monicahq.com/api/v1/agent-feedback', [
'kind' => 'bug',
'severity' => 'blocks_task',
'title' => 'Yearly reminders on 29 February are refused',
'tool' => 'create-contact-reminder',
'steps' => [['tool' => 'create-contact-reminder', 'arguments' => '{"contact": "<contact>", "day": 29, "month": 2}', 'outcome' => 'error', 'result' => 'The date field must be a valid date.']],
'observed' => 'Any reminder on 29 February fails validation, with or without a year.',
'expected' => 'The reminder is created and falls on 28 February in other years.',
'proposed_fix' => 'Validate the day against a leap year when no year is given.',
]);
Response 201
{
"id": "3d9b7e21-6f4a-4c85-9a02-b81e5c47d613",
"status": "new"
}

Keys act as you, with exactly the access you have. Make one per integration so you can revoke it alone.