# Pinned Events

Pinned Events is a hyperlocal social planning platform where people discover local plans, follow public channels, save events, RSVP, get reminders, and coordinate with friends.

Pinned Events provides a public Developer API that lets organizers, venues, platforms, community channels, and product teams publish events into Pinned Events channels from existing systems such as CMS tools, CRMs, forms, spreadsheets, ticketing systems, internal admin tools, backend jobs, and automation workflows.

## Developer API

The Pinned Events API is a REST API for event publishing and event creation. Public API calls use bearer API keys. API keys are scoped and tied to the key owner. Events are published into channels. The API supports duplicate-safe event creation using the Idempotency-Key header.

Important developer documentation:

- [Developer overview](https://pinned.events/developers): Product overview for the Pinned Events Developer API.
- [Developer docs](https://pinned.events/developers/docs): Documentation hub for the Public API.
- [Getting started](https://pinned.events/developers/docs/getting-started): Create an API key, find a channelId, publish your first event, and retry safely.
- [Authentication](https://pinned.events/developers/docs/authentication): Authenticate Public API requests with bearer API keys from trusted server-side code.
- [API keys and scopes](https://pinned.events/developers/docs/api-keys-and-scopes): Understand API key lifecycle, default quickstart scopes, owner-scoped channel access, and revocation behavior.
- [Channels](https://pinned.events/developers/docs/channels): Every event is published into a channel. Use GET /api/public/v1/channels to find accessible channelId values.
- [Create events](https://pinned.events/developers/docs/create-events): Create draft or published events with required fields first, then add location, media, ticketing, and publishing options.
- [Idempotency](https://pinned.events/developers/docs/idempotency): Use stable Idempotency-Key headers so webhook retries and import jobs do not create duplicate event listings.
- [Errors](https://pinned.events/developers/docs/errors): Understand the error envelope, common status codes, and how to debug failed Public API requests.
- [Rate limits](https://pinned.events/developers/docs/rate-limits): Understand 429 responses, Retry-After handling, and retry strategies for busy integrations.
- [Pagination](https://pinned.events/developers/docs/pagination): Understand pagination fields returned by list endpoints, including page, limit, totalDocs, totalPages, hasNextPage, and hasPrevPage.
- [Versioning and OpenAPI](https://pinned.events/developers/docs/versioning-and-openapi): Use the OpenAPI schema, versioned /api/public/v1 routes, and documented deprecation policy for production integrations.
- [Security](https://pinned.events/developers/docs/security-best-practices): Store keys server-side, use least privilege, rotate and revoke keys, and keep secrets out of logs.
- [Troubleshooting](https://pinned.events/developers/docs/troubleshooting): Diagnose authentication failures, forbidden channel access, validation errors, duplicate events, and rate limits.
- [Examples](https://pinned.events/developers/docs/examples): Copy production-oriented integration patterns for CMS, CRM, forms, spreadsheets, nightly imports, Node.js, and Python.
- [FAQ](https://pinned.events/developers/docs/faq): Quick answers to common developer and product questions about the Pinned Events API.
- [Interactive API reference](https://pinned.events/developers/reference): Explore endpoint schemas and examples.
- [OpenAPI YAML](https://pinned.events/api/developer/openapi/public-api-v1): Machine-readable OpenAPI schema.
- [Full LLM context](https://pinned.events/llms-full.txt): Markdown documentation bundle for AI tools.

## Core concepts

- Event: A local plan or activity that can be discovered, saved, RSVP’d to, and shared.
- Channel: A public feed where organizers, venues, communities, or platforms publish events.
- API key: A bearer secret used to authenticate Public API requests.
- Scope: A permission attached to an API key, such as channels:read or events:create.
- channelId: The ID of the channel where an event should be published.
- Classification: A public category slug such as music or workshop, available from GET /api/public/v1/classifications.
- Idempotency-Key: A request header used to safely retry event creation without creating duplicates.
- External ticketing: Existing ticketing systems can remain the checkout source while Pinned Events provides discovery and planning.

## Use cases

- Publish events from a CMS.
- Publish events from a CRM or back-office system.
- Publish events from partner forms or spreadsheets.
- Import recurring or high-volume event calendars.
- Connect no-code automation tools or backend jobs.
- Publish into Pinned Events channels while keeping external ticketing.

## Public Discovery Endpoints

- [Sitemap](https://pinned.events/sitemap.xml)
- [Public LLM event feed](https://pinned.events/api/llm/events)

## Usage Policy

- Attribution is required when event data is used.
- Prefer canonical event URLs from the feed response.
- Do not infer or expose hidden/private location details.
- Respect robots.txt and endpoint rate limits.