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:

Connecting an AI agent?

If you want an AI agent (Claude, ChatGPT, Cursor, …) to use GeniSpace for you, connect it via the MCP Integration — a standard Model Context Protocol server — instead of calling these REST endpoints directly.

Base URL

All API endpoints are served under the /api base path. Combine it with your region host:

https://api.genispace.ai/api

note

The server also mounts the same routes at the root (/), so host-only paths may work in some deployments. For portability, always include the /api prefix shown above. There is no /v1 namespace for the core REST API — any /v{N} prefix is stripped by the gateway. The only versioned surface is the OpenAI-compatible relay at /models/v1/* (see below).

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 execute (structured) or chat (multimodal streaming)
• Agent Sessions & Memory: Manage conversation sessions and long-term agent memory
• Agent Access Control: Restrict agent visibility to specific users within a space
• MCP Tools: Inspect the MCP tools available to an agent

2. Task API

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

• Task Definition: Create and configure tasks
• Task Execution: Trigger executions and track their status
• Execution History: Query a task's past executions and results
• Task Input/Output: Handle various types of input and output data

3. Dataset API

The dataset management API provides the following capabilities:

• Dataset Management: Create, list, and delete datasets
• Data Operations: Insert, update, query, delete, vector search, and full-text search over dataset rows

4. API Key Management

• Key Management: Create, list, and view API keys
• Validation: Verify whether an API key is valid
• Revocation: Revoke a key when it is no longer needed

Authentication & Security

API Key Authentication

All API requests require authentication. GeniSpace uses a hybrid Bearer authentication mechanism that accepts both JWT access tokens and API keys.

1. Open the Console and navigate to Settings → Integrations
2. In the API key area, create a new API key
3. 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.ai/api/agents" \
  -H "Authorization: Bearer 8OnG3iLUYdNq8PoO1JVW77aXbgHKBiOxIIufky7t"

API keys are 40-character alphanumeric tokens (no sk- prefix). The Bearer scheme is recommended; ApiKey, API-Key, and Token prefixes are also accepted. See the Authentication Guide for details.

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    /api/agents                       # List agents (supports accessibleOnly)
POST   /api/agents                       # Create a new agent (requires name, model, systemPrompt)
GET    /api/agents/{id}                  # Get agent details
PUT    /api/agents/{id}                  # Update an agent
DELETE /api/agents/{id}                  # Delete an agent
POST   /api/agents/{id}/chat             # Multimodal chat (SSE streaming, GeniSpace-native)
POST   /api/agents/{id}/execute          # Structured agent execution
GET    /api/agents/{id}/mcp/tools        # List MCP tools available to the agent
GET    /api/agents/system-agents         # List built-in system agents
POST   /api/agents/sessions              # Create a conversation session
GET    /api/agents/sessions              # List conversation sessions

Task API

GET    /api/tasks                        # List tasks
POST   /api/tasks                        # Create a new task
GET    /api/tasks/{id}                   # Get task details
PUT    /api/tasks/{id}                   # Update a task
DELETE /api/tasks/{id}                   # Delete a task
POST   /api/tasks/{id}/execute           # Execute a task
GET    /api/tasks/{id}/executions        # Get task execution history
GET    /api/tasks/runs/{executionId}     # Get a single execution's run status

Dataset API

GET    /api/datasets                          # List datasets
POST   /api/datasets                          # Create a new dataset
GET    /api/datasets/{id}                     # Get dataset details
DELETE /api/datasets/{id}                     # Delete a dataset
POST   /api/datasets/{id}/data/insert         # Insert rows
POST   /api/datasets/{id}/data/query          # Query rows with filters
POST   /api/datasets/{id}/data/update         # Update rows
POST   /api/datasets/{id}/data/delete         # Delete rows
POST   /api/datasets/{id}/data/search         # Vector search
POST   /api/datasets/{id}/data/full-text-search  # Full-text search

API Key API

GET    /api/api-keys                     # List API keys
POST   /api/api-keys                     # Create a new API key
GET    /api/api-keys/{id}                # Get API key details
PUT    /api/api-keys/{id}                # Update an API key
POST   /api/api-keys/{id}/revoke         # Revoke an API key
POST   /api/api-keys/validate            # Validate an API key

OpenAI-Compatible Relay

For OpenAI SDK compatibility, GeniSpace exposes a relay under /models/v1/* that forwards to the models service using the OpenAI wire format:

GET    /models/v1/{path}                 # OpenAI-compatible GET relay
POST   /models/v1/{path}                 # OpenAI-compatible POST relay (e.g. /models/v1/chat/completions)

Use this surface when you want to point an existing OpenAI client at GeniSpace. The agent chat endpoint (/api/agents/{id}/chat) is not OpenAI-messages-compatible — it uses a GeniSpace-native contents[] payload (see the Agent API).

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 and use a standard envelope:

{
  "success": true,
  "message": "Operation successful",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Smart Customer Service Assistant",
    "model": "gpt-4o",
    "agentType": "CHAT"
  }
}

The data field carries the entity or list returned by the endpoint.

Error Handling

When an API request fails, GeniSpace returns an appropriate HTTP status code along with a flat error body:

{
  "success": false,
  "message": "Validation failed: name is required",
  "code": "VALIDATION_ERROR"
}

The error body is flat — there is no nested error object. The code field carries a stable machine-readable error code.

Common HTTP status codes:

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

See the Error Handling guide for the full list of error codes.

Token & Quota Limits

GeniSpace meters usage by token consumption against your space's balance. When a request cannot be served because of balance or quota constraints, the API responds with a token/quota error:

• 402 with INSUFFICIENT_TOKENS — the space's token balance is depleted
• 402 with BELOW_MINIMUM_BALANCE — the balance is below the minimum required for the operation
• 400 with REQUEST_TOO_LARGE — the request payload exceeds the per-request token limit
• 429 with DAILY_LIMIT_EXCEEDED — the daily token usage limit has been reached

Top up your balance to resume normal operation. See Error Handling for details.

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 (baseURL includes the /api suffix)
const client = new GeniSpace({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.genispace.ai/api'  // Optional; this is also the default
});

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

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

// Agent chat (GeniSpace-native multimodal contents[])
const chatResponse = await client.agents.chat(agent.id, {
  contents: [{ type: 'text', text: 'When will my order be shipped?' }],
  settings: { temperature: 0.7 }
});

// Agent execution (structured inputs)
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' });

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

More Resources

• API Endpoints - Complete endpoint and parameter details
• Authentication Guide - Detailed authentication and security instructions
• Error Handling - Common errors and solutions
• Developer Resources - SDKs and client libraries

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