igeo.ai Public REST API guide

Use the Public REST API to connect reporting systems, automations, and applications to an igeo.ai workspace. The production base URL is https://api.igeo.ai. Supported product routes expose reads and selected writes using the same workspace API keys as MCP.

Discover the supported surface

• Public API OpenAPI schema: supported REST paths and methods, input parameters, and response definitions.
• Public route catalog: allowed path templates, methods, tags, and role metadata.
• Actions OpenAPI schema: the read-only connector subset; also available at openapi.json.

Use the full Public API schema for REST integrations that require mutations. The Actions schema contains allowlisted GET operations and does not describe the entire public write surface. MCP clients discover operations through tools/list and allowed_routes, as described in the MCP guide.

The supported product surface includes prompts, topics, competitors, findings, sources, recommendations, agents' content, and selected workspace data. Marketplace access exposes the supported site catalog; payment, checkout, and publication management routes remain private. Billing, identity administration, internal operations, and system administration are outside the public product API.

Make an authenticated request

Create a key in MCP & API keys. Store IGEO_API_KEY and IGEO_WORKSPACE_ID privately in your environment. This example reads account details:

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"

Both the path's account ID and the header must refer to the authorized workspace. Read the operation's schema for required fields and supported filters. For JSON request bodies, also send Content-Type: application/json. Do not infer a public endpoint from a private request observed in the web application.

Use filtering and pagination from the schema

Parameters differ by operation. For example, the prompts list supports take and skip:

curl --fail-with-body \
  "https://api.igeo.ai/accounts/$IGEO_WORKSPACE_ID/prompts?take=25&skip=0" \
  --header "Authorization: Bearer $IGEO_API_KEY" \
  --header "X-Workspace-Id: $IGEO_WORKSPACE_ID"

Continue through pages using the documented pagination fields and response metadata. Direct REST requests do not use MCP's automatic page aggregation. Preserve filters and date ranges when fetching subsequent pages so your report describes a consistent query. Do not assume that an empty first page proves the workspace has no data under other filters.

Read before writing

Retrieve existing records and retain their IDs before preparing an update. Select the exact method and body from the published schema. Scope requirements are read for GET, write for POST/PUT/PATCH, and delete for DELETE; mcp:full covers supported operations. Mutations also require owner, admin, or editor access. See authentication for setup.

Review the intended change before submitting it. For content generation, retain the returned generation ID and inspect the corresponding post or generation detail before treating the work as complete. No universal idempotency-key contract is documented here. If the response to a mutation is lost, check whether the change took effect before repeating the request.

Handle errors and limits

Handle validation failures by checking the operation's input schema. Investigate 401 credentials and workspace mismatches, and 403 role, scope, or public route restrictions. On 429, wait for Retry-After. Inspect the X-RateLimit-* headers and their monthly variants; quotas are configuration dependent. Retry transient read failures with bounded backoff and jitter.

Log the method, path, status, and relevant response details without logging authorization values. Distinguish an empty successful response from a failed request. For MCP calls, additionally inspect JSON-RPC errors and tool isError.

Compatibility, versioning, and deprecation policy

The public API uses the production base URL https://api.igeo.ai. Individual route families can have their own versioned paths. The OpenAPI info.version identifies the published schema; it is not a promise that every route has a matching URL version.

Integrations should tolerate additional response fields, preserve unknown enum values for inspection, and use the documented fields and operation IDs. Review the published schema and product updates when updating a client.

For a planned breaking change or endpoint removal, the deprecation process is to publish a migration guide and the intended retirement date in the developer documentation and product updates before removing the old behavior. The affected OpenAPI operation is marked deprecated: true while it remains available. Deprecation and Sunset response headers belong to an announced retirement with an actual date; a readiness scan does not establish a retirement schedule.

The product Public API documentation includes the route catalog and data-use license. Use it alongside the live schema when implementing or updating an integration.