{ "openapi": "3.1.0", "info": { "title": "Lukhoo Attorney Integration API", "version": "1.0.0", "description": "Server-to-server attorney integration. JSON over HTTPS; IDs are strings. Access is checked against current membership, the attorney identity, the contact window and client permissions. Webhook events contain references, not private message or incident content. Console routes use a separate browser session." }, "servers": [ { "url": "https://lukhoo.com/api/attorney/v1" } ], "paths": { "/incidents": { "get": { "summary": "List visible incident summaries and unlocked details", "description": "Required scope: incidents:read. The incidents after parameter is a current-list offset. Rescan from 0 after incident events; do not treat offsets as a durable change cursor.", "operationId": "get__incidents", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "after", "in": "query", "schema": { "type": "string", "default": "0" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Incident" } }, "next_after": { "type": [ "string", "null" ] } }, "required": [] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Membership, scope, or client permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Required source unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/incidents/{videoId}": { "get": { "summary": "Read a currently permitted incident", "description": "Required scope: incidents:read. ", "operationId": "get__incidents_videoId", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "videoId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Incident" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Membership, scope, or client permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Required source unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/incidents/{videoId}/contact": { "post": { "summary": "Start or resume the 24-hour contact window", "description": "Required scope: engagements:write. Client contact permission and reservation rules apply. Membership alone does not create a contact window.", "operationId": "post__incidents_videoId_contact", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "videoId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Reuse the same key and body when retrying an uncertain request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactResult" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Membership, scope, or client permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Required source unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/incidents/{videoId}/artifacts/{kind}": { "get": { "summary": "Download permitted evidence", "description": "Required scope: incidents:read. kind is video, transcript, or legal_brief. Requires an unlocked incident, current sharing permission and configured S3 storage. Response is the file stream; no reusable storage URL is disclosed.", "operationId": "get__incidents_videoId_artifacts_kind", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "videoId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kind", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Range", "in": "header", "schema": { "type": "string" }, "description": "Optional single bytes=start-end range." } ], "responses": { "200": { "description": "Authorized file", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Membership, scope, or client permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Required source unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/conversations": { "get": { "summary": "List this attorney's conversations", "description": "Required scope: messages:read. ", "operationId": "get__conversations", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "after", "in": "query", "schema": { "type": "string", "default": "0" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" } }, "next_after": { "type": [ "string", "null" ] } }, "required": [] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Membership, scope, or client permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Required source unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/conversations/{id}": { "get": { "summary": "Read conversation and both hire confirmations", "description": "Required scope: messages:read. ", "operationId": "get__conversations_id", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Membership, scope, or client permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Required source unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/conversations/{id}/messages": { "get": { "summary": "Read shared conversation messages", "description": "Required scope: messages:read. ", "operationId": "get__conversations_id_messages", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "after", "in": "query", "schema": { "type": "string", "default": "0" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "next_after": { "type": [ "string", "null" ] } }, "required": [] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Membership, scope, or client permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Required source unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Send a message to the client", "description": "Required scope: messages:write. ", "operationId": "post__conversations_id_messages", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Reuse the same key and body when retrying an uncertain request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 524 } }, "required": [ "body" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResult" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Membership, scope, or client permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Required source unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/messages/{id}": { "get": { "summary": "Read one currently permitted message", "description": "Required scope: messages:read. ", "operationId": "get__messages_id", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Membership, scope, or client permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Required source unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/conversations/{id}/read": { "post": { "summary": "Mark received messages read in Lukhoo", "description": "Required scope: messages:write. ", "operationId": "post__conversations_id_read", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "through_id": { "type": "string" } }, "required": [ "through_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "read_through": { "type": "string" } }, "required": [] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Membership, scope, or client permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Required source unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/conversations/{id}/hire-confirmation": { "post": { "summary": "Record the attorney's hiring confirmation", "description": "Required scope: engagements:write. This never sets the client confirmation. Both parties must confirm. Messaging may continue after confirmation.", "operationId": "post__conversations_id_hire_confirmation", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Reuse the same key and body when retrying an uncertain request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirm": { "type": "boolean", "const": true } }, "required": [ "confirm" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HireResult" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Membership, scope, or client permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Required source unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/events": { "get": { "summary": "Read event references with a durable sequence cursor", "description": "Only events allowed by the key scopes are returned. Fetch referenced resources to obtain current authorized data. Expect at-least-once delivery and deduplicate event_id.", "operationId": "get__events", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "after", "in": "query", "schema": { "type": "string", "default": "0" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "next_after": { "type": [ "string", "null" ] } }, "required": [] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Membership, scope, or client permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Required source unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/console/session": { "post": { "summary": "Verify attorney credentials for a console session", "description": "Same-origin browser request. Verifies the existing attorney password and verified flag, then sets an HttpOnly cookie. Not an external API authentication method.", "operationId": "post__console_session", "security": [], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "format": "password" } }, "required": [ "email", "password" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Membership, scope, or client permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Required source unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "Read console identity and CSRF token", "description": "", "operationId": "get__console_session", "security": [ { "ConsoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Membership, scope, or client permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Required source unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "End the API console session", "description": "", "operationId": "delete__console_session", "security": [ { "ConsoleSession": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "signed_out": { "type": "boolean" } }, "required": [] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Membership, scope, or client permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Required source unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/console/overview": { "get": { "summary": "Read current records and integration metrics", "description": "", "operationId": "get__console_overview", "security": [ { "ConsoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "membership": { "type": "object", "properties": { "api": { "type": "boolean" }, "portal": { "type": "boolean" }, "checked_at": { "type": "string", "format": "date-time" } }, "required": [] }, "incidents": { "type": "array", "items": { "$ref": "#/components/schemas/Incident" } }, "conversations": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" } }, "metrics": { "type": "object", "properties": { "live_incident_alerts": { "type": "integer" }, "detailed_unlocked": { "type": "integer" }, "current_clients": { "type": "integer" }, "new_messages": { "type": "integer" }, "visible_summaries": { "type": "integer" }, "webhook_endpoints": { "type": "integer" }, "events_this_month": { "type": "integer" }, "integration_requests_this_month": { "type": "integer" }, "webhook_delivery_attempts_this_month": { "type": "integer" }, "webhook_failed_deliveries_this_month": { "type": "integer" }, "last_successful_delivery_at": { "type": [ "string", "null" ], "format": "date-time" }, "delivery_success": { "type": [ "string", "null" ] } }, "required": [] }, "as_of": { "type": "string", "format": "date-time" }, "sync": { "type": "object", "properties": { "synced_at": { "type": [ "string", "null" ] }, "sync_error": { "type": [ "string", "null" ] }, "interval_seconds": { "type": "integer" } }, "required": [] } }, "required": [] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Membership, scope, or client permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Required source unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/console/keys": { "get": { "summary": "List key metadata", "description": "", "operationId": "get__console_keys", "security": [ { "ConsoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Key" } }, "next_after": { "type": [ "string", "null" ] } }, "required": [] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Membership, scope, or client permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Required source unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a scoped key; secret returned once", "description": "", "operationId": "post__console_keys", "security": [ { "ConsoleSession": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 80 }, "scopes": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "incidents:read", "messages:read", "messages:write", "engagements:write" ] } } }, "required": [ "label", "scopes" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Key" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Membership, scope, or client permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Required source unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/console/keys/{id}/rotate": { "post": { "summary": "Replace and immediately revoke the previous key", "description": "", "operationId": "post__console_keys_id_rotate", "security": [ { "ConsoleSession": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 80 }, "scopes": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "incidents:read", "messages:read", "messages:write", "engagements:write" ] } } }, "required": [ "label", "scopes" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Key" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Membership, scope, or client permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Required source unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/console/keys/{id}": { "delete": { "summary": "Revoke a key", "description": "", "operationId": "delete__console_keys_id", "security": [ { "ConsoleSession": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "boolean" } }, "required": [] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Membership, scope, or client permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Required source unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/console/endpoints": { "get": { "summary": "List webhook endpoints", "description": "", "operationId": "get__console_endpoints", "security": [ { "ConsoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Endpoint" } }, "next_after": { "type": [ "string", "null" ] } }, "required": [] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Membership, scope, or client permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Required source unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Register an HTTPS endpoint or synthetic test receiver", "description": "", "operationId": "post__console_endpoints", "security": [ { "ConsoleSession": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "events" ], "additionalProperties": false }, { "type": "object", "properties": { "test_receiver": { "type": "boolean", "const": true } }, "required": [ "test_receiver" ], "additionalProperties": false } ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Endpoint" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Membership, scope, or client permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Required source unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/console/endpoints/{id}": { "patch": { "summary": "Pause or resume event delivery", "description": "", "operationId": "patch__console_endpoints_id", "security": [ { "ConsoleSession": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Membership, scope, or client permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Required source unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/console/endpoints/{id}/test": { "post": { "summary": "Queue a signed synthetic test event", "description": "", "operationId": "post__console_endpoints_id_test", "security": [ { "ConsoleSession": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } } } }, "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "event_id": { "type": "string" }, "status": { "type": "string" } }, "required": [] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Membership, scope, or client permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Required source unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/console/deliveries": { "get": { "summary": "Read recent delivery outcomes", "description": "", "operationId": "get__console_deliveries", "security": [ { "ConsoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Delivery" } }, "next_after": { "type": [ "string", "null" ] } }, "required": [] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Membership, scope, or client permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Required source unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/console/usage": { "get": { "summary": "Read API-key-authenticated request counts, errors and average latency by route", "description": "Browser console activity is excluded. This reports only firm integration traffic authenticated with an API key.", "operationId": "get__console_usage", "security": [ { "ConsoleSession": [] } ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string" }, "requests": { "type": "integer" }, "errors": { "type": "integer" }, "average_ms": { "type": "integer" } }, "required": [] } }, "period": { "type": "string" } }, "required": [] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Membership, scope, or client permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Required source unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/console/deliveries/{id}/retry": { "post": { "summary": "Requeue a failed delivery", "description": "", "operationId": "post__console_deliveries_id_retry", "security": [ { "ConsoleSession": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } }, "required": [] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Membership, scope, or client permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Required source unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "lk_live_..." }, "ConsoleSession": { "type": "apiKey", "in": "cookie", "name": "__Secure-lukhoo_api_session" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "required": [ "error" ] }, "Client": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" } }, "required": [ "id", "name" ] }, "Incident": { "type": "object", "properties": { "video_id": { "type": "string" }, "incident_type": { "type": "string" }, "state": { "type": "string" }, "started_at": { "type": [ "string", "null" ] }, "score": {}, "access": { "type": "string", "enum": [ "summary", "details" ] }, "engagement_status": { "type": "string", "enum": [ "available", "communication_open", "hired" ] }, "contact_expires_at": { "type": [ "string", "null" ] }, "conversation_id": { "type": [ "string", "null" ] }, "can_contact": { "type": "boolean" }, "details": { "type": "object", "properties": { "client": { "$ref": "#/components/schemas/Client" }, "address": { "type": "string" }, "latitude": {}, "longitude": {}, "evidence": { "type": "object", "properties": { "video": { "type": "boolean" }, "transcript": { "type": "boolean" }, "legal_brief": { "type": "boolean" } }, "required": [] } }, "required": [] } }, "required": [ "video_id", "access", "can_contact" ] }, "Hire": { "type": "object", "properties": { "client_confirmed": { "type": "boolean" }, "attorney_confirmed": { "type": "boolean" }, "status": { "type": "string", "enum": [ "pending", "confirmed", "closed" ] } }, "required": [ "status" ] }, "Conversation": { "type": "object", "properties": { "id": { "type": "string" }, "client_id": { "type": "string" }, "video_id": { "type": [ "string", "null" ] }, "incident_key": { "type": [ "string", "null" ] }, "client_name": { "type": "string" }, "status": { "type": "string" }, "contact_expires_at": { "type": [ "string", "null" ] }, "unread_messages": { "type": "integer" }, "hire": { "$ref": "#/components/schemas/Hire" }, "can_message": { "type": "boolean" }, "can_confirm_hire": { "type": "boolean" } }, "required": [ "id", "hire", "can_message", "can_confirm_hire" ] }, "Message": { "type": "object", "properties": { "id": { "type": "string" }, "conversation_id": { "type": "string" }, "sender_role": { "type": "string", "enum": [ "attorney", "client" ] }, "body": { "type": "string", "maxLength": 524 }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "body", "sender_role", "created_at" ] }, "Event": { "type": "object", "properties": { "spec_version": { "type": "string", "const": "1.0" }, "event_id": { "type": "string", "format": "uuid" }, "sequence": { "type": "string" }, "event_type": { "type": "string", "enum": [ "incident.created", "incident.updated", "incident.removed", "conversation.updated", "message.created", "message.updated", "test.delivery" ] }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "resource_type": { "type": "string" }, "resource_id": { "type": "string" }, "resource_url": { "type": [ "string", "null" ] } }, "required": [ "resource_type", "resource_id" ] } }, "required": [ "event_id", "sequence", "event_type", "created_at", "data" ] }, "Key": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "expires_at": { "type": "string", "format": "date-time" }, "revoked_at": { "type": [ "string", "null" ] }, "secret": { "type": "string", "description": "Returned only on creation or rotation. Never recoverable." } }, "required": [] }, "Endpoint": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "verified_at": { "type": [ "string", "null" ] }, "signing_secret": { "type": "string", "description": "Returned once on creation." } }, "required": [] }, "Delivery": { "type": "object", "properties": { "id": { "type": "string" }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "sending", "delivered", "failed", "suppressed" ] }, "attempts": { "type": "integer" }, "http_status": { "type": [ "integer", "null" ] }, "updated_at": { "type": "string", "format": "date-time" }, "signature_verified": { "type": "boolean" } }, "required": [] }, "Session": { "type": "object", "properties": { "attorney_id": { "type": "string" }, "name": { "type": "string" }, "csrf_token": { "type": "string" } }, "required": [ "attorney_id", "name", "csrf_token" ] }, "ContactResult": { "type": "object", "properties": { "conversation_id": { "type": "string" }, "video_id": { "type": "string" }, "contact_expires_at": { "type": "string", "format": "date-time" } }, "required": [] }, "MessageResult": { "type": "object", "properties": { "message_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [] }, "HireResult": { "type": "object", "properties": { "conversation_id": { "type": "string" }, "hire": { "$ref": "#/components/schemas/Hire" } }, "required": [] } } }, "webhooks": { "event": { "post": { "summary": "Reference event sent to a verified endpoint", "parameters": [ { "name": "Lukhoo-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=UNIX_SECONDS,v1=HMAC_SHA256(secret,timestamp + dot + raw_body). Reject timestamps older than 5 minutes." }, { "name": "Lukhoo-Delivery-Id", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Event durably accepted. Duplicate events should also return 2xx." } } } } } }