Skip to main content

GeniSpace API Overview

GeniSpace provides a powerful REST API that enables developers to easily integrate GeniSpace's intelligent workflow and automation capabilities into their own applications and systems. Our API primarily supports the following core functional modules:

Core Functional Modules​

1. Agent API​

Agents are the core component of GeniSpace, offering the following capabilities:

  • Agent Management: Create, configure, update, and delete agents
  • Agent Execution: Invoke agents via the API to get intelligent responses
  • Agent Monitoring: View execution logs, performance metrics, and usage statistics
  • Agent Configuration: Set model parameters, prompt templates, knowledge base integrations, etc.

2. Task API​

The task system supports the execution and management of complex workflows:

  • Task Definition: Create and configure task templates
  • Task Execution: Start, monitor, and cancel task executions
  • Task Status: Query task execution status and results
  • Task Input/Output: Handle various types of input and output data

3. Dataset API​

The dataset management API provides the following capabilities:

  • Data Management: Create, update, and delete datasets
  • Data Querying: Support vector search and filtered queries
  • Data Import/Export: Batch data processing
  • Data Statistics: Retrieve dataset statistics

4. API Key Management​

  • Key Management: Create, update, and delete API keys
  • Permission Control: Set access permissions and scope for keys
  • Usage Statistics: View key usage information

Authentication & Security​

API Key Authentication​

All API requests require authentication. GeniSpace uses an API key-based authentication mechanism:

  1. In the GeniSpace console, navigate to "Settings" > "API Keys"
  2. Click "Create API Key"
  3. Set the key name, permissions, and validity period
  4. After generating the key, store it securely—it is only displayed once

Include the key in API requests as follows:

curl -X GET "https://api.genispace.cn/v1/agents" \
  -H "Authorization: Bearer YOUR_API_KEY"

Security Best Practices​

To protect your API keys and data, follow these best practices:

  • Never expose API keys in client-side code
  • Use different API keys for different applications and services
  • Rotate API keys regularly
  • Apply the principle of least privilege, granting only necessary permissions
  • Always use HTTPS in production environments

Core API Endpoints​

Agent API​

GET    /v1/agents                   # List agents
POST   /v1/agents                   # Create a new agent
GET    /v1/agents/{id}              # Get agent details
PUT    /v1/agents/{id}              # Update an agent
DELETE /v1/agents/{id}              # Delete an agent
POST   /v1/agents/{id}/chat         # OpenAI-compatible Chat API
POST   /v1/agents/{id}/execute      # Agent Execution Protocol API
POST   /v1/agents/{id}/invoke       # Invoke an agent (deprecated)
GET    /v1/agents/{id}/logs         # Get agent execution logs

Task API​

GET    /v1/tasks                    # List tasks
POST   /v1/tasks                    # Create a new task
GET    /v1/tasks/{id}               # Get task details
PUT    /v1/tasks/{id}               # Update a task
DELETE /v1/tasks/{id}               # Delete a task
POST   /v1/tasks/{id}/run           # Execute a task
GET    /v1/tasks/{id}/runs          # Get task execution history

Dataset API​

GET    /v1/datasets                 # List datasets
POST   /v1/datasets                 # Create a new dataset
GET    /v1/datasets/{id}            # Get dataset details
PUT    /v1/datasets/{id}            # Update a dataset
DELETE /v1/datasets/{id}            # Delete a dataset
POST   /v1/datasets/{id}/query      # Query a dataset
POST   /v1/datasets/{id}/import     # Import data
GET    /v1/datasets/{id}/export     # Export data

API Key API​

GET    /v1/api-keys                 # List API keys
POST   /v1/api-keys                 # Create a new API key
GET    /v1/api-keys/{id}            # Get API key details
PUT    /v1/api-keys/{id}            # Update an API key
DELETE /v1/api-keys/{id}            # Delete an API key
GET    /v1/api-keys/{id}/usage      # Get API key usage statistics

Request and Response Format​

The GeniSpace API uses JSON format for data exchange. All requests should include the appropriate Content-Type header:

Content-Type: application/json

Successful responses return an HTTP 2xx status code with a JSON response body. For example:

{
  "id": "agt_123456",
  "name": "Smart Customer Service Assistant",
  "description": "A professional customer service AI assistant",
  "created_at": "2024-03-01T10:00:00Z",
  "updated_at": "2024-03-15T14:30:00Z",
  "status": "active"
}

Error Handling​

When an API request fails, GeniSpace returns an appropriate HTTP status code along with detailed error information:

{
  "error": {
    "code": "invalid_parameter",
    "message": "Invalid parameter",
    "details": {
      "field": "name",
      "reason": "required"
    }
  }
}

Common HTTP status codes:

  • 400 Bad Request: Malformed request or invalid parameters
  • 401 Unauthorized: Authentication failed or invalid API key
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Requested resource does not exist
  • 429 Too Many Requests: API request limit exceeded
  • 500 Internal Server Error: Internal server error

Rate Limiting​

The GeniSpace API enforces rate limiting to ensure service reliability. Limits are based on the API key, with different account plans having different limits.

API responses include the following headers:

X-RateLimit-Limit: 100      # Maximum requests allowed per hour
X-RateLimit-Remaining: 95   # Remaining requests in the current time window
X-RateLimit-Reset: 1710835200  # Unix timestamp when the counter resets

When the limit is exceeded, the API returns a 429 Too Many Requests status code.

Versioning​

The GeniSpace API uses URL path prefixes for versioning, e.g., /v1/. We increment the version number when introducing breaking changes and keep older API versions available for a reasonable period.

Client Libraries​

GeniSpace provides an official JavaScript/TypeScript SDK with full API access capabilities. See Developer Resources for details.

JavaScript/TypeScript Example​

import GeniSpace from 'genispace';

// Initialize the client
const client = new GeniSpace({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.genispace.cn'  // Optional, default is api.genispace.ai
});

// Get user profile
const user = await client.users.getProfile();

// Create an agent
const agent = await client.agents.create({
  name: 'Smart Customer Service Assistant',
  description: 'A professional customer service AI assistant',
  agentType: 'CHAT',
  systemPrompt: 'You are a professional customer service assistant...'
});

// Agent chat
const chatResponse = await client.agents.chat(agent.id, {
  messages: [{ role: 'user', content: 'When will my order be shipped?' }],
  temperature: 0.7
});

// Agent execution
const execResponse = await client.agents.execute(agent.id, {
  inputs: { query: 'Analyze sales data', memory: true },
  settings: { temperature: 0.7, maxTokens: 2000 }
});

// Execute a task
const execResult = await client.tasks.execute('task_123456', { inputKey: 'value' });

// Get task execution status (requires execution ID)
const runStatus = await client.tasks.getRunStatus('execution_id');

For complete API capabilities, refer to Developer Resources and API Endpoints.

More Resources​

If you have any questions, check our FAQ or contact our support team for assistance.