Case Studies API¶

Generate, manage, and export AWS Partner Central case studies. AI-enhanced content maps 1:1 to Partner Central submission fields.

Base URL: https://api.vell.ai/api/v1 Authentication: Bearer token (OAuth) Prefix: /partners/case-studies

Agentic Workflow¶

The Case Study API is designed for end-to-end autonomous workflows:

1. GET  /schema          → Discover field schema and constraints
2. POST /generate        → AI generates full case study from inputs
3. POST /{id}/suggest    → Refine individual fields with AI
4. PATCH /{id}           → Save edits
5. GET  /{id}/export     → Export for Partner Central submission

Endpoints¶

List Case Studies¶

GET /partners/case-studies

Parameter	Type	Required	Default	Description
`status`	string	No	—	Filter: `draft`, `submitted`, `validated`
`is_public`	boolean	No	—	Filter by public/private
`page`	integer	No	`1`	Page number
`per_page`	integer	No	`20`	Items per page (max: 100)

Response:

{
  "data": [
    {
      "type": "case_study",
      "id": 42,
      "attributes": {
        "company_name": "Acme Corp",
        "case_study_title": "Acme Corp Achieves 42% Cost Reduction with Amazon ECS",
        "short_description": "Acme Corp migrated to containerized microservices...",
        "status": "draft",
        "is_public": false,
        "country": "United States",
        "industry_verticals": ["Enterprise IT"],
        "use_cases": ["Migration", "Modernization"],
        "start_date": "2025-06-01",
        "end_date": "2025-12-15",
        "has_generated_content": true,
        "created_at": "2026-03-10T14:30:00Z",
        "updated_at": "2026-03-12T09:15:00Z"
      },
      "links": {
        "self": "/api/v1/partners/case-studies/42",
        "export": "/api/v1/partners/case-studies/42/export",
        "suggest": "/api/v1/partners/case-studies/42/suggest"
      }
    }
  ],
  "meta": {
    "total": 8,
    "page": 1,
    "per_page": 20,
    "total_pages": 1
  },
  "links": {
    "first": "/api/v1/partners/case-studies?page=1&per_page=20",
    "last": "/api/v1/partners/case-studies?page=1&per_page=20",
    "prev": null,
    "next": null
  }
}

Create Case Study Draft¶

Create a case study without AI generation. Use this when you want to build up inputs incrementally before generating.

POST /partners/case-studies

Request Body:

{
  "company_name": "Acme Corp",
  "problem_statement": "Legacy monolith couldn't scale beyond 500 concurrent users",
  "proposed_solution": "Containerized microservices on Amazon ECS with Aurora Serverless",
  "outcomes": "42% cost reduction, 99.95% uptime, 3x throughput",
  "country": "United States",
  "start_date": "2025-06-01",
  "end_date": "2025-12-15",
  "industry_verticals": ["Enterprise IT"],
  "use_cases": ["Migration", "Modernization"],
  "aws_services_used": "Amazon ECS, Amazon Aurora Serverless v2, Amazon CloudWatch",
  "is_public": false
}

Field	Type	Required	Description
`company_name`	string	Yes	Customer company name
`problem_statement`	string	Yes	Business problem description
`proposed_solution`	string	Yes	Solution approach
`outcomes`	string	Yes	Business outcomes achieved
`country`	string	Yes	Engagement country
`start_date`	date	Yes	Project start date
`end_date`	date	Yes	Project end date (>= start_date)
`industry_verticals`	array	No	AWS Partner Central industry categories
`use_cases`	array	No	AWS Partner Central use case categories
`tco_analysis`	string	No	Total Cost of Ownership notes
`lessons_learned`	string	No	Key lessons
`aws_services_used`	string	No	AWS services used
`isv_tools`	string	No	ISV tools and technology
`is_public`	boolean	No	Public-facing or internal (default: false)

Response: 201 Created with full case study resource.

Get Case Study¶

GET /partners/case-studies/{id}

Returns the full case study including original inputs and generated content.

Response:

