Skip to main content

📤 Upload API

The Upload API allows you to handle file uploads within Pika, including user avatars, transaction attachments (receipts, invoices), and other document files. The API supports various file types and provides secure file storage with automatic validation.

📡 Base URL​

All upload endpoints are prefixed with:

/wp-json/pika/v1/upload

🚀 Endpoints​

Upload Avatar​

Upload an avatar image for people, or accounts.

Endpoint: POST /wp-json/pika/v1/upload/avatar

Headers:

  • Cookie: Authentication cookie
  • Content-Type: multipart/form-data

Form Data:

  • entityType (string, required): Type of entity (person, account)
  • file (file, required): Image file to upload

Supported File Types:

  • Images: JPG, JPEG, PNG, GIF, WebP
  • Maximum Size: 5MB
  • Recommended Dimensions: 200x200 to 500x500 pixels

Response:

{
    "id": "15",
    "url": "http:\/\/localhost:8000\/wp-content\/uploads\/pika\/avatars\/person-68b671f88bad1-1756787192.jpg",
    "type": "image",
    "name": "avatar.jpg",
    "size": "9246"
}

Example Request:

curl -X POST http://localhost:8000/wp-json/pika/v1/upload/avatar \
  -H "Cookie: pika_token=token" \
  -F "entityType=person" \
  -F "file=@avatar.jpg"

Upload Transaction Attachment​

Upload files as attachments to transactions (receipts, invoices, documents).

Endpoint: POST /wp-json/pika/v1/upload/attachment

Headers:

  • Cookie: Authentication cookie
  • Content-Type: multipart/form-data

Form Data:

  • entityType (string, required): Type of entity (transaction)
  • attachmentType (string, required): Type of attachment (image, document)
  • file (file, required): File to upload

Supported File Types:

  • Images: JPG, JPEG, PNG, GIF, WebP (max 5MB)
  • Documents: PDF, DOC, DOCX, TXT (max 10MB)

Response:

{
    "id": "16",
    "url": "http:\/\/localhost:8000\/wp-content\/uploads\/pika\/attachments\/transaction-68b6723b80518-1756787259.jpg",
    "type": "image",
    "name": "f6974bbe-7717-4801-b0c7-e6195c2f9835.jpg",
    "size": "1566701"
}

Example Request:

curl -X POST http://localhost:8000/wp-json/pika/v1/upload/attachment \
  -H "Cookie: pika_token=token" \
  -F "entityType=transaction" \
  -F "attachmentType=image" \
  -F "file=@receipt.jpg"

📁 File Types and Limits​

Avatar Uploads​

  • Purpose: Profile pictures for users, people, and accounts
  • Supported Formats: JPG, JPEG, PNG, GIF, WebP
  • Size Limit: 5MB
  • Auto-processing: Automatic thumbnail generation
  • Storage: Organized in /uploads/avatars/ directory

Transaction Attachments​

  • Purpose: Receipts, invoices, and supporting documents
  • Supported Formats:
    • Images: JPG, JPEG, PNG, GIF, WebP (5MB max)
    • Documents: PDF, DOC, DOCX, TXT (10MB max)
  • Auto-processing: Image optimization and thumbnail generation
  • Storage: Organized in /uploads/attachments/ directory

File Validation​

  • Type Checking: MIME type validation
  • Size Validation: File size limits enforced
  • Security Scanning: Malware and virus scanning
  • Format Validation: File format verification

🔒 Security Features​

File Validation​

  • MIME Type Checking: Ensures only allowed file types
  • Size Limits: Prevents oversized file uploads
  • Virus Scanning: Automatic malware detection
  • Content Validation: File content verification

Access Control​

  • Authentication Required: All uploads require valid session
  • Entity Ownership: Users can only upload for their own entities
  • Rate Limiting: Prevents upload abuse
  • File Isolation: Secure file storage and access

Storage Security​

  • Secure Directories: Files stored outside web root
  • Random Naming: Prevents file enumeration attacks
  • Access Logging: Track all file access attempts
  • Backup Protection: Secure backup procedures

🚨 Error Responses​

Upload Failed​

This is a general-purpose error for when a file upload fails for an unspecified reason, such as a network interruption or server-side issue.

{
  "code": "upload_failed",
  "message": "Upload failed.",
  "data": {
    "status": 400
  }
}

Upload Not Found​

This error is returned when an attempt is made to access an uploaded file or its record that does not exist.

{
  "code": "upload_not_found",
  "message": "Upload not found.",
  "data": {
    "status": 404
  }
}

Upload Not Allowed​

This error indicates that the user lacks the necessary permissions to upload a file in the given context. 🚫

{
  "code": "upload_not_allowed",
  "message": "Upload not allowed.",
  "data": {
    "status": 403
  }
}

File Size Exceeded​

This response is used when the uploaded file is larger than the maximum allowed size (e.g., 5MB).

{
  "code": "file_size_exceeded",
  "message": "File size exceeded, max file size is 5MB.",
  "data": {
    "status": 400
  }
}

Invalid Image Type​

This error is triggered when an image is uploaded with a file extension that is not on the approved list.

{
  "code": "invalid_image_type",
  "message": "Image type not allowed. Allowed image types are: jpg, jpeg, png, gif, svg, webp.",
  "data": {
    "status": 400
  }
}

Invalid Document Type​

This error occurs when a document is uploaded with a file extension that is not on the approved list.

{
  "code": "invalid_document_type",
  "message": "Document type not allowed. Allowed document types are: pdf.",
  "data": {
    "status": 400
  }
}

Invalid Image MIME Type​

This error checks the file's actual content type (MIME type) and is returned if it's not an allowed image format, preventing file extension spoofing.

{
  "code": "invalid_image_mime_type",
  "message": "Image mime type not allowed. Allowed image mime types are: image/png, image/jpeg, image/gif, image/svg+xml, image/webp.",
  "data": {
    "status": 400
  }
}

Invalid Document MIME Type​

Similar to the image MIME type check, this error is returned if a document's actual content type is not allowed.

{
  "code": "invalid_document_mime_type",
  "message": "Document mime type not allowed. Allowed document mime types are: application/pdf.",
  "data": {
    "status": 400
  }
}

Invalid Type​

This error relates to the purpose of the upload. It's used if the specified type isn't one of the valid categories like avatar, attachment, etc.

{
  "code": "invalid_type",
  "message": "File type not allowed. Allowed file types are: avatar, attachment, other.",
  "data": {
    "status": 400
  }
}

Invalid Attachment Type​

This error is for when the kind of attachment is invalid. For example, if the system only accepts image or document attachments and something else is provided.

{
  "code": "invalid_attachment_type",
  "message": "Attachment type not allowed. Allowed attachment types are: image, document.",
  "data": {
    "status": 400
  }
}

Invalid Entity Type​

This error specifies that the item the file is being attached to is not a valid type (e.g., person, account, transaction).

{
  "code": "invalid_entity_type",
  "message": "Entity type not allowed. Allowed entity types are: person, account, transaction, other.",
  "data": {
    "status": 400
  }
}

Invalid File​

This error is returned when the request is submitted without the actual file data attached.

{
  "code": "invalid_file",
  "message": "File missing you request.",
  "data": {
    "status": 400
  }
}

📚 Related Documentation​