{"openapi":"3.1.0","info":{"title":"meeeetup Face ID API","version":"1.0.0","description":"External API for managing scopes, resolving and reading per-scope profiles, the detection journal, browser capture sessions, hosted magic-link registrations, and server-to-server person indexing. Server-to-server face indexing lives under `/v1/persons` and requires the appropriate scope; browser capture uploads use a short-lived capture-session token. API-key endpoints are gated by per-key scopes."},"servers":[{"url":"/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Project API key (`sk_live_…`). Scopes are granted per key."},"captureSessionToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Short-lived capture-session token returned by POST /v1/capture-sessions. Safe to expose to a browser: bound to one session, one scope, one origin, a capture cap and an expiry."}},"schemas":{"PersonAttributes":{"type":"object","nullable":true,"properties":{"faceOccluded":{"type":"boolean","nullable":true},"faceOccludedConfidence":{"type":"number","nullable":true},"mouthOpen":{"type":"boolean","nullable":true},"mouthOpenConfidence":{"type":"number","nullable":true},"eyesOpen":{"type":"boolean","nullable":true},"eyesOpenConfidence":{"type":"number","nullable":true},"sunglasses":{"type":"boolean","nullable":true},"sunglassesConfidence":{"type":"number","nullable":true},"eyeglasses":{"type":"boolean","nullable":true},"eyeglassesConfidence":{"type":"number","nullable":true},"beard":{"type":"boolean","nullable":true},"beardConfidence":{"type":"number","nullable":true},"mustache":{"type":"boolean","nullable":true},"mustacheConfidence":{"type":"number","nullable":true},"smile":{"type":"boolean","nullable":true},"smileConfidence":{"type":"number","nullable":true}},"required":["faceOccluded","faceOccludedConfidence","mouthOpen","mouthOpenConfidence","eyesOpen","eyesOpenConfidence","sunglasses","sunglassesConfidence","eyeglasses","eyeglassesConfidence","beard","beardConfidence","mustache","mustacheConfidence","smile","smileConfidence"],"additionalProperties":false,"description":"Rekognition boolean face attributes; each `*Confidence` is 0–100."},"PersonPose":{"type":"object","nullable":true,"properties":{"roll":{"type":"number","nullable":true},"yaw":{"type":"number","nullable":true},"pitch":{"type":"number","nullable":true}},"required":["roll","yaw","pitch"],"additionalProperties":false,"description":"Head pose in degrees."},"PersonQuality":{"type":"object","nullable":true,"properties":{"brightness":{"type":"number","nullable":true},"sharpness":{"type":"number","nullable":true},"confidence":{"type":"number","nullable":true}},"required":["brightness","sharpness","confidence"],"additionalProperties":false,"description":"`brightness` / `sharpness` 0–100; `confidence` is the overall face-detection confidence 0–100."},"PersonDemographics":{"type":"object","nullable":true,"properties":{"gender":{"type":"string","nullable":true},"ageMin":{"type":"integer","nullable":true},"ageMax":{"type":"integer","nullable":true}},"required":["gender","ageMin","ageMax"],"additionalProperties":false}},"parameters":{}},"paths":{"/debug":{"get":{"summary":"Debug API key","description":"Verifies a key is valid and returns its metadata. No scope required - useful for testing your integration.","tags":["Debug"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Key is valid","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"key":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"orgId":{"type":"string"},"projectId":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","nullable":true,"format":"date-time"},"lastUsedAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","name","orgId","projectId","permissions","createdAt","lastUsedAt"]},"error":{"type":"string"}},"required":["ok"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"key":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"orgId":{"type":"string"},"projectId":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","nullable":true,"format":"date-time"},"lastUsedAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","name","orgId","projectId","permissions","createdAt","lastUsedAt"]},"error":{"type":"string"}},"required":["ok"]}}}}}}},"/scopes":{"get":{"summary":"List project scopes","description":"Cursor-paginated list of scopes owned by the API key's project, newest first. Pass the previous response's `next_before` as the next request's `before`; iterate until `has_more` is `false`. Requires `person:read` scope.","tags":["Scopes"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"before","in":"query"}],"responses":{"200":{"description":"Scopes","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"externalId":{"type":"string","nullable":true},"matchThreshold":{"type":"integer","nullable":true,"minimum":60,"maximum":99},"formSchema":{"type":"object","properties":{"systemFields":{"type":"object","additionalProperties":{"type":"boolean"}},"questions":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}}},"required":["systemFields","questions"],"additionalProperties":false},"createdAt":{"type":"string","nullable":true,"format":"date-time"},"updatedAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","projectId","name","slug","externalId","matchThreshold","formSchema","createdAt","updatedAt"],"additionalProperties":false}},"has_more":{"type":"boolean"},"next_before":{"type":"string","nullable":true,"format":"date-time"}},"required":["data","has_more","next_before"]}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}}}},"post":{"summary":"Create a scope with a registration form","description":"Creates a new scope with an optional registration form. When `externalId` is supplied, a retry with the same (projectId, externalId) returns the existing scope (200) instead of creating a duplicate (201). Requires `scope:create` scope.","tags":["Scopes"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"slug":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[a-z0-9-]+$"},"externalId":{"type":"string","minLength":1,"maxLength":255},"formSchema":{"type":"object","properties":{"systemFields":{"type":"object","additionalProperties":{"type":"boolean"}},"questions":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}}},"required":["systemFields","questions"],"additionalProperties":false}},"required":["name"],"additionalProperties":false}}}},"responses":{"200":{"description":"Existing scope returned (idempotent hit on externalId)","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"externalId":{"type":"string","nullable":true},"matchThreshold":{"type":"integer","nullable":true,"minimum":60,"maximum":99},"formSchema":{"type":"object","properties":{"systemFields":{"type":"object","additionalProperties":{"type":"boolean"}},"questions":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}}},"required":["systemFields","questions"],"additionalProperties":false},"createdAt":{"type":"string","nullable":true,"format":"date-time"},"updatedAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","projectId","name","slug","externalId","matchThreshold","formSchema","createdAt","updatedAt"],"additionalProperties":false}}}},"201":{"description":"Scope created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"externalId":{"type":"string","nullable":true},"matchThreshold":{"type":"integer","nullable":true,"minimum":60,"maximum":99},"formSchema":{"type":"object","properties":{"systemFields":{"type":"object","additionalProperties":{"type":"boolean"}},"questions":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}}},"required":["systemFields","questions"],"additionalProperties":false},"createdAt":{"type":"string","nullable":true,"format":"date-time"},"updatedAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","projectId","name","slug","externalId","matchThreshold","formSchema","createdAt","updatedAt"],"additionalProperties":false}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"409":{"description":"Slug already taken in this project","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}}}}},"/scopes/{scopeId}":{"patch":{"summary":"Update a scope and its registration form","description":"Applies a partial update to a scope owned by the API key's project. `matchThreshold` sets the per-scope face-similarity threshold on the 0–100 scale (valid range 60–99; null clears the override and reverts to the platform default ~80 — see § 3.1 of the integration spec). `formSchema` is overwritten wholesale — pre-GA there is no form versioning, so profile answers keyed to removed or renamed question ids remain in storage and the console renders them as raw JSON. `externalId` is immutable and is rejected with 400; rebind by creating a new scope. Requires `scope:update` scope.","tags":["Scopes"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"scopeId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"slug":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[a-z0-9-]+$"},"formSchema":{"type":"object","properties":{"systemFields":{"type":"object","additionalProperties":{"type":"boolean"}},"questions":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}}},"required":["systemFields","questions"],"additionalProperties":false},"matchThreshold":{"type":"integer","nullable":true,"minimum":60,"maximum":99}},"additionalProperties":false}}}},"responses":{"200":{"description":"Updated scope","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"externalId":{"type":"string","nullable":true},"matchThreshold":{"type":"integer","nullable":true,"minimum":60,"maximum":99},"formSchema":{"type":"object","properties":{"systemFields":{"type":"object","additionalProperties":{"type":"boolean"}},"questions":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}}},"required":["systemFields","questions"],"additionalProperties":false},"createdAt":{"type":"string","nullable":true,"format":"date-time"},"updatedAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","projectId","name","slug","externalId","matchThreshold","formSchema","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"Invalid body (including an attempt to change externalId, or a matchThreshold outside 60–99)","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"404":{"description":"Scope not found in this project","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"409":{"description":"Slug already taken in this project","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}}}}},"/scopes/{scopeId}/profiles":{"post":{"summary":"Attach a person to a scope (no image)","description":"Creates a scope profile for an existing `personId`. No image is accepted here — the face must already have been indexed via `POST /v1/persons`, the magic-link flow, or the browser capture-session upload. Idempotent on `(scopeId, personId)`: a retry returns the existing profile with `created: false`. Requires `person:create` scope.","tags":["Profiles"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"scopeId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"personId":{"type":"string","minLength":1},"name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"department":{"type":"string"},"formData":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}},"required":["personId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Existing profile (idempotent hit)","content":{"application/json":{"schema":{"type":"object","properties":{"profileId":{"type":"string"},"created":{"type":"boolean"}},"required":["profileId","created"],"additionalProperties":false}}}},"201":{"description":"Profile created","content":{"application/json":{"schema":{"type":"object","properties":{"profileId":{"type":"string"},"created":{"type":"boolean"}},"required":["profileId","created"],"additionalProperties":false}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"404":{"description":"Scope or person not found in this project / org","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}}}},"get":{"summary":"List profiles enrolled in a scope","description":"Cursor-paginated list of profiles for a scope, newest first. Pass the previous response's `next_before` as the next request's `before`; iterate until `has_more` is `false`. Requires `person:read` scope.","tags":["Profiles"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"scopeId","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"before","in":"query"}],"responses":{"200":{"description":"Profiles","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"scopeId":{"type":"string","nullable":true},"personId":{"type":"string","nullable":true},"projectId":{"type":"string"},"status":{"type":"string","enum":["registered","unregistered","detected-only"]},"name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"department":{"type":"string","nullable":true},"formData":{"type":"object","nullable":true,"additionalProperties":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},"createdAt":{"type":"string","nullable":true,"format":"date-time"},"updatedAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","scopeId","personId","projectId","status","name","email","phone","department","formData","createdAt","updatedAt"],"additionalProperties":false}},"has_more":{"type":"boolean"},"next_before":{"type":"string","nullable":true,"format":"date-time"}},"required":["data","has_more","next_before"]}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"404":{"description":"Scope not found in this project","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}}}}},"/scopes/{scopeId}/profiles/{profileId}":{"get":{"summary":"Get profile by profile id","description":"Returns the profile with the given id, scoped to this scope. Requires `person:read` scope.","tags":["Profiles"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"scopeId","in":"path"},{"schema":{"type":"string"},"required":true,"name":"profileId","in":"path"}],"responses":{"200":{"description":"Profile","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"scopeId":{"type":"string","nullable":true},"personId":{"type":"string","nullable":true},"projectId":{"type":"string"},"status":{"type":"string","enum":["registered","unregistered","detected-only"]},"name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"department":{"type":"string","nullable":true},"formData":{"type":"object","nullable":true,"additionalProperties":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},"createdAt":{"type":"string","nullable":true,"format":"date-time"},"updatedAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","scopeId","personId","projectId","status","name","email","phone","department","formData","createdAt","updatedAt"],"additionalProperties":false}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"404":{"description":"Scope or profile not found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}}}},"delete":{"summary":"Unregister a profile from a scope","description":"Unregisters the profile (soft delete — status becomes `unregistered`). Face image, engine collection entry, and the org-wide person row are preserved; full erasure is an admin-console / support operation. Requires `person:unregister` scope.","tags":["Profiles"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"scopeId","in":"path"},{"schema":{"type":"string"},"required":true,"name":"profileId","in":"path"}],"responses":{"200":{"description":"Unregistered profile","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"scopeId":{"type":"string","nullable":true},"personId":{"type":"string","nullable":true},"projectId":{"type":"string"},"status":{"type":"string","enum":["registered","unregistered","detected-only"]},"name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"department":{"type":"string","nullable":true},"formData":{"type":"object","nullable":true,"additionalProperties":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},"createdAt":{"type":"string","nullable":true,"format":"date-time"},"updatedAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","scopeId","personId","projectId","status","name","email","phone","department","formData","createdAt","updatedAt"],"additionalProperties":false}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"404":{"description":"Scope or profile not found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}}}}},"/persons":{"post":{"summary":"Create or resolve a person identity from a face image","description":"Indexes the submitted face into the organisation's recognition collection, creates / resolves the `person` row, and returns `{ personId, created }`. Idempotent on the face itself — a duplicate face returns the existing `personId` with `created: false`. Pass `?scopeId=` to apply that scope's `matchThreshold` (falls back to the platform default ~80 when the scope has no override or when `scopeId` is omitted); a scope outside the API key's project returns 400. Opt-in face analysis: pass `?include=attributes,pose,quality,demographics` (any subset, or `all`) to add those Rekognition sections to the response — e.g. reject occluded or turned-away captures before trusting the result. Each requested section is `null` when analysis was unavailable; an unknown section returns 400. Requires `person:create` scope.","tags":["Persons"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Scope whose `matchThreshold` governs face matching for this call. Must belong to the API key's project. Omit to use the platform default (~80).","example":"scp_xxx"},"required":false,"description":"Scope whose `matchThreshold` governs face matching for this call. Must belong to the API key's project. Omit to use the platform default (~80).","name":"scopeId","in":"query"},{"schema":{"type":"string","description":"Opt in to Rekognition face-analysis sections in the response. Comma-separated: `attributes`, `pose`, `quality`, `demographics`, or `all`. Omit for the default shape. A requested section is `null` when face analysis was unavailable.","example":"attributes,pose"},"required":false,"description":"Opt in to Rekognition face-analysis sections in the response. Comma-separated: `attributes`, `pose`, `quality`, `demographics`, or `all`. Omit for the default shape. A requested section is `null` when face analysis was unavailable.","name":"include","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"image":{"type":"string","minLength":1}},"required":["image"],"additionalProperties":false}}}},"responses":{"200":{"description":"Existing person (idempotent hit)","content":{"application/json":{"schema":{"type":"object","properties":{"personId":{"type":"string"},"created":{"type":"boolean"},"attributes":{"$ref":"#/components/schemas/PersonAttributes"},"pose":{"$ref":"#/components/schemas/PersonPose"},"quality":{"$ref":"#/components/schemas/PersonQuality"},"demographics":{"$ref":"#/components/schemas/PersonDemographics"}},"required":["personId","created"],"additionalProperties":false}}}},"201":{"description":"Person created","content":{"application/json":{"schema":{"type":"object","properties":{"personId":{"type":"string"},"created":{"type":"boolean"},"attributes":{"$ref":"#/components/schemas/PersonAttributes"},"pose":{"$ref":"#/components/schemas/PersonPose"},"quality":{"$ref":"#/components/schemas/PersonQuality"},"demographics":{"$ref":"#/components/schemas/PersonDemographics"}},"required":["personId","created"],"additionalProperties":false}}}},"400":{"description":"No face detected in image, `scopeId` not in this project, or unknown `include` section","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}}}}},"/persons/search":{"post":{"summary":"Identify a person by face image (1:N search)","description":"Searches the organisation's recognition collection for the submitted face. Returns `{ personId, faceOccluded }` — `personId` on match or `null` when the face is valid but doesn't match any known identity. Masked/occluded faces are searched like any other; `faceOccluded` (`true`/`false`, or `null` when face analysis was unavailable) is always returned so the partner decides whether to accept a match made on a covered face. Never indexes a new face — safe to call repeatedly. Pass `?scopeId=` to apply that scope's `matchThreshold` (falls back to the platform default ~80 when the scope has no override or when `scopeId` is omitted); a scope outside the API key's project returns 400. Opt-in face analysis: pass `?include=attributes,pose,quality,demographics` (any subset, or `all`) to add those Rekognition sections to the response — e.g. reject occluded or turned-away captures before trusting the result. Each requested section is `null` when analysis was unavailable; an unknown section returns 400. Requires `person:read` scope.","tags":["Persons"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Scope whose `matchThreshold` governs face matching for this call. Must belong to the API key's project. Omit to use the platform default (~80).","example":"scp_xxx"},"required":false,"description":"Scope whose `matchThreshold` governs face matching for this call. Must belong to the API key's project. Omit to use the platform default (~80).","name":"scopeId","in":"query"},{"schema":{"type":"string","description":"Opt in to Rekognition face-analysis sections in the response. Comma-separated: `attributes`, `pose`, `quality`, `demographics`, or `all`. Omit for the default shape. A requested section is `null` when face analysis was unavailable.","example":"attributes,pose"},"required":false,"description":"Opt in to Rekognition face-analysis sections in the response. Comma-separated: `attributes`, `pose`, `quality`, `demographics`, or `all`. Omit for the default shape. A requested section is `null` when face analysis was unavailable.","name":"include","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"image":{"type":"string","minLength":1}},"required":["image"],"additionalProperties":false}}}},"responses":{"200":{"description":"Match result","content":{"application/json":{"schema":{"type":"object","properties":{"personId":{"type":"string","nullable":true},"faceOccluded":{"type":"boolean","nullable":true},"attributes":{"$ref":"#/components/schemas/PersonAttributes"},"pose":{"$ref":"#/components/schemas/PersonPose"},"quality":{"$ref":"#/components/schemas/PersonQuality"},"demographics":{"$ref":"#/components/schemas/PersonDemographics"}},"required":["personId","faceOccluded"],"additionalProperties":false}}}},"400":{"description":"No face detected in image, `scopeId` not in this project, or unknown `include` section","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}}}}},"/persons/{personId}":{"delete":{"summary":"Erase a face identity (identity-level deletion)","description":"Partner-executed identity erasure for GDPR / Japan APPI data-subject requests. Tears down the Rekognition face, S3 image, `face_info` row, and `person` row (cascading to `person_journal` and every `profile` referencing the identity). Returns 202 with the affected scopes list. Idempotent — a repeat call on the same `personId` returns 404 which the partner MUST treat as success. Requires `person:delete` scope.","tags":["Persons"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"personId","in":"path"}],"responses":{"202":{"description":"Data-plane erasure complete; backup copies expire naturally","content":{"application/json":{"schema":{"type":"object","properties":{"personId":{"type":"string"},"status":{"type":"string","enum":["data-plane-complete"]},"erasedAt":{"type":"string"},"affectedScopes":{"type":"array","items":{"type":"string"}},"backupExpiryBy":{"type":"string"}},"required":["personId","status","erasedAt","affectedScopes","backupExpiryBy"],"additionalProperties":false}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"404":{"description":"Person not found in this organisation, or already erased","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}}}}},"/capture-sessions":{"post":{"summary":"Create browser capture session","description":"Creates a short-lived browser capture session token for direct image upload. Requires `captureSession:create` scope.","tags":["Capture Sessions"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"scopeId":{"type":"string","minLength":1},"webhookUrl":{"type":"string","format":"uri"},"allowedOrigin":{"type":"string","format":"uri"},"expiresInSeconds":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":300},"mode":{"type":"string","enum":["single","passive"],"default":"single"},"purpose":{"type":"string","enum":["identify","register"],"default":"identify"},"externalRef":{"type":"string","minLength":1,"maxLength":255}},"required":["scopeId","allowedOrigin"],"additionalProperties":false}}}},"responses":{"201":{"description":"Capture session token created","content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string"},"captureSessionToken":{"type":"string"},"webhookSecret":{"type":"string","description":"Per-session HMAC secret for the capture_session.profile_resolved webhook. Returned exactly once, scoped to this sessionId. Not the project-level webhook secret from the console (that one signs the project-wide /capture entry webhook). Present only when webhookUrl was supplied at session creation."},"expiresAt":{"type":"string","nullable":true,"format":"date-time"},"maxCaptures":{"type":"integer","minimum":0,"exclusiveMinimum":true}},"required":["sessionId","captureSessionToken","expiresAt","maxCaptures"],"additionalProperties":false}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"404":{"description":"Scope not found in this project","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}}}}},"/capture-sessions/{sessionId}/captures":{"post":{"summary":"Upload browser captures","description":"Resolves one or more browser-captured face images against the session's scope and returns a positional result per capture. Identify-only: never creates a person or a scope profile; `no_match` includes faces of people registered in another scope of the same project. Enrollment happens through the scope's registration flow at `account.meeeetup.com` or `POST /capture` with a capture key — never through an API-key-authenticated endpoint, which is why the v1 image surface was removed in #308. Authenticated with the `captureSessionToken` from POST /v1/capture-sessions — not an API key, and no API-key scope applies. The token itself pins the org, project and scope, the allowed origin, the capture cap and the expiry.","tags":["Capture Sessions"],"security":[{"captureSessionToken":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"sessionId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"captures":{"type":"array","items":{"type":"object","properties":{"image":{"type":"string","minLength":1},"capturedAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["image"],"additionalProperties":false},"minItems":1,"maxItems":12}},"required":["captures"],"additionalProperties":false}}}},"responses":{"200":{"description":"Per-capture resolve results, positionally matching the request","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"captureId":{"type":"string"},"status":{"type":"string","enum":["matched"]},"profileId":{"type":"string"}},"required":["captureId","status","profileId"],"additionalProperties":false},{"type":"object","properties":{"captureId":{"type":"string"},"status":{"type":"string","enum":["registered"]},"externalRef":{"type":"string"}},"required":["captureId","status","externalRef"],"additionalProperties":false},{"type":"object","properties":{"captureId":{"type":"string"},"status":{"type":"string","enum":["no_match"]}},"required":["captureId","status"],"additionalProperties":false},{"type":"object","properties":{"captureId":{"type":"string"},"status":{"type":"string","enum":["no_face"]}},"required":["captureId","status"],"additionalProperties":false},{"type":"object","properties":{"captureId":{"type":"string"},"status":{"type":"string","enum":["error"]},"errorCode":{"type":"string"},"errorMessage":{"type":"string"}},"required":["captureId","status","errorCode","errorMessage"],"additionalProperties":false}]}}},"required":["results"],"additionalProperties":false}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"401":{"description":"Invalid capture session token","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"403":{"description":"Capture session inactive, origin mismatch, or limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"404":{"description":"Capture session not found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}}}}},"/capture-sessions/{sessionId}/result":{"get":{"summary":"Read a capture session's final result","description":"Server-to-server fallback query. For register-mode sessions the browser response is deliberately lean (externalRef only) and `personId` is delivered via the signed `capture_session.profile_resolved` webhook. Use this endpoint if the webhook is delayed, dead-lettered, or the partner backend missed it. For identify-mode sessions the browser already received `profileId` inline, but this endpoint gives the server-side authoritative read when needed. Requires `captureSession:create` scope.","tags":["Capture Sessions"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"sessionId","in":"path"}],"responses":{"200":{"description":"Capture session result","content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string"},"purpose":{"type":"string","enum":["identify","register"]},"externalRef":{"type":"string","nullable":true},"status":{"type":"string","enum":["pending","matched","registered","no_match","no_face","error"]},"personId":{"type":"string","nullable":true},"profileId":{"type":"string","nullable":true},"errorCode":{"type":"string","nullable":true},"errorMessage":{"type":"string","nullable":true},"completedAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["sessionId","purpose","externalRef","status","personId","profileId","errorCode","errorMessage","completedAt"],"additionalProperties":false}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"404":{"description":"Session not found in this project","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}}}}},"/magic-links":{"post":{"summary":"Create a hosted-registration magic link","description":"Mints a one-time hosted-registration link scoped to a single buyer. Returns the plaintext token and the hosted-page URL exactly once; MeeeetUp persists only the SHA-256 hash. The partner delivers the URL to the user via its own email channel. Pass `requireLiveness: true` to run an Amazon Rekognition Face Liveness challenge on the hosted face step before the face image is accepted — a failed challenge rejects the capture and the user retries on the same link. Requires `magicLink:create` scope.","tags":["Magic Links"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"scopeId":{"type":"string","minLength":1},"externalRef":{"type":"string","minLength":1,"maxLength":255},"callbackUrl":{"type":"string","format":"uri"},"webhookUrl":{"type":"string","format":"uri"},"expiresInSeconds":{"type":"integer","minimum":0,"exclusiveMinimum":true},"requireLiveness":{"type":"boolean"}},"required":["scopeId","externalRef","callbackUrl"],"additionalProperties":false}}}},"responses":{"201":{"description":"Magic link created","content":{"application/json":{"schema":{"type":"object","properties":{"magicLinkId":{"type":"string"},"magicLinkUrl":{"type":"string","format":"uri"},"token":{"type":"string"},"webhookSecret":{"type":"string","description":"Per-link HMAC secret. Signs every webhook event this link emits (magic_link.opened, person.registered, profile.submitted) AND the HS256 callback-redirect JWT. Returned exactly once, scoped to this magicLinkId. Not the project-level webhook secret from the console (that one signs the project-wide /capture entry webhook). Present only when webhookUrl was supplied at link creation."},"expiresAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["magicLinkId","magicLinkUrl","token","expiresAt"],"additionalProperties":false}}}},"400":{"description":"Invalid request body (bad callbackUrl, bad webhookUrl, etc.)","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"404":{"description":"Scope not found in this project","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}}}}},"/magic-links/{token}":{"get":{"summary":"Read magic-link state (hosted-page bootstrap)","description":"Public — authenticates via the magic-link token in the URL. First successful read fires the `magic_link.opened` webhook; repeated reads do not. Returns the scope's form schema so the hosted page can render fields without a second call.","tags":["internal:hosted-page"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"token","in":"path"}],"responses":{"200":{"description":"Magic-link state","content":{"application/json":{"schema":{"type":"object","properties":{"magicLinkId":{"type":"string"},"scopeId":{"type":"string"},"status":{"type":"string","enum":["pending","opened","face_captured","completed","expired"]},"scope":{"type":"object","properties":{"name":{"type":"string"},"formSchema":{"type":"object","properties":{"systemFields":{"type":"object","additionalProperties":{"type":"boolean"}},"questions":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}}},"required":["systemFields","questions"],"additionalProperties":false}},"required":["name","formSchema"],"additionalProperties":false},"personId":{"type":"string","nullable":true},"profileId":{"type":"string","nullable":true},"requireLiveness":{"type":"boolean"},"livenessSessionId":{"type":"string","nullable":true},"livenessStatus":{"type":"string","nullable":true,"enum":["pending","succeeded","failed",null]},"expiresAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["magicLinkId","scopeId","status","scope","personId","profileId","requireLiveness","livenessSessionId","livenessStatus","expiresAt"],"additionalProperties":false}}}},"403":{"description":"Magic link expired","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"404":{"description":"Magic link not found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}}}}},"/magic-links/{token}/face":{"post":{"summary":"Upload the user's face from the hosted page","description":"Public — authenticates via the magic-link token in the URL. Accepts a single base64 image, indexes it into the organisation's recognition collection, resolves the `personId`, writes it to the magic-link row, and fires the `person.registered` webhook. Repeated calls on a magic link whose face is already captured return 409.","tags":["internal:hosted-page"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"token","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"image":{"type":"string","minLength":1}},"required":["image"],"additionalProperties":false}}}},"responses":{"200":{"description":"Face captured","content":{"application/json":{"schema":{"type":"object","properties":{"personId":{"type":"string"},"status":{"type":"string","enum":["pending","opened","face_captured","completed","expired"]}},"required":["personId","status"],"additionalProperties":false}}}},"400":{"description":"No face detected in image","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"403":{"description":"Magic link expired, or liveness challenge not completed","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"404":{"description":"Magic link not found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"409":{"description":"Face already captured for this magic link","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}}}}},"/magic-links/{token}/liveness-result":{"post":{"summary":"Report the hosted-page liveness challenge result","description":"Public — authenticates via the magic-link token in the URL. Call after the Amazon Rekognition Face Liveness challenge completes; the server fetches the authoritative result from Rekognition, records it on the magic link, and gates the face step on a pass. Returns 200 when the challenge passes. Returns 403 `LIVENESS_FAILED` (with a fresh `livenessSessionId` for retry) when it fails, expires, or scores below the recommended confidence — the magic link stays valid for the retry. The raw confidence score is never returned.","tags":["internal:hosted-page"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"token","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"livenessSessionId":{"type":"string","minLength":1}},"required":["livenessSessionId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Liveness challenge passed","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["succeeded"]}},"required":["status"],"additionalProperties":false}}}},"400":{"description":"Magic link did not request a liveness challenge","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"403":{"description":"Liveness challenge failed or expired; retry with the returned session id","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["LIVENESS_FAILED"]},"error":{"type":"string"},"livenessSessionId":{"type":"string"}},"required":["code","error","livenessSessionId"],"additionalProperties":false}}}},"404":{"description":"Magic link or liveness session not found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}}}}},"/magic-links/{token}/form":{"post":{"summary":"Submit the registration form from the hosted page","description":"Public — authenticates via the magic-link token in the URL. Upserts the scope profile from the submitted form data, marks the magic link `completed`, fires the `profile.submitted` webhook, and returns a short-lived HMAC-SHA256 signed JWT the hosted page carries back to the partner's callback URL for server-side verification.","tags":["internal:hosted-page"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"token","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"formData":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},"name":{"type":"string","minLength":1},"phone":{"type":"string"},"department":{"type":"string"}},"required":["formData"],"additionalProperties":false}}}},"responses":{"200":{"description":"Form submitted; redirect the user to callbackRedirectUrl","content":{"application/json":{"schema":{"type":"object","properties":{"profileId":{"type":"string"},"personId":{"type":"string"},"magicLinkId":{"type":"string"},"callbackToken":{"type":"string"},"callbackRedirectUrl":{"type":"string","format":"uri"}},"required":["profileId","personId","magicLinkId","callbackToken","callbackRedirectUrl"],"additionalProperties":false}}}},"400":{"description":"Invalid form payload","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"403":{"description":"Magic link expired, or face has not been captured yet","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"404":{"description":"Magic link not found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}}}}},"/journal":{"get":{"summary":"Detection journal + erasure event log","description":"By default returns face detection events ordered by most recent. Use `before` (the `next_before` from a previous response) to page through results. Use `from`/`to` to bound a time window. Pass `include=demographics` to add `gender`, `ageMin`, `ageMax` to each detection entry. Pass `event=person.erased` (#358) to switch source: the response returns identity-erasure events from the audit log instead of detection events — one row per `person.erased` for the API key's project, same cursor + from/to semantics. Use it for GDPR / APPI deletion-log reports or to rebuild state when the `person.erased` webhook was missed. Requires `journal:read`.","tags":["Journal"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"date-time","description":"ISO 8601 — filter events at or after this time"},"required":false,"description":"ISO 8601 — filter events at or after this time","name":"from","in":"query"},{"schema":{"type":"string","format":"date-time","description":"ISO 8601 — filter events at or before this time"},"required":false,"description":"ISO 8601 — filter events at or before this time","name":"to","in":"query"},{"schema":{"type":"string","format":"date-time","description":"ISO 8601 cursor for detection view, OR the opaque `next_before` from the erasure view — pass whichever matches the response you're paging through"},"required":false,"description":"ISO 8601 cursor for detection view, OR the opaque `next_before` from the erasure view — pass whichever matches the response you're paging through","name":"before","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Number of results (1-100)"},"required":false,"description":"Number of results (1-100)","name":"limit","in":"query"},{"schema":{"type":"string","enum":["demographics"],"description":"Opt in to extended fields on each entry. `demographics` adds `gender`, `ageMin`, `ageMax`. Ignored when `event=person.erased`."},"required":false,"description":"Opt in to extended fields on each entry. `demographics` adds `gender`, `ageMin`, `ageMax`. Ignored when `event=person.erased`.","name":"include","in":"query"},{"schema":{"type":"string","enum":["person.erased"],"description":"Switch source to the erasure event log (reads audit_log where action='person.erase.full'). The response schema becomes PersonErasedEventEntry."},"required":false,"description":"Switch source to the erasure event log (reads audit_log where action='person.erase.full'). The response schema becomes PersonErasedEventEntry.","name":"event","in":"query"}],"responses":{"200":{"description":"Detection entries (default) with cursor. Shape omits demographics unless `include=demographics`. When `event=person.erased` is passed, entries are erasure events from the audit log instead.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"captureKeyId":{"type":"string"},"channelId":{"type":"string","nullable":true},"personId":{"type":"string"},"detectedAt":{"type":"string","nullable":true,"format":"date-time"},"faceOccluded":{"type":"boolean","nullable":true}},"required":["id","projectId","captureKeyId","channelId","personId","detectedAt","faceOccluded"],"additionalProperties":false}},"has_more":{"type":"boolean"},"next_before":{"type":"string","nullable":true,"format":"date-time"}},"required":["data","has_more","next_before"]},{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"captureKeyId":{"type":"string"},"channelId":{"type":"string","nullable":true},"personId":{"type":"string"},"detectedAt":{"type":"string","nullable":true,"format":"date-time"},"faceOccluded":{"type":"boolean","nullable":true},"gender":{"type":"string","nullable":true},"ageMin":{"type":"integer","nullable":true},"ageMax":{"type":"integer","nullable":true}},"required":["id","projectId","captureKeyId","channelId","personId","detectedAt","faceOccluded","gender","ageMin","ageMax"],"additionalProperties":false}},"has_more":{"type":"boolean"},"next_before":{"type":"string","nullable":true,"format":"date-time"}},"required":["data","has_more","next_before"]},{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"event":{"type":"string","enum":["person.erased"]},"personId":{"type":"string"},"erasedAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","event","personId","erasedAt"],"additionalProperties":false}},"has_more":{"type":"boolean"},"next_before":{"type":"string","nullable":true,"format":"date-time"}},"required":["data","has_more","next_before"]}]}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","CONFLICT","INTERNAL_ERROR","RATE_LIMITED"]},"error":{"type":"string"}},"required":["code","error"]}}}}}}},"/llms.txt":{"get":{"summary":"Integration guide for AI agents (llms.txt)","description":"Plain-text guide describing how to integrate the v1 API. Endpoint list is generated from this spec. Public — no API key required.","tags":["Docs"],"security":[],"responses":{"200":{"description":"llms.txt guide","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/skill.md":{"get":{"summary":"Installable agent skill for integrating this API","description":"Markdown skill file (YAML frontmatter + integration guide) for coding agents such as Claude Code. Covers credentials, the data model, the capture SDKs and the failure modes that break integrations. Public — no API key required.","tags":["Docs"],"security":[],"responses":{"200":{"description":"Agent skill","content":{"text/markdown":{"schema":{"type":"string"}}}}}}}}}