{
  "data": {
    "type": "case_study",
    "id": 42,
    "attributes": {
      "company_name": "Acme Corp",
      "case_study_title": "Acme Corp Achieves 42% Cost Reduction with Amazon ECS",
      "status": "draft",
      "problem_statement": "Legacy monolith couldn't scale...",
      "proposed_solution": "Containerized microservices on Amazon ECS...",
      "outcomes": "42% cost reduction, 99.95% uptime...",
      "aws_services_used": "Amazon ECS, Amazon Aurora Serverless v2",
      "generated_content": {
        "case_study_title": "Acme Corp Achieves 42% Cost Reduction...",
        "short_description": "Acme Corp migrated from a monolithic...",
        "problem_statement_enhanced": "Acme Corp, a mid-market SaaS provider...",
        "proposed_solution_enhanced": "The solution leveraged Amazon ECS...",
        "outcomes_enhanced": "**42% infrastructure cost reduction**...",
        "tco_analysis_enhanced": "Three-year TCO comparison shows...",
        "lessons_learned_enhanced": "**Start with the data layer**...",
        "architecture_diagram_suggestions": ["Amazon API Gateway → AWS Lambda..."],
        "aws_services_recommendations": ["Amazon Aurora Serverless v2 — chosen for..."],
        "validation_tips": ["Prepare CloudWatch dashboard screenshots..."]
      }
    },
    "links": {
      "self": "/api/v1/partners/case-studies/42",
      "export": "/api/v1/partners/case-studies/42/export",
      "suggest": "/api/v1/partners/case-studies/42/suggest"
    }
  }
}

Update Case Study¶

PATCH /partners/case-studies/{id}

Update any combination of input fields, generated content, or status. Supports partial updates.

Request Body (example — update generated content):

{
  "generated_content": {
    "case_study_title": "Acme Corp Cuts Costs 42% with Amazon ECS Migration",
    "short_description": "Acme Corp reduced infrastructure costs by 42%...",
    "problem_statement_enhanced": "Updated problem statement...",
    "proposed_solution_enhanced": "Updated solution...",
    "outcomes_enhanced": "Updated outcomes..."
  }
}

Request Body (example — transition status):

{
  "status": "submitted"
}

Character Limits

case_study_title: max 80 characters (AWS Partner Central constraint)
short_description: max 300 characters (AWS Partner Central constraint)

Delete Case Study¶

DELETE /partners/case-studies/{id}

Response: 204 No Content

Generate Case Study (AI)¶

Generate a full case study with AI-enhanced content. Creates a new case study and returns it with all generated fields populated.

POST /partners/case-studies/generate

Request Body:

{
  "company_name": "Acme Corp",
  "problem_statement": "Legacy Java monolith on self-managed EC2, couldn't scale beyond 500 concurrent users, 97.8% uptime",
  "proposed_solution": "Migrated to containerized microservices on ECS with Aurora Serverless for database",
  "outcomes": "42% cost reduction, 99.95% uptime, API latency from 1.2s to 180ms",
  "country": "United States",
  "start_date": "2025-06-01",
  "end_date": "2025-12-15",
  "industry_verticals": ["Enterprise IT"],
  "use_cases": ["Migration", "Modernization"],
  "aws_services_used": "Amazon ECS, Amazon Aurora Serverless v2, Amazon CloudWatch, AWS CloudFormation",
  "is_public": false,
  "brand_voice_company_id": 5,
  "kb_ids": [12, 15],
  "additional_context": "Customer is an AWS Advanced Partner with SaaS competency"
}

Additional optional fields for context enhancement:

Field	Type	Description
`brand_voice_company_id`	integer	Company ID for brand voice context
`brand_voice_product_id`	integer	Product ID for solution-specific voice
`kb_ids`	array of integers	Knowledge base IDs to query for context
`additional_context`	string	Free-form additional context for the AI

Response: 201 Created with full case study resource including generated_content.

The AI generates content that meets AWS Bar Raiser quality standards:

Specific metrics with before/after comparisons
Official AWS service names with business rationale
Well-Architected Framework alignment
Professional tone (no marketing superlatives)

Suggest Field Content (AI)¶

Generate an AI suggestion for a specific field of an existing case study. Supports iterative refinement.

POST /partners/case-studies/{id}/suggest

Request Body:

{
  "field": "problem_statement",
  "mode": "replace",
  "brand_voice_company_id": 5,
  "kb_ids": [12]
}

Field	Type	Required	Description
`field`	string	Yes	Field to generate: `problem_statement`, `proposed_solution`, `outcomes`, `tco_analysis`, `lessons_learned`
`mode`	string	No	`replace` (default), `append`, or `refine`
`brand_voice_company_id`	integer	No	Company ID for brand context
`brand_voice_product_id`	integer	No	Product ID for solution context
`kb_ids`	array	No	Knowledge base IDs for additional context

Response:

{
  "data": {
    "type": "case_study_suggestion",
    "attributes": {
      "field": "problem_statement",
      "mode": "replace",
      "suggestion": "Acme Corp, a mid-market SaaS provider serving 2,000+ enterprise clients...",
      "case_study_id": 42
    }
  },
  "links": {
    "case_study": "/api/v1/partners/case-studies/42"
  }
}

Workflow Pattern

Use suggest iteratively to refine each field, then PATCH to save the content you approve.

Export Case Study¶

