# Add to OpenClaw
Source: https://docs.evento.so/ai/add-to-openclaw

Use the Evento SKILL.md with OpenClaw personal AI agents

## Overview

If you are leaning into the recent wave of personal AI agents, OpenClaw is one of the simplest ways to run one locally and keep control of your own environment.

The Evento MCP skill can be reused directly in OpenClaw by placing the same `SKILL.md` file into OpenClaw's skills workspace.

Canonical skill source:

* `https://github.com/andreneves/evento-public-mcp/blob/main/SKILL.md`

## Why OpenClaw for this

Based on OpenClaw's public docs and README, it is:

* Open source and self-hosted
* Designed for personal AI assistant workflows
* Set up with an onboarding flow (`openclaw onboard --install-daemon`)
* Compatible with filesystem-based skills (`~/.openclaw/workspace/skills/<skill>/SKILL.md`)

References:

* `https://github.com/openclaw/openclaw`
* `https://docs.openclaw.ai/start/getting-started`

## Add Evento skill to OpenClaw

Create a skill folder in your OpenClaw workspace and copy the Evento skill file:

```bash theme={null}
mkdir -p ~/.openclaw/workspace/skills/evento-public-mcp
cp /absolute/path/to/evento-public-mcp/SKILL.md ~/.openclaw/workspace/skills/evento-public-mcp/SKILL.md
```

If OpenClaw is already running, restart your session/gateway so the new skill is picked up.


# Architecture
Source: https://docs.evento.so/ai/architecture

Runtime architecture and execution flow for the Evento public MCP server

## What this server is

* MCP transport adapter over stdio
* Tool-to-route mapping layer for public Evento APIs
* Central auth/header injection using your API key
* No direct database access and no persistence in the MCP layer

## Key files

* `src/index.ts` - process entrypoint
* `src/mcp-server.ts` - MCP protocol handling (`tools/list`, `tools/call`)
* `src/public-tools.ts` - tool registry, executor, auth injection, timeout/retry, normalized responses
* `PUBLIC_MCP.tools.json` - manifest mirror of runtime tools

## Execution flow

1. MCP client calls `tools/list`
2. Server returns `PUBLIC_TOOLS`
3. MCP client calls `tools/call`
4. Server delegates to `executePublicTool(name, args)`
5. Executor validates args and resolves path placeholders
6. Executor sends authenticated API call with timeout/retry policy
7. Executor normalizes success or error payload back to MCP response

## Error and retry behavior

* Retries retryable statuses: `408`, `429`, `5xx`
* Retries retryable network failures (timeout, DNS, connection reset classes)
* Returns MCP `isError: true` for failed tool calls with structured payloads

## Next steps

<CardGroup>
  <Card title="Available tools" icon="list-check" href="/mcp-server/tools">
    Review each tool input schema and route mapping.
  </Card>

  <Card title="Testing and troubleshooting" icon="stethoscope" href="/mcp-server/testing-and-troubleshooting">
    Run verification commands and fix common issues.
  </Card>
</CardGroup>


# Client configuration
Source: https://docs.evento.so/ai/client-configuration

Configure the Evento public MCP server in MCP-compatible AI clients

## Configuration shape

Use the same server block pattern across MCP clients:

```json theme={null}
{
  "mcpServers": {
    "evento-public": {
      "command": "node",
      "args": ["/absolute/path/to/evento-public-mcp/dist/index.js"],
      "env": {
        "PUBLIC_API_KEY": "your-evento-api-key",
        "EVENTO_API_BASE_URL": "https://evento.so"
      }
    }
  }
}
```

## Client notes

<AccordionGroup>
  <Accordion title="Claude Desktop">
    Add the server block to `claude_desktop_config.json`, save, and restart Claude Desktop.
  </Accordion>

  <Accordion title="Cursor">
    Add the same block in Cursor MCP settings and restart Cursor.
  </Accordion>

  <Accordion title="Other MCP clients">
    Use the same `command`, `args`, and `env` fields where stdio MCP servers are configured.
  </Accordion>
</AccordionGroup>

## Best practices

* Use an absolute path in `args`
* Keep `PUBLIC_API_KEY` in client-local env config
* Restart the client after config changes

## Next steps

<CardGroup>
  <Card title="Available tools" icon="list-check" href="/mcp-server/tools">
    Test the configured client with `list-events` and `get-event`.
  </Card>

  <Card title="Testing and troubleshooting" icon="stethoscope" href="/mcp-server/testing-and-troubleshooting">
    Verify connectivity and auth quickly.
  </Card>
</CardGroup>


# Quickstart
Source: https://docs.evento.so/ai/setup

Set up the Evento public MCP server for any MCP-compatible AI client

## Overview

The Evento public MCP server runs locally over stdio and maps tool calls to authenticated public Evento API routes.

<CardGroup>
  <Card title="Local stdio transport" icon="terminal">
    Runs on your machine with no hosted MCP layer.
  </Card>

  <Card title="Public API tools" icon="wrench">
    Includes `list-events` and `get-event`.
  </Card>

  <Card title="Central auth injection" icon="key">
    Injects your API key for every outbound request.
  </Card>

  <Card title="Client-agnostic" icon="sparkles">
    Works with Claude Desktop, Cursor, ChatGPT-compatible MCP clients, and others.
  </Card>
</CardGroup>

## Requirements

* Node.js 18+
* npm
* Evento developer API key
* Any MCP client that supports stdio

## Install and run

```bash theme={null}
git clone https://github.com/andreneves/evento-public-mcp.git
cd evento-public-mcp
npm install
npm run build
cp .env.example .env
```

Set `PUBLIC_API_KEY` in `.env`, then run:

```bash theme={null}
npm start
```

## Minimal environment variables

Required:

* `PUBLIC_API_KEY`

Optional:

* `EVENTO_API_BASE_URL`
* `EVENTO_API_TIMEOUT_MS`
* `EVENTO_API_RETRY_ATTEMPTS`
* `EVENTO_API_RETRY_DELAY_MS`
* `EVENTO_PUBLIC_API_KEY` (legacy fallback)
* `EVENTO_SMOKE_USERNAME`

## Next steps

<CardGroup>
  <Card title="Client configuration" icon="sliders" href="/mcp-server/client-configuration">
    Configure Claude Desktop, Cursor, and other MCP clients.
  </Card>

  <Card title="Available tools" icon="list-check" href="/mcp-server/tools">
    See tool inputs and API route mappings.
  </Card>

  <Card title="Architecture" icon="diagram-project" href="/mcp-server/architecture">
    Review runtime flow and file responsibilities.
  </Card>

  <Card title="Testing and troubleshooting" icon="stethoscope" href="/mcp-server/testing-and-troubleshooting">
    Verify setup and debug common failures.
  </Card>
</CardGroup>


# Agent skill (SKILL.md)
Source: https://docs.evento.so/ai/skill

Installable SKILL.md for Evento Public MCP with full content and installation steps

## Overview

The Evento Public MCP skill is published as a canonical `SKILL.md` in the MCP repository:

* `https://github.com/andreneves/evento-public-mcp/blob/main/SKILL.md`

Use this page to copy/install it quickly and keep your local Claude skill aligned with the maintained source.

## Install locally

Copy the skill into your Claude skills directory:

```bash theme={null}
mkdir -p ~/.claude/skills/evento-public-mcp
cp /absolute/path/to/evento-public-mcp/SKILL.md ~/.claude/skills/evento-public-mcp/SKILL.md
```

If you use project-local skills instead, copy to:

```bash theme={null}
.claude/skills/evento-public-mcp/SKILL.md
```

## Full skill file

````md theme={null}
---
name: evento-public-mcp
description: Use Evento Public MCP to fetch Evento event data from AI clients via authenticated tools. Trigger this when users ask to list events by username, fetch event details by event ID, troubleshoot MCP setup, or configure Claude Desktop/Cursor with Evento public API access.
license: MIT
metadata:
  author: evento
  version: "1.0.0"
  docs: "https://docs.evento.so"
