{"openapi":"3.1.0","info":{"title":"Firestarter Commerce Execution API","version":"0.1.0","description":"One API call to find, buy, ship, and track any product. Send a natural language purchase request and Firestarter handles the full lifecycle: product search, supplier negotiation, payment, shipping, and tracking.","contact":{"email":"support@firestarter.network","url":"https://firestarter.network"}},"servers":[{"url":"https://api.firestarter.network","description":"Production"}],"security":[{"BearerAuth":[]}],"paths":{"/v1/executions":{"post":{"operationId":"executeCommerce","summary":"Execute a commerce transaction","description":"Submit a natural language purchase request. The agent finds products, negotiates with suppliers, and presents options for approval. Costs ~10 tokens per execution.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Optional client-generated key. Replaying a request with the same key returns the original execution (with idempotent_replay: true) instead of creating a duplicate."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["request"],"properties":{"request":{"type":"string","description":"Natural language description of what to buy","example":"wireless earbuds under $50, good quality"},"budget":{"type":"object","properties":{"max_total":{"type":"number","description":"Maximum budget in USD"},"currency":{"type":"string","default":"USD"}}},"preferences":{"type":"object","properties":{"priority":{"type":"string","enum":["cost","speed","quality"],"default":"quality"},"auto_pay":{"type":"boolean","default":false,"description":"If true, automatically pay within budget"},"require_approval":{"type":"boolean","default":true,"description":"Pause for human approval before payment"}}},"delivery_address":{"type":"string","description":"Shipping address"},"callback_url":{"type":"string","format":"uri","description":"Webhook URL for status updates"}}}}}},"responses":{"201":{"description":"Execution created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"stream_url":{"type":"string"}}}}}},"400":{"description":"Invalid request"},"401":{"description":"Invalid or missing API key"}}},"get":{"operationId":"listExecutions","summary":"List all executions","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":20}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"List of executions"}}}},"/v1/executions/{id}":{"get":{"operationId":"getExecution","summary":"Get execution status, steps, and product options","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Execution details with steps and options"}}}},"/v1/executions/{id}/approve":{"post":{"operationId":"approveExecution","summary":"Approve or reject a purchase","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["approve","reject"]}}}}}},"responses":{"200":{"description":"Execution approved/rejected"}}}},"/v1/executions/{id}/cancel":{"post":{"operationId":"cancelExecution","summary":"Cancel an execution","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Execution cancelled"}}}},"/v1/billing/balance":{"get":{"operationId":"getBalance","summary":"Check token balance and plan","responses":{"200":{"description":"Current balance, plan, and pricing tiers"}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key from firestarter.network/dashboard"}}}}