{"openapi":"3.0.3","info":{"title":"DAGwood B2B Lead Synthesis & Enrichment API","version":"1.0.0","description":"Enterprise B2B decision-maker discovery and contact enrichment API. Enriches contacts through Wiza with source-labelled confidence, and runs a two-stage estimate/approval lifecycle.","contact":{"name":"DAGwood Engineering Support","url":"https://dagwood.ai","email":"support@dagwood.dev"}},"servers":[{"url":"https://api.dagwood.ai/v1","description":"Dedicated Production API Gateway (Recommended)"},{"url":"https://api.dagwood.ai","description":"Dedicated Root API Gateway"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"tags":[{"name":"Leads","description":"B2B Lead Synthesis, Enrichment, Estimation, and Execution API"},{"name":"Craft","description":"DAGwood Craft Autonomous App & Deliverable Synthesis API"},{"name":"Auth & Keys","description":"API Key Management and Tenant Authentication"}],"paths":{"/":{"get":{"summary":"API Discovery & Overview","description":"Returns general API health, supported lifecycles, and endpoint index.","operationId":"getApiDiscovery","responses":{"200":{"description":"API discovery information returned successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiscoveryResponse"}}}}}}},"/openapi.json":{"get":{"summary":"OpenAPI 3.0 / Swagger JSON Definition","description":"Returns the raw OpenAPI 3.0.3 specification JSON.","operationId":"getOpenApiSpec","responses":{"200":{"description":"OpenAPI specification JSON.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/leads/estimate":{"post":{"summary":"Stage 1: Generate Cost Estimate","description":"Calculates the exact Gouda credit and USD cost for targeting parameters and returns a `pending_approval` request ticket with approval actions.","operationId":"createLeadEstimate","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadEstimateRequest"},"examples":{"landscapingPhoenix":{"summary":"Commercial Landscaping in Phoenix","value":{"industry":"Commercial Landscaping","cityMetro":"Phoenix","stateRegion":"Arizona","country":"United States","roles":"Owner, Founder, Chief Executive Officer","channels":"phone_linkedin","volumeCount":5}},"hvacEmailOnly":{"summary":"HVAC Email Discovery (Email Only)","value":{"industry":"HVAC Services","cityMetro":"Scottsdale","stateRegion":"Arizona","roles":"President, General Manager","channels":"email_only","volumeCount":10}}}}}},"responses":{"201":{"description":"Cost estimate created. Status is `pending_approval`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadEstimateResponse"},"example":{"success":true,"requestId":"req_1787612981245_40d5b895","status":"pending_approval","message":"Cost estimate generated. This request is PENDING APPROVAL. Send a POST request to the approval URL to execute lead discovery. Approval debits the bundle price of the delivered leads once (bundleGouda) and returns everything debited for the request as costCharged.","costEstimate":{"totalGoudaCost":525,"unitGoudaCost":105,"recordCount":5,"currency":"Gouda","estimatedUSD":"$5.25","bundle":"Direct Phone + Corporate Email + LinkedIn","enrichmentLevel":"full"},"targeting":{"industry":"Commercial Landscaping","location":"Phoenix, Arizona, United States","targetRoles":"Owner, Founder, Chief Executive Officer","channels":"Direct Phone + Corporate Email + LinkedIn"},"actions":{"approve":{"method":"POST","url":"https://api.dagwood.ai/v1/leads/requests/req_1787612981245_40d5b895/approve","description":"Approve estimate and trigger real-time lead generation & enrichment"},"cancel":{"method":"POST","url":"https://api.dagwood.ai/v1/leads/requests/req_1787612981245_40d5b895/cancel"},"status":{"method":"GET","url":"https://api.dagwood.ai/v1/leads/requests/req_1787612981245_40d5b895"}}}}}},"400":{"description":"Bad Request / Missing parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized / Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden / Origin or Referer domain not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/leads/requests/{requestId}/approve":{"post":{"summary":"Stage 2: Approve & Execute Lead Synthesis","description":"Approves a pending estimate ticket, executes live multi-agent decision maker synthesis, enriches contacts through Wiza, debits the bundle price of the delivered leads once (bundleGouda), and returns everything debited for the request as costCharged.","operationId":"approveLeadRequest","parameters":[{"name":"requestId","in":"path","required":true,"description":"The unique request identifier returned from `/leads/estimate`","schema":{"type":"string","example":"req_1787612981245_40d5b895"}}],"responses":{"200":{"description":"Request approved and leads synthesized successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadApprovalResponse"},"example":{"success":true,"requestId":"req_1787612981245_40d5b895","status":"completed","message":"Successfully synthesized and enriched 1 lead profiles.","costCharged":110,"bundleGouda":105,"leadCount":1,"leads":[{"id":"lead_1_1787613002008","name":"Sample Lead","role":"President","company":"Sample Heating and Cooling Co.","domain":"example.com","industry":"HVAC Services","location":"Phoenix, Arizona, United States","email":"sample.lead@example.com","emailConfidence":"high","emailCitation":"Example citation (sample data)","phone":"+1-602-555-0110","phoneType":"Direct Mobile","phoneConfidence":"high","phoneCitation":"Example citation (sample data)","linkedin":"https://example.com/profiles/sample-lead","salesMatchSummary":"Example match summary (sample data).","companyCitation":{"domain":"example.com","headquarters":"Phoenix, AZ","employeeCount":25,"foundedYear":2005}}]}}}},"400":{"description":"Invalid state transition (e.g. a cancelled request)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Request ID not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Already running from an earlier approval (LEAD_REQUEST_ALREADY_RUNNING), failed after a run that was charged, so approving again would charge again (LEAD_REQUEST_ALREADY_CHARGED: generate a new estimate), or finished or cancelled while this approval was starting (LEAD_REQUEST_NOT_APPROVABLE). Nothing runs and nothing is charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/leads/requests/{requestId}/cancel":{"post":{"summary":"Cancel Pending Estimate","description":"Cancels a pending estimate ticket before approval without charging Gouda credits.","operationId":"cancelLeadRequest","parameters":[{"name":"requestId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Request successfully cancelled.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"requestId":{"type":"string"},"status":{"type":"string","example":"cancelled"}}}}}}}}},"/leads/requests/{requestId}":{"get":{"summary":"Get Request Status & Leads","description":"Polls live execution progress or retrieves historical lead results for an existing request ticket.","operationId":"getLeadRequest","parameters":[{"name":"requestId","in":"path","required":true,"schema":{"type":"string","example":"req_1787612981245_40d5b895"}}],"responses":{"200":{"description":"Request details and leads returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadApprovalResponse"}}}},"404":{"description":"Request ID not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/in/{endpointId}":{"post":{"tags":["Leads"],"summary":"Direct 1-Step Ingress / Webhook Lead Generation","description":"Direct webhook and pipeline ingress endpoint. Supports synchronous execution (TaskBullet, Zapier, cURL) returning complete leads directly, or asynchronous dispatch (`async: true`) returning HTTP 202 in <100ms.","operationId":"ingressLeadGenerator","parameters":[{"name":"endpointId","in":"path","required":true,"description":"The endpoint slug identifier (e.g. `lead-generator`).","schema":{"type":"string","example":"lead-generator"}},{"name":"async","in":"query","required":false,"description":"Set to `true` to execute asynchronously and return HTTP 202 immediately.","schema":{"type":"boolean","default":false}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["industry"],"properties":{"industry":{"type":"string","example":"Commercial Landscaping"},"cityMetro":{"type":"string","example":"Phoenix"},"stateRegion":{"type":"string","example":"Arizona"},"country":{"type":"string","example":"United States"},"targetRoles":{"type":"string","example":"Owner, Founder, Chief Executive Officer"},"bundle":{"type":"string","enum":["phone_linkedin","email_linkedin","phone_only","email_only"],"default":"phone_linkedin"},"volumeCount":{"type":"integer","default":5,"minimum":1,"maximum":50},"async":{"type":"boolean","default":false,"description":"Set to true for async job creation with HTTP 202 Accepted"}}}}}},"responses":{"200":{"description":"Synchronous lead generation completed successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadApprovalResponse"}}}},"202":{"description":"Asynchronous job accepted and queued in gnr8.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"status":{"type":"string","example":"queued"},"_isJob":{"type":"boolean","example":true},"jobId":{"type":"string","example":"job_api_1788829962914_a6fa5f87"},"pollUrl":{"type":"string","example":"/v1/requests/job_api_1788829962914_a6fa5f87"},"message":{"type":"string"}}}}}}}}},"/craft":{"post":{"tags":["Craft"],"summary":"Synthesize Project & Generate Deliverable ZIP","description":"Autonomous multi-agent synthesis engine. Takes a prompt describing an application, website, or workflow, compiles a full project workspace, and returns inspectable JSON or a zero-dependency PKZIP 2.0 binary archive.","operationId":"synthesizeCraft","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string","description":"Natural language description of the application, workflow, or UI to generate.","example":"Build a mortgage rate comparison calculator with monthly payment schedule"},"format":{"type":"string","enum":["json","zip"],"default":"json","description":"Output format. 'json' returns full JSON metadata and base64 zip; 'zip' returns binary application/zip stream."},"explicitNodes":{"type":"array","items":{"type":"string"},"description":"Optional list of node IDs explicitly required in the pipeline."},"images":{"type":"array","items":{"type":"string"},"description":"Optional array of base64 data URIs or Cloud Storage image URLs for visual design reference."}}}}}},"responses":{"200":{"description":"Vibecraft synthesized successfully (JSON metadata or raw ZIP buffer). When the plan reports a required input as missing, the reply is a NeedsInputResponse instead and no bundle is built.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"success":{"type":"boolean","example":true},"title":{"type":"string","example":"Mortgage Calculator"},"summary":{"type":"string"},"archetype":{"type":"string","example":"interactive_web_app"},"filename":{"type":"string","example":"mortgage-calculator-deliverable.zip"},"files":{"type":"object","additionalProperties":{"type":"string"}},"zipBase64":{"type":"string"},"sizeBytes":{"type":"integer"}}},{"$ref":"#/components/schemas/NeedsInputResponse"}]}},"application/zip":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Missing or invalid prompt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - API key missing or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Vibecraft synthesis or AI pipeline failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/vibecraft":{"post":{"tags":["Craft"],"summary":"Legacy alias for /craft","description":"Backwards-compatible alias for /craft: the same request and the same replies, including NeedsInputResponse.","operationId":"synthesizeCraftLegacyAlias","responses":{"200":{"description":"Synthesized successfully"}}}},"/keys":{"get":{"summary":"List API Keys","description":"Lists all provisioned API keys belonging to the signed-in account. Requires a signed-in session (Firebase ID token or `__session` cookie); API keys cannot list keys.","operationId":"listApiKeys","security":[{"FirebaseIdToken":[]},{"SessionCookie":[]}],"responses":{"200":{"description":"List of active and revoked API keys.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"keys":{"type":"array","items":{"$ref":"#/components/schemas/ApiKeyRecord"}}}}}}},"403":{"description":"The caller is not a signed-in session (for example, the request used an API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create New API Key","description":"Creates a live API key (`dag_live_...`) for the signed-in account. Only a signed-in session can create keys: a Firebase ID token in `Authorization: Bearer`, or the `__session` cookie. A caller authenticated any other way, including with an API key, gets 403. The account also needs API access approved by an admin (the `apiKeyAccess` claim); until then the call gets 403 and no key. Request access while signed in with `POST /v1/keys/request`. The full key is returned once, in this response; only its SHA-256 hash is stored. `name` is the only field read from the body.","operationId":"createApiKey","security":[{"FirebaseIdToken":[]},{"SessionCookie":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Label for the key. Default: \"Live Production Key\".","example":"TaskBullet Integration Key"}}}}}},"responses":{"201":{"description":"Key created successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"apiKey":{"type":"string","example":"dag_test_EXAMPLE_not_a_real_key"},"keyId":{"type":"string","example":"BVNgT4q8nwb2opeWUAHX"},"name":{"type":"string","example":"TaskBullet Integration Key"},"prefix":{"type":"string","example":"dag_test_EXA..."},"message":{"type":"string"},"gouda":{"type":"integer","description":"The account's Gouda balance."},"usdBalance":{"type":"string","example":"10.00"}}}}}},"401":{"description":"No valid session or key, or an invalid Firebase ID token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The caller is not a signed-in session (for example, the request used an API key), or the account's API access is not approved yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/keys/{keyId}":{"delete":{"summary":"Revoke API Key","description":"Deactivates an API key immediately. Requires a signed-in session (Firebase ID token or `__session` cookie); API keys cannot revoke keys.","operationId":"revokeApiKey","security":[{"FirebaseIdToken":[]},{"SessionCookie":[]}],"parameters":[{"name":"keyId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Key revoked successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"API Key revoked successfully."}}}}}},"403":{"description":"The caller is not a signed-in session (for example, the request used an API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Pass your live DAGwood API key in the `X-API-Key` header."},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API-Key / JWT","description":"Standard Bearer token header (`Authorization: Bearer <key>`)."},"FirebaseIdToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"A Firebase ID token from a signed-in session (`Authorization: Bearer <FirebaseIdToken>`)."},"SessionCookie":{"type":"apiKey","in":"cookie","name":"__session","description":"A Firebase session cookie from a signed-in session."}},"schemas":{"LeadEstimateRequest":{"type":"object","required":["industry"],"properties":{"industry":{"type":"string","description":"Target commercial industry or vertical (e.g., 'Commercial Landscaping', 'HVAC Services', 'SaaS')","example":"Commercial Landscaping"},"cityMetro":{"type":"string","description":"Target metro area or municipality","example":"Phoenix"},"stateRegion":{"type":"string","description":"Target state or geographic province","example":"Arizona"},"country":{"type":"string","description":"Target sovereign country","example":"United States"},"roles":{"type":"string","description":"Comma-separated target executive job titles","example":"Owner, Founder, Chief Executive Officer"},"channels":{"type":"string","enum":["phone_linkedin","email_linkedin","phone_only","email_only","linkedin_only"],"default":"phone_linkedin","description":"Contact channels to find:\n* `phone_linkedin` (105 Gouda/lead) - Direct Phone + Email + LinkedIn\n* `email_linkedin` (55 Gouda/lead) - Corporate Email + LinkedIn\n* `phone_only` (75 Gouda/lead) - Direct Phone Only\n* `email_only` (35 Gouda/lead) - Corporate Email Only\n* `linkedin_only` (25 Gouda/lead) - LinkedIn Profile URL Only","example":"phone_linkedin"},"volumeCount":{"type":"integer","minimum":1,"maximum":50,"default":5,"description":"Number of high-precision lead profiles to synthesize (1 to 50)","example":5}}},"LeadEstimateResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"requestId":{"type":"string","example":"req_1787612981245_40d5b895"},"status":{"type":"string","enum":["pending_approval","running","completed","cancelled","failed"],"example":"pending_approval"},"message":{"type":"string"},"costEstimate":{"type":"object","properties":{"totalGoudaCost":{"type":"integer","example":525},"unitGoudaCost":{"type":"integer","example":105},"recordCount":{"type":"integer","example":5},"currency":{"type":"string","example":"Gouda"},"estimatedUSD":{"type":"string","example":"$5.25"},"bundle":{"type":"string","example":"Direct Phone + Corporate Email + LinkedIn"},"enrichmentLevel":{"type":"string","example":"full"}}},"targeting":{"type":"object"},"actions":{"type":"object","properties":{"approve":{"type":"object","properties":{"method":{"type":"string","example":"POST"},"url":{"type":"string"},"description":{"type":"string"}}},"cancel":{"type":"object"},"status":{"type":"object"}}}}},"LeadApprovalResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"requestId":{"type":"string","example":"req_1787612981245_40d5b895"},"status":{"type":"string","example":"completed"},"message":{"type":"string"},"costCharged":{"type":"integer","nullable":true,"example":530,"description":"Everything debited for this request (the search fee and the bundle price), read back from the ledger; null when it could not be confirmed."},"bundleGouda":{"type":"integer","example":525,"description":"Bundle price of the delivered leads (leads x unit), debited once on approval."},"leadCount":{"type":"integer","example":5},"leads":{"type":"array","items":{"$ref":"#/components/schemas/LeadRecord"}}}},"LeadRecord":{"type":"object","properties":{"id":{"type":"string","example":"lead_1_1787613002008"},"name":{"type":"string","example":"Sample Lead"},"role":{"type":"string","example":"President"},"company":{"type":"string","example":"Sample Heating and Cooling Co."},"domain":{"type":"string","example":"example.com"},"industry":{"type":"string","example":"HVAC Services"},"location":{"type":"string","example":"Phoenix, Arizona, United States"},"phone":{"type":"string","nullable":true,"example":"+1-602-555-0110"},"phoneType":{"type":"string","example":"Direct Mobile"},"phoneConfidence":{"type":"string","enum":["high","medium","low","none"],"example":"high"},"phoneCitation":{"type":"string","example":"Example citation (sample data)"},"email":{"type":"string","nullable":true,"example":"sample.lead@example.com"},"emailConfidence":{"type":"string","enum":["high","medium","low","none"],"example":"high"},"emailCitation":{"type":"string","example":"Example citation (sample data)"},"emailSource":{"type":"string","enum":["wiza","ai_research"],"nullable":true,"description":"Where the email came from"},"phoneSource":{"type":"string","enum":["wiza","ai_research"],"nullable":true,"description":"Where the phone number came from"},"linkedin":{"type":"string","nullable":true,"example":"https://example.com/profiles/sample-lead"},"salesMatchSummary":{"type":"string","example":"Example match summary (sample data)."},"companyCitation":{"type":"object","properties":{"domain":{"type":"string","example":"example.com"},"headquarters":{"type":"string","example":"Phoenix, AZ"},"employeeCount":{"type":"integer","example":25},"foundedYear":{"type":"integer","example":2005}}}}},"ApiKeyRecord":{"type":"object","properties":{"keyId":{"type":"string","example":"BVNgT4q8nwb2opeWUAHX"},"name":{"type":"string","example":"TaskBullet Production API Key"},"prefix":{"type":"string","example":"dag_test_EXA..."},"customer":{"type":"string","example":"TaskBullet"},"revoked":{"type":"boolean","example":false},"usageCount":{"type":"integer","example":12},"allowedDomains":{"type":"array","items":{"type":"string"},"example":["taskbullet.com","*.taskbullet.com"]}}},"NeedsInputResponse":{"type":"object","required":["success","status","question","missing"],"description":"Returned with HTTP 200 when the plan or the combo reports a required input still empty. No bundle is built.","properties":{"success":{"type":"boolean","example":true},"status":{"type":"string","enum":["needs_input"],"example":"needs_input"},"question":{"type":"object","properties":{"field":{"type":"string","description":"The first missing input.","example":"businessName"},"text":{"type":"string","example":"Happy to build that! What should I use for the business name?"},"hint":{"type":"string","nullable":true,"description":"The input's own description, when the template gives one."}}},"missing":{"type":"array","items":{"type":"string"},"description":"Every required input still missing, in order.","example":["businessName"]}}},"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Forbidden: Origin 'https://unauthorized.com' is not authorized."},"code":{"type":"integer","example":403},"support":{"type":"string","example":"We resolve errors ASAP - call us at +1 (442) 777-6633 and a real person will work with you live to fix."},"supportPhone":{"type":"string","example":"+1 (442) 777-6633"}}},"DiscoveryResponse":{"type":"object","properties":{"name":{"type":"string","example":"DAGwood Lead Synthesis & Enrichment API (Cloud Function)"},"version":{"type":"string","example":"v1.0.0"},"description":{"type":"string"},"openapi":{"type":"string","example":"https://api.dagwood.ai/openapi.json"},"swagger":{"type":"string","example":"https://api.dagwood.ai/swagger.json"},"supportPhone":{"type":"string","example":"+1 (442) 777-6633"}}}}}}