Circuit API
Circuit (now branded Spoke Dispatch) is a last-mile delivery management platform that helps courier and delivery teams plan multi-stop routes, optimize them, and track drivers in real time. This page is an independent design exercise that asks what a well-designed Circuit API could look like: the resources it would expose, the authentication it would need, and the workflows it could unlock. Below: a hypothetical endpoint design, the technical requirements a production implementation would face, the use cases programmatic access could serve, and where to start if your team needs this kind of access today.
This page is an independent analysis by Supergood of what a well-designed Circuit API could look like. It draws on publicly available information, vendor materials, and general integration experience in this category. Nothing on this page describes an existing Circuit product, and Supergood is not affiliated with or endorsed by the vendor. If the vendor offers an official API, we highly recommend it.
What is Circuit?
Circuit (now branded Spoke Dispatch) is a last-mile delivery management platform that helps courier and delivery teams plan multi-stop routes, optimize them, and track drivers in real time. Dispatchers work in a browser-based planning interface to build and optimize routes, assign stops to drivers, and monitor live progress, while drivers use a mobile app for turn-by-turn navigation, proof of delivery, and status updates. Recipients receive text or email tracking links and dynamic delivery-window notifications, reducing "where is my order?" support calls.
Core capabilities include:
- Route planning and optimization (Plans, Stops, optimized Routes with ETAs, distance, and stop order)
- Driver dispatch and management (driver records, depot assignments, route overrides, live tracking)
- Proof of delivery (photos, signatures, delivery notes, timestamped records for dispute resolution)
- Recipient notifications (tracking links, fixed and dynamic delivery windows, delay and arrival alerts)
- Live Plans and Live Stops for editing already-optimized, distributed plans on the day of delivery
An API for a platform like this would naturally organize around its core data entities:
- Plans, Stops, Unassigned Stops, Live Plans, Live Stops
- Routes (with ETA, travel distance, travel duration, stop order)
- Drivers, Depots
- Operations (long-running optimization and distribution jobs), Webhooks
The Circuit Integration Challenge
Circuit publishes a public REST API, but building a resilient production integration on top of last-mile delivery workflows still involves real friction:
- Asynchronous optimization: Plans must be optimized and distributed before ETAs, route order, and distances exist, integrations have to poll Operations or handle webhooks rather than read results synchronously
- Tiered rate limits: Write endpoints, driver creation, batch imports, and optimization each have distinct per-second and per-minute limits that require careful backoff and queueing
- Live-day mutations: Editing stops after a plan is distributed requires the separate Live Plans and Live Stops surfaces, with different semantics from pre-optimization stops
- Mobile-only signals: Proof of delivery, live driver location, and completion states originate in the driver mobile app and surface through routes rather than a simple data export
- Rebrand drift: The product is migrating from Circuit (getcircuit.com) to Spoke (spoke.com), so base URLs, console links, and docs shift across the transition
- Pagination and consistency: List endpoints page through nextPageToken, and stop/route state changes as drivers progress, so syncs must reconcile against a moving target
What a Circuit API Could Look Like
If Circuit exposed a modern, general-purpose API, the integration challenges above suggest what it would need to get right. This is a design sketch, not documentation of anything that exists today:
- First-class authentication: session handling with support for MFA and enterprise sign-on where the platform uses them
- Consistent resources: normalized JSON schemas and pagination across the platform's core objects
- Reliable writes: idempotency keys and validation that mirrors the platform's own workflow rules
- Entitlement awareness: endpoints scoped to what each customer's licensing actually permits
The endpoint sketches, technical requirements, and use cases below flesh out this hypothetical design.
How AI agents could connect to software like Circuit: MCP servers for software without a public API →
Need This Kind of Access Today?
If your team needs this kind of access today, Supergood builds integrations on request, one customer at a time. We act at the direction of our customers, within the access they already hold. Customers bring their own accounts, licenses, and entitlements. If the vendor offers an official API, we highly recommend it.
- Schedule an Integration Assessment
A 30-minute session to review your product mix, licensing, and authentication model. - Scope the Integration
We design the access pattern around your workflows and entitlements. - Deploy with Monitoring
Go live with continuous monitoring as your platforms evolve.
Potential API Endpoints
Authentication
/authenticateWould authenticate with a Circuit API key using Basic or Bearer auth and establish a session for downstream calls.
Plans
/plansWould list delivery plans with filters for date and status, including drivers and optimization state.
Plans
/create_planWould create a delivery plan for a specific day, then optimize and distribute it to assigned drivers.
Stops
/import_stopsWould batch import stops into a plan with addresses, time windows, and delivery details (up to 1,000 stops per minute).
Routes
/routesWould retrieve optimized routes for a plan with per-stop ETA, travel distance, travel duration, and stop order.
Drivers
/driversWould list drivers with depot assignments, route overrides, and availability for dispatch.
Use Cases
Automate plan creation and route optimization
- Create daily delivery plans and batch-import stops from your OMS or WMS - Trigger optimization and distribution, then poll Operations or webhooks for completion - Pull back optimized routes with ETAs, stop order, and travel distance for downstream systems
Sync delivery status and proof of delivery
- Stream stop completion, photos, signatures, and delivery notes into your records - Reconcile timestamped proof-of-delivery against orders for dispute resolution - Push exception and failed-delivery events to support and retention workflows
Power recipient tracking and notifications
- Surface live driver location and dynamic delivery windows to customer-facing tracking pages - Trigger arrival and delay alerts from route progress - Reduce WISMO contacts by feeding real-time ETAs into your notification stack
Manage drivers and depots programmatically
- Provision and update driver records and depot assignments in bulk - Apply route overrides and rebalance stops across drivers on the day of delivery - Keep driver rosters in sync with your HR and scheduling systems
Connect via No-Code Tools
Automate this platform from the no-code stack you already use.
Technical Requirements
Authentication
Would require circuit API key via Basic auth (apiKey:empty, base64) or Bearer token, managed in a secure session
Connectivity
Would build on circuit/Spoke public REST API (base https://api.getcircuit.com/public/v0.2b) plus authenticated app surfaces
Response format
Normalized JSON across Plans, Stops, Routes, Drivers, and Depots with Content-type application/json on writes
Rate limits
Adaptive throttling tuned to Circuit's tiers: 10 reads/sec, 5 writes/sec, 3 optimizations/min, batch imports per minute
Session management
Would need automatic API key handling, credential rotation, and retry of expired or throttled requests
Data freshness
Near real-time route, stop, and driver-location updates with optional scheduled batch syncs
Security
Encrypted credential vault, scoped access, SOC 2-aligned controls, and audit logging
Webhooks
Subscribe to Spoke webhook events for route, stop, and delivery status changes
Latency
Design target: sub-second reads on cached entities; async optimization handled via Operations polling and callbacks
Throughput
Design target: horizontally scaled workers sized to high-volume daily plans, stop imports, and driver rosters
Reliability
Exponential backoff on 429s, idempotent retries, and pagination via nextPageToken
Versioning
Clear versioning and change management would matter as Circuit evolves
Frequently asked questions
Availability of official interfaces varies by product, plan, and licensing. Many platforms in this category gate access behind partner programs or paid modules, and there is often no broadly available, self-serve public API. Check the vendor's developer resources for current offerings.
The hard parts would be authentication (MFA, session management, enterprise controls), consistent schemas across the platform's products, and write semantics that reconcile the way the platform's own workflows do.
No. This page is an independent analysis by Supergood and is not affiliated with, sponsored by, or endorsed by the vendor. All product names and trademarks belong to their respective owners and are used for identification only. Nothing here documents an actual Circuit product or service.
Supergood acts at the direction of its customers, within the access those customers already have. We respect each customer's agreements with their software vendors, and how those agreements apply to a customer's use is a determination the customer makes. If the vendor offers an official API, we highly recommend it.
Supergood builds managed API access to enterprise software for customers on request, scoped to each customer's own licensing and entitlements. If your team needs programmatic access to a platform like this, schedule an integration assessment to discuss options.