> For the complete documentation index, see [llms.txt](https://docs.flowretail.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flowretail.com/docs/developers/api-documentation/purchase/remove-a-purchase-order-item.md).

# Remove a purchase order item

Removes an item from a purchase order.

Required permissions: PURCHASE\_ORDER

```json
{"openapi":"3.0.2","info":{"title":"Flow Retail API version 2","version":"2.0.0"},"tags":[{"name":"Purchase","description":"Purchase"}],"servers":[{"description":"Flow Retail Production","url":"https://api.flowretail.com/v2"},{"description":"Flow Retail Stage","url":"https://api.stage.flowretail.com/v2"}],"security":[{"accessToken":[]},{"authToken":[]},{"integrationToken":[]}],"components":{"securitySchemes":{"accessToken":{"description":"Access token recevied after user login with a deviceToken","scheme":"bearer","type":"http"},"authToken":{"description":"Token received from the auth service","scheme":"bearer","type":"http"},"integrationToken":{"scheme":"bearer","type":"http"}},"responses":{"PurchaseOrderResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrderResponseSchema"}}},"description":"Example response"}},"schemas":{"PurchaseOrderResponseSchema":{"title":"PurchaseOrderResponseSchema","type":"object","required":["createdAt","createdBy","deliveryAddress","deliveryCity","deliveryCountryCode","deliveryName","deliveryPostalCode","externalId","items","lastModifiedAt","lastModifiedBy","note","purchaseNumber","purchaseOrderUid","status","storeUid","storeName","supplierUid","supplierName","discountRate","freight","currency","supplierReferenceNumber","invoiceAddress","reserveAfter","hasConfirmedReceivements"],"properties":{"createdAt":{"format":"date-time","type":"string"},"createdBy":{"type":"string"},"deliveryAddress":{"type":"string"},"deliveryCity":{"type":"string"},"deliveryCountryCode":{"type":"string"},"deliveryName":{"type":"string"},"deliveryPostalCode":{"type":"string"},"externalId":{"type":"string"},"items":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseOrderItemResponseSchema"}},"lastModifiedAt":{"format":"date-time","type":"string"},"lastModifiedBy":{"type":"string"},"note":{"type":"string"},"purchaseNumber":{"description":"Reference to a customer order","type":"string"},"purchaseOrderUid":{"$ref":"#/components/schemas/UID"},"status":{"$ref":"#/components/schemas/PurchaseOrderStatusENUM"},"storeUid":{"$ref":"#/components/schemas/UID"},"storeName":{"type":"string"},"supplierUid":{"$ref":"#/components/schemas/UID"},"supplierName":{"type":"string"},"discountRate":{"type":"integer"},"freight":{"type":"integer"},"currency":{"$ref":"#/components/schemas/PurchaseOrderCurrencySchema"},"supplierReferenceNumber":{"type":"string","description":"Supplier reference number"},"invoiceAddress":{"$ref":"#/components/schemas/PurchaseOrderInvoiceAddress"},"reserveAfter":{"type":"string","description":"If set, items in this purchase\norder cannot be reserved before this date.","format":"date-time","nullable":true},"interStoreSalesOrder":{"$ref":"#/components/schemas/InterStoreSalesOrderResponseSchema"},"hasConfirmedReceivements":{"type":"boolean"}}},"PurchaseOrderItemResponseSchema":{"title":"PurchaseOrderItemResponseSchema","type":"object","required":["createdAt","createdBy","expectedDeliveryDate","externalId","lastModifiedAt","lastModifiedBy","productUid","productName","productSerialNoRequired","productSku","purchaseOrderItemUid","quantityOrdered","quantityReceived","quantityReserved","supplierSku","unitPrice","receivementItems","discountAmount","freightAmount","unitCost","totalLinePrice","localCurrency","reservations","note","sortOrder","purchaseOrderItemLinks"],"properties":{"createdAt":{"type":"string","format":"date-time"},"createdBy":{"type":"string"},"expectedDeliveryDate":{"format":"date","type":"string"},"externalId":{"type":"string"},"lastModifiedAt":{"format":"date-time","type":"string"},"lastModifiedBy":{"type":"string"},"productUid":{"$ref":"#/components/schemas/UID"},"productName":{"type":"string"},"productSerialNoRequired":{"$ref":"#/components/schemas/SerialNoRequiredENUM"},"productSku":{"type":"string"},"purchaseOrderItemUid":{"$ref":"#/components/schemas/UID"},"quantityOrdered":{"type":"integer"},"quantityReceived":{"type":"integer"},"quantityReserved":{"type":"integer"},"supplierSku":{"type":"string"},"interStoreSalesOrder":{"$ref":"#/components/schemas/InterStoreSalesOrderItemResponseSchema"},"unitPrice":{"type":"integer","description":"unitPrice is in purchase price in order currency before discounts"},"receivementItems":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseReceivementItemResponseSchema"}},"discountAmount":{"type":"integer","description":"The discount amount pr unit"},"freightAmount":{"type":"integer","description":"The portion of the shipping cost pr unit."},"unitCost":{"type":"integer","description":"The price pr unit including discount and freight. This is what will be used as cost price during receivement."},"totalLinePrice":{"type":"integer","description":"Total price for all the items including discounts and freight amount."},"currency":{"$ref":"#/components/schemas/DeprecatedPurchaseOrderItemCurrencySchema"},"localCurrency":{"$ref":"#/components/schemas/PurchaseOrderItemCurrencySchema"},"reservations":{"type":"array","items":{"$ref":"#/components/schemas/OrderItemReservationSchema"}},"note":{"type":"string"},"sortOrder":{"type":"integer"},"purchaseOrderItemLinks":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseOrderItemLinkSchema"}}}},"UID":{"title":"UID","type":"string","pattern":"^[A-Za-z0-9-_]+"},"SerialNoRequiredENUM":{"description":"|ENUM      | Description |\n| ---------------- | ------------ |\n| NO | No Serial number required|\n| ON_SALE | Can register serial number when selling a product (Serial number is optional)|\n| ON_RECEIVE | Must register serial number when receiving and selling product (Serial number is required)|","enum":["NO","ON_SALE","ON_RECEIVE"],"title":"SerialNoRequiredENUM","type":"string"},"InterStoreSalesOrderItemResponseSchema":{"title":"InterStoreSalesOrderItemResponseSchema","description":"The seller store's sales order line auto-created from and coupled 1:1 to this purchase\norder item in inter-store trade. Carries the same sales order fields as\nInterStoreSalesOrderResponseSchema plus the coupled line itself. Absent when the\npurchase order item is not part of inter-store trade.","allOf":[{"$ref":"#/components/schemas/InterStoreSalesOrderResponseSchema"},{"type":"object","required":["orderItemUid","reservationType","reservationDetails"],"properties":{"orderItemUid":{"type":"string","pattern":"^[A-Za-z0-9-_]+","description":"The coupled sales order line at the seller store."},"reservationType":{"allOf":[{"$ref":"#/components/schemas/SalesReservationTypeENUM"}],"description":"How the seller is covering its line, and the field to read first — it decides whether reservationDetails is worth looking at.\n`WAREHOUSE` — the seller has the goods in stock now. This is the normal state for a proactive inter-store purchase. The line may still name the purchase order the goods arrived on, kept as history — see reservationDetails.\n`PURCHASEORDER` — the goods are still on their way in to the seller, and reservationDetails.purchaseOrder carries the date this purchase order really depends on.\n`PURCHASEORDER_CONFIRMED` — the seller has a confirmed incoming shipment earmarked for the line, named by reservationDetails.receivement.\n`REQUEST_PURCHASEORDER` — the seller line is waiting for a purchase order that has not been placed yet.\n`NONE` — the seller line holds no reservation."},"reservationDetails":{"allOf":[{"$ref":"#/components/schemas/SalesReservationDetailsSchema"}],"description":"What the seller's line is itself waiting on — the same reservationDetails the seller sees on that line.\n**reservationType says what the line is waiting for; this object says what it is tied to.** They are not the same question, and on a `WAREHOUSE` line they have different answers.\nGoods that arrived keep the purchase order they came in on: the link is deliberately left in place so the sale can be traced back to the purchase it was covered by. So a `WAREHOUSE` line can carry a `purchaseOrder` whose `expectedDeliveryDate` is in the past — that date is a record of when the goods were expected, not a promise about a delivery still to come. Read a delivery date as pending only while reservationType says the line is still waiting for one.\n`purchaseOrder` is the seller's own incoming purchase order line, and its `expectedDeliveryDate` is the date this purchase order really depends on. `receivement` names an earmarked incoming shipment.\nA seller line that is itself sourced from a third store carries `interStorePurchaseOrder` here, which is how a chain of stores becomes visible to the store paying for it — the inter-store markup is applied at every hop. **The chain is only followed one step.** That third store's own reservationDetails is not carried, so this field never nests further than the seller immediately behind this purchase order line.\nNote that `warehouse` is never set, here or on a sales order line — a line's warehouse is reported by the sales line's own `warehouseUid` and `warehouseName`, which are not part of this object. Read reservationType for the stock case."}}}]},"InterStoreSalesOrderResponseSchema":{"title":"InterStoreSalesOrderResponseSchema","type":"object","description":"The seller store's sales order auto-created from and coupled 1:1 to this purchase\norder in inter-store trade. Absent when the purchase order is not part of inter-store\ntrade.","required":["orderUid","orderNumber","orderState","storeUid","storeName"],"properties":{"orderUid":{"$ref":"#/components/schemas/UID"},"orderNumber":{"type":"string"},"orderState":{"$ref":"#/components/schemas/OrderOrderStateENUM"},"storeUid":{"type":"string","pattern":"^[A-Za-z0-9-_]+","description":"The seller store the coupled sales order belongs to."},"storeName":{"type":"string"}}},"OrderOrderStateENUM":{"description":"|ENUM | Description |\n| --- | --- |\n| OPEN | Order is open and beeing edited by someone|\n| PARKED | Order is parked|\n| CANCELED | Order is canceled/deleted|\n| COMPLETE | Order is complete|\n| CONFIRMED | Order is confirmed|\n","enum":["OPEN","PARKED","CANCELED","COMPLETE","CONFIRMED"],"title":"OrderOrderStateENUM","type":"string"},"SalesReservationTypeENUM":{"title":"SalesReservationTypeENUM","type":"string","enum":["NONE","WAREHOUSE","PURCHASEORDER","REQUEST_PURCHASEORDER","PURCHASEORDER_CONFIRMED"],"description":""},"SalesReservationDetailsSchema":{"title":"SalesReservationDetailsSchema","type":"object","description":"What a sales order line is waiting on.\n\nreceivement is the receivement this line is earmarked against, or was received on.\ninterStorePurchaseOrderReceivement is one hop further out, in inter-store trade: the\nsame for the coupled seller line, at the seller store. It pairs with\ninterStorePurchaseOrder the way receivement pairs with purchaseOrder, and is set only\nwhen interStorePurchaseOrder is.\nLike receivement it stays once the goods have arrived: receivedAt is then set and the\nseller line is reserved from stock. Like interStorePurchaseOrder, a receipt line does not\ncarry it.","properties":{"warehouse":{"$ref":"#/components/schemas/SalesReservationWarehouseSchema"},"purchaseOrder":{"$ref":"#/components/schemas/SalesReservationPurchaseOrderSchema"},"receivement":{"$ref":"#/components/schemas/SalesReservationReceivementSchema"},"interStorePurchaseOrder":{"$ref":"#/components/schemas/SalesReservationInterStorePurchaseOrderSchema"},"interStorePurchaseOrderReceivement":{"$ref":"#/components/schemas/SalesReservationReceivementSchema"},"purchaseRequest":{"$ref":"#/components/schemas/SalesReservationPurchaseRequestSchema"}}},"SalesReservationWarehouseSchema":{"title":"SalesReservationWarehouseSchema","type":"object","nullable":true,"description":"The warehouse a line covered from stock is held in.\n\nSet only when reservationType is WAREHOUSE. A line waiting on a purchase order can carry\na warehouse of its own, and naming it here would say the goods are in stock when they are\non order — so it stays absent for every other reservation type. That includes NONE, where\nthe line's own warehouseUid and warehouseName may well be set while this object is not.\n\nOn a sales order line it repeats what warehouseUid and warehouseName already say. Where it\nearns its place is a purchase order: there this object describes the coupled seller line,\nand the response carries no sales line to read those fields from, so this is the only\nplace the buying store learns which of the seller's warehouses its goods are held in.","required":["warehouseName"],"properties":{"warehouseName":{"type":"string","description":"The name of the warehouse. The uid is not part of this object: a sales order line\nreports it in its own warehouseUid, and a purchase order's coupled seller line does\nnot carry one at all."}}},"SalesReservationPurchaseOrderSchema":{"title":"SalesReservationPurchaseOrderSchema","type":"object","nullable":true,"required":["purchaseOrderUid","purchaseOrderItemUid","purchaseOrderNumber","quantityOrdered"],"properties":{"purchaseOrderUid":{"$ref":"#/components/schemas/UID"},"purchaseOrderItemUid":{"$ref":"#/components/schemas/UID"},"expectedDeliveryDate":{"type":"string","format":"date-time"},"purchaseOrderNumber":{"type":"string"},"quantityOrdered":{"type":"integer","description":"The quantity ordered on this purchase order line."},"externalId":{"type":"string"}}},"SalesReservationReceivementSchema":{"title":"SalesReservationReceivementSchema","type":"object","required":["receivementUid","receivementItemUid","expectedArrival","quantity","supplierOrderReference","receivedAt"],"properties":{"receivementUid":{"$ref":"#/components/schemas/UID"},"receivementItemUid":{"$ref":"#/components/schemas/UID"},"expectedArrival":{"type":"string","format":"date-time"},"expectedDispatch":{"type":"string","format":"date-time"},"quantity":{"type":"integer"},"supplierOrderReference":{"type":"string"},"receivedAt":{"type":"string","format":"date-time","nullable":true}}},"SalesReservationInterStorePurchaseOrderSchema":{"title":"SalesReservationInterStorePurchaseOrderSchema","type":"object","nullable":true,"description":"In inter-store trade, the seller store this sales order line's goods are coming from,\nand the seller's own incoming purchase order line they are coming in on.\n\nSet only on a line at the buying store. The seller's own mirrored line does not carry it,\nso the presence of this field is what tells a client which side of the coupling it is\nlooking at — no need to read the order it belongs to. A seller store learns how much of\nits mirrored line is promised to customers from interStoreOrderReservationQuantity on\nthat line instead.\n\nRead it on order and delivery responses. A receipt line does not carry it: both of the\nline-level inter-store fields are live reservation state, counted from the reserving lines\nas they stand when the line is read, and a receipt records a settled sale. So on a receipt\nline their absence says nothing about which side of a coupling it is on.\n\nNote that reservationDetails.purchaseOrder alongside it is unchanged: that is still the\nbuying store's own purchase order, the one this line actually reserves against. This\nfield is one hop further out — where that purchase order gets its goods from.\n\nThe store is always named; the purchase order fields can be absent. They are absent when\nthe seller is fulfilling from its own stock rather than from an incoming purchase order.\nThat is the state a proactive inter-store purchase starts in, where the mirrored seller\nline is reserved from stock, and the normal case for a seller-initiated sale. The fields\nappear once the seller line is re-pointed at a specific incoming purchase order line.","required":["storeUid","storeName"],"properties":{"storeUid":{"$ref":"#/components/schemas/UID"},"storeName":{"type":"string"},"purchaseOrderUid":{"$ref":"#/components/schemas/UID"},"purchaseOrderNumber":{"type":"string"},"purchaseOrderItemUid":{"$ref":"#/components/schemas/UID"}}},"SalesReservationPurchaseRequestSchema":{"title":"SalesReservationPurchaseRequestSchema","type":"object","description":"The request to purchasing that a line with reservationType REQUEST_PURCHASEORDER is.\n\nSet only on such a line. requestedAt is when the line became a request, and is absent\nfor a request that was already waiting before Flow started recording it. declinedAt is\nwhen purchasing declined the request, and is absent while it is open.","properties":{"requestedAt":{"type":"string","format":"date-time"},"declinedAt":{"type":"string","format":"date-time"}}},"PurchaseReceivementItemResponseSchema":{"title":"PurchaseReceivementItemResponseSchema","description":"PurchaseReceivementItem","allOf":[{"type":"object","required":["receivementUid","receivementStatus","invoiceApproval"],"properties":{"receivementUid":{"$ref":"#/components/schemas/UID"},"receivementStatus":{"$ref":"#/components/schemas/ReceivementStatusENUM"},"invoiceApproval":{"$ref":"#/components/schemas/ReceivementInvoiceApprovalSchema"}}},{"$ref":"#/components/schemas/ReceivementItemResponseSchema"}]},"ReceivementStatusENUM":{"description":"|ENUM      | Description |\n| ---------------- | ------------ |\n| RECEIVED | Received|\n| PENDING | Put aside, not finished|\n| UPDATING | Updating in progress|\n| CONFIRMED | Confirmed |","enum":["RECEIVED","PENDING","UPDATING","CONFIRMED"],"title":"ReceivementStatusENUM","type":"string"},"ReceivementInvoiceApprovalSchema":{"title":"ReceivementInvoiceApprovalSchema","type":"object","nullable":true,"description":"Invoice-approval (fakturagodkjent) state. Null when the receivement is not invoice-approved.","required":["approvedAt","tenantUserUid","tenantUserDisplayName"],"properties":{"approvedAt":{"type":"string","format":"date-time"},"tenantUserUid":{"$ref":"#/components/schemas/UID"},"tenantUserDisplayName":{"type":"string"}}},"ReceivementItemResponseSchema":{"title":"ReceivementItemResponseSchema","type":"object","required":["createdAt","createdBy","externalId","lastModifiedAt","lastModifiedBy","product","purchaseOrderItemUid","quantity","receivementItemUid","status","note","tenantUserUid","tenantUserDisplayName","reservations"],"properties":{"createdAt":{"format":"date-time","type":"string"},"createdBy":{"type":"string"},"externalId":{"description":"External reference to receivement line","type":"string"},"lastModifiedAt":{"format":"date-time","type":"string"},"lastModifiedBy":{"type":"string"},"product":{"$ref":"#/components/schemas/ReceivementItemProductResponseSchema"},"purchaseOrderItemUid":{"$ref":"#/components/schemas/UID"},"quantity":{"type":"integer"},"unitPrice":{"type":"integer","deprecated":true,"description":"Deprecated: Use unitcost instead"},"unitCost":{"type":"integer"},"receivementItemUid":{"$ref":"#/components/schemas/UID"},"serialnumber":{"type":"string"},"status":{"type":"string"},"note":{"type":"string"},"tenantUserUid":{"$ref":"#/components/schemas/OptionalUID"},"tenantUserDisplayName":{"type":"string","description":"The display name of the user that made the receivement"},"reservations":{"type":"array","items":{"$ref":"#/components/schemas/OrderItemReservationSchema"}}}},"ReceivementItemProductResponseSchema":{"title":"ReceivementItemProductResponseSchema","type":"object","required":["productUid","name","sku"],"properties":{"productUid":{"$ref":"#/components/schemas/UID"},"name":{"type":"string"},"sku":{"type":"string"}}},"OptionalUID":{"title":"OptionalUID","type":"string","pattern":"^[A-Za-z0-9-_]*"},"OrderItemReservationSchema":{"title":"OrderItemReservationSchema","type":"object","required":["orderUid","orderItemUid","orderNumber","quantity","reservationType"],"properties":{"orderUid":{"$ref":"#/components/schemas/UID"},"orderItemUid":{"$ref":"#/components/schemas/UID"},"orderNumber":{"type":"string"},"quantity":{"type":"integer"},"reservationType":{"$ref":"#/components/schemas/SalesReservationTypeENUM"}}},"DeprecatedPurchaseOrderItemCurrencySchema":{"title":"DeprecatedPurchaseOrderItemCurrencySchema","type":"object","deprecated":true,"required":["unitPrice","discountAmount","freightAmount","totalLinePrice"],"properties":{"unitPrice":{"type":"integer"},"discountAmount":{"type":"integer"},"freightAmount":{"type":"integer"},"totalLinePrice":{"type":"integer"}}},"PurchaseOrderItemCurrencySchema":{"title":"PurchaseOrderItemCurrencySchema","type":"object","description":"All prices is in the local tenant currency","required":["unitPrice","discountAmount","freightAmount","unitCost","totalLinePrice"],"properties":{"unitPrice":{"type":"integer","description":"unitPrice is in local currency before discount"},"discountAmount":{"type":"integer","description":"The discount amount pr unit"},"freightAmount":{"type":"integer","description":"The portion of the shipping cost for this purchase order line."},"unitCost":{"type":"integer","description":"The price pr unit including discount and freight. This is what will be used as cost price during receivement."},"totalLinePrice":{"type":"integer","description":"Total price for all the items including discounts and freight amount."}}},"PurchaseOrderItemLinkSchema":{"description":"Order reference for an order product item","title":"PurchaseOrderItemLinkSchema","type":"object","required":["purchaseOrderItemUid","type"],"properties":{"purchaseOrderItemUid":{"$ref":"#/components/schemas/UID"},"type":{"$ref":"#/components/schemas/PurchaseOrderLinkTypeResponseENUM"}}},"PurchaseOrderLinkTypeResponseENUM":{"description":"Describes the type of link on an order product item\n\n|ENUM | Description |\n| --- | --- |\n| PACKAGE | Reference to orderline with main package product |\n| PACKAGE_COMPONENT | Reference to orderline with package component product |\n","enum":["PACKAGE","PACKAGE_COMPONENT"],"title":"PurchaseOrderLinkTypeResponseENUM","type":"string"},"PurchaseOrderStatusENUM":{"description":"|ENUM      | Description |\n| ---------------- | ------------ |\n| NEW | Created, but not sent to supplier yet.|\n| SENT_TO_SUPPLIER | Sent to supplier.|\n| CANCELLED_BY_SUPPLIER | The purchase order have been cancelled by the supplier. This status is only applicable for suppliers who are integrated with FlowRetail.|\n| IN_TRANSIT | The goods are in transit. This status is only applicable for suppliers who are integrated with FlowRetail.|\n| PARTIALLY_RECEIVED | Not all goods have been received yet.|\n| RECEIVED | All goods have been received.|\n| CLOSED | No longer able to process purchase order.|\n| CANCELLED_BY_SUPPLIER | Purchase was cancelled by supplier|","enum":["NEW","PARTIALLY_RECEIVED","RECEIVED","SENT_TO_SUPPLIER","IN_TRANSIT","CLOSED","CANCELLED_BY_SUPPLIER"],"title":"PurchaseOrderStatusENUM","type":"string"},"PurchaseOrderCurrencySchema":{"title":"PurchaseOrderCurrencySchema","type":"object","required":["code","exchangeRate"],"properties":{"code":{"type":"string","description":"ISO 4217"},"exchangeRate":{"type":"integer"}}},"PurchaseOrderInvoiceAddress":{"title":"PurchaseOrderInvoiceAddress","type":"object","required":["companyName","address","postalCode","city","countryCode","vatNumber","email"],"properties":{"companyName":{"type":"string"},"address":{"type":"string"},"postalCode":{"type":"string"},"city":{"type":"string"},"countryCode":{"type":"string"},"vatNumber":{"type":"string"},"email":{"type":"string"}}}}},"paths":{"/tenants/{tenantUid}/stores/{storeUid}/purchase-orders/{purchaseOrderUid}/purchase-order-items/{purchaseOrderItemUid}":{"delete":{"description":"Removes an item from a purchase order.\n\nRequired permissions: PURCHASE_ORDER","operationId":"delete-tenants-stores-purchase-orders-purchase-order-items-details","responses":{"200":{"$ref":"#/components/responses/PurchaseOrderResponse"}},"summary":"Remove a purchase order item","tags":["Purchase"]}}}}
```


---

# 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.flowretail.com/docs/developers/api-documentation/purchase/remove-a-purchase-order-item.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.