Skip to main content

GeniSpace API

The GeniSpace API lets an authorized application manage and use Space resources such as agents, background Agent jobs, tasks, workflows, datasets, datasources, operators, knowledge, applications, and Workbenches.

External AI clients

If an MCP-compatible AI client should discover and use GeniSpace capabilities dynamically, connect it through MCP. Use REST or the JavaScript SDK when your application owns the integration flow and data contract.

Base URLs​

SurfaceGlobal URLContract
Core REST APIhttps://api.genispace.ai/apiGeniSpace JSON APIs
Models relayhttps://api.genispace.ai/models/v1OpenAI-compatible model APIs
MCP serverhttps://api.genispace.ai/mcpMCP Streamable HTTP

Use the /api prefix for portable core REST integrations. Agent chat uses contents[]; it is not an OpenAI messages[] endpoint.

Authentication and Space scope​

Use a JWT access token for an authenticated application session or a dedicated API key for a server integration:

Authorization: Bearer YOUR_ACCESS_TOKEN_OR_API_KEY

Create and revoke API keys in Console. A request is evaluated against the associated user, Space, roles, resource access, and quota. An ID from another Space does not grant access to that resource.

Keep API keys out of browser bundles, source control, URLs, and logs. Use a separate key per integration and revoke a key immediately if it is exposed.

Core API areas​

Agents​

  • manage user-created agents and their access scope;
  • stream conversational agents with the single langgraph-v3 protocol;
  • execute structured task agents;
  • resume user-choice interactions and cancel turns;
  • inspect and compact session context;
  • submit and monitor long-running Agent jobs.

Tasks and workflows​

  • manage manual, scheduled, and event-triggered tasks;
  • start executions and inspect their status, node results, logs, and errors;
  • configure workflows, mappings, operators, and execution policies.

Data​

  • manage Datasets and Datasources;
  • insert, update, query, count, and delete typed Dataset records;
  • use full-text or vector semantic search;
  • execute authorized Datasource operations.

Platform resources​

Other endpoints manage API keys, knowledge bases, operators, applications, Workbenches, storage, configuration, analytics, billing, and Space membership. Availability depends on your role and deployment.

Response and error handling​

Most REST endpoints return a JSON envelope:

{
  "success": true,
  "data": { "id": "resource-id" }
}

Errors include an HTTP status and a machine-readable code when available:

{
  "success": false,
  "message": "You do not have access to this resource",
  "code": "FORBIDDEN"
}

Streaming Agent requests are different: they return SSE LangGraph V3 frames and can also report a runtime failure through error.occurred. See Agent API.

Common statuses include 400 validation, 401 authentication, 402 quota, 403 authorization, 404 missing resource, 409 state conflict, 426 outdated stream protocol, 429 rate or usage limit, and 5xx service failures.

JavaScript/TypeScript SDK​

The genispace package centralizes authentication, REST resources, Agent V3 streaming, event projection, and background Agent jobs.

import { GeniSpace } from 'genispace';

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

const agents = await client.agents.list({ accessibleOnly: true });

for await (const event of client.agents.chatStream('AGENT_ID', {
  contents: [{ type: 'text', text: 'Summarize the latest approved policy.' }],
  session_id: 'session-123',
  turnId: crypto.randomUUID(),
})) {
  if (event.type === 'content.delta') process.stdout.write(event.content ?? '');
}

const taskResult = await client.agents.execute('TASK_AGENT_ID', {
  inputs: { query: 'Extract the required fields' },
});

Use the SDK's chatStream() for streaming. agents.chat() is intentionally non-streaming and rejects stream: true.

Integration checklist​

  1. Select the correct Global endpoint.
  2. Create a least-privilege server credential or use the authenticated session token.
  3. Confirm the active Space and target resource ID.
  4. Test success, empty, validation, authorization, quota, retry, and cancellation paths.
  5. Use idempotency identifiers for turns and consequential background work.
  6. Preserve request, turn, execution, or job IDs for diagnostics.
  7. Never log secrets, full resumes, confidential documents, or unnecessary tool payloads.