--- title: "igeo.ai Public REST API guide" description: "Find igeo.ai OpenAPI schemas, make authenticated REST requests, and handle public API pagination, errors, and retries." url: "https://www.igeo.ai/developers/api/" language: "en" --- BUILD WITH igeo.ai[Read as Markdown ↗](https://www.igeo.ai/developers/api.md) # 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](https://api.igeo.ai/public-api.json): supported REST paths and methods, input parameters, and response definitions. - [Public route catalog](https://api.igeo.ai/public-api/routes): allowed path templates, methods, tags, and role metadata. - [Actions OpenAPI schema](https://api.igeo.ai/openai.json): the read-only connector subset; also available at [openapi.json](https://api.igeo.ai/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](https://www.igeo.ai/developers/mcp/). 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](https://app.igeo.ai/mcp-api-keys). Store `IGEO_API_KEY` and `IGEO_WORKSPACE_ID` privately in your environment. This example reads 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" ``` 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`: ```bash 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](https://www.igeo.ai/developers/auth/) 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](https://api.igeo.ai/public-api.json) and [product updates](https://www.igeo.ai/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](https://app.igeo.ai/docs/public-api) includes the route catalog and data-use license. Use it alongside the live schema when implementing or updating an integration. --- Source: https://www.igeo.ai/developers/api/ [Documentation index](https://www.igeo.ai/llms.txt) · [Developer documentation](https://www.igeo.ai/developers/)