---
title: "Submit SEO recommendations"
method: POST
path: "/api/v1/seo/recommendations"
tags: ["SEO Recommendations"]
---

# Submit SEO recommendations

`POST /api/v1/seo/recommendations`

## Request

- Base URL: `https://api.athenahq.ai`
- URL: `https://api.athenahq.ai/api/v1/seo/recommendations`
- Auth: API key in header `x-api-key`

Submit one draft or public HTTPS page for asynchronous SEO and AI-search recommendations. The website's organization must have the seo_recommendations entitlement in Autumn, and the caller must have website content administration access. Missing entitlement returns 403; an unavailable entitlement check returns 500 without creating a job. Queued work is checked again before analysis. Reuse request_id with identical input for retries; changed input returns 409. A website may have 1,000 outstanding jobs, with up to four active analyses and 16 across all websites. The website submit ceiling is 120 requests/minute, subject to the organization-wide API budget (default 60 requests/minute shared by submissions, polling and other API calls). Honor Retry-After on 429. Pace submissions and reserve request budget for polling a bounded subset of jobs; do not poll an entire backlog every poll_after_seconds. Polling never starts another analysis.

## Request body

- object
  - `website_id` string, required
  - `request_id` string, required
  - `source` union, required
    - object
      - `kind` 'draft', required
      - `title` string, required
      - `meta_description` string, required
      - `markdown` string, required
    - object
      - `kind` 'url', required
      - `url` string, required
  - `target_queries` string[]
  - `locale` string
  - `local_context` string

## Response `202`

Success

- object
  - `job_id` string, required
  - `status` 'pending' | 'running' | 'completed' | 'failed', required
  - `contract_version` 'seo-recommendations/v1', required
  - `poll_after_seconds` integer, required

## Other responses

- `400`: Bad Request: validation failed
- `401`: Unauthenticated
- `403`: Forbidden
- `404`: Not Found
- `409`: Conflict
- `429`: Rate limited: honor Retry-After before retrying with the same request ID
- `500`: Internal Error

## Changes

- **2026-11-03** `2d1d86d5e067`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/athenahq/apis/athenahq-api/changes/api/v1/seo/recommendations/post.md)

---

[API](https://skmtc.dev/athenahq/apis/athenahq-api.md) - [All operations](https://skmtc.dev/athenahq/apis/athenahq-api/llms.txt) - [OpenAPI document](https://skmtc.dev/athenahq/apis/athenahq-api/revisions/6cf9ca58edf6?raw)