API Overview and Integration Guidelines

Introduction

The Publica.la REST API provides comprehensive integration capabilities for your digital publishing platform. Our API is designed specifically for server-to-server communication and backend integrations, offering robust tools to manage content, users, orders, plans, reading permissions, and authentication sessions.

This documentation covers everything you need to integrate securely and efficiently with our platform, including authentication requirements, rate limiting, CORS policies, and security best practices.

API Resources Overview

Our API provides access to these core resources:

• Content: Manage publications, issues, and digital content
• Orders: Content access and transactions data
• Plans: Manage subscription plans and pricing
• Users: Handle user accounts and profiles
• Reading Permissions: Control access to content
• Auth Sessions: Monitor and manage user sessions

Getting Started

1. Generate your API token from Dashboard > Settings > Integrations
2. Choose your integration approach
3. Set up authentication with the X-User-Token header
4. Test basic functionality with a simple GET request
5. Implement error handling for production usage
6. Monitor rate limits and optimize request patterns

For specific endpoint documentation, select the resource you need from the navigation menu.

API Architecture and Design Principles

Backend-Only Integration

Our REST API is designed exclusively for backend integrations. This architectural decision ensures:

• Enhanced Security: API tokens never leave your secure server environment
• Reliable Performance: No client-side limitations or browser restrictions
• Scalable Operations: Optimized for high-volume automated processes

Never Expose API Tokens on Client Side

NEVER include API tokens in frontend code, mobile applications, or any client-accessible environment. Tokens must remain secure on your backend servers only.

If you suspect your API token has been compromised, you can immediately delete or regenerate it by going to Dashboard > Settings > Integrations in your store.

Base URL Structure

All API endpoints operate based on your store's domain:

https://{store_final_domain}/integration-api/v1/

Example: If your store domain is example.publica.la, your API base URL is:

https://{store_final_domain}/integration-api/v1/

Authentication

Generating API Tokens

Before using the API, you must generate an authentication token:

1. Access your store dashboard: Go to Dashboard > Settings > Integrations
2. Generate API key: In the API Integration Key section, click Generate new key
3. Secure your token: Copy and store the token securely in your backend environment

Administrative Access

API keys can be generated by admin users only. Each admin can generate their own unique token.

Making Authenticated Requests

Include your API token in every request using the X-User-Token header:

GET /integration-api/v1/users
Content-Type: application/json
Accept: application/json
X-User-Token: your_api_token_here

Required Headers:

{
  "Content-Type": "application/json",
  "Accept": "application/json",
  "X-User-Token": "your_api_token_here"
}

Rate Limiting and Flood Protection

Our API applies two layers of rate limiting to keep the platform stable and to share resources fairly across integrations. Both layers apply to integration-api/v1 and api/v3.

Per-Minute Burst Limit

Every endpoint requires authentication and is limited to 60 requests per minute per API token (bulk endpoints have a separate, lower limit).

Rate Limiting Headers

Monitor your usage through these response headers:

Header	Description	Example
X-RateLimit-Limit	Total allowed requests per minute	60
X-RateLimit-Remaining	Requests left in current window	45
X-RateLimit-Reset	When limits reset (UNIX timestamp)	1666897200

Rate Limit Reset

X-RateLimit-Reset header appears only when limits are exhausted, showing when the window will reset.

Rate Limit Response Example

HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1666897200

# When limit exceeded:
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1666897320

Daily Read Quota

Read requests (GET and HEAD) are subject to an additional daily quota. It exists to discourage read loops that repeatedly fetch the same content and crowd out other integrations.

Scope	Limit	Counts
Per API token	2,000 reads per day	A single token's GET and HEAD requests
Per store	5,000 reads per day	The GET and HEAD requests of all tokens

• Reads only. Writes (POST, PUT, DELETE), such as catalog ingestion or order creation, are not counted against this quota and rely on the per-minute limit alone.
• Counted per API. integration-api/v1 and api/v3 keep independent daily counters, so traffic on one does not consume the other's quota.
• Rolling 24-hour window. The counter starts on your first read and resets 24 hours later, not at midnight.
• Exceeding either the per-token or the per-store quota returns 429 Too Many Requests with a Retry-After header.

Need a higher allocation?

These defaults fit most integrations. If your use case legitimately needs more (for example, syncing a large catalog), contact support to arrange a higher limit for your store. The practices below keep you within budget in the meantime.

Staying Within the Limits

1. Cache responses on your side and avoid re-fetching the same item by ID or ISBN on every cycle.
2. Prefer list endpoints with pagination over looping individual GET /{id} requests.
3. Sync incrementally using updated_at filters to fetch only what changed.

Security Features

Security Headers

All API responses include security headers:

Strict-Transport-Security: max-age=31536000; includeSubdomains
X-Content-Type-Options: nosniff
X-XSS-Protection: 1

Request Logging and Monitoring

• Comprehensive logging: All API requests are logged for security and debugging
• IP tracking: Request origins are monitored for abuse detection
• Audit trails: Complete audit logs for compliance and troubleshooting

Data Validation and Error Handling

Input Validation

All API endpoints implement strict validation:

• Type checking: Parameters must match expected data types
• Range validation: Numeric values must fall within acceptable ranges
• Format validation: Strings must match required patterns (emails, URLs, etc.)
• Required fields: Missing required parameters return clear error messages

Error Response Format

Errors follow a consistent format:

{
  "CODE": "error",
  "message": "Detailed error description",
  "errors": {
    "field_name": ["Specific validation error"]
  }
}

HTTP Status Codes

Code	Meaning	Usage
200	Success	Request completed successfully
400	Bad Request	Invalid request format or parameters
401	Unauthorized	Invalid or missing API token
404	Not Found	Resource doesn't exist
422	Validation Error	Request validation failed
429	Too Many Requests	Rate limit exceeded
500	Server Error	Internal server error

Integration Best Practices

Performance Optimization

1. Implement caching: Cache responses appropriately on your end to reduce API calls
2. Monitor rate limits: Always check rate limiting headers in responses
3. Implement backoff: Use exponential backoff when approaching limits
4. Distribute requests: Spread API calls over time rather than bursts

Security Best Practices

1. Secure token storage: Store API tokens in secure environment variables
2. HTTPS only: Always use HTTPS for API requests
3. Validate responses: Always validate API response data