Agents API

The Agents API provides endpoints for monitoring agent health (B2B) and executing analysis pipelines (B2C).

Agent Status (B2B)

Retrieve the current status of all registered agents.


GET /api/v1/admin/agents/status

Headers:


Authorization: Bearer {token}
X-Org-ID: {organization_id}

Response (200):


{
  "agents": [
    {
      "name": "extractor_agent",
      "status": "healthy",
      "latency_ms": 245,
      "error_rate": 0.02,
      "last_execution": "2026-02-08T14:23:00Z",
      "model": "gemini-2.5-pro",
      "executions_24h": 1284
    },
    {
      "name": "analyzer_agent",
      "status": "degraded",
      "latency_ms": 1820,
      "error_rate": 0.15,
      "last_execution": "2026-02-08T14:22:58Z",
      "model": "gpt-5.1",
      "executions_24h": 1190
    },
    {
      "name": "validator_agent",
      "status": "offline",
      "latency_ms": null,
      "error_rate": 1.0,
      "last_execution": "2026-02-08T12:00:00Z",
      "model": "deepseek-v3",
      "executions_24h": 580
    }
  ]
}

Agent Status Values

Status	Description
`healthy`	Agent is operating normally with error rate below threshold
`degraded`	Agent is responding but with elevated latency or error rate
`offline`	Agent is not responding or has a 100% error rate

System Health Summary (B2B)

Get an aggregated health summary across all agents.


GET /api/v1/admin/agents/summary

Response (200):


{
  "total_agents": 54,
  "healthy": 50,
  "degraded": 3,
  "offline": 1,
  "avg_latency_ms": 340,
  "total_executions_24h": 45200,
  "system_status": "degraded"
}

Run Analysis (B2C)

Execute a full analysis pipeline. This endpoint uses Server-Sent Events (SSE) to stream progress and results in real time.


POST /api/v1/analyze

Headers:


Authorization: Bearer {token}
Content-Type: application/json
Accept: text/event-stream

Request:


{
  "image_url": "https://example.com/photo.jpg",
  "analysis_type": "full",
  "options": {
    "include_analysis": true,
    "budget_range": [50, 200]
  }
}

SSE Event Stream

The response is a stream of Server-Sent Events. Each event has a type field indicating the event kind.


event: pipeline_start
data: {"pipeline_id": "pipe_abc123", "agents": ["extractor", "analyzer", "validator", "reporter"]}

event: agent_start
data: {"agent": "extractor", "model": "gemini-2.5-pro"}

event: token
data: {"agent": "extractor", "content": "Analyzing input composition"}

event: agent_progress
data: {"agent": "extractor", "progress": 0.45, "message": "Processing input..."}

event: agent_complete
data: {"agent": "extractor", "result": {"entities": [{"type": "document", "category": "technical"}]}, "latency_ms": 1240, "cost": 0.0032}

event: cost_update
data: {"pipeline_id": "pipe_abc123", "total_cost": 0.0032, "by_agent": {"extractor": 0.0032}}

event: agent_start
data: {"agent": "analyzer", "model": "gpt-5.1"}

event: agent_complete
data: {"agent": "analyzer", "result": {"analysis_profile": "detailed", "score": 8.2}, "latency_ms": 980, "cost": 0.0045}

event: cost_update
data: {"pipeline_id": "pipe_abc123", "total_cost": 0.0077, "by_agent": {"extractor": 0.0032, "analyzer": 0.0045}}

event: complete
data: {"pipeline_id": "pipe_abc123", "total_latency_ms": 4500, "total_cost": 0.0142, "result": {"entities": [...], "analysis_profile": "detailed", "results": [...]}}

SSE Event Types

Event	Description
`pipeline_start`	Pipeline execution has begun, lists agents in the pipeline
`agent_start`	An individual agent has started processing
`token`	Streaming text token from an agent (for real-time display)
`agent_progress`	Progress update from a running agent
`agent_complete`	An agent has finished, includes result and cost
`cost_update`	Running cost total for the pipeline
`error`	An error occurred in an agent or the pipeline
`complete`	Pipeline finished, includes aggregated results

Consuming SSE in JavaScript


const response = await fetch('https://api.curate-me.ai/api/v1/analyze', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ image_url, analysis_type: 'full' }),
});
 
const reader = response.body.getReader();
const decoder = new TextDecoder();
 
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
 
  const chunk = decoder.decode(value);
  const lines = chunk.split('\n');
 
  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const event = JSON.parse(line.slice(6));
      console.log(event);
    }
  }
}

Analysis History (B2C)

Retrieve past analysis results with pagination.


GET /api/v1/analyze/history?offset=0&limit=20

Headers:


Authorization: Bearer {token}

Response (200):


{
  "items": [
    {
      "analysis_id": "pipe_abc123",
      "created_at": "2026-02-08T14:23:00Z",
      "analysis_type": "full",
      "status": "completed",
      "total_cost": 0.0142,
      "total_latency_ms": 4500
    }
  ],
  "total": 87,
  "offset": 0,
  "limit": 20
}

Analysis Details (B2C)

Retrieve the full result of a specific analysis.


GET /api/v1/analyze/{analysis_id}

Headers:


Authorization: Bearer {token}

Response (200):


{
  "analysis_id": "pipe_abc123",
  "created_at": "2026-02-08T14:23:00Z",
  "analysis_type": "full",
  "status": "completed",
  "total_cost": 0.0142,
  "total_latency_ms": 4500,
  "agents": [
    {
      "name": "extractor",
      "model": "gemini-2.5-pro",
      "latency_ms": 1240,
      "cost": 0.0032,
      "result": { "entities": [{ "type": "document", "category": "technical" }] }
    },
    {
      "name": "analyzer",
      "model": "gpt-5.1",
      "latency_ms": 980,
      "cost": 0.0045,
      "result": { "analysis_profile": "detailed", "score": 8.2 }
    }
  ],
  "result": {
    "entities": [...],
    "analysis_profile": "detailed",
    "results": [...]
  }
}