API Reference

SOFE Server (FastAPI) and hosted API (api.sofe.dev) endpoints.

Authentication

X-API-Key: sk_sofe_your_key_here

Get your key at platform.sofe.dev/keys

Endpoints

POST/evaluate

Run policies against connected account

Request body:
{"policies": ["no-idle-ec2"], "regions": ["us-east-1"]}
Response:
{"findings_count": 48, "resources_scanned": 64,
 "resources_by_type": {"aws.lambda": 12, "aws.s3": 8, ...},
 "findings": [{policy_name, severity, resource_id, recommendation,
   remediation_commands: [{label, command, risk, note}]}]}
POST/validate

Check policy YAML syntax

Request body:
{"policy_yaml": "apiVersion: sofe/v1\nkind: Policy..."}
Response:
{"valid": true, "errors": []}
GET/policies

List available policies

Response:
{"policies": [{name, severity, description}], "total": 20}
GET/evaluations

Evaluation history (paginated)

Response:
{"evaluations": [{id, timestamp, findings_count}], "total": 15}
GET/evaluations/:id

Full evaluation detail with findings

Response:
{"findings": [...], "resources_by_type": {...}, "trigger": "manual"}
GET/collectors

List all available collectors

Response:
[{name, resource_type, metrics}]
GET/health

Status check (public, no auth)

Response:
{"status": "ok", "version": "0.2.0"}

Rate Limits

Rate limits apply only to POST /evaluate. All read endpoints (GET /evaluations, /collectors, /policies) are unlimited.

TierEvaluations/dayAPI Keys
Free101
Pro ($29/mo)1,00010
EnterpriseUnlimitedUnlimited

Error Codes

401Missing or invalid API key
429Rate limit exceeded (try again tomorrow or upgrade)
422Invalid request (malformed policy YAML, unknown policy name)
500Internal error (AWS API failure, please retry)
← Developing CollectorsNext: CI/CD Integration →