Skip to main content

​
Overview

Retrieves the complete metadata and information for a document family using its file system path. Returns the DocumentFamily object without downloading the actual file content.

​
Endpoint

GET /api/stores/{orgSlug}/{slug}/fs/**?meta
GET /api/stores/{orgSlug}/{slug}/{version}/fs/**?meta

​
Path Parameters

ParameterTypeRequiredDescription
orgSlugstringYesOrganization slug
slugstringYesStore slug
versionstringNoStore version (uses current version if not specified)
**stringYesFile path within the store

​
Query Parameters

ParameterTypeRequiredDescription
metabooleanYesMust be present to retrieve metadata instead of content
pathstringNoAlternative way to specify path (overrides URL path)

​
Example Usage

​
Get metadata by URL path

curl -X GET "https://platform.kodexa.com/api/stores/my-org/invoices/fs/2024/january/invoice-001.pdf?meta" \
  -H "x-api-key: your-api-key-here"

​
Get metadata using path parameter

curl -X GET "https://platform.kodexa.com/api/stores/my-org/invoices/fs?meta&path=2024/january/invoice-001.pdf" \
  -H "x-api-key: your-api-key-here"

​
Get metadata from specific version

curl -X GET "https://platform.kodexa.com/api/stores/my-org/invoices/v2.0/fs/contracts/contract-001.pdf?meta" \
  -H "x-api-key: your-api-key-here"

​
Using Python SDK

from kodexa import KodexaPlatform

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

# Get document metadata
family = platform.get_document_metadata(
    org_slug="my-org",
    slug="invoices",
    path="2024/january/invoice-001.pdf"
)

print(f"Document ID: {family.id}")
print(f"Path: {family.path}")
print(f"Locked: {family.locked}")
print(f"Content Type: {family.native_content_object.content_type}")
print(f"Size: {family.native_content_object.size} bytes")

​
Response

Returns a DocumentFamily object: 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "path": "2024/january/invoice-001.pdf",
  "locked": false,
  "nativeContentObject": {
    "id": "660e8400-e29b-41d4-a716-446655440000",
    "contentType": "application/pdf",
    "size": 245678,
    "created": "2024-01-15T10:30:00Z",
    "labels": ["processed", "verified"],
    "documentVersion": "v1"
  },
  "contentObjects": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "contentType": "application/pdf",
      "size": 245678,
      "transitionType": "UPLOAD"
    }
  ],
  "metadata": {
    "department": "accounting",
    "amount": "1500.00",
    "vendor": "ACME Corp"
  },
  "labels": ["invoice", "2024"],
  "documentStatus": {
    "status": "PROCESSED",
    "updatedAt": "2024-01-15T11:00:00Z"
  },
  "activeAssistant": null,
  "assignee": null,
  "created": "2024-01-15T10:30:00Z",
  "updated": "2024-01-15T11:00:00Z"
}

​
Response Fields

FieldTypeDescription
idstringUnique identifier for the document family
pathstringFile system path within the store
lockedbooleanWhether the document is locked for editing
nativeContentObjectobjectThe primary/latest content object
contentObjectsarrayAll content objects (versions) for this document
metadataobjectCustom metadata key-value pairs
labelsarrayClassification labels applied to the document
documentStatusobjectCurrent processing status
activeAssistantobjectAI assistant currently processing this document
assigneeobjectUser assigned to review this document
createdstringISO 8601 timestamp of creation
updatedstringISO 8601 timestamp of last update

​
Use Cases

​
Check if document exists

try:
    family = platform.get_document_metadata(org_slug="my-org", slug="invoices", path="invoice.pdf")
    print(f"Document exists: {family.path}")
except Exception as e:
    print("Document not found")

​
Verify content type before download

family = platform.get_document_metadata(org_slug="my-org", slug="docs", path="report.pdf")

if family.native_content_object.content_type == "application/pdf":
    # Download the PDF
    content = platform.download_document(org_slug="my-org", slug="docs", path="report.pdf")
else:
    print(f"Unexpected type: {family.native_content_object.content_type}")

​
Check document processing status

family = platform.get_document_metadata(org_slug="my-org", slug="invoices", path="invoice.pdf")

if family.document_status.status == "PROCESSED":
    print("Document processing complete")
elif family.document_status.status == "PROCESSING":
    print("Document still being processed")
elif family.document_status.status == "FAILED":
    print("Document processing failed")

​
Error Responses

  • 404 Not Found: Document family does not exist at the specified path
  • 400 Bad Request: Invalid path format or missing meta parameter
  • 403 Forbidden: Insufficient permissions to access the document
⌘I