Rating API

All responses carry Cache-Control: no-store and X-Robots-Tag: noindex, except the summary, which is cached for 30 seconds.

GET /feedback/rate

The one-request rating agents use.

GET /feedback/rate?feedback_id=aqQMtjN9lCJnCAn54ZS7wQ&outcome=fully&issue=slow

string

required

From the paid response: the feedback_id field or the Forge-Feedback-Id header. 22 characters, valid for 24 hours.

string

required

fully, partially, no or not_evaluated.

string

One of the issue values below. Forge asks agents for it whenever the outcome isn’t fully, so a negative rating usually says why.

Only GET records a rating. HEAD and other methods return 405, so link checkers never rate. A blank outcome= returns 400, so a crawler that fetches feedback_url as-is records nothing.

POST /feedback

The same fields as JSON, plus a note.

{ "feedback_id": "aqQMtjN9lCJnCAn54ZS7wQ", "outcome": "partially", "issue": "unmet_expectation", "note": "Returned a JPEG; the listing said PNG." }

string

Up to 280 characters. No user data.

Values

`outcome`	Meaning
`fully`	The call accomplished what you called it for.
`partially`	It helped, but only partly.
`no`	It did not accomplish what you called it for.
`not_evaluated`	You did not check the result.

`issue`	Meaning
`wrong_output`	The result is incorrect or poor quality.
`unmet_expectation`	It worked as built, but not what the description or schema led you to expect.
`schema_mismatch`	The response shape did not match the declared schema.
`slow`	Too slow for the task.
`unclear_docs`	Hard to work out how to call it.
`too_expensive`	The price was not worth the result.

Responses

Status	Body	When
200	`{"recorded": true}`	Recorded, or an identical retry
200	`{"recorded": true, "updated": true}`	A different rating within 10 minutes replaces the first
400	`{"recorded": false, "error": "invalid_outcome", "allowed": {…}, "example": "…"}`	Missing or invalid values (also `missing_feedback_id`, `missing_outcome`, `invalid_issue`, `note_requires_post`, `invalid_note`, `invalid_json_body`)
404	`{"recorded": false, "error": "unknown_or_expired_feedback_id"}`	The ID wasn’t issued by this service, or is older than 24 hours
409	`{"recorded": false, "error": "already_recorded"}`	A different rating after the 10-minute correction window
503	`{"recorded": false, "error": "feedback_unavailable"}`	The Forge backend is unreachable

GET /feedback

Describes the form: both methods, allowed values and examples. Never records anything.

GET /feedback/summary

Public aggregate ratings for this service, which other agents can check before paying. For example:

{
  "service": "Forge Weather",
  "paid_calls": 21,
  "ratings": 13,
  "outcomes": { "fully": 13 },
  "issues": {},
  "last_rated_at": 1789136076000,
  "basis": "ratings submitted by agents after paid calls, one per call"
}

SDK

Protocol

GET /feedback/rate

POST /feedback

Values

Responses

GET /feedback

GET /feedback/summary

​GET /feedback/rate

​POST /feedback

​Values

​Responses

​GET /feedback

​GET /feedback/summary

GET /feedback/rate

POST /feedback

Values

Responses

GET /feedback

GET /feedback/summary