---
title: "Assistant capabilities API"
description: "Private session-backed routes for reading and updating assistant capabilities."
date: "2026-11-20"
modified: "2026-11-20"
reviewed: "2026-11-20"
---

# Assistant capabilities API

> Private session-backed routes for reading and updating assistant capabilities.

Published on: 2026-11-20

Last updated on: 2026-11-20

API documentation for managing assistant capability metadata programmatically.

## Overview

The Capabilities API provides endpoints to:

- Retrieve available capabilities
- Get assistant capability configuration
- Update assistant capabilities
- Query capability metadata

These routes are **private application routes**. They are intended for the signed-in product experience and are scoped to your organization.

## Base URL

Use your app domain, for example `https://app.achiral.ai/api`.

## Authentication

For the product UI, authentication is handled by the signed-in session.

If you call these routes directly, use the same authenticated session context the app uses. Do not treat them as a separate public token-based API.

---

## Endpoints

### Get Capability Registry

Retrieve the capability registry. The registry includes both executable and non-executable metadata entries. Execution requires a matching handler or action bridge in the application capability registry.

**Endpoint:** `GET /registry`

**Query Parameters:**

| Parameter       | Type   | Description                                                                  |
| --------------- | ------ | ---------------------------------------------------------------------------- |
| `assistantType` | string | Filter by assistant type, such as `organization_wide` or `employee_personal` |
| `category`      | string | Filter by category                                                           |

**Request Example:**

```bash
curl -X GET "https://app.achiral.ai/api/capabilities/registry?assistantType=employee_personal" \
  --cookie "your_session_cookie_here"
```

**Response:**

```json
{
  "success": true,
  "capabilities": [
    {
      "id": "access_org_analytics",
      "name": "Access Organization Analytics",
      "description": "Query org-wide metrics, KPIs, and dashboards",
      "category": "org_intelligence",
      "scope": "organization",
      "requiresConfig": true,
      "configFields": ["allowedMetrics", "dataRetention"],
      "tierRequirement": "seed",
      "alwaysEnabled": false
    },
    // ... more capabilities
  ],
  "grouped": {
    "organization": [...],
    "user": [...],
    "both": [...]
  },
  "total": 16
}
```

---

### Get assistant capabilities

Get the currently enabled capabilities for a specific assistant.

**Endpoint:** `GET /assistants/{assistantId}/capabilities`

**Path Parameters:**

| Parameter     | Type   | Description             |
| ------------- | ------ | ----------------------- |
| `assistantId` | string | The ID of the assistant |

**Request Example:**

```bash
curl -X GET "https://app.achiral.ai/api/assistants/507f1f77bcf86cd799439011/capabilities" \
  --cookie "your_session_cookie_here"
```

**Response:**

```json
{
  "success": true,
  "capabilities": ["send_emails", "manage_tasks", "analyze_documents"],
  "capabilityCount": 3,
  "capabilityConfigs": {
    "send_emails": {
      "emailProvider": "gmail",
      "requiresApproval": true
    },
    "manage_tasks": {},
    "analyze_documents": {}
  }
}
```

---

### Get Available Capabilities for Assistant

Retrieve capabilities available for a specific assistant, filtered by:

- Assistant type
- Organization tier
- Tier requirements

**Endpoint:** `GET /assistants/{assistantId}/available-capabilities`

**Path Parameters:**

| Parameter     | Type   | Description             |
| ------------- | ------ | ----------------------- |
| `assistantId` | string | The ID of the assistant |

**Request Example:**

```bash
curl -X GET "https://app.achiral.ai/api/assistants/507f1f77bcf86cd799439011/available-capabilities" \
  --cookie "your_session_cookie_here"
```

**Response:**

```json
{
  "success": true,
  "capabilities": [
    {
      "id": "request_shepherd_help",
      "name": "Raise support requests for Shepherd automatically",
      "description": "Files a support request to your Shepherd when you ask for help",
      "category": "support",
      "scope": "user",
      "requiresConfig": false,
      "optIn": true,
      "tierRequirement": "spark"
    },
    // ... more available capabilities
  ],
  "grouped": {
    "support": [...],
    "productivity": [...],
    "intelligence": [...]
  },
  "organizationTier": "seed",
  "currentCapabilities": ["send_emails", "manage_tasks"],
  "capabilityLimit": 7
}
```