---

# Evento Public MCP

## Overview

This skill helps agents use the Evento public MCP server correctly and safely.

It maps MCP tools to authenticated Evento public API routes and is intended for local stdio MCP clients (Claude Desktop, Cursor, and compatible clients).

## When to use

Use this skill when the user wants to:

- List events for a username
- Get event details from an `evt_*` ID
- Configure MCP client settings for Evento
- Troubleshoot missing tools or auth failures
- Understand MCP architecture and tool routing

Do not use this skill when:

- The user needs admin-only API routes
- The user asks for direct database/Supabase access
- The user wants to bypass API key authentication

## Prerequisites

- Node.js 18+
- npm
- Evento developer API key
- Local MCP-compatible client

## MCP setup workflow

1. Clone and build:

   ```bash
   git clone https://github.com/andreneves/evento-public-mcp.git
   cd evento-public-mcp
   npm install
   npm run build
   cp .env.example .env
````

2. Set `PUBLIC_API_KEY` in `.env`.

3. Configure client with absolute path to `dist/index.js`:

   ```json theme={null}
   {
     "mcpServers": {
       "evento-public": {
         "command": "node",
         "args": ["/absolute/path/to/evento-public-mcp/dist/index.js"],
         "env": {
           "PUBLIC_API_KEY": "your-evento-api-key",
           "EVENTO_API_BASE_URL": "https://evento.so/api"
         }
       }
     }
   }
   ```

4. Restart the MCP client.

## Available tools

### `list-events`

* Purpose: list events for a user
* Input:
  * `username` (required, string)
  * `type` (optional: `upcoming | past | profile`)
  * `limit` (optional, number)
* Route:
  * `GET /public/v1/users/{username}/events`

### `get-event`

* Purpose: fetch event details
* Input:
  * `eventId` (required, string)
* Route:
  * `GET /public/v1/events/{eventId}`

## Prompt patterns

* "List upcoming events for username `satoshi`."
* "Get event details for `evt_abc123`."
* "Help me configure Evento MCP in Claude Desktop."

## Troubleshooting checklist

If tools are not visible:

1. Run `npm run build`
2. Confirm `dist/index.js` exists
3. Confirm config uses absolute path
4. Restart client app

If auth fails:

1. Verify `PUBLIC_API_KEY` is set
2. Verify key is valid in Evento developer settings
3. Verify base URL (`EVENTO_API_BASE_URL`) is correct

If API calls fail intermittently:

1. Check timeout/retry env values
2. Re-run smoke test:
   ```bash theme={null}
   EVENTO_SMOKE_USERNAME=your-username npm run smoke
   ```

## Implementation constraints

* MCP layer is a thin API adapter only
* No DB/Supabase access in MCP server
* Keep tool schema mirrored with `PUBLIC_MCP.tools.json`
* Preserve normalized success/error responses

```

## Related docs

- `/mcp-server/quickstart`
- `/mcp-server/setup`
- `/mcp-server/client-configuration`
- `/mcp-server/tools`
- `/mcp-server/testing-and-troubleshooting`
```


# Testing and troubleshooting
Source: https://docs.evento.so/ai/testing-and-troubleshooting

Verification commands, test layers, and common fixes for the Evento public MCP server

## Test commands

```bash theme={null}
npm test
npm run verify
EVENTO_SMOKE_USERNAME=your-username npm run smoke
```

## Test layers

* Unit: `tests/public-tools.unit.test.ts`
* Manifest parity: `tests/manifest-parity.test.ts`
* MCP stdio e2e: `tests/mcp.e2e.test.ts`

## Troubleshooting

<AccordionGroup>
  <Accordion title="Missing API key">
    Set `PUBLIC_API_KEY` in the MCP client `env` block.
  </Accordion>

  <Accordion title="Tools not visible in client">
    Build first (`npm run build`), confirm `dist/index.js` exists, use absolute path in `args`, then restart client.
  </Accordion>

  <Accordion title="API errors">
    Verify key scope, base URL (`EVENTO_API_BASE_URL`), and test with a known username via smoke check.
  </Accordion>
</AccordionGroup>

## Security reminders

* Keep API keys in local env config, never source control
* Rotate keys periodically
* Monitor usage against rate limits

## Next steps

<CardGroup>
  <Card title="Client configuration" icon="sliders" href="/mcp-server/client-configuration">
    Recheck client wiring and env setup.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/mcp-server/setup">
    Restart setup from install through first call.
  </Card>
</CardGroup>


# Available tools
Source: https://docs.evento.so/ai/tools

Tool inputs and API route mappings for the Evento public MCP server

## Tool inventory

<CardGroup>
  <Card title="list-events" icon="list">
    Lists events for a user.
  </Card>

  <Card title="get-event" icon="calendar">
    Fetches event details by ID.
  </Card>
</CardGroup>

## list-events

List events for a user.

Input:

* `username` (required, string)
* `type` (optional, `upcoming | past | profile`)
* `limit` (optional, number)

Route mapping:

* `GET /public/v1/users/{username}/events`

## get-event

Get event details by ID.

Input:

* `eventId` (required, string)

Route mapping:

* `GET /public/v1/events/{eventId}`

## Prompt examples

* "List my upcoming events"
* "Show events for satoshi"
* "Get event evt\_abc123"

## Next steps

<CardGroup>
  <Card title="Architecture" icon="diagram-project" href="/mcp-server/architecture">
    See how MCP calls are normalized and executed.
  </Card>

  <Card title="Testing and troubleshooting" icon="stethoscope" href="/mcp-server/testing-and-troubleshooting">
    Validate tools and debug failures.
  </Card>
</CardGroup>


# Quickstart
Source: https://docs.evento.so/api/api-keys

Create an API key and make your first public API request

## Overview

Use this quickstart to create a key and make your first request in minutes.

<Card title="Rate limits" icon="gauge">
  All API keys are limited to **1,000 requests per day**. Contact us if you need higher limits.
</Card>

## 1) Create an API key

<Steps>
  <Step title="Enable developer mode">
    Navigate to your [Evento settings](https://evento.so/settings) and enable **Developer Mode** in your profile settings.
  </Step>

  <Step title="Access API keys section">
    Once Developer Mode is enabled, go to [Settings → Developer → API Keys](https://evento.so/settings/developer).
  </Step>

  <Step title="Create new API key">
    Click **"Create API Key"** and provide a descriptive name for your key (e.g., "Production App", "Development", "MCP Server").
  </Step>

  <Step title="Copy your key">
    Your API key will be displayed **only once**. Copy it immediately and store it securely.

    <Warning>
      You cannot retrieve the key again after closing the dialog. If you lose it, you'll need to create a new one.
    </Warning>
  </Step>
</Steps>

## 2) Make your first request

```bash theme={null}
curl https://evento.so/api/public/v1/events/evt_abc123 \
  -H "x-evento-api-key: YOUR_API_KEY"
