Skip to main content
An intention is a named pattern — “Customer Support Lookup”, “Pipeline Review” — with an intent class, optional approval requirement, an allowed data-element list, and a token TTL. Every intent evaluation either matches an active intention or falls into the ambient cluster.

​
Endpoints

MethodPathDescription
GET/v1/intentionsList all intentions for the org
POST/v1/intentionsCreate a new intention (status draft)
POST/v1/intentions/{id}/publishPromote a draft to active
Creating or publishing an intention requires the policy_write or admin scope on the API key.

​
Intention object

{
  "id": "intention_2pX9...",
  "label": "customer_support_lookup",
  "display_name": "Customer Support Lookup",
  "description": "Look up a customer's name + email when answering a support ticket.",
  "intent_class": "lookup",
  "status": "active",
  "approval_required": false,
  "ttl_minutes": 5,
  "data_elements": [
    { "data_source_id": "salesforce_prod", "path": "Account.Name" },
    { "data_source_id": "salesforce_prod", "path": "Contact.Email" }
  ],
  "created_at": "2026-04-20T10:00:00Z",
  "updated_at": "2026-04-21T14:30:00Z"
}
intent_class is one of reporting, export, admin, lookup, analysis, write, other. status is draft, active, or archived — only active intentions match traffic.

​
List intentions

GET /v1/intentions
Authorization: Bearer <INVIOLET_API_KEY>
Response: 
{
  "data": [
    { "id": "intention_2pX9...", "label": "customer_support_lookup", "...": "..." }
  ]
}

​
Create an intention

POST /v1/intentions
Authorization: Bearer <INVIOLET_API_KEY>
Content-Type: application/json

{
  "label": "customer_support_lookup",
  "display_name": "Customer Support Lookup",
  "intent_class": "lookup",
  "approval_required": false,
  "ttl_minutes": 5,
  "data_elements": [
    { "data_source_id": "salesforce_prod", "path": "Account.Name" },
    { "data_source_id": "salesforce_prod", "path": "Contact.Email" }
  ]
}
Returns 201 Created with the new intention object. Status defaults to draft.

​
Publish

POST /v1/intentions/{id}/publish
Authorization: Bearer <INVIOLET_API_KEY>
Promotes a draft to active. The next matching tool call is decided against the intention immediately.

​
Errors

403 if the API key lacks policy_write. 409 if a label collides with an existing intention.