22 endpoints · 29 MCP tools · Full coverage

Built for machines.
Loved by developers.

Every operation in Ciry is available through the REST API and the MCP server. Automate everything. Let your AI run your calendar.

Authentication

All authenticated endpoints require a Bearer token in the Authorization header. Generate your API key from the Settings page or via the API.

Authorization: Bearer ciry_sk_your_api_key_here

Public endpoints (availability check, booking) do not require authentication.

MCP Setup

Add Ciry to your AI agent's MCP config. Drop this into your claude_desktop_config.json or equivalent:

{ "mcpServers": { "ciry": { "url": "https://ciry.ai/api/mcp", "headers": { "Authorization": "Bearer ciry_sk_your_api_key_here" } } } }

Your agent gets 24 native tools covering scheduling, orgs, teams, branding, and uploads.

Endpoint Reference

Scheduling

GET/api/v1/events

List event types

Show curl example
curl -H "Authorization: Bearer $API_KEY" https://ciry.ai/api/v1/events
POST/api/v1/events

Create event type

Show curl example
curl -X POST -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \ -d '{"name":"Discovery Call","duration_minutes":30}' \ https://ciry.ai/api/v1/events
GET/api/v1/events/:id

Get event type by ID

Show curl example
curl -H "Authorization: Bearer $API_KEY" https://ciry.ai/api/v1/events/evt_123
PATCH/api/v1/events/:id

Update event type

Show curl example
curl -X PATCH -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \ -d '{"name":"Updated Name"}' \ https://ciry.ai/api/v1/events/evt_123
DELETE/api/v1/events/:id

Delete event type

Show curl example
curl -X DELETE -H "Authorization: Bearer $API_KEY" https://ciry.ai/api/v1/events/evt_123
GET/api/v1/events/:id/hosts

Get host pool for a team event (assignment_strategy + members)

Show curl example
curl -H "Authorization: Bearer $API_KEY" https://ciry.ai/api/v1/events/evt_123/hosts
PUT/api/v1/events/:id/hosts

