{"openapi":"3.1.0","info":{"title":"Tesseract Agent API","version":"0.1.0","description":"Generate designs using Tesseract, inspect a private model preview, request quotes, and open human checkout. New billable operations are disabled until configured. An outcome_unknown requires reconciliation, not another submission. Public signup uses Apple or Google; a provider account is not proof of one unique human."},"servers":[{"url":"https://agents.tesseract.build"}],"paths":{"/v1/me":{"get":{"operationId":"getCurrentUser","summary":"Test this connection safely; does not generate or quote","security":[{"oauth":[]}],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["id","connectionId","scopes"],"properties":{"id":{"type":"string","format":"uuid"},"connectionId":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Connect or refresh your token"},"403":{"description":"Required scope not granted"},"404":{"description":"Not found or owned by someone else"},"409":{"description":"Idempotency conflict or fresh quote required"},"429":{"description":"Allowance, budget or capacity exhausted; observe Retry-After"},"503":{"description":"Admission disabled or service unavailable"}}}},"/v1/usage":{"get":{"operationId":"getUsage","summary":"Read remaining account limits and accepted usage","security":[{"oauth":["usage:read"]}],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"usage":{"type":"array","items":{"type":"object","properties":{"kind":{"enum":["generation","quote"]},"used":{"type":"integer"},"remaining":{"type":"integer"},"reserved_micros":{"type":"string"},"active":{"type":"integer"},"unresolved":{"type":"integer"}}}},"limits":{"type":"object","properties":{"generationsPerDay":{"type":"integer"},"quotesPerDay":{"type":"integer"}}},"reset":{"type":"string"},"costUnit":{"type":"string"}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Connect or refresh your token"},"403":{"description":"Required scope not granted"},"404":{"description":"Not found or owned by someone else"},"409":{"description":"Idempotency conflict or fresh quote required"},"429":{"description":"Allowance, budget or capacity exhausted; observe Retry-After"},"503":{"description":"Admission disabled or service unavailable"}}}},"/v1/materials":{"get":{"operationId":"listMaterials","summary":"List currently available print materials","security":[{"oauth":["quotes:read"]}],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"materials":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string"},"hex":{"type":"string"}}}}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Connect or refresh your token"},"403":{"description":"Required scope not granted"},"404":{"description":"Not found or owned by someone else"},"409":{"description":"Idempotency conflict or fresh quote required"},"429":{"description":"Allowance, budget or capacity exhausted; observe Retry-After"},"503":{"description":"Admission disabled or service unavailable"}}}},"/v1/generations":{"post":{"operationId":"generateDesign","summary":"Generate or refine a design; dimensions are millimeters, photo dimensions are estimates","security":[{"oauth":["designs:generate"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"},"description":"Use the same key when retrying identical input. Different input with a used key returns 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"prompt":{"type":"string","minLength":1,"maxLength":6000},"image":{"type":"string","maxLength":1500000,"pattern":"^data:image\\/(png|jpeg);base64,[A-Za-z0-9+/]+={0,2}$"},"parentDesignId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["prompt"],"additionalProperties":false}}}},"responses":{"202":{"description":"Accepted. Poll the returned id no faster than Retry-After.","content":{"application/json":{"schema":{"type":"object","required":["id","status","pollAfterSeconds"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["accepted","running","ready","failed","outcome_unknown"]},"error":{"type":"string"},"pollAfterSeconds":{"type":"integer","minimum":5},"expiresAt":{"type":"string","format":"date-time"},"checkoutReady":{"type":"boolean"},"result":{"type":"object","properties":{"designId":{"type":"string","format":"uuid"},"amount":{"type":"integer","description":"Total including shipping, in minor currency units (USD cents)."},"currency":{"type":"string"},"meshHash":{"type":"string"},"quantity":{"type":"integer"},"materialId":{"type":"string"},"sizeMm":{"type":"array","items":{"type":"number"},"minItems":3,"maxItems":3},"units":{"const":"mm"}}}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Connect or refresh your token"},"403":{"description":"Required scope not granted"},"404":{"description":"Not found or owned by someone else"},"409":{"description":"Idempotency conflict or fresh quote required"},"429":{"description":"Allowance, budget or capacity exhausted; observe Retry-After"},"503":{"description":"Admission disabled or service unavailable"}}}},"/v1/generations/{id}":{"get":{"operationId":"getGeneration","summary":"Poll generation; repeated reads never restart work","security":[{"oauth":["designs:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["id","status","pollAfterSeconds"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["accepted","running","ready","failed","outcome_unknown"]},"error":{"type":"string"},"pollAfterSeconds":{"type":"integer","minimum":5},"expiresAt":{"type":"string","format":"date-time"},"checkoutReady":{"type":"boolean"},"result":{"type":"object","properties":{"designId":{"type":"string","format":"uuid"},"amount":{"type":"integer","description":"Total including shipping, in minor currency units (USD cents)."},"currency":{"type":"string"},"meshHash":{"type":"string"},"quantity":{"type":"integer"},"materialId":{"type":"string"},"sizeMm":{"type":"array","items":{"type":"number"},"minItems":3,"maxItems":3},"units":{"const":"mm"}}}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Connect or refresh your token"},"403":{"description":"Required scope not granted"},"404":{"description":"Not found or owned by someone else"},"409":{"description":"Idempotency conflict or fresh quote required"},"429":{"description":"Allowance, budget or capacity exhausted; observe Retry-After"},"503":{"description":"Admission disabled or service unavailable"}}}},"/v1/designs/{id}":{"get":{"operationId":"getDesign","summary":"Read parameters, measurements and private preview link","security":[{"oauth":["designs:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"revision":{"type":"string"},"partName":{"type":"string"},"explanation":{"type":"string"},"parameters":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"default":{"type":"number"},"min":{"type":"number"},"max":{"type":"number"},"step":{"type":"number"},"unit":{"type":"string"}}}},"sizeMm":{"type":"array","items":{"type":"number"},"minItems":3,"maxItems":3},"volumeCm3":{"type":"number"},"units":{"const":"mm"},"estimatedFromImage":{"type":"boolean"},"supportNote":{"type":["string","null"]},"previewUrl":{"type":"string","format":"uri"},"stlUrl":{"type":"string","format":"uri"}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Connect or refresh your token"},"403":{"description":"Required scope not granted"},"404":{"description":"Not found or owned by someone else"},"409":{"description":"Idempotency conflict or fresh quote required"},"429":{"description":"Allowance, budget or capacity exhausted; observe Retry-After"},"503":{"description":"Admission disabled or service unavailable"}}}},"/v1/quotes":{"post":{"operationId":"createPrintQuote","summary":"Request one quote for an exact design, material, quantity and address; ask the user to confirm these first","security":[{"oauth":["quotes:create"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"},"description":"Use the same key when retrying identical input. Different input with a used key returns 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"designId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"materialId":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,100}$"},"quantity":{"type":"integer","minimum":1,"maximum":20},"email":{"type":"string","maxLength":254,"format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"address":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":150},"line1":{"type":"string","minLength":1,"maxLength":150},"line2":{"type":"string","maxLength":150},"city":{"type":"string","minLength":1,"maxLength":150},"state":{"type":"string","maxLength":100},"zip":{"type":"string","minLength":1,"maxLength":150},"country":{"type":"string","pattern":"^[A-Z]{2}$"}},"required":["name","line1","city","zip","country"],"additionalProperties":false}},"required":["designId","materialId","quantity","email","address"],"additionalProperties":false}}}},"responses":{"202":{"description":"Accepted. Poll the returned id no faster than Retry-After.","content":{"application/json":{"schema":{"type":"object","required":["id","status","pollAfterSeconds"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["accepted","running","ready","failed","outcome_unknown"]},"error":{"type":"string"},"pollAfterSeconds":{"type":"integer","minimum":5},"expiresAt":{"type":"string","format":"date-time"},"checkoutReady":{"type":"boolean"},"result":{"type":"object","properties":{"designId":{"type":"string","format":"uuid"},"amount":{"type":"integer","description":"Total including shipping, in minor currency units (USD cents)."},"currency":{"type":"string"},"meshHash":{"type":"string"},"quantity":{"type":"integer"},"materialId":{"type":"string"},"sizeMm":{"type":"array","items":{"type":"number"},"minItems":3,"maxItems":3},"units":{"const":"mm"}}}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Connect or refresh your token"},"403":{"description":"Required scope not granted"},"404":{"description":"Not found or owned by someone else"},"409":{"description":"Idempotency conflict or fresh quote required"},"429":{"description":"Allowance, budget or capacity exhausted; observe Retry-After"},"503":{"description":"Admission disabled or service unavailable"}}}},"/v1/quotes/{id}":{"get":{"operationId":"getPrintQuote","summary":"Read quoted amount in minor currency units and expiry","security":[{"oauth":["quotes:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["id","status","pollAfterSeconds"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["accepted","running","ready","failed","outcome_unknown"]},"error":{"type":"string"},"pollAfterSeconds":{"type":"integer","minimum":5},"expiresAt":{"type":"string","format":"date-time"},"checkoutReady":{"type":"boolean"},"result":{"type":"object","properties":{"designId":{"type":"string","format":"uuid"},"amount":{"type":"integer","description":"Total including shipping, in minor currency units (USD cents)."},"currency":{"type":"string"},"meshHash":{"type":"string"},"quantity":{"type":"integer"},"materialId":{"type":"string"},"sizeMm":{"type":"array","items":{"type":"number"},"minItems":3,"maxItems":3},"units":{"const":"mm"}}}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Connect or refresh your token"},"403":{"description":"Required scope not granted"},"404":{"description":"Not found or owned by someone else"},"409":{"description":"Idempotency conflict or fresh quote required"},"429":{"description":"Allowance, budget or capacity exhausted; observe Retry-After"},"503":{"description":"Admission disabled or service unavailable"}}}},"/v1/quotes/{id}/checkout":{"post":{"operationId":"openHumanCheckout","summary":"Open private human review and payment; never assert that payment succeeded from a redirect","security":[{"oauth":["checkout:create"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"},"description":"Use the same key when retrying identical input. Different input with a used key returns 409."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["checkoutUrl","requiresHumanReview"],"properties":{"checkoutUrl":{"type":"string","format":"uri"},"requiresHumanReview":{"const":true}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Connect or refresh your token"},"403":{"description":"Required scope not granted"},"404":{"description":"Not found or owned by someone else"},"409":{"description":"Idempotency conflict or fresh quote required"},"429":{"description":"Allowance, budget or capacity exhausted; observe Retry-After"},"503":{"description":"Admission disabled or service unavailable"}}}},"/v1/orders/{id}":{"get":{"operationId":"getOrder","summary":"Read authoritative payment and fulfillment state","security":[{"oauth":["orders:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["creating","open","confirming","confirmed","expired","payment_mismatch","outcome_unknown"]},"fulfillmentStatus":{"type":"string"},"amount":{"type":"integer"},"currency":{"type":"string"},"reviewUrl":{"type":"string","format":"uri"}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Connect or refresh your token"},"403":{"description":"Required scope not granted"},"404":{"description":"Not found or owned by someone else"},"409":{"description":"Idempotency conflict or fresh quote required"},"429":{"description":"Allowance, budget or capacity exhausted; observe Retry-After"},"503":{"description":"Admission disabled or service unavailable"}}}},"/v1/designs/{id}/model.stl":{"get":{"operationId":"downloadModel","summary":"Download a private validated STL in millimeters","security":[{"oauth":["designs:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Binary STL","content":{"model/stl":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Invalid access token"},"404":{"description":"Not found or not owned"}}}}},"components":{"securitySchemes":{"oauth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://agents.tesseract.build/oauth/authorize","tokenUrl":"https://agents.tesseract.build/oauth/token","scopes":{"designs:generate":"designs generate","designs:read":"designs read","quotes:create":"quotes create","quotes:read":"quotes read","checkout:create":"checkout create","orders:read":"orders read","usage:read":"usage read"}}}}}}}