> For the complete documentation index, see [llms.txt](https://docs.autoenhance.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.autoenhance.ai/api/orders.md).

# Orders

## List Orders

> Lists the orders for the current user with optional search and sorting.\
> \
> Query Parameters:\
> \- q: Free-text search term applied to order name\
> \- sort: Sorting key (name, -name, date, -date). Defaults to -date (most recent first)\
> \- offset: Pagination offset token\
> \- per\_page: Number of items per page

```json
{"openapi":"3.0.3","info":{"title":"Autoenhance API","version":"2026-10-01"},"tags":[{"name":"Orders"}],"servers":[{"url":"http://api:8080"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"OrdersOut":{"additionalProperties":false,"properties":{"orders":{"items":{"$ref":"#/components/schemas/OrderOut"},"type":"array"},"pagination":{"$ref":"#/components/schemas/Pagination"}},"type":"object"},"OrderOut":{"additionalProperties":false,"properties":{"created_at":{"description":"The creation date of the order.","format":"date-time","type":"string"},"default_image_sort_order":{"description":"Default sort order for images in the order.","enum":["name","-name","date_added","-date_added","custom"]},"images":{"description":"The list of images for the order.","items":{"$ref":"#/components/schemas/ImageOut"},"type":"array"},"is_deleted":{"description":"The status of the order.","type":"boolean"},"is_merging":{"description":"The processing status for the order","type":"boolean"},"is_processing":{"description":"The processing status for the order","type":"boolean"},"last_updated_at":{"description":"The last updated date of the order.","format":"date-time","type":"string"},"name":{"description":"The name for the order.","type":"string"},"order_id":{"description":"The ID for the order.","type":"string"},"status":{"description":"The status of the order.","readOnly":true},"total_images":{"description":"Number of images in the  order.","type":"number"}},"type":"object"},"ImageOut":{"additionalProperties":false,"properties":{"ai_version":{"description":"The version of the AI model to use for enhancing the image. Versions ending in an .x will use the latest minor version as soon as it's published.","type":"string"},"cloud_type":{"description":"The type of clouds in the new sky to replace the original sky with. Options include: CLEAR, LOW_CLOUD, HIGH_CLOUD","enum":["CLEAR","LOW_CLOUD","HIGH_CLOUD",null],"nullable":true,"type":"string"},"date_added":{"description":"The date the image was registered with Autoenhance.","type":"integer"},"downloaded":{"description":"Whether image has been already downloaded and paid for.","type":"boolean"},"enhance":{"default":true,"description":"Whether to enhance the image.","type":"boolean"},"finetune_settings":{"anyOf":[{"nullable":true,"type":"object"},{"$ref":"#/components/schemas/FinetuneOptions"}]},"image_id":{"format":"uuid","type":"string"},"image_name":{"type":"string"},"lens_correction":{"default":true,"description":"Correct any lens distortion in the image.","type":"boolean"},"metadata":{"additionalProperties":{},"description":"Metadata for the image.","type":"object"},"order_id":{"readOnly":true},"parent_image_id":{"description":"The ID of the parent image if this is a sub-image created for premium restaging. Null for original images.","nullable":true,"type":"string"},"perspective_correction":{"description":"Whether perspective correction is enabled for the image.","nullable":true,"type":"boolean"},"perspective_correction_mode":{"description":"The perspective correction mode used for the image. 'OFF' means disabled, 'DEFAULT_ENABLED' uses AI defaults, 'PRESERVE_CONTENT' prioritizes keeping content, 'PRIORITIZE_PERSPECTIVE' prioritizes straight lines.","enum":["OFF","DEFAULT_ENABLED","PRESERVE_CONTENT","PRIORITIZE_PERSPECTIVE",null],"nullable":true,"type":"string"},"preset_id":{"description":"The ID of the preset that was applied to the image.","readOnly":true},"preset_version":{"description":"Preset version applied when the image was last processed with a preset.","nullable":true,"readOnly":true},"privacy":{"description":"Whether to blur any faces or license plates in the image.","nullable":true,"type":"boolean"},"rating":{"description":"A rating between 0 and 5 on how good the image enhancmeent. Higher is better.","maximum":5,"minimum":0,"type":"integer"},"restage":{"anyOf":[{"$ref":"#/components/schemas/Restage"},{"nullable":true,"type":"object"}],"description":"Restage options for in-painting or modifying scene elements. Allows correcting details like lighting a fireplace, removing fingerprints from a TV screen, or removing unwanted items like tripods."},"scene":{"description":"The detected scene of the image i.e garden, patio, kitchen, etc.","type":"string"},"sky_replacement":{"description":"Whether the sky replacement feature was enabled for the image.","type":"boolean"},"status":{"description":"The status of the order.","readOnly":true},"status_reason":{"description":"Reason for the image's current status","readOnly":true},"tripod_hide":{"description":"Whether to crop the bottom of 360-degree images to hide the tripod. Note: This performs a simple crop and does not use generative in-painting.","nullable":true,"type":"boolean"},"upscale":{"description":"Whether to upscale the image.","type":"boolean"},"user_id":{"description":"The user ID of the user who uploaded (owns) the image.","readOnly":true},"window_pull_type":{"description":"What type of window pull to apply to the image (Available since AI version >= 4.0, WITH_SKIES can only be used from AI version 5.2 or higher).","enum":["NONE","ONLY_WINDOWS","WINDOWS_WITH_SKIES",null],"nullable":true,"type":"string"}},"type":"object"},"FinetuneOptions":{"additionalProperties":false,"properties":{},"type":"object"},"Restage":{"properties":{"fire_in_fireplaces":{"description":"Controls the appearance of fireplaces. 'AS_SHOT' leaves the fireplace exactly as captured (e.g., unlit). 'ALIGHT' in-paints fire into the fireplace to make it appear active.","enum":["AS_SHOT","ALIGHT",null],"nullable":true,"type":"string"},"grass":{"description":"Controls grass appearance enhancement. 'AS_SHOT' leaves the grass exactly as captured. 'GREEN' applies grass greening to make brown/dead grass appear lush and green.","enum":["AS_SHOT","GREEN",null],"nullable":true,"type":"string"},"photographer":{"description":"Controls removal of photographer. 'AS_SHOT' leaves the photographer exactly as captured. 'REMOVE' removes the photographer including their shadow, reflection and hands.","enum":["AS_SHOT","REMOVE",null],"nullable":true,"type":"string"},"sky":{"description":"Controls sky replacement. 'AS_SHOT' keeps the original sky (no replacement). Any cloud type value replaces the sky with that cloud type. Cloud type options include: AS_SHOT, CLEAR, LOW_CLOUD, HIGH_CLOUD.","enum":["AS_SHOT","CLEAR","LOW_CLOUD","HIGH_CLOUD",null],"nullable":true,"type":"string"},"tvs":{"description":"Controls the appearance of television screens in the photo. 'AS_SHOT' leaves the TV screen exactly as captured. 'BLACK_OUT' in-paints the screen to appear completely black/off.","enum":["AS_SHOT","BLACK_OUT",null],"nullable":true,"type":"string"}},"type":"object"},"Pagination":{"additionalProperties":false,"properties":{"next_offset":{"description":"The offset token for the next page of results or null if it is the last page. Pass this to the `offset` parameter when loading the next page.","type":"string"},"per_page":{"default":5,"description":"The amount of items per page of results.","type":"integer"}},"type":"object"},"HTTPError":{"properties":{"detail":{"type":"object"},"message":{"type":"string"}},"type":"object"},"ValidationError":{"properties":{"detail":{"properties":{"<location>":{"properties":{"<field_name>":{"items":{"type":"string"},"type":"array"}},"type":"object"}},"type":"object"},"message":{"type":"string"}},"type":"object"}}},"paths":{"/v3/orders/":{"get":{"description":"Lists the orders for the current user with optional search and sorting.\n\nQuery Parameters:\n- q: Free-text search term applied to order name\n- sort: Sorting key (name, -name, date, -date). Defaults to -date (most recent first)\n- offset: Pagination offset token\n- per_page: Number of items per page","operationId":"list_orders","parameters":[{"description":"The offset token used to indicate which page of results to use.","in":"query","name":"offset","required":false,"schema":{"default":"0","type":"string"}},{"description":"The amount of items to be loaded per page of results. The final response may have a smaller number than requested if too large.","in":"query","name":"per_page","required":false,"schema":{"default":5,"maximum":15,"type":"integer"}},{"description":"Free-text search term applied to order name. If omitted or empty, no search filter is applied.","in":"query","name":"q","required":false,"schema":{"default":null,"nullable":true,"type":"string"}},{"description":"Sorting key with optional '-' prefix for descending order. Allowed values: 'name' (sort by name ascending), '-name' (sort by name descending), 'date' (sort by created_at ascending), '-date' (sort by created_at descending). If omitted or invalid, defaults to '-date' (most recent first).","in":"query","name":"sort","required":false,"schema":{"default":"-date","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrdersOut"}}},"description":"Successful response"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPError"}}},"description":"Authentication error"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"}},"summary":"List Orders","tags":["Orders"]}}}}
```

## POST /v3/orders/

> Create Order

```json
{"openapi":"3.0.3","info":{"title":"Autoenhance API","version":"2026-10-01"},"tags":[{"name":"Orders"}],"servers":[{"url":"http://api:8080"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"OrderIn":{"additionalProperties":false,"properties":{"default_image_sort_order":{"description":"Default sort order for images in the order. Prefix with '-' for descending order.","enum":["name","-name","date_added","-date_added","custom"]},"name":{"description":"The name for the order.","type":"string"},"order_id":{"description":"The ID for the order.","minLength":1,"type":"string"}},"type":"object"},"HTTPError":{"properties":{"detail":{"type":"object"},"message":{"type":"string"}},"type":"object"},"ValidationError":{"properties":{"detail":{"properties":{"<location>":{"properties":{"<field_name>":{"items":{"type":"string"},"type":"array"}},"type":"object"}},"type":"object"},"message":{"type":"string"}},"type":"object"}}},"paths":{"/v3/orders/":{"post":{"operationId":"create_order","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderIn"}}}},"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Successful response"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPError"}}},"description":"Authentication error"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"}},"summary":"Create Order","tags":["Orders"]}}}}
```

## Retrieve Order

> Retrieve a specific order. Images can be sorted using the sort\_images\_by parameter.

```json
{"openapi":"3.0.3","info":{"title":"Autoenhance API","version":"2026-10-01"},"tags":[{"name":"Orders"}],"servers":[{"url":"http://api:8080"}],"paths":{"/v3/orders/{id}":{"get":{"description":"Retrieve a specific order. Images can be sorted using the sort_images_by parameter.","operationId":"retrieve_order","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Specifies sort order for images in the order","in":"query","name":"sort_images_by","required":false,"schema":{"enum":["name","-name","date_added","-date_added","custom"]}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderOut"}}},"description":"Successful response"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPError"}}},"description":"Not found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"}},"summary":"Retrieve Order","tags":["Orders"]}}},"components":{"schemas":{"OrderOut":{"additionalProperties":false,"properties":{"created_at":{"description":"The creation date of the order.","format":"date-time","type":"string"},"default_image_sort_order":{"description":"Default sort order for images in the order.","enum":["name","-name","date_added","-date_added","custom"]},"images":{"description":"The list of images for the order.","items":{"$ref":"#/components/schemas/ImageOut"},"type":"array"},"is_deleted":{"description":"The status of the order.","type":"boolean"},"is_merging":{"description":"The processing status for the order","type":"boolean"},"is_processing":{"description":"The processing status for the order","type":"boolean"},"last_updated_at":{"description":"The last updated date of the order.","format":"date-time","type":"string"},"name":{"description":"The name for the order.","type":"string"},"order_id":{"description":"The ID for the order.","type":"string"},"status":{"description":"The status of the order.","readOnly":true},"total_images":{"description":"Number of images in the  order.","type":"number"}},"type":"object"},"ImageOut":{"additionalProperties":false,"properties":{"ai_version":{"description":"The version of the AI model to use for enhancing the image. Versions ending in an .x will use the latest minor version as soon as it's published.","type":"string"},"cloud_type":{"description":"The type of clouds in the new sky to replace the original sky with. Options include: CLEAR, LOW_CLOUD, HIGH_CLOUD","enum":["CLEAR","LOW_CLOUD","HIGH_CLOUD",null],"nullable":true,"type":"string"},"date_added":{"description":"The date the image was registered with Autoenhance.","type":"integer"},"downloaded":{"description":"Whether image has been already downloaded and paid for.","type":"boolean"},"enhance":{"default":true,"description":"Whether to enhance the image.","type":"boolean"},"finetune_settings":{"anyOf":[{"nullable":true,"type":"object"},{"$ref":"#/components/schemas/FinetuneOptions"}]},"image_id":{"format":"uuid","type":"string"},"image_name":{"type":"string"},"lens_correction":{"default":true,"description":"Correct any lens distortion in the image.","type":"boolean"},"metadata":{"additionalProperties":{},"description":"Metadata for the image.","type":"object"},"order_id":{"readOnly":true},"parent_image_id":{"description":"The ID of the parent image if this is a sub-image created for premium restaging. Null for original images.","nullable":true,"type":"string"},"perspective_correction":{"description":"Whether perspective correction is enabled for the image.","nullable":true,"type":"boolean"},"perspective_correction_mode":{"description":"The perspective correction mode used for the image. 'OFF' means disabled, 'DEFAULT_ENABLED' uses AI defaults, 'PRESERVE_CONTENT' prioritizes keeping content, 'PRIORITIZE_PERSPECTIVE' prioritizes straight lines.","enum":["OFF","DEFAULT_ENABLED","PRESERVE_CONTENT","PRIORITIZE_PERSPECTIVE",null],"nullable":true,"type":"string"},"preset_id":{"description":"The ID of the preset that was applied to the image.","readOnly":true},"preset_version":{"description":"Preset version applied when the image was last processed with a preset.","nullable":true,"readOnly":true},"privacy":{"description":"Whether to blur any faces or license plates in the image.","nullable":true,"type":"boolean"},"rating":{"description":"A rating between 0 and 5 on how good the image enhancmeent. Higher is better.","maximum":5,"minimum":0,"type":"integer"},"restage":{"anyOf":[{"$ref":"#/components/schemas/Restage"},{"nullable":true,"type":"object"}],"description":"Restage options for in-painting or modifying scene elements. Allows correcting details like lighting a fireplace, removing fingerprints from a TV screen, or removing unwanted items like tripods."},"scene":{"description":"The detected scene of the image i.e garden, patio, kitchen, etc.","type":"string"},"sky_replacement":{"description":"Whether the sky replacement feature was enabled for the image.","type":"boolean"},"status":{"description":"The status of the order.","readOnly":true},"status_reason":{"description":"Reason for the image's current status","readOnly":true},"tripod_hide":{"description":"Whether to crop the bottom of 360-degree images to hide the tripod. Note: This performs a simple crop and does not use generative in-painting.","nullable":true,"type":"boolean"},"upscale":{"description":"Whether to upscale the image.","type":"boolean"},"user_id":{"description":"The user ID of the user who uploaded (owns) the image.","readOnly":true},"window_pull_type":{"description":"What type of window pull to apply to the image (Available since AI version >= 4.0, WITH_SKIES can only be used from AI version 5.2 or higher).","enum":["NONE","ONLY_WINDOWS","WINDOWS_WITH_SKIES",null],"nullable":true,"type":"string"}},"type":"object"},"FinetuneOptions":{"additionalProperties":false,"properties":{},"type":"object"},"Restage":{"properties":{"fire_in_fireplaces":{"description":"Controls the appearance of fireplaces. 'AS_SHOT' leaves the fireplace exactly as captured (e.g., unlit). 'ALIGHT' in-paints fire into the fireplace to make it appear active.","enum":["AS_SHOT","ALIGHT",null],"nullable":true,"type":"string"},"grass":{"description":"Controls grass appearance enhancement. 'AS_SHOT' leaves the grass exactly as captured. 'GREEN' applies grass greening to make brown/dead grass appear lush and green.","enum":["AS_SHOT","GREEN",null],"nullable":true,"type":"string"},"photographer":{"description":"Controls removal of photographer. 'AS_SHOT' leaves the photographer exactly as captured. 'REMOVE' removes the photographer including their shadow, reflection and hands.","enum":["AS_SHOT","REMOVE",null],"nullable":true,"type":"string"},"sky":{"description":"Controls sky replacement. 'AS_SHOT' keeps the original sky (no replacement). Any cloud type value replaces the sky with that cloud type. Cloud type options include: AS_SHOT, CLEAR, LOW_CLOUD, HIGH_CLOUD.","enum":["AS_SHOT","CLEAR","LOW_CLOUD","HIGH_CLOUD",null],"nullable":true,"type":"string"},"tvs":{"description":"Controls the appearance of television screens in the photo. 'AS_SHOT' leaves the TV screen exactly as captured. 'BLACK_OUT' in-paints the screen to appear completely black/off.","enum":["AS_SHOT","BLACK_OUT",null],"nullable":true,"type":"string"}},"type":"object"},"HTTPError":{"properties":{"detail":{"type":"object"},"message":{"type":"string"}},"type":"object"},"ValidationError":{"properties":{"detail":{"properties":{"<location>":{"properties":{"<field_name>":{"items":{"type":"string"},"type":"array"}},"type":"object"}},"type":"object"},"message":{"type":"string"}},"type":"object"}}}}
```

## Delete Order

> Deletes the specific order.

```json
{"openapi":"3.0.3","info":{"title":"Autoenhance API","version":"2026-10-01"},"tags":[{"name":"Orders"}],"servers":[{"url":"http://api:8080"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"HTTPError":{"properties":{"detail":{"type":"object"},"message":{"type":"string"}},"type":"object"}}},"paths":{"/v3/orders/{id}":{"delete":{"description":"Deletes the specific order.","operationId":"delete_order","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"No Content"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPError"}}},"description":"Authentication error"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPError"}}},"description":"Not found"}},"summary":"Delete Order","tags":["Orders"]}}}}
```

## Update Order

> Updates the details for the specific order. Images can be sorted using the sort\_images\_by parameter.

```json
{"openapi":"3.0.3","info":{"title":"Autoenhance API","version":"2026-10-01"},"tags":[{"name":"Orders"}],"servers":[{"url":"http://api:8080"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"OrderIn":{"additionalProperties":false,"properties":{"default_image_sort_order":{"description":"Default sort order for images in the order. Prefix with '-' for descending order.","enum":["name","-name","date_added","-date_added","custom"]},"name":{"description":"The name for the order.","type":"string"},"order_id":{"description":"The ID for the order.","minLength":1,"type":"string"}},"type":"object"},"OrderOut":{"additionalProperties":false,"properties":{"created_at":{"description":"The creation date of the order.","format":"date-time","type":"string"},"default_image_sort_order":{"description":"Default sort order for images in the order.","enum":["name","-name","date_added","-date_added","custom"]},"images":{"description":"The list of images for the order.","items":{"$ref":"#/components/schemas/ImageOut"},"type":"array"},"is_deleted":{"description":"The status of the order.","type":"boolean"},"is_merging":{"description":"The processing status for the order","type":"boolean"},"is_processing":{"description":"The processing status for the order","type":"boolean"},"last_updated_at":{"description":"The last updated date of the order.","format":"date-time","type":"string"},"name":{"description":"The name for the order.","type":"string"},"order_id":{"description":"The ID for the order.","type":"string"},"status":{"description":"The status of the order.","readOnly":true},"total_images":{"description":"Number of images in the  order.","type":"number"}},"type":"object"},"ImageOut":{"additionalProperties":false,"properties":{"ai_version":{"description":"The version of the AI model to use for enhancing the image. Versions ending in an .x will use the latest minor version as soon as it's published.","type":"string"},"cloud_type":{"description":"The type of clouds in the new sky to replace the original sky with. Options include: CLEAR, LOW_CLOUD, HIGH_CLOUD","enum":["CLEAR","LOW_CLOUD","HIGH_CLOUD",null],"nullable":true,"type":"string"},"date_added":{"description":"The date the image was registered with Autoenhance.","type":"integer"},"downloaded":{"description":"Whether image has been already downloaded and paid for.","type":"boolean"},"enhance":{"default":true,"description":"Whether to enhance the image.","type":"boolean"},"finetune_settings":{"anyOf":[{"nullable":true,"type":"object"},{"$ref":"#/components/schemas/FinetuneOptions"}]},"image_id":{"format":"uuid","type":"string"},"image_name":{"type":"string"},"lens_correction":{"default":true,"description":"Correct any lens distortion in the image.","type":"boolean"},"metadata":{"additionalProperties":{},"description":"Metadata for the image.","type":"object"},"order_id":{"readOnly":true},"parent_image_id":{"description":"The ID of the parent image if this is a sub-image created for premium restaging. Null for original images.","nullable":true,"type":"string"},"perspective_correction":{"description":"Whether perspective correction is enabled for the image.","nullable":true,"type":"boolean"},"perspective_correction_mode":{"description":"The perspective correction mode used for the image. 'OFF' means disabled, 'DEFAULT_ENABLED' uses AI defaults, 'PRESERVE_CONTENT' prioritizes keeping content, 'PRIORITIZE_PERSPECTIVE' prioritizes straight lines.","enum":["OFF","DEFAULT_ENABLED","PRESERVE_CONTENT","PRIORITIZE_PERSPECTIVE",null],"nullable":true,"type":"string"},"preset_id":{"description":"The ID of the preset that was applied to the image.","readOnly":true},"preset_version":{"description":"Preset version applied when the image was last processed with a preset.","nullable":true,"readOnly":true},"privacy":{"description":"Whether to blur any faces or license plates in the image.","nullable":true,"type":"boolean"},"rating":{"description":"A rating between 0 and 5 on how good the image enhancmeent. Higher is better.","maximum":5,"minimum":0,"type":"integer"},"restage":{"anyOf":[{"$ref":"#/components/schemas/Restage"},{"nullable":true,"type":"object"}],"description":"Restage options for in-painting or modifying scene elements. Allows correcting details like lighting a fireplace, removing fingerprints from a TV screen, or removing unwanted items like tripods."},"scene":{"description":"The detected scene of the image i.e garden, patio, kitchen, etc.","type":"string"},"sky_replacement":{"description":"Whether the sky replacement feature was enabled for the image.","type":"boolean"},"status":{"description":"The status of the order.","readOnly":true},"status_reason":{"description":"Reason for the image's current status","readOnly":true},"tripod_hide":{"description":"Whether to crop the bottom of 360-degree images to hide the tripod. Note: This performs a simple crop and does not use generative in-painting.","nullable":true,"type":"boolean"},"upscale":{"description":"Whether to upscale the image.","type":"boolean"},"user_id":{"description":"The user ID of the user who uploaded (owns) the image.","readOnly":true},"window_pull_type":{"description":"What type of window pull to apply to the image (Available since AI version >= 4.0, WITH_SKIES can only be used from AI version 5.2 or higher).","enum":["NONE","ONLY_WINDOWS","WINDOWS_WITH_SKIES",null],"nullable":true,"type":"string"}},"type":"object"},"FinetuneOptions":{"additionalProperties":false,"properties":{},"type":"object"},"Restage":{"properties":{"fire_in_fireplaces":{"description":"Controls the appearance of fireplaces. 'AS_SHOT' leaves the fireplace exactly as captured (e.g., unlit). 'ALIGHT' in-paints fire into the fireplace to make it appear active.","enum":["AS_SHOT","ALIGHT",null],"nullable":true,"type":"string"},"grass":{"description":"Controls grass appearance enhancement. 'AS_SHOT' leaves the grass exactly as captured. 'GREEN' applies grass greening to make brown/dead grass appear lush and green.","enum":["AS_SHOT","GREEN",null],"nullable":true,"type":"string"},"photographer":{"description":"Controls removal of photographer. 'AS_SHOT' leaves the photographer exactly as captured. 'REMOVE' removes the photographer including their shadow, reflection and hands.","enum":["AS_SHOT","REMOVE",null],"nullable":true,"type":"string"},"sky":{"description":"Controls sky replacement. 'AS_SHOT' keeps the original sky (no replacement). Any cloud type value replaces the sky with that cloud type. Cloud type options include: AS_SHOT, CLEAR, LOW_CLOUD, HIGH_CLOUD.","enum":["AS_SHOT","CLEAR","LOW_CLOUD","HIGH_CLOUD",null],"nullable":true,"type":"string"},"tvs":{"description":"Controls the appearance of television screens in the photo. 'AS_SHOT' leaves the TV screen exactly as captured. 'BLACK_OUT' in-paints the screen to appear completely black/off.","enum":["AS_SHOT","BLACK_OUT",null],"nullable":true,"type":"string"}},"type":"object"},"HTTPError":{"properties":{"detail":{"type":"object"},"message":{"type":"string"}},"type":"object"},"ValidationError":{"properties":{"detail":{"properties":{"<location>":{"properties":{"<field_name>":{"items":{"type":"string"},"type":"array"}},"type":"object"}},"type":"object"},"message":{"type":"string"}},"type":"object"}}},"paths":{"/v3/orders/{id}":{"patch":{"description":"Updates the details for the specific order. Images can be sorted using the sort_images_by parameter.","operationId":"update_order","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Specifies sort order for images in the order","in":"query","name":"sort_images_by","required":false,"schema":{"enum":["name","-name","date_added","-date_added","custom"]}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderIn"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderOut"}}},"description":"Successful response"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPError"}}},"description":"Authentication error"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPError"}}},"description":"Not found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"}},"summary":"Update Order","tags":["Orders"]}}}}
```

## Reorder Images

> Reorders images within an order. This endpoint allows you to set custom sort order\
> for images using fractional indexing, which minimizes database updates.\
> \
> If sort\_images\_by is provided in the query data, the images will first be sorted by that field,\
> and then the custom reordering will be applied on top.\
> \
> We use fractional indexing to handle the reordering, <https://www.figma.com/blog/realtime-editing-of-ordered-sequences/>

```json
{"openapi":"3.0.3","info":{"title":"Autoenhance API","version":"2026-10-01"},"tags":[{"name":"Orders"}],"servers":[{"url":"http://api:8080"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"OrderImagesIn":{"additionalProperties":false,"properties":{"images":{"description":"The list of images to reorder.","items":{"$ref":"#/components/schemas/OrderImageIn"},"type":"array"}},"type":"object"},"OrderImageIn":{"additionalProperties":false,"properties":{"id":{"description":"The ID of the image to reorder.","type":"string"},"index":{"description":"The new index of the image to reorder.","type":"integer"}},"required":["id","index"],"type":"object"},"OrderImagesOut":{"additionalProperties":false,"properties":{"images":{"description":"The list of images for the order.","readOnly":true}},"type":"object"},"HTTPError":{"properties":{"detail":{"type":"object"},"message":{"type":"string"}},"type":"object"},"ValidationError":{"properties":{"detail":{"properties":{"<location>":{"properties":{"<field_name>":{"items":{"type":"string"},"type":"array"}},"type":"object"}},"type":"object"},"message":{"type":"string"}},"type":"object"}}},"paths":{"/v3/orders/{id}/images":{"patch":{"description":"Reorders images within an order. This endpoint allows you to set custom sort order\nfor images using fractional indexing, which minimizes database updates.\n\nIf sort_images_by is provided in the query data, the images will first be sorted by that field,\nand then the custom reordering will be applied on top.\n\nWe use fractional indexing to handle the reordering, https://www.figma.com/blog/realtime-editing-of-ordered-sequences/","operationId":"update_order_images","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Specifies sort order for images in the order","in":"query","name":"sort_images_by","required":false,"schema":{"enum":["name","-name","date_added","-date_added","custom"]}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderImagesIn"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderImagesOut"}}},"description":"Successful response"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPError"}}},"description":"Authentication error"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPError"}}},"description":"Not found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPError"}}},"description":"Conflict"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"}},"summary":"Reorder Images","tags":["Orders"]}}}}
```

## Process Order

> Triggers the grouping of any brackets contained in the order and process the final images in the order.\
> \
> TODO: Ideally we use transactions to help deal with errors but it;s a pain with MongoEngine so need to do it as part of Django or other ORM

```json
{"openapi":"3.0.3","info":{"title":"Autoenhance API","version":"2026-10-01"},"tags":[{"name":"Orders"}],"servers":[{"url":"http://api:8080"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"OrderHDRProcessIn":{"properties":{"ai_version":{"description":"The version of the AI model to use for enhancing the image. Versions ending in an .x will use the latest minor version as soon as it's published.","type":"string"},"cloud_type":{"description":"The type of clouds in the new sky to replace the original sky with. Options include: CLEAR, LOW_CLOUD, HIGH_CLOUD","enum":["CLEAR","LOW_CLOUD","HIGH_CLOUD",null],"nullable":true,"type":"string"},"enhance":{"default":true,"description":"Whether to enhance the image.","type":"boolean"},"finetune_settings":{"anyOf":[{"nullable":true,"type":"object"},{"$ref":"#/components/schemas/FinetuneOptions"}]},"images":{"items":{"$ref":"#/components/schemas/OrderHDRImageIn"},"type":"array"},"lens_correction":{"default":true,"description":"Correct any lens distortion in the image.","type":"boolean"},"number_of_brackets_per_image":{"description":"If provided then group into an image after every specified number of brackets, if  not provided or set to 0 then we automatically group based on visual analysis.","type":"integer"},"perspective_correction":{"default":true,"description":"Enable perspective correction to straighten vertical and horizontal lines in the image.","type":"boolean"},"perspective_correction_mode":{"description":"Controls how aggressively perspective correction is applied when enabled. Only used when perspective_correction is true. 'PRESERVE_CONTENT' prioritizes keeping original image contents intact with strict guardrails. 'PRIORITIZE_PERSPECTIVE' relaxes guardrails to enforce straight lines, accepting heavy cropping. If omitted, or explicitly sent as null, when perspective_correction is true, the AI uses its default behavior.","enum":["OFF","DEFAULT_ENABLED","PRESERVE_CONTENT","PRIORITIZE_PERSPECTIVE",null],"nullable":true,"type":"string"},"preset_id":{"nullable":true,"type":"string"},"privacy":{"description":"Whether to blur any faces or license plates in the image.","nullable":true,"type":"boolean"},"restage":{"anyOf":[{"$ref":"#/components/schemas/Restage"},{"nullable":true,"type":"object"}],"description":"Restage options for in-painting or modifying scene elements. Allows correcting details like lighting a fireplace, removing fingerprints from a TV screen, or removing unwanted items like tripods."},"sky_replacement":{"description":"Enable the replacement of the original sky for a summer sky.","type":"boolean"},"tripod_hide":{"description":"Whether to crop the bottom of 360-degree images to hide the tripod. Note: This performs a simple crop and does not use generative in-painting.","nullable":true,"type":"boolean"},"upscale":{"description":"Whether to upscale the image.","type":"boolean"},"window_pull_type":{"description":"What type of window pull to apply to the image (Available since AI version >= 4.0, WITH_SKIES can only be used from AI version 5.2 or higher).","enum":["NONE","ONLY_WINDOWS","WINDOWS_WITH_SKIES",null],"nullable":true,"type":"string"}},"type":"object"},"FinetuneOptions":{"additionalProperties":false,"properties":{},"type":"object"},"OrderHDRImageIn":{"additionalProperties":false,"properties":{"bracket_ids":{"items":{"type":"string"},"type":"array"}},"type":"object"},"Restage":{"properties":{"fire_in_fireplaces":{"description":"Controls the appearance of fireplaces. 'AS_SHOT' leaves the fireplace exactly as captured (e.g., unlit). 'ALIGHT' in-paints fire into the fireplace to make it appear active.","enum":["AS_SHOT","ALIGHT",null],"nullable":true,"type":"string"},"grass":{"description":"Controls grass appearance enhancement. 'AS_SHOT' leaves the grass exactly as captured. 'GREEN' applies grass greening to make brown/dead grass appear lush and green.","enum":["AS_SHOT","GREEN",null],"nullable":true,"type":"string"},"photographer":{"description":"Controls removal of photographer. 'AS_SHOT' leaves the photographer exactly as captured. 'REMOVE' removes the photographer including their shadow, reflection and hands.","enum":["AS_SHOT","REMOVE",null],"nullable":true,"type":"string"},"sky":{"description":"Controls sky replacement. 'AS_SHOT' keeps the original sky (no replacement). Any cloud type value replaces the sky with that cloud type. Cloud type options include: AS_SHOT, CLEAR, LOW_CLOUD, HIGH_CLOUD.","enum":["AS_SHOT","CLEAR","LOW_CLOUD","HIGH_CLOUD",null],"nullable":true,"type":"string"},"tvs":{"description":"Controls the appearance of television screens in the photo. 'AS_SHOT' leaves the TV screen exactly as captured. 'BLACK_OUT' in-paints the screen to appear completely black/off.","enum":["AS_SHOT","BLACK_OUT",null],"nullable":true,"type":"string"}},"type":"object"},"OrderHDRProcessOut":{"additionalProperties":false,"properties":{"created_at":{"description":"The creation date of the order.","format":"date-time","type":"string"},"default_image_sort_order":{"description":"Default sort order for images in the order.","enum":["name","-name","date_added","-date_added","custom"]},"images":{"description":"The list of images for the order.","items":{"$ref":"#/components/schemas/ImageOut"},"type":"array"},"is_deleted":{"description":"The status of the order.","type":"boolean"},"is_merging":{"description":"The processing status for the order","type":"boolean"},"is_processing":{"description":"The processing status for the order","type":"boolean"},"last_updated_at":{"description":"The last updated date of the order.","format":"date-time","type":"string"},"name":{"description":"The name for the order.","type":"string"},"order_id":{"description":"The ID for the order.","type":"string"},"status":{"description":"The status of the order.","readOnly":true},"total_images":{"description":"Number of images in the  order.","type":"number"}},"type":"object"},"ImageOut":{"additionalProperties":false,"properties":{"ai_version":{"description":"The version of the AI model to use for enhancing the image. Versions ending in an .x will use the latest minor version as soon as it's published.","type":"string"},"cloud_type":{"description":"The type of clouds in the new sky to replace the original sky with. Options include: CLEAR, LOW_CLOUD, HIGH_CLOUD","enum":["CLEAR","LOW_CLOUD","HIGH_CLOUD",null],"nullable":true,"type":"string"},"date_added":{"description":"The date the image was registered with Autoenhance.","type":"integer"},"downloaded":{"description":"Whether image has been already downloaded and paid for.","type":"boolean"},"enhance":{"default":true,"description":"Whether to enhance the image.","type":"boolean"},"finetune_settings":{"anyOf":[{"nullable":true,"type":"object"},{"$ref":"#/components/schemas/FinetuneOptions"}]},"image_id":{"format":"uuid","type":"string"},"image_name":{"type":"string"},"lens_correction":{"default":true,"description":"Correct any lens distortion in the image.","type":"boolean"},"metadata":{"additionalProperties":{},"description":"Metadata for the image.","type":"object"},"order_id":{"readOnly":true},"parent_image_id":{"description":"The ID of the parent image if this is a sub-image created for premium restaging. Null for original images.","nullable":true,"type":"string"},"perspective_correction":{"description":"Whether perspective correction is enabled for the image.","nullable":true,"type":"boolean"},"perspective_correction_mode":{"description":"The perspective correction mode used for the image. 'OFF' means disabled, 'DEFAULT_ENABLED' uses AI defaults, 'PRESERVE_CONTENT' prioritizes keeping content, 'PRIORITIZE_PERSPECTIVE' prioritizes straight lines.","enum":["OFF","DEFAULT_ENABLED","PRESERVE_CONTENT","PRIORITIZE_PERSPECTIVE",null],"nullable":true,"type":"string"},"preset_id":{"description":"The ID of the preset that was applied to the image.","readOnly":true},"preset_version":{"description":"Preset version applied when the image was last processed with a preset.","nullable":true,"readOnly":true},"privacy":{"description":"Whether to blur any faces or license plates in the image.","nullable":true,"type":"boolean"},"rating":{"description":"A rating between 0 and 5 on how good the image enhancmeent. Higher is better.","maximum":5,"minimum":0,"type":"integer"},"restage":{"anyOf":[{"$ref":"#/components/schemas/Restage"},{"nullable":true,"type":"object"}],"description":"Restage options for in-painting or modifying scene elements. Allows correcting details like lighting a fireplace, removing fingerprints from a TV screen, or removing unwanted items like tripods."},"scene":{"description":"The detected scene of the image i.e garden, patio, kitchen, etc.","type":"string"},"sky_replacement":{"description":"Whether the sky replacement feature was enabled for the image.","type":"boolean"},"status":{"description":"The status of the order.","readOnly":true},"status_reason":{"description":"Reason for the image's current status","readOnly":true},"tripod_hide":{"description":"Whether to crop the bottom of 360-degree images to hide the tripod. Note: This performs a simple crop and does not use generative in-painting.","nullable":true,"type":"boolean"},"upscale":{"description":"Whether to upscale the image.","type":"boolean"},"user_id":{"description":"The user ID of the user who uploaded (owns) the image.","readOnly":true},"window_pull_type":{"description":"What type of window pull to apply to the image (Available since AI version >= 4.0, WITH_SKIES can only be used from AI version 5.2 or higher).","enum":["NONE","ONLY_WINDOWS","WINDOWS_WITH_SKIES",null],"nullable":true,"type":"string"}},"type":"object"},"HTTPError":{"properties":{"detail":{"type":"object"},"message":{"type":"string"}},"type":"object"},"ValidationError":{"properties":{"detail":{"properties":{"<location>":{"properties":{"<field_name>":{"items":{"type":"string"},"type":"array"}},"type":"object"}},"type":"object"},"message":{"type":"string"}},"type":"object"}}},"paths":{"/v3/orders/{id}/process":{"post":{"description":"Triggers the grouping of any brackets contained in the order and process the final images in the order.\n\nTODO: Ideally we use transactions to help deal with errors but it;s a pain with MongoEngine so need to do it as part of Django or other ORM","operationId":"process_order","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderHDRProcessIn"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderHDRProcessOut"}}},"description":"Successful response"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPError"}}},"description":"Authentication error"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPError"}}},"description":"Not found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"}},"summary":"Process Order","tags":["Orders"]}}}}
```

## Download Order Archive

> Generates a zip archive of an order's images. Use the \`original\`, \`enhanced\`\
> and \`restaged\` flags to choose which variants of each image to include — any\
> combination is allowed. When no flag is set the archive contains the final\
> \`restaged\` deliverable, preserving the behaviour of the legacy\
> POST /orders/\<id>/enhanced endpoint that aliases to this one.\
> \
> Generation is asynchronous: the first call returns 202 while the archive is\
> built, and subsequent calls 302-redirect to the finished zip.

```json
{"openapi":"3.0.3","info":{"title":"Autoenhance API","version":"2026-10-01"},"tags":[{"name":"Orders"}],"servers":[{"url":"http://api:8080"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"OrderArchiveQuery":{"properties":{"dpi":{"description":"DPI of the image, must at least be 72.","minimum":72,"type":"integer"},"enhanced":{"default":false,"description":"Include the enhanced (non-restaged) image in the archive.","type":"boolean"},"finetune":{"default":null,"description":"Whether to apply finetuning to the image. Deprecated: use 'finetuned' instead.","nullable":true,"type":"boolean"},"finetuned":{"default":null,"description":"Whether to apply finetuning to the image.","nullable":true,"type":"boolean"},"format":{"description":"Format of the image, must be one of 'avif', 'png', 'jpeg', 'jxl', or 'webp'.","enum":["avif","png","jpeg","jxl","webp"],"type":"string"},"image_ids":{"description":"IDs of the images to retrieve.","items":{"description":"IDs of the images to export.","type":"string"},"type":"array"},"image_name_option":{"description":"Naming convention for images in the export. 'image_name' uses the original image name, 'order_name' uses the order name with a numeric prefix for sortability. ","enum":["image_name","order_name"]},"max_width":{"description":"Maximum width of the image in pixels. Must be a positive integer.","minimum":1,"type":"integer"},"original":{"default":false,"description":"Include the original uploaded image in the archive.","type":"boolean"},"preview":{"description":"Whether to show a lower quality preview version.","type":"boolean"},"quality":{"description":"Quality of the image, must be between 1 and 90.","maximum":90,"minimum":1,"type":"integer"},"restaged":{"default":false,"description":"Include the final restaged-if-available image in the archive.","type":"boolean"},"scale":{"description":"Scale factor for the image, must be between 0.0 and 1.0.","maximum":1,"minimum":0,"type":"number"},"sort_images_by":{"description":"Sort images by field name. Prefix with '-' for descending order. ","enum":["name","-name","date_added","-date_added","custom"]},"visible_disclosure":{"default":false,"description":"Whether to overlay an AI disclosure label on the image.","type":"boolean"},"watermark":{"description":"Whether to apply a watermark to the image.","type":"boolean"}},"type":"object"},"HTTPError":{"properties":{"detail":{"type":"object"},"message":{"type":"string"}},"type":"object"},"ValidationError":{"properties":{"detail":{"properties":{"<location>":{"properties":{"<field_name>":{"items":{"type":"string"},"type":"array"}},"type":"object"}},"type":"object"},"message":{"type":"string"}},"type":"object"}}},"paths":{"/v3/orders/{order_id}/archive":{"post":{"description":"Generates a zip archive of an order's images. Use the `original`, `enhanced`\nand `restaged` flags to choose which variants of each image to include — any\ncombination is allowed. When no flag is set the archive contains the final\n`restaged` deliverable, preserving the behaviour of the legacy\nPOST /orders/<id>/enhanced endpoint that aliases to this one.\n\nGeneration is asynchronous: the first call returns 202 while the archive is\nbuilt, and subsequent calls 302-redirect to the finished zip.","operationId":"download_order_archive","parameters":[{"in":"path","name":"order_id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderArchiveQuery"}}}},"responses":{"200":{"content":{"application/zip":{"schema":{"format":"binary","type":"string"}}},"description":"Successful response"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPError"}}},"description":"Authentication error"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPError"}}},"description":"Not found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"}},"summary":"Download Order Archive","tags":["Orders"]}}}}
```

## Retrieve Order Brackets

> Retrieves the brackets for a specific order by its unique identifier.\
> If the order is not found, a 404 error is raised.\
> \
> Args:\
> order\_id (str): The unique identifier of the order to retrieve brackets for.\
> \
> Returns:\
> Order: The retrieved order object containing brackets.\
> \
> Raises:\
> HTTPException: If the order is not found, a 404 error is raised.

```json
{"openapi":"3.0.3","info":{"title":"Autoenhance API","version":"2026-10-01"},"tags":[{"name":"Orders"}],"servers":[{"url":"http://api:8080"}],"paths":{"/v3/orders/{order_id}/brackets":{"get":{"description":"Retrieves the brackets for a specific order by its unique identifier.\nIf the order is not found, a 404 error is raised.\n\nArgs:\norder_id (str): The unique identifier of the order to retrieve brackets for.\n\nReturns:\nOrder: The retrieved order object containing brackets.\n\nRaises:\nHTTPException: If the order is not found, a 404 error is raised.","parameters":[{"in":"path","name":"order_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderBracketsOut"}}},"description":"Successful response"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPError"}}},"description":"Not found"}},"summary":"Retrieve Order Brackets","tags":["Orders"]}}},"components":{"schemas":{"OrderBracketsOut":{"additionalProperties":false,"properties":{"brackets":{"items":{"$ref":"#/components/schemas/BracketOut"},"type":"array"}},"type":"object"},"BracketOut":{"additionalProperties":false,"properties":{"bracket_id":{"type":"string"},"image_id":{"readOnly":true},"is_uploaded":{"type":"boolean"},"metadata":{"additionalProperties":{},"description":"Metadata for the bracket.","type":"object"},"name":{"type":"string"},"order_id":{"readOnly":true}},"type":"object"},"HTTPError":{"properties":{"detail":{"type":"object"},"message":{"type":"string"}},"type":"object"}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.autoenhance.ai/api/orders.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.