Files API

Upload and manage files.

Files are now Nodes

Files in the Paradigm SDK are stored and managed as nodes. File-specific permissions (file_permissions) have been removed. Access to file data is controlled through tag permissions and schema permissions on the user's exposure profile, just like any other node.

Endpoints

POST /raw-files

POST Upload a file.

curl -X POST "https://api.ofself.ai/api/v1/raw-files" \
  -H "X-API-Key: your-key" \
  -H "X-User-ID: user-123" \
  -F "file=@document.pdf" \
  -F "tag_ids=tag_documents,tag_work" \
  -F 'metadata={"category":"reports"}'

Form Fields:

Field	Type	Required	Description
file	file	Yes	File to upload
tag_ids	string	No	Comma-separated tag IDs
metadata	string	No	JSON string of metadata
data_type	string	No	Optional; inferred if omitted (document/image/audio/video/text)
format	string	No	Optional; inferred from filename/MIME type if omitted (pdf, jpg, ...)
structure_type	string	No	Optional; defaults to unstructured

Response: 201 Created

{
  "id": "file_a1b2c3d4",
  "filename": "document.pdf",
  "content_type": "application/pdf",
  "size": 102400,
  "owner_id": "user-123",
  "tag_ids": ["tag_documents", "tag_work"],
  "created_at": "2024-01-15T10:30:00Z"
}

---

GET /raw-files

GET List files.

curl -X GET "https://api.ofself.ai/api/v1/raw-files?content_type=application/pdf" \
  -H "X-API-Key: your-key" \
  -H "X-User-ID: user-123"

Query Parameters:

Parameter	Type	Description
data_type	string	Filter by data type (document, image, audio, video, text)
content_type	string	Filter by MIME type
tag_id	string	Filter by single tag ID
tag_ids	string	Comma-separated tag IDs (match ANY)
page	integer	Page number (optional)
per_page	integer	Items per page (optional)
limit	integer	Limit (optional, alternative pagination)
offset	integer	Offset (optional, alternative pagination)

---

GET /raw-files/:file_id

GET Get file metadata.

curl -X GET "https://api.ofself.ai/api/v1/raw-files/file_abc" \
  -H "X-API-Key: your-key" \
  -H "X-User-ID: user-123"

---

GET /raw-files/:file_id/download

GET Download file content.

curl -X GET "https://api.ofself.ai/api/v1/raw-files/file_abc/download" \
  -H "X-API-Key: your-key" \
  -H "X-User-ID: user-123" \
  -o downloaded_file.pdf

Response: File binary content with appropriate Content-Type header.

---

PUT /raw-files/:file_id

PUT Update file metadata.

curl -X PUT "https://api.ofself.ai/api/v1/raw-files/file_abc" \
  -H "X-API-Key: your-key" \
  -H "X-User-ID: user-123" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "renamed_document.pdf",
    "metadata": {"category": "reports"}
  }'

---

DELETE /raw-files/:file_id

DELETE Delete a file.

curl -X DELETE "https://api.ofself.ai/api/v1/raw-files/file_abc" \
  -H "X-API-Key: your-key" \
  -H "X-User-ID: user-123"

---

POST /raw-files/:file_id/tags

POST Add a tag to a file.

curl -X POST "https://api.ofself.ai/api/v1/raw-files/file_abc/tags" \
  -H "X-API-Key: your-key" \
  -H "X-User-ID: user-123" \
  -H "Content-Type: application/json" \
  -d '{"tag_id": "tag_work"}'

---

DELETE /raw-files/:file_id/tags/:tag_id

DELETE Remove a tag from a file.

curl -X DELETE "https://api.ofself.ai/api/v1/raw-files/file_abc/tags/tag_work" \
  -H "X-API-Key: your-key" \
  -H "X-User-ID: user-123"

File Size Limits

Plan	Max File Size
Free	10 MB
Pro	100 MB
Enterprise	1 GB