Developer API Reference

API Reference

mate exposes a Minimal API REST interface from mate.WebUI. The interactive explorer and machine-readable spec are always up to date:

• Interactive Explorer (Scalar): /scalar/v1
• OpenAPI JSON spec: /openapi/v1.json

---

Authentication

All endpoints require one of:

Method	Header / Cookie	Scheme
Session cookie (browser)	Set by OIDC login	EntraId / Generic
API Key	X-API-Key: <key>	ApiKey
Bearer token	Authorization: Bearer <jwt>	EntraId JWT

In Generic auth mode (local dev), all endpoints are accessible without credentials.

API key roles enforce endpoint-level access:

Role	Allowed
Viewer	Read-only access
Tester	Viewer access + execute test runs
TenantAdmin	Full tenant-level management
SuperAdmin	Full global access

---

Endpoint Index

Agents

Method	Path	Description
GET	/api/agents	List all agents
GET	/api/agents/{id}	Get agent by ID
POST	/api/agents	Create agent
PUT	/api/agents/{id}	Update agent
DELETE	/api/agents/{id}	Delete agent
POST	/api/agents/{id}/test-connection	Run health + config validation

Test Suites

Method	Path	Description
GET	/api/testsuites	List test suites
GET	/api/testsuites/{id}	Get suite
POST	/api/testsuites	Create suite
PUT	/api/testsuites/{id}	Update suite
DELETE	/api/testsuites/{id}	Delete suite

Test Cases

Method	Path	Description
GET	/api/testcases?suiteId={id}	List test cases for a suite
POST	/api/testcases	Create test case
PUT	/api/testcases/{id}	Update test case
DELETE	/api/testcases/{id}	Delete test case

Runs & Results

Method	Path	Description
POST	/api/runs	Start a new run
GET	/api/runs?suiteId={id}	List runs for a suite
GET	/api/runs/{id}	Get run details
DELETE	/api/runs/{id}	Delete run
GET	/api/results?runId={id}	Get results for a run

Documents

Method	Path	Description
GET	/api/documents	List documents
POST	/api/documents	Upload document (multipart/form-data)
DELETE	/api/documents/{id}	Delete document

Modules

Method	Path	Description
GET	/api/modules/agent-connectors	List registered connector modules + config schemas
GET	/api/modules/testing	List registered judge modules

Judge Settings

Method	Path	Description
GET	/api/judgesettings	Get current judge config
POST	/api/judgesettings	Create/update judge config

Metrics

Method	Path	Description
GET	/api/metrics/rubric-breakdown	Per-criteria average scores
GET	/api/metrics/module-breakdown	Per-module pass/fail counts

Admin

Method	Path	Description
GET	/api/admin/api-keys	List API keys
POST	/api/admin/api-keys	Generate API key
DELETE	/api/admin/api-keys/{id}	Revoke/delete API key
GET	/api/admin/audit-log	Paginated audit log

Health

Method	Path	Description
GET	/health/live	Liveness probe
GET	/health/ready	Readiness probe (DB + modules)
GET	/health/modules	Per-module health JSON

---

Common Response Codes

Code	Meaning
200	Success
201	Created
204	Deleted / no content
400	Validation error — body contains errors object
401	Missing or invalid credentials
403	Insufficient scope
404	Resource not found
500	Server error

---

Example — Start a Run via API Key

curl -X POST https://your-mate-instance/api/runs \
  -H "X-API-Key: your-write-scope-key" \
  -H "Content-Type: application/json" \
  -d '{"testSuiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}'

---

Further Reading

• API Keys — how to generate and scope keys
• Architecture — how the API layer is structured in code