Intellia API Documentation

Overview

Intellia provides a comprehensive REST API for managing agents, conversations, knowledge bases, integrations, and more. Authentication is handled via API keys or JWT tokens.

Authentication

API Key Authentication

API keys are the recommended way to authenticate programmatic access to the Intellia API. They can be created in the Organization > API Keys section.

Creating an API Key

1. Navigate to Organization > API Keys in the UI
2. Click Create API Key
3. Provide a Description (required) - e.g., “Production Integration”
4. Select Permissions (required) - Define what this API key can access
5. The system will generate an API key (shown only once)

Permissions Model

When creating an API key, you can grant permissions to specific resources. The permission structure follows this pattern:

{
  "resource_name": {
    "read": boolean,
    "write": boolean
  }
}

Available permission scopes include:

• agents - Read/Write agent configurations
• conversations - Read/Write conversations
• knowledge_bases - Read/Write knowledge bases
• tools - Read/Write tool attachments
• integrations - Read/Write integrations
• prompts - Read/Write prompts
• assume_role - Generate assume-role tokens
• webhooks - Manage webhooks

Using API Keys in Requests

Include the API key in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.intellia.com.au/orgs/{organizationId}/agents

API Key Features

Endpoints for Managing API Keys

• Create API Key POST /orgs/{organizationId}/api-keys

  • Required Role: Admin or Owner
  • Request Body:

    {
      "description": "string",
      "permissions": {
        "agents": { "read": true, "write": true },
        "conversations": { "read": true, "write": false }
      }
    }
  • Response: Returns the OrganizationAccessKey object with the generated key

• List API Keys GET /orgs/{organizationId}/api-keys

  • Required Role: Admin or Owner
  • Query Parameters:
    • limit (optional): Number of results per page (default: 20)
    • cursor (optional): Pagination cursor
  • Response: Returns a paginated list of API keys

• Get API Key Details GET /orgs/{organizationId}/api-keys/{tokenId}

  • Required Role: Admin or Owner
  • Response: Returns a single OrganizationAccessKey object

• Update API Key PUT /orgs/{organizationId}/api-keys/{tokenId}

  • Required Role: Admin or Owner
  • Allows updating permissions or description

• Delete API Key DELETE /orgs/{organizationId}/api-keys/{tokenId}

  • Required Role: Admin or Owner
  • Permanently revokes the API key

API Key Limitations

The following operations cannot be performed with API keys (these require user authentication):

• Creating, listing, or managing API keys themselves
• User management and role assignments
• Organization member management
• Billing and subscription operations
• Assume-role token generation (unless specifically permitted)

Note: The noAPIKey: true flag on an endpoint means API key authentication is blocked for that endpoint.

Base URL

https://api.intellia.com.au

All requests must include:

• Authorization header with Bearer token or API key
• Content-Type: application/json for POST/PUT requests

API Endpoints

Agents

Manage AI agents and their attachments.

Agent Management

Agent Attachments

Conversations

Manage conversations, messages, and task plans.

Data Analysis

Browser Sessions

Action Chains

Manage action chains (workflows) and their steps.

Chain Steps

Chain Step Attachments

Knowledge Bases

Manage knowledge bases and documents.

Knowledge Base Files

Knowledge Base ETL

SharePoint Integration

Prompts

Manage system prompts for agents.

Integrations & Webhooks

Manage third-party integrations and webhooks.

Integrations

Webhooks

Webhook Handlers

Slack Integration

ETL Pipelines

Manage data ETL pipelines.

Pipeline Files

Transformations

Manage file transformations.

Transformation Files

Tables

Manage custom data tables.

Table Data

Vault

Manage secure vault items.

SMS

Send and manage SMS messages.

TOTP (Two-Factor Authentication)

Manage TOTP/2FA setup.

Schedules

Manage scheduled tasks and handlers.

Schedule Handlers

Forms

Manage forms and form templates.

Authentication

Handle SSO and authentication flows.

Browser Sessions

Manage browser automation sessions.

Organization & User Management

Manage organization settings, users, and roles.

Organization

Users & Roles

User Groups

Billing

Assume Role

Admin Endpoints

Administrative operations (typically restricted to super-admins).

BuddyBee (Third-party) Endpoints

Endpoints for BuddyBee and Vicforms integrations.

Error Handling

The API returns standard HTTP status codes:

Error responses follow this format:

{
  "message": "Error description"
}

Rate Limiting

The API rate limit is based on your token credits usage. Contact support for rate limit details specific to your organization.

Pagination

Endpoints that return lists support pagination via query parameters:

• limit - Number of results per page (default: 20, max: 100)
• cursor - Pagination cursor for retrieving next page

Example:

GET /orgs/{organizationId}/conversations?limit=50&cursor=0

Response includes pagination metadata:

{
  "items": [...],
  "nextToken": 50,
  "limit": 50
}

Webhooks

Webhooks allow you to receive real-time notifications for certain events. Set up webhooks in the Integrations section.

Supported Events

• conversation.created
• conversation.updated
• conversation.deleted
• message.created
• agent.executed

Webhook Payload

{
  "event": "event-type",
  "timestamp": "2024-01-01T00:00:00Z",
  "organizationId": "org-id",
  "data": {
    // Event-specific data
  }
}

Best Practices

1. API Key Security

   • Never commit API keys to version control
   • Rotate API keys periodically
   • Use environment variables to store keys
   • Create separate keys for different environments (dev, staging, prod)

2. Error Handling

   • Always check HTTP status codes
   • Implement exponential backoff for rate limiting
   • Log errors for debugging

3. Performance

   • Use pagination for list endpoints
   • Cache responses where appropriate
   • Batch requests when possible

4. Permissions

   • Grant only necessary permissions to API keys
   • Review API key usage regularly
   • Delete unused API keys

Support

For API support, contact: support@intellia.com.au

Additional resources:

• SDK Documentation
• Code Examples
• Troubleshooting Guide

Last Updated: November 2024