```

If the event exists and is public, the response includes `success: true` and an event object in `data`.

## 3) Key management

### Key limits

* Maximum of **10 active API keys** per user
* Each key can be named for easy identification
* Keys can be revoked at any time

### Revoking keys

If a key is compromised or no longer needed:

<Steps>
  <Step title="Navigate to API keys">
    Go to [Settings → Developer → API Keys](https://evento.so/settings/developer)
  </Step>

  <Step title="Find the key">
    Locate the key you want to revoke in the list
  </Step>

  <Step title="Revoke">
    Click the **"Revoke"** button next to the key. This action is immediate and irreversible.
  </Step>
</Steps>

<Info>
  Revoking a key will immediately invalidate all requests using that key. Make sure to update your applications before revoking keys in production.
</Info>

## 4) Security best practices

<CardGroup>
  <Card title="Never commit keys" icon="code">
    Don't commit API keys to version control. Use environment variables instead.
  </Card>

  <Card title="Rotate regularly" icon="rotate">
    Create new keys and revoke old ones periodically to maintain security.
  </Card>

  <Card title="Use separate keys" icon="layer-group">
    Use different keys for development, staging, and production environments.
  </Card>

  <Card title="Monitor usage" icon="chart-line">
    Check your API key usage regularly in the developer dashboard.
  </Card>
</CardGroup>

## Next steps

<CardGroup>
  <Card title="Authentication" icon="lock" href="/api/authentication">
    Learn how to use your API key in requests
  </Card>

  <Card title="API overview" icon="book" href="/api/overview">
    Explore available API endpoints
  </Card>

  <Card title="Get /events/{eventId}" icon="calendar" href="/api/events">
    Start with the core event details endpoint.
  </Card>
</CardGroup>


# Authentication
Source: https://docs.evento.so/api/authentication

Authentication behavior across public and embed APIs

## Overview

Authentication depends on the API surface:

<CardGroup>
  <Card title="Public API" icon="key">
    Requires API key.

    Preferred header: `x-evento-api-key`
  </Card>

  <Card title="Embed API" icon="globe">
    No authentication required.

    CORS-enabled for browser access.
  </Card>
</CardGroup>

<Warning>
  Never ship your Public API key in client-side JavaScript. Keep keyed requests server-side.
</Warning>

## Public API headers

Primary option:

```
x-evento-api-key: YOUR_API_KEY
```

Alternative option:

```
Authorization: Bearer YOUR_API_KEY
```

## Examples

<CodeGroup>
  ```bash Public API (x-evento-api-key) theme={null}
  curl https://evento.so/api/public/v1/events/evt_abc123 \
    -H "x-evento-api-key: YOUR_API_KEY"
  ```

  ```bash Public API (Bearer) theme={null}
  curl https://evento.so/api/public/v1/events/evt_abc123 \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash Embed API theme={null}
  curl https://evento.so/api/embed/v1/events/evt_abc123
  ```

  ```javascript JavaScript (Public) theme={null}
  const response = await fetch('https://evento.so/api/public/v1/events/evt_abc123', {
    headers: {
      'x-evento-api-key': process.env.EVENTO_API_KEY
    }
  });

  const data = await response.json();
  ```

  ```python Python (Public) theme={null}
  import os
  import requests

  headers = {
      'x-evento-api-key': os.environ['EVENTO_API_KEY']
  }

  response = requests.get(
      'https://evento.so/api/public/v1/events/evt_abc123',
      headers=headers
  )

  data = response.json()
  ```
</CodeGroup>

## Error responses

### 401 unauthorized

Returned when the API key is missing, invalid, or revoked:

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "Not authenticated."
  }
  ```
</ResponseExample>

**Common causes:**

* Missing `x-evento-api-key` header
* Invalid API key format
* Revoked or expired API key

### 403 forbidden

Returned when the key is valid but missing required permissions:

```json theme={null}
{
  "success": false,
  "message": "Insufficient API key scope."
}
```

### 429 too many requests

