Authentication

The public API is read-only. Some discovery endpoints can be used anonymously, while data endpoints require either a logged-in browser session or a Plushcap API key.

Sending Your API Key

Send the key in the X-API-Key HTTP header:

X-API-Key: your-api-key-here

MCP clients can also use the API key as a bearer token when connecting to the Plushcap MCP server.

Read-Only Access

All public API endpoints allow only safe HTTP methods:

Write methods such as POST, PUT, PATCH, and DELETE are not supported by the public API.

Public Discovery Endpoints

These endpoints do not require an API key:

API Key Endpoints

All other public API endpoints require an API key or an authenticated browser session. Free accounts have a small per-endpoint hourly allowance. Paid plans have higher access according to account tier.

When a free-plan endpoint limit is reached, Plushcap returns 429 Too Many Requests with limit metadata:

{
  "detail": "Free plan limit reached for this endpoint. Upgrade to Accelerate for unlimited API and MCP access.",
  "code": "free_plan_endpoint_limit_reached",
  "limit": 2,
  "window": "hour",
  "endpoint": "blog-posts",
  "upgrade_url": "https://www.plushcap.com/manage"
}

Successful limited responses include:

X-RateLimit-Limit: 2
X-RateLimit-Remaining: 1
X-RateLimit-Reset: 1767229200

Authentication Context

GET /api/v1/auth/context/

Returns the current authenticated account context, including subscription tier and whether the request is using internal MCP access.

{
  "authenticated": true,
  "subscription": "accelerate",
  "subscription_status": "active",
  "tier": "accelerate",
  "tier_level": 2,
  "is_staff_access": false,
  "is_internal_access": false
}

Error Responses

Missing or invalid API key:

{"detail": "Authentication credentials were not provided."}

Status: 403 Forbidden

Unsupported write method:

{"detail": "Method 'POST' not allowed. This endpoint only supports read operations."}

Status: 403 Forbidden or 405 Method Not Allowed, depending on the endpoint.