Agent API

GeniSpace provides two ways to invoke an agent, plus an OpenAI-compatible relay for existing OpenAI clients:

Multimodal Chat (/chat) — GeniSpace-native protocol using a contents[] array, with Server-Sent Events (SSE) streaming by default. Supports text, images, audio, and files.
Agent Execution (/execute) — Structured protocol with an inputs object and agent-specific feature toggles (memory, knowledge-base context, web search), returning a compact result.
OpenAI-Compatible Relay (/models/v1/*) — If you need to reuse an existing OpenAI SDK, point it at the relay described in the API Overview. The agent chat endpoint itself is not OpenAI-messages-compatible.

All agent invocation endpoints are gated by agent access control: callers must have access to the target agent.

Multimodal Chat

Endpoint

POST /api/agents/{agentId}/chat

Description

The native GeniSpace chat protocol. It accepts a multimodal contents[] array and, by default, streams the response back as Server-Sent Events (text/event-stream). This endpoint does not use the OpenAI messages format.

Request Parameters

Parameter	Type	Required	Description
`contents`	array	✓	Multimodal content array (must be non-empty). Each item has a `type` of `text`, `image_url`, `audio`, or `file`.
`session_id`	string	✗	Conversation session ID for multi-turn context
`stream`	boolean	✗	Whether to stream results via SSE. Defaults to `true`.
`settings`	object	✗	Model parameter settings (see below)

`contents` item shape

{ "type": "text", "text": "Message text" }
{ "type": "image_url", "image_url": { "url": "https://...", "detail": "auto" } }
{ "type": "audio", "audio_url": { "url": "https://..." } }
{ "type": "file", "file_info": { /* file metadata */ } }

The image_url.url and audio_url.url values accept both HTTP(S) URLs and data: base64 URIs.

`settings` parameters

Field	Type	Range / Default	Description
`temperature`	number	0–2	Controls output randomness
`max_tokens`	integer	≥ 1	Maximum output tokens
`top_p`	number	0–1	Nucleus sampling
`frequency_penalty`	number	—	Frequency penalty
`presence_penalty`	number	—	Presence penalty

Request Examples

Streaming Request (default)

curl -X POST "https://api.genispace.ai/api/agents/550e8400-e29b-41d4-a716-446655440000/chat" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      { "type": "text", "text": "Please help me write a market analysis report" }
    ],
    "settings": { "temperature": 0.7, "max_tokens": 2000 }
  }'

Multimodal Request (text + image)

curl -X POST "https://api.genispace.ai/api/agents/550e8400-e29b-41d4-a716-446655440000/chat" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      { "type": "text", "text": "Describe this chart" },
      { "type": "image_url", "image_url": { "url": "https://example.com/chart.png" } }
    ],
    "session_id": "ses_1234567890123_abcdef",
    "stream": false
  }'

Response Format

When stream is true (the default), the response has Content-Type: text/event-stream and emits SSE data: lines as the agent produces output, for example:

data: {"event": "session.started", "session_id": "ses_1234567890123_abcdef"}

data: {"event": "response.completed", "session_id": "ses_1234567890123_abcdef", "tokens_used": 620, "execution_time": 31017}

When stream is false, the response is a single JSON body.

Agent Execution

Endpoint

POST /api/agents/{agentId}/execute

Description

GeniSpace's structured execution protocol. It accepts an inputs object and returns a compact result with the answer, timing, and token usage. Use this when you want a single structured response and optional agent features such as memory, knowledge-base context, and web search.

Request Parameters

Parameter	Type	Required	Description
`inputs`	object	✗	Agent input parameters and feature toggles (see below)
`settings`	object	✗	Model parameter settings
`stream`	boolean	✗	Whether to stream results via SSE. Defaults to `false`.

`inputs` parameters

The inputs object accepts the following recognized fields, plus any additional custom variables your agent's prompt template expects:

Field	Type	Required	Description
`query`	string	✗	User query content
`session_id`	string	✗	Conversation session ID for multi-turn context
`memory`	boolean	✗	Enable memory, default `false`
`context`	boolean	✗	Enable knowledge-base context retrieval, default `false`
`internet`	boolean	✗	Enable internet search, default `false`
`images`	string[]	✗	Image URLs or `data:` base64 URIs
`audios`	string[]	✗	Audio URLs or `data:` base64 URIs

{
  "inputs": {
    "query": "User query content",
    "session_id": "ses_1234567890123_abcdef",
    "memory": true,
    "context": true,
    "internet": false,
    "images": ["https://example.com/image1.jpg"]
  }
}

`settings` parameters

Field	Type	Range	Description
`temperature`	number	0–1	Controls output randomness
`maxTokens`	integer	≥ 1	Maximum output tokens
`top_p`	number	0–1	Nucleus sampling
`presence_penalty`	number	—	Presence penalty
`frequency_penalty`	number	—	Frequency penalty

{
  "settings": {
    "temperature": 0.7,
    "maxTokens": 2000,
    "top_p": 1.0,
    "presence_penalty": 0,
    "frequency_penalty": 0
  }
}

Request Examples

Basic Query

curl -X POST "https://api.genispace.ai/api/agents/550e8400-e29b-41d4-a716-446655440000/execute" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "query": "Hello",
      "memory": true
    },
    "settings": {
      "temperature": 0.7,
      "maxTokens": 2000
    }
  }'

