{"openapi":"3.1.0","info":{"title":"Dragonfly Partner API","version":"2026-10-07.2","summary":"Send delivery orders to Dragonfly — single catering drops and multi-stop routes.","description":"Approved merchants (and their AI agents) send orders; Dragonfly stores them, builds/dispatches routes, and reports status. Guide: https://api.trydragonfly.com/v1/docs · Sandbox: POST /v1/signup with sandbox:true returns a test key instantly.","contact":{"name":"Dragonfly support","email":"support@trydragonfly.com"}},"servers":[{"url":"https://api.trydragonfly.com"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Authorization: Bearer dfk_live_… (production) or dfk_test_… (sandbox)"},"hmac":{"type":"apiKey","in":"header","name":"X-Dragonfly-Signature","description":"hex HMAC-SHA256 of the raw body keyed by your signingSecret, plus header X-Dragonfly-Key: <keyPrefix>"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","examples":["VALIDATION_ERROR","UNAUTHORIZED","MERCHANT_INACTIVE","FORBIDDEN","NOT_FOUND","CANCEL_NOT_ALLOWED","RATE_LIMITED","DUPLICATE_APPLICATION","EMAIL_IN_USE"]},"message":{"type":"string"},"details":{"type":"array","description":"VALIDATION_ERROR only — one entry per bad field","items":{"type":"object","properties":{"path":{"type":"string","examples":["dropoffs.1.contactPhone"]},"message":{"type":"string"}}}}}}}},"PickupStop":{"type":"object","required":["address","contactPhone"],"properties":{"address":{"type":"string","description":"Full street address incl. city, state, ZIP — e.g. \"445 N Michigan Ave, Chicago, IL 60611\""},"lat":{"type":"number"},"lng":{"type":"number"},"contactName":{"type":"string"},"contactPhone":{"type":"string","minLength":7,"description":"Reachable cellphone (E.164 preferred). Required — carriers text/call it."},"notes":{"type":"string","description":"Pickup instructions"},"windowStart":{"type":"string","format":"date-time","description":"Ready for pickup"},"windowEnd":{"type":"string","format":"date-time","description":"Pickup by"},"requiresSignature":{"type":"boolean"},"photoRequired":{"type":"string","enum":["NONE","OPTIONAL","REQUIRED"]},"notesRequired":{"type":"boolean"},"minimumAge":{"type":"integer","minimum":0,"maximum":120,"description":"Driver checks ID (e.g. 21 for alcohol, 18 for Rx)"},"pincodeRequired":{"type":"boolean","description":"4-digit code shown only on the recipient tracking page"},"barcodeRequired":{"type":"boolean"},"barcodes":{"type":"array","maxItems":100,"items":{"type":"object","required":["data"],"properties":{"data":{"type":"string"},"blockCompletion":{"type":"boolean","default":true}}}},"quantity":{"type":"integer","minimum":0},"items":{"type":"array","maxItems":200,"description":"Checklist shown to the driver","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"quantity":{"type":"integer"},"sku":{"type":"string"},"barcode":{"type":"string"},"notes":{"type":"string"}}}},"checklistRequired":{"type":"boolean","description":"Driver must tick every item before completing"}}},"DropoffStop":{"type":"object","required":["address","contactPhone"],"properties":{"address":{"type":"string","description":"Full street address incl. city, state, ZIP — e.g. \"445 N Michigan Ave, Chicago, IL 60611\""},"lat":{"type":"number"},"lng":{"type":"number"},"contactName":{"type":"string"},"contactPhone":{"type":"string","minLength":7,"description":"Reachable cellphone (E.164 preferred). Required — carriers text/call it."},"contactEmail":{"type":"string","format":"email","description":"Recipient email — receives the proof-of-delivery email."},"notes":{"type":"string","description":"Delivery instructions shown to the driver"},"windowStart":{"type":"string","format":"date-time","description":"Earliest delivery (ISO 8601 with offset)"},"windowEnd":{"type":"string","format":"date-time","description":"Latest delivery"},"requiresSignature":{"type":"boolean"},"photoRequired":{"type":"string","enum":["NONE","OPTIONAL","REQUIRED"]},"notesRequired":{"type":"boolean"},"minimumAge":{"type":"integer","minimum":0,"maximum":120,"description":"Driver checks ID (e.g. 21 for alcohol, 18 for Rx)"},"pincodeRequired":{"type":"boolean","description":"4-digit code shown only on the recipient tracking page"},"barcodeRequired":{"type":"boolean"},"barcodes":{"type":"array","maxItems":100,"items":{"type":"object","required":["data"],"properties":{"data":{"type":"string"},"blockCompletion":{"type":"boolean","default":true}}}},"quantity":{"type":"integer","minimum":0},"items":{"type":"array","maxItems":200,"description":"Checklist shown to the driver","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"quantity":{"type":"integer"},"sku":{"type":"string"},"barcode":{"type":"string"},"notes":{"type":"string"}}}},"checklistRequired":{"type":"boolean","description":"Driver must tick every item before completing"}}},"CreateOrder":{"type":"object","required":["externalId","pickup"],"description":"Send `dropoff` (one stop) or `dropoffs` (2–25 stops of one route).","properties":{"externalId":{"type":"string","maxLength":200,"description":"YOUR order id — the idempotency key. Re-sending it returns the existing order."},"subMerchantId":{"type":"string","description":"Pickup location id (multi-location accounts)"},"pickup":{"$ref":"#/components/schemas/PickupStop"},"dropoff":{"$ref":"#/components/schemas/DropoffStop"},"dropoffs":{"type":"array","minItems":1,"maxItems":25,"items":{"$ref":"#/components/schemas/DropoffStop"}},"subtotalCents":{"type":"integer","minimum":0,"description":"Order value in cents — drives tiered pricing"},"tipCents":{"type":"integer","minimum":0,"description":"100% to the driver"},"taxCents":{"type":"integer","minimum":0},"totalCents":{"type":"integer","minimum":0},"metadata":{"type":"object","additionalProperties":true}}},"Order":{"type":"object","properties":{"orderId":{"type":"string"},"externalId":{"type":"string"},"status":{"type":"string","enum":["PENDING","ASSIGNED","PICKED_UP","DELIVERED","FAILED","CANCELLED"]},"dispatchedTo":{"type":["string","null"],"enum":["cartwheel","onfleet","internal","dragonfly_routing","sandbox",null],"description":"dragonfly_routing = held for Dragonfly to route (your account is on routed intake)"},"trackingUrl":{"type":["string","null"]},"dropoffs":{"type":"integer"},"idempotentReplay":{"type":"boolean"},"promisedDeliveryAt":{"type":["string","null"],"format":"date-time"},"deliveredAt":{"type":["string","null"],"format":"date-time"},"onTime":{"type":["boolean","null"]},"createdAt":{"type":"string","format":"date-time"}}},"Signup":{"type":"object","required":["businessName","contactName","email","vertical"],"properties":{"sandbox":{"type":"boolean","description":"true = instant test account; key in the response; nothing dispatches or bills"},"businessName":{"type":"string"},"contactName":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"vertical":{"type":"string","enum":["catering","restaurant","grocery","parcels","industrial_3pl","pharmacy","medical","meal_kits","other"]},"address":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"zipCode":{"type":"string"},"pickupAddress":{"type":"string"},"expectedWeeklyOrders":{"type":"integer"},"notes":{"type":"string"}}}}},"paths":{"/v1/signup":{"post":{"operationId":"signup","summary":"Apply for a merchant account (or get a sandbox key instantly)","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Signup"}}}},"responses":{"201":{"description":"Production: { applicationId, pollToken (shown once), status: PENDING }. Sandbox: { apiKey, signingSecret, status: APPROVED }."},"400":{"description":"Invalid fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"DUPLICATE_APPLICATION, or EMAIL_IN_USE (existing merchants: request API access in the portal)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"10 signups/hour/IP","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/signup/{applicationId}":{"get":{"operationId":"getSignup","summary":"Poll an application; the first poll after approval returns the API key once","security":[],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Signup-Token","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"{ status } — PENDING | REJECTED (reviewNotes) | APPROVED (+ apiKey, signingSecret on the first poll only)"},"404":{"description":"Unknown id or wrong token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/orders":{"post":{"operationId":"createOrder","summary":"Create a delivery order (idempotent on externalId)","security":[{"bearer":[]},{"hmac":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrder"}}}},"responses":{"200":{"description":"Idempotent replay — the existing order","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Order"}}}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Order"}}}}}},"400":{"description":"VALIDATION_ERROR (see details) / INVALID_SUB_MERCHANT","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"MERCHANT_INACTIVE / missing scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"100 requests/min per key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/orders/{externalId}":{"get":{"operationId":"getOrder","summary":"Order status","security":[{"bearer":[]},{"hmac":[]}],"parameters":[{"name":"externalId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Order","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Order"}}}}}},"404":{"description":"Not your order / unknown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/orders/{externalId}/cancel":{"post":{"operationId":"cancelOrder","summary":"Cancel before pickup (PENDING or ASSIGNED); idempotent","security":[{"bearer":[]},{"hmac":[]}],"parameters":[{"name":"externalId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":500}}}}}},"responses":{"200":{"description":"{ cancelled: true, alreadyCancelled }"},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"CANCEL_NOT_ALLOWED — picked up, or already on a Dragonfly route","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks":{"get":{"operationId":"listWebhooks","summary":"Your webhook endpoints","security":[{"bearer":[]},{"hmac":[]}],"responses":{"200":{"description":"Endpoints (secrets redacted)"}}},"post":{"operationId":"createWebhook","summary":"Register an HTTPS endpoint for signed delivery events","security":[{"bearer":[]},{"hmac":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"},"examples":[["delivery.*"]]},"description":{"type":"string"}}}}}},"responses":{"201":{"description":"Endpoint incl. secret (whsec_…, shown once)"}}}},"/v1/webhooks/events":{"get":{"operationId":"webhookEvents","summary":"Event catalogue","security":[{"bearer":[]},{"hmac":[]}],"responses":{"200":{"description":"Events with Nash/Onfleet equivalents"}}}},"/v1/webhooks/{id}":{"patch":{"operationId":"updateWebhook","summary":"Update url/events/isActive","security":[{"bearer":[]},{"hmac":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Updated"}}},"delete":{"operationId":"deleteWebhook","summary":"Delete an endpoint","security":[{"bearer":[]},{"hmac":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted"}}}},"/v1/webhooks/{id}/deliveries":{"get":{"operationId":"webhookDeliveries","summary":"Delivery attempts","security":[{"bearer":[]},{"hmac":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Attempts"}}}},"/v1/webhooks/{id}/test":{"post":{"operationId":"testWebhook","summary":"Replay your latest order as a test event","security":[{"bearer":[]},{"hmac":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Queued"},"409":{"description":"NO_ORDERS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}