Skip to main content

Client Portal: Interactive Documentation, SDKs, and Sandbox

Equipe Ontologie
Equipe Ontologie

Building applications on Ontologie shouldn't require reading hundreds of pages of technical documentation. The new Client Portal delivers a complete developer experience: interactive documentation with runnable examples, ready-to-use TypeScript and Python SDKs, and a sandbox to test your integrations without touching production.

Why a Client Portal​

Until now, integrating Ontologie into your applications required you to:

  • Read the API reference (hundreds of endpoints) to find the right calls.
  • Manually write HTTP calls with the correct headers, body, and parameters.
  • Test against your production workspace, risking changes to real data.
  • Handle authentication, pagination, errors, and types without any assistance.

The Client Portal eliminates these friction points by providing everything a developer needs in one place.

What's New​

Interactive Documentation​

The Client Portal offers interactive documentation where each endpoint comes with:

  • Clear description: what the endpoint does, when to use it, and which permissions are required.
  • Documented parameters: each parameter is described with its type, possible values, and examples.
  • Code examples: copy-paste-ready snippets in TypeScript, Python, curl, and other languages.
  • Built-in tester: execute an API call directly from the documentation and see the response in real time.
  • Response schemas: the exact response format, with the type of each field.

Practical example: you want to list the entities in your ontology. The Client Portal shows you the GET /api/queries/nodes endpoint, its filtering and pagination parameters, a sample request in TypeScript, and lets you execute it with your API key to see real data from your workspace.

TypeScript SDK​

The TypeScript SDK lets you interact with Ontologie from any Node.js, Deno, or browser application:

import { OntologieClient } from '@ontologie/client';

const client = new OntologieClient({
  apiKey: 'ont_live_votre_cle_api',
  workspaceId: 'votre-workspace-id',
});

// List entities
const entities = await client.nodes.list({
  entityType: 'concept',
  limit: 10,
});

// Create an entity
const newEntity = await client.commands.execute({
  type: 'CREATE_NODE',
  payload: {
    name: 'Mon entite',
    entityType: 'concept',
    position: { x: 100, y: 200 },
  },
});

SDK features:

  • Full typing: autocompletion and compile-time validation through generated TypeScript types.
  • Error handling: API errors are typed and structured (code, message, details).
  • Automatic pagination: iterate over large collections without managing cursors manually.
  • Built-in retry: transient errors (429, 503) are automatically retried.
  • Streaming: native SSE support for long-running operations (agent invocation, workflow execution).

Python SDK​

For data teams and Jupyter notebooks, the Python SDK offers the same experience:

from ontologie import OntologieClient

client = OntologieClient(
    api_key="ont_live_votre_cle_api",
    workspace_id="votre-workspace-id",
)

# List entities
entities = client.nodes.list(entity_type="concept", limit=10)

# Semantic search
results = client.search.semantic("clients avec contrat expire")

The Python SDK is compatible with pandas, Jupyter, and data science pipeline environments.

Sandbox​

The sandbox is an isolated test environment where you can experiment risk-free:

  • Test data: the sandbox comes pre-populated with sample data representing a typical ontology.
  • Sandbox API key: a dedicated API key is automatically generated for the sandbox.
  • Reset on demand: restore the sandbox to its initial state at any time.
  • Same APIs: the endpoints and behavior are identical to production — only the data differs.

Practical example: you're developing an integration that modifies entities. Instead of testing against your production workspace, you use the sandbox to validate your code. Once satisfied, you switch the API key to point to production.

OAuth Packages​

For applications that authenticate on behalf of a user (rather than with an API key), the SDK includes an OAuth package:

  • Standard OAuth2 flow with PKCE.
  • Automatic token refresh.
  • Compatible with popular web frameworks (React, Next.js, Express).

React Package​

A React package is also available for frontend applications:

import { useNodes, useCommands } from '@ontologie/react';

function EntityList() {
  const { data: nodes, isLoading } = useNodes({ entityType: 'concept' });
  const { execute } = useCommands();

  const handleCreate = async () => {
    await execute({
      type: 'CREATE_NODE',
      payload: { name: 'Nouvelle entite', entityType: 'concept' },
    });
  };

  if (isLoading) return <p>Loading...</p>;
  return (
    <ul>
      {nodes.map((node) => (
        <li key={node.id}>{node.name}</li>
      ))}
    </ul>
  );
}

The React hooks automatically handle caching, revalidation, and optimistic updates.

Getting Started​

  1. Access the Client Portal via the link in the navigation bar ("Client Portal") or at portal.ontologie-growthsystemes.com.
  2. Explore the interactive documentation: browse endpoints by category.
  3. Test in the sandbox: use the built-in tester to execute API calls.
  4. Install the SDK:
    • TypeScript: npm install @ontologie/client
    • Python: pip install ontologie
  5. Integrate into your application using your API key.

Next Steps​