{"openapi":"3.1.0","info":{"title":"Vulcan Lipids Agent Intake API","version":"1.7.0","description":"Agents can submit customer-approved nonbinding custom lipid requests directly. No payment details, checkout or firm quantity are needed to start. Clarify the molecule and initiate chemist review and pricing discussion; a purchase commitment follows an agreed quote.","contact":{"name":"Vulcan Lipids","url":"https://vulcanlipids.com/request"}},"servers":[{"url":"https://vulcanlipids.com"}],"tags":[{"name":"Discovery","description":"Public, read-only capability information."},{"name":"Inquiry","description":"Prepare and submit nonbinding feasibility inquiries."}],"paths":{"/api/v1/connections":{"get":{"operationId":"getAgentConnectionGuide","summary":"Read documented client setup routes and integration testing qualifications","tags":["Discovery"],"responses":{"200":{"description":"Dated connection guide with official provider links","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/llms-full.txt":{"get":{"operationId":"getAgentConversationGuide","summary":"Read the direct workflow, nonbinding introduction and chemistry scenario bank","tags":["Discovery"],"responses":{"200":{"description":"Plain-text instructions and illustrative questions","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/api/v1/structures/discover":{"post":{"operationId":"discoverDrawingTargets","summary":"Propose separate drawing panels or native records for confirmation","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["bundle_id","access_token"],"properties":{"bundle_id":{"type":"string"},"access_token":{"type":"string"},"context":{"type":"string"},"ai_consent":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Proposed candidates with file IDs, locations, role uncertainty, and requires_confirmation=true"}}}},"/api/v1/inquiries/receipt":{"post":{"operationId":"getInquiryReceipt","summary":"Check private inquiry delivery status without resending","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["receipt_token"],"properties":{"receipt_token":{"type":"string"}}}}}},"responses":{"200":{"description":"Reference, status and target count"},"403":{"description":"Expired, invalid or different-account receipt access"}}}},"/api/v1/inquiries/draft":{"post":{"operationId":"saveOrLoadInquiryDraft","summary":"Privately save or resume a seven-day inquiry draft","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["save","load"]},"draft_id":{"type":"string"},"access_token":{"type":"string"},"data":{"type":"object"}}}}}},"responses":{"200":{"description":"Draft ID, private access token, expiry and draft data"},"403":{"description":"Expired or invalid draft access"}}}},"/api/v1/structures":{"post":{"operationId":"uploadChemicalStructure","summary":"Privately upload one structure file","description":"Up to five files, 5 MB each, 15 MB total. Draft access expires after seven days. Store the returned access token privately. Binary CDX needs a PDF/image companion for visual interpretation.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"},"bundle_id":{"type":"string"},"access_token":{"type":"string"}}}}}},"responses":{"200":{"description":"Private bundle ID, access token and file manifest"},"413":{"description":"Upload limit exceeded"}}},"delete":{"operationId":"removeDraftStructure","summary":"Remove a file from a draft; invalidates review","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["bundle_id","access_token","file_id"],"properties":{"bundle_id":{"type":"string"},"access_token":{"type":"string"},"file_id":{"type":"string"}}}}}},"responses":{"200":{"description":"Updated file manifest"}}}},"/api/v1/structures/review":{"get":{"operationId":"getStructureReviewStatus","summary":"Get AI availability and upload limits","responses":{"200":{"description":"Review service status"}}},"post":{"operationId":"reviewChemicalStructures","summary":"Prepare pre-submission structure clarification questions","description":"List each requested molecule in targets with its own source file/page/panel, working name, quantity and specifications, even when one file contains all targets. Maximum 20 targets. Supply the same project object and target list that will be submitted. Returns an AI review only when configured and ai_consent is true; otherwise a clearly labeled checklist. AI scope is at most ten PDF pages combined and 80,000 characters per native text file. Skipped files are disclosed. Answer every issue ID; unknown is acceptable. Changing a target, quantity, file or project requires re-review. Acknowledgement confirms all targets and clarification answers.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["bundle_id","access_token","project","targets"],"properties":{"bundle_id":{"type":"string"},"access_token":{"type":"string"},"project":{"type":"object","additionalProperties":false,"properties":{"original_request":{"type":"string"},"molecule_name":{"type":"string"},"lipid_family":{"type":"string"},"backbone":{"type":"string"},"headgroup":{"type":"string"},"sn1":{"type":"string"},"sn2":{"type":"string"},"linkage":{"type":"string"},"double_bond_positions_and_geometry":{"type":"string"},"stereochemistry":{"type":"string"},"lyso_position":{"type":"string"},"isotope_label":{"type":"string"},"functional_handle":{"type":"string"},"salt_or_counterion":{"type":"string"},"smiles":{"type":"string"},"inchi":{"type":"string"},"inchikey":{"type":"string"},"total_quantity":{"type":"string","description":"Amount or researcher-confirmed planning range with units, if known. Otherwise Choose after pricing. Not a purchase commitment."},"vial_count":{"type":"integer","minimum":1,"maximum":1000},"presentation":{"type":"string"},"purity_target":{"type":"string"},"analysis":{"type":"string"},"application":{"type":"string"},"desired_date":{"type":"string"},"notes":{"type":"string"}}},"targets":{"type":"array","minItems":1,"maxItems":20,"description":"One entry per requested molecule, even when several drawings share one file. Exclude intermediates and reference-only drawings. Preserve unknown identity. Quantities apply to each target separately.","items":{"type":"object","additionalProperties":false,"required":["id","file_id","location","name","specifications"],"properties":{"id":{"type":"string","maxLength":50,"pattern":"^[A-Za-z0-9_-]+$","description":"Unique target ID kept stable through review and submission."},"file_id":{"type":"string","maxLength":50,"description":"Uploaded source file ID."},"location":{"type":"string","maxLength":240,"description":"Page and panel, drawing label, or SDF/SMILES record number."},"name":{"type":"string","maxLength":200,"description":"Working name or label; do not invent an exact chemical identity."},"quantity":{"type":"string","maxLength":160,"description":"Optional amount for this target with units. Omit or leave blank to choose after pricing; Vulcan will discuss quantity and pricing options."},"specifications":{"type":"string","maxLength":2000,"description":"Target-specific packaging, purity or other requirements; unknown is allowed."}}}},"ai_consent":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Review ID, summary, mode and stable clarification issue IDs"},"400":{"description":"Missing or invalid target list; actionable message returned"},"403":{"description":"Invalid or expired upload access"},"409":{"description":"Concurrent draft change; review again"}}}},"/api/v1/structures/file":{"get":{"operationId":"readChemicalStructure","summary":"Download original uploaded bytes with private access","parameters":[{"name":"bundle_id","in":"query","schema":{"type":"string"}},{"name":"access_token","in":"query","schema":{"type":"string"}},{"name":"file_id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Original file bytes"},"403":{"description":"Invalid or expired access"}}}},"/api/v1/capabilities":{"get":{"operationId":"getCustomLipidCapabilities","summary":"Get Vulcan’s published custom lipid discussion scope","tags":["Discovery"],"responses":{"200":{"description":"Capability document","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/inquiries/validate":{"post":{"operationId":"prepareCustomLipidBrief","summary":"Prepare a draft and unanswered chemistry or reply-contact questions","tags":["Inquiry"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"original_request":{"type":"string"},"molecule_name":{"type":"string"},"lipid_family":{"type":"string"},"backbone":{"type":"string"},"headgroup":{"type":"string"},"sn1":{"type":"string"},"sn2":{"type":"string"},"linkage":{"type":"string"},"double_bond_positions_and_geometry":{"type":"string"},"stereochemistry":{"type":"string"},"lyso_position":{"type":"string"},"isotope_label":{"type":"string"},"functional_handle":{"type":"string"},"salt_or_counterion":{"type":"string"},"smiles":{"type":"string"},"inchi":{"type":"string"},"inchikey":{"type":"string"},"total_quantity":{"type":"string","description":"Amount or researcher-confirmed planning range with units, if known. Otherwise Choose after pricing. Not a purchase commitment."},"vial_count":{"type":"integer","minimum":1,"maximum":1000},"presentation":{"type":"string"},"purity_target":{"type":"string"},"analysis":{"type":"string"},"application":{"type":"string"},"desired_date":{"type":"string"},"notes":{"type":"string"},"requester":{"type":"object","required":[],"properties":{"name":{"type":"string","maxLength":240},"email":{"type":"string","format":"email","maxLength":240},"organization":{"type":"string","maxLength":240},"phone":{"type":"string","maxLength":240},"shipping_address":{"type":"string","maxLength":1000,"description":"Optional researcher-approved delivery address or destination for planning. May be deferred until a quote; never required for an initial inquiry."}},"additionalProperties":false}}}}}},"responses":{"200":{"description":"Prepared brief with clarification questions","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/inquiries":{"post":{"operationId":"submitCustomLipidInquiry","summary":"Submit a researcher-approved feasibility inquiry for chemist review","description":"Creates an inquiry only. It does not create an order, quote, price, delivery commitment, or payment obligation.","tags":["Inquiry"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["requester","project","human_confirmed","idempotency_key"],"additionalProperties":false,"properties":{"idempotency_key":{"type":"string","minLength":16,"maxLength":120,"description":"One stable key per approved brief. Reuse it unchanged on retries to get the same receipt without another email."},"requester":{"type":"object","required":["name","email"],"properties":{"name":{"type":"string","maxLength":240},"email":{"type":"string","format":"email","maxLength":240},"organization":{"type":"string","maxLength":240},"phone":{"type":"string","maxLength":240},"shipping_address":{"type":"string","maxLength":1000,"description":"Optional researcher-approved delivery address or destination for planning. May be deferred until a quote; never required for an initial inquiry."}},"additionalProperties":false},"project":{"type":"object","additionalProperties":false,"properties":{"original_request":{"type":"string"},"molecule_name":{"type":"string"},"lipid_family":{"type":"string"},"backbone":{"type":"string"},"headgroup":{"type":"string"},"sn1":{"type":"string"},"sn2":{"type":"string"},"linkage":{"type":"string"},"double_bond_positions_and_geometry":{"type":"string"},"stereochemistry":{"type":"string"},"lyso_position":{"type":"string"},"isotope_label":{"type":"string"},"functional_handle":{"type":"string"},"salt_or_counterion":{"type":"string"},"smiles":{"type":"string"},"inchi":{"type":"string"},"inchikey":{"type":"string"},"total_quantity":{"type":"string","description":"Amount or researcher-confirmed planning range with units, if known. Otherwise Choose after pricing. Not a purchase commitment."},"vial_count":{"type":"integer","minimum":1,"maximum":1000},"presentation":{"type":"string"},"purity_target":{"type":"string"},"analysis":{"type":"string"},"application":{"type":"string"},"desired_date":{"type":"string"},"notes":{"type":"string"}}},"human_confirmed":{"type":"boolean","const":true},"structures":{"type":"object","required":["bundle_id","access_token","review_id","targets","answers","acknowledged"],"additionalProperties":false,"properties":{"bundle_id":{"type":"string"},"access_token":{"type":"string","description":"Private upload access token. Never publish it or include it in the project description."},"review_id":{"type":"string"},"targets":{"type":"array","minItems":1,"maxItems":20,"description":"One entry per requested molecule, even when several drawings share one file. Exclude intermediates and reference-only drawings. Preserve unknown identity. Quantities apply to each target separately.","items":{"type":"object","additionalProperties":false,"required":["id","file_id","location","name","specifications"],"properties":{"id":{"type":"string","maxLength":50,"pattern":"^[A-Za-z0-9_-]+$","description":"Unique target ID kept stable through review and submission."},"file_id":{"type":"string","maxLength":50,"description":"Uploaded source file ID."},"location":{"type":"string","maxLength":240,"description":"Page and panel, drawing label, or SDF/SMILES record number."},"name":{"type":"string","maxLength":200,"description":"Working name or label; do not invent an exact chemical identity."},"quantity":{"type":"string","maxLength":160,"description":"Optional amount for this target with units. Omit or leave blank to choose after pricing; Vulcan will discuss quantity and pricing options."},"specifications":{"type":"string","maxLength":2000,"description":"Target-specific packaging, purity or other requirements; unknown is allowed."}}}},"answers":{"type":"object","additionalProperties":{"type":"string","maxLength":2000}},"acknowledged":{"type":"boolean","const":true,"description":"True only after the researcher confirmed the complete target list, separate quantities, files, questions and answers."}}},"source_agent":{"type":"string"}}}}}},"responses":{"202":{"description":"Inquiry accepted for chemist review","content":{"application/json":{"schema":{"type":"object"}}}},"409":{"description":"Explicit researcher confirmation is required"},"422":{"description":"Molecular identity is missing"},"503":{"description":"Inquiry delivery is temporarily unavailable"}}}},"/api/v1/status":{"get":{"operationId":"getAgentIntakeStatus","summary":"Get the current agent-intake service status","tags":["Discovery"],"responses":{"200":{"description":"Service status"}}}}}}