Dock Optimizer REST API

📖 Overview

The REST surface is a thin, plain-JSON view over the same data the MCP server exposes. Every endpoint is GET (read-only); for writes, use the MCP tools/call surface. Same auth, same rate-limit bucket, same audit trail — the two surfaces share one credential.

🔐 Authentication

All API requests require a Bearer token in the Authorization header. API keys are organization-specific — an admin in your organization generates them from the Integration Hub → Agent Keys tab. Each key is scoped to that organization's data.

curl -X POST https://dockoptimizer.com/api/mcp/v1/message \
  -H "Authorization: Bearer do_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Key Scopes

Scopes gate the write-capable RPC methods. Discovery (tools/list and resources/list) is always allowed so a client can introspect the server regardless of what it's permitted to do.

Capability Gating (Fine-Grained Access)

Scopes gate methods; capabilities gate individual tools. Sensitive tool families check the key's agentConfig.capabilities[] array and return SCOPE_DENIED if the capability is missing. Use this to keep a booking agent from touching stock, or an inventory agent from moving appointments.

Configure per key via POST /api/agent-keys/{id}/update-metadata with an agentConfig payload:

{
  "version": 1,
  "capabilities": ["appointments", "inventory"],
  "defaultFacilityId": 19,
  "notes": "Zo booking agent, prod"
}

Environment Tagging

Keys may carry an environment tag of staging or production. The auth filter compares that tag against the server's ASPNETCORE_ENVIRONMENT on every request — a tagged key whose environment doesn't match the server is rejected with 401. Tenant keys may leave the tag blank for legacy compatibility.

Key Identity & Metadata

Every key carries identifying metadata so admins can distinguish one agent from another on the dashboard and in audit logs:

Rotation & Revocation

• Rotate regularly — Call POST /api/agent-keys/{id}/regenerate to atomically revoke the old token and issue a new one with the same metadata. Recommended cadence: 90 days for production agents, 30 days for shared developer keys.
• Revoke immediately if a token is ever logged, committed, or leaves the owner's machine. POST /api/agent-keys/{id}/revoke takes effect on the next request.
• Never embed keys in client-side code — browsers, mobile apps, and public repos are not safe hosts. Agents must call the API from a server or trusted workstation.

📜 OpenAPI 3 Spec + Explorer

Partners generating typed SDKs can point their codegen at the machine-readable spec; everyone else can poke at endpoints interactively in the Swagger UI.

🛣️ Endpoints

All paths return application/json. Filter, sort, and paginate via query parameters; combine with If-None-Match for cheap polling.

Response Headers

Example

curl -H "Authorization: Bearer do_live_..." \
  "https://dockoptimizer.com/api/v1/appointments?date=2026-04-22&facilityId=18"

Polling with ETags

curl -H "Authorization: Bearer do_live_..." \
     -H "If-None-Match: \"abc123\"" \
  "https://dockoptimizer.com/api/v1/facilities"
# Returns 304 Not Modified if the response would be identical.

Delta sync

For long-running sync loops, use /api/v1/appointments/changed?since=… or /api/v1/loads/changed?since=… with the nextSince cursor returned in the previous response. This avoids re-pulling unchanged records on every poll.

Freight visibility

The load endpoints return exactly what your organization can see in the app: loads you posted (shipper side) plus loads your carrier account has bid on, including awarded freight (carrier side). Brokerage fields — customerRate, customerName, margin — appear only on your own loads when your org is on the Pro TMS tier and has declared itself a broker; carrierTakeHome appears only on your own bids.

⚡ Outbound webhooks

Instead of polling /loads/changed, org admins can register webhook endpoints (Load Board → Webhooks) and receive a signed POST on every load lifecycle transition: load.posted, load.awarded, load.in_transit, load.delivered, load.settled.

Deliveries time out after 10 seconds and retry with backoff; respond 2xx quickly and process asynchronously. Endpoints that fail repeatedly are disabled automatically and surfaced on the management page.

🔄 Partner TMS sync recipe

The standard integration is a one-time backfill, then webhooks for real-time updates, with the delta cursor as the safety net for anything missed while your endpoint was down.

1 · Backfill — page through everything once

curl -H "Authorization: Bearer do_live_..." \
  "https://dockoptimizer.com/api/v1/loads?limit=200&offset=0"
# Follow rel="next" in the Link header until it disappears.
# Record max(lastModified) across pages — that's your starting cursor.

2 · Stay current — webhooks + the delta cursor

Register a webhook endpoint for real-time pushes. On every webhook you process — and on a timer as a catch-up sweep — advance the cursor:

curl -H "Authorization: Bearer do_live_..." \
  "https://dockoptimizer.com/api/v1/loads/changed?since=2026-06-12T00:00:00Z"
# Response carries nextSince — persist it and pass it back on the next poll.
# Rows include isDeleted so removals replicate too.

3 · Verify webhook signatures

// Node.js — same idea in any language: HMAC-SHA256 the RAW body.
const crypto = require('crypto');
function verify(rawBody, signatureHeader, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret)
    .update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected));
}

4 · Generate a typed client

npx @openapitools/openapi-generator-cli generate \
  -i https://dockoptimizer.com/api/v1/swagger/v1/swagger.json \
  -g typescript-fetch -o ./dock-optimizer-client

Bringing history FROM another TMS instead? Use the guided importer at /TmsImport (CSV/JSON, dry-run preview, idempotent re-runs).

✏️ Writes? Use MCP

The REST surface is intentionally read-only. All mutations — creating appointments, recording inventory, blocking doors — go through the MCP tools/call endpoint. This keeps the REST contract narrow and lets us add idempotency keys, HITL gating, and tool-level capability checks on writes without complicating the REST schema.

❌ Error Handling

The API uses standard JSON-RPC 2.0 error codes alongside HTTP status codes. Error responses include an optional data.hint field with recovery guidance for agents.

RFC 7807 Problem Details (REST + transport-level MCP errors)

Unhandled errors on /api/v1/* and transport-level errors on /api/mcp/* come back as application/problem+json:

{
  "type": "https://dockoptimizer.com/errors/internal",
  "title": "Internal server error",
  "status": 500,
  "detail": "An unexpected error occurred. Our team has been notified.",
  "instance": "/api/v1/appointments",
  "requestId": "8f4d2c1a7b6e4e3f9a0c1b8d2e7f4a9c"
}

JSON-RPC error codes (MCP)

Recovery Hints

Error responses may include a data.hint field with actionable guidance:

{
  "error": {
    "code": -32002,
    "message": "Resource not found or empty result for URI: dock://appointments/99999",
    "data": {
      "hint": "The requested resource returned no data. Check the appointment ID or filters."
    }
  }
}

⚡ Rate Limits

API requests are rate-limited per API key across three windows. The three layers protect against burst traffic, runaway loops, and accidental write storms from a single agent. REST and MCP traffic share the same bucket — the limits below are per key, not per surface.

429 Response Headers

When rate-limited, the API returns HTTP 429 Too Many Requests. The minute-window limiter is a token bucket — the bucket refills continuously. The daily window resets at 00:00 UTC.

Right-sizing Per-Key Limits

Use writeRateLimit on keys that should only make occasional changes (a data-quality agent, a report runner). Leave it null for keys that may legitimately run bursts (a bulk backfill import). The per-minute burst limit still applies either way.

🔑 Key Management

Manage API keys programmatically via the admin endpoints (requires an authenticated admin session cookie — these endpoints are not callable from an agent using its own API key). The same keys work for both REST and MCP traffic.