API reference

The API is an HTTP API that returns JSON. Dates use the ISO 8601 format, in UTC. All paths below are relative to the base URL:

https://docs.traductionexpert.com/api/v1

Every request must carry the Authorization: Bearer sd_live_… header (see Authentication). A request without a valid key gets 401, whatever the endpoint. Errors always take the form { "error": "message" } (see Errors and limits).

File IDs are UUIDs. View tokens are 43-character base64url strings. An ID or token that belongs to another account behaves exactly like a nonexistent one: 404.

Contents

• Account: GET /account
• Files: POST /files, GET /files, GET /files/:id, GET /files/:id/download, DELETE /files/:id
• Access log: GET /files/:id/access-log
• View links: POST /views, GET /views/:token, GET /views/:token/pages/:n, DELETE /views/:token, POST /files/:id/revoke-views

Account

Get the account and its usage

GET/account

Returns the account tied to the key, its plan with its limits, and current usage. Handy for checking a key when your application starts or for displaying a quota.

{
  "id": "0c7e5a1d-3b52-4c2e-8f61-7a9d4e2b1c30",
  "name": "Traduction Expert",
  "plan": {
    "id": "pro",
    "name": "Pro",
    "priceCents": 1900,
    "maxDocuments": 5000,
    "maxStorageBytes": 26843545600,
    "maxViewSeconds": 2592000,
    "customWatermark": true,
    "accessLogExport": false,
    "maxApiKeys": 10,
    "support": "Email, within 48 hours"
  },
  "usage": {
    "documents": 312,
    "storageBytes": 418230112,
    "activeLinks": 14,
    "apiKeys": 2
  }
}

plan.maxDocuments is null when the number of documents is unlimited (Business plan).

Files

Upload a file

POST/files

The request body is the raw file (not multipart/form-data). Metadata goes in the headers. The actual type is detected from the file's first bytes: the Content-Type header only serves to get the body accepted, and the response's contentType field reflects what was detected. The file is encrypted before it is written.

curl -X POST https://docs.traductionexpert.com/api/v1/files \
  -H "Authorization: Bearer $SECURE_DOCS_API_KEY" \
  -H "Content-Type: application/pdf" \
  -H "x-file-name: passport.pdf" \
  -H "x-file-kind: source" \
  --data-binary @passport.pdf

{
  "id": "9dab9089-bbc5-4853-a179-03e76523c5da",
  "name": "passport.pdf",
  "kind": "source",
  "contentType": "application/pdf",
  "size": 482113,
  "pageCount": 2,
  "createdAt": "2026-10-14T09:12:03.000Z"
}

List files

GET/files?page=1&perPage=25

Returns the account's files, newest first, with the number of active links for each.

{
  "files": [
    {
      "id": "9dab9089-bbc5-4853-a179-03e76523c5da",
      "name": "passport.pdf",
      "kind": "source",
      "contentType": "application/pdf",
      "size": 482113,
      "pageCount": 2,
      "createdAt": "2026-10-14T09:12:03.000Z",
      "activeLinks": 1
    }
  ],
  "total": 312
}

Get a file's metadata

GET/files/:id

Returns a file's metadata. Never its content.

{
  "id": "9dab9089-bbc5-4853-a179-03e76523c5da",
  "name": "passport.pdf",
  "kind": "source",
  "contentType": "application/pdf",
  "size": 482113,
  "pageCount": 2,
  "createdAt": "2026-10-14T09:12:03.000Z"
}

Download a delivered document

GET/files/:id/download

Returns the bytes of the decrypted file. Only for kind: "delivery" files: a source document never leaves the vault. Every download is recorded in the access log.

Response headers:

Delete a file

DELETE/files/:id

Permanently deletes the encrypted file and all its view links, which stop working immediately. A delete entry is added to the account's log, visible in the dashboard; GET /files/:id/access-log then returns 404. Response: 204 with no body.

Access log

Get a file's access log

GET/files/:id/access-log

Returns the file's latest 200 entries, newest first.

[
  { "at": "2026-10-14T09:20:41.512Z", "fileId": "9dab9089-bbc5-4853-a179-03e76523c5da", "action": "page", "viewerEmail": "[email protected]", "ip": "203.0.113.24", "page": 2 },
  { "at": "2026-10-14T09:20:39.087Z", "fileId": "9dab9089-bbc5-4853-a179-03e76523c5da", "action": "page", "viewerEmail": "[email protected]", "ip": "203.0.113.24", "page": 1 },
  { "at": "2026-10-14T09:20:38.940Z", "fileId": "9dab9089-bbc5-4853-a179-03e76523c5da", "action": "view", "viewerEmail": "[email protected]", "ip": "203.0.113.24" },
  { "at": "2026-10-14T09:12:03.000Z", "fileId": "9dab9089-bbc5-4853-a179-03e76523c5da", "action": "upload" }
]

View links

Create a link

POST/views

Creates a read-only view link for a named person. The name and email are burned into the watermark of every page. JSON body, with Content-Type: application/json.

curl -X POST https://docs.traductionexpert.com/api/v1/views \
  -H "Authorization: Bearer $SECURE_DOCS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileId": "9dab9089-bbc5-4853-a179-03e76523c5da",
    "viewerName": "Claire Martin",
    "viewerEmail": "[email protected]",
    "ttlSeconds": 86400
  }'

{
  "token": "TsTzcrhEaO2ge3ejImbqgKC33uCaRoQi0CzugwxFKcM",
  "url": "https://docs.traductionexpert.com/v/TsTzcrhEaO2ge3ejImbqgKC33uCaRoQi0CzugwxFKcM",
  "expiresAt": "2026-10-15T09:20:00.000Z"
}

url is the hosted viewer link, ready to send to the viewer. Use token if you display the pages in your own application.

Get a link

GET/views/:token

Returns what you need to display the document: name, page count, viewer, expiration and account branding. Each call records a view entry in the log. Call it from your server when the viewer opens the document.

{
  "fileName": "passport.pdf",
  "pageCount": 2,
  "viewerName": "Claire Martin",
  "viewerEmail": "[email protected]",
  "expiresAt": "2026-10-15T09:20:00.000Z",
  "brand": "Traduction Expert"
}

Get a page

GET/views/:token/pages/:n

Returns page n (starting at 1) as image/jpeg, rendered on demand and watermarked for the link's viewer. The response carries Cache-Control: private, no-store. Each call records a page entry in the log. Rendering takes about one second per page.

Revoke a link

DELETE/views/:token

Disables the link immediately. Response: 204 with no body.

Revoke all links for a file

POST/files/:id/revoke-views

Disables all of the file's active links, for example at the end of an assignment or if a link has leaked. The file itself is kept. A revoke entry is recorded in the log if at least one link was disabled. An unknown ID returns { "revoked": 0 }.

{ "revoked": 3 }