API

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

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.

What to expect:
  • Every API request uses Authorization: Bearer YOUR_SECRET_KEY.
  • All current endpoints are GET requests.
  • Use /time/answer when you want findtime.io to 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.
request
curl --request GET \
  --url "https://time-api.findtime.io/time/snapshot?query=Tokyo&countryCode=JP&includeTransitions=true" \
  --header "Authorization: Bearer YOUR_SECRET_KEY"
sample response
{
  "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"
      }
    }
  ]
}
API

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.

API

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.

How to read the contract:
  • resolved: true means the request mapped to a canonical location or timezone and the payload can be used directly.
  • ambiguous: true with status: "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 with candidateLimit / candidateOffset or follow moreCandidates.
  • /time/answer is the natural-language agent endpoint. It returns intent, 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/snapshot can return partial batch success. Inspect each location row’s status instead of assuming the entire batch resolved or failed together.
  • notFound or HTTP 404 means the API could not resolve the input with enough confidence. Start with /locations/search if you need a deterministic retry path.
  • countryCode on /locations/search is 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 suggestedQuery and suggestedId so apps and agents can retry with either a human-readable city-country form like Paris, France or a stable findtime: id.
  • Abbreviations such as IST, CST, and BST are often ambiguous. Pair them with a country or region, or use /time/answer or /locations/search to get structured clarification.
  • Country-name queries for /time/current and /time/snapshot are supported directly. Single-zone countries resolve to a canonical city, while multi-zone countries return explicit ambiguity with candidate timezones.
API

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.

How it works:
  • 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_KEY on 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.
request
curl --request GET \
  --url "https://time-api.findtime.io/time/current?query=Tokyo" \
  --header "Authorization: Bearer YOUR_SECRET_KEY"
Agent endpoint

answer_time_question

GET/time/answer

Natural-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.

Use this as the default entry point for natural-language prompts like “3pm PST to London”, “convert 3pm next Tuesday in New York to London”, “working hours overlap for SF, Berlin, and Tokyo”, or “what does CST mean?”. This is the right endpoint for messy relative-date prompts such as “tomorrow”, “next Friday”, or “this weekend”. If your integration already knows the intent and has structured parameters, use the narrower endpoint directly; /time/convert can resolve simple time strings like “3pm Tuesday”, and overlap or meeting endpoints can resolve simple date strings like “Thursday”.

Parameters

querystring

Raw natural-language time, timezone, conversion, DST, overlap, scheduling, abbreviation, or IANA question.

userTimezonestringOptional

IANA timezone for the user, used for relative questions like “my time” or “tomorrow”.

localestringOptional

Locale hint such as en-US.

nowstringOptional

ISO timestamp for deterministic relative-date handling.

datestringOptional

YYYY-MM-DD date context.

request
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"
response
{
  "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"
    }
  }
}
Flagship endpoint

time_snapshot

GET/time/snapshot

Start 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.

Use this as the default entry point for apps and agents. Multi-location requests can return partial success with per-location status so one ambiguous place does not fail the whole batch.

Parameters

query or locationsstring

Single location query or pipe-delimited list of locations to resolve.

countryCode or countryCodesstringOptional

ISO country hint to improve deterministic resolution. Hints improve ranking and disambiguation but do not turn search-like inputs into strict country filters.

includeTransitionsbooleanOptional

Adds last and next timezone transition detail when you need full DST context.

candidateLimitintegerOptional

Page size for namesake candidates. Default 6, max 50.

candidateOffsetintegerOptional

Skip this many namesake candidates. Follow moreCandidates.resolve or moreCandidates.search for the rest.

request
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"
response
{
  "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"
      }
    }
  ]
}
Core endpoint

get_current_time

GET/time/current

Current 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 querystring

A 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.

countryCodestringOptional

ISO country hint for duplicate city names like Victoria or San Jose.

candidateLimitintegerOptional

Page size for namesake candidates. Default 6, max 50. Use with candidateOffset or follow moreCandidates.resolve / moreCandidates.search.

candidateOffsetintegerOptional

Skip this many namesake candidates. Copy from moreCandidates.candidateOffset to fetch the rest.

request
curl --request GET \
  --url "https://time-api.findtime.io/time/current?city=Tokyo&countryCode=JP" \
  --header "Authorization: Bearer YOUR_SECRET_KEY"
response
{
  "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
  }
}
Core endpoint

get_dst_schedule

GET/timezone/dst

DST truth surface: current state, current abbreviation, last transition, next transition, and yearly DST context without guessing.

This is the endpoint to use when you need to answer “does this place observe DST?” or “when do clocks change this year?” with current and upcoming transition detail. The request example below uses the optional `at` and `year` parameters together.

Parameters

city, query, or timezonestring

Location input or direct IANA timezone.

countryCodestringOptional

ISO hint to break city-name ties.

atstringOptional

ISO timestamp, for example `2026-01-15T12:00:00Z`, that anchors lastTransition and nextTransition to a specific reference instant.

yearintegerOptional

