Public API - Genseo

The Public API exposes explicit, allowlisted Genseo operations. API keys stay project-bound; OAuth grants can list accessible projects and then operate on one explicit project per request.

Base URL

https://api.genseo.co/v1

Authentication

Send an OAuth access token or project-bound API key as a Bearer token:

curl https://api.genseo.co/v1/me   -H "Authorization: Bearer gs_live_..."

There is no cookie fallback. Ordinary browser-session JWTs are rejected. OAuth access tokens must target https://api.genseo.co/mcp.

Project matching

Most endpoints include projectId. It must match the API key’s project or a project available through the OAuth user’s current workspace memberships. Unauthorized project selection returns 403 project_forbidden and must not be retried with guessed IDs.

Endpoints

Method	Path	Purpose
`GET`	`/me`	Inspect the current key and project
`GET`	`/projects`	List accessible projects
`GET`	`/project`	Get the key’s project
`GET`	`/projects/{projectId}`	Get the matching project by ID
`PATCH`	`/projects/{projectId}`	Update allowlisted project settings
`GET`	`/projects/{projectId}/keywords`	List keywords
`POST`	`/projects/{projectId}/keywords`	Add a custom keyword
`PATCH/DELETE`	`/projects/{projectId}/keywords/{keywordId}`	Update or remove a keyword
`POST`	`/projects/{projectId}/keywords/generate`	Generate keyword ideas
`POST`	`/projects/{projectId}/keyword-metrics`	Refresh keyword metrics
`GET`	`/projects/{projectId}/posts`	List posts
`POST`	`/projects/{projectId}/posts`	Create a draft post
`GET`	`/projects/{projectId}/posts/{postId}`	Read one post
`PATCH`	`/projects/{projectId}/posts/{postId}`	Update a post
`DELETE`	`/projects/{projectId}/posts/{postId}`	Soft-delete a post; unavailable to OAuth Autopilot
`POST`	`/projects/{projectId}/posts/{postId}/generate`	Generate post content
`POST`	`/projects/{projectId}/posts/{postId}/publish`	Publish a post
`GET`	`/projects/{projectId}/integrations`	List integration status
`POST`	`/projects/{projectId}/integrations/{provider}/connect-url`	Create an integration connect URL
`GET`	`/projects/{projectId}/integrations/{provider}/fields`	List provider fields
`POST`	`/projects/{projectId}/integrations/{provider}/mapping`	Save provider field mapping
`GET`	`/projects/{projectId}/webhooks`	List webhooks
`POST`	`/projects/{projectId}/webhooks`	Create a webhook
`DELETE`	`/projects/{projectId}/webhooks/{webhookId}`	Delete a webhook
`GET/POST`	`/projects/{projectId}/audits`	List or start Site Audits
`GET`	`/projects/{projectId}/audits/current`	Read current Audit progress
`GET`	`/projects/{projectId}/audits/{auditId}`	Read one Audit from project history
`POST`	`/projects/{projectId}/audits/recheck`	Recheck applied fixes
`GET`	`/projects/{projectId}/site-health`	Read health summary
`GET`	`/projects/{projectId}/pages`	List audited pages
`GET`	`/projects/{projectId}/issues`	Filter Issues by status and severity
`GET/PATCH`	`/projects/{projectId}/issues/{issueId}`	Read, open or hide an Issue
`POST`	`/projects/{projectId}/issues/page-status/bulk`	Set up to 100 occurrences open/done
`GET`	`/projects/{projectId}/opportunities`	List prioritized Opportunities
`GET/PATCH`	`/projects/{projectId}/opportunities/{id}`	Read or update an Opportunity
`GET/POST`	`/projects/{projectId}/brand/{resource}`	Read or create brand data
`GET/PATCH`	`/projects/{projectId}/autopilot`	Read or update Autopilot
`POST`	`/projects/{projectId}/autopilot/bootstrap`	Bootstrap Autopilot
`GET`	`/projects/{projectId}/visibility/overview`	AI visibility KPIs, trend, competitors, sources
`GET`	`/projects/{projectId}/visibility/prompts`	List tracked visibility prompts
`GET`	`/projects/{projectId}/visibility/prompts/{promptId}`	Read one prompt and series
`GET`	`/projects/{projectId}/visibility/quota`	Prompt quota and enabled models
`POST`	`/projects/{projectId}/visibility/prompts`	Create tracked prompts without starting a run
`PATCH`	`/projects/{projectId}/visibility/prompts/{promptId}`	Archive or restore a prompt
`POST`	`/projects/{projectId}/visibility/prompts/{promptId}/track`	Enqueue a visibility tracking run

