{"openapi":"3.1.0","info":{"title":"Minno API","description":"Face liveness for identity verification builders. Docs: https://tryminno.com/docs/","license":{"name":""},"version":"1"},"servers":[{"url":"https://api.tryminno.com"}],"paths":{"/v1/billing/checkout":{"post":{"tags":["billing"],"summary":"Returns a Stripe Checkout URL to add a card to this key. $0.05 per check; the first 100 are free.","operationId":"billing_checkout","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutStarted"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"bearer":[]}]}},"/v1/capture/{id}/complete":{"post":{"tags":["hosted capture"],"operationId":"capture_complete","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaptureAuth"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaptureDone"}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"410":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/capture/{id}/start":{"post":{"tags":["hosted capture"],"operationId":"capture_start","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaptureAuth"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaptureStart"}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"410":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/sessions":{"post":{"tags":["sessions"],"operationId":"create_session","requestBody":{"description":"All fields optional; an empty body is fine.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSession"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedSession"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"bearer":[]}]}},"/v1/sessions/{id}":{"get":{"tags":["sessions"],"operationId":"get_session","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"include_image","in":"query","description":"Return the reference frame","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionResult"}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"bearer":[]}]},"delete":{"tags":["sessions"],"summary":"Erase a session's personal data now (the customer's deletion request). The row stays only as a\nbilling count: decision, score, reference, return URL and capture token are cleared, and any\nqueued webhook for it is dropped. Later reads get 404.","operationId":"delete_session","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Erased"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"bearer":[]}]}},"/v1/sessions/{id}/match":{"post":{"tags":["sessions"],"operationId":"match_face","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatchReq"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatchResult"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"409":{"description":"Liveness did not pass, or the capture is no longer available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"422":{"description":"No usable face in id_photo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"bearer":[]}]}},"/v1/signup/checkout":{"post":{"tags":["signup"],"operationId":"signup_checkout","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupReq"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutStarted"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/signup/checkout/{checkout_session_id}/key":{"post":{"tags":["signup"],"summary":"The live key for a completed Checkout, exactly once. POST (not GET) so link prefetchers and\ncrawlers can't consume it.","operationId":"signup_reveal","parameters":[{"name":"checkout_session_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewKey"}}}},"409":{"description":"Checkout not completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"410":{"description":"Key already shown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/signup/test-key":{"post":{"tags":["signup"],"operationId":"signup_test_key","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupReq"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewKey"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/usage":{"get":{"tags":["account"],"operationId":"usage","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"bearer":[]}]}},"/v1/webhook":{"get":{"tags":["webhooks"],"operationId":"get_webhook","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookInfo"}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"bearer":[]}]},"put":{"tags":["webhooks"],"operationId":"put_webhook","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookReq"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCreated"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"bearer":[]}]},"delete":{"tags":["webhooks"],"operationId":"delete_webhook","responses":{"204":{},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"bearer":[]}]}},"/v1/webhook/test":{"post":{"tags":["webhooks"],"operationId":"test_webhook","responses":{"202":{},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"bearer":[]}]}}},"components":{"schemas":{"CaptureAuth":{"type":"object","required":["token"],"properties":{"token":{"type":"string","description":"The `t` value from the capture_url fragment."}},"additionalProperties":false},"CaptureDone":{"type":"object","required":["status"],"properties":{"redirect_url":{"type":["string","null"],"description":"The partner's return_url with session_id and status appended, if they set one."},"status":{"type":"string"}}},"CaptureStart":{"type":"object","required":["region","test"],"properties":{"credentials":{"oneOf":[{"$ref":"#/components/schemas/Credentials"},{"type":"null"}]},"region":{"type":"string"},"test":{"type":"boolean"}}},"CheckoutStarted":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"Send the browser here (Stripe Checkout)."}}},"CreateSession":{"type":"object","properties":{"consent_obtained":{"type":["boolean","null"],"description":"Required, must be `true`: you showed the person the biometric notice and got their express\nconsent before this call. Stored with the session as your per-check record."},"pass_threshold":{"type":["number","null"],"format":"float","description":"Override the pass threshold (0-100) for this session. Default 80."},"reference":{"type":["string","null"],"description":"Your id for the end customer or applicant (max 200 chars). Usage is split by it so you can re-bill."},"return_url":{"type":["string","null"],"description":"Hosted capture only: where to send the person afterwards. `?session_id=…&status=…` is appended.\nMust be https (http allowed for localhost)."},"simulate":{"type":["string","null"],"description":"Test keys only: `pass` (default) or `fail`. Test sessions never call AWS and never bill."}},"additionalProperties":false},"CreatedSession":{"type":"object","required":["session_id","test","region","capture_url"],"properties":{"capture_url":{"type":"string","description":"Hosted capture page for this session. Send the person here if you don't build your own\nscreen. Valid for 15 minutes; treat it like a password."},"credentials":{"oneOf":[{"$ref":"#/components/schemas/Credentials","description":"For your own capture screen. `null` for test keys."},{"type":"null"}]},"region":{"type":"string"},"session_id":{"type":"string"},"test":{"type":"boolean"}}},"Credentials":{"type":"object","required":["access_key_id","secret_access_key","session_token","expiration"],"properties":{"access_key_id":{"type":"string"},"expiration":{"type":"string","description":"RFC 3339."},"secret_access_key":{"type":"string"},"session_token":{"type":"string"}}},"Delivery":{"type":"object","required":["event_id","event","delivered","attempts","created_at"],"properties":{"attempts":{"type":"integer","format":"int32"},"created_at":{"type":"string"},"delivered":{"type":"boolean"},"event":{"type":"string"},"event_id":{"type":"string"},"last_error":{"type":["string","null"]},"last_status":{"type":["integer","null"],"format":"int32"},"session_id":{"type":["string","null"]}}},"ErrorBody":{"type":"object","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}}},"ErrorDetail":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. `liveness_not_passed`."},"message":{"type":"string"}}},"MatchReq":{"type":"object","required":["id_photo"],"properties":{"id_photo":{"type":"string","description":"Base64 JPEG or PNG (up to 5 MB decoded): an ID document portrait or a stored selfie."}},"additionalProperties":false},"MatchResult":{"type":"object","required":["session_id","match","similarity","match_threshold","test"],"properties":{"match":{"type":"boolean"},"match_threshold":{"type":"number","format":"float"},"session_id":{"type":"string"},"similarity":{"type":"number","format":"float"},"test":{"type":"boolean"}}},"MonthToDate":{"type":"object","required":["sessions_created","checks_billed","face_matches_billed"],"properties":{"checks_billed":{"type":"integer","format":"int64"},"face_matches_billed":{"type":"integer","format":"int64"},"sessions_created":{"type":"integer","format":"int64"}}},"NewKey":{"type":"object","required":["api_key","test"],"properties":{"api_key":{"type":"string","description":"Shown once. Minno stores only its hash."},"test":{"type":"boolean"}}},"ReferenceUsage":{"type":"object","required":["checks","face_matches"],"properties":{"checks":{"type":"integer","format":"int64"},"face_matches":{"type":"integer","format":"int64"},"reference":{"type":["string","null"]}}},"SessionResult":{"type":"object","required":["session_id","status","live","pass_threshold","test"],"properties":{"confidence":{"type":["number","null"],"format":"float"},"live":{"type":"boolean","description":"The decision: `status` is `succeeded` and `confidence` ≥ `pass_threshold`."},"pass_threshold":{"type":"number","format":"float"},"reference":{"type":["string","null"]},"reference_image":{"type":["string","null"],"description":"Base64 JPEG reference frame, only with `?include_image=true` on a succeeded session. Never stored by Minno."},"session_id":{"type":"string"},"status":{"type":"string","description":"`pending`, then exactly one of `succeeded`, `failed` (AWS could not complete the check) or `expired`."},"test":{"type":"boolean"}}},"SignupReq":{"type":"object","required":["accept_terms"],"properties":{"accept_terms":{"type":"boolean","description":"Must be `true`: you accept https://tryminno.com/legal/terms/ and the DPA."},"email":{"type":["string","null"],"description":"Optional; used only to reach you about your key."}},"additionalProperties":false},"Usage":{"type":"object","required":["month_to_date","by_reference"],"properties":{"by_reference":{"type":"array","items":{"$ref":"#/components/schemas/ReferenceUsage"},"description":"Top 1000 references this month by billed checks."},"month_to_date":{"$ref":"#/components/schemas/MonthToDate"},"monthly_limit":{"type":["integer","null"],"format":"int32"}}},"WebhookCreated":{"type":"object","required":["url","secret"],"properties":{"secret":{"type":"string","description":"Signing secret, shown once. Verify `Minno-Signature: t=<unix>,v1=<hex>` where\nv1 = HMAC-SHA256(secret, \"<t>.<raw body>\"). Setting the URL again rotates it."},"url":{"type":"string"}}},"WebhookInfo":{"type":"object","required":["recent_deliveries"],"properties":{"recent_deliveries":{"type":"array","items":{"$ref":"#/components/schemas/Delivery"},"description":"Last 20 deliveries, newest first."},"url":{"type":["string","null"]}}},"WebhookReq":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"https URL that receives `session.completed` events."}},"additionalProperties":false}},"securitySchemes":{"bearer":{"type":"http","scheme":"bearer"}}}}