{ "openapi": "3.1.0", "info": { "title": "eScheduleIt Public API", "version": "1.0", "description": "Account-bound REST access to eScheduleIt. The account is fixed by your OAuth connection; no request carries an account identifier. Every operation here is also an MCP tool at /mcp.", "x-mcp-endpoint": "https://mcp.eschedule.it/mcp", "x-documentation": "https://mcp.eschedule.it/docs" }, "servers": [ { "url": "https://mcp.eschedule.it" } ], "paths": { "/v1/coverage/analyze-appointment": { "post": { "operationId": "analyze_coverage_for_appointment", "summary": "analyze coverage for appointment", "description": "Who could replace one or more people on an existing appointment, honouring its offering requirements, tags and proximity. For a recurring series you must pass occurrence_start_utc and occurrence_end_utc for the specific instance \u2014 the series seed date is not a valid anchor. Read-only; propose the change with manage_appointments.", "tags": [ "coverage" ], "security": [ { "oauth2": [ "eschedule:read" ] } ], "x-required-privileges": [ "SearchAppointment", "SearchAvailability" ], "x-mcp-tool": "analyze_coverage_for_appointment", "x-posture": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "scanned_window_start_utc": { "type": [ "string", "null" ], "format": "date-time" }, "scanned_window_end_utc": { "type": [ "string", "null" ], "format": "date-time" }, "open_slots": { "type": "array" }, "coverage_gaps": { "type": "array" }, "outreach_candidates": { "type": "array" }, "analysis_incomplete": { "type": "boolean" }, "analysis_notes": { "type": [ "string", "null" ] }, "timezone_for_results": { "type": [ "string", "null" ] }, "coverage_context": { "type": [ "object", "null" ], "additionalProperties": false }, "appointment_description": { "type": [ "string", "null" ] } }, "additionalProperties": false } } } }, "400": { "description": "Validation failed or forbidden parameter", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_privileges, insufficient_scope (with a Bearer challenge naming the scope) or account_ineligible", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found in this account", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Dependency unavailable; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appointment_id": { "type": "string", "format": "uuid" }, "resource_ids_to_replace": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "required_tag_ids": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" } }, "proximity_miles": { "type": [ "number", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "occurrence_start_utc": { "type": [ "string", "null" ], "format": "date-time" }, "occurrence_end_utc": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": false } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Replays within this connection return the stored result; a reused key with a different body is refused." } ] } }, "/v1/coverage/analyze": { "post": { "operationId": "analyze_schedule_coverage", "summary": "analyze schedule coverage", "description": "For a requirement (duration, window \u2264 31 days, required people and tags), report where coverage exists (open slots), where it\nis missing (coverage gaps) and who could be asked to fill gaps (outreach candidates). Read-only analysis; to book, use\nfind_open_appointment_slots and then manage_appointments.", "tags": [ "coverage" ], "security": [ { "oauth2": [ "eschedule:read" ] } ], "x-required-privileges": [ "SearchAppointment", "SearchAvailability" ], "x-mcp-tool": "analyze_schedule_coverage", "x-posture": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "scanned_window_start_utc": { "type": [ "string", "null" ], "format": "date-time" }, "scanned_window_end_utc": { "type": [ "string", "null" ], "format": "date-time" }, "open_slots": { "type": "array" }, "coverage_gaps": { "type": "array" }, "outreach_candidates": { "type": "array" }, "analysis_incomplete": { "type": "boolean" }, "analysis_notes": { "type": [ "string", "null" ] }, "timezone_for_results": { "type": [ "string", "null" ] }, "coverage_context": { "type": [ "object", "null" ], "additionalProperties": false }, "appointment_description": { "type": [ "string", "null" ] } }, "additionalProperties": false } } } }, "400": { "description": "Validation failed or forbidden parameter", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_privileges, insufficient_scope (with a Bearer challenge naming the scope) or account_ineligible", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found in this account", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Dependency unavailable; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "duration_minutes": { "type": "integer" }, "start_utc": { "type": "string", "format": "date-time" }, "end_utc": { "type": "string", "format": "date-time" }, "start_time_of_day": { "type": [ "string", "null" ] }, "end_time_of_day": { "type": [ "string", "null" ] }, "required_resource_ids": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" } }, "required_tags": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "tag_id": { "type": "string", "format": "uuid" }, "operand": { "type": "string" }, "value1": { "type": "integer" }, "value2": { "type": [ "integer", "null" ] } }, "additionalProperties": false } }, "exclude_resource_ids": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" } }, "proximity_type": { "type": [ "string", "null" ] }, "proximity_miles": { "type": [ "number", "null" ] }, "timezone": { "type": [ "string", "null" ] } }, "additionalProperties": false } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Replays within this connection return the stored result; a reused key with a different body is refused." } ] } }, "/v1/appointments/book-for-contact": { "post": { "operationId": "book_appointment_for_contact", "summary": "book appointment for contact", "description": "Find-or-create a client by name plus phone or email, and propose an appointment for them with the given staff. Staged as a booking request for approval unless the account auto-approves bookings. Check find_open_appointment_slots first, and quote the returned request_id to the user.", "tags": [ "appointments" ], "security": [ { "oauth2": [ "eschedule:write" ] } ], "x-required-privileges": [ "BookAppointment" ], "x-mcp-tool": "book_appointment_for_contact", "x-posture": "staged", "responses": { "200": { "description": "Applied immediately (account auto-approval)", "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_resource_id": { "type": [ "string", "null" ], "format": "uuid" }, "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "message": { "type": "string" }, "counts": { "type": "object", "properties": { "create": { "type": "integer" }, "update": { "type": "integer" }, "cancel": { "type": "integer" }, "delete": { "type": "integer" } }, "additionalProperties": false }, "auth_capacity_fit": { "type": [ "string", "null" ] }, "capacity_warnings": { "type": "array", "items": { "type": "object", "properties": { "resource_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "severity": { "type": "string" }, "detail": { "type": "string" } }, "additionalProperties": false } }, "posture_reason": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "Validation failed or forbidden parameter", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_privileges, insufficient_scope (with a Bearer challenge naming the scope) or account_ineligible", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found in this account", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Dependency unavailable; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "202": { "description": "Staged; waiting for approval in the app", "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_resource_id": { "type": [ "string", "null" ], "format": "uuid" }, "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "message": { "type": "string" }, "counts": { "type": "object", "properties": { "create": { "type": "integer" }, "update": { "type": "integer" }, "cancel": { "type": "integer" }, "delete": { "type": "integer" } }, "additionalProperties": false }, "auth_capacity_fit": { "type": [ "string", "null" ] }, "capacity_warnings": { "type": "array", "items": { "type": "object", "properties": { "resource_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "severity": { "type": "string" }, "detail": { "type": "string" } }, "additionalProperties": false } }, "posture_reason": { "type": "string" } }, "additionalProperties": false } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_name": { "type": "string" }, "contact_phone": { "type": [ "string", "null" ] }, "contact_email": { "type": [ "string", "null" ] }, "start_utc": { "type": "string", "format": "date-time" }, "end_utc": { "type": "string", "format": "date-time" }, "performer_resource_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "offering_id": { "type": [ "string", "null" ], "format": "uuid" }, "description": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "time_zone": { "type": [ "string", "null" ] } }, "additionalProperties": false } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Replays within this connection return the stored result; a reused key with a different body is refused." } ] } }, "/v1/people/{resource_id}/open-availability": { "get": { "operationId": "check_resource_open_availability", "summary": "check resource open availability", "description": "Free slots for a person: working hours minus booked appointments and holiday closures, cut into slots of slot_duration_minutes (default 30), over a window of at most 31 days. Each entry says whether it is available and names the holiday closing it when it is not.", "tags": [ "availability" ], "security": [ { "oauth2": [ "eschedule:read" ] } ], "x-required-privileges": [ "ReadAvailability" ], "x-mcp-tool": "check_resource_open_availability", "x-posture": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "resource_id": { "type": "string", "format": "uuid" }, "entries": { "type": "array", "items": { "type": "object", "properties": { "is_available": { "type": "boolean" }, "holiday_closure": { "type": [ "object", "null" ], "properties": { "name": { "type": "string" }, "start_utc": { "type": "string", "format": "date-time" }, "end_utc": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "id": { "type": "string", "format": "uuid" }, "resource_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "available_for_any_offering": { "type": "boolean" }, "start_utc": { "type": "string", "format": "date-time" }, "end_utc": { "type": "string", "format": "date-time" }, "start_in_timezone": { "type": "string", "format": "date-time" }, "end_in_timezone": { "type": "string", "format": "date-time" }, "duration": { "$comment": "Represents a System.TimeSpan value.", "type": "string", "pattern": "^-?(\\d\u002B\\.)?\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,7})?$" }, "is_recurring": { "type": "boolean" }, "recurrence_description": { "type": [ "string", "null" ] }, "available_for_offerings": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" } } }, "additionalProperties": false } }, "summary": { "type": "string" }, "time_zone_for_results": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "Validation failed or forbidden parameter", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_privileges, insufficient_scope (with a Bearer challenge naming the scope) or account_ineligible", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found in this account", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Dependency unavailable; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "parameters": [ { "name": "resource_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "style": "form", "explode": true }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "style": "form", "explode": true }, { "name": "timezone", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] }, "style": "form", "explode": true }, { "name": "slot_duration_minutes", "in": "query", "required": false, "schema": { "type": "integer" }, "style": "form", "explode": true }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Ignored on reads." } ] } }, "/v1/people/{resource_id}/working-schedule": { "get": { "operationId": "check_resource_working_schedule", "summary": "check resource working schedule", "description": "A person\u0027s declared working hours (availability patterns) in a window of at most 180 days, expanded to concrete entries in UTC and the requested time zone, with a plain-language summary. This is when they are meant to be working, not when they are free \u2014 use check_resource_open_availability for that.", "tags": [ "availability" ], "security": [ { "oauth2": [ "eschedule:read" ] } ], "x-required-privileges": [ "ReadAvailability" ], "x-mcp-tool": "check_resource_working_schedule", "x-posture": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "resource_id": { "type": "string", "format": "uuid" }, "entries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "resource_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "available_for_any_offering": { "type": "boolean" }, "start_utc": { "type": "string", "format": "date-time" }, "end_utc": { "type": "string", "format": "date-time" }, "start_in_timezone": { "type": "string", "format": "date-time" }, "end_in_timezone": { "type": "string", "format": "date-time" }, "duration": { "$comment": "Represents a System.TimeSpan value.", "type": "string", "pattern": "^-?(\\d\u002B\\.)?\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,7})?$" }, "is_recurring": { "type": "boolean" }, "recurrence_description": { "type": [ "string", "null" ] }, "available_for_offerings": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" } } }, "additionalProperties": false } }, "summary": { "type": "string" }, "time_zone_for_results": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "Validation failed or forbidden parameter", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_privileges, insufficient_scope (with a Bearer challenge naming the scope) or account_ineligible", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found in this account", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Dependency unavailable; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "parameters": [ { "name": "resource_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "style": "form", "explode": true }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "style": "form", "explode": true }, { "name": "timezone", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] }, "style": "form", "explode": true }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Ignored on reads." } ] } }, "/v1/authorizations/allocations/{allocation_id}/explain": { "get": { "operationId": "explain_capacity_decision", "summary": "explain capacity decision", "description": "Why one allocation was allowed, warned about or refused: the thresholds that applied, what was already committed, and which rule decided. Use it when a user asks why a booking was blocked, instead of guessing from the refusal message.", "tags": [ "authorizations" ], "security": [ { "oauth2": [ "eschedule:read" ] } ], "x-required-privileges": [ "authz.capacity.view" ], "x-mcp-tool": "explain_capacity_decision", "x-posture": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation failed or forbidden parameter", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_privileges, insufficient_scope (with a Bearer challenge naming the scope) or account_ineligible", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found in this account", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Dependency unavailable; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "parameters": [ { "name": "allocation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Ignored on reads." } ] } }, "/v1/authorizations/coverage-opportunities": { "get": { "operationId": "find_beneficiaries_needing_hours", "summary": "find beneficiaries needing hours", "description": "People whose authorized hours are going unused: how many units remain, how many weeks are left in the period, the weekly burn required to use them against what is actually scheduled, and an urgency score. Ranked most urgent first. Use it to decide who to schedule next.", "tags": [ "authorizations" ], "security": [ { "oauth2": [ "eschedule:read" ] } ], "x-required-privileges": [ "authz.reports.utilization.view" ], "x-mcp-tool": "find_beneficiaries_needing_hours", "x-posture": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "opportunities": { "type": "array", "items": { "type": "object", "properties": { "beneficiary_resource_id": { "type": "string", "format": "uuid" }, "beneficiary_resource_name": { "type": [ "string", "null" ] }, "allowance_bucket_id": { "type": "string", "format": "uuid" }, "bucket_code": { "type": "string" }, "remaining_units": { "type": "integer" }, "weeks_until_period_end": { "type": "integer" }, "required_weekly_burn": { "type": "number" }, "scheduled_weekly_burn": { "type": "number" }, "burn_gap_units": { "type": "integer" }, "urgency_score": { "type": "number" } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "400": { "description": "Validation failed or forbidden parameter", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_privileges, insufficient_scope (with a Bearer challenge naming the scope) or account_ineligible", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found in this account", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Dependency unavailable; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "parameters": [ { "name": "min_urgency", "in": "query", "required": false, "schema": { "type": "number" }, "style": "form", "explode": true }, { "name": "max_results", "in": "query", "required": false, "schema": { "type": "integer" }, "style": "form", "explode": true }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Ignored on reads." } ] } }, "/v1/appointments/candidates": { "post": { "operationId": "find_open_appointment_slots", "summary": "find open appointment slots", "description": "Find bookable slots. Offering mode uses the offering\u0027s duration and requirements; custom mode takes a duration plus required\npeople and tag requirements. Window \u2264 31 days. Each candidate lists the people who would be booked, an authorization/capacity\nverdict (Ok, Warning, Critical, Unknown) and warnings \u2014 surface a Critical verdict to the user before proposing the slot.", "tags": [ "appointments" ], "security": [ { "oauth2": [ "eschedule:read" ] } ], "x-required-privileges": [ "SearchAppointment", "SearchAvailability" ], "x-mcp-tool": "find_open_appointment_slots", "x-posture": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "candidate_count": { "type": "integer" }, "timezone_for_results": { "type": [ "string", "null" ] }, "candidates": { "type": "array", "items": { "type": "object", "properties": { "start_utc": { "type": "string", "format": "date-time" }, "end_utc": { "type": "string", "format": "date-time" }, "start_in_timezone": { "type": "string", "format": "date-time" }, "end_in_timezone": { "type": "string", "format": "date-time" }, "duration": { "type": "string" }, "offering": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "additionalProperties": false }, "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "additionalProperties": false } }, "capacity_warnings": { "type": "array", "items": { "type": "object", "properties": { "resource_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "severity": { "type": "string" }, "detail": { "type": "string" } }, "additionalProperties": false } }, "auth_capacity_fit": { "type": "string" }, "kept_assignments": { "type": "array", "items": { "type": "object", "properties": { "performer_resource_id": { "type": "string", "format": "uuid" }, "performer_name": { "type": "string" }, "beneficiary_resource_id": { "type": "string", "format": "uuid" }, "beneficiary_name": { "type": "string" }, "since_utc": { "type": "string", "format": "date-time" } }, "additionalProperties": false } } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "400": { "description": "Validation failed or forbidden parameter", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_privileges, insufficient_scope (with a Bearer challenge naming the scope) or account_ineligible", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found in this account", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Dependency unavailable; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "search_mode": { "type": "string" }, "offering_id": { "type": [ "string", "null" ], "format": "uuid" }, "duration": { "type": [ "string", "null" ] }, "required_resource_ids": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" } }, "additional_resource_ids": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" } }, "required_tags": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "tag_id": { "type": "string", "format": "uuid" }, "operand": { "type": "string" }, "value1": { "type": "integer" }, "value2": { "type": [ "integer", "null" ] } }, "additionalProperties": false } }, "start_utc": { "type": "string", "format": "date-time" }, "end_utc": { "type": "string", "format": "date-time" }, "start_time_of_day": { "type": [ "string", "null" ] }, "end_time_of_day": { "type": [ "string", "null" ] }, "proximity_type": { "type": [ "string", "null" ] }, "proximity_miles": { "type": [ "number", "null" ] }, "max_results": { "type": "integer" }, "timezone": { "type": [ "string", "null" ] } }, "additionalProperties": false } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Replays within this connection return the stored result; a reused key with a different body is refused." } ] } }, "/v1/authorizations/resources-needing-hours": { "get": { "operationId": "find_resources_needing_hours", "summary": "find resources needing hours", "description": "Staff who are under their billable target for the ISO week containing week_start (default: this week): planned minutes against base and overtime thresholds, and how far under target they are. Ranked by the largest shortfall first, so the first name is the person to give work to.", "tags": [ "authorizations" ], "security": [ { "oauth2": [ "eschedule:read" ] } ], "x-required-privileges": [ "authz.reports.utilization.view" ], "x-mcp-tool": "find_resources_needing_hours", "x-posture": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "week_start": { "type": "string", "format": "date-time" }, "resources": { "type": "array", "items": { "type": "object", "properties": { "resource_id": { "type": "string", "format": "uuid" }, "resource_name": { "type": [ "string", "null" ] }, "capacity_kind_id": { "type": "string", "format": "uuid" }, "capacity_kind_name": { "type": "string" }, "category": { "type": [ "string", "null" ] }, "base_minutes_per_week": { "type": [ "integer", "null" ] }, "overtime_minutes_per_week": { "type": [ "integer", "null" ] }, "planned_minutes": { "type": "integer" }, "remaining_minutes": { "type": "integer" }, "under_target_minutes": { "type": "integer" }, "over_target_minutes": { "type": "integer" }, "warning_level": { "type": [ "string", "null" ] } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "400": { "description": "Validation failed or forbidden parameter", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_privileges, insufficient_scope (with a Bearer challenge naming the scope) or account_ineligible", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found in this account", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Dependency unavailable; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "parameters": [ { "name": "week_start", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" }, "style": "form", "explode": true }, { "name": "max_results", "in": "query", "required": false, "schema": { "type": "integer" }, "style": "form", "explode": true }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Ignored on reads." } ] } }, "/v1/account": { "get": { "operationId": "get_account_details", "summary": "get account details", "description": "The account this connection is locked to: its name, distance unit, decline timeout, and its locations with addresses. Use it to resolve a place the user names in conversation. No ids, provisioning or billing fields.", "tags": [ "account" ], "security": [ { "oauth2": [ "eschedule:read" ] } ], "x-required-privileges": [ "ReadAccount" ], "x-mcp-tool": "get_account_details", "x-posture": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "preferred_distance_unit": { "type": "string" }, "decline_appointment_timeout_seconds": { "type": "integer" }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "address_line1": { "type": [ "string", "null" ] }, "address_line2": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zip_code": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "active": { "type": "boolean" } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "400": { "description": "Validation failed or forbidden parameter", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_privileges, insufficient_scope (with a Bearer challenge naming the scope) or account_ineligible", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found in this account", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Dependency unavailable; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Ignored on reads." } ] } }, "/v1/assignments": { "get": { "operationId": "get_assignments", "summary": "get assignments", "description": "Standing assignments between a client and the staff who cover them: coverage role, kind, status, and the dates the assignment runs between. Pass resource_id for everything a person is part of on either side, OR name one side with beneficiary_resource_id or performer_resource_id \u2014 not both, they ask different questions. Ended assignments are excluded unless include_ended is true. Use it to keep continuity \u2014 the person already assigned is usually the right one to book.", "tags": [ "assignments" ], "security": [ { "oauth2": [ "eschedule:read" ] } ], "x-required-privileges": [ "engagement.view" ], "x-mcp-tool": "get_assignments", "x-posture": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "assignments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "beneficiary_resource_id": { "type": "string", "format": "uuid" }, "beneficiary_resource_name": { "type": [ "string", "null" ] }, "performer_resource_id": { "type": "string", "format": "uuid" }, "performer_resource_name": { "type": [ "string", "null" ] }, "coverage_role": { "type": "string" }, "kind": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "effective_from_utc": { "type": "string", "format": "date-time" }, "effective_to_utc": { "type": [ "string", "null" ], "format": "date-time" }, "origin": { "type": [ "string", "null" ] }, "end_reason": { "type": [ "string", "null" ] } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "400": { "description": "Validation failed or forbidden parameter", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_privileges, insufficient_scope (with a Bearer challenge naming the scope) or account_ineligible", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found in this account", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Dependency unavailable; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "parameters": [ { "name": "resource_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" }, "style": "form", "explode": true }, { "name": "beneficiary_resource_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" }, "style": "form", "explode": true }, { "name": "performer_resource_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" }, "style": "form", "explode": true }, { "name": "include_ended", "in": "query", "required": false, "schema": { "type": "boolean" }, "style": "form", "explode": true }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Ignored on reads." } ] } }, "/v1/authorizations/balances": { "get": { "operationId": "get_authorization_balances", "summary": "get authorization balances", "description": "Authorized-hours balances per beneficiary and bucket: authorized, held, consumed, scheduled, remaining and available-to-book units, utilization percent, projected run-out date and runway warning level. Filter by beneficiary, bucket, minimum warning level or a utilization band.", "tags": [ "authorizations" ], "security": [ { "oauth2": [ "eschedule:read" ] } ], "x-required-privileges": [ "authz.reports.balances.view" ], "x-mcp-tool": "get_authorization_balances", "x-posture": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "balances": { "type": "array", "items": { "type": "object", "properties": { "beneficiary_resource_id": { "type": "string", "format": "uuid" }, "beneficiary_resource_name": { "type": [ "string", "null" ] }, "allowance_grant_id": { "type": "string", "format": "uuid" }, "allowance_bucket_id": { "type": "string", "format": "uuid" }, "bucket_code": { "type": "string" }, "period_start": { "type": "string", "format": "date-time" }, "period_end": { "type": "string", "format": "date-time" }, "authorized_units": { "type": "integer" }, "held_units": { "type": "integer" }, "consumed_units": { "type": "integer" }, "scheduled_future_units": { "type": "integer" }, "remaining_units": { "type": "integer" }, "available_to_book_units": { "type": "integer" }, "utilization_percent": { "type": "number" }, "projected_runout_date": { "type": [ "string", "null" ], "format": "date-time" }, "warning_level": { "type": [ "string", "null" ] } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "400": { "description": "Validation failed or forbidden parameter", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_privileges, insufficient_scope (with a Bearer challenge naming the scope) or account_ineligible", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found in this account", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Dependency unavailable; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "parameters": [ { "name": "beneficiary_resource_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" }, "style": "form", "explode": true }, { "name": "allowance_bucket_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" }, "style": "form", "explode": true }, { "name": "min_warning_level", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] }, "style": "form", "explode": true }, { "name": "min_utilization_percent", "in": "query", "required": false, "schema": { "type": [ "number", "null" ] }, "style": "form", "explode": true }, { "name": "max_utilization_percent", "in": "query", "required": false, "schema": { "type": [ "number", "null" ] }, "style": "form", "explode": true }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Ignored on reads." } ] } }, "/v1/authorizations/{allowance_grant_id}/trends": { "get": { "operationId": "get_authorization_utilization_trends", "summary": "get authorization utilization trends", "description": "How one authorization has been used over time, weekly or monthly: authorized, scheduled, consumed and remaining units per period. Use it to say whether usage is on track or falling behind, rather than guessing from a single balance.", "tags": [ "authorizations" ], "security": [ { "oauth2": [ "eschedule:read" ] } ], "x-required-privileges": [ "authz.reports.trends.view" ], "x-mcp-tool": "get_authorization_utilization_trends", "x-posture": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "granularity": { "type": "string" }, "points": { "type": "array", "items": { "type": "object", "properties": { "allowance_grant_id": { "type": "string", "format": "uuid" }, "period_key": { "type": "string" }, "authorized_units": { "type": "integer" }, "scheduled_units": { "type": "integer" }, "consumed_units": { "type": "integer" }, "remaining_units": { "type": "integer" } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "400": { "description": "Validation failed or forbidden parameter", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_privileges, insufficient_scope (with a Bearer challenge naming the scope) or account_ineligible", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found in this account", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Dependency unavailable; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "parameters": [ { "name": "allowance_grant_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "granularity", "in": "query", "required": false, "schema": { "type": "string" }, "style": "form", "explode": true }, { "name": "range_start", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "style": "form", "explode": true }, { "name": "range_end", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "style": "form", "explode": true }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Ignored on reads." } ] } }, "/v1/authorizations/expiring": { "get": { "operationId": "get_authorizations_expiring", "summary": "get authorizations expiring", "description": "Authorizations ending within within_days (1-365, default 30): when each period ends, how many units are still unused and therefore at risk, whether a renewal grant already exists, and whether anything is already booked past the end date with no renewal \u2014 which is the case worth raising with the user first.", "tags": [ "authorizations" ], "security": [ { "oauth2": [ "eschedule:read" ] } ], "x-required-privileges": [ "authz.reports.expiring.view" ], "x-mcp-tool": "get_authorizations_expiring", "x-posture": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "authorizations": { "type": "array", "items": { "type": "object", "properties": { "allowance_grant_id": { "type": "string", "format": "uuid" }, "beneficiary_resource_id": { "type": "string", "format": "uuid" }, "beneficiary_resource_name": { "type": [ "string", "null" ] }, "period_end": { "type": "string", "format": "date-time" }, "days_until_end": { "type": "integer" }, "remaining_units_at_risk": { "type": "integer" }, "has_renewal_grant": { "type": "boolean" }, "next_scheduled_appointment_after_end": { "type": [ "string", "null" ], "format": "uuid" }, "renewal_status_enum": { "type": [ "string", "null" ] } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "400": { "description": "Validation failed or forbidden parameter", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_privileges, insufficient_scope (with a Bearer challenge naming the scope) or account_ineligible", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found in this account", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Dependency unavailable; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "parameters": [ { "name": "within_days", "in": "query", "required": false, "schema": { "type": "integer" }, "style": "form", "explode": true }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Ignored on reads." } ] } }, "/v1/people/{resource_id}/holidays": { "get": { "operationId": "get_holidays", "summary": "get holidays", "description": "Holiday closures that apply to a person in a window of at most a year, in UTC and the requested time zone. Use it before proposing appointments on or near public holidays, so the user is not offered a slot the office is shut for.", "tags": [ "availability" ], "security": [ { "oauth2": [ "eschedule:read" ] } ], "x-required-privileges": [ "ReadAvailability" ], "x-mcp-tool": "get_holidays", "x-posture": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "holidays": { "type": "array", "items": { "type": "object", "properties": { "holiday_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "start_utc": { "type": "string", "format": "date-time" }, "end_utc": { "type": "string", "format": "date-time" }, "start_in_timezone": { "type": "string", "format": "date-time" }, "end_in_timezone": { "type": "string", "format": "date-time" }, "time_zone_id": { "type": [ "string", "null" ] } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "400": { "description": "Validation failed or forbidden parameter", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_privileges, insufficient_scope (with a Bearer challenge naming the scope) or account_ineligible", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found in this account", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Dependency unavailable; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "parameters": [ { "name": "resource_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "start_utc", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "style": "form", "explode": true }, { "name": "end_utc", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "style": "form", "explode": true }, { "name": "timezone", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] }, "style": "form", "explode": true }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Ignored on reads." } ] } }, "/v1/me": { "get": { "operationId": "get_my_context", "summary": "get my context", "description": "Who you are acting for. Returns the signed-in person\u0027s name, the account this connection is locked to, the account\u0027s\ntime zone, today\u0027s date in that zone, the scopes this connection was granted, and the tools you may call. Call this\nfirst in a conversation. Never ask the user for an account id \u2014 the account is fixed by the connection.", "tags": [ "context" ], "security": [ { "oauth2": [ "eschedule:read" ] } ], "x-required-privileges": [], "x-mcp-tool": "get_my_context", "x-posture": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "account_name": { "type": "string" }, "time_zone": { "type": "string" }, "time_zone_note": { "type": [ "string", "null" ] }, "today": { "type": "string", "format": "date" }, "connected_app": { "type": "string" }, "granted_scopes": { "type": "array", "items": { "type": "string" } }, "available_tools": { "type": "array", "items": { "type": "string" } }, "my_tags": { "type": "array", "items": { "type": "string" } }, "guidance": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "Validation failed or forbidden parameter", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_privileges, insufficient_scope (with a Bearer challenge naming the scope) or account_ineligible", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found in this account", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Dependency unavailable; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Ignored on reads." } ] } }, "/v1/people/{resource_id}/capacity": { "get": { "operationId": "get_resource_capacity", "summary": "get resource capacity", "description": "A person\u0027s weekly capacity and authorization balances for the ISO week containing week_start (default: this week): planned minutes against thresholds, per capacity kind and per authorization bucket. Use it before proposing extra work, so you can say whether it fits.", "tags": [ "authorizations" ], "security": [ { "oauth2": [ "eschedule:read" ] } ], "x-required-privileges": [ "authz.capacity.view" ], "x-mcp-tool": "get_resource_capacity", "x-posture": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "resource_id": { "type": "string", "format": "uuid" }, "week_start": { "type": "string", "format": "date-time" }, "balances": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "identifier": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "category": { "type": [ "string", "null" ] }, "planned_minutes": { "type": "integer" }, "threshold_minutes": { "type": [ "integer", "null" ] }, "remaining_minutes": { "type": [ "integer", "null" ] } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "400": { "description": "Validation failed or forbidden parameter", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_privileges, insufficient_scope (with a Bearer challenge naming the scope) or account_ineligible", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found in this account", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Dependency unavailable; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "parameters": [ { "name": "resource_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "week_start", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" }, "style": "form", "explode": true }, { "name": "source_filter", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] }, "style": "form", "explode": true }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Ignored on reads." } ] } }, "/v1/people/lookup": { "get": { "operationId": "lookup_resource", "summary": "lookup resource", "description": "Find a person (staff or client) in the account by id, phone, name or email. Returns contact details, tags, time zone and\nlinked logins. This is the ONLY tool that returns contact details; search tools return ids and names. Fuzzy matching may\nreturn several candidates \u2014 ask the user to disambiguate rather than guessing.", "tags": [ "people" ], "security": [ { "oauth2": [ "eschedule:read" ] } ], "x-required-privileges": [ "SearchResource" ], "x-mcp-tool": "lookup_resource", "x-posture": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "resources": { "type": "array", "items": { "type": "object", "properties": { "resource_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "resource_type": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone_number": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean" }, "preferred_language": { "type": [ "string", "null" ] }, "preferred_contact_method": { "type": [ "string", "null" ] }, "time_zone": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "additionalProperties": false } }, "associated_users": { "type": "array", "items": { "type": "object", "properties": { "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone_number": { "type": [ "string", "null" ] }, "time_zone": { "type": "string" }, "relationship_type": { "type": "string" }, "is_active": { "type": "boolean" } }, "additionalProperties": false } }, "match_source": { "type": [ "string", "null" ] }, "match_score": { "type": [ "number", "null" ] }, "matched_field": { "type": [ "string", "null" ] } }, "additionalProperties": false } }, "account": { "type": [ "object", "null" ], "properties": { "name": { "type": "string" }, "time_zone": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "fuzzy_applied": { "type": "boolean" }, "ambiguous": { "type": "boolean" }, "did_you_mean": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "name": { "type": "string" }, "score": { "type": "number" }, "match_source": { "type": [ "string", "null" ] } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "400": { "description": "Validation failed or forbidden parameter", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_privileges, insufficient_scope (with a Bearer challenge naming the scope) or account_ineligible", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found in this account", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Dependency unavailable; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "parameters": [ { "name": "resource_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" }, "style": "form", "explode": true }, { "name": "phone_number", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] }, "style": "form", "explode": true }, { "name": "name", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] }, "style": "form", "explode": true }, { "name": "email", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] }, "style": "form", "explode": true }, { "name": "match_threshold", "in": "query", "required": false, "schema": { "type": [ "number", "null" ] }, "style": "form", "explode": true }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Ignored on reads." } ] } }, "/v1/appointments/changes": { "post": { "operationId": "manage_appointments", "summary": "manage appointments", "description": "Propose appointment changes \u2014 create, reschedule/update, cancel or delete, one batch per request (at most 25). The proposal is\nSTAGED: it waits for approval in eScheduleIt unless the account auto-approves that kind of change. Times are UTC instants; the\napprover sees them in the account\u0027s zone. Use find_open_appointment_slots first when creating, and quote the returned\nrequest_id to the user so they can find it.", "tags": [ "appointments" ], "security": [ { "oauth2": [ "eschedule:write" ] } ], "x-required-privileges": [ "CreateAppointment", "UpdateAppointment", "CancelAppointment", "DeleteAppointment" ], "x-mcp-tool": "manage_appointments", "x-posture": "staged", "responses": { "200": { "description": "Applied immediately (account auto-approval)", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "message": { "type": "string" }, "counts": { "type": "object", "properties": { "create": { "type": "integer" }, "update": { "type": "integer" }, "cancel": { "type": "integer" }, "delete": { "type": "integer" } }, "additionalProperties": false }, "auth_capacity_fit": { "type": [ "string", "null" ] }, "capacity_warnings": { "type": "array", "items": { "type": "object", "properties": { "resource_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "severity": { "type": "string" }, "detail": { "type": "string" } }, "additionalProperties": false } }, "posture_reason": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "Validation failed or forbidden parameter", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_privileges, insufficient_scope (with a Bearer challenge naming the scope) or account_ineligible", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found in this account", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Dependency unavailable; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "202": { "description": "Staged; waiting for approval in the app", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "message": { "type": "string" }, "counts": { "type": "object", "properties": { "create": { "type": "integer" }, "update": { "type": "integer" }, "cancel": { "type": "integer" }, "delete": { "type": "integer" } }, "additionalProperties": false }, "auth_capacity_fit": { "type": [ "string", "null" ] }, "capacity_warnings": { "type": "array", "items": { "type": "object", "properties": { "resource_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "severity": { "type": "string" }, "detail": { "type": "string" } }, "additionalProperties": false } }, "posture_reason": { "type": "string" } }, "additionalProperties": false } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "change_reason": { "type": "string" }, "time_zone": { "type": [ "string", "null" ] }, "appointments_to_create": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "description": { "type": "string" }, "start_utc": { "type": "string", "format": "date-time" }, "end_utc": { "type": "string", "format": "date-time" }, "resource_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "offering_id": { "type": [ "string", "null" ], "format": "uuid" }, "notes": { "type": [ "string", "null" ] }, "subjects": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "role_name": { "type": "string" }, "resource_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "replaces_appointment_id": { "type": [ "string", "null" ], "format": "uuid" }, "recurrence": { "type": [ "object", "null" ], "properties": { "frequency": { "type": "string" }, "days_of_week": { "type": [ "array", "null" ], "items": { "type": "string" } }, "interval": { "type": "integer" }, "monthly_mode": { "type": [ "string", "null" ] }, "until_utc": { "type": [ "string", "null" ], "format": "date-time" }, "count": { "type": [ "integer", "null" ] } }, "additionalProperties": false } }, "additionalProperties": false } }, "appointments_to_update": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "appointment_id": { "type": "string", "format": "uuid" }, "occurrence_start_utc": { "type": [ "string", "null" ], "format": "date-time" }, "new_start_date": { "type": [ "string", "null" ] }, "new_start_time": { "type": [ "string", "null" ] }, "new_end_time": { "type": [ "string", "null" ] }, "new_description": { "type": [ "string", "null" ] }, "new_resource_ids": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" } }, "new_offering_id": { "type": [ "string", "null" ], "format": "uuid" }, "new_notes": { "type": [ "string", "null" ] }, "update_reason": { "type": [ "string", "null" ] } }, "additionalProperties": false } }, "appointments_to_cancel": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "appointment_id": { "type": "string", "format": "uuid" }, "occurrence_start_utc": { "type": [ "string", "null" ], "format": "date-time" }, "cancellation_reason": { "type": [ "string", "null" ] } }, "additionalProperties": false } }, "appointments_to_delete": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "appointment_id": { "type": "string", "format": "uuid" }, "occurrence_start_utc": { "type": [ "string", "null" ], "format": "date-time" }, "delete_reason": { "type": [ "string", "null" ] } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Replays within this connection return the stored result; a reused key with a different body is refused." } ] } }, "/v1/availability/request": { "post": { "operationId": "manage_availability", "summary": "manage availability", "description": "Propose changes to one person\u0027s working hours \u2014 add slots, block slots, or end, delete, suspend or replace an existing\nrecurring pattern (at most 25 changes per request). The proposal is STAGED: it waits for approval in eScheduleIt unless the\naccount auto-approves that kind of change. Check check_resource_working_schedule first to see what is already there, and\nquote the returned request_id to the user.", "tags": [ "availability" ], "security": [ { "oauth2": [ "eschedule:write" ] } ], "x-required-privileges": [ "CreateAvailability", "UpdateAvailability", "DeleteAvailability" ], "x-mcp-tool": "manage_availability", "x-posture": "staged", "responses": { "200": { "description": "Applied immediately (account auto-approval)", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "message": { "type": "string" }, "counts": { "type": "object", "properties": { "create": { "type": "integer" }, "update": { "type": "integer" }, "cancel": { "type": "integer" }, "delete": { "type": "integer" } }, "additionalProperties": false }, "auth_capacity_fit": { "type": [ "string", "null" ] }, "capacity_warnings": { "type": "array", "items": { "type": "object", "properties": { "resource_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "severity": { "type": "string" }, "detail": { "type": "string" } }, "additionalProperties": false } }, "posture_reason": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "Validation failed or forbidden parameter", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_privileges, insufficient_scope (with a Bearer challenge naming the scope) or account_ineligible", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found in this account", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Dependency unavailable; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "202": { "description": "Staged; waiting for approval in the app", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "message": { "type": "string" }, "counts": { "type": "object", "properties": { "create": { "type": "integer" }, "update": { "type": "integer" }, "cancel": { "type": "integer" }, "delete": { "type": "integer" } }, "additionalProperties": false }, "auth_capacity_fit": { "type": [ "string", "null" ] }, "capacity_warnings": { "type": "array", "items": { "type": "object", "properties": { "resource_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "severity": { "type": "string" }, "detail": { "type": "string" } }, "additionalProperties": false } }, "posture_reason": { "type": "string" } }, "additionalProperties": false } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "resource_id": { "type": "string", "format": "uuid" }, "update_reason": { "type": "string" }, "time_zone": { "type": [ "string", "null" ] }, "slots_to_add": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "start_date_time": { "type": "string", "format": "date-time" }, "end_date_time": { "type": "string", "format": "date-time" }, "recurrence": { "type": [ "object", "null" ], "properties": { "frequency": { "type": "string" }, "days_of_week": { "type": [ "array", "null" ], "items": { "type": "string" } }, "interval": { "type": "integer" }, "monthly_mode": { "type": [ "string", "null" ] }, "until_utc": { "type": [ "string", "null" ], "format": "date-time" }, "count": { "type": [ "integer", "null" ] } }, "additionalProperties": false }, "notes": { "type": [ "string", "null" ] } }, "additionalProperties": false } }, "slots_to_block": { "type": [ "array", "null" ], "items": { "$ref": "#/properties/slots_to_add/items" } }, "pattern_operations": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "operation": { "type": "string" }, "availability_id": { "type": "string", "format": "uuid" }, "effective_from_utc": { "type": [ "string", "null" ], "format": "date-time" }, "resume_from_utc": { "type": [ "string", "null" ], "format": "date-time" }, "replacement": { "type": [ "object", "null" ], "properties": { "start_date_time": { "type": "string", "format": "date-time" }, "end_date_time": { "type": "string", "format": "date-time" }, "recurrence": { "$ref": "#/properties/slots_to_add/items/properties/recurrence" }, "notes": { "type": [ "string", "null" ] } }, "additionalProperties": false } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Replays within this connection return the stored result; a reused key with a different body is refused." } ] } }, "/v1/resources/changes": { "post": { "operationId": "manage_resources", "summary": "manage resources", "description": "Propose changes to people (staff or clients) \u2014 create, update or delete, one batch per request (at most 25). The proposal is\nSTAGED: it waits for approval in eScheduleIt unless the account auto-approves that kind of change. Quote the returned\nrequest_id to the user so they can find it.", "tags": [ "people" ], "security": [ { "oauth2": [ "eschedule:write" ] } ], "x-required-privileges": [ "CreateResource", "UpdateResource", "DeleteResource" ], "x-mcp-tool": "manage_resources", "x-posture": "staged", "responses": { "200": { "description": "Applied immediately (account auto-approval)", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "message": { "type": "string" }, "counts": { "type": "object", "properties": { "create": { "type": "integer" }, "update": { "type": "integer" }, "cancel": { "type": "integer" }, "delete": { "type": "integer" } }, "additionalProperties": false }, "auth_capacity_fit": { "type": [ "string", "null" ] }, "capacity_warnings": { "type": "array", "items": { "type": "object", "properties": { "resource_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "severity": { "type": "string" }, "detail": { "type": "string" } }, "additionalProperties": false } }, "posture_reason": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "Validation failed or forbidden parameter", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_privileges, insufficient_scope (with a Bearer challenge naming the scope) or account_ineligible", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found in this account", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Dependency unavailable; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "202": { "description": "Staged; waiting for approval in the app", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "message": { "type": "string" }, "counts": { "type": "object", "properties": { "create": { "type": "integer" }, "update": { "type": "integer" }, "cancel": { "type": "integer" }, "delete": { "type": "integer" } }, "additionalProperties": false }, "auth_capacity_fit": { "type": [ "string", "null" ] }, "capacity_warnings": { "type": "array", "items": { "type": "object", "properties": { "resource_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "severity": { "type": "string" }, "detail": { "type": "string" } }, "additionalProperties": false } }, "posture_reason": { "type": "string" } }, "additionalProperties": false } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "change_reason": { "type": "string" }, "resources_to_create": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "active": { "type": "boolean" }, "preferred_language": { "type": [ "string", "null" ] }, "preferred_contact_method": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "contacts": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "type": { "type": "string" }, "value": { "type": "string" } }, "additionalProperties": false } }, "tags": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "additionalProperties": false } }, "resources_to_update": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "resource_id": { "type": "string", "format": "uuid" }, "new_name": { "type": [ "string", "null" ] }, "new_description": { "type": [ "string", "null" ] }, "new_active": { "type": [ "boolean", "null" ] }, "new_preferred_language": { "type": [ "string", "null" ] }, "new_preferred_contact_method": { "type": [ "string", "null" ] }, "new_timezone": { "type": [ "string", "null" ] }, "contacts_to_add": { "type": [ "array", "null" ], "items": { "$ref": "#/properties/resources_to_create/items/properties/contacts/items" } }, "contact_ids_to_remove": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" } }, "tags_to_add": { "type": [ "array", "null" ], "items": { "type": "string" } }, "tags_to_remove": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "additionalProperties": false } }, "resources_to_delete": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "resource_id": { "type": "string", "format": "uuid" }, "deletion_reason": { "type": [ "string", "null" ] } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Replays within this connection return the stored result; a reused key with a different body is refused." } ] } }, "/v1/tasks/changes": { "post": { "operationId": "manage_tasks", "summary": "manage tasks", "description": "Propose task changes \u2014 create, update or delete, one batch per request (at most 25). The proposal is STAGED: it waits for\napproval in eScheduleIt unless the account auto-approves that kind of change. Quote the returned request_id to the user so\nthey can find it.", "tags": [ "tasks" ], "security": [ { "oauth2": [ "eschedule:write" ] } ], "x-required-privileges": [ "CreateTask", "UpdateTask", "DeleteTask" ], "x-mcp-tool": "manage_tasks", "x-posture": "staged", "responses": { "200": { "description": "Applied immediately (account auto-approval)", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "message": { "type": "string" }, "counts": { "type": "object", "properties": { "create": { "type": "integer" }, "update": { "type": "integer" }, "cancel": { "type": "integer" }, "delete": { "type": "integer" } }, "additionalProperties": false }, "auth_capacity_fit": { "type": [ "string", "null" ] }, "capacity_warnings": { "type": "array", "items": { "type": "object", "properties": { "resource_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "severity": { "type": "string" }, "detail": { "type": "string" } }, "additionalProperties": false } }, "posture_reason": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "Validation failed or forbidden parameter", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_privileges, insufficient_scope (with a Bearer challenge naming the scope) or account_ineligible", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found in this account", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Dependency unavailable; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "202": { "description": "Staged; waiting for approval in the app", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "message": { "type": "string" }, "counts": { "type": "object", "properties": { "create": { "type": "integer" }, "update": { "type": "integer" }, "cancel": { "type": "integer" }, "delete": { "type": "integer" } }, "additionalProperties": false }, "auth_capacity_fit": { "type": [ "string", "null" ] }, "capacity_warnings": { "type": "array", "items": { "type": "object", "properties": { "resource_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "severity": { "type": "string" }, "detail": { "type": "string" } }, "additionalProperties": false } }, "posture_reason": { "type": "string" } }, "additionalProperties": false } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "change_reason": { "type": "string" }, "tasks_to_create": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "on_utc": { "type": [ "string", "null" ], "format": "date-time" }, "expected_utc": { "type": [ "string", "null" ], "format": "date-time" }, "due_utc": { "type": [ "string", "null" ], "format": "date-time" }, "task_resources": { "type": "array", "items": { "type": "object", "properties": { "resource_id": { "type": "string", "format": "uuid" }, "status": { "type": [ "string", "null" ] }, "on_utc": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": false } } }, "additionalProperties": false } }, "tasks_to_update": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "task_id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "expected_utc": { "type": [ "string", "null" ], "format": "date-time" }, "due_utc": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": false } }, "tasks_to_delete": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" } } }, "additionalProperties": false } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Replays within this connection return the stored result; a reused key with a different body is refused." } ] } }, "/v1/assignments/propose": { "post": { "operationId": "propose_assignment", "summary": "propose assignment", "description": "For an open demand entry (a client needing a standing assignment), have eScheduleIt score candidates and create an assignment proposal \u2014 optionally preferring one staff member. The proposal waits for approval unless the account auto-approves assignments. Scores are not returned; the approver sees them in the app.", "tags": [ "assignments" ], "security": [ { "oauth2": [ "eschedule:write" ] } ], "x-required-privileges": [ "engagement.view", "engagement.edit" ], "x-mcp-tool": "propose_assignment", "x-posture": "staged", "responses": { "200": { "description": "Applied immediately (account auto-approval)", "content": { "application/json": { "schema": { "type": "object", "properties": { "outcome": { "type": "string" }, "status": { "type": "string" }, "reason": { "type": [ "string", "null" ] }, "proposal_id": { "type": [ "string", "null" ], "format": "uuid" }, "demand_entry_id": { "type": "string", "format": "uuid" }, "beneficiary_resource_id": { "type": [ "string", "null" ], "format": "uuid" }, "coverage_role": { "type": [ "string", "null" ] }, "budget_exhausted": { "type": "boolean" }, "preferred_performer_included": { "type": [ "boolean", "null" ] }, "candidate_count": { "type": "integer" } }, "additionalProperties": false } } } }, "400": { "description": "Validation failed or forbidden parameter", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_privileges, insufficient_scope (with a Bearer challenge naming the scope) or account_ineligible", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found in this account", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Dependency unavailable; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "202": { "description": "Staged; waiting for approval in the app", "content": { "application/json": { "schema": { "type": "object", "properties": { "outcome": { "type": "string" }, "status": { "type": "string" }, "reason": { "type": [ "string", "null" ] }, "proposal_id": { "type": [ "string", "null" ], "format": "uuid" }, "demand_entry_id": { "type": "string", "format": "uuid" }, "beneficiary_resource_id": { "type": [ "string", "null" ], "format": "uuid" }, "coverage_role": { "type": [ "string", "null" ] }, "budget_exhausted": { "type": "boolean" }, "preferred_performer_included": { "type": [ "boolean", "null" ] }, "candidate_count": { "type": "integer" } }, "additionalProperties": false } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "demand_entry_id": { "type": "string", "format": "uuid" }, "preferred_performer_resource_id": { "type": [ "string", "null" ], "format": "uuid" }, "rationale": { "type": "string" } }, "additionalProperties": false } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Replays within this connection return the stored result; a reused key with a different body is refused." } ] } }, "/v1/authorizations/recovery-plan": { "get": { "operationId": "propose_utilization_recovery_plan", "summary": "propose utilization recovery plan", "description": "A suggested plan for recovering under-used authorized hours over the chosen horizon: which beneficiaries are behind, roughly how much to schedule, and which staff have the capacity to take it. Read-only advice \u2014 nothing is booked, and every suggestion still has to go through find_open_appointment_slots.", "tags": [ "authorizations" ], "security": [ { "oauth2": [ "eschedule:read" ] } ], "x-required-privileges": [ "authz.reports.utilization.view" ], "x-mcp-tool": "propose_utilization_recovery_plan", "x-posture": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation failed or forbidden parameter", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_privileges, insufficient_scope (with a Bearer challenge naming the scope) or account_ineligible", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found in this account", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Dependency unavailable; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "parameters": [ { "name": "horizon", "in": "query", "required": false, "schema": { "type": "string" }, "style": "form", "explode": true }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Ignored on reads." } ] } }, "/v1/appointments": { "get": { "operationId": "search_appointments", "summary": "search appointments", "description": "Appointments for one person (resource_id) in a window of at most 180 days. Returns start/end in UTC and in the requested\ntime zone, offering, status (Confirmed, Pending, Cancelled\u2026), recurrence flag, and the other participants by id, name,\nstatus and tags \u2014 no contact details (use lookup_resource for those). Holidays overlapping the window are included.", "tags": [ "appointments" ], "security": [ { "oauth2": [ "eschedule:read" ] } ], "x-required-privileges": [ "SearchAppointment" ], "x-mcp-tool": "search_appointments", "x-posture": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "total_count": { "type": "integer" }, "timezone_for_results": { "type": [ "string", "null" ] }, "appointments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "description": { "type": [ "string", "null" ] }, "offering_name": { "type": [ "string", "null" ] }, "offering_id": { "type": [ "string", "null" ], "format": "uuid" }, "allow_overbooking": { "type": "boolean" }, "notes": { "type": [ "string", "null" ] }, "start_utc": { "type": "string", "format": "date-time" }, "end_utc": { "type": "string", "format": "date-time" }, "start_in_timezone": { "type": "string", "format": "date-time" }, "end_in_timezone": { "type": "string", "format": "date-time" }, "duration": { "$comment": "Represents a System.TimeSpan value.", "type": "string", "pattern": "^-?(\\d\u002B\\.)?\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,7})?$" }, "status": { "type": "string" }, "is_recurring": { "type": "boolean" }, "booked_resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } } }, "additionalProperties": false } }, "holidays": { "type": "array", "items": { "type": "object", "properties": { "holiday_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "start_utc": { "type": "string", "format": "date-time" }, "end_utc": { "type": "string", "format": "date-time" }, "start_in_timezone": { "type": "string", "format": "date-time" }, "end_in_timezone": { "type": "string", "format": "date-time" }, "time_zone_id": { "type": [ "string", "null" ] } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "400": { "description": "Validation failed or forbidden parameter", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_privileges, insufficient_scope (with a Bearer challenge naming the scope) or account_ineligible", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found in this account", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Dependency unavailable; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "parameters": [ { "name": "resource_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "style": "form", "explode": true }, { "name": "start_utc", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "style": "form", "explode": true }, { "name": "end_utc", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "style": "form", "explode": true }, { "name": "timezone", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] }, "style": "form", "explode": true }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Ignored on reads." } ] } }, "/v1/offerings": { "get": { "operationId": "search_offerings", "summary": "search offerings", "description": "Offerings (services) the account schedules, by name/description search with fuzzy matching and optional enabled/public filters. Paged, 1-based, at most 50 per page. Returns each offering\u0027s duration and the tag and people requirements it imposes, which find_open_appointment_slots then honours in offering mode.", "tags": [ "offerings" ], "security": [ { "oauth2": [ "eschedule:read" ] } ], "x-required-privileges": [ "SearchOffering" ], "x-mcp-tool": "search_offerings", "x-posture": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "total_count": { "type": "integer" }, "page": { "type": "integer" }, "page_size": { "type": "integer" }, "offerings": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "duration": { "$comment": "Represents a System.TimeSpan value.", "type": "string", "pattern": "^-?(\\d\u002B\\.)?\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,7})?$" }, "is_public": { "type": "boolean" }, "enabled": { "type": "boolean" }, "proximity_type": { "type": [ "string", "null" ] }, "proximity_miles": { "type": [ "number", "null" ] }, "required_tags": { "type": "array", "items": { "type": "object", "properties": { "tag_id": { "type": "string", "format": "uuid" }, "tag_name": { "type": [ "string", "null" ] }, "operand": { "type": "string" }, "value1": { "type": "integer" }, "value2": { "type": [ "integer", "null" ] } }, "additionalProperties": false } }, "required_resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "additionalProperties": false } }, "match_score": { "type": [ "number", "null" ] } }, "additionalProperties": false } }, "fuzzy_applied": { "type": "boolean" }, "ambiguous": { "type": "boolean" }, "did_you_mean": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "name": { "type": "string" }, "score": { "type": "number" }, "match_source": { "type": [ "string", "null" ] } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "400": { "description": "Validation failed or forbidden parameter", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_privileges, insufficient_scope (with a Bearer challenge naming the scope) or account_ineligible", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found in this account", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Dependency unavailable; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "parameters": [ { "name": "query", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] }, "style": "form", "explode": true }, { "name": "enabled", "in": "query", "required": false, "schema": { "type": [ "boolean", "null" ] }, "style": "form", "explode": true }, { "name": "is_public", "in": "query", "required": false, "schema": { "type": [ "boolean", "null" ] }, "style": "form", "explode": true }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "style": "form", "explode": true }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer" }, "style": "form", "explode": true }, { "name": "match_threshold", "in": "query", "required": false, "schema": { "type": [ "number", "null" ] }, "style": "form", "explode": true }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Ignored on reads." } ] } }, "/v1/tags": { "get": { "operationId": "search_tags", "summary": "search tags", "description": "Tags (skills, credentials, regions, groups) used to label people, with the people carrying each tag by id and name. Fuzzy search, paged, 1-based, at most 50 per page. Use it to turn a phrase the user says \u2014 \u0027a Spanish speaking RBT\u0027 \u2014 into the tag ids that find_open_appointment_slots takes.", "tags": [ "tags" ], "security": [ { "oauth2": [ "eschedule:read" ] } ], "x-required-privileges": [ "SearchTag" ], "x-mcp-tool": "search_tags", "x-posture": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "total_count": { "type": "integer" }, "page": { "type": "integer" }, "page_size": { "type": "integer" }, "tags": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "color_code": { "type": [ "string", "null" ] }, "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } }, "fuzzy_applied": { "type": "boolean" }, "ambiguous": { "type": "boolean" }, "did_you_mean": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "name": { "type": "string" }, "score": { "type": "number" }, "match_source": { "type": [ "string", "null" ] } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "400": { "description": "Validation failed or forbidden parameter", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_privileges, insufficient_scope (with a Bearer challenge naming the scope) or account_ineligible", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found in this account", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Dependency unavailable; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "parameters": [ { "name": "query", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] }, "style": "form", "explode": true }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "style": "form", "explode": true }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer" }, "style": "form", "explode": true }, { "name": "match_threshold", "in": "query", "required": false, "schema": { "type": [ "number", "null" ] }, "style": "form", "explode": true }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Ignored on reads." } ] } }, "/v1/tasks": { "get": { "operationId": "search_tasks", "summary": "search tasks", "description": "Tasks in the account, optionally for one person, by text search, status (Not Started, In Progress, Completed, Blocked, Cancelled, Overdue, Pending Review, Reviewed) and a date window on the calendar, expected or due date. Paged, 1-based, at most 50 per page.", "tags": [ "tasks" ], "security": [ { "oauth2": [ "eschedule:read" ] } ], "x-required-privileges": [ "SearchTask" ], "x-mcp-tool": "search_tasks", "x-posture": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "total_count": { "type": "integer" }, "page": { "type": "integer" }, "page_size": { "type": "integer" }, "timezone_for_results": { "type": [ "string", "null" ] }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "on_utc": { "type": "string", "format": "date-time" }, "on_in_timezone": { "type": [ "string", "null" ], "format": "date-time" }, "expected_utc": { "type": [ "string", "null" ], "format": "date-time" }, "expected_in_timezone": { "type": [ "string", "null" ], "format": "date-time" }, "due_utc": { "type": [ "string", "null" ], "format": "date-time" }, "due_in_timezone": { "type": [ "string", "null" ], "format": "date-time" }, "is_recurring": { "type": "boolean" }, "priority": { "type": "integer" }, "task_resources": { "type": "array", "items": { "type": "object", "properties": { "resource_id": { "type": "string", "format": "uuid" }, "resource_name": { "type": "string" }, "status": { "type": "string" }, "on_utc": { "type": "string", "format": "date-time" }, "on_in_timezone": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": false } }, "match_score": { "type": [ "number", "null" ] } }, "additionalProperties": false } }, "fuzzy_applied": { "type": "boolean" }, "ambiguous": { "type": "boolean" }, "did_you_mean": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "name": { "type": "string" }, "score": { "type": "number" }, "match_source": { "type": [ "string", "null" ] } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "400": { "description": "Validation failed or forbidden parameter", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_privileges, insufficient_scope (with a Bearer challenge naming the scope) or account_ineligible", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found in this account", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Dependency unavailable; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "parameters": [ { "name": "resource_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" }, "style": "form", "explode": true }, { "name": "query", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] }, "style": "form", "explode": true }, { "name": "date_range_type", "in": "query", "required": false, "schema": { "type": "string" }, "style": "form", "explode": true }, { "name": "start_utc", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" }, "style": "form", "explode": true }, { "name": "end_utc", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" }, "style": "form", "explode": true }, { "name": "statuses", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "timezone", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] }, "style": "form", "explode": true }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "style": "form", "explode": true }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer" }, "style": "form", "explode": true }, { "name": "match_threshold", "in": "query", "required": false, "schema": { "type": [ "number", "null" ] }, "style": "form", "explode": true }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Ignored on reads." } ] } }, "/v1/announcements": { "post": { "operationId": "send_announcement", "summary": "send announcement", "description": "Propose an SMS or email announcement to everyone carrying the given tags. It is QUEUED FOR APPROVAL in eScheduleIt and never sent directly, unless the account auto-approves announcements. Sending identical content twice creates one announcement, not two.", "tags": [ "messaging" ], "security": [ { "oauth2": [ "eschedule:messaging" ] } ], "x-required-privileges": [ "SendAnnouncement" ], "x-mcp-tool": "send_announcement", "x-posture": "staged", "responses": { "200": { "description": "Applied immediately (account auto-approval)", "content": { "application/json": { "schema": { "type": "object", "properties": { "announcement_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "intended_count": { "type": "integer" }, "sms_candidates": { "type": "integer" }, "email_candidates": { "type": "integer" }, "unreachable": { "type": "integer" }, "already_existed": { "type": "boolean" }, "tag_suggestions": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "Validation failed or forbidden parameter", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, expired or revoked token", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_privileges, insufficient_scope (with a Bearer challenge naming the scope) or account_ineligible", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found in this account", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Dependency unavailable; see Retry-After", "content": { "application/problem\u002Bjson": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "202": { "description": "Staged; waiting for approval in the app", "content": { "application/json": { "schema": { "type": "object", "properties": { "announcement_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "intended_count": { "type": "integer" }, "sms_candidates": { "type": "integer" }, "email_candidates": { "type": "integer" }, "unreachable": { "type": "integer" }, "already_existed": { "type": "boolean" }, "tag_suggestions": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" } }, "additionalProperties": false } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tag_names": { "type": "array", "items": { "type": "string" } }, "channel_policy": { "type": "string" }, "sms_body": { "type": [ "string", "null" ] }, "email_subject": { "type": [ "string", "null" ] }, "email_body": { "type": [ "string", "null" ] } }, "additionalProperties": false } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Replays within this connection return the stored result; a reused key with a different body is refused." } ] } } }, "components": { "securitySchemes": { "oauth2": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://auth.eschedule.it/connect/authorize", "tokenUrl": "https://auth.eschedule.it/connect/token", "refreshUrl": "https://auth.eschedule.it/connect/token", "scopes": { "eschedule:read": "Read schedules, people, availability, authorizations and tasks in the connected account", "eschedule:write": "Propose changes (staged for approval unless the account allows automatic approval)", "eschedule:messaging": "Propose announcements to people carrying selected tags" } } }, "x-resource-indicator": "https://mcp.eschedule.it/", "x-pkce": "S256 required" } }, "schemas": { "Problem": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "correlation_id": { "type": "string" }, "required_scope": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "security": [ { "oauth2": [ "eschedule:read" ] } ] }