Shopify AEO
Answer Engine Optimization for Shopify content
Start async AEO analysis job for Shopify resource(s)
/shopify/aeo/analyzeThis endpoint creates an async job and returns immediately with 202 Accepted. Use the returned job_id to poll for progress and fetch results when complete.
Analyzes one or more Shopify resources (product, collection, page, or blog post) in the background. Converts resources to semantic HTML and delegates to the core AEO analyzer.
Single resource mode (application/json): Provide a single JSON object with resource_type and resource_id. Bulk mode (application/x-ndjson): Provide newline-delimited JSON with one resource per line. Each line should be a JSON object with resource_type and resource_id.
Idempotency: Only one analysis job can be active per shop at a time. If a job is already running or pending, this endpoint returns the existing job.
Example NDJSON:
{"resource_type":"product","resource_id":"123"}
{"resource_type":"product","resource_id":"456"}
v1 Limitation: Only supports resourceType='product'. Other resource types will return a 400 Bad Request error.
Authentication: Requires Shopify session token via Authorization header. The shop domain is extracted from the session token's 'dest' claim.
Authentication required: shopifySessionToken
Request Body
Example:
{
"resource_type": "product",
"resource_id": "123456789"
}
Code Examples
curl -X POST "https://searchaf.antfly.io/api/v1/shopify/aeo/analyze" \\
-H "Authorization: Bearer YOUR_API_KEY" \\
-H "Content-Type: application/json" \\
-d '{
"resource_type": "product",
"resource_id": "123456789"
}'Responses
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"organization_id": "550e8400-e29b-41d4-a716-446655440000",
"project_id": "550e8400-e29b-41d4-a716-446655440000",
"shop_id": "550e8400-e29b-41d4-a716-446655440000",
"resource_type": "product",
"resource_ids": [
"string"
],
"status": "pending",
"progress_percent": 0,
"total_items": 0,
"completed_items": 0,
"error_message": "string",
"started_at": "2025-10-02T15:30:00Z",
"completed_at": "2025-10-02T15:30:00Z",
"created_at": "2025-10-02T15:30:00Z",
"updated_at": "2025-10-02T15:30:00Z"
}Get AEO analysis history
/shopify/aeo/analyzeRetrieves all AEO analyses for the authenticated shop's resources. Returns historical analysis reports ordered by most recent first.
Authentication: Requires Shopify session token via Authorization header. The shop domain is extracted from the session token's 'dest' claim.
Authentication required: shopifySessionToken
Parameters
| Name | Type | Location | Required | Description |
|---|---|---|---|---|
resource_type | string (product, collection, page, blog_post) | query | No | Filter by resource type (optional) |
resource_id | string | query | No | Filter by specific resource ID (optional) |
limit | integer | query | No | Maximum number of results to return |
offset | integer | query | No | Number of results to skip for pagination |
Code Examples
curl -X GET "https://searchaf.antfly.io/api/v1/shopify/aeo/analyze?resource_type=value&resource_id=value&limit=value&offset=value" \\
-H "Authorization: Bearer YOUR_API_KEY"Responses
[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"score": {
"value": 75,
"grade": "excellent"
},
"summary": {
"total_issues": 0,
"critical_count": 0,
"warning_count": 0,
"info_count": 0
},
"suggestions": [
{
"id": "STR-001",
"category": "structure",
"priority": "critical",
"title": "Missing H1 Heading",
"description": "Add a clear H1 heading that describes the main topic of the page.",
"example": "string",
"impact": "high"
}
],
"metadata": {
"source": "string",
"content_type": "html",
"analyzed_at": "2025-10-02T15:30:00Z",
"processing_time": 0,
"content_length": 0,
"additional_fields": {}
},
"created_at": "2025-10-02T15:30:00Z",
"eeat": {
"experience": {
"score": 0,
"signals": [
"string"
],
"missing": [
"string"
]
},
"expertise": {
"score": 0,
"author_info": true,
"credentials": [
"string"
],
"expert_quotes": 0,
"missing": [
"string"
]
},
"authoritativeness": {
"score": 0,
"citations": 0,
"external_links": 0,
"source_quality": "high",
"missing": [
"string"
]
},
"trustworthiness": {
"score": 0,
"contact_info": true,
"about_page": true,
"transparency_signals": [
"string"
],
"missing": [
"string"
]
},
"overall_score": 0
},
"conversational_query": {
"score": 0,
"question_answer_pairs": [
{
"question": "string",
"answer": "string",
"quality": "high"
}
],
"faq_detected": true,
"natural_language_optimization": {
"score": 0,
"conversational_tone": true,
"direct_answers": 0,
"improvements": [
"string"
]
},
"voice_search_readiness": {
"score": 0,
"featured_snippet_potential": true,
"concise_answers": 0,
"improvements": [
"string"
]
},
"missing_questions": [
"string"
]
},
"semantic_richness": {
"score": 0,
"topical_authority": {
"score": 0,
"main_topics": [
"string"
],
"subtopic_coverage": [
"string"
],
"depth": "comprehensive",
"improvements": [
"string"
]
},
"semantic_keywords": {
"score": 0,
"primary_keywords": [
"string"
],
"related_terms": [
"string"
],
"semantic_gaps": [
"string"
]
},
"content_depth": {
"score": 0,
"word_count": 0,
"reading_level": "Graduate",
"technical_depth": "expert",
"improvements": [
"string"
]
},
"entity_coverage": {
"score": 0,
"entities": [
"string"
],
"relationships": [
"string"
],
"missing": [
"string"
]
}
},
"comparisons": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Competitor Inc",
"source": "string",
"score": {
"value": 75,
"grade": "excellent"
},
"insights": {
"strength_areas": [
"Well-structured content with clear headings",
"Comprehensive FAQ section"
],
"weak_areas": [
"Title is too generic",
"Missing structured data"
],
"opportunities": [
{
"title": "Add Schema.org markup",
"description": "Quick win to improve AI comprehension",
"impact": "high",
"effort": "easy",
"priority": 1
}
],
"summary": "Competitor has strong content structure but lacks technical SEO elements"
}
}
],
"optimizations": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"analysis_id": "550e8400-e29b-41d4-a716-446655440000",
"field": "meta_description",
"optimization_type": "enhance",
"title": "Missing or Short Meta Description",
"description": "string",
"current_value": "string",
"optimized_value": "string",
"expected_score_increase": 15,
"auto_applicable": true,
"generation_style": {
"tone": "professional",
"length": "standard"
},
"confidence_score": 85,
"manually_edited": true,
"applied_at": "2025-10-02T15:30:00Z",
"created_at": "2025-10-02T15:30:00Z"
}
]
}
]Test resource visibility in AI search
/shopify/aeo/visibilityTests how visible a Shopify resource is in AI search results for given queries. Returns relevance scores and recommendations for improving visibility.
v1 Limitation: Only supports resourceType='product'. Other resource types will return a 400 Bad Request error.
Authentication: Requires Shopify session token via Authorization header. The shop domain is extracted from the session token's 'dest' claim.
Authentication required: shopifySessionToken
Request Body
Example:
{
"resource_type": "product",
"resource_id": "123456789",
"queries": [
"What is organic coffee?",
"Best coffee beans for espresso"
]
}
Code Examples
curl -X POST "https://searchaf.antfly.io/api/v1/shopify/aeo/visibility" \\
-H "Authorization: Bearer YOUR_API_KEY" \\
-H "Content-Type: application/json" \\
-d '{
"resource_type": "product",
"resource_id": "123456789",
"queries": [
"What is organic coffee?",
"Best coffee beans for espresso"
]
}'Responses
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"url": "string",
"overall_score": 0,
"queries": [
{
"query": "string",
"found": true,
"position": 0,
"relevance_score": 0,
"snippet": "string"
}
],
"recommendations": [
"string"
],
"tested_at": "2025-10-02T15:30:00Z"
}Get visibility test history
/shopify/aeo/visibilityRetrieves all visibility test results for the authenticated shop's resources. Returns historical visibility tests ordered by most recent first.
Authentication: Requires Shopify session token via Authorization header. The shop domain is extracted from the session token's 'dest' claim.
Authentication required: shopifySessionToken
Parameters
| Name | Type | Location | Required | Description |
|---|---|---|---|---|
limit | integer | query | No | Maximum number of results to return |
offset | integer | query | No | Number of results to skip for pagination |
Code Examples
curl -X GET "https://searchaf.antfly.io/api/v1/shopify/aeo/visibility?limit=value&offset=value" \\
-H "Authorization: Bearer YOUR_API_KEY"Responses
[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"url": "string",
"overall_score": 0,
"queries": [
{
"query": "string",
"found": true,
"position": 0,
"relevance_score": 0,
"snippet": "string"
}
],
"recommendations": [
"string"
],
"tested_at": "2025-10-02T15:30:00Z"
}
]Get optimizations for an analysis
/shopify/aeo/analyses/{analysis_id}/optimizationsRetrieves all AI-generated optimizations for a specific Shopify AEO analysis.
Authentication: Requires Shopify session token via Authorization header.
Authentication required: shopifySessionToken
Parameters
| Name | Type | Location | Required | Description |
|---|---|---|---|---|
analysis_id | string | path | Yes | Analysis ID |
Code Examples
curl -X GET "https://searchaf.antfly.io/api/v1/shopify/aeo/analyses/{analysis_id}/optimizations" \\
-H "Authorization: Bearer YOUR_API_KEY"Responses
[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"analysis_id": "550e8400-e29b-41d4-a716-446655440000",
"field": "meta_description",
"optimization_type": "enhance",
"title": "Missing or Short Meta Description",
"description": "string",
"current_value": "string",
"optimized_value": "string",
"expected_score_increase": 15,
"auto_applicable": true,
"generation_style": {
"tone": "professional",
"length": "standard"
},
"confidence_score": 85,
"manually_edited": true,
"applied_at": "2025-10-02T15:30:00Z",
"created_at": "2025-10-02T15:30:00Z"
}
]Start async job to generate AI-powered optimizations for an analysis
/shopify/aeo/analyses/{analysis_id}/optimizationsThis endpoint creates an async job and returns immediately with 202 Accepted. Use the returned job_id to poll for progress and fetch results when complete.
Generates or regenerates AI-powered optimizations for a Shopify AEO analysis in the background. This endpoint:
- Creates an optimization job
- Returns immediately with job information
- Background worker fetches analysis and suggestions, deletes unapplied optimizations, generates new ones
Important: Applied optimizations (applied_at IS NOT NULL) are never deleted and cannot be regenerated.
Idempotency: Only one optimization job can be active per shop at a time. If a job is already running or pending, this endpoint returns the existing job.
Authentication: Requires Shopify session token via Authorization header.
Authentication required: shopifySessionToken
Parameters
| Name | Type | Location | Required | Description |
|---|---|---|---|---|
analysis_id | string | path | Yes | Analysis ID |
Request Body
Example:
{
"optimization_ids": [
"789e4567-e89b-12d3-a456-426614174000"
],
"style_options": {
"tone": "professional",
"length": "concise"
}
}
Code Examples
curl -X POST "https://searchaf.antfly.io/api/v1/shopify/aeo/analyses/{analysis_id}/optimizations" \\
-H "Authorization: Bearer YOUR_API_KEY" \\
-H "Content-Type: application/json" \\
-d '{
"optimization_ids": [
"789e4567-e89b-12d3-a456-426614174000"
],
"style_options": {
"tone": "professional",
"length": "concise"
}
}'Responses
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"organization_id": "550e8400-e29b-41d4-a716-446655440000",
"project_id": "550e8400-e29b-41d4-a716-446655440000",
"shop_id": "550e8400-e29b-41d4-a716-446655440000",
"analysis_ids": [
"550e8400-e29b-41d4-a716-446655440000"
],
"status": "pending",
"progress_percent": 0,
"total_items": 0,
"completed_items": 0,
"error_message": "string",
"started_at": "2025-10-02T15:30:00Z",
"completed_at": "2025-10-02T15:30:00Z",
"created_at": "2025-10-02T15:30:00Z",
"updated_at": "2025-10-02T15:30:00Z"
}List optimization jobs for a specific analysis
/shopify/aeo/analyses/{analysis_id}/optimization-jobsReturns all optimization generation jobs for a specific analysis. Results are ordered by creation date (most recent first). Supports filtering by status and pagination.
Authentication: Requires Shopify session token via Authorization header.
Authentication required: shopifySessionToken
Parameters
| Name | Type | Location | Required | Description |
|---|---|---|---|---|
analysis_id | string | path | Yes | Analysis ID |
status | string | query | No | Filter by job status (optional) |
limit | integer | query | No | Maximum number of results to return |
offset | integer | query | No | Number of results to skip for pagination |
Code Examples
curl -X GET "https://searchaf.antfly.io/api/v1/shopify/aeo/analyses/{analysis_id}/optimization-jobs?status=value&limit=value&offset=value" \\
-H "Authorization: Bearer YOUR_API_KEY"Responses
[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"organization_id": "550e8400-e29b-41d4-a716-446655440000",
"project_id": "550e8400-e29b-41d4-a716-446655440000",
"shop_id": "550e8400-e29b-41d4-a716-446655440000",
"analysis_ids": [
"550e8400-e29b-41d4-a716-446655440000"
],
"status": "pending",
"progress_percent": 0,
"total_items": 0,
"completed_items": 0,
"error_message": "string",
"started_at": "2025-10-02T15:30:00Z",
"completed_at": "2025-10-02T15:30:00Z",
"created_at": "2025-10-02T15:30:00Z",
"updated_at": "2025-10-02T15:30:00Z"
}
]Manually edit an optimization
/shopify/aeo/optimizations/{optimization_id}Allows user to manually edit the optimized_value of an unapplied optimization. Sets manually_edited = true when updated.
Important: Cannot edit applied optimizations (applied_at IS NOT NULL).
Authentication: Requires Shopify session token via Authorization header.
Authentication required: shopifySessionToken
Parameters
| Name | Type | Location | Required | Description |
|---|---|---|---|---|
optimization_id | string | path | Yes | Optimization ID |
Request Body
Example:
{
"optimized_value": "Discover premium organic coffee beans - ethically sourced, expertly roasted"
}
Code Examples
curl -X PATCH "https://searchaf.antfly.io/api/v1/shopify/aeo/optimizations/{optimization_id}" \\
-H "Authorization: Bearer YOUR_API_KEY" \\
-H "Content-Type: application/json" \\
-d '{
"optimized_value": "Discover premium organic coffee beans - ethically sourced, expertly roasted"
}'Responses
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"analysis_id": "550e8400-e29b-41d4-a716-446655440000",
"field": "meta_description",
"optimization_type": "enhance",
"title": "Missing or Short Meta Description",
"description": "string",
"current_value": "string",
"optimized_value": "string",
"expected_score_increase": 15,
"auto_applicable": true,
"generation_style": {
"tone": "professional",
"length": "standard"
},
"confidence_score": 85,
"manually_edited": true,
"applied_at": "2025-10-02T15:30:00Z",
"created_at": "2025-10-02T15:30:00Z"
}List all analysis jobs for the shop
/shopify/aeo/analysis-jobsReturns all AEO analysis jobs for the authenticated shop. Results are ordered by creation date (most recent first). Supports filtering by status and pagination.
Authentication: Requires Shopify session token via Authorization header. The shop domain is extracted from the session token's 'dest' claim.
Authentication required: shopifySessionToken
Parameters
| Name | Type | Location | Required | Description |
|---|---|---|---|---|
status | string | query | No | Filter by job status (optional) |
limit | integer | query | No | Maximum number of results to return |
offset | integer | query | No | Number of results to skip for pagination |
Code Examples
curl -X GET "https://searchaf.antfly.io/api/v1/shopify/aeo/analysis-jobs?status=value&limit=value&offset=value" \\
-H "Authorization: Bearer YOUR_API_KEY"Responses
[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"organization_id": "550e8400-e29b-41d4-a716-446655440000",
"project_id": "550e8400-e29b-41d4-a716-446655440000",
"shop_id": "550e8400-e29b-41d4-a716-446655440000",
"resource_type": "product",
"resource_ids": [
"string"
],
"status": "pending",
"progress_percent": 0,
"total_items": 0,
"completed_items": 0,
"error_message": "string",
"started_at": "2025-10-02T15:30:00Z",
"completed_at": "2025-10-02T15:30:00Z",
"created_at": "2025-10-02T15:30:00Z",
"updated_at": "2025-10-02T15:30:00Z"
}
]Get analysis job status and progress
/shopify/aeo/analysis-jobs/{job_id}Returns the current status and progress of an AEO analysis job. Poll this endpoint to check job progress until status is 'completed' or 'failed'.
Authentication: Requires Shopify session token via Authorization header.
Authentication required: shopifySessionToken
Parameters
| Name | Type | Location | Required | Description |
|---|---|---|---|---|
job_id | string | path | Yes | Job ID |
Code Examples
curl -X GET "https://searchaf.antfly.io/api/v1/shopify/aeo/analysis-jobs/{job_id}" \\
-H "Authorization: Bearer YOUR_API_KEY"Responses
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"organization_id": "550e8400-e29b-41d4-a716-446655440000",
"project_id": "550e8400-e29b-41d4-a716-446655440000",
"shop_id": "550e8400-e29b-41d4-a716-446655440000",
"resource_type": "product",
"resource_ids": [
"string"
],
"status": "pending",
"progress_percent": 0,
"total_items": 0,
"completed_items": 0,
"error_message": "string",
"started_at": "2025-10-02T15:30:00Z",
"completed_at": "2025-10-02T15:30:00Z",
"created_at": "2025-10-02T15:30:00Z",
"updated_at": "2025-10-02T15:30:00Z"
}Get completed analysis results
/shopify/aeo/analysis-jobs/{job_id}/resultsReturns all analysis results for a completed job. Returns 409 Conflict if job is not yet completed.
Authentication: Requires Shopify session token via Authorization header.
Authentication required: shopifySessionToken
Parameters
| Name | Type | Location | Required | Description |
|---|---|---|---|---|
job_id | string | path | Yes | Job ID |
Code Examples
curl -X GET "https://searchaf.antfly.io/api/v1/shopify/aeo/analysis-jobs/{job_id}/results" \\
-H "Authorization: Bearer YOUR_API_KEY"Responses
[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"organization_id": "550e8400-e29b-41d4-a716-446655440000",
"project_id": "550e8400-e29b-41d4-a716-446655440000",
"shop_id": "550e8400-e29b-41d4-a716-446655440000",
"job_id": "550e8400-e29b-41d4-a716-446655440000",
"resource_type": "product",
"resource_id": "string",
"resource_title": "string",
"score": 0,
"grade": "excellent",
"total_issues": 0,
"critical_count": 0,
"warning_count": 0,
"suggestions": [
{
"id": "STR-001",
"category": "structure",
"priority": "critical",
"title": "Missing H1 Heading",
"description": "Add a clear H1 heading that describes the main topic of the page.",
"example": "string",
"impact": "high"
}
],
"resource_metadata": {},
"status": "pending",
"analyzed_at": "2025-10-02T15:30:00Z",
"created_at": "2025-10-02T15:30:00Z"
}
]List all optimization jobs for the shop
/shopify/aeo/optimization-jobsReturns all AEO optimization generation jobs for the authenticated shop. Results are ordered by creation date (most recent first). Supports filtering by status and pagination.
Authentication: Requires Shopify session token via Authorization header. The shop domain is extracted from the session token's 'dest' claim.
Authentication required: shopifySessionToken
Parameters
| Name | Type | Location | Required | Description |
|---|---|---|---|---|
status | string | query | No | Filter by job status (optional) |
limit | integer | query | No | Maximum number of results to return |
offset | integer | query | No | Number of results to skip for pagination |
Code Examples
curl -X GET "https://searchaf.antfly.io/api/v1/shopify/aeo/optimization-jobs?status=value&limit=value&offset=value" \\
-H "Authorization: Bearer YOUR_API_KEY"Responses
[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"organization_id": "550e8400-e29b-41d4-a716-446655440000",
"project_id": "550e8400-e29b-41d4-a716-446655440000",
"shop_id": "550e8400-e29b-41d4-a716-446655440000",
"analysis_ids": [
"550e8400-e29b-41d4-a716-446655440000"
],
"status": "pending",
"progress_percent": 0,
"total_items": 0,
"completed_items": 0,
"error_message": "string",
"started_at": "2025-10-02T15:30:00Z",
"completed_at": "2025-10-02T15:30:00Z",
"created_at": "2025-10-02T15:30:00Z",
"updated_at": "2025-10-02T15:30:00Z"
}
]Get optimization job status and progress
/shopify/aeo/optimization-jobs/{job_id}Returns the current status and progress of an AEO optimization generation job. Poll this endpoint to check job progress until status is 'completed' or 'failed'.
Authentication: Requires Shopify session token via Authorization header.
Authentication required: shopifySessionToken
Parameters
| Name | Type | Location | Required | Description |
|---|---|---|---|---|
job_id | string | path | Yes | Job ID |
Code Examples
curl -X GET "https://searchaf.antfly.io/api/v1/shopify/aeo/optimization-jobs/{job_id}" \\
-H "Authorization: Bearer YOUR_API_KEY"Responses
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"organization_id": "550e8400-e29b-41d4-a716-446655440000",
"project_id": "550e8400-e29b-41d4-a716-446655440000",
"shop_id": "550e8400-e29b-41d4-a716-446655440000",
"analysis_ids": [
"550e8400-e29b-41d4-a716-446655440000"
],
"status": "pending",
"progress_percent": 0,
"total_items": 0,
"completed_items": 0,
"error_message": "string",
"started_at": "2025-10-02T15:30:00Z",
"completed_at": "2025-10-02T15:30:00Z",
"created_at": "2025-10-02T15:30:00Z",
"updated_at": "2025-10-02T15:30:00Z"
}Get completed optimization results
/shopify/aeo/optimization-jobs/{job_id}/resultsReturns all optimization results for a completed job. Returns 409 Conflict if job is not yet completed.
Authentication: Requires Shopify session token via Authorization header.
Authentication required: shopifySessionToken
Parameters
| Name | Type | Location | Required | Description |
|---|---|---|---|---|
job_id | string | path | Yes | Job ID |
Code Examples
curl -X GET "https://searchaf.antfly.io/api/v1/shopify/aeo/optimization-jobs/{job_id}/results" \\
-H "Authorization: Bearer YOUR_API_KEY"Responses
[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"analysis_id": "550e8400-e29b-41d4-a716-446655440000",
"job_id": "550e8400-e29b-41d4-a716-446655440000",
"field": "string",
"optimization_type": "string",
"title": "string",
"description": "string",
"current_value": "string",
"optimized_value": "string",
"expected_score_increase": 0,
"auto_applicable": true,
"generation_style": {},
"confidence_score": 0,
"manually_edited": true,
"applied_at": "2025-10-02T15:30:00Z",
"created_at": "2025-10-02T15:30:00Z"
}
]