findtime.io
Time Intelligence for Apps and Agents
findtime.io now has a production time intelligence surface for apps and agents. The goal is not thin parity with legacy time APIs. The goal is better ambiguity handling, better DST truth, and better cross-timezone workflow intelligence.
You can use this surface from your app backend, internal tools, or MCP clients. Start with /time/answer for raw user prompts, or /time/snapshot when you already know the locations and want packaged time data.
MCP clients reach the same tools two ways. The local package uses a developer API key. https://mcp.findtime.io/mcp uses OAuth 2.1 with PKCE, and it also accepts that API key as a bearer token. Read Hosted MCP.
Built on a global location dataset with 62,179 cities, plus country and timezone coverage tuned for accurate resolution, DST handling, and cross-timezone workflows.
Ambiguity-safe
CST, IST, Victoria, San Jose, and other messy inputs return candidates instead of false confidence.
DST truth
Current state, last transition, next transition, and current abbreviation are packaged directly.
Workflow layer
Overlap and meeting-finding move beyond commodity “what time is it?” answers.
Agent-ready
The same production API powers MCP so agents and apps stay on one truth surface.
API Quickstart
If you are building an agent or accepting raw user text, start with /time/answer. If your app already knows the intent, use the narrower deterministic endpoint directly, such as /time/snapshot for one-call packaged time data.
- Every API request uses
Authorization: Bearer YOUR_SECRET_KEY. - All current endpoints are GET requests.
- Use
/time/answerwhen you wantfindtime.ioto classify a natural-language prompt and choose the right deterministic behavior. Use narrower endpoints directly when your app already knows the intent. - Use pipe-delimited values for multi-location inputs such as London|Tokyo|New York.
- If a query is ambiguous, the API returns candidates instead of guessing.
- Batch time snapshots can return partial success with per-location status, so one ambiguous place does not fail the whole request.
curl --request GET \ --url "https://time-api.findtime.io/time/snapshot?query=Tokyo&countryCode=JP&includeTransitions=true" \ --header "Authorization: Bearer YOUR_SECRET_KEY"
{
"shape": "time_snapshot.v2",
"resolved": false,
"ambiguous": true,
"partial": true,
"resolvedCount": 1,
"ambiguousCount": 1,
"notFoundCount": 0,
"locations": [
{
"side": 0,
"status": "resolved",
"query": "Iceland",
"resolutionReason": "country=IS",
"location": {
"name": "Reykjavík",
"countryCode": "IS",
"countryName": "Iceland",
"timezoneIana": "Atlantic/Reykjavik"
},
"timezone": {
"iana": "Atlantic/Reykjavik",
"abbreviation": "GMT",
"utcOffset": "UTC+0"
}
},
{
"side": 1,
"status": "ambiguous",
"resolved": false,
"ambiguous": true,
"query": "Paris",
"candidates": [
{
"type": "city",
"id": "findtime:paris|FR|2988507|Europe/Paris",
"name": "Paris",
"slug": "paris",
"displayName": "Paris",
"label": "Paris, France (Europe/Paris)",
"countryCode": "FR",
"countryName": "France",
"timezoneIana": "Europe/Paris",
"population": 2138551,
"admin1": "11",
"admin1Name": "",
"stateCode": "11",
"geonameId": 2988507,
"coordinates": { "lat": 48.85341, "lon": 2.3488 },
"suggestedId": "findtime:paris|FR|2988507|Europe/Paris",
"suggestedQuery": "Paris, France",
"currentTime": {
"iso": "2026-10-14T14:00:00.000+02:00",
"date": "2026-10-14",
"time24h": "14:00",
"time12h": "2:00 PM",
"weekday": "Wednesday",
"shortDate": "Wed, Oct 14"
},
"abbreviation": "CEST",
"utcOffset": "UTC+2",
"offsetMinutes": 120,
"isDST": true,
"observesDST": true,
"dst": {
"observesDST": true,
"isDSTActiveNow": true,
"currentAbbreviation": "CEST"
}
},
{
"type": "city",
"id": "findtime:paris-us|US|4717560|America/Chicago",
"name": "Paris",
"slug": "paris-us",
"displayName": "Paris",
"label": "Paris, TX (America/Chicago)",
"countryCode": "US",
"countryName": "United States",
"timezoneIana": "America/Chicago",
"population": 24782,
"admin1": "TX",
"admin1Name": "Texas",
"stateCode": "TX",
"geonameId": 4717560,
"coordinates": { "lat": 33.66094, "lon": -95.55551 },
"suggestedId": "findtime:paris-us|US|4717560|America/Chicago",
"suggestedQuery": "Paris, TX",
"currentTime": {
"iso": "2026-10-14T07:00:00.000-05:00",
"date": "2026-10-14",
"time24h": "07:00",
"time12h": "7:00 AM",
"weekday": "Wednesday",
"shortDate": "Wed, Oct 14"
},
"abbreviation": "CDT",
"utcOffset": "UTC-5",
"offsetMinutes": -300,
"isDST": true,
"observesDST": true,
"dst": {
"observesDST": true,
"isDSTActiveNow": true,
"currentAbbreviation": "CDT"
}
}
],
"totalCandidates": 7,
"candidateLimit": 6,
"candidateOffset": 0,
"additionalCandidates": 1,
"additionalCandidatesLabel": "+1 more",
"moreCandidates": {
"candidateLimit": 6,
"candidateOffset": 6,
"resolve": "/resolve?query=Paris&candidateLimit=6&candidateOffset=6",
"current": "/time/current?query=Paris&candidateLimit=6&candidateOffset=6",
"search": "/locations/search?query=Paris&limit=7"
}
}
]
}Why findtime.io API is different
We designed the API around the jobs developers and agents actually need, not around a giant list of thin wrappers. Start with /time/answer for natural-language prompts, or use narrower deterministic endpoints when your integration already knows the intent.
The same production truth surface powers the API, the MCP server, and findtime.io itself. That keeps timezone handling, DST transitions, location resolution, overlap windows, and meeting suggestions aligned across the website, integrations, and agents.
Response contract and disambiguation
The API is designed to surface ambiguity instead of hiding it. When a query is underspecified, the contract is to return enough structure for the caller to retry deterministically rather than silently guessing.
resolved: truemeans the request mapped to a canonical location or timezone and the payload can be used directly.ambiguous: truewithstatus: "ambiguous"means the input matched multiple valid places. There is no primary pick. Each candidate includes local time, UTC offset, abbreviation, DST, population, id, and coordinates. Page extra namesakes withcandidateLimit/candidateOffsetor followmoreCandidates./time/answeris the natural-language agent endpoint. It returnsintent,toolUsed,answer, and the underlying deterministic result so callers can audit how the answer was produced. Structured callers can skip classification and call the narrower endpoint directly./time/snapshotcan return partial batch success. Inspect each location row’sstatusinstead of assuming the entire batch resolved or failed together.notFoundor HTTP404means the API could not resolve the input with enough confidence. Start with/locations/searchif you need a deterministic retry path.countryCodeon/locations/searchis a ranking and disambiguation hint. It can move a country to the top of the results, but it does not guarantee that every returned row belongs to that country.- Ambiguous candidates now include both
suggestedQueryandsuggestedIdso apps and agents can retry with either a human-readable city-country form likeParis, Franceor a stablefindtime:id. - Abbreviations such as
IST,CST, andBSTare often ambiguous. Pair them with a country or region, or use/time/answeror/locations/searchto get structured clarification. - Country-name queries for
/time/currentand/time/snapshotare supported directly. Single-zone countries resolve to a canonical city, while multi-zone countries return explicit ambiguity with candidate timezones.
API Keys
Create and manage developer keys from a Google-authenticated findtime.io account. This keeps API access tied to a real developer identity and gives you one place to issue, revoke, and rotate credentials.
- Sign in with Google from the docs top bar.
- Create a key from the docs-styled API Keys console.
- Send it using
Authorization: Bearer YOUR_SECRET_KEYon every API request. - The same key authorizes the Time API, the local MCP package through
FINDTIME_TIME_API_KEY, and the hosted MCP server as a bearer token.
curl --request GET \ --url "https://time-api.findtime.io/time/current?query=Tokyo" \ --header "Authorization: Bearer YOUR_SECRET_KEY"
answer_time_question
/time/answerNatural-language time intelligence for apps and agents. Send the raw user prompt and findtime.io classifies the intent, dispatches to deterministic time behavior, and returns either an answer or structured clarification.
Parameters
querystringRaw natural-language time, timezone, conversion, DST, overlap, scheduling, abbreviation, or IANA question.
userTimezonestringOptionalIANA timezone for the user, used for relative questions like “my time” or “tomorrow”.
localestringOptionalLocale hint such as en-US.
nowstringOptionalISO timestamp for deterministic relative-date handling.
datestringOptionalYYYY-MM-DD date context.
curl --request GET \ --url "https://time-api.findtime.io/time/answer?query=what%20is%20the%20IANA%20timezone%20for%20San%20Francisco%3F" \ --header "Authorization: Bearer YOUR_SECRET_KEY"
{
"shape": "answer_time_question.v1",
"resolved": true,
"status": "ok",
"intent": "iana_timezone_lookup",
"query": "what is the IANA timezone for San Francisco?",
"answer": "The IANA timezone for San Francisco, United States is America/Los_Angeles.",
"toolUsed": "get_current_time",
"confidence": "high",
"needsClarification": false,
"result": {
"shape": "current_time.v2",
"resolved": true,
"location": {
"name": "San Francisco",
"countryName": "United States",
"timezoneIana": "America/Los_Angeles"
},
"timezone": {
"iana": "America/Los_Angeles",
"abbreviation": "PDT",
"utcOffset": "UTC-7"
}
}
}time_snapshot
/time/snapshotStart here when you want one-call time intelligence. It resolves the place, packages timezone and DST truth, includes geo, and can optionally include transition detail so callers make fewer follow-up requests.
Parameters
query or locationsstringSingle location query or pipe-delimited list of locations to resolve.
countryCode or countryCodesstringOptionalISO country hint to improve deterministic resolution. Hints improve ranking and disambiguation but do not turn search-like inputs into strict country filters.
includeTransitionsbooleanOptionalAdds last and next timezone transition detail when you need full DST context.
candidateLimitintegerOptionalPage size for namesake candidates. Default 6, max 50.
candidateOffsetintegerOptionalSkip this many namesake candidates. Follow moreCandidates.resolve or moreCandidates.search for the rest.
curl --request GET \ --url "https://time-api.findtime.io/time/snapshot?locations=Tokyo|New%20York&countryCodes=JP|US&includeTransitions=true" \ --header "Authorization: Bearer YOUR_SECRET_KEY"
{
"shape": "time_snapshot.v2",
"resolved": false,
"ambiguous": true,
"partial": true,
"resolvedCount": 1,
"ambiguousCount": 1,
"notFoundCount": 0,
"locations": [
{
"side": 0,
"status": "resolved",
"query": "Iceland",
"resolutionReason": "country=IS",
"location": {
"name": "Reykjavík",
"countryCode": "IS",
"countryName": "Iceland",
"timezoneIana": "Atlantic/Reykjavik"
},
"timezone": {
"iana": "Atlantic/Reykjavik",
"abbreviation": "GMT",
"utcOffset": "UTC+0"
}
},
{
"side": 1,
"status": "ambiguous",
"resolved": false,
"ambiguous": true,
"query": "Paris",
"candidates": [
{
"type": "city",
"id": "findtime:paris|FR|2988507|Europe/Paris",
"name": "Paris",
"slug": "paris",
"displayName": "Paris",
"label": "Paris, France (Europe/Paris)",
"countryCode": "FR",
"countryName": "France",
"timezoneIana": "Europe/Paris",
"population": 2138551,
"admin1": "11",
"admin1Name": "",
"stateCode": "11",
"geonameId": 2988507,
"coordinates": { "lat": 48.85341, "lon": 2.3488 },
"suggestedId": "findtime:paris|FR|2988507|Europe/Paris",
"suggestedQuery": "Paris, France",
"currentTime": {
"iso": "2026-10-14T14:00:00.000+02:00",
"date": "2026-10-14",
"time24h": "14:00",
"time12h": "2:00 PM",
"weekday": "Wednesday",
"shortDate": "Wed, Oct 14"
},
"abbreviation": "CEST",
"utcOffset": "UTC+2",
"offsetMinutes": 120,
"isDST": true,
"observesDST": true,
"dst": {
"observesDST": true,
"isDSTActiveNow": true,
"currentAbbreviation": "CEST"
}
},
{
"type": "city",
"id": "findtime:paris-us|US|4717560|America/Chicago",
"name": "Paris",
"slug": "paris-us",
"displayName": "Paris",
"label": "Paris, TX (America/Chicago)",
"countryCode": "US",
"countryName": "United States",
"timezoneIana": "America/Chicago",
"population": 24782,
"admin1": "TX",
"admin1Name": "Texas",
"stateCode": "TX",
"geonameId": 4717560,
"coordinates": { "lat": 33.66094, "lon": -95.55551 },
"suggestedId": "findtime:paris-us|US|4717560|America/Chicago",
"suggestedQuery": "Paris, TX",
"currentTime": {
"iso": "2026-10-14T07:00:00.000-05:00",
"date": "2026-10-14",
"time24h": "07:00",
"time12h": "7:00 AM",
"weekday": "Wednesday",
"shortDate": "Wed, Oct 14"
},
"abbreviation": "CDT",
"utcOffset": "UTC-5",
"offsetMinutes": -300,
"isDST": true,
"observesDST": true,
"dst": {
"observesDST": true,
"isDSTActiveNow": true,
"currentAbbreviation": "CDT"
}
}
],
"totalCandidates": 7,
"candidateLimit": 6,
"candidateOffset": 0,
"additionalCandidates": 1,
"additionalCandidatesLabel": "+1 more",
"moreCandidates": {
"candidateLimit": 6,
"candidateOffset": 6,
"resolve": "/resolve?query=Paris&candidateLimit=6&candidateOffset=6",
"current": "/time/current?query=Paris&candidateLimit=6&candidateOffset=6",
"search": "/locations/search?query=Paris&limit=7"
}
}
]
}get_current_time
/time/currentCurrent local time for a single city or timezone with the same packaged location, timezone, currentTime, dst, and geo model used across the API.
Parameters
city or querystringA city name, timezone abbreviation, IANA zone, or other free-form location query. Exact country-name queries resolve directly when there is one canonical zone, and return explicit ambiguity when a country spans multiple zones. Same-named cities in different UTC offsets return status ambiguous with no primary pick.
countryCodestringOptionalISO country hint for duplicate city names like Victoria or San Jose.
candidateLimitintegerOptionalPage size for namesake candidates. Default 6, max 50. Use with candidateOffset or follow moreCandidates.resolve / moreCandidates.search.
candidateOffsetintegerOptionalSkip this many namesake candidates. Copy from moreCandidates.candidateOffset to fetch the rest.
curl --request GET \ --url "https://time-api.findtime.io/time/current?city=Tokyo&countryCode=JP" \ --header "Authorization: Bearer YOUR_SECRET_KEY"
{
"shape": "current_time.v2",
"resolved": true,
"location": {
"name": "Tokyo",
"countryName": "Japan",
"timezoneIana": "Asia/Tokyo"
},
"timezone": {
"abbreviation": "JST",
"longName": "Japan Standard Time",
"utcOffset": "UTC+9"
},
"currentTime": {
"time24h": "22:31",
"time12h": "10:31 PM",
"weekday": "Tuesday"
},
"dst": {
"observesDST": false,
"isDSTActiveNow": false
}
}get_dst_schedule
/timezone/dstDST truth surface: current state, current abbreviation, last transition, next transition, and yearly DST context without guessing.
Parameters
city, query, or timezonestringLocation input or direct IANA timezone.
countryCodestringOptionalISO hint to break city-name ties.
atstringOptionalISO timestamp, for example `2026-01-15T12:00:00Z`, that anchors lastTransition and nextTransition to a specific reference instant.
yearintegerOptionalCalendar year that adds a year-specific transition view with transitions, springTransition, and fallTransition.
curl --request GET \ --url "https://time-api.findtime.io/timezone/dst?timezone=Europe/London&at=2026-01-15T12:00:00Z&year=2026" \ --header "Authorization: Bearer YOUR_SECRET_KEY"
{
"shape": "dst_schedule.v2",
"resolved": true,
"referenceAt": "2026-01-15T12:00:00.000Z",
"location": {
"name": "London",
"countryName": "United Kingdom",
"timezoneIana": "Europe/London"
},
"timezone": {
"abbreviation": "GMT",
"longName": "Greenwich Mean Time",
"utcOffset": "UTC+0"
},
"dst": {
"observesDST": true,
"isDSTActiveNow": false,
"currentAbbreviation": "GMT",
"lastTransition": {
"type": "ends",
"date": "October 26, 2025"
},
"nextTransition": {
"type": "begins",
"date": "March 29, 2026"
},
"year": 2026,
"transitions": [
{
"type": "begins",
"date": "March 29, 2026"
},
{
"type": "ends",
"date": "October 25, 2026"
}
],
"springTransition": {
"type": "begins",
"date": "March 29, 2026"
},
"fallTransition": {
"type": "ends",
"date": "October 25, 2026"
}
}
}convert_time
/time/convertOne-to-one or one-to-many conversion with explicit ambiguity handling. No silent guessing when inputs like CST or Victoria are underspecified.
Parameters
fromstringSource location or timezone.
tostringOne target or pipe-delimited targets.
timestringSource local time to convert. May include a simple human day phrase such as “3pm Tuesday”.
datestringDate for the conversion context. Prefer ISO YYYY-MM-DD; simple human values such as “Thursday” or “tomorrow” are accepted.
curl --request GET \ --url "https://time-api.findtime.io/time/convert?from=New%20York&to=London|Tokyo&toCountryCodes=GB|JP&time=9:00%20AM&date=2026-03-10" \ --header "Authorization: Bearer YOUR_SECRET_KEY"
{
"shape": "convert_time.v2",
"source": {
"location": {
"name": "New York",
"countryName": "United States"
},
"timezone": {
"abbreviation": "EDT"
},
"currentTime": {
"time12h": "9:00 AM"
}
},
"targets": [
{
"location": { "name": "London", "countryName": "United Kingdom" },
"timezone": { "abbreviation": "GMT" },
"currentTime": { "time12h": "1:00 PM" }
},
{
"location": { "name": "Tokyo", "countryName": "Japan" },
"timezone": { "abbreviation": "JST" },
"currentTime": { "time12h": "10:00 PM" }
}
]
}get_overlap_hours
/time/overlapShared business-hours overlap across locations. This is where findtime.io moves from utility to workflow intelligence.
Parameters
locationsstringPipe-delimited list of cities or timezones.
countryCodesstringOptionalPipe-delimited ISO hints aligned with the locations list.
datestringDate used to compute the overlap window. Prefer ISO YYYY-MM-DD; simple human values such as “Thursday” or “tomorrow” are accepted and resolved relative to the first location timezone.
curl --request GET \ --url "https://time-api.findtime.io/time/overlap?locations=New%20York|London&countryCodes=US|GB&date=2026-03-10" \ --header "Authorization: Bearer YOUR_SECRET_KEY"
{
"shape": "overlap_hours.v2",
"resolved": true,
"overlap": {
"hasOverlap": true,
"minutes": 300,
"window": {
"start": "2026-03-10T13:00:00.000Z",
"end": "2026-03-10T18:00:00.000Z"
}
}
}find_meeting_time
/meeting/findRanked meeting suggestions across multiple cities with a deep link back into findtime.io. This is one of the strongest parity++ surfaces in the platform.
Parameters
locationsstringPipe-delimited list of locations to include in the meeting search.
countryCodesstringOptionalPipe-delimited ISO hints aligned with the locations list.
datestringOptionalDate to anchor the meeting search. Prefer ISO YYYY-MM-DD; simple human values such as “Thursday” or “tomorrow” are accepted and resolved relative to the first location timezone.
durationMinutesintegerOptionalOptional meeting length. Only 30, 45, or 60 are written onto the planner link as aiDuration.
refstringOptionalPlanner ref query param. MCP sends mcp-bot.
curl --request GET \ --url "https://time-api.findtime.io/meeting/find?locations=New%20York|Sydney|Tokyo&countryCodes=US|AU|JP&date=2026-09-29&ref=mcp-bot" \ --header "Authorization: Bearer YOUR_SECRET_KEY"
{
"resolved": true,
"ambiguous": false,
"source": "deterministic",
"locations": [
{
"query": "New York",
"displayLabel": "New York City",
"resolutionReason": "us_state=NY",
"match": {
"type": "city",
"id": "findtime:new-york-city|US|America/New_York",
"name": "New York City",
"slug": "new-york-city",
"countryCode": "US",
"countryName": "United States",
"timezoneIana": "America/New_York",
"population": 8804190
},
"timezoneIana": "America/New_York"
},
{
"query": "Sydney",
"displayLabel": "Sydney",
"resolutionReason": "countryCode=AU",
"match": {
"type": "city",
"id": "findtime:sydney|AU|Australia/Sydney",
"name": "Sydney",
"slug": "sydney",
"countryCode": "AU",
"countryName": "Australia",
"timezoneIana": "Australia/Sydney",
"population": 5557233
},
"timezoneIana": "Australia/Sydney"
},
{
"query": "Tokyo",
"displayLabel": "Tokyo",
"resolutionReason": null,
"match": {
"type": "city",
"id": "findtime:tokyo|JP|Asia/Tokyo",
"name": "Tokyo",
"slug": "tokyo",
"countryCode": "JP",
"countryName": "Japan",
"timezoneIana": "Asia/Tokyo",
"population": 9733276
},
"timezoneIana": "Asia/Tokyo"
}
],
"date": "2026-09-29",
"input": {
"date": "2026-09-29"
},
"options": [
{
"rank": 1,
"badnessScore": 2,
"qualityLabel": "Excellent",
"lines": [
{
"city": "New York City",
"time": "Tue 6:00 PM",
"date": "2026-09-29",
"dateTime": "Tue Sep 29, 6:00 PM"
},
{
"city": "Tokyo",
"time": "Wed 7:00 AM",
"date": "2026-09-30",
"dateTime": "Wed Sep 30, 7:00 AM"
},
{
"city": "Sydney",
"time": "Wed 8:00 AM",
"date": "2026-09-30",
"dateTime": "Wed Sep 30, 8:00 AM"
}
],
"startUtc": "2026-09-29T22:00:00.000Z"
},
{
"rank": 2,
"badnessScore": 2,
"qualityLabel": "Excellent",
"lines": [
{
"city": "New York City",
"time": "Tue 7:00 PM",
"date": "2026-09-29",
"dateTime": "Tue Sep 29, 7:00 PM"
},
{
"city": "Tokyo",
"time": "Wed 8:00 AM",
"date": "2026-09-30",
"dateTime": "Wed Sep 30, 8:00 AM"
},
{
"city": "Sydney",
"time": "Wed 9:00 AM",
"date": "2026-09-30",
"dateTime": "Wed Sep 30, 9:00 AM"
}
],
"startUtc": "2026-09-29T23:00:00.000Z"
},
{
"rank": 3,
"badnessScore": 2,
"qualityLabel": "Excellent",
"lines": [
{
"city": "New York City",
"time": "Wed 6:00 PM",
"date": "2026-09-30",
"dateTime": "Wed Sep 30, 6:00 PM"
},
{
"city": "Tokyo",
"time": "Thu 7:00 AM",
"date": "2026-10-01",
"dateTime": "Thu Oct 1, 7:00 AM"
},
{
"city": "Sydney",
"time": "Thu 8:00 AM",
"date": "2026-10-01",
"dateTime": "Thu Oct 1, 8:00 AM"
}
],
"startUtc": "2026-09-30T22:00:00.000Z"
}
],
"plannerUrl": "https://findtime.io/?aiCities=New%20York%20City%7CAmerica%2FNew_York%2CSydney%7CAustralia%2FSydney%2CTokyo%7CAsia%2FTokyo&aiTime=Tue%206%3A00%20PM&aiDate=2026-09-29&aiSlots=2026-09-29T22%3A00%3A00.000Z%7C2026-09-29T23%3A00%3A00.000Z%7C2026-09-30T22%3A00%3A00.000Z&ref=mcp-bot",
"shareText": "Meeting times
1. New York City Tue Sep 29, 6:00 PM · Tokyo Wed Sep 30, 7:00 AM · Sydney Wed Sep 30, 8:00 AM
2. New York City Tue Sep 29, 7:00 PM · Tokyo Wed Sep 30, 8:00 AM · Sydney Wed Sep 30, 9:00 AM
3. New York City Wed Sep 30, 6:00 PM · Tokyo Thu Oct 1, 7:00 AM · Sydney Thu Oct 1, 8:00 AM
https://findtime.io/?aiCities=New%20York%20City%7CAmerica%2FNew_York%2CSydney%7CAustralia%2FSydney%2CTokyo%7CAsia%2FTokyo&aiTime=Tue%206%3A00%20PM&aiDate=2026-09-29&aiSlots=2026-09-29T22%3A00%3A00.000Z%7C2026-09-29T23%3A00%3A00.000Z%7C2026-09-30T22%3A00%3A00.000Z&ref=mcp-bot",
"presentation": {
"plainText": "Meeting times
1. New York City Tue Sep 29, 6:00 PM · Tokyo Wed Sep 30, 7:00 AM · Sydney Wed Sep 30, 8:00 AM
2. New York City Tue Sep 29, 7:00 PM · Tokyo Wed Sep 30, 8:00 AM · Sydney Wed Sep 30, 9:00 AM
3. New York City Wed Sep 30, 6:00 PM · Tokyo Thu Oct 1, 7:00 AM · Sydney Thu Oct 1, 8:00 AM
https://findtime.io/?aiCities=New%20York%20City%7CAmerica%2FNew_York%2CSydney%7CAustralia%2FSydney%2CTokyo%7CAsia%2FTokyo&aiTime=Tue%206%3A00%20PM&aiDate=2026-09-29&aiSlots=2026-09-29T22%3A00%3A00.000Z%7C2026-09-29T23%3A00%3A00.000Z%7C2026-09-30T22%3A00%3A00.000Z&ref=mcp-bot"
}
}check_proposed_time
/meeting/checkJudge a proposed meeting instant for each city. Returns verdicts, alternatives, shareText, and a planner URL with up to three UTC aiSlots.
Parameters
locationsstringPipe-delimited cities or timezones.
countryCodesstringOptionalPipe-delimited ISO hints aligned with locations.
startstringISO instant with offset, or a floating local time such as 2026-09-29T09:00.
homestringOptionalIANA timezone for a floating start, such as America/Los_Angeles.
datestringOptionalYYYY-MM-DD when start is only a clock time.
durationMinutesintegerOptionalOptional. Only 30, 45, or 60 are written onto the planner link.
workStartintegerOptionalFirst in-hours local hour. Default 9.
workEndintegerOptionalLast in-hours local hour, inclusive. Default 18.
curl --request GET \ --url "https://time-api.findtime.io/meeting/check?locations=San%20Francisco|London|Tokyo&countryCodes=US|GB|JP&start=2026-09-29T09:00&home=America/Los_Angeles" \ --header "Authorization: Bearer YOUR_SECRET_KEY"
{
"resolved": true,
"startUtc": "2026-09-29T16:00:00.000Z",
"overall": "bad",
"workStart": 9,
"workEnd": 18,
"verdicts": [
{
"city": "San Francisco",
"timezone": "America/Los_Angeles",
"local": "Tue 9:00 AM",
"zoneLabel": "PDT | UTC-7",
"verdict": "ok",
"weekend": false,
"hour": 9
},
{
"city": "London",
"timezone": "Europe/London",
"local": "Tue 5:00 PM",
"zoneLabel": "BST | UTC+1",
"verdict": "ok",
"weekend": false,
"hour": 17
},
{
"city": "Tokyo",
"timezone": "Asia/Tokyo",
"local": "Wed 1:00 AM",
"zoneLabel": "JST | UTC+9",
"verdict": "sleep",
"weekend": false,
"hour": 1
}
],
"alternatives": [
{
"rank": 1,
"badnessScore": 6,
"qualityLabel": "Acceptable",
"lines": [
{
"city": "San Francisco",
"time": "Tue 1:00 PM"
},
{
"city": "London",
"time": "Tue 9:00 PM"
},
{
"city": "Tokyo",
"time": "Wed 5:00 AM"
}
],
"startUtc": "2026-09-29T20:00:00.000Z"
},
{
"rank": 2,
"badnessScore": 8,
"qualityLabel": "Late hours",
"lines": [
{
"city": "San Francisco",
"time": "Tue 6:00 AM"
},
{
"city": "London",
"time": "Tue 2:00 PM"
},
{
"city": "Tokyo",
"time": "Tue 10:00 PM"
}
],
"startUtc": "2026-09-29T13:00:00.000Z"
},
{
"rank": 3,
"badnessScore": 8,
"qualityLabel": "Late hours",
"lines": [
{
"city": "San Francisco",
"time": "Tue 12:00 PM"
},
{
"city": "London",
"time": "Tue 8:00 PM"
},
{
"city": "Tokyo",
"time": "Wed 4:00 AM"
}
],
"startUtc": "2026-09-29T19:00:00.000Z"
}
],
"plannerUrl": "https://findtime.io/?aiCities=San%20Francisco%7CAmerica%2FLos_Angeles%2CLondon%7CEurope%2FLondon%2CTokyo%7CAsia%2FTokyo&aiTime=Tue%201%3A00%20PM&aiSlots=2026-09-29T20%3A00%3A00.000Z%7C2026-09-29T13%3A00%3A00.000Z%7C2026-09-29T19%3A00%3A00.000Z&ref=mcp-bot",
"shareText": "Proposed time is rough
San Francisco Tue 9:00 AM PDT | UTC-7 (ok)
London Tue 5:00 PM BST | UTC+1 (ok)
Tokyo Wed 1:00 AM JST | UTC+9 (sleep)
Alt 1. San Francisco Tue 1:00 PM PDT · London Tue 9:00 PM BST · Tokyo Wed 5:00 AM JST
Alt 2. San Francisco Tue 6:00 AM PDT · London Tue 2:00 PM BST · Tokyo Tue 10:00 PM JST
Alt 3. San Francisco Tue 12:00 PM PDT · London Tue 8:00 PM BST · Tokyo Wed 4:00 AM JST
https://findtime.io/?aiCities=San%20Francisco%7CAmerica%2FLos_Angeles%2CLondon%7CEurope%2FLondon%2CTokyo%7CAsia%2FTokyo&aiTime=Tue%201%3A00%20PM&aiSlots=2026-09-29T20%3A00%3A00.000Z%7C2026-09-29T13%3A00%3A00.000Z%7C2026-09-29T19%3A00%3A00.000Z&ref=mcp-bot",
"presentation": {
"plainText": "Proposed time is rough
San Francisco Tue 9:00 AM PDT | UTC-7 (ok)
London Tue 5:00 PM BST | UTC+1 (ok)
Tokyo Wed 1:00 AM JST | UTC+9 (sleep)
Alt 1. San Francisco Tue 1:00 PM PDT · London Tue 9:00 PM BST · Tokyo Wed 5:00 AM JST
Alt 2. San Francisco Tue 6:00 AM PDT · London Tue 2:00 PM BST · Tokyo Tue 10:00 PM JST
Alt 3. San Francisco Tue 12:00 PM PDT · London Tue 8:00 PM BST · Tokyo Wed 4:00 AM JST
https://findtime.io/?aiCities=San%20Francisco%7CAmerica%2FLos_Angeles%2CLondon%7CEurope%2FLondon%2CTokyo%7CAsia%2FTokyo&aiTime=Tue%201%3A00%20PM&aiSlots=2026-09-29T20%3A00%3A00.000Z%7C2026-09-29T13%3A00%3A00.000Z%7C2026-09-29T19%3A00%3A00.000Z&ref=mcp-bot"
}
}are_they_awake
/meeting/awakeSay whether people in other cities are in work, awake, or sleep at one moment. Use for ping timing before you interrupt someone in another timezone.
Parameters
theirCitystringOptionalOne city or timezone to judge.
theirCitiesstringOptionalPipe-delimited cities or timezones to judge.
myTimestringOptionalISO instant or floating local time in myTimezone. Defaults to now.
myTimezonestringOptionalIANA timezone for the caller, such as America/Los_Angeles.
myCitystringOptionalCaller city when myTimezone is omitted.
datestringOptionalYYYY-MM-DD when myTime is only a clock time.
durationMinutesintegerOptionalOptional. Only 30, 45, or 60 are written onto the planner link.
workStartintegerOptionalFirst in-hours local hour. Default 9.
workEndintegerOptionalLast in-hours local hour, inclusive. Default 18.
curl --request GET \ --url "https://time-api.findtime.io/meeting/awake?myTime=2026-09-29T15:00&myTimezone=America/Los_Angeles&theirCity=Bangalore" \ --header "Authorization: Bearer YOUR_SECRET_KEY"
{
"resolved": true,
"startUtc": "2026-09-29T22:00:00.000Z",
"rows": [
{
"role": "me",
"city": "America/Los_Angeles",
"timezone": "America/Los_Angeles",
"local": "Tue 3:00 PM",
"verdict": "ok",
"label": "work",
"weekend": false,
"hour": 15
},
{
"role": "them",
"city": "Bengaluru",
"timezone": "Asia/Kolkata",
"local": "Wed 3:30 AM",
"verdict": "sleep",
"label": "sleep",
"weekend": false,
"hour": 3
}
],
"needsRescue": true,
"alternatives": [
{
"rank": 1,
"badnessScore": 2,
"qualityLabel": "Excellent",
"lines": [
{
"city": "America/Los_Angeles",
"time": "Tue 7:00 AM"
},
{
"city": "Bengaluru",
"time": "Tue 7:30 PM"
}
],
"startUtc": "2026-09-29T14:00:00.000Z"
},
{
"rank": 2,
"badnessScore": 2,
"qualityLabel": "Excellent",
"lines": [
{
"city": "America/Los_Angeles",
"time": "Tue 7:00 PM"
},
{
"city": "Bengaluru",
"time": "Wed 7:30 AM"
}
],
"startUtc": "2026-09-30T02:00:00.000Z"
},
{
"rank": 3,
"badnessScore": 4,
"qualityLabel": "Good",
"lines": [
{
"city": "America/Los_Angeles",
"time": "Tue 6:00 AM"
},
{
"city": "Bengaluru",
"time": "Tue 6:30 PM"
}
],
"startUtc": "2026-09-29T13:00:00.000Z"
}
],
"plannerUrl": "https://findtime.io/?aiCities=America%2FLos_Angeles%7CAmerica%2FLos_Angeles%2CBengaluru%7CAsia%2FKolkata&aiTime=Tue%207%3A00%20AM&aiSlots=2026-09-29T14%3A00%3A00.000Z%7C2026-09-30T02%3A00%3A00.000Z%7C2026-09-29T13%3A00%3A00.000Z&ref=mcp-bot",
"shareText": "Not a good ping
America/Los_Angeles Tue 3:00 PM (work)
Bengaluru Wed 3:30 AM (sleep)
Better 1. America/Los_Angeles Tue 7:00 AM · Bengaluru Tue 7:30 PM
Better 2. America/Los_Angeles Tue 7:00 PM · Bengaluru Wed 7:30 AM
Better 3. America/Los_Angeles Tue 6:00 AM · Bengaluru Tue 6:30 PM
https://findtime.io/?aiCities=America%2FLos_Angeles%7CAmerica%2FLos_Angeles%2CBengaluru%7CAsia%2FKolkata&aiTime=Tue%207%3A00%20AM&aiSlots=2026-09-29T14%3A00%3A00.000Z%7C2026-09-30T02%3A00%3A00.000Z%7C2026-09-29T13%3A00%3A00.000Z&ref=mcp-bot",
"presentation": {
"plainText": "Not a good ping
America/Los_Angeles Tue 3:00 PM (work)
Bengaluru Wed 3:30 AM (sleep)
Better 1. America/Los_Angeles Tue 7:00 AM · Bengaluru Tue 7:30 PM
Better 2. America/Los_Angeles Tue 7:00 PM · Bengaluru Wed 7:30 AM
Better 3. America/Los_Angeles Tue 6:00 AM · Bengaluru Tue 6:30 PM
https://findtime.io/?aiCities=America%2FLos_Angeles%7CAmerica%2FLos_Angeles%2CBengaluru%7CAsia%2FKolkata&aiTime=Tue%207%3A00%20AM&aiSlots=2026-09-29T14%3A00%3A00.000Z%7C2026-09-30T02%3A00%3A00.000Z%7C2026-09-29T13%3A00%3A00.000Z&ref=mcp-bot"
}
}rank_recurring_slot
/meeting/recurringScore who a weekly wall-clock time punishes across the next few weeks, including a daylight-saving week when one falls in the scan window. Returns per-city pain, a kinder slot, shareText, and plannerUrl.
Parameters
locationsstringPipe-delimited cities or timezones.
countryCodesstringOptionalPipe-delimited ISO hints aligned with locations.
weekdaystringDay name such as Mon or Monday.
timestringClock time such as 9am or 09:00 in the home timezone.
homestringIANA timezone of the recurring clock, such as America/Los_Angeles.
occurrencesintegerOptionalWeeks to score before adding a DST week. Default 4. Max 8.
nowstringOptionalISO instant used as today when choosing the next weekday.
durationMinutesintegerOptionalOptional. Only 30, 45, or 60 are written onto the planner link.
workStartintegerOptionalFirst in-hours local hour. Default 9.
workEndintegerOptionalLast in-hours local hour, inclusive. Default 18.
curl --request GET \ --url "https://time-api.findtime.io/meeting/recurring?locations=San%20Francisco|London|Bangalore&countryCodes=US|GB|IN&weekday=Mon&time=9am&home=America/Los_Angeles&now=2026-09-29T16:00:00.000Z" \ --header "Authorization: Bearer YOUR_SECRET_KEY"
{
"resolved": true,
"weekday": "Mon",
"home": "America/Los_Angeles",
"time": "09:00",
"summary": [
{
"city": "San Francisco",
"timezone": "America/Los_Angeles",
"pain": 0,
"verdict": "ok",
"weekend": false,
"local": "Mon 9:00 AM"
},
{
"city": "London",
"timezone": "Europe/London",
"pain": 0,
"verdict": "ok",
"weekend": false,
"local": "Mon 5:00 PM"
},
{
"city": "Bengaluru",
"timezone": "Asia/Kolkata",
"pain": 6,
"verdict": "late",
"weekend": false,
"local": "Mon 9:30 PM"
}
],
"occurrences": [
{
"week": 0,
"date": "2026-10-05",
"startUtc": "2026-10-05T16:00:00.000Z",
"cities": [
{
"city": "San Francisco",
"timezone": "America/Los_Angeles",
"local": "Mon 9:00 AM",
"verdict": "ok",
"weekend": false,
"pain": 0,
"offsetMinutes": -420
},
{
"city": "London",
"timezone": "Europe/London",
"local": "Mon 5:00 PM",
"verdict": "ok",
"weekend": false,
"pain": 0,
"offsetMinutes": 60
},
{
"city": "Bengaluru",
"timezone": "Asia/Kolkata",
"local": "Mon 9:30 PM",
"verdict": "late",
"weekend": false,
"pain": 6,
"offsetMinutes": 330
}
]
},
{
"week": 1,
"date": "2026-10-12",
"startUtc": "2026-10-12T16:00:00.000Z",
"cities": [
{
"city": "San Francisco",
"timezone": "America/Los_Angeles",
"local": "Mon 9:00 AM",
"verdict": "ok",
"weekend": false,
"pain": 0,
"offsetMinutes": -420
},
{
"city": "London",
"timezone": "Europe/London",
"local": "Mon 5:00 PM",
"verdict": "ok",
"weekend": false,
"pain": 0,
"offsetMinutes": 60
},
{
"city": "Bengaluru",
"timezone": "Asia/Kolkata",
"local": "Mon 9:30 PM",
"verdict": "late",
"weekend": false,
"pain": 6,
"offsetMinutes": 330
}
]
},
{
"week": 2,
"date": "2026-10-19",
"startUtc": "2026-10-19T16:00:00.000Z",
"cities": [
{
"city": "San Francisco",
"timezone": "America/Los_Angeles",
"local": "Mon 9:00 AM",
"verdict": "ok",
"weekend": false,
"pain": 0,
"offsetMinutes": -420
},
{
"city": "London",
"timezone": "Europe/London",
"local": "Mon 5:00 PM",
"verdict": "ok",
"weekend": false,
"pain": 0,
"offsetMinutes": 60
},
{
"city": "Bengaluru",
"timezone": "Asia/Kolkata",
"local": "Mon 9:30 PM",
"verdict": "late",
"weekend": false,
"pain": 6,
"offsetMinutes": 330
}
]
},
{
"week": 3,
"date": "2026-10-26",
"startUtc": "2026-10-26T16:00:00.000Z",
"cities": [
{
"city": "San Francisco",
"timezone": "America/Los_Angeles",
"local": "Mon 9:00 AM",
"verdict": "ok",
"weekend": false,
"pain": 0,
"offsetMinutes": -420
},
{
"city": "London",
"timezone": "Europe/London",
"local": "Mon 4:00 PM",
"verdict": "ok",
"weekend": false,
"pain": 0,
"offsetMinutes": 0
},
{
"city": "Bengaluru",
"timezone": "Asia/Kolkata",
"local": "Mon 9:30 PM",
"verdict": "late",
"weekend": false,
"pain": 6,
"offsetMinutes": 330
}
]
}
],
"dstDate": "2026-10-26",
"alternate": {
"rank": 1,
"badnessScore": 2,
"qualityLabel": "Excellent",
"lines": [
{
"city": "San Francisco",
"time": "Mon 7:00 AM"
},
{
"city": "London",
"time": "Mon 3:00 PM"
},
{
"city": "Bengaluru",
"time": "Mon 7:30 PM"
}
],
"startUtc": "2026-10-05T14:00:00.000Z"
},
"plannerUrl": "https://findtime.io/?aiCities=San%20Francisco%7CAmerica%2FLos_Angeles%2CLondon%7CEurope%2FLondon%2CBengaluru%7CAsia%2FKolkata&aiTime=Mon%207%3A00%20AM&aiSlots=2026-10-05T14%3A00%3A00.000Z%7C2026-10-05T13%3A00%3A00.000Z%7C2026-10-05T15%3A00%3A00.000Z&ref=mcp-bot",
"shareText": "Standup pain · Mon 09:00 America/Los_Angeles
San Francisco Mon 9:00 AM (ok, pain 0)
London Mon 5:00 PM (ok, pain 0)
Bengaluru Mon 9:30 PM (late, pain 6)
DST week 2026-10-26: San Francisco Mon 9:00 AM · London Mon 4:00 PM · Bengaluru Mon 9:30 PM
Kinder slot. San Francisco Mon 7:00 AM · London Mon 3:00 PM · Bengaluru Mon 7:30 PM
https://findtime.io/?aiCities=San%20Francisco%7CAmerica%2FLos_Angeles%2CLondon%7CEurope%2FLondon%2CBengaluru%7CAsia%2FKolkata&aiTime=Mon%207%3A00%20AM&aiSlots=2026-10-05T14%3A00%3A00.000Z%7C2026-10-05T13%3A00%3A00.000Z%7C2026-10-05T15%3A00%3A00.000Z&ref=mcp-bot",
"presentation": {
"plainText": "Standup pain · Mon 09:00 America/Los_Angeles
San Francisco Mon 9:00 AM (ok, pain 0)
London Mon 5:00 PM (ok, pain 0)
Bengaluru Mon 9:30 PM (late, pain 6)
DST week 2026-10-26: San Francisco Mon 9:00 AM · London Mon 4:00 PM · Bengaluru Mon 9:30 PM
Kinder slot. San Francisco Mon 7:00 AM · London Mon 3:00 PM · Bengaluru Mon 7:30 PM
https://findtime.io/?aiCities=San%20Francisco%7CAmerica%2FLos_Angeles%2CLondon%7CEurope%2FLondon%2CBengaluru%7CAsia%2FKolkata&aiTime=Mon%207%3A00%20AM&aiSlots=2026-10-05T14%3A00%3A00.000Z%7C2026-10-05T13%3A00%3A00.000Z%7C2026-10-05T15%3A00%3A00.000Z&ref=mcp-bot"
}
}team
/meeting/teamHomepage planner Saved groups and a hosted agent's teams are one record when both use the same Google account. list_teams returns those names. Pass that exact spelling as teamId to load the group's cities when the call has no locations. save_team writes the full city list. A city may be a plain name or City|IANA. save_team, rename_team and delete_team need the meetings:plan scope. list_teams and get_team need time:read. A deleted group stays deleted. Marketing and marketing are two groups. This public route does not read the account. An API key gets teams_not_persisted. Pass locations on each meeting call in that case.
Parameters
teamIdstringOptionalExact homepage group name. This public route still returns the stub. A signed-in hosted agent loads that group.
curl --request GET \ --url "https://time-api.findtime.io/meeting/team?teamId=standup" \ --header "Authorization: Bearer YOUR_SECRET_KEY"
{
"stub": true,
"error": "teams_not_persisted",
"teamId": "standup",
"message": "No-auth MCP does not store teams. Pass locations on each call. Account storage is a later batch."
}locations/search + locations/:id
/locations/search and /locations/:idSearch locations first, then hydrate exact locations by stable findtime: id. Current ids are findtime:slug|CC|geonameId-or-state|TZ. Older findtime:slug|CC|TZ ids such as findtime:tokyo|JP|Asia/Tokyo still resolve to the original city. This keeps external callers on a clean, deterministic location model for findtime.io.
Parameters
querystringSearch term such as Victoria, Sao Paulo, or Tokyo.
countryCodestringOptionalISO country hint for ranking and disambiguation. This is a hint, not an exclusive country filter.
limitnumberOptionalMaximum number of search results to return. Use this (or candidateLimit / candidateOffset on /resolve and /time/current) when moreCandidates says namesakes were capped.
candidateLimitintegerOptionalPage size for exact namesake matches on this query. Default 6, max 50.
candidateOffsetintegerOptionalSkip this many namesake candidates. Copy from moreCandidates.candidateOffset.
curl --request GET \ --url "https://time-api.findtime.io/locations/search?query=Victoria&countryCode=CA&limit=3" \ --header "Authorization: Bearer YOUR_SECRET_KEY"
{
"shape": "locations_search.v2",
"results": [
{
"id": "findtime:victoria|CA|America/Vancouver",
"name": "Victoria",
"countryName": "Canada",
"timezoneIana": "America/Vancouver",
"population": 85792
}
]
}Booking API
Guests' agents and hosts' agents can find open times, request a booking and manage requests on findtime.io. The routes live on the booking server at https://api.findtime.io and are the same ones the hosted MCP booking tools call. A guest's agent can only request a time. The host approves or declines every request.
For Claude (Settings → Connectors, custom connector named findtime.io at https://mcp.findtime.io/mcp) and Cursor setup, the host robot control, what happens after a request, a sample prompt and troubleshooting, start at Set up in Claude on the MCP docs.
- After a host publishes their page, they turn agent booking on from the Booking Hours tab in Simple mode: the robot icon next to pause and lock. Off it is labeled Let AI agents request times; on it is AI agent requests on. A missing, private or agent-off host gets one uniform 404
host_not_found. - Reading a profile and open times needs no sign-in. Requests, reschedule and every host route need the signed-in findtime account behind the call. Status, history and cancel take the guest's
guestTrackingTokenorguestHistoryTokeninstead. The hosted MCP passes that identity to the booking server, so use the MCP tools for writes. - Scopes:
booking:requestfor a guest's agent andbooking:hostfor a host's agent. Custom clients request those scopes by name. - Every write takes
confirm. Withoutconfirm: truethe answer is a read-back and nothing changes. Retryrequest_bookingwith the sameidempotencyKey. - Host routes act only on requests whose
hostUidis the signed-in host. Older requests without it stay in the findtime inbox and are counted inolderRequests.
Parameter lists below are the main ones. The MCP tool schemas are authoritative for the rest, such as passcode, invite, meeting type, exact start, subject and notes.
Guest routes
| Method | Path | Auth | What it does |
|---|---|---|---|
| GET | /api/booking/agent/hosts/:handle | None | Host profile: name, zone, meeting lengths, one meeting type (labeled Meeting), minimum notice, passcode flag. |
| POST | /api/booking/agent/hosts/:handle/slots | None | Numbered open times as optionIds, in the guest's zone and the host's. Options last about 15 minutes. |
| POST | /api/booking/agent/requests | booking:request | Request one option. Takes handle, optionId, guestName, guestZone, idempotencyKey, confirm. |
| GET | /api/booking/agent/requests/:requestId?token= | Tracking token | One request: pending, confirmed, declined, cancelled_by_guest or cancelled_by_host. |
| GET | /api/booking/agent/guest-requests?guestHistoryToken= | History token | Every request the guest sent to one host. |
| POST | /api/booking/agent/requests/:requestId/cancel | Tracking or history token | Cancel a pending request or an approved meeting. Needs confirm: true. |
| POST | /api/booking/agent/requests/:requestId/reschedule | booking:request | Move a pending request to a new optionId, plus the guest's guestTrackingToken or guestHistoryToken. An approved meeting can't be moved by an agent yet. |
Host routes
| Method | Path | Auth | What it does |
|---|---|---|---|
| GET | /api/booking/agent/host/page | booking:host | The host's page: link, lengths, weekly hours, paused or private, passcode, agent switch, free meetings used and left, active invite links. |
| PUT | /api/booking/agent/host/page | booking:host | Change lengths, weekly hours, pause, or the agent switch. Read-back first, then confirm: true. |
| GET | /api/booking/agent/host/requests?status=&from=&to= | booking:host | The host's inbox with lifecycleVersion and allowed actions. olderRequests counts rows only visible in findtime. |
| POST | /api/booking/agent/host/requests/:requestId/approve | booking:host | Approve. Returns needs_calendar_connect, needs_payment, needs_sync or conflict when it can't finish. |
| POST | /api/booking/agent/host/requests/:requestId/decline | booking:host | Decline, with an optional reason. |
| POST | /api/booking/agent/host/requests/:requestId/cancel | booking:host | Cancel a request or an approved meeting. A stale lifecycleVersion returns conflict. |
| POST | /api/booking/agent/host/invite-links | booking:host | Make a personal link for one guest. findtime doesn't send it. |
| POST | /api/booking/agent/host/invite-links/:linkId/revoke | booking:host | Stop a personal link from working. |
Result statuses
Every result has a status: ok, needs_clarification, no_match, existing_request, needs_confirmation, needs_sign_in, needs_payment, needs_calendar_connect, needs_sync, conflict, temporarily_unavailable, invalid_input, rate_limited or error. no_match carries a reason such as host_not_found, host_busy_in_window, outside_booking_window, duration_not_offered, host_not_taking_requests, option_expired or slot_taken.
Request lifecycle statuses are pending, confirmed, declined, cancelled_by_guest and cancelled_by_host. Past the free meetings, approving returns needs_payment with a findtime link to the one-time $4.99 unlock. An agent never pays and never connects Google Calendar.
API Quick Reference
- Production base URL:
https://time-api.findtime.io - Natural-language agent call:
/time/answer - Flagship call:
/time/snapshot - Use
/locations/searchfirst when you want deterministic location resolution, then store the returnedfindtime:id. Current ids include geonameId or state; olderslug|CC|TZids still hydrate. - Every endpoint expects
Authorization: Bearer YOUR_SECRET_KEY. - Hosted MCP is
POST https://mcp.findtime.io/mcpwith OAuth 2.1 and PKCE, and it accepts bearer API keys. /time/overlapreturns the shared overlap window across locations./meeting/findreturns ranked meeting suggestions withshareTextand a planner URL./meeting/check,/meeting/awake, and/meeting/recurringreturn paste-ready meeting intelligence for proposed times, ping timing, and recurring standups./meeting/teamnever stores a group; it answersteams_not_persisted. Saved groups live on the hosted MCP server, signed in with Google.
| Surface | Best for | Why it matters |
|---|---|---|
| answer_time_question | Raw user prompts | Classifies time questions, resolves relative dates like tomorrow or next Friday, and returns structured clarification for ambiguity. |
| time_snapshot | Default integration | One-call packaged time intelligence with fewer follow-up requests. |
| get_overlap_hours | Scheduling workflows | Turns time data into useful workflow intelligence. |
| find_meeting_time | Agents and teams | Returns ranked meeting options across cities with shareText and a planner URL. |
| check_proposed_time | Proposed slots | Verdicts per city plus alternatives when the proposed instant is rough. |
| are_they_awake | Ping timing | Work, awake, or sleep labels for other cities at your moment. |
| rank_recurring_slot | Weekly standups | Per-city pain, daylight-saving week, and a kinder recurring slot. |
| team | Saved teams | Homepage Saved groups and a hosted agent on the same Google account share one list. Copy the exact name from list_teams. save_team writes the full city list, as a plain name or City|IANA. save_team, rename_team and delete_team need meetings:plan. A deleted group stays deleted. An API key gets teams_not_persisted. |