API Reference

Alius Agent Team provides a complete REST API that supports programmatic interaction with the system. This document details all API endpoints, request parameters, and response formats.

API Overview

Basic Information

  • Base URL: https://api.alius.ai/v1
  • API Version: v1
  • Protocol: HTTPS only
  • Data Format: JSON
  • Character Encoding: UTF-8

Authentication Methods

API supports the following authentication methods:

Bearer Token

Add Authorization field in request header:

Authorization: Bearer YOUR_API_TOKEN

API Key

Add X-API-Key field in request header:

X-API-Key: YOUR_API_KEY

Rate Limiting

API implements rate limiting to ensure system stability:

  • Default Limit: 60 requests per minute
  • Batch Operations: 10 requests per minute
  • Response headers include rate limit information:
    • X-RateLimit-Limit: Rate limit
    • X-RateLimit-Remaining: Remaining request count
    • X-RateLimit-Reset: Rate limit reset time

Error Handling

API uses standard HTTP status codes to indicate request results:

Success Status Codes

  • 200 OK: Request successful
  • 201 Created: Resource created successfully
  • 202 Accepted: Request accepted, being processed
  • 204 No Content: Request successful, no content returned

Client Error Status Codes

  • 400 Bad Request: Request parameter error
  • 401 Unauthorized: Not authenticated
  • 403 Forbidden: No permission
  • 404 Not Found: Resource doesn’t exist
  • 409 Conflict: Resource conflict
  • 422 Unprocessable Entity: Request format correct but semantic error
  • 429 Too Many Requests: Too many requests

Server Error Status Codes

  • 500 Internal Server Error: Server internal error
  • 502 Bad Gateway: Gateway error
  • 503 Service Unavailable: Service unavailable
  • 504 Gateway Timeout: Gateway timeout

Error Response Format

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Request parameter error",
    "details": {
      "field": "email",
      "issue": "Invalid email format"
    }
  }
}

Authentication API

SMS Login

Endpoint: POST /auth/login/sms

Description: Login using SMS verification code

Request Body:

{
  "phone": "+8613800138000",
  "code": "123456"
}

Response:

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 3600,
    "user": {
      "id": "user_12345",
      "username": "example_user",
      "email": "user@example.com"
    }
  }
}

Send SMS Verification Code

Endpoint: POST /auth/sms/send

Description: Send SMS verification code

Request Body:

{
  "phone": "+8613800138000"
}

Response:

{
  "success": true,
  "data": {
    "expiresIn": 300,
    "requestId": "req_12345"
  }
}

Apple Login

Endpoint: POST /auth/login/apple

Description: Login using Apple ID

Request Body:

{
  "identityToken": "apple_identity_token",
  "authorizationCode": "apple_auth_code",
  "user": {
    "email": "user@example.com",
    "name": "Example User"
  }
}

WeChat Login

Endpoint: POST /auth/login/wechat

Description: Login using WeChat

Request Body:

{
  "code": "wechat_auth_code"
}

Refresh Token

Endpoint: POST /auth/refresh

Description: Use refresh token to get new access token

Request Body:

{
  "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Logout

Endpoint: POST /auth/logout

Description: Logout, invalidate token

Request Body:

{
  "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Agent API

List Agents

Endpoint: GET /agents

Description: Get Agent list

Query Parameters:

ParameterTypeRequiredDescription
pagenumberNoPage number, default 1
limitnumberNoItems per page, default 20, max 100
statusstringNoFilter by status
typestringNoFilter by type
teamIdstringNoFilter by team
searchstringNoSearch keyword

Response:

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "agent_12345",
        "name": "My Code Assistant",
        "description": "Agent specialized for code generation and review",
        "type": "codegen",
        "status": "active",
        "health": {
          "score": 95,
          "lastCheck": "2024-01-15T10:00:00Z"
        },
        "config": {
          "model": "gpt-4",
          "temperature": 0.2,
          "maxTokens": 4096
        },
        "createdAt": "2024-01-01T00:00:00Z",
        "updatedAt": "2024-01-15T10:00:00Z",
        "ownerId": "user_12345",
        "teamId": "team_12345"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 45,
      "totalPages": 3
    }
  }
}

Create Agent

Endpoint: POST /agents

Description: Create new Agent

Request Body:

{
  "name": "My Code Assistant",
  "description": "Agent specialized for code generation and review",
  "type": "codegen",
  "config": {
    "model": "gpt-4",
    "temperature": 0.2,
    "maxTokens": 4096
  },
  "teamId": "team_12345"
}

