API reference · Natural Language Scheduling

Natural Language Scheduling

Parse natural language into a structured event, with per-field confidence.

★

Aspirational surface. This resource is part of the developer-platform roadmap. The field shapes follow the same conventions as live resources and are stable for prototype integrations.

Endpoints

POST /v1/scheduling/parse Natural-language → event

Parse natural language into an event

HTTP
POST /v1/scheduling/parse

Returns a fully-typed Event candidate plus per-field confidence scores. Drop the event object straight into POST /v1/events.

JSON
{
  "text": "Lunch with Sarah Tuesday at 12 at Buena Vista Cafe",
  "user_context": {
    "timezone": "America/Los_Angeles",
    "user_id": "usr_1abc2def3ghi",
    "default_event_duration_min": 60
  }
}

Response:

JSON
{
  "object": "parsed_event",
  "event": {
    "title": "Lunch with Sarah",
    "start_time": "2026-05-26T12:00:00-07:00",
    "end_time": "2026-05-26T13:00:00-07:00",
    "timezone": "America/Los_Angeles",
    "location": {
      "name": "Buena Vista Cafe",
      "address": "2765 Hyde St, San Francisco, CA 94109"
    },
    "attendees": [
      { "name": "Sarah", "email": null }
    ]
  },
  "confidence": {
    "title": 0.96,
    "start_time": 0.91,
    "location": 0.88,
    "attendees": 0.62
  },
  "warnings": ["attendee_email_missing"]
}

Handling low confidence

We recommend surfacing a confirmation step to the user whenever any top-level field's confidence is below 0.7. The parser is conservative — it would rather fail-soft than fabricate.

curl https://api.chronapilot.com/v1/scheduling/parse \ -X POST \ -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc" \ -H "Chronapilot-Version: 2026-05-20" \ -H "Content-Type: application/json" \ -d '{ "text": "Lunch with Sarah Tuesday at 12 at Buena Vista Cafe", "user_context": { "timezone": "America/Los_Angeles", "user_id": "usr_1abc2def3ghi" } }'

import ChronaPilot from '@chronapilot/node'; const cp = new ChronaPilot('sk_test_4eC39HqLyjWDarjtT1zdp7dc'); const result = await cp.scheduling.parse({ text: 'Lunch with Sarah Tuesday at 12 at Buena Vista Cafe', user_context: { timezone: 'America/Los_Angeles', user_id: 'usr_1abc2def3ghi' } });

import chronapilot chronapilot.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc' result = chronapilot.Scheduling.parse( text='Lunch with Sarah Tuesday at 12 at Buena Vista Cafe', user_context={ 'timezone': 'America/Los_Angeles', 'user_id': 'usr_1abc2def3ghi' }, )

{ "object": "parsed_event", "event": { "title": "Lunch with Sarah", "start_time": "2026-05-26T12:00:00-07:00", "end_time": "2026-05-26T13:00:00-07:00", "location": { "name": "Buena Vista Cafe" } }, "confidence": { "title": 0.96, "start_time": 0.91, "location": 0.88 }, "warnings": [ "attendee_email_missing" ], "livemode": true, "request_id": "req_1A2b3C4d5E6f" }