Core CRUD

Basic assistant creation, retrieval, update, and deletion operations.

GET /api/assistants

Search and filter assistants with pagination.

Authentication: Required (AI seat)

Pre-blocks: ai.verify

Response:

The response is a paginated HAL collection. Assistant items are returned under _embedded["inf:assistant"], each optionally including associated skills.

{
  "_links": {
    "self": { "href": "/api/assistants" },
    "next": { "href": "/api/assistants?start=30&limit=30" }
  },
  "_embedded": {
    "inf:assistant": [
      {
        "_links": {
          "self": { "href": "/api/assistants/d4f8a2b1-..." },
          "inf:assistant-skills": { "href": "/api/assistants/analytics:sales-assistant/skills" },
          "inf:assistant-datasets": { "href": "/api/assistants/analytics:sales-assistant/datasets" }
        },
        "id": "d4f8a2b1-...",
        "slug": "sales-assistant",
        "name": "Sales Assistant",
        "description": "Helps with sales data analysis",
        "instructions": "You are a helpful sales analyst...",
        "welcome": "Hello! How can I help with sales today?",
        "dispatcher": false,
        "suggestions": [
          "Show me this month's top deals",
          "Analyze quarterly trends"
        ],
        "modelId": "model-uuid-...",
        "token": null,
        "shared": true,
        "embedded": false,
        "data": {},
        "ownerId": "analytics",
        "folderId": null,
        "skills": [
          {
            "id": "skill-uuid-...",
            "type": "dataset-query",
            "name": "Query Sales Data"
          }
        ],
        "createdAt": "2024-01-15T10:00:00.000Z",
        "updatedAt": "2024-02-08T14:30:00.000Z"
      }
    ]
  },
  "start": 0,
  "count": 1,
  "total": 12
}

Filtering:

Only returns assistants where editingId is null (published assistants, not drafts)
Includes associated skills

GET /api/assistants-list

Get a complete list of all accessible assistants with tags and sharing info.

Authentication: Required (AI seat)

Pre-blocks:

ai.verify
Tag collection
Sharing collection

Response:

[
  {
    "id": "team:sales-assistant",
    "name": "Sales Assistant",
    "description": "Helps with sales data analysis",
    "tags": ["tag-123", "tag-456"],
    "sharing": [
      {
        "principalId": "team:marketing",
        "accessLevel": 2
      }
    ],
    "skills": [...],
    "createdAt": "2024-01-15T10:00:00Z"
  }
]

Use Cases:

Building assistant picker UIs
Dashboard overviews
Permission auditing

GET /api/assistants/{id}

Get a single assistant with full details including associated chat.

Authentication: Required (AI seat)

Pre-blocks:

ai.verify
Assistant lookup
Chat lookup (finds chat owned by this assistant for current user)

Path Parameters:

Parameter	Type	Description
`id`	string	Assistant ID (natural ID or compound key)

Response:

{
  "id": "team:sales-assistant",
  "name": "Sales Assistant",
  "description": "Helps with sales data analysis",
  "instructions": "You are a helpful sales analyst with access to our CRM data...",
  "welcome": "Hello! I can help you analyze sales data, track deals, and forecast revenue.",
  "dispatcher": false,
  "suggestions": [
    "Show me this month's top deals",
    "What's our win rate?",
    "Forecast next quarter"
  ],
  "modelId": "claude-opus-4",
  "model": {
    "id": "claude-opus-4",
    "name": "Claude Opus 4",
    "tier": "strategic"
  },
  "token": null,
  "icon": "briefcase",
  "shared": true,
  "data": {
    "customField": "value"
  },
  "chatId": "chat-123",
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-02-08T14:30:00Z",
  "_links": {
    "self": { "href": "/api/assistants/team:sales-assistant" },
    "inf:skills": { "href": "/api/assistants/team:sales-assistant/skills" },
    "inf:datasets": { "href": "/api/assistants/team:sales-assistant/datasets" },
    "inf:secrets": { "href": "/api/assistants/team:sales-assistant/secrets" }
  }
}

Chat Association:

If a chat exists where ownerAssistantId matches this assistant and username matches the current user, the chatId is included in the response.

POST /api/assistants

Create a new assistant.

Authentication: Required (AI seat)

Permission: assistants:create

Pre-blocks:

ai.verify
permission.assistants.create

Request Body:

Field	Type	Required	Description
`name`	string	Yes	Assistant display name
`description`	string	No	Assistant description
`instructions`	string	No	System instructions for the assistant
`welcome`	string	No	Welcome message shown to users
`dispatcher`	boolean	No	Whether this is a dispatcher assistant (default: false)
`suggestions`	array	No	Array of suggested prompts
`model`	string	No	Preferred model ID
`token`	string	No	API token for external access
`data`	object	No	Custom metadata
`icon`	string	No	Icon identifier
`shared`	boolean	No	Whether assistant is team-shared (default: false)

