API Reference

Authentication, errors, endpoints, and caching. Also available via the swoogo-integration-guide tool.

Authentication

MCP OAuth 2.1 (Recommended)

Automatic when connecting any MCP client. The client discovers metadata at /.well-known/oauth-authorization-server, you approve with Swoogo credentials, and tokens refresh automatically.

Direct Swoogo API Authentication

For server-side backends that call the Swoogo API directly (e.g., registration form submissions):

POST {SWOOGO_API_URL}/oauth2/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64(client_id:client_secret)>

grant_type=client_credentials

Response:

{
  "access_token": "abc123...",
  "type": "bearer",
  "expires_at": "2026-02-24 15:30:00"
}

Critical: Credentials go in the Authorization: Basic header (Base64-encoded client_id:client_secret), NOT in the POST body. The endpoint is /oauth2/token — no .json suffix.

Token Caching

Cache the token in memory (~30 min lifetime). The response uses expires_at (absolute timestamp). Re-authenticate on 401. Never request a new token per call.

Error Handling

422 Validation Error

Field-level errors array:

[
  { "field": "email", "message": "Email is required" },
  { "field": "reg_type_id", "message": "Invalid registration type" }
]

Map error.field to question.attribute from the event questions to display inline validation errors in forms.

400 Bad Request

Structural issues:

{ "message": "You must specify a valid event_id." }

429 Rate Limit

Per-tenant rate limits. If exceeded:

HTTP/1.1 429 Too Many Requests
Retry-After: 60

Wait Retry-After seconds. Writes have stricter limits than reads.

401 Unauthorized

Token expired or revoked. MCP clients re-authenticate automatically.

Endpoints Overview

MCP Endpoints

Endpoint	Method	Description
`/mcp`	POST / GET	Builder profile — 13 curated tools for AI builders
`/mcp/assistant`	POST / GET	Full assistant profile — 31 domain tools + system tools

OAuth Endpoints

Endpoint	Method	Description
`/.well-known/oauth-authorization-server`	GET	OAuth 2.1 server metadata (RFC 8414)
`/.well-known/oauth-protected-resource`	GET	Protected resource metadata
`/oauth/authorize`	GET	Authorization endpoint (redirects to credential form)
`/oauth/token`	POST	Token exchange (authorization code → access + refresh tokens)
`/oauth/register`	POST	Dynamic client registration (RFC 7591)

Swoogo API Entity Endpoints

For server-side backends calling the Swoogo API directly:

Entity	Endpoint	Notes
Registrants	`/registrants.json`	.json suffix required. Flat body with event_id.
Sessions	`/sessions.json`	Read-only via API. Requires event_id.
Speakers	`/speakers.json`	Read-only. Requires event_id.
Contacts	`/contacts.json`	Org-wide, not event-specific.
Transactions	`/transactions.json`	Create requires event_id and registrant_id.

Common Pitfalls

Pitfall	Fix
Wrong path: `POST /events/{id}/registrants`	Use `POST /registrants.json` with `event_id` in body
Missing `.json` suffix on CRUD	Entity endpoints require it (`/registrants.json`). Action endpoints don't.
Wrong paths silently redirect	Check `response.status === 0` or `response.type === "opaqueredirect"`
List response is not an array	Access `.items` — shape is `{ items: [...], _meta: {...} }`
Missing `event_id`	Required on most list endpoints. Omitting returns empty or 400.
No CORS on Swoogo API	Build a server-side backend. Browsers cannot call it directly.
Choice fields: sending name instead of ID	`dropDownList`, `radioList`: send choice ID (integer)
POST is not idempotent	Persist `registrant_id` immediately after creation
Address fields: `work_address_id`	Payload key is `workAddress` (camelCase, drop `_id`)
Session questions (`sq_*`) in POST	Skip in POST. Assign via PUT with `session_ids` after creation.
Upload fields in POST	Skip in POST. Use `PUT /image/registrant/{id}/{attribute}` after.
Flat body required	`POST /registrants.json`: flat object, no nested wrapper. Include `event_id`.

Caching

Per-tenant cache TTLs:

Entity	TTL	Rationale
Event details	5 minutes	Changes infrequently once published
Sessions	5 minutes	Schedule may change during planning
Speakers	5 minutes	Changes infrequently
Registrants	1 minute	Changes frequently during registration
Questions / Form config	5 minutes	Structure changes rarely
Reg types / Packages	5 minutes	Pricing changes rarely
Transactions	1 minute	Financial data needs freshness

Troubleshooting

Problem	Fix
401 Unauthorized	Token expired. MCP clients re-auth automatically. Direct API: request new token via `POST /oauth2/token`.
422 Validation Error	Map `error.field` to `question.attribute` for inline display. See Common Pitfalls.
Timeout / No Response	Session expired from inactivity. Reconnect your MCP client.
Validation keeps failing	Check `swoogo-validate-page` errors: wrong IDs, missing pricing for paid events, sections for missing data. After 3 failures: stop.