Assistant capabilities API

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:

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

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://app.achiral.ai/api/assistants/507f1f77bcf86cd799439011/capabilities" \
  --cookie "your_session_cookie_here"

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
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://app.achiral.ai/api/assistants/507f1f77bcf86cd799439011/available-capabilities" \
  --cookie "your_session_cookie_here"

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://app.achiral.ai/api/assistants/507f1f77bcf86cd799439011/capabilities" \
  --cookie "your_session_cookie_here" \
  -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"
}

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

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:

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

Code Examples

JavaScript/Node.js

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",
      ["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://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()

# 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

These routes are private application routes. Expect normal application-side limits, permission checks, and validation rather than a separate public API contract. | --------------- | --------------------------- | | Spark | 60 | | Seed | 200 | | Rise | 200 | | Boost and above | 1000 or contract-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