API Reference¶

Base URL: http://conductor-e-api:8080 (internal ClusterIP)

Endpoints¶

Health¶

GET /health

{"status": "healthy", "timestamp": "2026-04-02T06:56:08Z"}

Submit Event¶

POST /api/events

Submit any rig event. The stream ID is derived from repo#issueNumber for issue events, or agentId for heartbeats.

Request:

{
  "type": "ISSUE_APPROVED",
  "repo": "Stig-Johnny/star-rewards",
  "issueNumber": 547,
  "title": "feat: Add Firestore rules CI check",
  "priority": "normal",
  "dependsOn": []
}

Response (200):

{
  "streamId": "Stig-Johnny/star-rewards#547",
  "type": "ISSUE_APPROVED",
  "timestamp": "2026-04-02T06:56:22Z"
}

Error (400):

{"error": "Unknown event type: INVALID"}

See Event Store for all event types and their fields.

Get Issues¶

GET /api/issues
GET /api/issues?state=queued

Returns all tracked issues, optionally filtered by state.

States: queued, assigned, in_progress, in_review, deploying, done, failed

Get Priority Queue¶

GET /api/queue

Returns unassigned issues sorted by priority (critical > high > normal > oldest).

Get Next Assignment¶

GET /api/assignments/next?agentId=dev-e-1

Returns the top-priority unassigned issue, or 204 No Content if nothing available.

Response (200):

{
  "streamId": "Stig-Johnny/star-rewards#547",
  "issue": {
    "number": 547,
    "repo": "Stig-Johnny/star-rewards",
    "title": "feat: Add Firestore rules CI check",
    "milestone": null
  },
  "priority": "normal",
  "attempt": 1
}

Get Agent Status¶

GET /api/agents

Returns status of all known agents (populated by heartbeat events).

Get Event Stream¶

GET /api/events/stream?id=Stig-Johnny/star-rewards%23547

Returns all events for a specific stream. The id parameter must be URL-encoded (use %23 for #).

Response:

[
  {
    "id": "uuid",
    "type": "IssueApproved",
    "data": { "repo": "...", "issueNumber": 547, "title": "..." },
    "timestamp": "2026-04-02T06:56:22Z"
  }
]

Architecture¶

POST /api/events → SubmitEvent (Use Case) → IEventStore (Port) → MartenEventStore (Adapter) → PostgreSQL

GET /api/queue   → IIssueQuery (Port) → MartenIssueQuery (Adapter) → PostgreSQL (Marten projection)

Clean Architecture: endpoints delegate to use cases/ports, never touch Marten directly.