Enable Agent Features

curl -X POST "https://api.genispace.ai/api/agents/550e8400-e29b-41d4-a716-446655440000/execute" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "query": "Help me analyze customer satisfaction data",
      "memory": true,
      "context": true,
      "internet": true
    },
    "settings": {
      "temperature": 0.3,
      "maxTokens": 1500
    }
  }'

Response Format

Success Response

{
  "answer": "Hello! I'm happy to help...",
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "execution_time": 2.35,
  "token_usage": {
    "prompt_tokens": 168,
    "completion_tokens": 85,
    "total_tokens": 253,
    "cost": 0.012
  }
}

Response Field Descriptions

Field	Type	Description
`answer`	string	The response content generated by the agent
`agent_id`	string	ID of the executed agent
`execution_time`	number	Execution time (seconds)
`token_usage`	object	Token usage statistics
`token_usage.prompt_tokens`	integer	Input token count
`token_usage.completion_tokens`	integer	Output token count
`token_usage.total_tokens`	integer	Total token count
`token_usage.cost`	number	Billed cost for the execution

When stream is true, the response is delivered as SSE (text/event-stream) instead of a single JSON body.

Agent Access Control

When creating an agent (POST /api/agents), the following fields are required: name, model, and systemPrompt. You can also control who within the space may invoke the agent:

Field	Type	Description
`accessScope`	string	`SPACE` (all space members) or `RESTRICTED` (only listed users)
`allowedUserIds`	string[]	User IDs allowed to access a `RESTRICTED` agent

When listing agents (GET /api/agents), pass accessibleOnly=true to return only the agents the caller can access. All invocation endpoints enforce this access control.

Error Handling

All agent endpoints use the standard flat error envelope:

{
  "success": false,
  "message": "Resource not found",
  "code": "NOT_FOUND"
}

Common Error Codes

Error Code	HTTP Status	Description
`VALIDATION_ERROR`	400	Invalid request parameters
`UNAUTHORIZED`	401	Missing or invalid credentials
`FORBIDDEN`	403	No access to the requested agent
`NOT_FOUND`	404	Agent does not exist
`INSUFFICIENT_TOKENS`	402	Token balance depleted
`SERVER_ERROR`	500	Internal server error

See Error Handling for the complete list.

Best Practices

Choosing the Right Protocol

Use Chat (/chat) when:
- You want streaming responses (SSE)
- You need multimodal inputs (images, audio, files)
- You are building an interactive conversational experience
Use Execute (/execute) when:
- You want a single structured result with token usage and timing
- You want to toggle agent features (memory, knowledge-base context, web search)
- You are passing custom prompt-template variables
Use the OpenAI relay (/models/v1/*) when:
- You need to reuse an existing OpenAI SDK or codebase

Performance Optimization

Selectively enable features based on requirements: memory, context, internet
Set maxTokens / max_tokens appropriately to control response length and cost
Adjust temperature based on task complexity

Security Considerations

Always validate user input to prevent injection attacks
Restrict agent access with accessScope / allowedUserIds in production
Apply appropriate data masking for sensitive data

SDK Support

JavaScript SDK

The official GeniSpace JavaScript SDK supports agent chat and execution. See Developer Resources for details.

import GeniSpace from 'genispace';

const client = new GeniSpace({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.genispace.ai/api'
});

// Multimodal chat (GeniSpace-native contents[])
const chatResponse = await client.agents.chat('550e8400-e29b-41d4-a716-446655440000', {
  contents: [{ type: 'text', text: 'Analyze sales data' }],
  settings: { temperature: 0.7 }
});

// Agent execution (structured inputs)
const execResponse = await client.agents.execute('550e8400-e29b-41d4-a716-446655440000', {
  inputs: {
    query: 'Analyze sales data',
    memory: true,
    context: true,
    internet: false
  },
  settings: {
    temperature: 0.7,
    maxTokens: 2000
  }
});

API Endpoints - Complete endpoint reference
Authentication Guide - API key and security setup
Agent Overview - Agent feature details
Agent Memory - Memory system usage guide

Multimodal Chat​

Endpoint​

Description​

Request Parameters​

contents item shape​

settings parameters​

Request Examples​

Streaming Request (default)​

Multimodal Request (text + image)​

Response Format​

Agent Execution​

Endpoint​

Description​

Request Parameters​

inputs parameters​

settings parameters​

Request Examples​

Basic Query​

Enable Agent Features​

Response Format​

Success Response​

Response Field Descriptions​

Agent Access Control​

Error Handling​

Common Error Codes​

Best Practices​

Choosing the Right Protocol​

Performance Optimization​

Security Considerations​

SDK Support​

JavaScript SDK​

Related Documentation​

Multimodal Chat

Endpoint

Description

Request Parameters

`contents` item shape

`settings` parameters

Request Examples

Streaming Request (default)

Multimodal Request (text + image)

Response Format

Agent Execution

Endpoint

Description

Request Parameters

`inputs` parameters

`settings` parameters

Request Examples

Basic Query

Enable Agent Features

Response Format

Success Response

Response Field Descriptions

Agent Access Control

Error Handling

Common Error Codes

Best Practices

Choosing the Right Protocol

Performance Optimization

Security Considerations

SDK Support

JavaScript SDK

Related Documentation