Agent API Reference

Build integrations with Nexting's website optimization infrastructure. Let AI Agents create, manage, and publish SEO-optimized pages — programmatically.

Built for AI Agents

Pro Plan Required

The Agent API is available on Pro and Enterprise plans. API keys can be created from the Dashboard or via the Key Management endpoints below.

Quick Start

Create an API Key

Each API key is scoped to a single project. Create one from your Dashboard or use the Key Management API below.

Go to Dashboard → Create API KeySelect a project, then navigate to API Keys

Or create via the API:

bash

# Create a key via the API (requires session auth)
curl -X POST https://nexting.ai/api/v1/keys \
  -H "Content-Type: application/json" \
  -H "Cookie: <session_cookie>" \
  -d '{
    "project_id": "your-project-uuid",
    "name": "My Agent Key",
    "scopes": ["read", "write"]
  }'

The plaintext key is shown only once at creation. Store it securely — it cannot be retrieved again.

Make Your First Request

Use the key as a Bearer token. We recommend starting with the Agent Brief endpoint for a complete snapshot of your site:

bash

curl https://nexting.ai/api/v1/sites/example.com/brief \
  -H "Authorization: Bearer nxt_your_api_key_here"

Create a Page

Publish a new page through Nexting's proxy — no code changes needed on your site:

bash

curl -X POST https://nexting.ai/api/v1/sites/example.com/pages \
  -H "Authorization: Bearer nxt_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/blog/ai-seo-tips",
    "title": "10 AI SEO Tips for 2026",
    "content": "<h2>Tip 1: Optimize for Answer Engines</h2><p>...</p>",
    "meta_description": "Practical tips for AI search optimization.",
    "status": "published"
  }'

Base URL

text

https://nexting.ai/api/v1

All endpoints described below are relative to this base URL.

Authentication

Public API endpoints use Bearer token authentication. Include your API key in the Authorization header:

http

Authorization: Bearer nxt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API Key Properties

Prefix: nxt_ — 48 characters total
Hashed with SHA-256 before storage — plaintext shown only on creation
Scoped to a single project
Permissions controlled by scopes: read, write, auto

Scopes

Each API key can be granted one or more scopes that control access to endpoints:

Scope	Access
`read`	List pages, view analytics, read site data
`write`	Create, update, and delete pages
`auto`	Trigger automated operations (auto-optimize, auto-generate)

Key Management

These endpoints use session auth (Dashboard cookies), not API key auth. They are for managing keys through the Dashboard or admin tools.

GET/api/v1/keys

List all API keys for the current user.

Response 200 OK

json

{
  "data": [
    {
      "id": "uuid",
      "project_id": "uuid",
      "name": "Production Key",
      "key_prefix": "nxt_abc1",
      "scopes": ["read", "write"],
      "rate_limit_rpm": 60,
      "rate_limit_rph": 1000,
      "rate_limit_rpd": 10000,
      "is_active": true,
      "last_used_at": "2026-02-15T10:00:00Z",
      "expires_at": null,
      "created_at": "2026-02-15T09:00:00Z"
    }
  ]
}

POST/api/v1/keys

Create a new API key. Requires project owner or admin role.

Parameters

Name	Type	Required	Description
`project_id`	string	Yes	Project to bind this key to
`name`	string	No	Human-readable label. Default: "Default API Key"
`scopes`	string[]	No	Permissions. Default: ["read"]
`rate_limit_rpm`	number	No	Requests per minute. Default: 60
`rate_limit_rph`	number	No	Requests per hour. Default: 1000
`rate_limit_rpd`	number	No	Requests per day. Default: 10000
`expires_at`	string \| null	No	ISO 8601 expiration, or null for no expiry

Request Body

json

{
  "project_id": "your-project-uuid",
  "name": "Agent Key",
  "scopes": ["read", "write"],
  "rate_limit_rpm": 60,
  "rate_limit_rph": 1000,
  "rate_limit_rpd": 10000,
  "expires_at": null
}

