canonical: https://jentic.com/apis/gancio.org/gancio # Gancio API Jentic publishes the only available OpenAPI specification for Gancio API, keeping it validated and agent-ready. Gancio is a self-hosted, federated event platform built for local communities, collectives, and grassroots organisations - instances run independently and can syndicate events to one another. The API exposes event discovery, OAuth login, refresh-token rotation, and authenticated user profile lookup so agents can populate community calendars, mirror events to other platforms, or build moderation tooling. Each deployment uses its own base URL, defaulting to the public demo instance. ## For AI agents Read events from a Gancio community calendar, authenticate with OAuth, refresh tokens, and look up the active user profile. ## Scope Does not handle ticketing, payments, or RSVP collection - use for federated community event listing and authentication only. ## Capabilities - List upcoming community events filtered by start and end timestamps via `/api/events` - Authenticate a user against a Gancio instance using `/oauth/login` to obtain access and refresh tokens - Rotate an expiring access token by calling `/oauth/token` with a refresh_token grant - Retrieve the authenticated user's profile through `/api/user` to confirm role and instance binding - Point requests at any self-hosted Gancio instance via the {instance} server variable, not just the demo ## Use cases ### Community Event Aggregator Pull a rolling list of upcoming events from one or more Gancio instances into a unified feed for a city or scene. The agent calls `/api/events` with start and end Unix timestamps, deduplicates by id, and pushes a normalised payload to a website, newsletter, or social bot. Replaces hand-curated event roundups with a daily refresh. Example prompt: Call GET `/api/events` with start=now and end=now+7d, then format each item into a markdown digest grouped by day ### Cross-Posting Bot for Collectives Mirror events created on a collective's Gancio instance to other channels such as Mastodon, Slack, or a static site. After authenticating with `/oauth/login` and storing tokens, the bot polls `/api/events` on an interval, detects new ids, and republishes them. Keeps members aware of upcoming gatherings without duplicating data entry. Example prompt: Authenticate via POST `/oauth/login` (deprecated path, use refresh flow when available), then poll GET `/api/events` every 15 minutes and post new event ids to the configured channel ### Token-Rotated Long-Running Workers Run a background worker that hits Gancio for hours or days without manual reauthentication. The worker stores the refresh_token, calls `/oauth/token` before expiry, and replaces the bearer token in memory. Handles long-lived integrations like archive scrapers and analytics jobs that would otherwise drop on token expiry. Example prompt: When access token returns 401, POST `/oauth/token` with grant_type=refresh_token and refresh_token=, then retry the original request with the new bearer ### Agent-Backed Community Calendar Through Jentic AI agents discover Gancio through Jentic's intent search, load the events listing operation, and answer questions like 'what's on this weekend' for a community without scraping a website. Jentic isolates the bearer token in its vault. Brings federated grassroots event data into agent workflows that previously needed bespoke scrapers. Example prompt: Use Jentic search query 'list community events' to load the gancio_list_events tool, execute with start and end timestamps, and return the event titles ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | `/oauth/login` | Obtain access and refresh tokens with credentials | | POST | `/oauth/token` | Refresh an expired access token | | GET | `/api/events` | List events filtered by start and end timestamps | | GET | `/api/user` | Retrieve the authenticated user's profile | ## Key resources - **Authentication** — OAuth login and token refresh against a Gancio instance - **Events** — List events filtered by time range - **User** — Retrieve the authenticated user's profile ## Why Jentic - **Setup:** Wiring the Gancio API by hand means running its OAuth login and token exchange, carrying the bearer token, and picking between the demo host and your self-hosted instance yourself. Through Jentic you install once, import the Gancio API from the API Directory, store the token once, and your agent calls it. - **Permission scoping:** Gancio exposes login, token, event listing, and user reads rather than per-resource write paths, so scope this by operation: limit the agent to the operations it needs, such as listing events or reading the current user, and leave the rest out of the allowed set. Every operation the agent can run is one you chose to include. - **Credential handling:** Your Gancio bearer token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'list community events' or 'read the current Gancio user', and Jentic returns the matching Gancio API operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Meetup API** — Meetup is a centralised commercial event platform; Gancio is decentralised, self-hosted, and aimed at grassroots communities. - **Slack API** — Post upcoming Gancio events into a Slack channel for community announcements. - **OpenAI API** — Use OpenAI to summarise long event descriptions before posting a digest. ## FAQ ### Why is there no official OpenAPI spec for Gancio API? Gancio does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Gancio API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the Gancio API use? Gancio uses OAuth 2.0 bearer tokens. Tokens are obtained from `/oauth/login` (deprecated in v2.0) and refreshed via `/oauth/token.` When called through Jentic the bearer is stored encrypted in the vault and injected per request. ### Can I list events for a specific date range with the Gancio API? Yes. GET `/api/events` accepts optional start and end query parameters as Unix timestamps; omitting start defaults to the current time, returning future events from now. ### How do I refresh a Gancio access token? Call POST `/oauth/token` with grant_type=refresh_token and the stored refresh_token in the body. The response delivers a fresh access token plus an updated refresh token to persist for the next rotation. ### Can I use the Gancio API with my own self-hosted instance? Yes. The spec defines a server variable {instance} that defaults to demo.gancio.org. Set it to your instance hostname (for example events.example.org) and all endpoints will route there. ### How do I list community events through Jentic? Install with pip install jentic, search 'list community events', load the schema for the gancio_list_events operation, and execute with your start and end timestamps. Jentic handles bearer-token injection automatically. ### Can I limit what my agent is allowed to do with the Gancio API? Yes. Because Jentic One is self-hosted, your own rules decide which Gancio operations and credentials the agent may use. The Gancio API exposes only read and auth paths such as listing events via GET `/api/events`, reading the current user via GET `/api/user`, OAuth login, and token refresh, so you scope access by operation. Add just the ones the agent needs, for example listing events, and leave the login, token, or user reads out of the allowed set.