`capabilityLimit` is `null` when the organization's plan has no limit.

`request_shepherd_help` is listed only for the assistant of an organization owner or admin, because only they can raise support requests. It is off until its owner turns it on.

---

### Update assistant capabilities

Enable or disable capabilities for an assistant.

**Endpoint:** `PATCH /assistants/{assistantId}/capabilities`

**Path Parameters:**

| Parameter     | Type   | Description             |
| ------------- | ------ | ----------------------- |
| `assistantId` | string | The ID of the assistant |

**Request Body:**

```json
{
  "capabilities": ["send_emails", "manage_tasks", "analyze_documents"],
  "capabilityConfigs": {
    "send_emails": {
      "emailProvider": "gmail",
      "requiresApproval": true
    }
  }
}
```

**Request Example:**

```bash
curl -X PATCH "https://app.achiral.ai/api/assistants/507f1f77bcf86cd799439011/capabilities" \
  --cookie "your_session_cookie_here" \
  -H "Content-Type: application/json" \
  -d '{
    "capabilities": ["send_emails", "manage_tasks"],
    "capabilityConfigs": {
      "send_emails": {
        "emailProvider": "gmail",
        "requiresApproval": true
      }
    }
  }'
```

**Response:**

```json
{
  "success": true,
  "assistant": {
    "_id": "507f1f77bcf86cd799439011",
    "name": "My Assistant",
    "type": "employee_personal",
    "capabilities": ["send_emails", "manage_tasks"],
    "capabilityConfigs": {
      "send_emails": {
        "emailProvider": "gmail",
        "requiresApproval": true
      }
    }
  },
  "message": "Capabilities updated successfully"
}
```

The current product also enforces assistant access checks and separate modify permission checks on capability updates.

Turning on `request_shepherd_help` for the assistant of a member who is not an organization owner or admin returns `403`.

---

## Error Handling

### Validation Errors

When validation fails, the response includes detailed error information:

```json
{
  "success": false,
  "error": "Validation failed",
  "validationErrors": [
    {
      "capabilityId": "manage_org_policies",
      "error": "Capability \"Manage Organization Policies\" (manage_org_policies) is only available for organization-level assistants (Chiro)"
    },
    {
      "error": "Organization tier \"spark\" allows maximum 3 capabilities, but 5 were provided"
    }
  ]
}
```

### Common Error Codes

| Code | Status       | Description                                           |
| ---- | ------------ | ----------------------------------------------------- |
| 400  | Bad Request  | Invalid request format or validation error            |
| 401  | Unauthorized | Missing or invalid authentication token               |
| 403  | Forbidden    | User doesn't have permission to modify this assistant |
| 404  | Not Found    | Assistant or capability not found                     |
| 500  | Server Error | Internal server error                                 |

### Example Error Response

```json
{
  "success": false,
  "error": "Failed to update assistant capabilities",
  "message": "Capability \"Schedule Meetings\" (schedule_meetings) requires Seed tier or higher"
}
```

---

## Validation Rules

### Capability Scope Validation

- **Organization-level capabilities** (scope: `organization`) can only be assigned to Chiro assistants (type: `org_shared`)
- **User-level capabilities** (scope: `user`) can only be assigned to Executive Assistants (type: `employee_personal`)
- **Shared capabilities** (scope: `both`) can be assigned to both types

### Tier Limits

Your organization tier determines the maximum capabilities you can enable.

| Tier            | Limit     | Always-Enabled Count                  |
| --------------- | --------- | ------------------------------------- |
| Free            | 3         | `answer_questions` is always enabled  |
| Spark           | 3         | `answer_questions` (1) = 2 additional |
| Seed            | 7         | `answer_questions` (1) = 6 additional |
| Rise            | 7         | Same configured limit as Seed         |
| Boost and above | Unlimited | No configured count limit             |

