NightOwl Docs
Early access integration docs for NightOwl
Start with the current integration path for NightOwl's open-now and business-hours API workflows. Full self-serve contract docs are still being finalized, but you can use the links below to get practical next steps immediately.
Start here
For current implementation notes, use the product context and access request path first. Detailed endpoint/schema docs are shared through approved-access channels while public docs are completed.
Who should request access
- Local directory builders
- Restaurant/venue apps
- Service marketplaces
- AI agents/workflows
- Internal ops tools
NightOwl remains request-based for production onboarding.
Sample /api/open-now response (MVP)
{
"openNow": true,
"status": "open",
"nextChange": "17:00",
"nextRelevantWindow": "Monday at 09:00",
"timezone": "America/New_York",
"confidence": 0.86,
"caveats": [
"Schedule covers 5/7 days; some days may be closed"
],
"evaluatedAt": "2026-04-26T14:30:00.000Z",
"note": "This is an early-access API MVP. Business availability data is deterministic based on provided schedule."
}API Contract Boundary (MVP)
This NightOwl API provides deterministic schedule-only evaluation. The following fields are stable and guaranteed for MVP compatibility. Fields marked as "Early Access" may change without notice.
Stable MVP Fields (Guaranteed)
openNow— booleanstatus— "open" | "closed"nextChange— HH:mm when status changesnextRelevantWindow— human-readable windowtimezone— IANA timezone identifierconfidence— 0.0-1.0 score
Early Access (Caveats)
caveats— may expand without noticeevaluatedAt— format may changenote— may be removed when stable
Deterministic Schedule-Only Truth
This MVP provides deterministic evaluation based entirely on the schedule you provide. No external data sources are queried. Results may differ from real-world business availability. Do not use for production billing without explicit verification.
API Reference
POST /api/open-now
Evaluate whether a business is currently open based on a deterministic schedule.
Request Body (JSON)
{
"schedule": {
"monday": { "open": "09:00", "close": "17:00" },
"tuesday": { "open": "09:00", "close": "17:00" },
"wednesday": { "open": "09:00", "close": "17:00" },
"thursday": { "open": "09:00", "close": "17:00" },
"friday": { "open": "09:00", "close": "20:00" },
"saturday": { "open": "10:00", "close": "18:00" },
"sunday": { "open": "11:00", "close": "16:00" }
},
"timezone": "America/New_York",
"current_time": "2026-04-26T14:30:00Z"
}schedule
Required. Object with days as keys (monday-sunday), each containing open/close times in "HH:mm" format.
timezone
Optional. IANA timezone identifier (default: UTC).
current_time
Optional. ISO 8601 datetime string (default: server time).
Successful Response (200 OK)
{
"openNow": true,
"status": "open",
"nextChange": "17:00",
"nextRelevantWindow": "Monday at 09:00",
"timezone": "America/New_York",
"confidence": 0.86,
"caveats": [
"Schedule covers 5/7 days; some days may be closed"
],
"evaluatedAt": "2026-04-26T14:30:00.000Z",
"note": "This is an early-access API MVP. Business availability data is deterministic based on provided schedule."
}Response Fields:
- openNow — boolean indicating if business is currently open
- status — "open" or "closed"
- nextChange — "HH:mm" when status next changes (if known)
- nextRelevantWindow — human-readable description of next window
- confidence — 0.0-1.0 score based on schedule completeness
- caveats — array of limitations/notes about evaluation
- evaluatedAt — ISO 8601 timestamp of evaluation
Error Examples
400 Bad Request — Invalid Schedule
Invalid time format or missing schedule object returns a 400 error with details.
Invalid Request
{
"schedule": {
"monday": { "open": "25:00", "close": "17:00" }
},
"timezone": "America/New_York"
}400 Response
{
"error": "Invalid schedule",
"message": "Schedule contains validation errors",
"details": [
"Invalid open time on monday: 25:00"
]
}400 Bad Request — Missing Schedule
Request without the required schedule object.
Invalid Request
{
"timezone": "America/New_York"
}400 Response
{
"error": "Missing schedule",
"message": "Request must include a 'schedule' object"
}400 Bad Request — Invalid Time
Malformed current_time date string.
Invalid Request
{
"schedule": {
"monday": { "open": "09:00", "close": "17:00" }
},
"timezone": "America/New_York",
"current_time": "not-a-date"
}400 Response
{
"error": "Invalid current_time",
"message": "current_time must be a valid ISO 8601 date string"
}500 Internal Server Error
{
"error": "Internal server error",
"message": "An error occurred while evaluating business availability"
}Important Limitations
- Early Access MVP: This endpoint uses deterministic logic only. No external Google Business data ingestion.
- Request-Based Access: Current production access is through manual request/onboarding. Self-serve is not yet available.
- No Holidays: Holiday calendars are not included in this MVP.
- Deterministic Only: Results depend entirely on the schedule you provide — no real-time data fetching.
- Basic Validation: Only format validation is performed. Invalid business logic in schedules returns deterministic (not necessarily sensible) results.
This API is for evaluation purposes only. Do not use for production billing or user-facing features without explicit verification.
What this docs page now confirms
- NightOwl is the flagship API for open-now and business-hours availability decisions.
- Primary fit is local-business and restaurant-style developer workflows.
- Public self-serve API contract docs are not fully published yet.
Not public yet
- Legacy coding-workflow API examples.
- Monitor/incident or uptime-monitoring endpoint docs.
- Finalized public schema guarantees before rollout completion.