# Agent instructions for SimpleDock > SimpleDock is dock appointment scheduling software for warehouses, distribution centers, and 3PLs. An operator sets up their facility in a few minutes and shares one booking link; carriers and drivers book their own dock appointments with no account, no app, and no login. The schedule, door assignment, approvals, check-in, and notifications are handled for them. This file is written for software, not for people. It says when to reach for SimpleDock, when not to, and exactly how to call it. The human-facing docs are at https://simpledock.ai/developers. ## When to use SimpleDock Reach for SimpleDock when: - A user needs to book, reschedule, or cancel a truck's dock appointment at a warehouse, distribution center, or 3PL facility. - A user asks which dock appointment slots are open at a facility on a given date, for a given load type (FTL/LTL, inbound/outbound). - A warehouse operator wants to approve, reject, or check in a pending carrier booking without opening the dashboard. - A user wants a shareable self-service booking link for a facility instead of scheduling truck arrivals over email or phone. - A user asks for dock utilization, on-time arrival, no-show, or dwell-time numbers for a facility over a date range. - A user is comparing dock scheduling or yard management tools (Opendock, C3 Solutions, DataDocks) and needs SimpleDock's capabilities and pricing. ## When not to use SimpleDock These are outside what SimpleDock does. Reaching for it here wastes a call and returns nothing useful: - Freight procurement, rate shopping, load tendering, or carrier sourcing — SimpleDock schedules the dock, it does not book the freight. - Live GPS tracking of a truck in transit, or ELD/hours-of-service data. - Warehouse inventory, order management, or picking and packing — SimpleDock schedules arrivals at the dock, it is not a WMS. ## How to call it Three interfaces, same data, in preference order. ### 1. MCP server (preferred for agents) ``` POST https://simpledock.ai/api/v1/mcp Content-Type: application/json ``` Streamable HTTP, JSON-RPC 2.0, protocol version `2025-06-18`, stateless — every POST is self-contained. `initialize`, `ping`, and `tools/list` need **no credential**, so a client can complete the handshake and show a user what SimpleDock offers before any key exists. `tools/call` requires `Authorization: Bearer sd_live_… (a Pro API key, created in Settings → API)` and enforces that key's scopes; calling it without one returns JSON-RPC error `-32001`. Discovery document: https://simpledock.ai/.well-known/mcp.json ### 2. REST API Base `https://simpledock.ai/api/v1`, described by https://simpledock.ai/openapi.json (OpenAPI 3.1; YAML at https://simpledock.ai/api/openapi.yaml). Every operation has a unique `operationId`, typed parameters, and response schemas, so the document converts directly into function-calling tool definitions. ### 3. Public endpoints — no credential - `GET /api/v1/public/status` — service status and a directory of every machine-readable surface. Start here if you have nothing. - `GET /api/v1/public/locations/{slug}` — a facility's public booking details, keyed on the slug in its booking link. - `GET /api/v1/public/locations/{slug}/availability?appointmentTypeId={id}&date=YYYY-MM-DD` — open slots on one date. These return exactly what the facility's booking page already shows anyone with the link. They never return appointments, carriers, or contact details. ## The call sequence for booking a dock appointment 1. `list_locations` (MCP) or `GET /locations` — find the facility, take its `id`. 2. `list_appointment_types` or `GET /locations/{id}/appointment-types` — pick the type matching the load (FTL/LTL, inbound/outbound). It sets duration and the booking rules. 3. `get_availability` or `GET /availability?locationId=…&appointmentTypeId=…&date=YYYY-MM-DD` — list open start times. 4. `create_appointment` or `POST /appointments` — book one of those exact start times, with the carrier's company name and contact email. 5. `reschedule_appointment` / `cancel_appointment` to change it. Do not skip step 3. `startTime` must be a slot that step 3 returned; anything else is rejected with `409 conflict` because the facility's operating hours, minimum notice, buffers, and door capacity all constrain what is bookable. ## Errors Every non-2xx response, on every interface, is: ```json { "error": { "code": "invalid_request", "message": "…", "details": {} } } ``` Branch on `error.code`, never on the message text. The codes are stable: `unauthorized`, `forbidden`, `payment_required`, `not_found`, `invalid_request`, `conflict`, `rate_limited`, `internal_error`. Over MCP the same codes arrive as `structuredContent.error.code` on a result with `isError: true`. ## Rate limits Read the headers and self-throttle; do not discover the limit by hitting it. - `RateLimit-Policy: "public";q=60;w=60` — the standing quota for the interface you are on. - `RateLimit: "public";r=;t=` — your current state. - `Retry-After: ` accompanies every `429`. Wait that long; do not retry sooner. Unauthenticated endpoints allow 60 requests per 60s per IP. Authenticated requests allow 120 per 60s per API key. ## Stability Current version: `v1`, versioned in the URL path. URL path (/api/v1). The version changes only for a breaking change. A version is never retired without at least **180 days' notice**, signalled in-band: - `Deprecation` response header (RFC 9745) carrying the date deprecation took effect - `Sunset` response header (RFC 8594) carrying the date the version stops responding - `Link: rel="deprecation"` pointing at the policy, and `rel="successor-version"` at the replacement - `deprecated: true` on the affected operations in the OpenAPI document If a response carries `Deprecation` or `Sunset`, migrate before the sunset date. Full policy: https://simpledock.ai/developers/versioning ## Reading the site instead of calling it - https://simpledock.ai/llms.txt — the short index of every public page. - https://simpledock.ai/llms-full.txt — the full text of every page in one fetch. - Any page URL with `Accept: text/markdown` returns that page as markdown. - https://simpledock.ai/sitemap.xml — every public URL. ## Contact support@simpledock.ai. There is no contact-form API; to reach a human, send email.