Getting Started

Welcome to the Plinth API. This guide will help you get up and running with API access to your organisation's data.

Authentication

The Plinth API supports two authentication methods:

API Key Authentication (Recommended)

API keys are the simplest way to authenticate with the API. Each key is scoped to a single organisation and provides access to that organisation's data.

How to use:

Pass your API key in the x-api-key header:

curl -X GET "https://app.plinth.org.uk/api/v1/members" \
  -H "x-api-key: sk_your_api_key_here"

Token Authentication

For applications that integrate with Plinth authentication, you can use your authentication token. When using token authentication, you must specify the organisationId as a query parameter.

curl -X GET "https://app.plinth.org.uk/api/v1/members?organisationId=your_org_id" \
  -H "Authorization: Bearer your-auth-token"

Generating an API Key

API keys can be generated and managed by organisation administrators through the Plinth dashboard.

Steps to generate a key:

1. Log in to your Plinth account at app.plinth.org.uk
2. Navigate to Settings > API Keys
3. Click Generate New API Key
4. Enter a descriptive name for your key (e.g., "Marketing Integration", "Data Export Script")
5. Click Generate
6. Important: Copy your API key immediately. For security reasons, the full key is only displayed once and cannot be retrieved later.

API Key Format

API keys begin with the prefix sk_ followed by a random string, for example:

sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4

Managing API Keys

From the API Keys settings page, you can:

• View all API keys for your organisation (only the first 8 characters are shown for security)
• Revoke a key to immediately disable it
• Reactivate a previously revoked key
• Delete a key permanently

Base URL

All API requests should be made to:

https://app.plinth.org.uk/api/v1

Common Response Format

All endpoints return JSON responses with consistent formatting:

Success Responses

List endpoints return paginated results:

{
  "members": [...],
  "offset": 0,
  "limit": 100,
  "total": 250
}

Error Responses

Errors follow a consistent format:

{
  "type": "ERROR_CODE",
  "message": "Human readable error message"
}

Common HTTP Status Codes:

Pagination

Most list endpoints support pagination with these query parameters:

• limit (number, default: 100, max: 250) - Number of results to return
• offset (number, default: 0) - Number of results to skip

Example:

# Get the second page of 50 results
curl "https://app.plinth.org.uk/api/v1/members?limit=50&offset=50" \
  -H "x-api-key: sk_your_api_key"

Filtering

Most list endpoints support filtering via query parameters. Any field in the document can be used as a filter:

# Filter members by email
curl "https://app.plinth.org.uk/api/v1/members?email=john@example.com" \
  -H "x-api-key: sk_your_api_key"

Data Type Parsing:

• Booleans: true or false (case-insensitive)
• Numbers: Automatically parsed
• Strings: Used as-is

Timestamps

All timestamp fields are returned in ISO 8601 format:

2025-01-15T10:30:00.000Z

Rate Limiting

The API may be subject to rate limiting. Check response headers for rate limit information.

Available Endpoints

The API provides access to the following resources:

Next Steps

• Explore the Members API to retrieve and create members
• View Bookings to access event attendance data
• Check out Events to list your organisation's events
• Use the Schemas endpoint to discover available fields

Support

If you encounter any issues or have questions about the API, please contact your system administrator or reach out to the Plinth support team.