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 cached responses
Twelve cached GET operations, including GET /accounts/{accountId}/pages/v2, wrap successful resource data in a cache envelope. For example, a 200 response with an empty page list can be:
{
"data": [],
"computedAt": "2026-10-22T00:00:00.000Z",
"dataVersion": 1,
"isLive": false
}
Read resource fields or arrays from data. computedAt is the computation timestamp and can be null on an existing cache record. dataVersion is the cache record version. isLive: true indicates fresh computation or a cache bypass; false indicates a cached result. Use the operation's response schema to distinguish this envelope from an unwrapped response.
While a cache is building, the GET can return 202 with this pending body:
{"statusCode":202,"message":"Cache is building"}
Check HTTP status before parsing resource data. Keep the same workspace, path, and filters, then retry the GET with bounded backoff and jitter. Set a client retry budget and leave the result pending if that budget is exhausted. Cache-building responses do not specify a universal polling interval or guarantee a Retry-After header.
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. 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.
Follow background content generation
POST /accounts/{accountId}/agents/generateContent starts background generation. For an approved draft request, send JSON such as:
{
"topic": "AI search visibility",
"prompt": "Draft a concise LinkedIn post explaining how to review AI citations.",
"socialMediaProvider": "LINKEDIN",
"generateImage": false
}
The acknowledgement is HTTP 201 with generationId and message, for example:
{
"generationId": "<returned-generation-id>",
"message": "Task started, processing in the background"
}
Retain that ID as IGEO_GENERATION_ID and read generation details using the same workspace credentials:
curl --fail-with-body \
"https://api.igeo.ai/accounts/$IGEO_WORKSPACE_ID/agents/posts/$IGEO_GENERATION_ID/detail" \
--header "Authorization: Bearer $IGEO_API_KEY" \
--header "X-Workspace-Id: $IGEO_WORKSPACE_ID"
This GET returns HTTP 200 with {posts, totalCount}. An initial empty posts array can still mean the worker has not created its rows. Inspect each returned post's state: IN_PROGRESS is pending, FAILED reports a failure for that post, and SUGGESTED means a generated draft is ready for inspection. Review its content before approval or publication; a suggested draft does not establish that content was posted or is publicly visible.
History is also available at GET /accounts/{accountId}/agents/posts?generationId={generationId}. Its default filters can omit ordinary IN_PROGRESS posts, so prefer the detail endpoint while waiting. Poll GETs within your own retry budget, stop on a reported failure, and reconcile an unresolved generation before considering another POST. The acknowledgement provides no completion deadline or guaranteed polling interval.
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.