Intent API

The Intent API is how you invoke LiyaEngine. Pass a domain, an intent key, and your input — get back a validated, structured response. No raw prompts, no system-message wrangling, no parsing free-text output.

Call an intent

POST https://api.liyaengine.ai/v1/run
Authorization: Bearer liya_prod_...
Content-Type: application/json

{
  "domain": "your-domain",
  "intent": "your-custom-intent",
  "input": { ... }
}

Every call made with an API key must include input.user_id: any string that identifies your end user, for example "user_001". Without it the call is refused with 400 INVALID_INPUT ("Missing required field: input.user_id"). The id ties the call to that user for session and usage tracking, so send a stable id from your own system. input.user.id also works. The same applies to POST /v1/run/stream and to the SDK run and stream methods, which pass input through unchanged.

An equivalent path-based form is also available: POST /v1/{domain}/{intent} with just { "input": {...} } in the body.

Response:

{
  "success": true,
  "data": {
    "output": { ... },
    "session_id": "ses_abc",
    "message_id": "msg_xyz"
  },
  "metadata": {
    "intent": "your-custom-intent",
    "domain": "your-domain",
    "model_used": "claude-sonnet-5",
    "tokens_used": 1240,
    "cost_usd": 0.00062,
    "latency_ms": 340,
    "cached": false
  }
}

What makes it different

Intent structure

An intent is a named, schema-bound AI action. It has:

• Input contract — what fields you must and may pass
• Output contract — what fields you always get back
• Tool set — functions the engine can invoke (see Agent Orchestration)
• Guardrail policies — safety and compliance checks applied (see Guardrails)

You define all of this once, when creating a custom domain — the engine enforces it on every call after that.

Related

What's next?

• Use Quickstart to make a real request.
• Use Custom Domain Walkthrough to create your own intent.
• Use Dashboard API when you need to manage domains, keys, sessions, and usage programmatically.