get-ai-suggestions

Use speakeasy suggest for AI-powered spec improvements.

When to Use

• Want AI-generated suggestions for operation IDs or error types
• Looking to improve spec quality automatically
• User says: "suggest improvements", "AI suggestions", "better operation names"

Inputs

Input	Required	Description
OpenAPI spec	Yes	Spec to analyze (-s)
Authentication	Yes	Via speakeasy auth login or SPEAKEASY_API_KEY env var

Outputs

Output	Description
Suggestions	Printed to console or overlay file (-o)
Overlay file	Optional: saves suggestions as overlay

Prerequisites

For non-interactive environments (CI/CD, AI agents), set:

export SPEAKEASY_API_KEY="<your-api-key>"

See configure-authentication skill for details.

Commands

# Suggest better operation IDs (method names)
speakeasy suggest operation-ids -s <spec-path>

# Suggest error type definitions
speakeasy suggest error-types -s <spec-path>

# Output suggestions as overlay file
speakeasy suggest operation-ids -s <spec-path> -o suggested-overlay.yaml

Operation ID Suggestions

Transforms auto-generated names into intuitive SDK method names:

• get_api_v1_users_list → listUsers
• post_api_v1_users_create → createUser

Error Type Suggestions

Analyzes your API and suggests structured error responses:

• Common HTTP error codes (400, 401, 404, 500)
• Custom error schemas

Applying Suggestions

# Generate overlay with suggestions
speakeasy suggest operation-ids -s openapi.yaml -o operation-ids-overlay.yaml

# Add to workflow.yaml
sources:
  my-api:
    inputs:
      - location: ./openapi.yaml
    overlays:
      - location: ./operation-ids-overlay.yaml

# Regenerate
speakeasy run --output console

Troubleshooting

Error	Cause	Solution
"unauthorized"	Missing API key	Set SPEAKEASY_API_KEY env var
No suggestions	Spec already well-named	No action needed
Timeout	Large spec	Try smaller sections or wait longer

Related Skills

• improve-operation-ids - Detailed guidance on SDK method naming
• create-openapi-overlay - Create custom overlays beyond suggestions
• fix-validation-errors-with-overlays - Use suggestions to fix lint errors
• regenerate-sdk - Apply suggestions and regenerate