Identity

`GET /me`

Returns API-key metadata and its bound project, or OAuth authorization metadata plus accessible projects. OAuth responses require explicit project selection.

curl https://api.genseo.co/v1/me   -H "Authorization: Bearer gs_live_..."

Example response:

{
  "apiKey": {
    "id": "key_123",
    "name": "Claude agent",
    "prefix": "gs_live_abcd",
    "lastUsedAt": "2026-06-20T12:00:00.000Z"
  },
  "project": {
    "id": "47120f69-be45-4f32-bec9-f226f45748b6",
    "name": "Example GmbH",
    "domain": "example.com"
  }
}

Agents should call this endpoint before doing anything else.

Project

`GET /project`

Returns the project attached to the API key. OAuth clients use GET /projects and then GET /projects/{projectId}.

`GET /projects/{projectId}`

Returns the same project when projectId exactly matches the key’s project.

Keywords

`GET /projects/{projectId}/keywords`

Lists keywords for the project.

curl https://api.genseo.co/v1/projects/{projectId}/keywords   -H "Authorization: Bearer gs_live_..."

`POST /projects/{projectId}/keywords`

Adds a custom keyword.

{
  "keyword": "seo automation software",
  "searchVolume": 1200,
  "keywordDifficulty": 34,
  "intent": "commercial"
}

`POST /projects/{projectId}/keywords/generate`

Starts keyword generation for the project. Generation may return 202 Accepted when work continues asynchronously.

`POST /projects/{projectId}/keyword-metrics`

Refreshes metrics for one or more keywords.

{
  "keywords": ["seo automation software", "ai seo tool"]
}

Posts

`GET /projects/{projectId}/posts`

Lists posts for the project.

`POST /projects/{projectId}/posts`

Creates a draft post.

{
  "title": "How AI visibility automation works",
  "keywordId": "keyword_123"
}

`GET /projects/{projectId}/posts/{postId}`

Reads one post. The post must belong to the same project as the key.

`PATCH /projects/{projectId}/posts/{postId}`

Updates allowlisted fields on a post.

{
  "title": "Updated title",
  "status": "draft"
}

Agents should preserve existing content when patching. Read the post first, then send only intentional changes.

`POST /projects/{projectId}/posts/{postId}/generate`

Starts or queues content generation for a post.

`POST /projects/{projectId}/posts/{postId}/publish`

Publishes through the project’s configured integration. Agents should ask before publishing unless autonomous publishing is explicitly enabled by the user.

Integrations

`GET /projects/{projectId}/integrations`

Lists connected providers and readiness status.

`POST /projects/{projectId}/integrations/{provider}/connect-url`

Creates a provider connect URL when supported. The user may still need to complete OAuth or provider authorization in the browser.

`GET /projects/{projectId}/integrations/{provider}/fields`

Lists available provider fields for mapping.

`POST /projects/{projectId}/integrations/{provider}/mapping`

Saves field mapping.

{
  "connectionId": "connection_123",
  "siteId": "site_123",
  "collectionId": "collection_123",
  "fieldMap": {
    "title": "name",
    "content": "body"
  }
}

Webhooks

`GET /projects/{projectId}/webhooks`

Lists webhooks.

`POST /projects/{projectId}/webhooks`

Creates a webhook endpoint.

{
  "targetUrl": "https://example.com/genseo/webhook",
  "event": "post.published"
}

`DELETE /projects/{projectId}/webhooks/{webhookId}`