Response:

{
  "success": true,
  "data": {
    "id": "agent_12345",
    "name": "My Code Assistant",
    "status": "inactive",
    "createdAt": "2024-01-15T10:00:00Z"
  }
}

Get Agent Details

Endpoint: GET /agents/:id

Description: Get detailed information of specified Agent

Path Parameters:

ParameterTypeRequiredDescription
idstringYesAgent ID

Response: Same as single Agent object in List Agents

Update Agent

Endpoint: PUT /agents/:id

Description: Update Agent information

Path Parameters:

ParameterTypeRequiredDescription
idstringYesAgent ID

Request Body:

{
  "name": "Updated Agent Name",
  "description": "Updated description",
  "config": {
    "temperature": 0.3
  }
}

Delete Agent

Endpoint: DELETE /agents/:id

Description: Delete Agent

Path Parameters:

ParameterTypeRequiredDescription
idstringYesAgent ID

Start Agent

Endpoint: POST /agents/:id/actions/start

Description: Start Agent

Path Parameters:

ParameterTypeRequiredDescription
idstringYesAgent ID

Stop Agent

Endpoint: POST /agents/:id/actions/stop

Description: Stop Agent

Restart Agent

Endpoint: POST /agents/:id/actions/restart

Description: Restart Agent

Get Agent Logs

Endpoint: GET /agents/:id/logs

Description: Get Agent execution logs

Query Parameters:

ParameterTypeRequiredDescription
levelstringNoLog level filter
startTimestringNoStart time
endTimestringNoEnd time
limitnumberNoReturn count, default 100
offsetnumberNoOffset, default 0

Task API

List Tasks

Endpoint: GET /tasks

Description: Get task list

Query Parameters:

ParameterTypeRequiredDescription
pagenumberNoPage number
limitnumberNoItems per page
statusstringNoFilter by status
agentIdstringNoFilter by Agent
prioritystringNoFilter by priority
assigneeIdstringNoFilter by assignee

Create Task

Endpoint: POST /tasks

Description: Create new task

Request Body:

{
  "title": "Code Review",
  "description": "Review the code quality of the following Pull Request",
  "agentId": "agent_12345",
  "priority": "high",
  "deadline": "2024-01-20T17:00:00Z",
  "attachments": [
    {
      "type": "url",
      "url": "https://github.com/example/repo/pull/123"
    }
  ]
}

Get Task Details

Endpoint: GET /tasks/:id

Description: Get detailed information of specified task

Update Task

Endpoint: PUT /tasks/:id

Description: Update task information

Delete Task

Endpoint: DELETE /tasks/:id

Description: Delete task

Cancel Task

Endpoint: POST /tasks/:id/actions/cancel

Description: Cancel task

Retry Task

Endpoint: POST /tasks/:id/actions/retry

Description: Retry failed task

Get Task Result

Endpoint: GET /tasks/:id/result

Description: Get task execution result

Team API

List Teams

Endpoint: GET /teams

Description: Get list of teams the user belongs to

Create Team

Endpoint: POST /teams

Description: Create new team

Request Body:

{
  "name": "My Team",
  "description": "This is my team",
  "visibility": "private"
}

Get Team Details

Endpoint: GET /teams/:id

Description: Get detailed information of specified team

Update Team

Endpoint: PUT /teams/:id

Description: Update team information

Delete Team

Endpoint: DELETE /teams/:id

Description: Delete team

Invite Member

Endpoint: POST /teams/:id/members/invite

Description: Invite user to join team

Request Body:

{
  "email": "user@example.com",
  "role": "member"
}

Remove Member

Endpoint: DELETE /teams/:id/members/:userId

Description: Remove team member

Update Member Role

Endpoint: PUT /teams/:id/members/:userId/role

Description: Update team member role

Request Body:

{
  "role": "admin"
}

User API

Get Current User Info

Endpoint: GET /users/me

Description: Get current authenticated user’s information

Update User Info

Endpoint: PUT /users/me

Description: Update current user information

Get User List (Team)

Endpoint: GET /teams/:teamId/users

Description: Get team member list (requires team admin permission)

Notification API

List Notifications

Endpoint: GET /notifications

Description: Get notification list

Query Parameters:

ParameterTypeRequiredDescription
pagenumberNoPage number
limitnumberNoItems per page
readbooleanNoFilter by read status
typestringNoFilter by type

