API Reference

Complete reference for the FaraCore REST API endpoints.

Base URL

All API endpoints are prefixed with /v1:

http://127.0.0.1:8000/v1

Authentication

If FARA_AUTH_TOKEN is set, include it in the Authorization header:

Authorization: Bearer your-token

Actions

POST /v1/actions

Submit an action for evaluation.

curl -X POST http://127.0.0.1:8000/v1/actions \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "my-agent",
    "tool": "shell",
    "operation": "run",
    "params": {"cmd": "ls -la"},
    "context": {"environment": "production"}
  }'

Request Body:

agent_id (string, required) - Agent identifier
tool (string, required) - Tool name
operation (string, required) - Operation name
params (object, optional) - Action parameters
context (object, optional) - Additional context

Response: Action object with id, status, decision, reason, etc.

GET /v1/actions/{id}

Get details of a specific action.

curl http://127.0.0.1:8000/v1/actions/abc123

Response: Complete action object

GET /v1/actions

List actions with optional filters.

# List all actions
curl http://127.0.0.1:8000/v1/actions

# Filter by status
curl "http://127.0.0.1:8000/v1/actions?status=pending_approval"

# Filter by agent
curl "http://127.0.0.1:8000/v1/actions?agent_id=my-agent"

# Filter by tool
curl "http://127.0.0.1:8000/v1/actions?tool=shell"

Query Parameters:

status - Filter by status
agent_id - Filter by agent ID
tool - Filter by tool name
limit - Limit number of results
offset - Offset for pagination

POST /v1/actions/{id}/approval

Approve or deny an action.

curl -X POST http://127.0.0.1:8000/v1/actions/abc123/approval \
  -H "Content-Type: application/json" \
  -d '{
    "token": "approval-token",
    "approve": true,
    "reason": "Approved for deployment"
  }'

Request Body:

token (string, required) - Approval token from action
approve (boolean, required) - true to approve, false to deny
reason (string, optional) - Reason for approval/denial

POST /v1/actions/{id}/start

Start execution of an approved action.

curl -X POST http://127.0.0.1:8000/v1/actions/abc123/start

POST /v1/actions/{id}/result

Report the result of an executed action.

curl -X POST http://127.0.0.1:8000/v1/actions/abc123/result \
  -H "Content-Type: application/json" \
  -d '{
    "status": "succeeded",
    "output": "Command output here",
    "error": null
  }'

Events

GET /v1/events

Stream real-time events via Server-Sent Events (SSE).

curl -N http://127.0.0.1:8000/v1/events

Query Parameters:

status - Filter by status
agent_id - Filter by agent ID
tool - Filter by tool name

Event Format:

data: {"type":"action.created","data":{"id":"abc123","status":"pending_approval",...},"timestamp":"2024-01-01T00:00:00Z"}

System

GET /health

Health check endpoint. Always returns 200 OK.

curl http://127.0.0.1:8000/health

GET /ready

Readiness check endpoint. Verifies database connectivity.

curl http://127.0.0.1:8000/ready

GET /metrics

Prometheus metrics endpoint.

curl http://127.0.0.1:8000/metrics

GET /docs

Interactive API documentation (Swagger UI).

http://127.0.0.1:8000/docs

Response Format

All endpoints return JSON. Success responses include the requested data. Error responses include:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  }
}

Status Codes

200 - Success
201 - Created
400 - Bad Request
401 - Unauthorized
404 - Not Found
422 - Validation Error
500 - Internal Server Error