Response 201 Created

json

{
  "data": {
    "id": "uuid",
    "key": "nxt_abc1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "key_prefix": "nxt_abc1",
    "name": "Agent Key",
    "scopes": ["read", "write"],
    "is_active": true,
    "created_at": "2026-02-15T09:00:00Z"
  }
}

GET/api/v1/keys/{keyId}

Get details of a single API key.

PATCH/api/v1/keys/{keyId}

Update an API key's name, scopes, rate limits, or active status.

Request Body

json

{
  "name": "Renamed Key",
  "scopes": ["read"],
  "is_active": false
}

DELETE/api/v1/keys/{keyId}

Permanently delete an API key.

Response 200 OK

json

{
  "data": { "deleted": true }
}

Agent Brief

The recommended first call for any AI agent. Returns an aggregated snapshot of your site in a single request — site info, traffic metrics, AI visibility score, optimization insights, and available actions.

This endpoint consolidates data from multiple sources so agents can understand your site's current state without making several separate API calls.

GET/api/v1/sites/{domain}/briefscope: read

Aggregated agent briefing with site info, traffic, visibility score, insights, and available actions.

Parameters

Name	Type	Required	Description
`period`	query	No	Time period: "24h", "7d" (default), "30d", or "90d"

Response 200 OK

json

{
  "data": {
    "site": {
      "domain": "example.com",
      "name": "Example Inc",
      "description": "AI-powered SaaS platform",
      "status": "active",
      "pages_count": 12,
      "published_pages": 10
    },
    "traffic": {
      "period": "7d",
      "total_requests": 1245,
      "ai_crawler_requests": 312,
      "ai_referral_visits": 87,
      "top_crawlers": ["GPTBot", "ClaudeBot", "PerplexityBot"],
      "top_referrers": ["perplexity.ai", "chatgpt.com"]
    },
    "visibility": {
      "score": 72.5,
      "trend": 4.2,
      "breakdown": {
        "core_visibility": 65.0,
        "solution_test": 78.0,
        "context_check": 80.0,
        "knowledge_test": 70.0
      }
    },
    "insights": [
      {
        "type": "opportunity",
        "priority": "high",
        "message": "Create content for 'AI SEO tools' — high search volume, not currently cited."
      }
    ],
    "summary": "Your site has good AI visibility (72.5/100, up 4.2). 312 AI crawler visits this week. 3 high-priority optimization opportunities available.",
    "available_actions": [
      "create_page", "auto_generate", "auto_optimize", "view_analytics"
    ]
  }
}

Pages API

These endpoints use API key auth (Bearer token). The {domain} parameter must match the API key's project domain.

Pages created through the API are automatically rendered using the project's template (header, footer, styles) and served through Nexting's proxy infrastructure.

GET/api/v1/sites/{domain}/pagesscope: read

List all pages managed by Nexting for this domain.

Parameters

Name	Type	Required	Description
`status`	query	No	Filter: draft, published, offline
`source`	query	No	Filter: manual, agent, auto
`limit`	query	No	Max results, 1-100. Default: 50
`offset`	query	No	Pagination offset. Default: 0

Response 200 OK

json

{
  "data": [
    {
      "id": "uuid",
      "project_id": "uuid",
      "path": "/blog/ai-seo-guide",
      "title": "AI SEO Guide",
      "meta_description": "Learn how to optimize...",
      "meta_keywords": "AI SEO, AEO",
      "status": "published",
      "source": "agent",
      "view_count": 142,
      "auto_page_slot": null,
      "created_at": "2026-02-10T08:00:00Z",
      "updated_at": "2026-02-14T12:00:00Z"
    }
  ],
  "meta": {
    "timestamp": "2026-02-15T10:30:00Z",
    "total": 12,
    "limit": 50,
    "offset": 0,
    "domain": "example.com"
  }
}

POST/api/v1/sites/{domain}/pagesscope: write

