Intentions

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

Method	Path	Description
`GET`	`/v1/intentions`	List all intentions for the org
`POST`	`/v1/intentions`	Create a new intention (status `draft`)
`POST`	`/v1/intentions/{id}/publish`	Promote 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.

Endpoints

Reference

Intent

Approvals

Webhooks

Intentions

Endpoints

Intention object

List intentions

Create an intention

Publish

Errors

Read next

​Endpoints

​Intention object

​List intentions

​Create an intention

​Publish

​Errors

​Read next

Endpoints

Intention object

List intentions

Create an intention

Publish

Errors

Read next