Locker API Overview
The Locker API enables you to store, manage, and chat with documents programmatically. Upload files, organize with metadata and tags, and use AI-powered chat to query document contents.
Key Features
- Document Storage - Upload, organize, and retrieve documents with metadata and tags
- AI Chat - Ask questions about your documents using natural language
- Streaming Responses - Real-time AI chat responses via Server-Sent Events (SSE)
- Structured AI Search - Search document contents with discoverable metadata filters and grounded citations
- Flexible Upload - Upload via base64-encoded JSON or multipart form data (up to 50 MB)
Architecture
Core Concepts
Document
A document is a file stored in Propper Locker with associated metadata. Documents can be uploaded, organized with tags, and queried via AI chat.
Chat Session
A chat session lets you ask questions about one or more documents. The AI engine uses document contents to generate answers with source references. Sessions can maintain conversation history for follow-up questions.
Document Types
| Type | Description |
|---|---|
CONTRACT | Legal contracts and agreements |
INVOICE | Invoices and billing documents |
REPORT | Reports and analyses |
POLICY | Policies and compliance documents |
OTHER | General documents (default) |
API Base URL
| Environment | Base URL |
|---|---|
| Production | https://api.propper.ai/v1/locker |
Authentication
The Locker API uses OAuth 2.0 with bearer tokens:
POST https://auth.propper.ai/oauth2/token
Content-Type: application/json
{
"grant_type": "client_credentials",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"scope": "locker:read locker:write"
}
OAuth Scopes
| Scope | Description |
|---|---|
locker:read | Read documents, download files, chat with documents |
locker:write | Create and update documents, upload files |
locker:admin | Administrative operations including purge (grants read + write) |
AI Search and Contract Discovery
Locker uses a provider-neutral structured filter contract. Discover the metadata facets, operators, value kinds, limits, and contract versions available to your organization before building a search UI or query. Metadata filters refine search relevance; OAuth scopes and organization isolation remain the access-control boundary.
| Method | Endpoint | Scope | Purpose |
|---|---|---|---|
POST | /v1/locker/search | locker:read | Search with optional structured metadata clauses and receive grounded sources |
POST | /v1/locker/chat | locker:read | Chat with optional structured metadata clauses |
POST | /v1/locker/chat/stream | locker:read | Stream chat responses with the same filter contract |
GET | /v1/locker/settings | locker:read | Discover supported filters, citation facts, result contracts, and limits |
Filter keys are intentionally not hard-coded in the request schema. Use the ai block of
GET /v1/locker/settings to determine which keys and operators are currently supported,
then send those clauses to search or chat. This lets integrations adopt new safe metadata
facets without changing their request envelope. Organizations without AI features receive
"ai": { "enabled": false }.
Facets may include an optional machine-readable format. For example, date-like numeric
facets advertise unix-seconds, so range bounds use seconds since the Unix epoch. Clients
should use the discovered format instead of inferring units from a facet name.
Rate Limits
| Category | Limit |
|---|---|
| Default | 300 req/min |
| Chat | 30 req/min |
| Downloads | 120 req/min |
See the Rate Limits page for details on limits, headers, and best practices.
Next Steps
Quickstart
Upload a document and chat with it in 5 minutes.
API Reference
Complete endpoint documentation with examples.