Create a new page and publish it through the proxy.

Parameters

Name	Type	Required	Description
`path`	string	Yes	URL path (e.g., /blog/my-article). Auto-prefixed with / if missing.
`title`	string	Yes	Page title (used in <title> and <h1>)
`content`	string	Yes	Page content (HTML body)
`meta_description`	string	No	Meta description for SEO
`meta_keywords`	string	No	Comma-separated keywords
`status`	string	No	"draft" (default) or "published"

Request Body

json

{
  "path": "/blog/ai-seo-tips",
  "title": "10 AI SEO Tips for 2026",
  "content": "<h2>Tip 1</h2><p>Optimize for answer engines...</p>",
  "meta_description": "Practical tips for AI search optimization.",
  "meta_keywords": "AI SEO, tips",
  "status": "published"
}

Response 201 Created

json

{
  "data": {
    "id": "uuid",
    "project_id": "uuid",
    "path": "/blog/ai-seo-tips",
    "title": "10 AI SEO Tips for 2026",
    "meta_description": "Practical tips...",
    "status": "published",
    "source": "agent",
    "created_at": "2026-02-15T10:30:00Z",
    "updated_at": "2026-02-15T10:30:00Z"
  },
  "meta": {
    "timestamp": "2026-02-15T10:30:00Z"
  }
}

GET/api/v1/sites/{domain}/pages/{pageId}scope: read

Get full details of a single page including content.

Response 200 OK

json

{
  "data": {
    "id": "uuid",
    "project_id": "uuid",
    "path": "/blog/ai-seo-tips",
    "title": "10 AI SEO Tips for 2026",
    "content": "<h2>Tip 1</h2><p>...</p>",
    "meta_description": "Practical tips...",
    "meta_keywords": "AI SEO, tips",
    "status": "published",
    "source": "agent",
    "view_count": 142,
    "auto_page_slot": null,
    "created_at": "2026-02-15T10:30:00Z",
    "updated_at": "2026-02-15T10:30:00Z"
  }
}

PUT/api/v1/sites/{domain}/pages/{pageId}scope: write

Update a page's content, metadata, or status. Re-renders HTML automatically on content change. Auto pages cannot be edited.

Parameters

Name	Type	Required	Description
`path`	string	No	New URL path. Checked for duplicates.
`title`	string	No	New page title
`content`	string	No	New HTML body. Triggers re-render.
`meta_description`	string	No	New meta description
`meta_keywords`	string	No	New keywords
`status`	string	No	"draft", "published", or "offline"

Request Body

json

{
  "title": "Updated Title",
  "content": "<h2>New content</h2><p>...</p>",
  "meta_description": "Updated description",
  "status": "published"
}

Response 200 OK

json

{
  "data": {
    "id": "uuid",
    "path": "/blog/ai-seo-tips",
    "title": "Updated Title",
    "status": "published",
    "source": "agent",
    "updated_at": "2026-02-16T08:00:00Z"
  }
}

DELETE/api/v1/sites/{domain}/pages/{pageId}scope: write

Permanently delete a page. Auto pages cannot be deleted.

Response 200 OK

json

{
  "data": {
    "deleted": true,
    "id": "uuid"
  }
}

Intelligence API

Read-only endpoints that return site analysis, AI visibility scores, content opportunities, and competitor intelligence. All use API key auth with read scope.

These endpoints return data from Nexting's analysis engine. Data is populated when you run checks from the Dashboard or via automated scans.

GET/api/v1/sites/{domain}/analyzescope: read

Full site analysis combining AI visibility, page stats, top opportunities, site audit, and actionable recommendations.

Response 200 OK

json

