Skip to main content
A purpose 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 purpose or falls into the ambient cluster.

​
Endpoints

MethodPathDescription
GET/v1/purposesList all purposes for the org
POST/v1/purposesCreate a new purpose (status draft)
POST/v1/purposes/{id}/publishPromote a draft to active
Creating or publishing a purpose requires the policy_write or admin scope on the API key.

​
Purpose object

{
  "id": "purpose_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 purposes match traffic.

​
List purposes

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

​
Create a purpose

POST /v1/purposes
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 purpose object. Status defaults to draft.

​
Publish

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

​
Errors

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