Assistant Capabilities API Reference

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

All endpoints require authentication and are scoped to your organization.

Base URL

https://api.achiral.ai/api/capabilities

Authentication

Include your API token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

For Next.js/session-based auth, authentication is handled automatically.

---

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: org_shared or employee_personal (optional)
category	string	Filter by category (optional)

Request Example:

curl -X GET "https://api.achiral.ai/api/capabilities/registry?assistantType=org_shared" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response:

{
  "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:

curl -X GET "https://api.achiral.ai/api/assistants/507f1f77bcf86cd799439011/capabilities" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response:

{
  "success": true,
  "capabilities": [
    "create_orders",
    "manage_tasks",
    "analyze_documents"
  ],
  "capabilityCount": 3,
  "capabilityConfigs": {
    "create_orders": {
      "allowedOrderTypes": ["standard", "rush"],
      "maxOrdersPerDay": 10,
      "requiresApproval": true
    },
    "manage_tasks": {},
    "analyze_documents": {}
  }
}

---

Get Available Capabilities for Assistant

Retrieve capabilities available for a specific assistant, filtered by:

• Assistant type (org_shared vs employee_personal)
• Organization tier
• Tier requirements

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

Path Parameters:

Parameter	Type	Description
assistantId	string	The ID of the assistant

Request Example:

curl -X GET "https://api.achiral.ai/api/assistants/507f1f77bcf86cd799439011/available-capabilities" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response:

{
  "success": true,
  "capabilities": [
    {
      "id": "create_orders",
      "name": "Create Orders",
      "description": "Create orders on behalf of assigned user",
      "category": "commerce",
      "scope": "user",
      "requiresConfig": true,
      "tierRequirement": "spark"
    },
    // ... more available capabilities
  ],
  "grouped": {
    "commerce": [...],
    "productivity": [...],
    "intelligence": [...]
  },
  "organizationTier": "seed",
  "currentCapabilities": ["create_orders", "manage_tasks"],
  "capabilityLimit": 7
}

---

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:

{
  "capabilities": ["create_orders", "manage_tasks", "analyze_documents"],
  "capabilityConfigs": {
    "create_orders": {
      "allowedOrderTypes": ["standard", "rush"],
      "maxOrdersPerDay": 10,
      "requiresApproval": true
    }
  }
}

Request Example:

curl -X PATCH "https://api.achiral.ai/api/assistants/507f1f77bcf86cd799439011/capabilities" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "capabilities": ["create_orders", "manage_tasks"],
    "capabilityConfigs": {
      "create_orders": {
        "allowedOrderTypes": ["standard"],
        "maxOrdersPerDay": 5,
        "requiresApproval": true
      }
    }
  }'

Response:

{
  "success": true,
  "assistant": {
    "_id": "507f1f77bcf86cd799439011",
    "name": "My Assistant",
    "type": "employee_personal",
    "capabilities": ["create_orders", "manage_tasks"],
    "capabilityConfigs": {
      "create_orders": {
        "allowedOrderTypes": ["standard"],
        "maxOrdersPerDay": 5,
        "requiresApproval": true
      }
    }
  },
  "message": "Capabilities updated successfully"
}

---

Error Handling

Validation Errors

When validation fails, the response includes detailed error information:

{
  "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

{
  "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. Pricing plan IDs are normalized into the operational capability tiers used by the validator.

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

const axios = require('axios');

const API_BASE = 'https://api.achiral.ai/api';
const API_TOKEN = 'your_api_token_here';

const client = axios.create({
  baseURL: API_BASE,
  headers: {
    'Authorization': `Bearer ${API_TOKEN}`,
    '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',
      ['create_orders', 'manage_tasks'],
      {
        create_orders: {
          allowedOrderTypes: ['standard'],
          maxOrdersPerDay: 5,
          requiresApproval: true
        }
      }
    );
    console.log('Updated:', result);
  } catch (error) {
    console.error('Error:', error.response.data);
  }
})();

Python

import requests

API_BASE = 'https://api.achiral.ai/api'
API_TOKEN = 'your_api_token_here'

headers = {
    'Authorization': f'Bearer {API_TOKEN}',
    '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()

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

        result = update_capabilities(
            'assistant_id_here',
            ['create_orders', 'manage_tasks'],
            {
                'create_orders': {
                    'allowedOrderTypes': ['standard'],
                    'maxOrdersPerDay': 5,
                    'requiresApproval': True
                }
            }
        )
        print('Updated:', result)
    except Exception as e:
        print('Error:', e)

---

Rate Limiting

API requests are rate-limited per organization:

Tier	Requests/Minute
Spark	60
Seed	200
Rise	200
Boost and above	1000 or deployment-specific

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