Dociya

Documents

The core resource: every file a household uploads becomes a document with one or more versions. Upload is a two-step handshake — presign, then register — so the file goes straight from the client to storage without transiting the API.

Get a presigned upload URL

POST/documents/presign

Returns a short-lived, direct-to-storage PUT URL and the fileKey you'll reference when registering. 40 requests/minute per household.

Parameters
filenamestringrequired

mimestringrequired

curl https://api.dociya.com/documents/presign \
  -H "Authorization: Bearer $DOCIYA_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "filename": "license.jpg", "mime": "image/jpeg" }'

Register an uploaded file

POST/documents

Creates the document and its first version, then enqueues background ingestion (classification + extraction). Re-registering the same fileHash for a household is a no-op, not a duplicate.

Parameters
fileKeystringrequired

From the presign step.

fileHashstringrequired

SHA-256 of the uploaded bytes — used to dedup re-uploads of the same file.

mimestringrequired

batchIdstringoptional

Client-generated UUID shared across a multi-file upload, for aggregate progress tracking.

curl https://api.dociya.com/documents \
  -H "Authorization: Bearer $DOCIYA_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fileKey": "hh_9a2.../4e1c...jpg",
    "fileHash": "sha256:9f86d0...",
    "mime": "image/jpeg"
  }'

List documents

GET/documents

Every document in the household, each shaped as a wallet card. Unfiltered and unpaginated by design — see pagination.

Parameters
categorystringoptional

Filter by category, e.g. identity, legal, financial.

profileIdstringoptional

Filter to one family member.

conversationIdstringoptional

Filter to one conversation thread.

Response fields
cardWalletCardoptional

The registry-bound wallet presentation — see Wallet cards.

curl "https://api.dociya.com/documents?category=identity" \
  -H "Authorization: Bearer $DOCIYA_ACCESS_TOKEN"

Retrieve a document

GET/documents/:id

Full detail: extracted fields (masked per the masking rule), every version, and the card shape. 404 if the document doesn't exist or belongs to another household.

curl https://api.dociya.com/documents/5b1e2b7a-... \
  -H "Authorization: Bearer $DOCIYA_ACCESS_TOKEN"

Delete a document

DELETE/documents/:id

Soft-delete — bytes are recoverable for a grace window, not purged immediately.

curl -X DELETE https://api.dociya.com/documents/5b1e2b7a-... \
  -H "Authorization: Bearer $DOCIYA_ACCESS_TOKEN"

Ask a question about a document

POST/documents/:id/ask

Answers strictly from this document where possible — never a guess. 40 requests/minute per household.

Parameters
questionstringrequired

Response fields
answerstringoptional

sourcedbooleanoptional

false when the answer goes beyond this document's contents (advisory, clearly labeled).

curl https://api.dociya.com/documents/5b1e2b7a-.../ask \
  -H "Authorization: Bearer $DOCIYA_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "question": "When does this expire?" }'

Reveal a masked field

POST/documents/:id/fields/:key/reveal

Requires both a bearer token and a fresh X-Step-Up-Token — see step-up authentication. Every reveal is audit-logged. A multi-card document has a card-scoped variant at /documents/:id/cards/:cardKey/fields/:key/reveal.

curl -X POST https://api.dociya.com/documents/5b1e2b7a-.../fields/license_number/reveal \
  -H "Authorization: Bearer $DOCIYA_ACCESS_TOKEN" \
  -H "X-Step-Up-Token: $STEP_UP_TOKEN"

Also on this resource

POST /documents/:id/supersedeAttach a new version — the renewal path.
POST /documents/:id/walletAdd or remove the card from the wallet (never deletes the document).
POST /documents/:id/starPin/unpin for Discover quick access.
POST /documents/:id/tags · /notesSet normalized tags or a free-text annotation.
POST /documents/:id/reprocess · /extract-moreRe-run extraction from the stored original.
GET /documents/:id/raw-files/:rawId/viewShort-lived signed URL to view a stored original (audited).
GET /documents/:id/renewal-packetAssembled required-docs for a renewal — found vs. still missing.
POST /documents/:id/conversationMove or merge a document into another conversation.
POST /documents/:id/splitSplit a merged multi-file document back into separate documents.
GET /documents/filesThe Library ‘Files’ view — stored originals, metadata only.
GET /documents/batches/:batchIdAggregate progress for a multi-file upload, keyed by the batchId passed to register.
Note
Want the shape of the card object itself — templates, fact ladders, masking rules? See Wallet cards.