{
  "data": {
    "domain": "example.com",
    "site_name": "Example Inc",
    "status": "active",
    "ai_visibility": {
      "score": 72.5,
      "trend": 4.2,
      "share_of_voice": 31.0,
      "breakdown": {
        "core_visibility": 65.0,
        "solution_test": 78.0,
        "context_check": 80.0,
        "knowledge_test": 70.0
      },
      "position": {
        "avg_when_mentioned": 2.3,
        "top_3_rate": 64.0,
        "first_mention_rate": 28.0
      },
      "brand_health": {
        "sentiment": 45.0,
        "discoverability": 90.0
      },
      "last_checked_at": "2026-02-14T18:00:00Z"
    },
    "site_audit": { "score": 85, "passed": 17, "total": 20 },
    "pages": {
      "total": 12,
      "published": 10,
      "draft": 2,
      "by_source": { "manual": 4, "agent": 3, "auto": 5 }
    },
    "top_pages": [
      { "path": "/blog/ai-seo", "title": "AI SEO Guide", "views": 340, "source": "agent" }
    ],
    "top_opportunities": [
      {
        "topic": "answer engine optimization",
        "keyword": "AEO guide",
        "type": "gap",
        "priority_score": 85,
        "ai_score": 90,
        "seo_score": 75,
        "recommended_actions": ["Create comprehensive AEO guide"]
      }
    ],
    "competitors_tracked": 3,
    "llms_txt_enabled": true,
    "recommendations": [
      "You have 5 actionable content opportunities. Address high-priority ones first."
    ]
  }
}

GET/api/v1/sites/{domain}/scorescope: read

Quick AI visibility score (0-100) with breakdown by question type, AI engine, position metrics, and brand health.

Response 200 OK

json

{
  "data": {
    "visibility_score": 72.5,
    "visibility_trend": 4.2,
    "share_of_voice": 31.0,
    "breakdown": {
      "by_question_type": {
        "core_visibility": 65.0,
        "solution_test": 78.0,
        "context_check": 80.0,
        "knowledge_test": 70.0
      },
      "by_engine": {
        "perplexity": { "score": 80.0, "share_of_voice": 35.0 },
        "chatgpt": { "score": 68.0, "share_of_voice": 28.0 },
        "gemini": { "score": 70.0, "share_of_voice": 30.0 },
        "claude": { "score": 72.0, "share_of_voice": 32.0 }
      },
      "position": {
        "avg_position_when_mentioned": 2.3,
        "top_3_rate": 64.0,
        "first_mention_rate": 28.0
      },
      "brand_health": {
        "sentiment_score": 45.0,
        "discoverability_rate": 90.0
      }
    },
    "last_checked_at": "2026-02-14T18:00:00Z"
  }
}

GET/api/v1/sites/{domain}/opportunitiesscope: read

Content opportunities ranked by priority. Combines AI citation gaps, SEO keyword data, and trend signals.

Parameters

Name	Type	Required	Description
`type`	query	No	Filter: trending, gap, optimize, ai_citation, competitor_gap
`status`	query	No	Filter: new, viewed, in_progress, actioned, dismissed
`sort`	query	No	"priority" (default), "ai", or "seo"
`limit`	query	No	Max results, 1-100. Default: 20
`offset`	query	No	Pagination offset. Default: 0

Response 200 OK

json

{
  "data": {
    "opportunities": [
      {
        "id": "uuid",
        "topic": "answer engine optimization",
        "keyword": "AEO guide",
        "opportunity_type": "gap",
        "ai_citation_status": "not_cited",
        "ai_citation_rate": 0,
        "search_volume": 2400,
        "keyword_difficulty": 35,
        "priority_score": 85,
        "ai_opportunity_score": 90,
        "seo_opportunity_score": 75,
        "reasoning": "High search volume, low difficulty, not cited by any AI engine.",
        "recommended_actions": ["Create comprehensive AEO guide"],
        "status": "new"
      }
    ],
    "summary": {
      "total": 15,
      "high_priority": 4,
      "by_type": { "trending": 3, "gap": 5, "optimize": 4, "ai_citation": 2, "competitor_gap": 1 }
    }
  }
}

GET/api/v1/sites/{domain}/competitorsscope: read