Deletes a webhook. The webhook must belong to the key’s project.

Pagination

List endpoints support a conservative limit parameter where available. Clients should prefer small pages and retry 429 responses with backoff.

Response safety

Responses are allowlisted. The Public API does not return provider secrets, full API key hashes, internal database fields, billing internals, or workspace-wide data.

Audit and Issue lifecycle

Audit starts return 202 Accepted. Poll /audits/current; do not repeatedly start new Audits. Read an Issue’s recommendation and page evidence, fix the site through an authorized CMS or repository, mark only the fixed {issue_id,page_id} occurrences as done, and run one Recheck. A later Audit can reopen a recurrence.

{
  "scope": {
    "type": "urls",
    "urls": ["https://example.test/services"]
  }
}

{
  "status": "done",
  "items": [
    {
      "issue_id": "00000000-0000-4000-8000-000000000002",
      "page_id": "00000000-0000-4000-8000-000000000003"
    }
  ]
}

AI visibility

Visibility endpoints are project-scoped. Read overview and prompt data before starting paid tracking runs.

`GET /projects/{projectId}/visibility/overview`

Returns KPIs, daily trend, competitors, cited sources, prompt summary, and setup progress for the requested period.

`GET /projects/{projectId}/visibility/prompts`

Lists active or archived prompts and latest mention, citation, and sentiment metrics where available.

`POST /projects/{projectId}/visibility/prompts/{promptId}/track`

Enqueues an external tracking run. Treat as potentially billable; confirm with the user before calling from an agent.

Brand data and Autopilot

Set {resource} to products, competitors, faqs, or ctas. Brand create requests accept at most 100 items and always bind them to the path’s project; IDs and project ownership cannot be supplied through the payload.

{
  "items": [
    {
      "question": "What does the example service include?",
      "answer": "Replace this placeholder with approved brand information."
    }
  ]
}

Autopilot updates accept only enabled, publish_interval_days, and publish_weekdays. OAuth writes require Agent Autonomy to have been enabled in the Genseo dashboard.

{
  "enabled": true,
  "publish_interval_days": 7,
  "publish_weekdays": [2, 4]
}

Rate limits

Boundary	Limit
OAuth connection or API key	30/minute and 5,000/UTC day
Writes per connection	10/minute
Workspace aggregate	150/minute and 25,000/UTC day
Audit/Recheck per project	One/10 minutes and six/UTC day
Audit/Recheck per workspace	25/UTC day

HTTP 429 uses code rate_limit_exceeded and includes Retry-After, RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset. Wait for Retry-After and then back off exponentially. Monthly plan quotas remain separate.

​Base URL

​Authentication

​Project matching

​Endpoints

​Identity

​GET /me

​Project

​GET /project

​GET /projects/{projectId}

​Keywords

​GET /projects/{projectId}/keywords

​POST /projects/{projectId}/keywords

​POST /projects/{projectId}/keywords/generate

​POST /projects/{projectId}/keyword-metrics

​Posts

​GET /projects/{projectId}/posts

​POST /projects/{projectId}/posts

​GET /projects/{projectId}/posts/{postId}

​PATCH /projects/{projectId}/posts/{postId}

​POST /projects/{projectId}/posts/{postId}/generate

​POST /projects/{projectId}/posts/{postId}/publish

​Integrations

​GET /projects/{projectId}/integrations

​POST /projects/{projectId}/integrations/{provider}/connect-url

​GET /projects/{projectId}/integrations/{provider}/fields

​POST /projects/{projectId}/integrations/{provider}/mapping

​Webhooks

​GET /projects/{projectId}/webhooks

​POST /projects/{projectId}/webhooks

​DELETE /projects/{projectId}/webhooks/{webhookId}

​Pagination

​Response safety

​Audit and Issue lifecycle

​AI visibility

​GET /projects/{projectId}/visibility/overview

​GET /projects/{projectId}/visibility/prompts

​POST /projects/{projectId}/visibility/prompts/{promptId}/track

​Brand data and Autopilot

​Rate limits