files:upsert

Description: Create a file/document or update a single file by ID or import_id.

Files are represented as Document records in the Arkipel system. They can store metadata (title, description) and optionally include an uploaded file attachment.

When no id or import_id is provided, a new document is created with an auto-generated import_id.

Request Schema

{
  "payload": {
    "id": 1,
    "import_id": "DOC-001",
    "type": "files:upsert",
    "title": "Project Proposal",
    "description": "Q2 2026 project proposal document",
    "file_url": "https://example.com/files/proposal.pdf",
    "file_filename": "proposal.pdf",
    "file_content_type": "application/pdf"
  },
  "signature": "payload_ed25519_hex_signature",
  "source_public_key": "your_client_public_key"
}

Or with base64-encoded file content:

{
  "payload": {
    "import_id": "DOC-002",
    "type": "files:upsert",
    "title": "Meeting Minutes",
    "description": "Weekly team meeting minutes",
    "file_content": "JVBERi0xLjQKJcOkw7zDtsO...",
    "file_filename": "minutes.pdf",
    "file_content_type": "application/pdf"
  },
  "signature": "payload_ed25519_hex_signature",
  "source_public_key": "your_client_public_key"
}

Request Attributes

See global request attributes

Field Constraints

Field	Type	Required	Default	Max Length	Constraints
`id`	Integer	No	null	-	Arkipel ID. When set, updates existing record. When omitted, creates new record.
`import_id`	String	No	Auto-generated	255	Your external system ID for this file. Unique per account. Auto-generated if not provided.
`title`	String	Yes	null	255	File title. Required.
`description`	String	No	null	-	File description.
`file_url`	String	No	null	-	URL to download the file from. The receiving system will download and attach the file.
`file_content`	String	No	null	-	Base64-encoded file content. Alternative to `file_url`.
`file_filename`	String	No	null	255	The filename for the uploaded file. Required when providing `file_url` or `file_content`.
`file_content_type`	String	No	null	-	The MIME type of the file (e.g., `application/pdf`, `image/png`).

File Upload Options

You can provide a file attachment in one of two ways:

By URL (file_url) - The receiving Arkipel server will download the file from the provided URL
By Base64 Content (file_content) - The file content is encoded as base64 in the payload

When providing a file, file_filename is required. file_content_type is recommended but will be auto-detected if omitted.

Special Field: import_id

The import_id field is your integration’s identifier for this file. Use it to link Arkipel records with your external system.

Characteristics:

Required but auto-generated if not provided
Must be unique per account
Your external system ID format is recommended (e.g., doc_123, file_456)
Used for idempotent operations and duplicate prevention
Auto-generated format: 6 characters from 234679ACDEFGHJKMNPRTVWXYZ

Real Life Example

Creating a File with URL

{
  "type": "files:upsert",
  "import_id": "DOC-2024-001",
  "title": "Annual Report 2024",
  "description": "Annual financial report for the community",
  "file_url": "https://example.com/reports/annual-2024.pdf",
  "file_filename": "annual-2024.pdf",
  "file_content_type": "application/pdf"
}

Creating a File with Base64 Content

{
  "type": "files:upsert",
  "import_id": "DOC-2024-002",
  "title": "Meeting Agenda",
  "description": "Agenda for the monthly community meeting",
  "file_content": "SGVsbG8gV29ybGQh",
  "file_filename": "agenda.txt",
  "file_content_type": "text/plain"
}

Updating an Existing File by Import ID

{
  "type": "files:upsert",
  "import_id": "DOC-2024-001",
  "title": "Annual Report 2024 (Updated)",
  "description": "Updated annual financial report with corrections"
}

Updating Metadata Without File

{
  "type": "files:upsert",
  "id": 123,
  "title": "Updated Title"
}

Response Schema

{
  "source_public_key": "community_public_key",
  "source_site": {
    "protocol": "http",
    "fqdn": "arkipel.localhost:3000"
  },
  "created_at": "2025-11-13T20:52:49Z",
  "signature": "8b6392d5550605bd6ccddf9c21ebec470de4b44e4b4deb746076e37ab61c5346e07e7c7c7cebb5bbee41cdd92a476bcd3f02373d146ec165b31c31fc31c9ce0d",
  "payload": {
    "message_id": "6916452112f746b2b4cf48c1",
    "type": "files:upsert"
  }
}

Usage Notes

Files are created as Document records in the Arkipel system
The import_id is used for idempotent operations - if a file with the same import_id already exists, it will be updated
When both id and import_id are provided, id takes precedence for lookup
If neither id nor import_id is provided, a new file is created with an auto-generated import_id
File uploads via file_url or file_content are processed asynchronously