Inference

The inference endpoint is the core of Ctrl AI. It takes a natural language query, finds matching verified units, executes them, and returns a trust-tagged response with per-claim attribution.

Run a Query

POST /api/v1/inference

Request Body

Field	Type	Required	Description
`query`	string	Yes	The natural language question
`domainId`	string	No	Scope to a specific domain
`jurisdiction`	string	No	Jurisdiction filter (e.g., "US", "EU")
`sessionId`	string	No	Resume a multi-turn session
`additionalInputs`	object	No	Answers to pending gate questions
`includeUnverified`	boolean	No	Include candidate units (default: false)

Example Request

curl -X POST https://app.ctrlai.com/api/v1/inference \
  -H "Authorization: Bearer ctrlai_pk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is the credit risk assessment for an applicant with income $85,000 and credit score 720?"
  }'

Response

{
  "data": {
    "response": "Based on the verified credit risk assessment framework...",
    "segments": [
      {
        "text": "The applicant's DTI ratio of 28% is below the 43% threshold",
        "trustLevel": "verified",
        "unitId": "01HX...",
        "unitName": "DTI Threshold Check"
      },
      {
        "text": "Credit score of 720 places the applicant in the 'good' tier",
        "trustLevel": "expert_reviewed",
        "unitId": "01HY...",
        "unitName": "Credit Score Classification"
      }
    ],
    "trustSummary": {
      "verified": 2,
      "expertReviewed": 3,
      "synthesized": 0,
      "neural": 1
    },
    "coveragePercent": 83,
    "unitsUsed": [
      {
        "id": "01HX...",
        "name": "DTI Threshold Check",
        "type": "program",
        "status": "verified",
        "verificationScore": 100
      }
    ],
    "mode": "full_coverage",
    "sessionId": null,
    "pendingQuestions": [],
    "modelsUsed": {
      "parse": { "provider": "gemini", "model": "gemini-2.5-flash" },
      "evaluate": { "provider": "gemini", "model": "gemini-2.5-flash" },
      "prose": { "provider": "gemini", "model": "gemini-2.5-flash" }
    }
  }
}

Response Fields

Field	Type	Description
`response`	string	Full prose response
`segments`	array	Trust-tagged response segments
`segments[].trustLevel`	string	`verified`, `expert_reviewed`, `synthesized`, or `neural`
`segments[].unitId`	string	ID of the unit that produced this segment
`trustSummary`	object	Count of segments per trust level
`coveragePercent`	number	Percentage of query covered by verified units
`unitsUsed`	array	Units that fired during execution
`mode`	string	`full_coverage`, `partial_coverage`, or `neural_only`
`sessionId`	string	Non-null if this is a multi-turn session
`pendingQuestions`	array	Questions the user needs to answer (protocol gates)
`modelsUsed`	object	LLM provider + model for each role

Multi-Turn Sessions (Agentic Flows)

When a Protocol unit has an interactive gate, execution pauses and returns pending questions:

{
  "data": {
    "response": "I need additional information to proceed...",
    "sessionId": "01HZ...",
    "pendingQuestions": [
      {
        "question": "Has the applicant's identity been verified?",
        "options": ["Yes, verified", "No, not yet", "Escalate to compliance"]
      }
    ]
  }
}

Resume the session by including sessionId and additionalInputs:

curl -X POST https://app.ctrlai.com/api/v1/inference \
  -H "Authorization: Bearer ctrlai_pk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "01HZ...",
    "additionalInputs": {
      "identity_verified": "Yes, verified"
    }
  }'

Save as Unit

Convert a useful response segment into a candidate unit:

POST /api/v1/inference/save-as-unit

Field	Type	Required	Description
`segmentText`	string	Yes	The response text to formalize
`domainId`	string	Yes	Target domain
`unitType`	string	No	Preferred unit type

Feedback

Record feedback on inference claims:

POST /api/v1/inference/feedback

Field	Type	Required	Description
`inferenceLogId`	string	Yes	The inference log entry
`segmentIndex`	number	Yes	Which segment
`feedback`	string	Yes	`confirm` or `incorrect`

On this page