Example Request:

{
  "name": "Marketing Assistant",
  "description": "Helps with marketing campaign analysis",
  "instructions": "You are an expert marketing analyst...",
  "welcome": "Hi! I can help analyze marketing campaigns.",
  "suggestions": [
    "Show campaign performance",
    "Analyze email open rates"
  ],
  "model": "claude-sonnet-4",
  "icon": "megaphone",
  "shared": true
}

Response:

{
  "id": "team:marketing-assistant",
  "name": "Marketing Assistant",
  "description": "Helps with marketing campaign analysis",
  "instructions": "You are an expert marketing analyst...",
  "welcome": "Hi! I can help analyze marketing campaigns.",
  "dispatcher": false,
  "suggestions": [
    "Show campaign performance",
    "Analyze email open rates"
  ],
  "modelId": "claude-sonnet-4",
  "token": null,
  "icon": "megaphone",
  "shared": true,
  "data": {},
  "createdAt": "2024-02-09T10:00:00Z",
  "updatedAt": "2024-02-09T10:00:00Z",
  "_links": {
    "self": { "href": "/api/assistants/team:marketing-assistant" }
  }
}

Status: 201 Created

Transaction: Yes

PUT /api/assistants/{id}

Update an assistant.

Authentication: Required (AI seat)

Permission: assistant:write

Pre-blocks:

ai.verify
Assistant lookup
Model lookup (if modelId provided)
permission.assistant.write(pre.assistant)

Path Parameters:

Parameter	Type	Description
`id`	string	Assistant ID

Request Body:

Field	Type	Description
`name`	string	Update assistant name
`description`	string	Update description (null allowed)
`instructions`	string	Update system instructions (null allowed)
`modelId`	string	Change preferred model (null allowed)
`token`	string	Update API token (null allowed)
`dispatcher`	boolean	Toggle dispatcher mode
`suggestions`	array	Update suggested prompts (null allowed)
`welcome`	string	Update welcome message (null allowed)
`data`	object	Update custom metadata (null allowed)
`icon`	string	Update icon (null allowed)
`shared`	boolean	Toggle team sharing

Example Request:

{
  "name": "Updated Marketing Assistant",
  "instructions": "Enhanced instructions...",
  "suggestions": [
    "New suggestion 1",
    "New suggestion 2"
  ]
}

Response:

Returns the updated assistant object.

Transaction: Yes

DELETE /api/assistants/{id}

Delete an assistant permanently.

Authentication: Required (AI seat)

Permission: assistant:delete

Pre-blocks:

ai.verify
Assistant lookup
permission.assistant.delete(pre.assistant)

Path Parameters:

Parameter	Type	Description
`id`	string	Assistant ID

Response:

204 No Content

Transaction: Yes

Permanent Deletion

This operation permanently deletes the assistant and all associated skills, datasets, secrets, files, and references. This cannot be undone.

GET /api/assistant-skill-templates

Get available skill templates for creating new skills.

Authentication: Required (AI seat)

Response:

{
  "_links": {
    "self": { "href": "/api/assistant-skill-templates" }
  },
  "_embedded": {
    "inf:skill-template": [
      {
        "id": "dataset-query",
        "name": "Query Dataset",
        "description": "Search and analyze dataset records",
        "fields": [...]
      },
      {
        "id": "web-search",
        "name": "Web Search",
        "description": "Search the internet",
        "fields": [...]
      }
    ]
  },
  "start": 0,
  "count": 2,
  "total": 2
}

GET /api/assistants/{id}/usage

Get usage statistics for an assistant.

Authentication: Required (AI seat)

Pre-blocks:

ai.verify
Assistant lookup

Path Parameters:

Parameter	Type	Description
`id`	string	Assistant ID

Response:

{
  "totalMessages": 1250,
  "totalChats": 45,
  "totalCost": 12.45,
  "activeUsers": 8,
  "lastUsed": "2024-02-09T09:30:00Z"
}

Use Cases:

Monitor assistant adoption
Track costs
Identify popular assistants

GET /api/assistants​

GET /api/assistants-list​

GET /api/assistants/{id}​

POST /api/assistants​

PUT /api/assistants/{id}​

DELETE /api/assistants/{id}​

GET /api/assistant-skill-templates​

GET /api/assistants/{id}/usage​

GET /api/assistants

GET /api/assistants-list

GET /api/assistants/{id}

POST /api/assistants

PUT /api/assistants/{id}

DELETE /api/assistants/{id}

GET /api/assistant-skill-templates

GET /api/assistants/{id}/usage