### Configuration Requirements

Capabilities that require configuration have a `requiresConfig: true` flag. When updating capabilities:

1. Include required config fields in `capabilityConfigs`
2. All fields specified in the capability's `configFields` must be provided
3. Missing required fields will cause validation to fail

---

## Code Examples

### JavaScript/Node.js

```javascript
const axios = require("axios");

const API_BASE = "https://app.achiral.ai/api";
const SESSION_COOKIE = "your_session_cookie_here";

const client = axios.create({
  baseURL: API_BASE,
  headers: {
    Cookie: SESSION_COOKIE,
    "Content-Type": "application/json",
  },
});

// Get capability registry
async function getCapabilities() {
  const response = await client.get("/capabilities/registry");
  return response.data.capabilities;
}

// Get assistant capabilities
async function getAssistantCapabilities(assistantId) {
  const response = await client.get(`/assistants/${assistantId}/capabilities`);
  return response.data;
}

// Update assistant capabilities
async function updateCapabilities(assistantId, capabilities, configs) {
  const response = await client.patch(
    `/assistants/${assistantId}/capabilities`,
    {
      capabilities,
      capabilityConfigs: configs,
    },
  );
  return response.data;
}

// Usage
(async () => {
  try {
    const caps = await getCapabilities();
    console.log("Available capabilities:", caps);

    const result = await updateCapabilities(
      "assistant_id_here",
      ["send_emails", "manage_tasks"],
      {
        send_emails: {
          emailProvider: "gmail",
          requiresApproval: true,
        },
      },
    );
    console.log("Updated:", result);
  } catch (error) {
    console.error("Error:", error.response.data);
  }
})();
```

### Python

```python
import requests

API_BASE = 'https://app.achiral.ai/api'
SESSION_COOKIE = 'your_session_cookie_here'

headers = {
    'Cookie': SESSION_COOKIE,
    'Content-Type': 'application/json'
}

def get_capabilities():
    """Retrieve all available capabilities"""
    response = requests.get(f'{API_BASE}/capabilities/registry', headers=headers)
    return response.json()

def get_assistant_capabilities(assistant_id):
    """Get capabilities for a specific assistant"""
    response = requests.get(
        f'{API_BASE}/assistants/{assistant_id}/capabilities',
        headers=headers
    )
    return response.json()

def update_capabilities(assistant_id, capabilities, configs):
    """Update assistant capabilities"""
    response = requests.patch(
        f'{API_BASE}/assistants/{assistant_id}/capabilities',
        headers=headers,
        json={
            'capabilities': capabilities,
            'capabilityConfigs': configs
        }
    )
    return response.json()

if __name__ == '__main__':
    try:
        caps = get_capabilities()
        print('Available capabilities:', caps['capabilities'])

        result = update_capabilities(
            'assistant_id_here',
            ['send_emails', 'manage_tasks'],
            {
                'send_emails': {
                    'emailProvider': 'gmail',
                    'requiresApproval': True
                }
            }
        )
        print('Updated:', result)
    except Exception as e:
        print('Error:', e)
```

---

## Rate Limiting

These routes are private application routes. Expect normal application-side limits, permission checks, and validation rather than a separate public API contract.

When rate limited, you'll receive a 429 status with retry information.

---

## Webhooks (Future)

Capability configuration changes can trigger webhooks. Webhook documentation coming soon.

---

## FAQ

**Q: Can I use the API from my frontend?**  
A: No, API tokens should only be used server-side. For frontend capability management, use the UI or proxy through your backend.

**Q: What happens if I update capabilities while the assistant is in a conversation?**  
A: The changes take effect for new messages. Existing conversation history is not affected.

**Q: Can I batch-update multiple assistants?**  
A: Currently, updates are per-assistant. For bulk operations, make multiple requests.

---

## Support

- **API Issues:** support@achiral.ai
- **Documentation:** https://achiral.ai/docs
- **Status Page:** https://status.achiral.ai