Returned when you exceed the rate limit (1,000 requests/day):

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "Too many requests. Please try again later."
  }
  ```
</ResponseExample>

**Response headers include:**

```
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640995200
```

## Best practices

<CardGroup>
  <Card title="Use environment variables" icon="shield">
    Store API keys in environment variables, never hardcode them

    ```bash theme={null}
    EVENTO_API_KEY=evento_xxx
    ```
  </Card>
</CardGroup>

<CardGroup>
  <Card title="Server-side only" icon="server">
    Use keyed requests from trusted backend environments only.
  </Card>

  <Card title="Implement retry logic" icon="rotate">
    Use exponential backoff when retrying failed requests
  </Card>
</CardGroup>

<CardGroup>
  <Card title="Handle errors gracefully" icon="triangle-exclamation">
    Always check for 401 and 429 responses and handle them appropriately
  </Card>
</CardGroup>

## CORS notes (Embed API)

Embed API includes permissive CORS headers:

```http theme={null}
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, OPTIONS
Access-Control-Allow-Headers: Content-Type
```

## Testing authentication

Use this simple request to verify your API key is working:

<RequestExample>
  ```bash cURL theme={null}
  curl https://evento.so/api/public/v1/events/evt_test \
    -H "x-evento-api-key: YOUR_API_KEY" \
    -v
  ```
</RequestExample>

<Tip>
  If the key is valid but the event does not exist, you will receive `404` instead of `401`.
</Tip>

## Next steps

<CardGroup>
  <Card title="Get /events/{eventId}" icon="calendar" href="/api/events">
    Public event details and guest-list endpoints.
  </Card>

  <Card title="Embed API" icon="window-maximize" href="/api/embed-api">
    No-auth endpoints for browser embeds.
  </Card>
</CardGroup>


# Data models
Source: https://docs.evento.so/api/data-models

Canonical object schemas for Public and Embed API responses

## Event object (Public API)

```typescript theme={null}
{
  id: string;
  title: string;
  description: string;
  cover: string;
  location: string;
  start_date: string;
  end_date: string | null;
  timezone: string;
  status: 'published';
  visibility: 'public';
  cost: number | null;
  created_at: string;
  creator: {
    id: string;
    username: string;
    image: string;
    verification_status: string | null;
  };
  links: {
    spotify_url: string | null;
    wavlake_url: string | null;
  };
  contributions: {
    cashapp: string | null;
    venmo: string | null;
    paypal: string | null;
    btc_lightning: string | null;
  };
}
```

## Event object (Embed API)

```typescript theme={null}
{
  id: string;
  title: string;
  description: string | null;
  cover: string | null;
  start_date: string;
  end_date: string | null;
  timezone: string;
  location: {
    name: string;
    city: string | null;
    country: string | null;
  } | null;
  url: string;
  creator: {
    username: string;
    image: string | null;
    verified: boolean;
  };
  status: 'upcoming' | 'ongoing' | 'past';
}
```

## Guest object

```typescript theme={null}
{
  id: string;
  username: string;
  name: string | null;
  image: string | null;
  verification_status: string | null;
  rsvp_status: 'yes' | 'maybe' | 'no';
  rsvp_date: string;
}
```

## Pagination object

```typescript theme={null}
{
  limit: number;
  offset: number;
  total: number;
}
```

## Model notes

<CardGroup>
  <Card title="Timestamps" icon="clock">
    All datetime fields are ISO 8601 strings in UTC (`Z`) format.
  </Card>

  <Card title="Nullable fields" icon="circle-minus">
    Optional metadata is represented as `null`, not omitted.
  </Card>

  <Card title="Visibility constraints" icon="eye">
    Public and Embed APIs only return public, published event content.
  </Card>

  <Card title="Verification states" icon="badge-check">
    Verification fields may be `null`, `verified`, or `id_verified`.
  </Card>
</CardGroup>

## Next steps

<CardGroup>
  <Card title="Public events" icon="calendar" href="/api/events">
    See event and guest models in real endpoint responses.
  </Card>

  <Card title="Embed API" icon="window-maximize" href="/api/embed-api">
    See compact embed model payloads.
  </Card>
</CardGroup>


# Embed API overview
Source: https://docs.evento.so/api/embed-api

No-auth, CORS-enabled endpoints for widgets and public embeds

## Overview

Embed API is optimized for browser-first integrations.

<CardGroup>
  <Card title="No authentication" icon="unlock">
    Safe for client-side rendering. No API key required.
  </Card>

  <Card title="CORS Enabled" icon="globe">
    Cross-origin access supports `GET` and `OPTIONS`.
  </Card>

  <Card title="Compact payloads" icon="feather-pointed">
    Response objects are tuned for embeds and widgets.
  </Card>

  <Card title="Computed status" icon="clock">
    Status is returned as `upcoming`, `ongoing`, or `past`.
  </Card>
</CardGroup>

## Base URL

```
https://evento.so/api/embed/v1
```

## CORS headers

```http theme={null}
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, OPTIONS
Access-Control-Allow-Headers: Content-Type
```

## Endpoints

<CardGroup>
  <Card title="Get /events/{eventId}" icon="calendar" href="/api/embed-event">
    Fetch a compact event object for rendering event cards and detail embeds.
  </Card>

  <Card title="Get /users/{username}/events" icon="user" href="/api/embed-user-events">
    Fetch a creator event feed with optional date filters.
  </Card>
</CardGroup>

## Next steps

<CardGroup>
  <Card title="React components" icon="react" href="/embeds/react-components">
    Use prebuilt UI components on top of Embed API responses.
  </Card>

  <Card title="Public API" icon="book" href="/api/events">
    Use keyed endpoints for richer metadata and guest lists.
  </Card>
</CardGroup>


# Fetch embed event
Source: https://docs.evento.so/api/embed-event

GET https://evento.so/api/embed/v1/events/{eventId}
Retrieve embed-optimized event payload by event ID

## Endpoint

```http theme={null}
GET /api/embed/v1/events/{eventId}
```

## Path parameters

<ParamField type="string">
  Unique event identifier.
</ParamField>

## Request example

<RequestExample>
  ```bash cURL theme={null}
  curl https://evento.so/api/embed/v1/events/evt_abc123
  ```

  ```javascript Browser Fetch theme={null}
  const response = await fetch('https://evento.so/api/embed/v1/events/evt_abc123');
  const payload = await response.json();
  ```
</RequestExample>

## Response

```json theme={null}
{
  "success": true,
  "message": "Event fetched successfully",
  "data": {
    "id": "evt_abc123",
    "title": "Tech Meetup 2026",
    "description": "Join us for an evening of tech talks",
    "cover": "https://cdn.evento.so/covers/abc123.jpg",
    "start_date": "2026-12-15T18:00:00Z",
    "end_date": "2026-12-15T21:00:00Z",
    "timezone": "America/Los_Angeles",
    "location": {
      "name": "Tech Hub SF",
      "city": "San Francisco",
      "country": "United States"
    },
    "url": "https://evento.so/e/evt_abc123",
    "creator": {
      "username": "techorg",
      "image": "https://cdn.evento.so/avatars/techorg.jpg",
      "verified": true
    },
    "status": "upcoming"
  }
}
```

## Error codes

| Status | Description                   |
| ------ | ----------------------------- |
| `400`  | Event ID is missing           |
| `404`  | Event not found or not public |
| `500`  | Internal server error         |

## Next steps

<CardGroup>
  <Card title="Get /users/{username}/events" icon="user" href="/api/embed-user-events">
    Fetch user feeds for calendar and list embeds.
  </Card>

  <Card title="Embed API overview" icon="window-maximize" href="/api/embed-api">
    Review CORS behavior and integration differences.
  </Card>
</CardGroup>


# Fetch embed user events
Source: https://docs.evento.so/api/embed-user-events

GET https://evento.so/api/embed/v1/users/{username}/events
Retrieve embed-optimized event feeds by username

## Endpoint

```http theme={null}
GET /api/embed/v1/users/{username}/events
```

## Path parameters

<ParamField type="string">
  Username (case-insensitive).
</ParamField>

## Query parameters

<ParamField type="string">
  Inclusive start datetime (ISO 8601).
</ParamField>

<ParamField type="string">
  Inclusive end datetime (ISO 8601).
</ParamField>

<ParamField type="integer">
  Number of events to return (max 100).
</ParamField>

## Request example

```bash theme={null}
curl "https://evento.so/api/embed/v1/users/johndoe/events?from=2026-01-01T00:00:00Z&limit=10"
```

## Response

```json theme={null}
{
  "success": true,
  "message": "Events fetched successfully",
  "data": [
    {
      "id": "evt_123",
      "title": "Monthly Tech Talks",
      "description": "Lightning talks and networking",
      "cover": "https://cdn.evento.so/covers/123.jpg",
      "start_date": "2026-06-15T18:00:00Z",
      "end_date": "2026-06-15T21:00:00Z",
      "timezone": "America/Los_Angeles",
      "location": {
        "name": "Tech Hub",
        "city": "San Francisco",
        "country": "United States"
      },
      "url": "https://evento.so/e/evt_123",
      "creator": {
        "username": "johndoe",
        "image": "https://cdn.evento.so/avatars/johndoe.jpg",
        "verified": true
      },
      "status": "upcoming"
    }
  ]
}
```

## Filter notes

<AccordionGroup>
  <Accordion title="Date filtering">
    Filters are applied against `computed_start_date` with inclusive bounds.
  </Accordion>

  <Accordion title="Status behavior">
    `status` is computed per event based on start and end timestamps.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="Get /events/{eventId}" icon="calendar" href="/api/embed-event">
    Fetch an embed event object by ID.
  </Card>

  <Card title="React components" icon="react" href="/embeds/react-components">
    Render feeds with prebuilt components.
  </Card>
</CardGroup>


# Error handling
Source: https://docs.evento.so/api/error-handling

HTTP status behavior, common failure messages, and recovery strategies

## Status code matrix

| Status Code | Description           | Typical Cause                                              |
| ----------- | --------------------- | ---------------------------------------------------------- |
| `200`       | OK                    | Request succeeded                                          |
| `400`       | Bad Request           | Invalid params, missing fields, malformed input            |
| `401`       | Unauthorized          | Missing or invalid API key                                 |
| `403`       | Forbidden             | Key lacks required permission                              |
| `404`       | Not Found             | Resource does not exist or is not public                   |
| `409`       | Conflict              | Duplicate resource                                         |
| `422`       | Unprocessable Entity  | Missing required properties or semantic validation failure |
| `429`       | Too Many Requests     | Rate limit exceeded                                        |
| `500`       | Internal Server Error | Unexpected server-side failure                             |

## Common error messages

| Scenario           | Message                                      |
| ------------------ | -------------------------------------------- |
| Missing API Key    | `Not authenticated.`                         |
| Invalid API Key    | `Not authenticated.`                         |
| Insufficient Scope | `Insufficient API key scope.`                |
| Rate Limited       | `Too many requests. Please try again later.` |
| Resource Not Found | `Resource not found.`                        |
| Event Not Public   | `Resource not found.`                        |

## Recovery playbooks

<AccordionGroup>
  <Accordion title="401 unauthorized">
    Verify header format, key environment, and key lifecycle status. For Public API, prefer `x-evento-api-key`.
  </Accordion>

  <Accordion title="403 forbidden">
    Ensure key has required permission(s), such as `events:read` for Public API.
  </Accordion>

  <Accordion title="429 too many requests">
    Implement exponential backoff and queue requests when approaching daily quota.
  </Accordion>

  <Accordion title="404 not found">
    Confirm IDs, usernames, and visibility constraints. Public endpoints only return published public resources.
  </Accordion>
</AccordionGroup>

## Backoff example

<CodeGroup>
  ```javascript JavaScript theme={null}
  async function fetchWithBackoff(url, options, maxRetries = 4) {
    for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
      const response = await fetch(url, options);

      if (response.status !== 429) return response;
      if (attempt === maxRetries) return response;

      const delayMs = 500 * Math.pow(2, attempt);
      await new Promise((resolve) => setTimeout(resolve, delayMs));
    }
  }
  ```

  ```python Python theme={null}
  import time
  import requests


  def get_with_backoff(url, headers, max_retries=4):
      for attempt in range(max_retries + 1):
          response = requests.get(url, headers=headers)

          if response.status_code != 429:
              return response

          if attempt == max_retries:
              return response

          time.sleep(0.5 * (2 ** attempt))
  ```
</CodeGroup>

## Error payload example

```json theme={null}
{
  "success": false,
  "message": "Validation failed",
  "code": "validation_error"
}
```

## Next steps

<CardGroup>
  <Card title="Authentication" icon="lock" href="/api/authentication">
    Header requirements and auth behavior by surface.
  </Card>

  <Card title="Response format" icon="code" href="/api/response-format">
    Shared envelope and payload contracts.
  </Card>
</CardGroup>


# Fetch event guests
Source: https://docs.evento.so/api/event-guests

GET https://evento.so/api/public/v1/events/{eventId}/guests
Retrieve RSVP guests for a published public event

## Endpoint

```http theme={null}
GET /api/public/v1/events/{eventId}/guests
```

## Authentication

<Warning>
  This endpoint requires a public API key.
</Warning>

```http theme={null}
x-evento-api-key: YOUR_API_KEY
```

## Path parameters

<ParamField type="string">
  Unique event identifier.
</ParamField>

## Query parameters

<ParamField type="integer">
  Results per page (1-100).
</ParamField>

<ParamField type="integer">
  Pagination offset.
</ParamField>

<ParamField type="string">
  RSVP filter: `yes`, `maybe`, `no`, or `all`.
</ParamField>

## Request example

```bash theme={null}
curl "https://evento.so/api/public/v1/events/evt_abc123/guests?limit=20&status=yes" \
  -H "x-evento-api-key: YOUR_API_KEY"