Tracked competitors with Share of Voice data and mention statistics.

Response 200 OK

json

{
  "data": {
    "your_brand": {
      "mentions": 28,
      "citations": 15,
      "avg_position": 2.1,
      "top_picks": 8,
      "mention_sov": 31.0,
      "citation_sov": 35.0
    },
    "competitors": [
      {
        "id": "uuid",
        "competitor_domain": "competitor.com",
        "competitor_name": "Competitor Inc",
        "is_active": true,
        "stats": {
          "mentions": 22,
          "recommendations": 6,
          "avg_position": 2.8
        }
      }
    ],
    "total_competitors": 3
  }
}

Analytics API

AI traffic analytics — crawler visits, AI-referred users, and optimization insights. All use API key auth with read scope.

Analytics data is collected by the Nexting middleware SDK. Deploy it on your site to start tracking AI traffic.

GET/api/v1/sites/{domain}/analyticsscope: read

AI traffic analytics broken down by section. Returns different data depending on the section parameter.

Parameters

Name	Type	Required	Description
`section`	query	No	"overview" (default), "daily", "crawlers", "referrals", or "pages"
`period`	query	No	"24h", "7d" (default), "30d", or "90d"

Response 200 OK

json

{
  "data": {
    "period": "7d",
    "section": "overview",
    "total_requests": 1245,
    "ai_crawler_requests": 312,
    "ai_referral_visits": 87,
    "human_visits": 846,
    "top_crawlers": [
      { "name": "GPTBot", "requests": 145 },
      { "name": "ClaudeBot", "requests": 98 },
      { "name": "PerplexityBot", "requests": 69 }
    ],
    "top_referrers": [
      { "source": "perplexity.ai", "visits": 42 },
      { "source": "chatgpt.com", "visits": 28 }
    ]
  }
}

GET/api/v1/sites/{domain}/analytics/insightsscope: read

AI-generated optimization insights prioritized by impact. Insights are cached and refreshed periodically.

Parameters

Name	Type	Required	Description
`refresh`	query	No	Force regeneration of insights. Default: false
`limit`	query	No	Max insights to return. Default: 10

Response 200 OK

json

{
  "data": {
    "insights": [
      {
        "id": "uuid",
        "type": "optimization",
        "priority": "high",
        "title": "Optimize FAQ page for AI citation",
        "description": "Your FAQ page receives 45 AI crawler visits/week but is not being cited. Add structured Q&A markup.",
        "impact_score": 85,
        "status": "active",
        "created_at": "2026-02-15T10:00:00Z"
      }
    ],
    "total": 8,
    "generated_at": "2026-02-15T10:00:00Z"
  }
}

Automation API

Endpoints for triggering automated content operations — auto-optimization scheduling, AI page generation, and optimization reporting. Use API key auth with the scopes indicated on each endpoint.

Auto-optimize controls per-page optimization schedules. Auto-generate uses Nexting's AI engine to create SEO-optimized pages based on your site's context and keyword data.

GET/api/v1/sites/{domain}/auto-optimizescope: read

Get auto-optimization status for all published pages, including schedules and admin kill switch state.

Response 200 OK

json

{
  "data": {
    "kill_switch_active": false,
    "summary": {
      "total_published": 12,
      "auto_optimize_enabled": 5,
      "auto_optimize_disabled": 7
    },
    "pages": [
      {
        "id": "uuid",
        "path": "/blog/ai-seo",
        "title": "AI SEO Guide",
        "auto_optimize_enabled": true,
        "schedule": "weekly",
        "next_optimize_at": "2026-02-22T00:00:00Z",
        "last_optimized_at": "2026-02-15T00:00:00Z"
      }
    ]
  }
}

POST/api/v1/sites/{domain}/auto-optimizescope: write

Enable or configure auto-optimization for specific pages. Auto pages (source='auto') are managed by the platform and cannot be configured.

Parameters

