{"openapi":"3.1.0","info":{"title":"Gold Standard Analytics Agent API","version":"2026-07-17","description":"Customer-bound API for catalog discovery, quotes, laboratory orders, Mercury invoicing, Ethereum-mainnet native USDC verification, shipping, QA-published results, released instrument files, and signed webhooks. Monetary values are integer cents. Mutations require scoped keys, explicit confirmation, and idempotency keys."},"servers":[{"url":"https://www.goldstandardanalytics.com/api/v1/agent"}],"externalDocs":{"description":"Stateless MCP endpoint (protocol 2025-11-25)","url":"https://www.goldstandardanalytics.com/api/mcp"},"components":{"securitySchemes":{"agentBearer":{"type":"http","scheme":"bearer","bearerFormat":"gsa_live_<public-id>_<secret>"}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}}}}},"CreateOrderRequest":{"type":"object","additionalProperties":false,"required":["quoteId","paymentMethod","confirm"],"properties":{"quoteId":{"type":"string","format":"uuid"},"paymentMethod":{"type":"string","enum":["mercury_invoice","ethereum_usdc"]},"expectedPayerAddress":{"type":"string","maxLength":100,"description":"Self-custodied Ethereum sender address. USDC instructions return a permanent sub-cent reference and exact six-decimal amount that must not be rounded. Use Mercury for exchange or pooled-wallet withdrawals."},"clientReference":{"type":"string","minLength":1,"maxLength":120},"notes":{"type":"string","maxLength":4000},"publishRawData":{"type":"boolean","default":true},"billingAddressId":{"type":"string","format":"uuid"},"shippingAddressId":{"type":"string","format":"uuid"},"sampleMetadata":{"type":"array","maxItems":50,"description":"Optional unique subset of locked quote compounds. This metadata cannot modify category, price, sample count, tests, or any other commercial field.","items":{"type":"object","additionalProperties":false,"required":["compoundName"],"anyOf":[{"required":["lotNumber"]},{"required":["matrixNotes"]}],"properties":{"compoundName":{"type":"string","minLength":1,"maxLength":200,"description":"Exact, case-sensitive compound name from the locked quote."},"lotNumber":{"type":"string","maxLength":200},"matrixNotes":{"type":"string","maxLength":2000}}}},"confirm":{"type":"boolean","const":true}}},"RawDataManifest":{"type":"object","additionalProperties":false,"required":["order","generatedAt","expiresAt","files"],"properties":{"order":{"type":"object","additionalProperties":false,"required":["id","orderNumber"],"properties":{"id":{"type":"string","format":"uuid"},"orderNumber":{"type":"string"}}},"generatedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time","description":"Expiry shared by every signed URL in this manifest (one hour after generation)."},"files":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["importId","resultSetId","vendor","filename","sha256","downloadUrl","nativeBundleUrl","metadata"],"properties":{"importId":{"type":"string","format":"uuid"},"resultSetId":{"type":"string","format":"uuid"},"vendor":{"type":"string"},"filename":{"type":"string"},"mimeType":{"type":["string","null"]},"sizeBytes":{"type":["integer","null"],"minimum":0},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"Server-computed SHA-256 for downloadUrl."},"downloadUrl":{"type":"string","format":"uri"},"nativeBundleUrl":{"type":["string","null"],"format":"uri"},"metadata":{"type":"object","additionalProperties":false,"description":"Release-safe instrument and COA provenance metadata. Internal storage coordinates and parser raw payloads are never returned.","required":["clientSha256","parserVersion","connectorVersion","sampleIdentifier","runIdentifier","instrumentName","acquiredAt","importedAt","integrityVerifiedAt","releases"],"properties":{"clientSha256":{"type":["string","null"],"pattern":"^[0-9a-f]{64}$"},"parserVersion":{"type":"string"},"connectorVersion":{"type":["string","null"]},"sampleIdentifier":{"type":["string","null"]},"runIdentifier":{"type":["string","null"]},"instrumentName":{"type":["string","null"]},"acquiredAt":{"type":["string","null"],"format":"date-time"},"importedAt":{"type":"string","format":"date-time"},"integrityVerifiedAt":{"type":["string","null"],"format":"date-time"},"releases":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["coaId","accessionNumber","publishedAt"],"properties":{"coaId":{"type":"string","format":"uuid"},"accessionNumber":{"type":"string"},"publishedAt":{"type":["string","null"],"format":"date-time"}}}}}}}}}}}}},"security":[{"agentBearer":[]}],"paths":{"/catalog":{"get":{"operationId":"listCatalog","summary":"List tests, pricing, bundles, and sample requirements","parameters":[{"name":"category","in":"query","schema":{"type":"string"}},{"name":"query","in":"query","schema":{"type":"string"}},{"name":"include","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"401":{"description":"Invalid or missing API key"},"403":{"description":"Missing scope or spend authorization"},"409":{"description":"Conflict or idempotency collision"},"429":{"description":"Rate limited"}}}},"/quotes":{"post":{"operationId":"createQuote","summary":"Create a locked, expiring server quote","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Successful response"},"201":{"description":"Quote created"},"400":{"description":"Invalid request"},"401":{"description":"Invalid or missing API key"},"403":{"description":"Missing scope or spend authorization"},"409":{"description":"Conflict or idempotency collision"},"429":{"description":"Rate limited"}}}},"/orders":{"get":{"operationId":"listOrders","summary":"List orders","responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"401":{"description":"Invalid or missing API key"},"403":{"description":"Missing scope or spend authorization"},"409":{"description":"Conflict or idempotency collision"},"429":{"description":"Rate limited"}}},"post":{"operationId":"createOrder","summary":"Create an order from a quote","description":"The quote's stored commercial rows remain authoritative. sampleMetadata may overlay only lot_number and matrix_notes after an exact compound-name match. Ethereum USDC responses include amount.atomic, exact six-decimal amount.decimal, amount.referenceAtomic, and a no-rounding notice; the sender must be self-custodied.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrderRequest"}}}},"responses":{"200":{"description":"Successful response"},"201":{"description":"Order created"},"400":{"description":"Invalid request"},"401":{"description":"Invalid or missing API key"},"403":{"description":"Missing scope or spend authorization"},"409":{"description":"Conflict or idempotency collision"},"429":{"description":"Rate limited"}}}},"/orders/{reference}":{"get":{"operationId":"getOrder","summary":"Get order detail and status","parameters":[{"name":"reference","in":"path","required":true,"description":"Resource UUID or public order/invoice/tracking/accession reference","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"401":{"description":"Invalid or missing API key"},"403":{"description":"Missing scope or spend authorization"},"409":{"description":"Conflict or idempotency collision"},"429":{"description":"Rate limited"}}}},"/orders/{reference}/raw-data":{"get":{"operationId":"getOrderRawData","summary":"Get QA-released instrument files for an order","description":"Requires raw_data:read. Resolves only a customer-owned order with publishRawData enabled and at least one published COA. Returns one-hour signed URLs; absent, cross-customer, disabled, and unpublished resources all return the same generic 404.","x-required-scopes":["raw_data:read"],"parameters":[{"name":"reference","in":"path","required":true,"description":"Resource UUID or public order/invoice/tracking/accession reference","schema":{"type":"string"}}],"responses":{"200":{"description":"Released raw-data manifest","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["rawData"],"properties":{"rawData":{"$ref":"#/components/schemas/RawDataManifest"}}}}}}}},"400":{"description":"Invalid request"},"401":{"description":"Invalid or missing API key"},"403":{"description":"Missing scope or spend authorization"},"404":{"description":"Resource not found or not released"},"409":{"description":"Conflict or idempotency collision"},"429":{"description":"Rate limited"},"503":{"description":"Released files could not be signed"}}}},"/invoices":{"get":{"operationId":"listInvoices","summary":"List invoice metadata","responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"401":{"description":"Invalid or missing API key"},"403":{"description":"Missing scope or spend authorization"},"409":{"description":"Conflict or idempotency collision"},"429":{"description":"Rate limited"}}}},"/invoices/{reference}":{"get":{"operationId":"getInvoice","summary":"Get Mercury or USDC invoice metadata","parameters":[{"name":"reference","in":"path","required":true,"description":"Resource UUID or public order/invoice/tracking/accession reference","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"401":{"description":"Invalid or missing API key"},"403":{"description":"Missing scope or spend authorization"},"409":{"description":"Conflict or idempotency collision"},"429":{"description":"Rate limited"}}}},"/payments":{"get":{"operationId":"listPayments","summary":"List payments","responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"401":{"description":"Invalid or missing API key"},"403":{"description":"Missing scope or spend authorization"},"409":{"description":"Conflict or idempotency collision"},"429":{"description":"Rate limited"}}}},"/payments/{reference}":{"get":{"operationId":"getPayment","summary":"Get Mercury or USDC payment state","parameters":[{"name":"reference","in":"path","required":true,"description":"Resource UUID or public order/invoice/tracking/accession reference","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"401":{"description":"Invalid or missing API key"},"403":{"description":"Missing scope or spend authorization"},"409":{"description":"Conflict or idempotency collision"},"429":{"description":"Rate limited"}}}},"/payments/prepare":{"post":{"operationId":"retryPaymentPreparation","summary":"Retry payment preparation for an order","description":"Ethereum USDC responses include the exact six-decimal amount and permanent sub-cent reference. Pay it without rounding from the stated self-custodied sender; use Mercury for pooled or exchange withdrawals.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"401":{"description":"Invalid or missing API key"},"403":{"description":"Missing scope or spend authorization"},"409":{"description":"Conflict or idempotency collision"},"429":{"description":"Rate limited"}}}},"/payments/usdc/submit":{"post":{"operationId":"submitUsdcTransaction","summary":"Verify a payer-submitted Ethereum USDC transaction hash","description":"Read-only chain verification of the exact referenced atomic amount from the instructed self-custodied sender. The service never signs or broadcasts a transaction.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"401":{"description":"Invalid or missing API key"},"403":{"description":"Missing scope or spend authorization"},"409":{"description":"Conflict or idempotency collision"},"429":{"description":"Rate limited"}}}},"/shipments":{"get":{"operationId":"listShipments","summary":"List labels and shipments","responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"401":{"description":"Invalid or missing API key"},"403":{"description":"Missing scope or spend authorization"},"409":{"description":"Conflict or idempotency collision"},"429":{"description":"Rate limited"}}}},"/shipments/{reference}":{"get":{"operationId":"getShipment","summary":"Get tracking and carrier event history","parameters":[{"name":"reference","in":"path","required":true,"description":"Resource UUID or public order/invoice/tracking/accession reference","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"401":{"description":"Invalid or missing API key"},"403":{"description":"Missing scope or spend authorization"},"409":{"description":"Conflict or idempotency collision"},"429":{"description":"Rate limited"}}}},"/results":{"get":{"operationId":"listPublishedResults","summary":"List QA-published results only","responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"401":{"description":"Invalid or missing API key"},"403":{"description":"Missing scope or spend authorization"},"409":{"description":"Conflict or idempotency collision"},"429":{"description":"Rate limited"}}}},"/results/{reference}":{"get":{"operationId":"getPublishedResult","summary":"Get a published COA and structured results","parameters":[{"name":"reference","in":"path","required":true,"description":"Resource UUID or public order/invoice/tracking/accession reference","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"401":{"description":"Invalid or missing API key"},"403":{"description":"Missing scope or spend authorization"},"409":{"description":"Conflict or idempotency collision"},"429":{"description":"Rate limited"}}}},"/webhooks":{"get":{"operationId":"listWebhooks","summary":"List safe endpoint metadata","responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"401":{"description":"Invalid or missing API key"},"403":{"description":"Missing scope or spend authorization"},"409":{"description":"Conflict or idempotency collision"},"429":{"description":"Rate limited"}}},"post":{"operationId":"createWebhook","summary":"Register an SSRF-validated HTTPS endpoint","description":"Supported events: order.created, order.status_changed, order.cancelled, invoice.created, invoice.updated, payment.requested, payment.observed, payment.confirming, payment.confirmed, payment.reorged, payment.expired, shipment.label_created, shipment.updated, sample.received, testing.started, results.published, coa.published, coa.retracted. The plaintext signing secret is returned after creation and may be recovered only by the same API key replaying the identical idempotent request while its replay record is retained.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Successful response"},"201":{"description":"Endpoint created"},"400":{"description":"Invalid request"},"401":{"description":"Invalid or missing API key"},"403":{"description":"Missing scope or spend authorization"},"409":{"description":"Conflict or idempotency collision"},"429":{"description":"Rate limited"}}}},"/webhooks/{endpointId}":{"delete":{"operationId":"deleteWebhook","summary":"Delete an endpoint","parameters":[{"name":"endpointId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"401":{"description":"Invalid or missing API key"},"403":{"description":"Missing scope or spend authorization"},"409":{"description":"Conflict or idempotency collision"},"429":{"description":"Rate limited"}}}},"/webhooks/{endpointId}/rotate-secret":{"post":{"operationId":"rotateWebhookSecret","summary":"Rotate a signing secret with idempotent recovery","parameters":[{"name":"endpointId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"401":{"description":"Invalid or missing API key"},"403":{"description":"Missing scope or spend authorization"},"409":{"description":"Conflict or idempotency collision"},"429":{"description":"Rate limited"}}}},"/webhooks/{endpointId}/test":{"post":{"operationId":"testWebhook","summary":"Queue and attempt a signed test delivery","parameters":[{"name":"endpointId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"401":{"description":"Invalid or missing API key"},"403":{"description":"Missing scope or spend authorization"},"409":{"description":"Conflict or idempotency collision"},"429":{"description":"Rate limited"}}}}}}