```

## Response

```json theme={null}
{
  "success": true,
  "message": "Guest list fetched successfully for event evt_abc123",
  "data": [
    {
      "id": "usr_123",
      "username": "johndoe",
      "name": "John Doe",
      "image": "https://cdn.evento.so/avatars/123.jpg",
      "verification_status": "verified",
      "rsvp_status": "yes",
      "rsvp_date": "2026-06-01T10:30:00Z"
    }
  ]
}
```

## Privacy rules

<AccordionGroup>
  <Accordion title="Only public events are eligible">
    Guest lists are returned only for events with `visibility: public` and `status: published`.
  </Accordion>

  <Accordion title="Sensitive fields are stripped">
    Emails, phone numbers, and private contact details are never returned.
  </Accordion>

  <Accordion title="Anonymous guests are filtered">
    Only guests linked to user profiles are included.
  </Accordion>
</AccordionGroup>

## Error codes

| Status | Description                   |
| ------ | ----------------------------- |
| `400`  | Invalid query parameters      |
| `401`  | API key missing or invalid    |
| `404`  | Event not found or not public |

## Next steps

<CardGroup>
  <Card title="Get /events/{eventId}" icon="calendar" href="/api/events">
    Fetch the parent event object and metadata.
  </Card>

  <Card title="Get /users/{username}/events" icon="user" href="/api/users">
    Use organizer-level event listings with pagination.
  </Card>
</CardGroup>


# Fetch event
Source: https://docs.evento.so/api/events

GET https://evento.so/api/public/v1/events/{eventId}
Retrieve detailed information for a published public event

## Endpoint

```http theme={null}
GET /api/public/v1/events/{eventId}
```

## Authentication

<Warning>
  This endpoint requires a public API key.
</Warning>

```http theme={null}
x-evento-api-key: YOUR_API_KEY
```

## Path parameters

<ParamField type="string">
  Unique event identifier.
</ParamField>

## Request example

<RequestExample>
  ```bash cURL theme={null}
  curl https://evento.so/api/public/v1/events/evt_abc123 \
    -H "x-evento-api-key: YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://evento.so/api/public/v1/events/evt_abc123',
    {
      headers: {
        'x-evento-api-key': process.env.EVENTO_API_KEY
      }
    }
  );

  const payload = await response.json();
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.get(
      'https://evento.so/api/public/v1/events/evt_abc123',
      headers={'x-evento-api-key': os.environ['EVENTO_API_KEY']}
  )

  payload = response.json()
  ```
</RequestExample>

## Response

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "success": true,
    "message": "Event details fetched successfully",
    "data": {
      "id": "evt_abc123",
      "title": "Tech Meetup 2026",
      "description": "Join us for an evening of talks and demos",
      "cover": "https://cdn.evento.so/covers/abc123.jpg",
      "location": "San Francisco, CA",
      "start_date": "2026-06-15T18:00:00Z",
      "end_date": "2026-06-15T21:00:00Z",
      "timezone": "America/Los_Angeles",
      "status": "published",
      "visibility": "public",
      "cost": 25.0,
      "created_at": "2026-05-20T10:00:00Z",
      "creator": {
        "id": "usr_xyz789",
        "username": "techorg",
        "image": "https://cdn.evento.so/avatars/xyz789.jpg",
        "verification_status": "verified"
      },
      "links": {
        "spotify_url": "https://open.spotify.com/playlist/example",
        "wavlake_url": null
      },
      "contributions": {
        "cashapp": "$techorg",
        "venmo": "@techorg",
        "paypal": "donate@techorg.com",
        "btc_lightning": null
      }
    }
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "success": false,
    "message": "Resource not found."
  }
  ```
</ResponseExample>

## Error codes

| Status | Description                    |
| ------ | ------------------------------ |
| `400`  | Event ID is missing or invalid |
| `401`  | API key missing or invalid     |
| `404`  | Event not found or not public  |

## Use cases

<CardGroup>
  <Card title="Event detail pages" icon="browser">
    Render public event pages with creator, links, and contribution metadata.
  </Card>

  <Card title="Calendar ingestion" icon="calendar-days">
    Import event metadata into scheduling products.
  </Card>

  <Card title="Discovery features" icon="compass">
    Build ranked discovery around public event objects.
  </Card>

  <Card title="Content sync" icon="arrows-rotate">
    Refresh local caches for event data consumers.
  </Card>
</CardGroup>

## Next steps

<CardGroup>
  <Card title="Get /events/{eventId}/guests" icon="users" href="/api/event-guests">
    Retrieve RSVP guests for a public event.
  </Card>

  <Card title="Get /users/{username}/events" icon="user" href="/api/users">
    List public events for an organizer profile.
  </Card>
</CardGroup>


# API overview
Source: https://docs.evento.so/api/overview

Complete reference for the Evento APIs

## Evento API reference

Evento exposes two public-facing API surfaces built for different integration models.

<CardGroup>
  <Card title="Public API" icon="globe">
    Read-only event and user data for third-party server integrations.

    `https://evento.so/api/public/v1`
  </Card>
</CardGroup>

<CardGroup>
  <Card title="Embed API" icon="window-maximize">
    No-auth, CORS-friendly responses for widgets and client-side embeds.

    `https://evento.so/api/embed/v1`
  </Card>
</CardGroup>

## API surfaces

<CardGroup>
  <Card title="Public API" icon="key" href="/api/public-api-overview">
    Authenticated with Unkey API keys.

    Includes event details, user event lists, and guest lists.
  </Card>

  <Card title="Embed API" icon="code" href="/api/embed-api">
    No authentication required.

    Built for browser use with full CORS support.
  </Card>
</CardGroup>

<CardGroup>
  <Card title="Shared contracts" icon="brackets-curly" href="/api/response-format">
    Consistent success and error formats.

    Shared status-code and model conventions across surfaces.
  </Card>
</CardGroup>

## Rate limiting

<Info>
  Public API keys are limited to **1000 requests per day** per key (`evento-public-api` namespace).
</Info>

### Rate limit headers

```
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1640995200
```

When rate limits are exceeded:

```json theme={null}
{
  "success": false,
  "message": "Too many requests. Please try again later."
}
```

## Next steps