Name	Type	Required	Description
`page_ids`	string[]	Yes	Page UUIDs to configure (max 50)
`enabled`	boolean	No	Enable or disable auto-optimization
`schedule`	string	No	"daily", "weekly", "biweekly", "monthly", or "off"

Request Body

json

{
  "page_ids": ["uuid-1", "uuid-2"],
  "enabled": true,
  "schedule": "weekly"
}

Response 200 OK

json

{
  "data": {
    "updated": 2,
    "skipped": 0,
    "schedule": "weekly",
    "enabled": true
  }
}

GET/api/v1/sites/{domain}/pages/auto-generatescope: read

Get auto page generation status — existing auto pages, plan limits, and refresh intervals.

Response 200 OK

json

{
  "data": {
    "auto_pages": [
      {
        "id": "uuid",
        "path": "/about",
        "title": "About Example Inc",
        "status": "published",
        "auto_page_slot": 1,
        "auto_last_refreshed_at": "2026-02-15T00:00:00Z",
        "auto_next_refresh_at": "2026-02-22T00:00:00Z",
        "view_count": 45,
        "created_at": "2026-02-01T00:00:00Z"
      }
    ],
    "limits": {
      "max_auto_pages": 20,
      "current_count": 5,
      "refresh_interval_days": 7
    },
    "plan": "pro"
  }
}

POST/api/v1/sites/{domain}/pages/auto-generatescope: auto

Trigger AI content generation. Creates SEO-optimized pages based on your domain, keywords, and tag content knowledge. Supports optional parameters to control topics, style, and count. Only available for sites you own.

Parameters

Name	Type	Required	Description
`topics`	string[]	No	Specific topics to generate pages about. Overrides default slot strategy.
`target_keywords`	string[]	No	Target keywords to optimize for. Overrides stored keyword data.
`style`	string	No	"professional", "conversational", or "technical"
`count`	number	No	Number of pages to generate, 1-5. Default: 5
`target_audience`	string	No	Target audience description for content tailoring

Request Body

json

{
  "topics": ["AI SEO best practices", "pricing comparison"],
  "target_keywords": ["AI SEO", "answer engine optimization"],
  "style": "professional",
  "count": 3,
  "target_audience": "SaaS marketing teams"
}

Response 201 Created

json

{
  "data": {
    "created": 3,
    "page_ids": ["uuid-1", "uuid-2", "uuid-3"],
    "errors": 0,
    "has_knowledge": true
  }
}

GET/api/v1/sites/{domain}/reportsscope: read

Optimization history and auto page reports. Returns optimization run summaries, page-level change logs, and auto page performance data.

Parameters

Name	Type	Required	Description
`type`	query	No	"all" (default), "optimization", or "auto_page"
`limit`	query	No	Max results per section, 1-100. Default: 20
`offset`	query	No	Pagination offset. Default: 0

Response 200 OK

json

{
  "data": {
    "optimization": {
      "total_runs": 12,
      "recent_runs": [
        {
          "id": "uuid",
          "trigger": "cron",
          "started_at": "2026-02-15T02:00:00Z",
          "completed_at": "2026-02-15T02:05:00Z",
          "status": "completed",
          "pages": { "total": 5, "success": 4, "failed": 1, "pending": 0, "skipped": 0 },
          "tokens_used": 12500
        }
      ],
      "recent_page_changes": [
        {
          "id": "uuid",
          "page_id": "uuid",
          "field": "meta_description",
          "old_value": "Old description...",
          "new_value": "Improved description...",
          "reason": "Better keyword targeting",
          "status": "applied",
          "confidence": 0.85,
          "tokens_used": 2500,
          "created_at": "2026-02-15T02:01:00Z"
        }
      ]
    },
    "auto_pages": {
      "total_auto_pages": 5,
      "total_views": 230,
      "pages": [
        {
          "id": "uuid",
          "path": "/about",
          "title": "About Example Inc",
          "status": "published",
          "slot": 1,
          "views": 85,
          "last_refreshed": "2026-02-15T00:00:00Z",
          "next_refresh": "2026-02-22T00:00:00Z"
        }
      ]
    }
  }
}

