Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ivory.finance/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

POST /v1/documents/upload ingests a document into your tenant’s isolated OpenSearch index. The pipeline extracts text, splits it into overlapping chunks, embeds each chunk with a 768-dimensional model, and stores the result ready for hybrid search. The index (client-docs-{tenant_id}) is physically separate for every tenant — KNN queries cannot cross tenant boundaries.
The document index must be pre-provisioned for your tenant before the first upload. If not provisioned, the endpoint returns 503. Contact support if you see this error.

​
IAM access control

Every document carries access control metadata written at upload time and enforced as mandatory pre-filters on every search query.
FieldValuesWho can see the document
visibilitytenant_wideAny authenticated user in your tenant
visibilitydeal_privateOnly identity UUIDs in allowed_identity_ids
visibilityteam_onlyOnly users whose role is in allowed_roles
barrier_idUUIDAdditionally requires the caller to have crossed the named information barrier
Set visibility carefully at upload time — it cannot be changed without re-uploading the document. A CIM or NDA should use deal_private, not tenant_wide.

​
Supported file types

FormatExtraction method
PDFpdfplumber — preserves paragraph structure
DOCXpython-docx — paragraphs and table text
PPTXpython-pptx — all text frames across slides
TXT / MD / CSVDirect UTF-8 decode
PNG / JPEGGPT-4o-mini vision — OCR + chart/diagram description
SVG<text> / <tspan> tag extraction; vision fallback if empty
Maximum file size: 50 MB.

​
Request

​
file
file
required
The document to upload. Multipart form upload.
​
tenant_id
string
required
Your tenant UUID. Available from your JWT context or dashboard.
​
identity_id
string
required
The identity UUID of the user performing the upload.
​
entity_id
string
The entity this document relates to — a deal UUID, company entity UUID, or person UUID. Used to scope searches by entity.
​
doc_type
string
default:"other"
Document classification. One of: cim · nda · management_accounts · dd_report · board_pack · research_note · legal_agreement · pitch · other
​
visibility
string
default:"tenant_wide"
Access control level: tenant_wide · deal_private · team_only
​
allowed_identity_ids
string
Comma-separated identity UUIDs that may access this document. Required when visibility=deal_private.
​
allowed_roles
string
Comma-separated role slugs that may access this document. Required when visibility=team_only. Example: compliance_officer,risk_manager
​
barrier_id
string
Information barrier UUID. When set, only users who have crossed this barrier will see the document in search results.

​
Response

​
doc_id
string
UUID of the indexed document. Pass this to /v1/documents/search or the agent.
​
filename
string
Original filename.
​
chunks
integer
Number of text chunks indexed.
​
tenant_id
string
Your tenant UUID.
​
index_name
string
The OpenSearch index the document was stored in (client-docs-{tenant_id}).
​
entity_id
string
Entity association, if provided.
​
doc_type
string
Document classification.
​
visibility
string
The access level set on this document.
​
status
string
indexed — document is immediately searchable.

​
Examples

curl -X POST https://api.ivory.finance/v1/documents/upload \
  -H "X-API-Key: YOUR_KEY" \
  -F "file=@target_cim_v3.pdf" \
  -F "tenant_id=a1b2c3d4-5e6f-7890-abcd-ef1234567890" \
  -F "identity_id=usr_abc123" \
  -F "entity_id=deal_xyz789" \
  -F "doc_type=cim" \
  -F "visibility=deal_private" \
  -F "allowed_identity_ids=usr_abc123,usr_def456,usr_ghi789"
Response: 
{
  "doc_id":     "3f7a2b1c-4e8d-4a9f-b2c1-d3e4f5a6b7c8",
  "filename":   "target_cim_v3.pdf",
  "chunks":     63,
  "tenant_id":  "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
  "index_name": "client-docs-a1b2c3d4-5e6f-7890-abcd-ef1234567890",
  "entity_id":  "deal_xyz789",
  "doc_type":   "cim",
  "visibility": "deal_private",
  "status":     "indexed"
}

​
Error responses

CodeReason
413File exceeds 50 MB limit
422No text could be extracted, or invalid visibility value
503Document index not provisioned for this tenant — contact support