<CardGroup>
  <Card title="Authentication" icon="lock" href="/api/authentication">
    Header formats, auth flows by surface, and security practices.
  </Card>

  <Card title="Response format" icon="code" href="/api/response-format">
    Shared success/error payload contracts and pagination schema.
  </Card>

  <Card title="Data models" icon="table" href="/api/data-models">
    Event, guest, and pagination object definitions.
  </Card>

  <Card title="Integration guides" icon="map" href="/guides/use-cases">
    Use cases, implementation examples, and source-code patterns.
  </Card>
</CardGroup>


# Public API overview
Source: https://docs.evento.so/api/public-api-overview

Authentication, base URL, and endpoint map for authenticated public Evento APIs

## Base URL

```http theme={null}
https://evento.so/api/public/v1
```

## Authentication

All public endpoints require an API key.

Preferred header:

```http theme={null}
x-evento-api-key: YOUR_API_KEY
```

Alternative header:

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Available endpoints

<CardGroup>
  <Card title="Fetch event" icon="calendar" href="/api/events">
    `GET /events/{eventId}`
  </Card>

  <Card title="Fetch event guests" icon="users" href="/api/event-guests">
    `GET /events/{eventId}/guests`
  </Card>

  <Card title="Fetch user events" icon="user" href="/api/users">
    `GET /users/{username}/events`
  </Card>
</CardGroup>

## Rate limits

Public API keys are limited to `1000` requests per day, per key.

## Next steps

<CardGroup>
  <Card title="Authentication" icon="lock" href="/api/authentication">
    Header behavior, auth errors, and key handling best practices.
  </Card>

  <Card title="Response format" icon="code" href="/api/response-format">
    Shared success and error envelope definitions.
  </Card>
</CardGroup>


# Response format
Source: https://docs.evento.so/api/response-format

Standard success and error payload contracts used across Evento APIs

## Success envelope

All successful responses use the same top-level structure:

```json theme={null}
{
  "success": true,
  "message": "Descriptive success message",
  "data": {}
}
```

## Error envelope

All error responses include `success: false` and a human-readable message:

```json theme={null}
{
  "success": false,
  "message": "Error description"
}
```

Validation-style failures may include an explicit code:

```json theme={null}
{
  "success": false,
  "message": "Validation failed",
  "code": "validation_error"
}
```

## List responses and pagination

Collection endpoints typically return objects with `events` and `pagination`:

```json theme={null}
{
  "success": true,
  "message": "Events fetched successfully",
  "data": {
    "events": [],
    "pagination": {
      "limit": 20,
      "offset": 0,
      "total": 42
    }
  }
}
```

## Field semantics

<ResponseField name="success" type="boolean">
  Indicates whether the request was processed successfully.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable outcome message for logging or UX copy.
</ResponseField>

<ResponseField name="data" type="object">
  Endpoint-specific payload. Shape varies by endpoint.
</ResponseField>

<ResponseField name="code" type="string">
  Optional machine-readable error category.
</ResponseField>

## Surface differences

<CardGroup>
  <Card title="Public API" icon="globe">
    Rich payloads with creator metadata, links, contributions, and pagination.
  </Card>

  <Card title="Embed API" icon="window-maximize">
    Lean payloads optimized for browser rendering with computed event status.
  </Card>
</CardGroup>

## Next steps

<CardGroup>
  <Card title="Error handling" icon="triangle-exclamation" href="/api/error-handling">
    Full status code matrix and retry guidance.
  </Card>

  <Card title="Data models" icon="table" href="/api/data-models">
    Canonical object schemas for events, guests, and pagination.
  </Card>
</CardGroup>


# Fetch user events
Source: https://docs.evento.so/api/users

GET https://evento.so/api/public/v1/users/{username}/events
List public events by username with filtering and pagination

## Endpoint

```http theme={null}
GET /api/public/v1/users/{username}/events
```

## Authentication

<Warning>
  This endpoint requires a public API key.
</Warning>

```http theme={null}
x-evento-api-key: YOUR_API_KEY
```

Retrieve public events created by a user, with optional filtering for time-based views.

## Path parameters

<ParamField type="string">
  Username (case-insensitive, no `@` prefix).
</ParamField>

## Query parameters

<ParamField type="string">
  Optional filter: `upcoming`, `past`, or `profile`.
</ParamField>

<ParamField type="integer">
  Results per page (max 100).
</ParamField>

<ParamField type="integer">
  Pagination offset.
</ParamField>

## Request examples

<RequestExample>
  ```bash cURL theme={null}
  curl "https://evento.so/api/public/v1/users/johndoe/events?type=upcoming&limit=10" \
    -H "x-evento-api-key: YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const username = 'johndoe';
  const params = new URLSearchParams({
    type: 'upcoming',
    limit: '10',
    offset: '0'
  });

  const response = await fetch(
    `https://evento.so/api/public/v1/users/${username}/events?${params}`,
    {
      headers: {
        'x-evento-api-key': process.env.EVENTO_API_KEY
      }
    }
  );

  const payload = await response.json();
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.get(
      'https://evento.so/api/public/v1/users/johndoe/events',
      params={'type': 'upcoming', 'limit': 10, 'offset': 0},
      headers={'x-evento-api-key': os.environ['EVENTO_API_KEY']}
  )

  payload = response.json()
  ```
</RequestExample>

## Success response

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "success": true,
    "message": "Events fetched successfully",
    "data": {
      "events": [
        {
          "id": "evt_future1",
          "title": "Summer Festival 2026",
          "description": "Annual summer celebration",
          "cover": "https://cdn.evento.so/covers/future1.jpg",
          "location": "Central Park, NY",
          "start_date": "2026-06-21T14:00:00Z",
          "end_date": "2026-06-21T22:00:00Z",
          "timezone": "America/New_York",
          "status": "published",
          "visibility": "public",
          "cost": 25.0,
          "created_at": "2026-05-15T09:00:00Z",
          "creator": {
            "id": "usr_123",
            "username": "johndoe",
            "image": "https://cdn.evento.so/avatars/123.jpg",
            "verification_status": "verified"
          },
          "links": {
            "spotify_url": "https://open.spotify.com/playlist/summer2026",
            "wavlake_url": null
          },
          "contributions": {
            "cashapp": "$johndoe",
            "venmo": "@johndoe",
            "paypal": "johndoe@example.com",
            "btc_lightning": null
          }
        }
      ],
      "pagination": {
        "limit": 10,
        "offset": 0,
        "total": 1
      }
    }
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "success": false,
    "message": "Username missing or user not found"
  }
  ```
</ResponseExample>

## Filter semantics

<AccordionGroup>
  <Accordion title="upcoming">
    Returns events where `start_date >= now`.
  </Accordion>

  <Accordion title="past">
    Returns events where `start_date < now`.
  </Accordion>

  <Accordion title="profile">
    Returns profile-visible events (created by or RSVP-associated to the user).
  </Accordion>
</AccordionGroup>

## Pagination pattern

