Upload, share, and track PDFs from anywhere
A small, predictable JSON API over the same engine as the dashboard. Authenticate with OAuth, upload a deck, email tracking links, and read back who actually engaged.
Connect with OAuth
Register a client, send your user through the consent screen, and exchange the code for an access token. No API keys to store.
Upload a PDF
Request a presigned URL, PUT the file straight to storage, then create the document. Files up to 250 MB.
Share and measure
Email a personal tracking link to each recipient, then poll for view counts, intent scores, and most-read pages.
Authentication
Every endpoint is authenticated with an OAuth 2.1 access token sent as a bearer token. There are no API keys: your users approve access with their existing Replay Docs login and can revoke it at any time.
Clients register themselves, so there is nothing to request from us. Start at the discovery document, which lists the authorize, token, and registration endpoints.
PKCE with S256 is required, and the scope you request must be api. Access tokens last one hour; refresh tokens last 90 days and rotate on every use.
Base URL
https://www.replaydocs.com/api/v1Discovery
https://www.replaydocs.com/.well-known/oauth-authorization-serverAuthenticated request
curl https://www.replaydocs.com/api/v1/documents \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"1. Register a client
Dynamic client registration returns a client_id. Public clients only, so there is no secret to protect.
curl -X POST https://www.replaydocs.com/api/oauth/register \
-H "Content-Type: application/json" \
-d '{
"client_name": "My integration",
"redirect_uris": ["https://example.com/oauth/callback"]
}'2. Send the user to authorize
They log in, review what you are asking for, and are redirected back with a single-use code valid for 60 seconds.
https://www.replaydocs.com/oauth/authorize
?response_type=code
&client_id=YOUR_CLIENT_ID
&redirect_uri=https://example.com/oauth/callback
&scope=api
&code_challenge=YOUR_CODE_CHALLENGE
&code_challenge_method=S256
&state=YOUR_STATE3. Exchange for a token
Post the code and your PKCE verifier as form-encoded fields to receive an access token and a refresh token.
curl -X POST https://www.replaydocs.com/api/oauth/token \
-d grant_type=authorization_code \
-d client_id=YOUR_CLIENT_ID \
-d code=AUTHORIZATION_CODE \
-d code_verifier=YOUR_CODE_VERIFIER \
-d redirect_uri=https://example.com/oauth/callbackThree calls to add a PDF
The file goes straight to storage rather than through the API, so uploads are not capped by a request body limit. PDFs can be up to 250 MB.
1. Request a presigned URL
Tell us the filename. You get back the normalized document name, a storage key, and a URL that accepts the file for the next five minutes.
curl -X POST https://www.replaydocs.com/api/v1/documents/upload-url \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"fileName": "Q3 Proposal.pdf"}'2. Upload the file
PUT the raw PDF bytes to the uploadUrl with a Content-Type of application/pdf. This goes straight to storage, bypassing the usual request body cap, so the only limit is the 250 MB maximum file size.
curl -X PUT "UPLOAD_URL" \
-H "Content-Type: application/pdf" \
--data-binary @"Q3 Proposal.pdf"3. Create the document
Pass back the name and storageKey from step one. We confirm the file landed and is within the 250 MB limit before recording the document, then return its id.
curl -X POST https://www.replaydocs.com/api/v1/documents \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Q3 Proposal.pdf",
"storageKey": "documents/YOUR_USER_ID/Q3 Proposal.pdf"
}'The dashboard's core actions, as endpoints
Documents created through the API appear in your dashboard immediately, and shares from either place feed the same analytics.
List documents
Every document you own, with recipient counts and view stats, newest activity first.
Upload PDFs
A presigned upload sends bytes straight to storage, so decks up to 250 MB are never capped by a request body limit.
Share with recipients
Creates a personal tracking link per recipient and emails it, exactly like sharing from the dashboard.
Read analytics
View counts, session summaries, intent scores, and most-read pages for every recipient.
Easy to get started
No SDK to install — plain JSON over HTTPS that any HTTP client can call. All paths are relative to https://www.replaydocs.com/api/v1. Full schemas, per-language code samples, and a live request client are in the interactive reference.
- GET
/meThe account the token belongs to - GET
/documentsList your documents, optionally paged - POST
/documents/upload-urlStart an upload - POST
/documentsFinish an upload - GET
/documents/{documentId}Engagement analytics - POST
/documents/{documentId}/recipientsShare with a recipient
Predictable failures
Every error returns the same JSON shape with a stable machine-readable code and a message safe to show your users.
Error shape
{
"error": {
"code": "duplicate_recipient",
"message": "This document has already been shared with that email address."
}
}- 400A payload, path, or query parameter failed validation, including an expired pagination cursor.
- 401The access token is missing, expired, or revoked.
- 403The token is missing the "api" scope.
- 402You have hit a document or recipient limit on your plan.
- 404No such document, or it belongs to another account.
- 409A duplicate name or recipient, or an upload that never completed.
- 413The uploaded PDF is larger than 250 MB.
Frequently asked questions
Ready when you are
Stop guessing who read your document.
See real engagement and intent signals from every reader. Get started with Replay Docs today.