Evaluation routes cover the company-level quality workflow for artifacts, recovery, and human review. All routes are company-scoped and enforce company access in the handler.

​
Recent Evaluations

GET /api/companies/{companyId}/evaluations/recent?limit={limit}
Returns the most recent evaluations for the company.

​
Response Semantics

  • limit defaults to 25 and is clamped to the range 1..100.
  • The response is the direct list returned by the evaluation service.

​
Calibration Sample

GET /api/companies/{companyId}/evaluations/calibration-sample
POST /api/companies/{companyId}/evaluations/calibration-sample
GET returns the latest phase-one calibration sample. POST creates a new sample.

​
Response Semantics

  • POST accepts an optional name and persist flag; persist defaults to true.
  • POST returns the created sample with 201.

​
Operational Summary

GET /api/companies/{companyId}/evaluations/summary
Returns the phase-one operational summary for the company.

​
Review Queue

GET /api/companies/{companyId}/evaluations/review-queue?limit={limit}
POST /api/companies/{companyId}/evaluations/review-queue/assign
POST /api/companies/{companyId}/evaluations/review-queue/unassign
POST /api/companies/{companyId}/evaluations/review-queue/resolve
This queue tracks items that still need evaluation review or assignment.

​
Response Semantics

  • limit defaults to 50 and is clamped to the range 1..200.
  • GET returns queue rows enriched with assignment context for the current actor.
  • assign returns the assignment record with 201.
  • unassign returns the cleared assignment record when one exists, or { "ok": true } when there was nothing to clear.
  • resolve returns the created annotation with 201.

​
Queue Targets

The review queue routes accept these target types:
  • issue_work_product
  • document
  • run_output_artifact
  • heartbeat_run
  • issue

​
Artifact Evaluation

POST /api/companies/{companyId}/evaluations/promoted-artifacts
POST /api/companies/{companyId}/evaluations/self-healing
These routes run system-side evaluation workflows over promoted artifacts or failed runs.

​
Response Semantics

  • promoted-artifacts accepts targetType, targetId, and an optional model; it returns evaluation results with 201.
  • self-healing requires runId and accepts an optional model.
  • self-healing returns the evaluation result with 201 when a run is evaluated, or { "skipped": true, "reason": "no_failure_signal" } with 200 when there is nothing to evaluate.

​
Human Annotations

POST /api/companies/{companyId}/evaluations/annotations
Creates a human annotation for an artifact, run, or issue.

​
Response Semantics

  • Required body fields are targetType, targetId, annotatorRole, and label.
  • Optional fields include heartbeatRunId, issueId, evaluationRunId, severity, notes, and evidenceJson.
  • The route returns the created annotation with 201.

​
Dataset Seeding

POST /api/companies/{companyId}/evaluations/datasets/seed
Seeds the company’s phase-one datasets.

​
Response Semantics

  • The route returns the seeded dataset set with 201.

​
Scope Notes

  • These routes are the server’s current evaluation surface.
  • The handlers use direct service results, so the response bodies stay close to the underlying evaluation model.