<CodeGroup>
  ```javascript Pagination Loop theme={null}
  async function getAllEventsForUser(username, apiKey) {
    const events = [];
    let offset = 0;
    const limit = 50;

    while (true) {
      const params = new URLSearchParams({
        type: 'upcoming',
        limit: String(limit),
        offset: String(offset)
      });

      const response = await fetch(
        `https://evento.so/api/public/v1/users/${username}/events?${params}`,
        { headers: { 'x-evento-api-key': apiKey } }
      );

      const json = await response.json();
      events.push(...json.data.events);

      if (offset + limit >= json.data.pagination.total) break;
      offset += limit;
    }

    return events;
  }
  ```

  ```python Pagination Loop theme={null}
  import os
  import requests


  def get_all_events_for_user(username):
      events = []
      offset = 0
      limit = 50

      while True:
          response = requests.get(
              f'https://evento.so/api/public/v1/users/{username}/events',
              params={'type': 'upcoming', 'limit': limit, 'offset': offset},
              headers={'x-evento-api-key': os.environ['EVENTO_API_KEY']}
          )

          payload = response.json()['data']
          events.extend(payload['events'])

          if offset + limit >= payload['pagination']['total']:
              break

          offset += limit

      return events
  ```
</CodeGroup>

## Use cases

<CardGroup>
  <Card title="Organizer profiles" icon="id-badge">
    Show upcoming and past events on user profile pages.
  </Card>

  <Card title="Creator analytics" icon="chart-line">
    Build aggregate reports for event volume and cadence by organizer.
  </Card>

  <Card title="Calendar exports" icon="calendar-plus">
    Transform public schedules into external calendars and feeds.
  </Card>

  <Card title="Discovery pages" icon="compass">
    Curate creators and surface upcoming events by niche.
  </Card>
</CardGroup>

## Next steps

<CardGroup>
  <Card title="Get /events/{eventId}" icon="calendar" href="/api/events">
    Retrieve a single public event.
  </Card>

  <Card title="Get /events/{eventId}/guests" icon="users" href="/api/event-guests">
    Retrieve guests and RSVP statuses.
  </Card>
</CardGroup>


# Event calendar
Source: https://docs.evento.so/embed/event-calendar

Render interactive calendar views for a creator event stream

## Basic usage

```tsx theme={null}
import { EventCalendar } from 'evento-embed-react';

export function Calendar() {
  return <EventCalendar username="satoshi" />;
}
```

## Advanced usage

```tsx theme={null}
import { EventCalendar } from 'evento-embed-react';

export function Calendar() {
  return (
    <EventCalendar
      username="satoshi"
      defaultView="month"
      onEventClick={(event) => console.log('clicked', event)}
      theme={{ primary: '#000000', background: '#ffffff', text: '#333333' }}
    />
  );
}
```

## Props

<ParamField type="string">
  Evento username to render events for.
</ParamField>

<ParamField type="string">
  Initial view: `month`, `week`, or `day`.
</ParamField>

<ParamField type="function">
  Callback signature: `(event: Event) => void`.
</ParamField>

<ParamField type="object">
  Theme object with `primary`, `background`, and `text` values.
</ParamField>

<ParamField type="string">
  Additional CSS class names.
</ParamField>

## Notes

* Supports client rendering and SSR frameworks
* Works with shared component theme model

## Next steps

<CardGroup>
  <Card title="Event card" icon="rectangle-wide" href="/embeds/event-card">
    Render individual event objects in card format.
  </Card>

  <Card title="Event list" icon="list" href="/embeds/event-list">
    Render list feeds with filters and pagination.
  </Card>
</CardGroup>


# Event card
Source: https://docs.evento.so/embed/event-card

Render a single Evento event as a reusable card component

## Basic usage

```tsx theme={null}
import { EventCard } from 'evento-embed-react';

export function Card() {
  return <EventCard eventId="evt_abc123" />;
}
```

## Advanced usage

```tsx theme={null}
import { EventCard } from 'evento-embed-react';

export function Card() {
  return (
    <EventCard
      eventId="evt_abc123"
      variant="compact"
      showOrganizer
      onRegisterClick={(event) => {
        window.location.href = `https://evento.so/e/${event.slug}`;
      }}
      theme={{ primary: '#000000', background: '#ffffff', text: '#333333' }}
    />
  );
}
```

## Props

<ParamField type="string">
  Event identifier in `evt_xxxxx` format.
</ParamField>

<ParamField type="string">
  Display style: `default`, `compact`, or `detailed`.
</ParamField>

<ParamField type="boolean">
  Shows organizer profile metadata when enabled.
</ParamField>

<ParamField type="function">
  Callback signature: `(event: Event) => void`.
</ParamField>

<ParamField type="object">
  Theme object with `primary`, `background`, and `text` values.
</ParamField>

<ParamField type="string">
  Additional CSS class names.
</ParamField>

<ParamField type="ReactNode">
  Optional fallback UI for missing or invalid event IDs.
</ParamField>

## Next steps

<CardGroup>
  <Card title="Event calendar" icon="calendar" href="/embeds/event-calendar">
    Render event timelines for creator accounts.
  </Card>

  <Card title="Event list" icon="list" href="/embeds/event-list">
    Render multi-event feeds with filters.
  </Card>
</CardGroup>


# Event list
Source: https://docs.evento.so/embed/event-list

Render event feeds with user-based filters and pagination

## Basic usage

```tsx theme={null}
import { EventList } from 'evento-embed-react';

export function List() {
  return <EventList username="satoshi" />;
}
```

## Advanced usage

```tsx theme={null}
import { EventList } from 'evento-embed-react';

export function List() {
  return (
    <EventList
      username="satoshi"
      type="upcoming"
      limit={10}
      showFilters
      onEventClick={(event) => {
        window.location.href = `https://evento.so/e/${event.slug}`;
      }}
      theme={{ primary: '#000000', background: '#ffffff', text: '#333333' }}
    />
  );
}
```

## Props

<ParamField type="string">
  Evento username to render events for.
</ParamField>

<ParamField type="string">
  Filter type: `upcoming`, `past`, or `profile`.
</ParamField>

<ParamField type="number">
  Max events returned per request.
</ParamField>

<ParamField type="boolean">
  Renders built-in filter controls.
</ParamField>

<ParamField type="function">
  Callback signature: `(event: Event) => void`.
</ParamField>

<ParamField type="object">
  Theme object with `primary`, `background`, and `text` values.
</ParamField>

<ParamField type="string">
  Additional CSS class names.
</ParamField>

## Performance notes

<CardGroup>
  <Card title="Caching" icon="database">
    Built-in request caching reduces repeated API calls.
  </Card>

  <Card title="Tree shaking" icon="tree">
    Import only the component modules you need.
  </Card>
</CardGroup>

## Next steps

<CardGroup>
  <Card title="Event calendar" icon="calendar" href="/embeds/event-calendar">
    Render timeline-style calendar views.
  </Card>

  <Card title="Event card" icon="rectangle-wide" href="/embeds/event-card">
    Render single-event cards and variants.
  </Card>
</CardGroup>


# Components overview
Source: https://docs.evento.so/embed/react-components

Overview of React components for embedding Evento content

## Overview

`evento-embed-react` provides typed, reusable React components for rendering Evento event data.

<CardGroup>
  <Card title="Event card" icon="rectangle-wide" href="/embeds/event-card">
    Single-event card with compact and detailed variants.
  </Card>

  <Card title="Event list" icon="list" href="/embeds/event-list">
    Feed-style list with filtering and pagination options.
  </Card>
</CardGroup>

<CardGroup>
  <Card title="Event calendar" icon="calendar" href="/embeds/event-calendar">
    Interactive calendar for user event timelines.
  </Card>
</CardGroup>

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install evento-embed-react
  ```

  ```bash yarn theme={null}
  yarn add evento-embed-react
  ```

  ```bash pnpm theme={null}
  pnpm add evento-embed-react
  ```

  ```bash bun theme={null}
  bun add evento-embed-react
  ```
</CodeGroup>

## Quick start

```tsx theme={null}
import { EventCalendar, EventCard, EventList } from 'evento-embed-react';

export function App() {
  return (
    <div>
      <EventCalendar username="satoshi" />
      <EventCard eventId="evt_abc123" />
      <EventList username="satoshi" type="upcoming" />
    </div>
  );
}
```

## Shared theming model

```tsx theme={null}
interface Theme {
  primary: string;
  background: string;
  text: string;
}
```

```css theme={null}
.evento-embed {
  --evento-primary: #000000;
  --evento-background: #ffffff;
  --evento-text: #333333;
  --evento-border-radius: 8px;
  --evento-spacing: 16px;
}
```

## Next steps

