API Reference
Classify Intent
Determine the intent of an inbound case so the orchestrator can route it.
Authorization
bearerAuth AuthorizationBearer <token>
OAuth2 client credentials flow. Token obtained from /oauth2/token on the auth host.
In: header
Header Parameters
X-Correlation-Id*string
Caller-supplied correlation ID. Propagated end-to-end and returned in responses and audit logs.
Idempotency-Key?string
Optional. If reused within 24 hours with the same payload, the cached response is returned. Reuse with a different payload yields 409.
Prefer?string
Set to 'respond-async' to receive a 202 Accepted with a job ID instead of a synchronous result.
Value in
"respond-async"Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://api.eu.faction.ai/v1/intent/classify" \ -H "X-Correlation-Id: 8f3c-b21" \ -H "Idempotency-Key: case-CRM-2026-04-29-00417-intent-v1" \ -H "Content-Type: application/json" \ -d '{ "case_id": "CRM-2026-04-29-00417", "sender": "buyer@acme-engineering.co.uk", "subject": "Urgent: bearings + drive belts needed by Friday", "body": "Hi, please can you quote for: 50 x SKF 6205-2RS bearings and 20 x Gates B-section drive belts (B72). Delivery to Birmingham depot by Friday. Thanks, Tom", "attachments": [], "country": "GB", "branch_id": "BR-UK-014" }'{
"intent": "quote",
"confidence_score": 0.97,
"rationale": "Explicit ask 'please can you quote for' + structured product list with quantities and delivery requirement.",
"secondary_intents": [
{
"intent": "rfq",
"confidence_score": 0.62
}
],
"recommended_action": "auto_accept"
}{
"job_id": "job_01JZP4XYZ123",
"status_url": "/v1/jobs/job_01JZP4XYZ123",
"status": "queued"
}{
"error_code": "MISSING_REQUIRED_FIELD",
"message": "Field 'case_id' is required.",
"correlation_id": "8f3c-b21",
"request_id": "req_01JZP4..."
}{
"error_code": "EXPIRED_TOKEN",
"message": "Bearer token expired at 2026-04-29T13:00:00Z.",
"correlation_id": "8f3c-b21",
"request_id": "req_01JZP4..."
}{
"error_code": "SCOPE_INSUFFICIENT",
"message": "Token lacks scope 'extract.quote'.",
"correlation_id": "8f3c-b21",
"request_id": "req_01JZP4..."
}{
"error_code": "IDEMPOTENCY_KEY_CONFLICT",
"message": "Idempotency key was previously used with a different request payload.",
"correlation_id": "8f3c-b22",
"request_id": "req_01JZP4..."
}{
"error_code": "RATE_LIMITED",
"message": "Per-tenant per-module rate limit exceeded.",
"correlation_id": "8f3c-b21",
"request_id": "req_01JZP4..."
}{
"error_code": "INTERNAL_ERROR",
"message": "An unexpected error occurred.",
"correlation_id": "8f3c-b21",
"request_id": "req_01JZP4..."
}Notes
- Multi-intent messages return the dominant intent in
intentand the secondary insecondary_intents. - Auto-replies / out-of-office messages return
intent: "other"plusauto_reply: true. - Unsupported languages return
intent: "other"pluslanguage_unsupported: true. Currently supported: English, French, German, Spanish, Italian, Dutch. - Default p50 latency target: under 600 ms. Payloads over 10 MB should use the async pattern.