Export a case study in a portable format designed for direct AWS Partner Central submission.

GET /partners/case-studies/{id}/export

Response:

{
  "data": {
    "type": "case_study_export",
    "id": 42,
    "schema_version": "1.0",
    "export_format": "aws_partner_central",
    "exported_at": "2026-03-13T10:30:00Z",

    "partner_central_fields": {
      "case_study_title": "Acme Corp Achieves 42% Cost Reduction with Amazon ECS",
      "short_description": "Acme Corp reduced infrastructure costs by 42%...",
      "customer_company_name": "Acme Corp",
      "country": "United States",
      "industry_verticals": ["Enterprise IT"],
      "use_cases": ["Migration", "Modernization"],
      "start_date": "2025-06-01",
      "end_date": "2025-12-15",
      "is_public": false,
      "problem_statement": "Acme Corp, a mid-market SaaS provider...",
      "proposed_solution": "The solution leveraged Amazon ECS...",
      "outcomes": "**42% infrastructure cost reduction**...",
      "tco_analysis": "Three-year TCO comparison shows...",
      "lessons_learned": "**Start with the data layer**...",
      "aws_services_used": "Amazon ECS, Amazon Aurora Serverless v2",
      "isv_tools": null
    },

    "supplementary": {
      "architecture_diagram_suggestions": ["Amazon API Gateway → AWS Lambda..."],
      "aws_services_recommendations": ["Amazon Aurora Serverless v2 — chosen for..."],
      "validation_tips": ["Prepare CloudWatch dashboard screenshots..."]
    },

    "original_inputs": {
      "company_name": "Acme Corp",
      "country": "United States",
      "start_date": "2025-06-01",
      "end_date": "2025-12-15"
    },

    "metadata": {
      "status": "draft",
      "created_at": "2026-03-10T14:30:00Z",
      "updated_at": "2026-03-12T09:15:00Z",
      "submitted_at": null,
      "title_char_count": 58,
      "description_char_count": 187
    }
  },
  "links": {
    "self": "/api/v1/partners/case-studies/42/export",
    "case_study": "/api/v1/partners/case-studies/42",
    "schema": "/api/v1/partners/case-studies/schema"
  }
}

The partner_central_fields object maps directly to the AWS Partner Central case study submission form. Use AI-enhanced content when available, falling back to original inputs.

Get JSON Schema¶

Returns the JSON Schema definition for case study data. Use this for input validation and MCP client discovery.

GET /partners/case-studies/schema

Response:

{
  "data": {
    "type": "json_schema",
    "id": "partner_central_case_study",
    "schema_version": "1.0",
    "attributes": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "title": "AWS Partner Central Case Study",
      "properties": {
        "case_study_title": {
          "type": "string",
          "maxLength": 80
        },
        "short_description": {
          "type": "string",
          "maxLength": 300
        }
      },
      "required": ["case_study_title", "short_description", "customer_company_name", "..."]
    }
  },
  "meta": {
    "industry_verticals": ["Digital Marketing", "Education", "Financial Services", "..."],
    "use_cases": ["Analytics", "Artificial Intelligence", "Migration", "..."],
    "countries": ["United States", "United Kingdom", "Germany", "..."],
    "statuses": ["draft", "submitted", "validated"]
  },
  "links": {
    "case_studies": "/api/v1/partners/case-studies",
    "generate": "/api/v1/partners/case-studies/generate"
  }
}

Get Filters¶

Returns available enum values for filtering and form population.

GET /partners/case-studies/filters

Response:

{
  "industry_verticals": ["Digital Marketing", "Education", "Enterprise IT", "..."],
  "use_cases": ["Analytics", "Artificial Intelligence", "Big Data", "..."],
  "countries": ["United States", "United Kingdom", "Germany", "..."],
  "statuses": ["draft", "submitted", "validated"]
}

Error Codes¶

Code	HTTP Status	Description
`VALIDATION_ERROR`	422	Invalid request parameters
`CASE_STUDY_NOT_FOUND`	404	Case study does not exist or not owned by user
`GENERATION_FAILED`	500	AI generation encountered an error
`SUGGESTION_FAILED`	500	Field suggestion generation failed
`CREATION_FAILED`	500	Database insert failed

Portability¶

This API is designed for maximum portability:

Partner Central submission: The /export endpoint returns fields mapped 1:1 to the Partner Central form
MCP/Agent discovery: The /schema endpoint returns a JSON Schema for automated validation
CRM integration: Standard JSON:API-like responses work with any HTTP client
Workflow automation: The full create → generate → refine → export pipeline is programmatic

See PARTNER_OUTPUT_PORTABILITY_AUDIT.md for the full portability assessment.