decide¶

Make a decision using a clone via its API key.

Endpoint¶

POST https://api.cloman.app/api/v1/public/decide

Authentication¶

Requires an X-API-Key header with a valid API key that has the decide scope.

X-API-Key: cloman_sk_your_key_here

Request Body¶

Field	Type	Required	Default	Description
`context`	`string`	Yes	—	The question or situation to decide on. Must be non-empty.
`action_type`	`string`	No	`"general"`	Type of action being requested.
`data`	`object`	No	`{}`	Action-specific structured data passed to the clone.

Example Request¶

{
  "context": "Should we approve this refund request for $49.99?",
  "action_type": "approval",
  "data": {
    "amount": 49.99,
    "reason": "defective product",
    "customer_tier": "premium"
  }
}

Response Body¶

Field	Type	Description
`decision_id`	`string`	Unique identifier for this decision.
`clone_id`	`string`	ID of the clone that made the decision.
`clone_name`	`string`	Human-readable name of the clone.
`decision`	`string`	The clone's recommendation.
`reasoning`	`string`	Explanation of why this decision was made.
`confidence`	`float`	Confidence score between 0.0 and 1.0.
`confidence_level`	`string`	Human-readable confidence: `high`, `medium`, or `low`.
`requires_human_review`	`boolean`	Whether the clone recommends human review.
`was_escalated`	`boolean`	Whether guardrails triggered an escalation.
`alternatives_considered`	`array`	Other options the clone considered.
`processing_time_ms`	`float`	Time taken to process the decision in milliseconds.
`created_at`	`string`	ISO 8601 timestamp of when the decision was created.

Example Response¶

{
  "decision_id": "dec_abc123",
  "clone_id": "cln_xyz789",
  "clone_name": "Customer Support Clone",
  "decision": "approve",
  "reasoning": "The refund amount is within policy limits.",
  "confidence": 0.92,
  "confidence_level": "high",
  "requires_human_review": false,
  "was_escalated": false,
  "alternatives_considered": [
    {
      "action": "deny",
      "reason": "Amount exceeds typical threshold",
      "confidence": 0.08
    }
  ],
  "processing_time_ms": 234.5,
  "created_at": "2026-02-19T12:00:00Z"
}

Error Responses¶

All errors follow a consistent format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description.",
    "status": 401,
    "details": {},
    "request_id": "req_abc123",
    "timestamp": "2026-02-19T12:00:00Z"
  }
}

Status	Code	Meaning
401	`AUTHENTICATION_ERROR`	Missing or invalid API key
403	`AUTHORIZATION_ERROR`	API key lacks the `decide` scope
404	`CLONE_NOT_FOUND`	Clone does not exist or key is not linked
422	`VALIDATION_ERROR`	Invalid request body
429	`RATE_LIMIT_EXCEEDED`	Rate limit exceeded
500	`INTERNAL_ERROR`	Server error
502	`LLM_SERVICE_ERROR`	AI service temporarily unavailable

See Error Codes for the full list.