Palmr.

API Endpoints

Palmr. provides a comprehensive, well-documented, and fully typed REST API designed for maximum developer productivity and seamless integration. Whether you're building custom applications, automating workflows, or integrating with third-party services, our API offers the flexibility and reliability you need.

Overview: The API is built with Fastify + Zod + TypeScript, ensuring type safety, schema validation, and excellent performance for all operations.

Prerequisites

Exposing the API port

To access the API endpoints, you need to expose port 3333 in your Docker configuration. This port is where the Palmr. API server runs.

Using Docker Compose:

services:
  palmr:
    image: kyantech/palmr:latest
    ports:
      - "5487:5487" # Web interface
      - "3333:3333" # API port (required for API access)
    # ... other configuration

Using Docker run command:

docker run -d \
  --name palmr \
  -e ENABLE_S3=false \
  -e ENCRYPTION_KEY=change-this-key-in-production-min-32-chars \
  -p 5487:5487 \
  -p 3333:3333 \
  -v palmr_data:/app/server \
  --restart unless-stopped \
  kyantech/palmr:latest

Note: Port 3333 exposure is optional if you only need the web interface. However, it's required for direct API access, custom integrations, and accessing the interactive documentation.

Accessing the API documentation

The API documentation is available through interactive interfaces that allow you to explore, test, and validate all available endpoints directly in your browser.

Documentation endpoints

Local development:

  • Scalar documentation: http://localhost:3333/docs
  • Swagger documentation: http://localhost:3333/swagger

Production environment:

  • Scalar documentation: {your_domain}:3333/docs
  • Swagger documentation: {your_domain}:3333/swagger

Important: We don't provide an online version of the API documentation because endpoints and functionality may vary between different versions of Palmr. Always access the documentation from your specific deployment to ensure accuracy.

Interactive documentation with Scalar

Our primary API documentation is powered by Scalar, a modern documentation platform that provides an exceptional developer experience.

Palmr API Documentation

Why Scalar?

  • Interactive testing - Test endpoints directly in the documentation
  • Real-time validation - Immediate feedback on request/response formats
  • Modern interface - Clean, intuitive design optimized for developer productivity
  • Type-safe integration - Full TypeScript support with automatic type inference
  • Schema visualization - Clear representation of request and response structures

Key features

  • Comprehensive endpoint coverage - All API endpoints documented with examples
  • Authentication testing - Built-in support for JWT token authentication
  • Request builders - Interactive forms for constructing API requests
  • Response visualization - Formatted display of API responses with syntax highlighting
  • Code generation - Generate client code in multiple programming languages

Alternative Swagger documentation

For developers who prefer Swagger or need compatibility with existing tools, we also provide a Swagger-based documentation interface.

Palmr API Documentation

When to use Swagger

  • Legacy tool compatibility - Integration with existing Swagger-based workflows
  • Team preferences - When your team is more familiar with Swagger interface
  • OpenAPI specification - Direct access to OpenAPI spec for code generation
  • Third-party integrations - Tools that specifically require Swagger format

Both documentation formats provide identical endpoint coverage and functionality, ensuring you can choose the interface that best fits your development workflow.

API capabilities

The Palmr. API provides comprehensive access to all platform features:

File operations

  • Upload files - Single and batch file uploads with progress tracking
  • Download files - Secure file retrieval with access control
  • File management - Rename, delete, and organize files
  • Metadata access - Retrieve file information and properties

Share management

  • Create shares - Generate public links for file sharing
  • Configure access - Set passwords, expiration dates, and view limits
  • Track usage - Monitor share views and download statistics
  • Manage recipients - Add and remove share recipients

User operations

  • Authentication - Login, logout, and session management
  • Profile management - Update user information and preferences
  • User administration - Create and manage user accounts (admin only)

System integration

  • Health checks - Monitor system status and availability
  • Configuration - Access and modify system settings
  • Storage operations - Manage filesystem and S3 storage options

Authentication

The API uses HTTP-only cookies for secure authentication. After logging in through the web interface or API, authentication is automatically handled via secure cookies:

# Login to establish authenticated session
POST /auth/login
{
  "email": "user@example.com",
  "password": "your-password"
}
 
# Subsequent requests automatically include authentication cookies
# No Authorization header needed - cookies are sent automatically
GET /api/files

How authentication works

  1. Login - Use the /auth/login endpoint with your credentials
  2. Cookie storage - The server sets HTTP-only cookies containing JWT tokens
  3. Automatic authentication - All subsequent API requests include these cookies automatically
  4. Session management - Cookies handle session persistence and expiration

Security features

  • HTTP-only cookies - Tokens stored securely in HTTP-only cookies, preventing XSS attacks
  • Secure transmission - Cookies marked as secure and same-site for enhanced protection
  • Token expiration - Automatic session timeout for security
  • Role-based access - Different permissions for users and administrators
  • Request validation - All inputs validated using Zod schemas

Getting started with the API

1. Expose the API port

Ensure port 3333 is exposed in your Docker configuration to access the API endpoints.

2. Access the documentation

Visit your Palmr. instance at :3333/docs to explore the interactive API documentation.

3. Authenticate

Use the login endpoint to establish an authenticated session. Authentication cookies will be automatically set and included in subsequent requests.

4. Test endpoints

Use the interactive documentation to test API endpoints and understand request/response formats.

5. Build your integration

Implement your custom application using the API endpoints that match your requirements.

Integration examples

The API enables powerful integrations and automation:

Workflow automation:

  • Automatically upload files from CI/CD pipelines
  • Create shares for build artifacts and reports
  • Integrate with project management tools

Custom applications:

  • Build mobile apps with native file management
  • Create specialized interfaces for specific use cases
  • Develop backup and sync solutions

Business integrations:

  • Connect with existing document management systems
  • Automate file sharing workflows
  • Integrate with CRM and ERP systems

Best practices

Performance optimization

  • Use appropriate HTTP methods - GET for retrieval, POST for creation, etc.
  • Implement pagination - Handle large datasets efficiently
  • Cache responses - Store frequently accessed data locally
  • Batch operations - Group multiple operations when possible

Error handling

  • Check status codes - Handle different HTTP response codes appropriately
  • Parse error messages - Use detailed error information for debugging
  • Implement retries - Handle temporary failures gracefully
  • Log API interactions - Maintain audit trails for troubleshooting

Security considerations

  • Use HTTPS - Always encrypt API communications to protect authentication cookies
  • Secure cookies - Authentication handled automatically via HTTP-only cookies
  • Validate inputs - Sanitize data before sending to API
  • Monitor usage - Track API calls for unusual activity

On this page