Calendar year that adds a year-specific transition view with transitions, springTransition, and fallTransition.

request
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"
response
{
  "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"
    }
  }
}
Core endpoint

convert_time

GET/time/convert

One-to-one or one-to-many conversion with explicit ambiguity handling. No silent guessing when inputs like CST or Victoria are underspecified.

Parameters

fromstring

Source location or timezone.

tostring

One target or pipe-delimited targets.

timestring

Source local time to convert. May include a simple human day phrase such as “3pm Tuesday”.

datestring

Date for the conversion context. Prefer ISO YYYY-MM-DD; simple human values such as “Thursday” or “tomorrow” are accepted.

request
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"
response
{
  "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" }
    }
  ]
}
Differentiator

get_overlap_hours

GET/time/overlap

Shared business-hours overlap across locations. This is where findtime.io moves from utility to workflow intelligence.

This is one of the clearest parity++ surfaces. It answers the workflow question legacy time APIs usually leave to the caller.

Parameters

locationsstring

Pipe-delimited list of cities or timezones.

countryCodesstringOptional

Pipe-delimited ISO hints aligned with the locations list.

datestring

Date 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.

request
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"
response
{
  "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"
    }
  }
}
Differentiator

find_meeting_time

GET/meeting/find

Ranked 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

locationsstring

Pipe-delimited list of locations to include in the meeting search.

countryCodesstringOptional

Pipe-delimited ISO hints aligned with the locations list.

datestringOptional

Date 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.

durationMinutesintegerOptional

Optional meeting length. Only 30, 45, or 60 are written onto the planner link as aiDuration.

refstringOptional

Planner ref query param. MCP sends mcp-bot.

request
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"
response
{
  "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"
  }
}
Differentiator

check_proposed_time

GET/meeting/check

Judge a proposed meeting instant for each city. Returns verdicts, alternatives, shareText, and a planner URL with up to three UTC aiSlots.

Parameters

locationsstring

Pipe-delimited cities or timezones.

countryCodesstringOptional

Pipe-delimited ISO hints aligned with locations.

startstring

ISO instant with offset, or a floating local time such as 2026-09-29T09:00.

homestringOptional

IANA timezone for a floating start, such as America/Los_Angeles.

datestringOptional

YYYY-MM-DD when start is only a clock time.

durationMinutesintegerOptional

Optional. Only 30, 45, or 60 are written onto the planner link.

workStartintegerOptional

First in-hours local hour. Default 9.

workEndintegerOptional

Last in-hours local hour, inclusive. Default 18.

request
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"
response
{
  "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"
  }
}
Differentiator

are_they_awake

GET/meeting/awake

Say 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

theirCitystringOptional

One city or timezone to judge.

theirCitiesstringOptional

Pipe-delimited cities or timezones to judge.

myTimestringOptional

ISO instant or floating local time in myTimezone. Defaults to now.

myTimezonestringOptional

IANA timezone for the caller, such as America/Los_Angeles.

myCitystringOptional

Caller city when myTimezone is omitted.

datestringOptional

YYYY-MM-DD when myTime is only a clock time.

durationMinutesintegerOptional

Optional. Only 30, 45, or 60 are written onto the planner link.

workStartintegerOptional

First in-hours local hour. Default 9.

workEndintegerOptional

Last in-hours local hour, inclusive. Default 18.

request
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"
response
{
  "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"
  }
}
Differentiator

rank_recurring_slot

GET/meeting/recurring

Score 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

locationsstring

Pipe-delimited cities or timezones.

countryCodesstringOptional

Pipe-delimited ISO hints aligned with locations.

weekdaystring

Day name such as Mon or Monday.

timestring

Clock time such as 9am or 09:00 in the home timezone.

homestring

IANA timezone of the recurring clock, such as America/Los_Angeles.

occurrencesintegerOptional

Weeks to score before adding a DST week. Default 4. Max 8.

nowstringOptional

ISO instant used as today when choosing the next weekday.

durationMinutesintegerOptional

Optional. Only 30, 45, or 60 are written onto the planner link.

workStartintegerOptional

First in-hours local hour. Default 9.

workEndintegerOptional

Last in-hours local hour, inclusive. Default 18.

request
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"
response
{
  "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"
  }
}
Teams

team

GET/meeting/team

Homepage 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

teamIdstringOptional

Exact homepage group name. This public route still returns the stub. A signed-in hosted agent loads that group.

request
curl --request GET \
  --url "https://time-api.findtime.io/meeting/team?teamId=standup" \
  --header "Authorization: Bearer YOUR_SECRET_KEY"
response
{
  "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."
}
Catalog

locations/search + locations/:id

GET/locations/search and /locations/:id

Search 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

querystring

Search term such as Victoria, Sao Paulo, or Tokyo.

countryCodestringOptional

ISO country hint for ranking and disambiguation. This is a hint, not an exclusive country filter.

limitnumberOptional

Maximum number of search results to return. Use this (or candidateLimit / candidateOffset on /resolve and /time/current) when moreCandidates says namesakes were capped.

candidateLimitintegerOptional

