---
title: "igeo.ai developer documentation"
description: "Connect AI assistants and integrations to igeo.ai through MCP, the Public REST API, and workspace API keys."
url: "https://www.igeo.ai/developers/"
language: "en"
---

BUILD WITH igeo.ai[Read as Markdown ↗](https://www.igeo.ai/developers.md)

# igeo.ai developer documentation

Connect an AI assistant or your own integration to your igeo.ai workspace. Read tracked prompts, topics, competitor data, AI mentions, sentiment, recommendations, and supported sources. Supported write operations let authorized integrations manage monitoring data and work with generated content.

## Choose an interface

| Interface | Use it for | Discovery |
| --- | --- | --- |
| MCP | An assistant that discovers and calls workspace tools | `tools/list`, `allowed_routes`, and MCP resources |
| Public REST API | Direct HTTP integrations and reporting | [Public API OpenAPI schema](https://api.igeo.ai/public-api.json) |
| OpenAPI Actions | A client importing the read-only connector schema | [Actions OpenAPI schema](https://api.igeo.ai/openai.json) |

The production API base URL is `https://api.igeo.ai`. The MCP endpoint is `https://api.igeo.ai/mcp`. Operations are limited to the public allowlist and the authenticated workspace. The full application API includes private routes that are outside this integration surface.

## Get an API key

Sign in and open [MCP & API keys](https://app.igeo.ai/mcp-api-keys). Active workspace members can manage keys. Copy the new key when it is displayed and record the workspace ID from the generated configuration. The secret is shown only when the key is created.

Store the key in a server-side secret store or local environment variable. Send these headers on authenticated requests:

```http
Authorization: Bearer <YOUR_API_KEY>
X-Workspace-Id: <YOUR_WORKSPACE_ID>
```

Use a key scoped to the required operations. For example, a reporting integration needs `read`. Public REST writes require an owner, admin, or editor role as well as the appropriate scope. MCP tools also require an owner, admin, or editor role. See [authentication and permissions](https://www.igeo.ai/developers/auth/) before enabling mutations.

## Make a first read

Set `IGEO_API_KEY` and `IGEO_WORKSPACE_ID` privately in your environment, then request the workspace's account details:

```bash
curl --fail-with-body \
  "https://api.igeo.ai/accounts/$IGEO_WORKSPACE_ID" \
  --header "Authorization: Bearer $IGEO_API_KEY" \
  --header "X-Workspace-Id: $IGEO_WORKSPACE_ID"
```

For an assistant connection, follow the [MCP setup guide](https://www.igeo.ai/developers/mcp/). After initialization, discover the tool schemas, call `allowed_routes`, then use a named read tool such as `prompt_work_priorities`. Named tools use the workspace supplied by authentication; do not invent another account ID.

## Build from observed workspace data

Fetch the current state before proposing changes. Keep the returned record IDs, date ranges, and pagination metadata with your results. Read the tool or OpenAPI schema before each new operation and check both HTTP and application-level errors.

Review proposed content or monitoring changes before applying them. If a write times out, first inspect the affected records or generation status before deciding to repeat it. These guides do not specify a universal idempotency-key contract.

## Continue

-   [MCP: connect, discover, and run a read workflow](https://www.igeo.ai/developers/mcp/)
-   [Authentication: keys, OAuth, permissions, and scopes](https://www.igeo.ai/developers/auth/)
-   [REST API: schemas, requests, pagination, and errors](https://www.igeo.ai/developers/api/)
-   [Product MCP documentation](https://app.igeo.ai/docs/mcp)
-   [Product Public API documentation and data-use terms](https://app.igeo.ai/docs/public-api)

## JavaScript SDK and CLI

The dependency-free JavaScript client includes TypeScript declarations and a read-only CLI for Node.js 22 or newer. Download the [igeo.ai SDK and CLI release](https://www.igeo.ai/downloads/igeo-ai-sdk-0.1.0.tgz) and install the public artifact:

```bash
npm install https://www.igeo.ai/downloads/igeo-ai-sdk-0.1.0.tgz
npx --no-install igeo info
npx --no-install igeo schema --summary
```

The installed package name is `@igeo-ai/sdk`. This download is available directly from igeo.ai; npm registry publication is a separate release step. The artifact's SHA-256 is `b34efe4a0c551472f5efc0158af39ff6d6449fd05d007b7fe47387dccb5f8551`.

Store `IGEO_API_KEY` and `IGEO_WORKSPACE_ID` privately before an authenticated read. The SDK makes one request per call, refuses redirects, and does not automatically retry mutations. The CLI can read public schema metadata and authorized workspace records; it cannot write workspace data. Read the package README for cancellation, typed errors, query filters, and client configuration.

## Python SDK

The Python 3.10+ client uses the standard library and the same workspace authentication. Install the [Python wheel](https://www.igeo.ai/downloads/igeo_ai-0.1.0-py3-none-any.whl) directly:

```bash
python -m pip install "https://www.igeo.ai/downloads/igeo_ai-0.1.0-py3-none-any.whl#sha256=47a58ea4c5ddf34f39933df496c27abfa85de02a0144ed2a04c9f2527710bb11"
```

Import the client from `igeo_ai`. It supports typed errors, query filters, per-request timeouts, and anonymous schema retrieval. It refuses redirects and makes no automatic retries. The [source archive](https://www.igeo.ai/downloads/igeo_ai-0.1.0.tar.gz) includes the usage guide and license. These are direct igeo.ai downloads; a PyPI listing is a separate publication step.

Endpoint availability, input fields, and allowed operations should be checked against the connected server and its published schemas.

---

Source: https://www.igeo.ai/developers/

[Documentation index](https://www.igeo.ai/llms.txt) · [Developer documentation](https://www.igeo.ai/developers/)