API Reference

Authentication

All Reasoning Engine endpoints require these headers:

Header	Value	Description
Authorization	Bearer {access_token}	OAuth 2.0 bearer token (client credentials flow)
Ocp-Apim-Subscription-Key	{subscription_key}	API Management subscription key
Content-Type	application/json	Required for all POST requests

Endpoints

The Reasoning Engine exposes a workflow-based API with synchronous and asynchronous execution modes.

Synchronous Execution

POST /reasoning-engine/workflows/main

Runs the full pipeline and returns the result when complete. Use for simple integrations where blocking is acceptable.

Response: The complete output schema.

Asynchronous Execution

POST /reasoning-engine/workflows/main/start-async

Starts the pipeline and returns immediately with a runId. Use for production integrations to avoid HTTP timeouts.

Response:

{
  "runId": "run-a1b2c3d4"
}

Poll Run Status

GET /reasoning-engine/workflows/main/runs/{runId}

Check the status of an async run and retrieve the result when complete.

Response:

{
  "status": "completed",
  "result": { }
}

Status values: running, completed, failed.

Request Body

All execution endpoints accept the same request body.

Required Fields

Field	Type	Description
objective	string	The analytical question the engine should answer

Data Inputs

At least one of series or datasets should be provided.

Field	Type	Description
series	array (optional)	Time-series data. Each item: {id, label, points: [{t, v}]} where t is an ISO timestamp and v is a numeric value
datasets	array (optional)	Numeric datasets for correlation. Each item: {id, label, values: [number]}

Optional Fields

Field	Type	Description
hints	string[] (optional)	Context hints to guide the analysis
outputProfile	string (optional)	Output format profile (default: "default")
taskId	string (optional)	Custom task identifier for tracing

Example Request

{
  "objective": "Analyze the relationship between sleep duration and mood scores over the past month",
  "series": [
    {
      "id": "sleep_hours",
      "label": "Sleep Duration",
      "points": [
        { "t": "2025-02-15", "v": 7.5 },
        { "t": "2025-02-16", "v": 6.2 },
        { "t": "2025-02-17", "v": 8.1 }
      ]
    },
    {
      "id": "mood_score",
      "label": "Mood Score",
      "points": [
        { "t": "2025-02-15", "v": 8 },
        { "t": "2025-02-16", "v": 5 },
        { "t": "2025-02-17", "v": 9 }
      ]
    }
  ],
  "hints": ["User reports feeling tired on weekdays"],
  "outputProfile": "default"
}

curl Example

curl -X POST "$BASE_URL/reasoning-engine/workflows/main" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Ocp-Apim-Subscription-Key: $SUBSCRIPTION_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "objective": "What trends exist in my sleep data?",
    "series": [
      {
        "id": "sleep",
        "label": "Sleep Hours",
        "points": [
          {"t": "2025-03-01", "v": 7.0},
          {"t": "2025-03-02", "v": 6.5},
          {"t": "2025-03-03", "v": 5.8}
        ]
      }
    ]
  }'

Response

See the complete Output Schema for the full response structure.

Key top-level fields in the response:

Field	Always Present	Description
taskId	Yes	Trace identifier
objective	Yes	Original objective
temporal	When temporal step runs	Statistics, trends, insights
pattern	When pattern step runs	Detected behavioral patterns
correlation	When correlation step runs	Cross-metric relationships
domain	When domain step runs	External knowledge retrieved
explanation	Always	Synthesized narrative and recommendations
validation	Always	Fact-check results
result	Always	Summary, key insights, confidence score
executedSteps	Yes	Which steps ran, skipped, or failed
timing	Yes	Execution duration

Error Codes

Code	Meaning
400	Invalid request body (missing objective, malformed data)
401	Invalid or expired bearer token
403	Subscription key rejected
422	Schema validation failed (invalid field types or values)
500	Internal server error