Usage & Quota

Check your current API key's usage and remaining quota. This endpoint is free — it does not count against any rate limit.

GET/api/v1/usagescope: read

Returns today's usage counts per category (read/write/auto) and remaining limits for the authenticated API key.

Response 200 OK

json

{
  "data": {
    "today": { "read": 45, "write": 12, "auto": 3 },
    "limits": { "read": 200, "write": 50, "auto": 10 },
    "remaining": { "read": 155, "write": 38, "auto": 7 },
    "resets_at": "2026-02-18T00:00:00Z",
    "plan": "pro"
  }
}

Rate Limiting

API usage is metered per key with category-based daily quotas and burst-protection windows. Read operations (cheap) have generous limits, while write and AI generation operations are more restricted.

Daily Quotas by Category

Category	Pro	Enterprise	Endpoints
Read	200 / day	2,000 / day	All GET endpoints (brief, score, analytics, pages, etc.)
Write	50 / day	500 / day	POST/PUT/DELETE pages, POST auto-optimize
Auto	10 / day	100 / day	POST auto-generate (AI content generation)

Burst Protection

Window	Pro	Enterprise
Per minute	30 rpm	60 rpm

Rate limit headers are included on every response:

http

X-RateLimit-Limit: 200
X-RateLimit-Remaining: 155
X-RateLimit-Reset: 2026-02-18T00:00:00Z
X-RateLimit-Window: day
X-RateLimit-Category: read
X-Request-Id: 550e8400-e29b-41d4-a716-446655440000

When a limit is exceeded, the API returns 429 Too Many Requests with detailed information about which category was exceeded and when you can retry.

Idempotency

For POST, PUT, and DELETE requests, you can send an Idempotency-Key header to prevent duplicate operations. If the same key is sent again within 24 hours, the cached response is returned instead of re-executing.

bash

curl -X POST https://nexting.ai/api/v1/sites/example.com/pages \
  -H "Authorization: Bearer nxt_your_key" \
  -H "Idempotency-Key: unique-request-id-123" \
  -H "Content-Type: application/json" \
  -d '{"path": "/blog/new-post", "title": "New Post", "content": "<p>...</p>"}'

Fail-Open Policy

If the rate limiting system encounters an internal error, requests are allowed through rather than blocked. Legitimate traffic is never dropped due to infrastructure issues.

CORS

All /api/v1/sites/ endpoints include CORS headers for cross-origin access:

http

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type, Idempotency-Key
Access-Control-Max-Age: 86400

Preflight OPTIONS requests return 204 No Content with these headers.

Error Handling

All errors follow a consistent format:

json

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "details": {},
    "timestamp": "2026-02-15T10:30:00Z"
  }
}

Error Codes

Code	Status	Description
`MISSING_API_KEY`	401	No Authorization: Bearer header
`INVALID_API_KEY`	401	Key doesn't exist, is revoked, or expired
`INSUFFICIENT_SCOPE`	403	Key lacks the required scope
`PRO_FEATURE_REQUIRED`	403	Subscription doesn't include API access
`DOMAIN_MISMATCH`	403	Key's project domain doesn't match {domain}
`RATE_LIMIT_EXCEEDED`	429	Rate limit exceeded
`VALIDATION_ERROR`	400	Missing or invalid request body fields
`INVALID_JSON`	400	Request body is not valid JSON
`NOT_FOUND`	404	Page or resource not found
`DUPLICATE_PATH`	409	A page with this path already exists
`AUTO_PAGE_READONLY`	403	Auto pages cannot be edited or deleted via API
`NOT_OWN_SITE`	403	Operation only available for sites you own
`QUOTA_EXCEEDED`	403	Plan limit reached (e.g., max auto pages)
`AUTO_OPTIMIZE_DISABLED`	503	Auto-optimization is disabled by the platform
`GENERATION_FAILED`	500	AI content generation returned no results
`DB_ERROR`	500	Internal database error

