---
title: "Expand Constraint Choices Endpoint"
method: POST
path: "/v1/constraints/expand"
tags: ["constraints"]
---

# Expand Constraint Choices Endpoint

`POST /v1/constraints/expand`

## Request

- Base URL: `https://api.pioneer.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.pioneer.ai/v1/constraints/expand`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/pioneer/apis/brain-api/docs/v1/constraints/expand/post.ts> (a function with typed inputs; its response is checked against the schema)

Expand the choice list for a single constraint.

Args:
    request: Constraint to expand, target count, and task description.
    auth: Authenticated caller.

Returns:
    The updated constraint with its expanded choices and token usage.

Raises:
    HTTPException: 503 for transient upstream failures, 500 otherwise.

## Request body

- ExpandConstraintChoicesRequest: Expand constraint choices request
  - `user_id` string, nullable: User ID (optional, uses authenticated user if not provided)
  - `constraint` ConstraintRequest, required: Constraint request model
    - `description` string, required: Constraint description
    - `choices` string[], nullable: Optional list of choices for this constraint
    - `weights` number[], nullable: Optional weights for choices (must align with choices length)
    - `probability` number, nullable: Optional probability (0.0-1.0) for this constraint
  - `task_description` string, required: Task description for context
  - `max_count` integer: Maximum number of choices after expansion

## Response `200`

Successful Response

- ExpandConstraintChoicesResponse: Expand constraint choices response
  - `success` boolean, required
  - `constraint` ConstraintRequest, required: Constraint request model
    - `description` string, required: Constraint description
    - `choices` string[], nullable: Optional list of choices for this constraint
    - `weights` number[], nullable: Optional weights for choices (must align with choices length)
    - `probability` number, nullable: Optional probability (0.0-1.0) for this constraint
  - `expanded_choices` string[], required
  - `count` integer, required
  - `token_usage` integer, nullable: Estimated tokens used for expansion

## Other responses

- `422`: Validation Error

## Changes

- **2026-09-24** `0e5e86e2bae5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/pioneer/apis/brain-api/changes/v1/constraints/expand/post.md)

---

[API](https://skmtc.dev/pioneer/apis/brain-api.md) - [All operations](https://skmtc.dev/pioneer/apis/brain-api/llms.txt) - [OpenAPI document](https://skmtc.dev/pioneer/apis/brain-api/revisions/0e5e86e2bae5?raw)