Public Stats API

Api docs / public-api

Public Stats API

Use this API to read workspace analytics and media usage from external systems.

Api public-api.md

Base URL

/api/v1

Authentication

Every request requires a workspace API key.

  • Header: X-FolioSpace-API-Key: fsp_...
  • Or header: Authorization: Bearer fsp_...
  • Or query param: ?api_key=fsp_...

API key format:

  • fsp_ + 48 alphanumeric characters
  • Regex: ^fsp_[A-Za-z0-9]{48}$

Get/regenerate keys in Dashboard:

  1. Open Workspace
  2. Open the split menu on Download ZIP
  3. Click API Keys

Endpoint: Visits Stats

  • Method: GET
  • Path: /stats/visits
  • Query params:
  • from (optional, YYYY-MM-DD)
  • to (optional, YYYY-MM-DD)
  • Defaults:
  • from: 30 days ago (UTC)
  • to: today (UTC)

Example:

curl -H "X-FolioSpace-API-Key: fsp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://example.com/api/v1/stats/visits?from=2026-05-01&to=2026-05-25"

Response fields:

  • workspace_owner_id
  • from
  • to
  • timezone (UTC)
  • total_visits
  • average_per_day
  • series (array of { date, visits })

Endpoint: Media Usage Stats

  • Method: GET
  • Path: /stats/media-usage

Example:

curl -H "Authorization: Bearer fsp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://example.com/api/v1/stats/media-usage"

Response fields:

  • workspace_owner_id
  • plan
  • images
  • used
  • limit
  • ratio (x/x)
  • percent
  • videos
  • used
  • limit
  • ratio (x/x)
  • percent
  • media_total
  • used
  • limit
  • ratio (x/x)
  • percent
  • storage
  • used_bytes
  • limit_bytes
  • ratio (x/x)
  • percent

Errors

  • 401 Unauthorized for missing/invalid API key
  • 400 for invalid request inputs
  • Standard WordPress REST error format:
  • code
  • message
  • data.status