Replace host pool (must all be team_members of the event's team)

Show curl example
curl -X PUT -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d '{"host_user_ids":["usr_456","usr_789"]}' https://ciry.ai/api/v1/events/evt_123/hosts
GET/api/v1/schedule

Get availability schedule

Show curl example
curl -H "Authorization: Bearer $API_KEY" https://ciry.ai/api/v1/schedule
PUT/api/v1/schedule

Set availability schedule

Show curl example
curl -X PUT -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \ -d '{"monday":{"start":"09:00","end":"17:00"}}' \ https://ciry.ai/api/v1/schedule
GET/api/v1/availability

Check available slots (public). Returns [{start, end, duration_minutes}]

Show curl example
curl "https://ciry.ai/api/v1/availability?user_id=USR_ID&event_id=EVT_ID&start=2026-04-15&end=2026-04-20&timezone=America/Denver"
POST/api/v1/bookings

Book a meeting (public). Validates the slot, picks a host for round-robin, writes the calendar event, persists to bookings + booking_answers.

Show curl example
curl -X POST -H "Content-Type: application/json" \ -d '{"event_id":"evt_123","start_time":"2026-04-15T14:30:00Z","timezone":"America/Denver","guest_name":"Sarah","guest_email":"sarah@acme.co","guest_notes":"optional","answers":[{"question_id":"q_uuid","answer":"text"}]}' \ https://ciry.ai/api/v1/bookings
GET/api/v1/bookings

List your bookings. Filters: ?status=confirmed|cancelled|all, ?from=ISO, ?to=ISO

Show curl example
curl -H "Authorization: Bearer $API_KEY" "https://ciry.ai/api/v1/bookings?status=confirmed"
GET/api/v1/bookings/:id

Get a single booking

Show curl example
curl -H "Authorization: Bearer $API_KEY" https://ciry.ai/api/v1/bookings/bkg_123
DELETE/api/v1/bookings/:id

Cancel a booking. Best-effort calendar removal.

Show curl example
curl -X DELETE -H "Authorization: Bearer $API_KEY" https://ciry.ai/api/v1/bookings/bkg_123
PATCH/api/v1/bookings/:id

Reschedule. Same host, validates new slot, replaces calendar event.

Show curl example
curl -X PATCH -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \ -d '{"start_time":"2026-04-16T15:00:00Z","timezone":"America/Denver"}' \ https://ciry.ai/api/v1/bookings/bkg_123
GET/api/v1/events/:id/questions

List per-event booking questions (public read)

Show curl example
curl https://ciry.ai/api/v1/events/evt_123/questions
PUT/api/v1/events/:id/questions

Replace the full set of booking questions on an event

Show curl example
curl -X PUT -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \ -d '{"questions":[{"label":"What\'s the goal?","type":"textarea","required":true}]}' \ https://ciry.ai/api/v1/events/evt_123/questions
GET/api/v1/availability-profiles

List your availability profiles with embedded slots + overrides

Show curl example
curl -H "Authorization: Bearer $API_KEY" https://ciry.ai/api/v1/availability-profiles
POST/api/v1/availability-profiles

Create a profile with optional weekly slots

Show curl example
curl -X POST -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \ -d '{"name":"Work hours","timezone":"America/Denver","is_default":true,"slots":[{"day_of_week":"monday","start_time":"09:00","end_time":"17:00"}]}' \ https://ciry.ai/api/v1/availability-profiles
GET/api/v1/availability-profiles/:id

Get one profile with slots + overrides

Show curl example
curl -H "Authorization: Bearer $API_KEY" https://ciry.ai/api/v1/availability-profiles/prof_123
PATCH/api/v1/availability-profiles/:id

Update name/timezone/default; pass slots to replace them

Show curl example
curl -X PATCH -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d '{"name":"Updated"}' https://ciry.ai/api/v1/availability-profiles/prof_123
DELETE/api/v1/availability-profiles/:id

Delete a profile (cascades to slots + overrides)

Show curl example
curl -X DELETE -H "Authorization: Bearer $API_KEY" https://ciry.ai/api/v1/availability-profiles/prof_123
POST/api/v1/availability-profiles/:id/overrides

Upsert a date override (holiday, special hours)

Show curl example
curl -X POST -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d '{"date":"2026-12-25","is_available":false}' https://ciry.ai/api/v1/availability-profiles/prof_123/overrides
DELETE/api/v1/availability-profiles/:id/overrides/:overrideId

Remove a date override

Show curl example
curl -X DELETE -H "Authorization: Bearer $API_KEY" https://ciry.ai/api/v1/availability-profiles/prof_123/overrides/ovr_456

Organizations

GET/api/v1/orgs

List your organizations

Show curl example
curl -H "Authorization: Bearer $API_KEY" https://ciry.ai/api/v1/orgs
POST/api/v1/orgs

Create organization

Show curl example
curl -X POST -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \ -d '{"name":"Acme Inc","slug":"acme"}' \ https://ciry.ai/api/v1/orgs
GET/api/v1/orgs/:id

Get organization

Show curl example
curl -H "Authorization: Bearer $API_KEY" https://ciry.ai/api/v1/orgs/org_123
PATCH/api/v1/orgs/:id

Update organization

Show curl example
curl -X PATCH -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \ -d '{"name":"New Name"}' \ https://ciry.ai/api/v1/orgs/org_123
DELETE/api/v1/orgs/:id

Delete organization

Show curl example
curl -X DELETE -H "Authorization: Bearer $API_KEY" https://ciry.ai/api/v1/orgs/org_123
GET/api/v1/orgs/:id/members

List org members

Show curl example
curl -H "Authorization: Bearer $API_KEY" https://ciry.ai/api/v1/orgs/org_123/members
POST/api/v1/orgs/:id/members

Add org member

Show curl example
curl -X POST -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \ -d '{"email":"new@acme.co","role":"member"}' \ https://ciry.ai/api/v1/orgs/org_123/members
DELETE/api/v1/orgs/:id/members

Remove org member by user_id query param

Show curl example
curl -X DELETE -H "Authorization: Bearer $API_KEY" "https://ciry.ai/api/v1/orgs/org_123/members?user_id=usr_456"
PATCH/api/v1/orgs/:id/members/:userId

Update a member's role

Show curl example
curl -X PATCH -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d '{"role":"admin"}' https://ciry.ai/api/v1/orgs/org_123/members/usr_456
DELETE/api/v1/orgs/:id/members/:userId

Remove org member (path-style)

Show curl example
curl -X DELETE -H "Authorization: Bearer $API_KEY" https://ciry.ai/api/v1/orgs/org_123/members/usr_456
GET/api/v1/orgs/:id/teams

List teams

Show curl example
curl -H "Authorization: Bearer $API_KEY" https://ciry.ai/api/v1/orgs/org_123/teams
POST/api/v1/orgs/:id/teams

Create team

Show curl example
curl -X POST -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \ -d '{"name":"Engineering"}' \ https://ciry.ai/api/v1/orgs/org_123/teams
GET/api/v1/orgs/:id/teams/:teamId

Get team

Show curl example
curl -H "Authorization: Bearer $API_KEY" https://ciry.ai/api/v1/orgs/org_123/teams/team_456
PATCH/api/v1/orgs/:id/teams/:teamId

Update team

Show curl example
curl -X PATCH -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \ -d '{"name":"Updated Team"}' \ https://ciry.ai/api/v1/orgs/org_123/teams/team_456
DELETE/api/v1/orgs/:id/teams/:teamId

Delete team

Show curl example
curl -X DELETE -H "Authorization: Bearer $API_KEY" https://ciry.ai/api/v1/orgs/org_123/teams/team_456
GET/api/v1/orgs/:id/teams/:teamId/members

List team members

Show curl example
curl -H "Authorization: Bearer $API_KEY" https://ciry.ai/api/v1/orgs/org_123/teams/team_456/members
POST/api/v1/orgs/:id/teams/:teamId/members

Add team member

Show curl example
curl -X POST -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \ -d '{"user_id":"usr_789"}' \ https://ciry.ai/api/v1/orgs/org_123/teams/team_456/members
DELETE/api/v1/orgs/:id/teams/:teamId/members

Remove team member

Show curl example
curl -X DELETE -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \ -d '{"user_id":"usr_789"}' \ https://ciry.ai/api/v1/orgs/org_123/teams/team_456/members

Branding & Assets

GET/api/v1/branding

Get branding (with fallback chain)

Show curl example
curl -H "Authorization: Bearer $API_KEY" "https://ciry.ai/api/v1/branding?org_id=org_123"
PUT/api/v1/branding

Set branding

Show curl example
curl -X PUT -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \ -d '{"org_id":"org_123","primary_color":"#8b5cf6","logo_url":"https://..."}' \ https://ciry.ai/api/v1/branding
POST/api/v1/upload

Upload image

Show curl example
curl -X POST -H "Authorization: Bearer $API_KEY" \ -F "file=@logo.png" -F "folder=logos" \ https://ciry.ai/api/v1/upload

Discovery (Public)

GET/api/v1/discover/:slug

Get user or org info, events with per-event questions, and booking instructions — no auth needed

Show curl example
curl https://ciry.ai/api/v1/discover/justin

Connections (Calendar / Conferencing OAuth)

GET/api/v1/connections

List connected toolkits

Show curl example
curl -H "Authorization: Bearer $API_KEY" https://ciry.ai/api/v1/connections
POST/api/v1/connections

Initiate OAuth — returns connect_url for the user to visit

Show curl example
curl -X POST -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d '{"toolkit":"googlecalendar"}' https://ciry.ai/api/v1/connections
DELETE/api/v1/connections/:toolkit

Revoke a toolkit. Optional ?connected_account_id=...

Show curl example
curl -X DELETE -H "Authorization: Bearer $API_KEY" https://ciry.ai/api/v1/connections/googlecalendar

Orchestration (Phase 2)Coming soon

GET/api/v1/meeting-requests

List your meeting requests. Filters: ?status=&limit=

Show curl example
curl -H "Authorization: Bearer $API_KEY" "https://ciry.ai/api/v1/meeting-requests?status=draft"
POST/api/v1/meeting-requests

Create a delegated scheduling job

Show curl example
curl -X POST -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d '{"counterparty_emails":["sarah@acme.co"],"event_id":"evt_123","context":"intro chat next week"}' https://ciry.ai/api/v1/meeting-requests
GET/api/v1/meeting-requests/:id

Get one meeting request

Show curl example
curl -H "Authorization: Bearer $API_KEY" https://ciry.ai/api/v1/meeting-requests/req_123
PATCH/api/v1/meeting-requests/:id

Update fields (not status — use /transition)

Show curl example
curl -X PATCH -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d '{"context":"updated"}' https://ciry.ai/api/v1/meeting-requests/req_123
DELETE/api/v1/meeting-requests/:id

Delete (rare — usually transition to canceled)

Show curl example
curl -X DELETE -H "Authorization: Bearer $API_KEY" https://ciry.ai/api/v1/meeting-requests/req_123
POST/api/v1/meeting-requests/:id/transition

Move to a new status. Illegal transitions return 409.

Show curl example
curl -X POST -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d '{"to_status":"booked","booking_id":"bkg_456"}' https://ciry.ai/api/v1/meeting-requests/req_123/transition
GET/api/v1/meeting-requests/:id/events

Audit log: every status change, message, hold, etc.

Show curl example
curl -H "Authorization: Bearer $API_KEY" https://ciry.ai/api/v1/meeting-requests/req_123/events
GET/api/v1/counterparties

List people you have scheduled with

Show curl example
curl -H "Authorization: Bearer $API_KEY" "https://ciry.ai/api/v1/counterparties?search=acme"
POST/api/v1/counterparties

Upsert a counterparty (idempotent on owner+email)

Show curl example
curl -X POST -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d '{"email":"sarah@acme.co","display_name":"Sarah","org_relationship":"external"}' https://ciry.ai/api/v1/counterparties
GET/api/v1/counterparties/:id

Get one counterparty

Show curl example
curl -H "Authorization: Bearer $API_KEY" https://ciry.ai/api/v1/counterparties/cp_456
DELETE/api/v1/counterparties/:id

Delete a counterparty

Show curl example
curl -X DELETE -H "Authorization: Bearer $API_KEY" https://ciry.ai/api/v1/counterparties/cp_456
GET/api/v1/approval-policy

Your approval policy (auto-created with defaults)

Show curl example
curl -H "Authorization: Bearer $API_KEY" https://ciry.ai/api/v1/approval-policy
PATCH/api/v1/approval-policy

Update policy fields

Show curl example
curl -X PATCH -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d '{"auto_book_external":true,"vip_emails":["ceo@acme.co"]}' https://ciry.ai/api/v1/approval-policy
POST/api/v1/meeting-requests/:id/route

Phase 3 — assess capability, pick mode, open negotiation, send outreach. Optional body { force_mode }.

Show curl example
curl -X POST -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d '{}' https://ciry.ai/api/v1/meeting-requests/req_123/route
POST/api/v1/intent

Phase 6 — natural-language → meeting_request. Body { text, force_create? }. Returns { intent, meetingRequestId, status }.

Show curl example
curl -X POST -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d '{"text":"Book 30 min with Sarah next week"}' https://ciry.ai/api/v1/intent

Tasks

GET/api/v1/tasks

List tasks (filter by ?status=todo|done, ?org_id=)

Show curl example
curl -H "Authorization: Bearer $API_KEY" "https://ciry.ai/api/v1/tasks?status=todo"
POST/api/v1/tasks

Create a task

Show curl example
curl -X POST -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \ -d '{"title":"Prep deck for Tuesday call","due_date":"2026-04-15"}' \ https://ciry.ai/api/v1/tasks
GET/api/v1/tasks/:id

Get a task

Show curl example
curl -H "Authorization: Bearer $API_KEY" https://ciry.ai/api/v1/tasks/task_123
PATCH/api/v1/tasks/:id

Update a task (title, notes, status, due_date)

Show curl example
curl -X PATCH -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \ -d '{"status":"done"}' \ https://ciry.ai/api/v1/tasks/task_123
DELETE/api/v1/tasks/:id

Delete a task

Show curl example
curl -X DELETE -H "Authorization: Bearer $API_KEY" https://ciry.ai/api/v1/tasks/task_123

Profile

GET/api/v1/me

Get your profile

Show curl example
curl -H "Authorization: Bearer $API_KEY" https://ciry.ai/api/v1/me
PATCH/api/v1/me

Update your profile

Show curl example
curl -X PATCH -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \ -d '{"name":"Matt Smith","timezone":"America/New_York"}' \ https://ciry.ai/api/v1/me
POST/api/v1/me/api-key

Generate API key

Show curl example
curl -X POST -H "Authorization: Bearer $API_KEY" https://ciry.ai/api/v1/me/api-key

MCP Tools

24 native tools available to any MCP-compatible AI agent. Your assistant calls these directly — no HTTP wrangling required.

Scheduling

ciry.list_eventsList all event types
ciry.create_eventCreate a new event type
ciry.get_eventGet event type details
ciry.update_eventUpdate an event type
ciry.delete_eventDelete an event type
ciry.get_scheduleGet availability schedule
ciry.set_scheduleSet availability schedule
ciry.check_availabilityCheck open time slots
ciry.book_meetingBook a meeting

Organizations

ciry.list_orgsList your organizations
ciry.create_orgCreate an organization
ciry.get_orgGet organization details
ciry.update_orgUpdate an organization
ciry.delete_orgDelete an organization
ciry.manage_membersAdd or remove org members
ciry.list_teamsList teams in an org
ciry.create_teamCreate a team
ciry.manage_teamUpdate or delete a team
ciry.manage_team_membersAdd or remove team members

Branding & Assets

ciry.get_brandingGet branding with fallback chain
ciry.set_brandingSet colors, logo, and theme
ciry.upload_imageUpload an image asset

Tasks

ciry.list_tasksList your tasks/todos
ciry.create_taskCreate a task or reminder
ciry.update_taskUpdate a task
ciry.complete_taskMark a task as done
ciry.delete_taskDelete a task

Profile

ciry.get_profileGet your profile
ciry.update_profileUpdate profile details

Ready to automate?

Sign up, grab your API key, and let your AI take over scheduling.

Start Free Trial