Mark Notification as Read

Endpoint: PUT /notifications/:id/read

Description: Mark specified notification as read

Mark All Notifications as Read

Endpoint: PUT /notifications/read-all

Description: Mark all notifications as read

Delete Notification

Endpoint: DELETE /notifications/:id

Description: Delete specified notification

Session API

List Sessions

Endpoint: GET /sessions

Description: Get session list

Get Session Details

Endpoint: GET /sessions/:id

Description: Get detailed information of specified session

Close Session

Endpoint: POST /sessions/:id/actions/close

Description: Close specified session

Webhook

Webhook Events

Alius Agent Team supports Webhooks, which can send HTTP POST requests to a URL you specify when specific events occur.

Supported Event Types

  • agent.created: Agent created
  • agent.updated: Agent updated
  • agent.deleted: Agent deleted
  • agent.status_changed: Agent status changed
  • task.created: Task created
  • task.updated: Task updated
  • task.completed: Task completed
  • task.failed: Task failed
  • team.member_joined: Member joined team
  • team.member_left: Member left team

Webhook Payload Example

{
  "event": "task.completed",
  "data": {
    "taskId": "task_12345",
    "agentId": "agent_12345",
    "status": "completed",
    "result": {
      "output": "Task execution result..."
    }
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "signature": "webhook_signature"
}

Configure Webhook

Endpoint: POST /webhooks

Description: Create Webhook configuration

Request Body:

{
  "url": "https://your-server.com/webhook",
  "events": ["task.completed", "agent.status_changed"],
  "secret": "your_webhook_secret"
}

SDK and Examples

Official SDKs

Alius Agent Team provides the following official SDKs:

  • JavaScript/TypeScript: @alius/agent-team-sdk
  • Python: alius-agent-team-sdk
  • Go: github.com/alius/agent-team-sdk-go
  • Java: com.alius.agent-team-sdk

JavaScript SDK Example

Installation

npm install @alius/agent-team-sdk

Usage Example

import { AliusClient } from '@alius/agent-team-sdk';

// Initialize client
const client = new AliusClient({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.alius.ai/v1'
});

// List Agents
const agents = await client.agents.list({
  status: 'active',
  limit: 10
});

console.log(agents);

// Create task
const task = await client.tasks.create({
  title: 'Code Review',
  description: 'Review PR #123',
  agentId: 'agent_12345',
  priority: 'high'
});

console.log(task);

// Listen to Webhook events
client.webhooks.on('task.completed', (data) => {
  console.log('Task completed:', data);
});

Python SDK Example

Installation

pip install alius-agent-team-sdk

Usage Example

from alius_agent_team import AliusClient

# Initialize client
client = AliusClient(api_key="YOUR_API_KEY")

# List Agents
agents = client.agents.list(status="active", limit=10)
print(agents)

# Create task
task = client.tasks.create(
    title="Code Review",
    description="Review PR #123",
    agent_id="agent_12345",
    priority="high"
)
print(task)

# Get task result
result = client.tasks.get_result(task.id)
print(result)

Best Practices

API Call Optimization

  • Use Pagination: For requests with large amounts of data, use pagination to avoid timeouts
  • Batch Operations: Use batch APIs to reduce number of requests
  • Cache Responses: Cache data that doesn’t change frequently
  • Use Webhooks: For scenarios with high real-time requirements, use Webhooks instead of polling

Error Handling

  • Implement Retry Logic: For recoverable errors (e.g., 429, 503), implement exponential backoff retry
  • Log Errors: Log all API errors for troubleshooting
  • User-Friendly Prompts: Display user-friendly error messages

Security

  • Protect API Keys: Don’t hardcode API keys in frontend code
  • Use Least Privilege: Only request necessary permissions
  • Verify Webhook Signatures: Verify Webhook request signatures to ensure trusted source

Changelog

v1.0.0 (2024-01-01)

  • Initial API version release
  • Support basic Agent, Task, Team management
  • Support SMS, Apple, WeChat login

v1.1.0 (2024-02-15)

  • New Session API
  • New Webhook support
  • Improved error handling

v1.2.0 (2024-03-30)

  • New batch operation API
  • New advanced search features
  • Performance optimization

Summary

Alius Agent Team API provides complete programmatic access capabilities, supporting various integration and automation scenarios. If you have any API-related questions or suggestions, please contact our technical support team.

For detailed error code list, more advanced usage examples, and latest API updates, please visit our developer portal: https://developers.alius.ai