AimableDocs
DocsAPI Reference
POST/v1/spaces/{space_id}/responses

Create Response Route

Create a programmatic LLM response with Aimable governance applied. See [spec.md](specs/responses-endpoint/spec.md) User Story 1.

Path Parameters

NameTypeRequiredDescription
space_idstring (uuid)Required

Headers

NameTypeRequiredDescription
Idempotency-KeystringOptional
Last-Event-IDstringOptional
X-API-KeystringOptional

Request Body

application/jsonRequired
inputobjectRequired
modelobjectTenant_model alias. Must be in the space's allow-list. Omit to use the space's default model.
toolsobject
tool_choiceobject
tool_modestringDefault ``auto_resolve`` per Clarifications Q2 — the backend runs the LLM → tool → LLM loop until a final response.
auto_resolvereturn_calls
max_output_tokensobject
reasoningobject
streamboolean
previous_response_idobject
idempotency_keyobject
metadataobject
aimableobject

Request

curl -X POST '/api-proxy/v1/spaces/{space_id}/responses' \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "input": {},
  "model": {},
  "tools": {},
  "tool_choice": {},
  "tool_mode": "auto_resolve",
  "max_output_tokens": {},
  "reasoning": {},
  "stream": false,
  "previous_response_id": {},
  "idempotency_key": {},
  "metadata": {},
  "aimable": {}
}'

Response

201(generated)
{
  "data": {
    "id": "string",
    "object": "response",
    "status": "queued",
    "created_at": "2024-01-01T00:00:00Z",
    "finished_at": {},
    "expires_at": "2024-01-01T00:00:00Z",
    "space_id": "550e8400-e29b-41d4-a716-446655440000",
    "model": "string",
    "model_alias": "string",
    "previous_response_id": {},
    "output": [
      {}
    ],
    "usage": {
      "input_tokens": 0,
      "output_tokens": 0,
      "reasoning_tokens": 0,
      "cost_usd": "0.000000"
    },
    "aimable": {
      "langfuse_trace_id": {},
      "governance_applied": {},
      "iteration_count": 0,
      "failure_reason": {}
    }
  }
}

Error Responses