<CardGroup>
  <Card title="Event calendar" icon="calendar" href="/embeds/event-calendar">
    Props, examples, and callback behavior for calendar views.
  </Card>

  <Card title="Event card" icon="rectangle-wide" href="/embeds/event-card">
    Variants, click handlers, and display controls.
  </Card>

  <Card title="Event list" icon="list" href="/embeds/event-list">
    Filtering, pagination, and feed interactions.
  </Card>

  <Card title="API overview" icon="book" href="/api/overview">
    Understand underlying public and embed API payloads.
  </Card>
</CardGroup>


# Examples
Source: https://docs.evento.so/guides/examples

Copy-ready implementation snippets for common Evento API workflows

## Setup

<CodeGroup>
  ```bash .env theme={null}
  EVENTO_API_KEY=your_public_api_key
  ```

  ```bash cURL Header Reuse theme={null}
  export EVENTO_API_HEADER="x-evento-api-key: $EVENTO_API_KEY"
  ```
</CodeGroup>

## Example: Public event fetch (Node.js)

```javascript theme={null}
export async function getPublicEvent(eventId) {
  const response = await fetch(`https://evento.so/api/public/v1/events/${eventId}`, {
    headers: {
      'x-evento-api-key': process.env.EVENTO_API_KEY
    }
  });

  const json = await response.json();

  if (!json.success) {
    throw new Error(json.message);
  }

  return json.data;
}
```

## Example: Public user events with pagination (Python)

```python theme={null}
import os
import requests


def list_all_upcoming(username):
    all_events = []
    offset = 0
    limit = 50

    while True:
        response = requests.get(
            f'https://evento.so/api/public/v1/users/{username}/events',
            params={'type': 'upcoming', 'limit': limit, 'offset': offset},
            headers={'x-evento-api-key': os.environ['EVENTO_API_KEY']}
        )
        payload = response.json()

        if not payload['success']:
            raise RuntimeError(payload['message'])

        events = payload['data']['events']
        total = payload['data']['pagination']['total']

        all_events.extend(events)
        offset += limit

        if offset >= total:
            break

    return all_events
```

## Example: Embed API browser widget feed

```javascript theme={null}
async function loadWidgetFeed(username) {
  const response = await fetch(`https://evento.so/api/embed/v1/users/${username}/events?limit=6`);
  const payload = await response.json();

  if (!payload.success) {
    throw new Error(payload.message);
  }

  return payload.data;
}
```

## Example: Retry pattern for 429

```javascript theme={null}
export async function fetchWithRetry(url, options, retries = 4) {
  for (let i = 0; i <= retries; i += 1) {
    const response = await fetch(url, options);
    if (response.status !== 429 || i === retries) return response;
    await new Promise((resolve) => setTimeout(resolve, 500 * 2 ** i));
  }
}
```

## Next steps

<CardGroup>
  <Card title="Use cases" icon="map" href="/guides/use-cases">
    End-to-end patterns for product and ops workflows.
  </Card>

  <Card title="Error handling" icon="triangle-exclamation" href="/api/error-handling">
    Status matrix and failure-recovery playbooks.
  </Card>
</CardGroup>


# Source code patterns
Source: https://docs.evento.so/guides/source-code

Implementation-level references used in Evento API wrappers and services

## Purpose

This page documents wrapper and utility patterns used by Evento services so integrators can mirror behavior.

<Note>
  These snippets are representative references, not a published SDK contract.
</Note>

## Public API auth wrapper pattern

```typescript theme={null}
export function withUnkeyAuth(handler: Function, options?: {
  requiredPermissions?: string[]
}) {
  // Validates API key through Unkey
  // Checks permissions (for example events:read)
  // Enforces rate limit policies
  // Returns 401 / 403 / 429 on failure
}
```

Accepted key sources:

1. `x-evento-api-key` header (preferred)
2. `Authorization: Bearer {key}` (alternative)

## Embed API CORS wrapper pattern

```typescript theme={null}
export const corsHeaders = {
  'Access-Control-Allow-Origin': '*',
  'Access-Control-Allow-Methods': 'GET, OPTIONS',
  'Access-Control-Allow-Headers': 'Content-Type',
};

export function embedResponse<T>(data: T, message: string, status = 200) {
  return new Response(JSON.stringify({ success: true, message, data }), {
    status,
    headers: corsHeaders,
  });
}
```

## Response utility pattern

```typescript theme={null}
export const handle200 = (data: any, message: string) =>
  NextResponse.json({ success: true, message, data }, { status: 200 });

export const handle401 = () =>
  NextResponse.json({ success: false, message: 'Not authenticated.' }, { status: 401 });

export const handle404 = () =>
  NextResponse.json({ success: false, message: 'Resource not found.' }, { status: 404 });

export const handle429 = () =>
  NextResponse.json({ success: false, message: 'Too many requests. Please try again later.' }, { status: 429 });
```

## Operational tips

<CardGroup>
  <Card title="Keep contracts stable" icon="shield-halved">
    Preserve `success`, `message`, and `data` envelope consistency across all handlers.
  </Card>

  <Card title="Log with context" icon="file-lines">
    Include actor, endpoint, and request identifiers in server logs for audit and debugging.
  </Card>

  <Card title="Do not expose API keys" icon="lock">
    Keep keyed requests on trusted backend infrastructure.
  </Card>

  <Card title="Prefer explicit validation" icon="list-check">
    Validate path/query/body before data fetches to avoid noisy 500s.
  </Card>
</CardGroup>

## Next steps

<CardGroup>
  <Card title="Examples" icon="code" href="/guides/examples">
    Practical snippets using these patterns in integrations.
  </Card>

  <Card title="Authentication" icon="key" href="/api/authentication">
    Header patterns, CORS rules, and auth failure handling.
  </Card>
</CardGroup>


# Use cases
Source: https://docs.evento.so/guides/use-cases

Practical integration patterns for Public and Embed APIs

## Integration catalog

<CardGroup>
  <Card title="Event discovery platform" icon="compass">
    Build pages that aggregate events from creator accounts and public event IDs.
  </Card>

  <Card title="Calendar and Widgets" icon="calendar-days">
    Use Embed API for browser-safe calendars and event cards.
  </Card>

  <Card title="Event detail views" icon="browser">
    Render detail pages with creator metadata, links, and contributions.
  </Card>

  <Card title="Community intelligence" icon="chart-line">
    Analyze attendance patterns using guest lists and user event history.
  </Card>
</CardGroup>

## 1) Event discovery by ID

<Steps>
  <Step title="Receive or store event IDs">
    Persist IDs like `evt_abc123` from user submissions or previous sync jobs.
  </Step>

  <Step title="Fetch event details">
    Call `GET /api/public/v1/events/{eventId}` with `x-evento-api-key`.
  </Step>

  <Step title="Render and cache">
    Cache responses to reduce request volume and improve page speed.
  </Step>
</Steps>

## 2) Public creator pages

Use `GET /api/public/v1/users/{username}/events` with `type=upcoming` and `type=past`.

```bash theme={null}
curl "https://evento.so/api/public/v1/users/johndoe/events?type=upcoming&limit=20" \
  -H "x-evento-api-key: YOUR_API_KEY"
```

## 3) Browser embeds

Use Embed API for no-auth client rendering:

```javascript theme={null}
const response = await fetch('https://evento.so/api/embed/v1/users/johndoe/events?limit=10');
const data = await response.json();
```

<Info>
  If you need richer metadata (contributions, links, or full creator details), call Public API from your backend.
</Info>

## 4) Guest intelligence

Call `GET /api/public/v1/events/{eventId}/guests` to compute:

* RSVP conversion by status (`yes`, `maybe`, `no`)
* Verification distribution across attendees
* Repeat attendee trends across event IDs

## Next steps

<CardGroup>
  <Card title="Examples" icon="code" href="/guides/examples">
    Copy-and-adapt snippets for Node, Python, and browser clients.
  </Card>

  <Card title="Source code patterns" icon="github" href="/guides/source-code">
    Wrapper-level implementation references used in Evento services.
  </Card>
</CardGroup>