Skip to main content

​
Overview

Uploads a new document to the store at a specified path, creating a new document family or adding content to an existing one. This endpoint supports multipart file uploads with metadata.

​
Endpoint

POST /api/stores/{orgSlug}/{slug}/fs/**
POST /api/stores/{orgSlug}/{slug}/{version}/fs/**

​
Path Parameters

ParameterTypeRequiredDescription
orgSlugstringYesOrganization slug
slugstringYesStore slug
versionstringNoStore version (optional, uses current version if not specified)
**stringYesFile path within the store (part of URL path)

​
Form Data Parameters

ParameterTypeRequiredDescription
filefileYes*The file to upload
documentfileNoAlternative document file parameter
pathstringNoOverride path from URL
documentVersionstringNoVersion identifier for this document
metadataobjectNoAdditional metadata key-value pairs
*Either file or document parameter must be provided

​
Special Import Mode

If the path ends with .dfm, the endpoint will import a Kodexa Document Family format file instead of creating a new document.

​
Example Usage

​
Upload a PDF invoice

curl -X POST "https://platform.kodexa.com/api/stores/my-org/invoices/fs/2024/january/invoice-001.pdf" \
  -H "x-api-key: your-api-key-here" \
  -F "file=@invoice-001.pdf" \
  -F "documentVersion=v1" \
  -F "metadata[department]=accounting" \
  -F "metadata[amount]=1500.00"

​
Upload with path parameter

curl -X POST "https://platform.kodexa.com/api/stores/my-org/invoices/fs" \
  -H "x-api-key: your-api-key-here" \
  -F "file=@invoice-001.pdf" \
  -F "path=2024/january/invoice-001.pdf" \
  -F "documentVersion=v1"

​
Upload to specific version

curl -X POST "https://platform.kodexa.com/api/stores/my-org/invoices/v2.0/fs/contracts/contract-001.pdf" \
  -H "x-api-key: your-api-key-here" \
  -F "file=@contract-001.pdf"

​
Using Python SDK

from kodexa import KodexaPlatform

platform = KodexaPlatform(url="https://platform.kodexa.com", api_key="your-api-key")

# Upload a document
with open("invoice-001.pdf", "rb") as f:
    document_family = platform.upload_to_store(
        org_slug="my-org",
        slug="invoices",
        path="2024/january/invoice-001.pdf",
        file=f,
        metadata={
            "department": "accounting",
            "amount": "1500.00"
        },
        document_version="v1"
    )

print(f"Uploaded: {document_family.path}")
print(f"Family ID: {document_family.id}")

​
Import a .dfm file

curl -X POST "https://platform.kodexa.com/api/stores/my-org/invoices/fs/import-data.dfm" \
  -H "x-api-key: your-api-key-here" \
  -F "file=@export.dfm"

​
Response

Returns a DocumentFamily object containing: 
{
  "id": "family-uuid",
  "path": "2024/january/invoice-001.pdf",
  "locked": false,
  "nativeContentObject": {
    "id": "content-uuid",
    "contentType": "application/pdf",
    "size": 245678,
    "labels": []
  },
  "metadata": {
    "department": "accounting",
    "amount": "1500.00"
  }
}

​
Path Handling

The file path can be specified in two ways:
  1. URL Path: Include the path directly in the URL after /fs/
    • Example: /api/stores/my-org/invoices/fs/2024/invoice.pdf
  2. Query Parameter: Use the path parameter
    • Example: /api/stores/my-org/invoices/fs?path=2024/invoice.pdf
If both are provided, the path parameter takes precedence.

​
Document Versioning

  • Each upload creates a new ContentObject within the DocumentFamily
  • Use documentVersion to label different versions
  • The latest content object becomes the active version
  • Previous versions are preserved for audit history

​
Metadata

Custom metadata can be attached during upload:
  • Passed as form data with metadata[key]=value format
  • Stored with the document family
  • Searchable and retrievable with the document
  • Useful for categorization, classification, and filtering

​
Content Type Detection

The content type is automatically detected from:
  1. File extension
  2. File content analysis (if extension is missing)
  3. Falls back to application/octet-stream

​
Error Responses

  • 400 Bad Request: Missing required file parameter
  • 404 Not Found: Store or version not found
  • 413 Payload Too Large: File exceeds size limits
  • 415 Unsupported Media Type: Invalid file type for store configuration