Palmr/apps/docs/content/docs/3.0-beta/api.mdx

---
title: API Endpoints
icon: Plug
---

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:**

```yaml
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:**

```bash
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](/assets/v2/api-docs/scalar.png)

### 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](/assets/v2/api-docs/swagger.png)

### 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:

```bash
# 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

## Useful links

- [Scalar Official Website](https://scalar.com/) - Learn more about our primary documentation platform
- [Swagger Official Website](https://swagger.io/) - Information about the alternative documentation format
- [JWT.io](https://jwt.io/) - Understanding JSON Web Tokens for authentication