{ "openapi": "3.0.0", "info": { "title": "Propper Locker API", "version": "1.0.0", "description": "\nDocument Storage & Chat API for the Propper Platform.\n\n## Base URL\n\n- **Production:** `https://api.propper.ai/v1/locker`\n\n## Authentication\n\nOAuth 2.0 Bearer token:\n\n```\nAuthorization: Bearer \n```\n\n## OAuth Scopes\n\n| Scope | Description |\n|-------|-------------|\n| `locker:read` | Read documents, download files, chat |\n| `locker:write` | Create documents |\n| `locker:admin` | Administrative operations (grants read + write) |\n\n## Key Endpoints\n\n- `GET /v1/locker/documents` - List documents\n- `POST /v1/locker/documents` - Create document\n- `GET /v1/locker/documents/:id/download` - Download document\n- `POST /v1/locker/chat` - Chat with documents\n- `POST /v1/locker/chat/stream` - Chat with documents (SSE streaming)\n\n## Rate Limits\n\n| Category | Limit |\n|----------|-------|\n| Default | 300 req/min |\n| Chat | 30 req/min |\n| Downloads | 120 req/min |\n" }, "servers": [ { "url": "https://api.propper.ai", "description": "Production environment" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "OAuth 2.0 access token" } } }, "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Documents", "description": "Document storage and retrieval" }, { "name": "Chat", "description": "AI chat with documents" } ], "paths": { "/v1/locker/chat": { "post": { "summary": "Chat with documents", "tags": [ "Chat" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "maxLength": 4000 }, "sessionId": { "type": "string" }, "documentIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "topK": { "type": "integer", "minimum": 1, "maximum": 20 }, "history": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" } } } } } } } } }, "responses": { "200": { "description": "Chat response with answer and sources" } } } }, "/v1/locker/chat/stream": { "post": { "summary": "Chat with documents (SSE streaming)", "tags": [ "Chat" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "maxLength": 4000 }, "sessionId": { "type": "string" }, "documentIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "topK": { "type": "integer", "minimum": 1, "maximum": 20 }, "history": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" } } } } } } } } }, "responses": { "200": { "description": "SSE stream of chat response chunks", "content": { "text/event-stream": { "schema": { "type": "string" } } } } } } }, "/v1/locker/documents": { "get": { "summary": "List documents", "tags": [ "Documents" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "folderId", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "search", "schema": { "type": "string" } }, { "in": "query", "name": "mimeType", "schema": { "type": "string" } }, { "in": "query", "name": "sortBy", "schema": { "type": "string", "enum": [ "name", "createdAt", "updatedAt", "size" ] } }, { "in": "query", "name": "sortOrder", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "in": "query", "name": "page", "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List of documents" } } }, "post": { "summary": "Create a document", "tags": [ "Documents" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "fileUrl" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "documentType": { "type": "string", "default": "OTHER" }, "source": { "type": "string", "default": "UPLOADED" }, "fileUrl": { "type": "string" }, "mimeType": { "type": "string", "default": "application/pdf" }, "sizeBytes": { "type": "integer", "default": 0 }, "sha256": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "201": { "description": "Document created" } } } }, "/v1/locker/documents/{id}": { "get": { "summary": "Get document by ID", "tags": [ "Documents" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Document details" }, "404": { "description": "Document not found" } } }, "patch": { "summary": "Update document metadata", "tags": [ "Documents" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "documentType": { "type": "string" }, "folderId": { "type": "string", "format": "uuid", "nullable": true } } } } } }, "responses": { "200": { "description": "Updated document" }, "400": { "description": "Invalid request body" }, "404": { "description": "Document not found" } } }, "delete": { "summary": "Delete a document", "description": "Soft-deletes the document by default. Pass ?purge=true to permanently delete the document and all associated data. Purge requires locker:admin scope.", "tags": [ "Documents" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "purge", "schema": { "type": "boolean", "default": false } } ], "responses": { "204": { "description": "Document deleted" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Document not found" } } } }, "/v1/locker/documents/{id}/download": { "get": { "summary": "Download a document", "tags": [ "Documents" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Document binary content" }, "404": { "description": "Document not found" } } } }, "/v1/locker/documents/upload": { "post": { "summary": "Upload a document", "description": "Upload a document via base64-encoded JSON or multipart/form-data. For JSON, provide a base64-encoded document string. For multipart, attach the file as 'file' with metadata fields. Maximum file size is 50MB.", "tags": [ "Documents" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "document", "name" ], "properties": { "document": { "type": "string", "description": "Base64-encoded document content" }, "name": { "type": "string" }, "description": { "type": "string" }, "documentType": { "type": "string", "default": "OTHER" }, "mimeType": { "type": "string", "default": "application/pdf" }, "tags": { "type": "array", "items": { "type": "string" } } } } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "file", "name" ], "properties": { "file": { "type": "string", "format": "binary" }, "name": { "type": "string" }, "description": { "type": "string" }, "documentType": { "type": "string", "default": "OTHER" }, "tags": { "type": "string", "description": "Comma-separated tags or repeated field" } } } } } }, "responses": { "201": { "description": "Document created" }, "400": { "description": "Invalid request" }, "413": { "description": "File too large" } } } } } }