Code Examples

Python

nexting_example.py

import requests

API_KEY = "nxt_your_api_key_here"
BASE = "https://nexting.ai/api/v1"
DOMAIN = "example.com"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

# List published pages
pages = requests.get(
    f"{BASE}/sites/{DOMAIN}/pages?status=published",
    headers=headers,
)
print(f"{pages.json()['meta']['total']} pages found")

# Create a new page
new_page = requests.post(
    f"{BASE}/sites/{DOMAIN}/pages",
    headers=headers,
    json={
        "path": "/guides/getting-started",
        "title": "Getting Started Guide",
        "content": "<h2>Welcome</h2><p>Your guide starts here.</p>",
        "meta_description": "A beginner's guide.",
        "status": "published",
    },
)
print(new_page.json())

TypeScript / Node.js

nexting_example.ts

const API_KEY = "nxt_your_api_key_here";
const BASE = "https://nexting.ai/api/v1";
const DOMAIN = "example.com";

// List pages
const res = await fetch(
  `${BASE}/sites/${DOMAIN}/pages?status=published`,
  { headers: { Authorization: `Bearer ${API_KEY}` } },
);
const { data, meta } = await res.json();
console.log(`${meta.total} pages found`);

// Create a page
const created = await fetch(`${BASE}/sites/${DOMAIN}/pages`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    path: "/resources/faq",
    title: "Frequently Asked Questions",
    content: "<h2>FAQ</h2><p>...</p>",
    status: "draft",
  }),
});
console.log(await created.json());

Roadmap

The Agent API is being built in phases. Phase 0 (Foundation) is live.

Phase 0: FoundationLive

✓API key generation and authentication
✓Rate limiting (minute / hour / day)
✓Key management endpoints
✓Pages API (list & create)
✓CORS support and usage logging

Phase 1: Intelligence LayerLive

✓GET /sites/{domain}/analyze — full site analysis
✓GET /sites/{domain}/score — AI visibility score
✓GET /sites/{domain}/opportunities — keyword gaps
✓GET /sites/{domain}/competitors — competitor intel

Phase 2: Full PublishingLive

✓GET /sites/{domain}/pages/{pageId} — get page details
✓PUT /sites/{domain}/pages/{pageId} — update page with re-render
✓DELETE /sites/{domain}/pages/{pageId} — delete page

Phase 3: AutomationLive

✓GET/POST /sites/{domain}/auto-optimize — auto-optimization control
✓GET/POST /sites/{domain}/pages/auto-generate — AI content generation
✓GET /sites/{domain}/reports — optimization reports

Phase 4: EcosystemPlanned

○MCP server (npm package)
○Webhook notifications
○Python & TypeScript SDKs

Agent API Reference

Quick Start

Create an API Key

Make Your First Request

Create a Page

Base URL

Authentication

API Key Properties

Scopes

Key Management

Response 200 OK

Parameters

Request Body

Response 201 Created

Request Body

Response 200 OK

Agent Brief

Parameters

Response 200 OK

Pages API

Parameters

Response 200 OK

Parameters

Request Body

Response 201 Created

Response 200 OK

Parameters

Request Body

Response 200 OK

Response 200 OK

Intelligence API

Response 200 OK

Response 200 OK

Parameters

Response 200 OK

Response 200 OK

Analytics API

Parameters

Response 200 OK

Parameters

Response 200 OK

Automation API

Response 200 OK

Parameters

Request Body

Response 200 OK

Response 200 OK

Parameters

Request Body

Response 201 Created

Parameters

Response 200 OK

Usage & Quota

Response 200 OK

Rate Limiting

Daily Quotas by Category

Burst Protection

Idempotency

CORS

Error Handling

Error Codes

Code Examples

Python

TypeScript / Node.js

Roadmap

Related Docs