Page size for exact namesake matches on this query. Default 6, max 50.

candidateOffsetintegerOptional

Skip this many namesake candidates. Copy from moreCandidates.candidateOffset.

request
curl --request GET \
  --url "https://time-api.findtime.io/locations/search?query=Victoria&countryCode=CA&limit=3" \
  --header "Authorization: Bearer YOUR_SECRET_KEY"
response
{
  "shape": "locations_search.v2",
  "results": [
    {
      "id": "findtime:victoria|CA|America/Vancouver",
      "name": "Victoria",
      "countryName": "Canada",
      "timezoneIana": "America/Vancouver",
      "population": 85792
    }
  ]
}
Booking

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.

Auth:
  • 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 guestTrackingToken or guestHistoryToken instead. The hosted MCP passes that identity to the booking server, so use the MCP tools for writes.
  • Scopes: booking:request for a guest's agent and booking:host for a host's agent. Custom clients request those scopes by name.
  • Every write takes confirm. Without confirm: true the answer is a read-back and nothing changes. Retry request_booking with the same idempotencyKey.
  • Host routes act only on requests whose hostUid is the signed-in host. Older requests without it stay in the findtime inbox and are counted in olderRequests.

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

MethodPathAuthWhat it does
GET/api/booking/agent/hosts/:handleNoneHost profile: name, zone, meeting lengths, one meeting type (labeled Meeting), minimum notice, passcode flag.
POST/api/booking/agent/hosts/:handle/slotsNoneNumbered open times as optionIds, in the guest's zone and the host's. Options last about 15 minutes.
POST/api/booking/agent/requestsbooking:requestRequest one option. Takes handle, optionId, guestName, guestZone, idempotencyKey, confirm.
GET/api/booking/agent/requests/:requestId?token=Tracking tokenOne request: pending, confirmed, declined, cancelled_by_guest or cancelled_by_host.
GET/api/booking/agent/guest-requests?guestHistoryToken=History tokenEvery request the guest sent to one host.
POST/api/booking/agent/requests/:requestId/cancelTracking or history tokenCancel a pending request or an approved meeting. Needs confirm: true.
POST/api/booking/agent/requests/:requestId/reschedulebooking:requestMove 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

MethodPathAuthWhat it does
GET/api/booking/agent/host/pagebooking:hostThe 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/pagebooking:hostChange lengths, weekly hours, pause, or the agent switch. Read-back first, then confirm: true.
GET/api/booking/agent/host/requests?status=&from=&to=booking:hostThe host's inbox with lifecycleVersion and allowed actions. olderRequests counts rows only visible in findtime.
POST/api/booking/agent/host/requests/:requestId/approvebooking:hostApprove. Returns needs_calendar_connect, needs_payment, needs_sync or conflict when it can't finish.
POST/api/booking/agent/host/requests/:requestId/declinebooking:hostDecline, with an optional reason.
POST/api/booking/agent/host/requests/:requestId/cancelbooking:hostCancel a request or an approved meeting. A stale lifecycleVersion returns conflict.
POST/api/booking/agent/host/invite-linksbooking:hostMake a personal link for one guest. findtime doesn't send it.
POST/api/booking/agent/host/invite-links/:linkId/revokebooking:hostStop 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

API Quick Reference

  • Production base URL: https://time-api.findtime.io
  • Natural-language agent call: /time/answer
  • Flagship call: /time/snapshot
  • Use /locations/search first when you want deterministic location resolution, then store the returned findtime: id. Current ids include geonameId or state; older slug|CC|TZ ids still hydrate.
  • Every endpoint expects Authorization: Bearer YOUR_SECRET_KEY.
  • Hosted MCP is POST https://mcp.findtime.io/mcp with OAuth 2.1 and PKCE, and it accepts bearer API keys.
  • /time/overlap returns the shared overlap window across locations.
  • /meeting/find returns ranked meeting suggestions with shareText and a planner URL.
  • /meeting/check, /meeting/awake, and /meeting/recurring return paste-ready meeting intelligence for proposed times, ping timing, and recurring standups.
  • /meeting/team never stores a group; it answers teams_not_persisted. Saved groups live on the hosted MCP server, signed in with Google.
SurfaceBest forWhy it matters
answer_time_questionRaw user promptsClassifies time questions, resolves relative dates like tomorrow or next Friday, and returns structured clarification for ambiguity.
time_snapshotDefault integrationOne-call packaged time intelligence with fewer follow-up requests.
get_overlap_hoursScheduling workflowsTurns time data into useful workflow intelligence.
find_meeting_timeAgents and teamsReturns ranked meeting options across cities with shareText and a planner URL.
check_proposed_timeProposed slotsVerdicts per city plus alternatives when the proposed instant is rough.
are_they_awakePing timingWork, awake, or sleep labels for other cities at your moment.
rank_recurring_slotWeekly standupsPer-city pain, daylight-saving week, and a kinder recurring slot.
teamSaved teamsHomepage 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.
v4.6-549-g87ea78d5f-6997-87ea78d