{ "openapi": "3.1.0", "info": { "title": "Face Recognition API", "version": "0.3.1", "description": "Development API. Tenant = application, collection = school. Matching is not proof of identity or liveness. Similarity is not a probability. Scope names: read, write, infer." }, "servers": [ { "url": "http://127.0.0.1:8080" } ], "security": [ { "ApiKey": [] } ], "paths": { "/v1/usage": { "get": { "summary": "Daily usage and operation quota for authenticated tenant", "operationId": "get_v1_usage", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "410": { "description": "Historical idempotency response invalidated by data deletion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "429": { "description": "Rate limit or daily quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds until token availability for RATE_LIMITED responses; daily quota errors may omit this header", "schema": { "type": "integer" } } } }, "500": { "description": "Inference failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "401": { "description": "API key missing, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "404": { "description": "Resource not found in tenant/collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "409": { "description": "Duplicate external_id or sample limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "413": { "description": "Request too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "422": { "description": "Invalid image, no face, multiple faces, or invalid field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } } }, "description": "Required API key scope: read.", "parameters": [ { "in": "query", "name": "date", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "description": "Asia/Jakarta day YYYY-MM-DD; today by default" } ] } }, "/healthz": { "get": { "summary": "Go process health", "operationId": "get_healthz", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "410": { "description": "Historical idempotency response invalidated by data deletion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "429": { "description": "Rate limit or daily quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds until token availability for RATE_LIMITED responses; daily quota errors may omit this header", "schema": { "type": "integer" } } } }, "500": { "description": "Inference failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "401": { "description": "API key missing, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "404": { "description": "Resource not found in tenant/collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "409": { "description": "Duplicate external_id or sample limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "413": { "description": "Request too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "422": { "description": "Invalid image, no face, multiple faces, or invalid field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } } }, "security": [] } }, "/readyz": { "get": { "summary": "Inference and database readiness", "operationId": "get_readyz", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "410": { "description": "Historical idempotency response invalidated by data deletion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "429": { "description": "Rate limit or daily quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds until token availability for RATE_LIMITED responses; daily quota errors may omit this header", "schema": { "type": "integer" } } } }, "500": { "description": "Inference failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "401": { "description": "API key missing, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "404": { "description": "Resource not found in tenant/collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "409": { "description": "Duplicate external_id or sample limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "413": { "description": "Request too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "422": { "description": "Invalid image, no face, multiple faces, or invalid field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } } }, "security": [] } }, "/v1/collections": { "get": { "summary": "List schools", "operationId": "get_v1_collections", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "collections": { "type": "array", "items": { "type": "object", "properties": { "collection_id": { "type": "string" }, "name": { "type": "string" } } } }, "next_after": { "type": [ "string", "null" ] } }, "required": [ "collections", "next_after" ] } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "410": { "description": "Historical idempotency response invalidated by data deletion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "429": { "description": "Rate limit or daily quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds until token availability for RATE_LIMITED responses; daily quota errors may omit this header", "schema": { "type": "integer" } } } }, "500": { "description": "Inference failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "401": { "description": "API key missing, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "404": { "description": "Resource not found in tenant/collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "409": { "description": "Duplicate external_id or sample limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "413": { "description": "Request too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "422": { "description": "Invalid image, no face, multiple faces, or invalid field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } } }, "description": "Required API key scope: read.", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "in": "query", "name": "after", "schema": { "type": "string", "maxLength": 100 }, "description": "Use next_after from the previous response. Null next_after ends pagination." } ] }, "post": { "summary": "Create school", "operationId": "post_v1_collections", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "collection_id": { "type": "string" }, "name": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when returning a stored result", "schema": { "type": "string" } } } }, "410": { "description": "Historical idempotency response invalidated by data deletion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "429": { "description": "Rate limit or daily quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds until token availability for RATE_LIMITED responses; daily quota errors may omit this header", "schema": { "type": "integer" } } } }, "500": { "description": "Inference failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "401": { "description": "API key missing, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "404": { "description": "Resource not found in tenant/collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "409": { "description": "Duplicate external_id or sample limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "413": { "description": "Request too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "422": { "description": "Invalid image, no face, multiple faces, or invalid field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } } }, "description": "Required API key scope: write.", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]+$" }, "description": "Tenant-wide key, retained 24 hours. Same method/path/query/field contents replay without extra units; changed payload gives 409. Multipart boundary/order may differ." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "name" ] } } } } } }, "/v1/collections/{collection_id}": { "delete": { "summary": "Delete school and all subjects/samples", "operationId": "delete_v1_collections_collection_id", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when returning a stored result", "schema": { "type": "string" } } } }, "410": { "description": "Historical idempotency response invalidated by data deletion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "429": { "description": "Rate limit or daily quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds until token availability for RATE_LIMITED responses; daily quota errors may omit this header", "schema": { "type": "integer" } } } }, "500": { "description": "Inference failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "401": { "description": "API key missing, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "404": { "description": "Resource not found in tenant/collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "409": { "description": "Duplicate external_id or sample limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "413": { "description": "Request too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "422": { "description": "Invalid image, no face, multiple faces, or invalid field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } } }, "description": "Required API key scope: write.", "parameters": [ { "in": "path", "name": "collection_id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]+$" }, "description": "Tenant-wide key, retained 24 hours. Same method/path/query/field contents replay without extra units; changed payload gives 409. Multipart boundary/order may differ." } ] } }, "/v1/collections/{collection_id}/subjects": { "get": { "summary": "List subjects", "operationId": "get_v1_collections_collection_id_subjects", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "subjects": { "type": "array", "items": { "type": "object", "properties": { "subject_id": { "type": "string" }, "name": { "type": "string" }, "external_id": { "type": [ "string", "null" ] }, "face_id": { "type": "string" } } } }, "next_after": { "type": [ "string", "null" ] } }, "required": [ "subjects", "next_after" ] } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "410": { "description": "Historical idempotency response invalidated by data deletion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "429": { "description": "Rate limit or daily quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds until token availability for RATE_LIMITED responses; daily quota errors may omit this header", "schema": { "type": "integer" } } } }, "500": { "description": "Inference failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "401": { "description": "API key missing, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "404": { "description": "Resource not found in tenant/collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "409": { "description": "Duplicate external_id or sample limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "413": { "description": "Request too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "422": { "description": "Invalid image, no face, multiple faces, or invalid field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } } }, "description": "Required API key scope: read.", "parameters": [ { "in": "path", "name": "collection_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "in": "query", "name": "after", "schema": { "type": "string", "maxLength": 100 }, "description": "Use next_after from the previous response. Null next_after ends pagination." } ] }, "post": { "summary": "Create subject with first face sample", "operationId": "post_v1_collections_collection_id_subjects", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "subject_id": { "type": "string" }, "name": { "type": "string" }, "external_id": { "type": [ "string", "null" ] }, "face_id": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when returning a stored result", "schema": { "type": "string" } } } }, "410": { "description": "Historical idempotency response invalidated by data deletion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "429": { "description": "Rate limit or daily quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds until token availability for RATE_LIMITED responses; daily quota errors may omit this header", "schema": { "type": "integer" } } } }, "500": { "description": "Inference failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "401": { "description": "API key missing, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "404": { "description": "Resource not found in tenant/collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "409": { "description": "Duplicate external_id or sample limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "413": { "description": "Request too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "422": { "description": "Invalid image, no face, multiple faces, or invalid field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } } }, "description": "Required API key scope: write.", "parameters": [ { "in": "path", "name": "collection_id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]+$" }, "description": "Tenant-wide key, retained 24 hours. Same method/path/query/field contents replay without extra units; changed payload gives 409. Multipart boundary/order may differ." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "external_id": { "type": "string", "maxLength": 200, "description": "Unique within this school when provided" }, "image": { "type": "string", "format": "binary", "description": "JPEG/PNG up to 4 MB and 12 megapixels; upright orientation. Enrollment/verify/compare require exactly one face." } }, "required": [ "name", "image" ] } } } } } }, "/v1/collections/{collection_id}/subjects/{subject_id}": { "get": { "summary": "Get subject metadata", "operationId": "get_v1_collections_collection_id_subjects_subject_id", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "subject_id": { "type": "string" }, "name": { "type": "string" }, "external_id": { "type": [ "string", "null" ] }, "face_id": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "410": { "description": "Historical idempotency response invalidated by data deletion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "429": { "description": "Rate limit or daily quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds until token availability for RATE_LIMITED responses; daily quota errors may omit this header", "schema": { "type": "integer" } } } }, "500": { "description": "Inference failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "401": { "description": "API key missing, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "404": { "description": "Resource not found in tenant/collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "409": { "description": "Duplicate external_id or sample limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "413": { "description": "Request too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "422": { "description": "Invalid image, no face, multiple faces, or invalid field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } } }, "description": "Required API key scope: read.", "parameters": [ { "in": "path", "name": "collection_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "subject_id", "required": true, "schema": { "type": "string" } } ] }, "delete": { "summary": "Delete subject and all face samples", "operationId": "delete_v1_collections_collection_id_subjects_subject_id", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when returning a stored result", "schema": { "type": "string" } } } }, "410": { "description": "Historical idempotency response invalidated by data deletion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "429": { "description": "Rate limit or daily quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds until token availability for RATE_LIMITED responses; daily quota errors may omit this header", "schema": { "type": "integer" } } } }, "500": { "description": "Inference failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "401": { "description": "API key missing, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "404": { "description": "Resource not found in tenant/collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "409": { "description": "Duplicate external_id or sample limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "413": { "description": "Request too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "422": { "description": "Invalid image, no face, multiple faces, or invalid field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } } }, "description": "Required API key scope: write.", "parameters": [ { "in": "path", "name": "collection_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "subject_id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]+$" }, "description": "Tenant-wide key, retained 24 hours. Same method/path/query/field contents replay without extra units; changed payload gives 409. Multipart boundary/order may differ." } ] } }, "/v1/collections/{collection_id}/subjects/{subject_id}/faces": { "get": { "summary": "List face samples", "operationId": "get_v1_collections_collection_id_subjects_subject_id_faces", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "faces": { "type": "array", "items": { "type": "object", "properties": { "face_id": { "type": "string" }, "model_version": { "type": "string" } } } }, "next_after": { "type": [ "string", "null" ] } }, "required": [ "faces", "next_after" ] } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "410": { "description": "Historical idempotency response invalidated by data deletion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "429": { "description": "Rate limit or daily quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds until token availability for RATE_LIMITED responses; daily quota errors may omit this header", "schema": { "type": "integer" } } } }, "500": { "description": "Inference failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "401": { "description": "API key missing, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "404": { "description": "Resource not found in tenant/collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "409": { "description": "Duplicate external_id or sample limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "413": { "description": "Request too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "422": { "description": "Invalid image, no face, multiple faces, or invalid field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } } }, "description": "Required API key scope: read.", "parameters": [ { "in": "path", "name": "collection_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "subject_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "in": "query", "name": "after", "schema": { "type": "string", "maxLength": 100 }, "description": "Use next_after from the previous response. Null next_after ends pagination." } ] }, "post": { "summary": "Add face sample, maximum 10 per subject", "operationId": "post_v1_collections_collection_id_subjects_subject_id_faces", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "face_id": { "type": "string" }, "model_version": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when returning a stored result", "schema": { "type": "string" } } } }, "410": { "description": "Historical idempotency response invalidated by data deletion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "429": { "description": "Rate limit or daily quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds until token availability for RATE_LIMITED responses; daily quota errors may omit this header", "schema": { "type": "integer" } } } }, "500": { "description": "Inference failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "401": { "description": "API key missing, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "404": { "description": "Resource not found in tenant/collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "409": { "description": "Duplicate external_id or sample limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "413": { "description": "Request too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "422": { "description": "Invalid image, no face, multiple faces, or invalid field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } } }, "description": "Required API key scope: write.", "parameters": [ { "in": "path", "name": "collection_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "subject_id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]+$" }, "description": "Tenant-wide key, retained 24 hours. Same method/path/query/field contents replay without extra units; changed payload gives 409. Multipart boundary/order may differ." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "image": { "type": "string", "format": "binary", "description": "JPEG/PNG up to 4 MB and 12 megapixels; upright orientation. Enrollment/verify/compare require exactly one face." } }, "required": [ "image" ] } } } } } }, "/v1/collections/{collection_id}/subjects/{subject_id}/faces/{face_id}": { "delete": { "summary": "Delete one face sample", "operationId": "delete_v1_collections_collection_id_subjects_subject_id_faces_face_id", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when returning a stored result", "schema": { "type": "string" } } } }, "410": { "description": "Historical idempotency response invalidated by data deletion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "429": { "description": "Rate limit or daily quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds until token availability for RATE_LIMITED responses; daily quota errors may omit this header", "schema": { "type": "integer" } } } }, "500": { "description": "Inference failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "401": { "description": "API key missing, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "404": { "description": "Resource not found in tenant/collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "409": { "description": "Duplicate external_id or sample limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "413": { "description": "Request too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "422": { "description": "Invalid image, no face, multiple faces, or invalid field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } } }, "description": "Required API key scope: write.", "parameters": [ { "in": "path", "name": "collection_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "subject_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "face_id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]+$" }, "description": "Tenant-wide key, retained 24 hours. Same method/path/query/field contents replay without extra units; changed payload gives 409. Multipart boundary/order may differ." } ] } }, "/v1/collections/{collection_id}/subjects/{subject_id}/verify": { "post": { "summary": "Verify selfie against one subject, using best sample score", "operationId": "post_v1_collections_collection_id_subjects_subject_id_verify", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "subject_id": { "type": "string" }, "matched": { "type": "boolean" }, "similarity": { "type": [ "number", "null" ] }, "threshold": { "type": "number" }, "threshold_status": { "const": "demo_uncalibrated" }, "liveness": { "const": "not_checked" }, "sample_status": { "enum": [ "available", "no_samples" ] }, "model_version": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when returning a stored result", "schema": { "type": "string" } } } }, "410": { "description": "Historical idempotency response invalidated by data deletion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "429": { "description": "Rate limit or daily quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds until token availability for RATE_LIMITED responses; daily quota errors may omit this header", "schema": { "type": "integer" } } } }, "500": { "description": "Inference failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "401": { "description": "API key missing, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "404": { "description": "Resource not found in tenant/collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "409": { "description": "Duplicate external_id or sample limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "413": { "description": "Request too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "422": { "description": "Invalid image, no face, multiple faces, or invalid field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } } }, "description": "Required API key scope: infer.", "parameters": [ { "in": "path", "name": "collection_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "subject_id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]+$" }, "description": "Tenant-wide key, retained 24 hours. Same method/path/query/field contents replay without extra units; changed payload gives 409. Multipart boundary/order may differ." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "image": { "type": "string", "format": "binary", "description": "JPEG/PNG up to 4 MB and 12 megapixels; upright orientation. Enrollment/verify/compare require exactly one face." } }, "required": [ "image" ] } } } } } }, "/v1/collections/{collection_id}/search": { "post": { "summary": "Find best subject for each face in the image, within one school", "operationId": "post_v1_collections_collection_id_search", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "faces": { "type": "array", "items": { "type": "object", "properties": { "subject": { "anyOf": [ { "$ref": "#/components/schemas/Subject" }, { "type": "null" } ] }, "matched": { "type": "boolean" }, "similarity": { "type": [ "number", "null" ] }, "box": { "type": "array", "items": { "type": "number" }, "minItems": 4, "maxItems": 4 }, "confidence": { "type": "number" } } } }, "face_count": { "type": "integer" }, "threshold": { "type": "number" }, "threshold_status": { "const": "demo_uncalibrated" }, "liveness": { "const": "not_checked" }, "model_version": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when returning a stored result", "schema": { "type": "string" } } } }, "410": { "description": "Historical idempotency response invalidated by data deletion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "429": { "description": "Rate limit or daily quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds until token availability for RATE_LIMITED responses; daily quota errors may omit this header", "schema": { "type": "integer" } } } }, "500": { "description": "Inference failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "401": { "description": "API key missing, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "404": { "description": "Resource not found in tenant/collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "409": { "description": "Duplicate external_id or sample limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "413": { "description": "Request too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "422": { "description": "Invalid image, no face, multiple faces, or invalid field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } } }, "description": "Required API key scope: infer.", "parameters": [ { "in": "path", "name": "collection_id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]+$" }, "description": "Tenant-wide key, retained 24 hours. Same method/path/query/field contents replay without extra units; changed payload gives 409. Multipart boundary/order may differ." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "image": { "type": "string", "format": "binary", "description": "JPEG/PNG up to 4 MB and 12 megapixels; upright orientation. Enrollment/verify/compare require exactly one face." } }, "required": [ "image" ] } } } } } }, "/v1/faces/detect": { "post": { "summary": "Detect faces without storage", "operationId": "post_v1_faces_detect", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when returning a stored result", "schema": { "type": "string" } } } }, "410": { "description": "Historical idempotency response invalidated by data deletion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "429": { "description": "Rate limit or daily quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds until token availability for RATE_LIMITED responses; daily quota errors may omit this header", "schema": { "type": "integer" } } } }, "500": { "description": "Inference failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "401": { "description": "API key missing, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "404": { "description": "Resource not found in tenant/collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "409": { "description": "Duplicate external_id or sample limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "413": { "description": "Request too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "422": { "description": "Invalid image, no face, multiple faces, or invalid field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } } }, "description": "Required API key scope: infer.", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]+$" }, "description": "Tenant-wide key, retained 24 hours. Same method/path/query/field contents replay without extra units; changed payload gives 409. Multipart boundary/order may differ." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "image": { "type": "string", "format": "binary", "description": "JPEG/PNG up to 4 MB and 12 megapixels; upright orientation. Enrollment/verify/compare require exactly one face." } }, "required": [ "image" ] } } } } } }, "/v1/faces/compare": { "post": { "summary": "Compare two images without storage", "operationId": "post_v1_faces_compare", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "subject_id": { "type": "string" }, "matched": { "type": "boolean" }, "similarity": { "type": [ "number", "null" ] }, "threshold": { "type": "number" }, "threshold_status": { "const": "demo_uncalibrated" }, "liveness": { "const": "not_checked" }, "sample_status": { "enum": [ "available", "no_samples" ] }, "model_version": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when returning a stored result", "schema": { "type": "string" } } } }, "410": { "description": "Historical idempotency response invalidated by data deletion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "429": { "description": "Rate limit or daily quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds until token availability for RATE_LIMITED responses; daily quota errors may omit this header", "schema": { "type": "integer" } } } }, "500": { "description": "Inference failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "401": { "description": "API key missing, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "404": { "description": "Resource not found in tenant/collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "409": { "description": "Duplicate external_id or sample limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "413": { "description": "Request too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "422": { "description": "Invalid image, no face, multiple faces, or invalid field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } } }, "description": "Required API key scope: infer.", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]+$" }, "description": "Tenant-wide key, retained 24 hours. Same method/path/query/field contents replay without extra units; changed payload gives 409. Multipart boundary/order may differ." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "image1": { "type": "string", "format": "binary", "description": "JPEG/PNG up to 4 MB and 12 megapixels; upright orientation. Enrollment/verify/compare require exactly one face." }, "image2": { "type": "string", "format": "binary", "description": "JPEG/PNG up to 4 MB and 12 megapixels; upright orientation. Enrollment/verify/compare require exactly one face." } }, "required": [ "image1", "image2" ] } } } } } }, "/portal/v1/auth/register": { "post": { "summary": "Portal POST /auth/register", "security": [], "description": "Same-origin portal endpoint. Admin routes require a database admin role. API keys do not authenticate portal requests.", "responses": { "200": { "description": "Success; registration and key/collection creation return 201" }, "401": { "description": "Session missing or expired" }, "403": { "description": "CSRF or role denied" }, "422": { "description": "Invalid input" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/portal/v1/auth/login": { "post": { "summary": "Portal POST /auth/login", "security": [], "description": "Same-origin portal endpoint. Admin routes require a database admin role. API keys do not authenticate portal requests.", "responses": { "200": { "description": "Success; registration and key/collection creation return 201" }, "401": { "description": "Session missing or expired" }, "403": { "description": "CSRF or role denied" }, "422": { "description": "Invalid input" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/portal/v1/auth/session": { "get": { "summary": "Portal GET /auth/session", "security": [ { "PortalSession": [] } ], "description": "Same-origin portal endpoint. Admin routes require a database admin role. API keys do not authenticate portal requests.", "responses": { "200": { "description": "Success; registration and key/collection creation return 201" }, "401": { "description": "Session missing or expired" }, "403": { "description": "CSRF or role denied" }, "422": { "description": "Invalid input" }, "429": { "description": "Rate limited" } } } }, "/portal/v1/auth/logout": { "post": { "summary": "Portal POST /auth/logout", "security": [ { "PortalSession": [] } ], "description": "Same-origin portal endpoint. Admin routes require a database admin role. API keys do not authenticate portal requests.", "responses": { "200": { "description": "Success; registration and key/collection creation return 201" }, "401": { "description": "Session missing or expired" }, "403": { "description": "CSRF or role denied" }, "422": { "description": "Invalid input" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" }, "description": "csrf_token returned by auth/session or successful login/registration" } ] } }, "/portal/v1/overview": { "get": { "summary": "Portal GET /overview", "security": [ { "PortalSession": [] } ], "description": "Same-origin portal endpoint. Admin routes require a database admin role. API keys do not authenticate portal requests.", "responses": { "200": { "description": "Success; registration and key/collection creation return 201" }, "401": { "description": "Session missing or expired" }, "403": { "description": "CSRF or role denied" }, "422": { "description": "Invalid input" }, "429": { "description": "Rate limited" } } } }, "/portal/v1/keys": { "get": { "summary": "Portal GET /keys", "security": [ { "PortalSession": [] } ], "description": "Same-origin portal endpoint. Admin routes require a database admin role. API keys do not authenticate portal requests.", "responses": { "200": { "description": "Success; registration and key/collection creation return 201" }, "401": { "description": "Session missing or expired" }, "403": { "description": "CSRF or role denied" }, "422": { "description": "Invalid input" }, "429": { "description": "Rate limited" } } }, "post": { "summary": "Portal POST /keys", "security": [ { "PortalSession": [] } ], "description": "Same-origin portal endpoint. Admin routes require a database admin role. API keys do not authenticate portal requests.", "responses": { "200": { "description": "Success; registration and key/collection creation return 201" }, "401": { "description": "Session missing or expired" }, "403": { "description": "CSRF or role denied" }, "422": { "description": "Invalid input" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" }, "description": "csrf_token returned by auth/session or successful login/registration" } ] } }, "/portal/v1/keys/{key_id}/revoke": { "post": { "summary": "Portal POST /keys/{key_id}/revoke", "security": [ { "PortalSession": [] } ], "description": "Same-origin portal endpoint. Admin routes require a database admin role. API keys do not authenticate portal requests.", "responses": { "200": { "description": "Success; registration and key/collection creation return 201" }, "401": { "description": "Session missing or expired" }, "403": { "description": "CSRF or role denied" }, "422": { "description": "Invalid input" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "parameters": [ { "in": "path", "name": "key_id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" }, "description": "csrf_token returned by auth/session or successful login/registration" } ] } }, "/portal/v1/collections": { "get": { "summary": "Portal GET /collections", "security": [ { "PortalSession": [] } ], "description": "Same-origin portal endpoint. Admin routes require a database admin role. API keys do not authenticate portal requests.", "responses": { "200": { "description": "Success; registration and key/collection creation return 201" }, "401": { "description": "Session missing or expired" }, "403": { "description": "CSRF or role denied" }, "422": { "description": "Invalid input" }, "429": { "description": "Rate limited" } } }, "post": { "summary": "Portal POST /collections", "security": [ { "PortalSession": [] } ], "description": "Same-origin portal endpoint. Admin routes require a database admin role. API keys do not authenticate portal requests.", "responses": { "200": { "description": "Success; registration and key/collection creation return 201" }, "401": { "description": "Session missing or expired" }, "403": { "description": "CSRF or role denied" }, "422": { "description": "Invalid input" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" }, "description": "csrf_token returned by auth/session or successful login/registration" } ] } }, "/portal/v1/activity": { "get": { "summary": "Portal GET /activity", "security": [ { "PortalSession": [] } ], "description": "Same-origin portal endpoint. Admin routes require a database admin role. API keys do not authenticate portal requests.", "responses": { "200": { "description": "Success; registration and key/collection creation return 201" }, "401": { "description": "Session missing or expired" }, "403": { "description": "CSRF or role denied" }, "422": { "description": "Invalid input" }, "429": { "description": "Rate limited" } } } }, "/portal/v1/admin/overview": { "get": { "summary": "Portal GET /admin/overview", "security": [ { "PortalSession": [] } ], "description": "Same-origin portal endpoint. Admin routes require a database admin role. API keys do not authenticate portal requests.", "responses": { "200": { "description": "Success; registration and key/collection creation return 201" }, "401": { "description": "Session missing or expired" }, "403": { "description": "CSRF or role denied" }, "422": { "description": "Invalid input" }, "429": { "description": "Rate limited" } } } }, "/portal/v1/admin/tenants": { "get": { "summary": "Portal GET /admin/tenants", "security": [ { "PortalSession": [] } ], "description": "Same-origin portal endpoint. Admin routes require a database admin role. API keys do not authenticate portal requests.", "responses": { "200": { "description": "Success; registration and key/collection creation return 201" }, "401": { "description": "Session missing or expired" }, "403": { "description": "CSRF or role denied" }, "422": { "description": "Invalid input" }, "429": { "description": "Rate limited" } } } }, "/portal/v1/admin/activity": { "get": { "summary": "Portal GET /admin/activity", "security": [ { "PortalSession": [] } ], "description": "Same-origin portal endpoint. Admin routes require a database admin role. API keys do not authenticate portal requests.", "responses": { "200": { "description": "Success; registration and key/collection creation return 201" }, "401": { "description": "Session missing or expired" }, "403": { "description": "CSRF or role denied" }, "422": { "description": "Invalid input" }, "429": { "description": "Rate limited" } } } }, "/portal/v1/face-api/v1/usage": { "get": { "summary": "Daily usage and operation quota for authenticated tenant", "operationId": "portal_webcam_get_v1_usage", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "410": { "description": "Historical idempotency response invalidated by data deletion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "429": { "description": "Rate limit or daily quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds until token availability for RATE_LIMITED responses; daily quota errors may omit this header", "schema": { "type": "integer" } } } }, "500": { "description": "Inference failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "401": { "description": "Session missing or expired" }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "404": { "description": "Resource not found in tenant/collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "409": { "description": "Duplicate external_id or sample limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "413": { "description": "Request too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "422": { "description": "Invalid image, no face, multiple faces, or invalid field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } } }, "description": "Authenticated webcam: tenant comes from session, not headers. Uses the same daily quota and operation ledger as the API. No API key required.", "parameters": [ { "in": "query", "name": "date", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "description": "Asia/Jakarta day YYYY-MM-DD; today by default" } ], "security": [ { "PortalSession": [] } ] } }, "/portal/v1/face-api/v1/collections": { "get": { "summary": "List schools", "operationId": "portal_webcam_get_v1_collections", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "collections": { "type": "array", "items": { "type": "object", "properties": { "collection_id": { "type": "string" }, "name": { "type": "string" } } } }, "next_after": { "type": [ "string", "null" ] } }, "required": [ "collections", "next_after" ] } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "410": { "description": "Historical idempotency response invalidated by data deletion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "429": { "description": "Rate limit or daily quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds until token availability for RATE_LIMITED responses; daily quota errors may omit this header", "schema": { "type": "integer" } } } }, "500": { "description": "Inference failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "401": { "description": "Session missing or expired" }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "404": { "description": "Resource not found in tenant/collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "409": { "description": "Duplicate external_id or sample limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "413": { "description": "Request too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "422": { "description": "Invalid image, no face, multiple faces, or invalid field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } } }, "description": "Authenticated webcam: tenant comes from session, not headers. Uses the same daily quota and operation ledger as the API. No API key required.", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "in": "query", "name": "after", "schema": { "type": "string", "maxLength": 100 }, "description": "Use next_after from the previous response. Null next_after ends pagination." } ], "security": [ { "PortalSession": [] } ] }, "post": { "summary": "Create school", "operationId": "portal_webcam_post_v1_collections", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "collection_id": { "type": "string" }, "name": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when returning a stored result", "schema": { "type": "string" } } } }, "410": { "description": "Historical idempotency response invalidated by data deletion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "429": { "description": "Rate limit or daily quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds until token availability for RATE_LIMITED responses; daily quota errors may omit this header", "schema": { "type": "integer" } } } }, "500": { "description": "Inference failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "401": { "description": "Session missing or expired" }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "404": { "description": "Resource not found in tenant/collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "409": { "description": "Duplicate external_id or sample limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "413": { "description": "Request too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "422": { "description": "Invalid image, no face, multiple faces, or invalid field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } } }, "description": "Authenticated webcam: tenant comes from session, not headers. Uses the same daily quota and operation ledger as the API. No API key required.", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]+$" }, "description": "Tenant-wide key, retained 24 hours. Same method/path/query/field contents replay without extra units; changed payload gives 409. Multipart boundary/order may differ." }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "name" ] } } } }, "security": [ { "PortalSession": [] } ] } }, "/portal/v1/face-api/v1/collections/{collection_id}/subjects": { "get": { "summary": "List subjects", "operationId": "portal_webcam_get_v1_collections_collection_id_subjects", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "subjects": { "type": "array", "items": { "type": "object", "properties": { "subject_id": { "type": "string" }, "name": { "type": "string" }, "external_id": { "type": [ "string", "null" ] }, "face_id": { "type": "string" } } } }, "next_after": { "type": [ "string", "null" ] } }, "required": [ "subjects", "next_after" ] } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "410": { "description": "Historical idempotency response invalidated by data deletion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "429": { "description": "Rate limit or daily quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds until token availability for RATE_LIMITED responses; daily quota errors may omit this header", "schema": { "type": "integer" } } } }, "500": { "description": "Inference failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "401": { "description": "Session missing or expired" }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "404": { "description": "Resource not found in tenant/collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "409": { "description": "Duplicate external_id or sample limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "413": { "description": "Request too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "422": { "description": "Invalid image, no face, multiple faces, or invalid field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } } }, "description": "Authenticated webcam: tenant comes from session, not headers. Uses the same daily quota and operation ledger as the API. No API key required.", "parameters": [ { "in": "path", "name": "collection_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "in": "query", "name": "after", "schema": { "type": "string", "maxLength": 100 }, "description": "Use next_after from the previous response. Null next_after ends pagination." } ], "security": [ { "PortalSession": [] } ] }, "post": { "summary": "Create subject with first face sample", "operationId": "portal_webcam_post_v1_collections_collection_id_subjects", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "subject_id": { "type": "string" }, "name": { "type": "string" }, "external_id": { "type": [ "string", "null" ] }, "face_id": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when returning a stored result", "schema": { "type": "string" } } } }, "410": { "description": "Historical idempotency response invalidated by data deletion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "429": { "description": "Rate limit or daily quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds until token availability for RATE_LIMITED responses; daily quota errors may omit this header", "schema": { "type": "integer" } } } }, "500": { "description": "Inference failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "401": { "description": "Session missing or expired" }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "404": { "description": "Resource not found in tenant/collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "409": { "description": "Duplicate external_id or sample limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "413": { "description": "Request too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "422": { "description": "Invalid image, no face, multiple faces, or invalid field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } } }, "description": "Authenticated webcam: tenant comes from session, not headers. Uses the same daily quota and operation ledger as the API. No API key required.", "parameters": [ { "in": "path", "name": "collection_id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]+$" }, "description": "Tenant-wide key, retained 24 hours. Same method/path/query/field contents replay without extra units; changed payload gives 409. Multipart boundary/order may differ." }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "external_id": { "type": "string", "maxLength": 200, "description": "Unique within this school when provided" }, "image": { "type": "string", "format": "binary", "description": "JPEG/PNG up to 4 MB and 12 megapixels; upright orientation. Enrollment/verify/compare require exactly one face." } }, "required": [ "name", "image" ] } } } }, "security": [ { "PortalSession": [] } ] } }, "/portal/v1/face-api/v1/collections/{collection_id}/subjects/{subject_id}": { "delete": { "summary": "Delete subject and all face samples", "operationId": "portal_webcam_delete_v1_collections_collection_id_subjects_subject_id", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when returning a stored result", "schema": { "type": "string" } } } }, "410": { "description": "Historical idempotency response invalidated by data deletion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "429": { "description": "Rate limit or daily quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds until token availability for RATE_LIMITED responses; daily quota errors may omit this header", "schema": { "type": "integer" } } } }, "500": { "description": "Inference failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "401": { "description": "Session missing or expired" }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "404": { "description": "Resource not found in tenant/collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "409": { "description": "Duplicate external_id or sample limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "413": { "description": "Request too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "422": { "description": "Invalid image, no face, multiple faces, or invalid field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } } }, "description": "Authenticated webcam: tenant comes from session, not headers. Uses the same daily quota and operation ledger as the API. No API key required.", "parameters": [ { "in": "path", "name": "collection_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "subject_id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]+$" }, "description": "Tenant-wide key, retained 24 hours. Same method/path/query/field contents replay without extra units; changed payload gives 409. Multipart boundary/order may differ." }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "security": [ { "PortalSession": [] } ] } }, "/portal/v1/face-api/v1/collections/{collection_id}/search": { "post": { "summary": "Find best subject for each face in the image, within one school", "operationId": "portal_webcam_post_v1_collections_collection_id_search", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "faces": { "type": "array", "items": { "type": "object", "properties": { "subject": { "anyOf": [ { "$ref": "#/components/schemas/Subject" }, { "type": "null" } ] }, "matched": { "type": "boolean" }, "similarity": { "type": [ "number", "null" ] }, "box": { "type": "array", "items": { "type": "number" }, "minItems": 4, "maxItems": 4 }, "confidence": { "type": "number" } } } }, "face_count": { "type": "integer" }, "threshold": { "type": "number" }, "threshold_status": { "const": "demo_uncalibrated" }, "liveness": { "const": "not_checked" }, "model_version": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when returning a stored result", "schema": { "type": "string" } } } }, "410": { "description": "Historical idempotency response invalidated by data deletion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "429": { "description": "Rate limit or daily quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds until token availability for RATE_LIMITED responses; daily quota errors may omit this header", "schema": { "type": "integer" } } } }, "500": { "description": "Inference failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "401": { "description": "Session missing or expired" }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "404": { "description": "Resource not found in tenant/collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "409": { "description": "Duplicate external_id or sample limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "413": { "description": "Request too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "422": { "description": "Invalid image, no face, multiple faces, or invalid field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "description": "Server-generated request identifier", "schema": { "type": "string" } } } } }, "description": "Authenticated webcam: tenant comes from session, not headers. Uses the same daily quota and operation ledger as the API. No API key required.", "parameters": [ { "in": "path", "name": "collection_id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]+$" }, "description": "Tenant-wide key, retained 24 hours. Same method/path/query/field contents replay without extra units; changed payload gives 409. Multipart boundary/order may differ." }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "image": { "type": "string", "format": "binary", "description": "JPEG/PNG up to 4 MB and 12 megapixels; upright orientation. Enrollment/verify/compare require exactly one face." } }, "required": [ "image" ] } } } }, "security": [ { "PortalSession": [] } ] } } }, "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "PortalSession": { "type": "apiKey", "in": "cookie", "name": "fr_session" } }, "schemas": { "Subject": { "type": "object", "properties": { "subject_id": { "type": "string" }, "name": { "type": "string" }, "external_id": { "type": [ "string", "null" ] }, "face_id": { "type": "string" } } }, "Collection": { "type": "object", "properties": { "collection_id": { "type": "string" }, "name": { "type": "string" } } }, "FaceSample": { "type": "object", "properties": { "face_id": { "type": "string" }, "model_version": { "type": "string" } } }, "Match": { "type": "object", "properties": { "subject": { "anyOf": [ { "$ref": "#/components/schemas/Subject" }, { "type": "null" } ] }, "matched": { "type": "boolean" }, "similarity": { "type": [ "number", "null" ] }, "box": { "type": "array", "items": { "type": "number" }, "minItems": 4, "maxItems": 4 }, "confidence": { "type": "number" } } }, "Verification": { "type": "object", "properties": { "subject_id": { "type": "string" }, "matched": { "type": "boolean" }, "similarity": { "type": [ "number", "null" ] }, "threshold": { "type": "number" }, "threshold_status": { "const": "demo_uncalibrated" }, "liveness": { "const": "not_checked" }, "sample_status": { "enum": [ "available", "no_samples" ] }, "model_version": { "type": "string" } } }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code" ] } }, "required": [ "error" ] } } } }