Endpoints to operate on [Plans](/docs/models/plan) resources when it's pending re-optimization and re-distribution. You must use these endpoints to apply the changes when any [Live Stops](#tag/Live-Stops) request returns `pending = true`.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/circuit-live-plans-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Spoke Live Plans API
description: This is the documentation of the Spoke Public API HTTP endpoints.
version: v1
servers:
- url: https://api.spoke.com/public/v1
security:
- BasicAuth: []
tags:
- name: Live Plans
description: 'Endpoints to operate on Plans resources when it''s pending re-optimization and re-distribution.
You must use these endpoints to apply the changes when any Live Stops request returns `pending = true`.'
paths:
/plans/{planId}:reoptimize:
post:
operationId: reoptimizePlan
summary: Re-optimize a plan
tags:
- Live Plans
description: Re-optimize a plan. This endpoint should be used only after updating a live plan. Returns the created operation, which can be polled for the result. Use the returned `id` with the operations endpoints to poll for the result.
requestBody:
content:
application/json:
schema:
description: The request body for reoptimize a plan.
type: object
properties:
optimizationType:
description: The type of optimization to use
default: reorder_changed_stops
type: string
enum:
- reorder_changed_stops
- reorder_all_stops
- redistribute_stops_between_drivers
additionalProperties: false
description: The request body for reoptimize a plan.
parameters:
- schema:
type: string
pattern: ^[a-zA-Z0-9---_]{1,50}$
in: path
name: planId
required: true
description: The plan id
responses:
'200':
description: The created plan_optimization operation.
content:
application/json:
schema:
$ref: '#/components/schemas/operationSchema'
description: The created plan_optimization operation.
'400':
description: ID format is invalid
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message.
code:
type: string
description: The error code.
param:
type: string
description: The parameter that caused the error.
url:
type: string
description: The URL with more information about the error.
required:
- message
description: ID format is invalid
title: The request is invalid
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message.
url:
type: string
description: The URL with more information about the error.
required:
- message
description: Unauthorized
'403':
description: Plan is no longer accessible due to data access restrictions. Upgrade to a plan that supports a longer delivery history period to access it.
content:
application/json:
schema:
type: object
properties:
message:
type: string
enum:
- Plan is no longer accessible due to data access restrictions. Upgrade to a plan that supports a longer delivery history period to access it.
code:
type: string
enum:
- plan_inaccessible
url:
type: string
enum:
- https://dispatch.spoke.com/paywall
required:
- message
- code
- url
description: Plan is no longer accessible due to data access restrictions. Upgrade to a plan that supports a longer delivery history period to access it.
'404':
description: The provided plan id does not exist
content:
application/json:
schema:
type: object
properties:
message:
type: string
enum:
- Plan not found
required:
- message
description: The provided plan id does not exist
title: Plan not found
'409':
description: The plan is not being edited, an optimization is already in progress, there are no drivers, or there is a problem with the depot.
content:
application/json:
schema:
oneOf:
- type: object
properties:
message:
type: string
enum:
- Plan already optimized
code:
type: string
enum:
- plan_already_optimized
required:
- message
- code
title: Plan already optimized
- type: object
properties:
message:
type: string
enum:
- Only `reorder_changed_stops` optimization type is supported when the plan is already distributed.
code:
type: string
enum:
- plan_optimization_not_supported
required:
- message
- code
description: Plan optimization type is not supported.
title: Plan optimization type is not supported
- type: object
properties:
message:
type: string
enum:
- Plan optimization in progress
code:
type: string
enum:
- plan_optimization_in_progress
required:
- message
- code
description: The plan's optimization is in progress.
title: Plan optimization in progress
- type: object
properties:
message:
type: string
enum:
- Plan has no drivers. Either the plan's depot has no drivers, if the optimization is for minimizing drivers, or the plan has no assigned drivers.
code:
type: string
enum:
- no_drivers_available
required:
- message
- code
description: The plan has no available drivers.
title: Plan has no drivers
- type: object
properties:
message:
type: string
enum:
- Please set an end time or max stops per driver for the plan's depot when optimizing to minimize drivers.
code:
type: string
enum:
- no_end_time_and_max_stops_per_driver
required:
- message
- code
description: The plan's depot has no end time and max stops per driver.
title: Plan's depot has no end time and max stops per driver
- type: object
properties:
message:
type: string
enum:
- Depot not found
code:
type: string
enum:
- depot_not_found
required:
- message
- code
description: Depot not found
title: Depot not found
x-response-description: Depot not found
- type: object
properties:
message:
type: string
enum:
- Please set a start location for the plan's depot.
code:
type: string
enum:
- depot_missing_start_address
required:
- message
- code
description: Depot not found
title: Plan's depot missing start address
description: The plan is not being edited, an optimization is already in progress, there are no drivers, or there is a problem with the depot.
'500':
description: An internal server error occurred
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message.
code:
type: string
description: The error code.
param:
type: string
description: The parameter that caused the error.
url:
type: string
description: The URL with more information about the error.
required:
- message
description: An internal server error occurred
default:
description: The default error model
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message.
code:
type: string
description: The error code.
param:
type: string
description: The parameter that caused the error.
url:
type: string
description: The URL with more information about the error.
required:
- message
description: The default error model
/plans/{planId}:redistribute:
post:
operationId: redistributePlan
summary: Re-distribute a plan
tags:
- Live Plans
description: Re-distribute a plan to its drivers. This endpoint should be used only after updating a live plan. This will apply the re-optimization changes and send the drivers their routes.
parameters:
- schema:
type: string
pattern: ^[a-zA-Z0-9---_]{1,50}$
in: path
name: planId
required: true
description: The plan id
responses:
'200':
description: The distributed plan
content:
application/json:
schema:
$ref: '#/components/schemas/planSchema'
description: The distributed plan
'400':
description: ID format is invalid
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message.
code:
type: string
description: The error code.
param:
type: string
description: The parameter that caused the error.
url:
type: string
description: The URL with more information about the error.
required:
- message
description: ID format is invalid
title: The request is invalid
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message.
url:
type: string
description: The URL with more information about the error.
required:
- message
description: Unauthorized
'403':
description: Plan is no longer accessible due to data access restrictions. Upgrade to a plan that supports a longer delivery history period to access it.
content:
application/json:
schema:
type: object
properties:
message:
type: string
enum:
- Plan is no longer accessible due to data access restrictions. Upgrade to a plan that supports a longer delivery history period to access it.
code:
type: string
enum:
- plan_inaccessible
url:
type: string
enum:
- https://dispatch.spoke.com/paywall
required:
- message
- code
- url
description: Plan is no longer accessible due to data access restrictions. Upgrade to a plan that supports a longer delivery history period to access it.
'404':
description: The provided plan id does not exist
content:
application/json:
schema:
type: object
properties:
message:
type: string
enum:
- Plan not found
required:
- message
description: The provided plan id does not exist
title: Plan not found
'409':
description: The plan is not yet optimized, is optimizing, was already distributed or was modified whilst processing request.
content:
application/json:
schema:
oneOf:
- type: object
properties:
message:
type: string
enum:
- Plan already distributed
code:
type: string
enum:
- plan_already_distributed
required:
- message
- code
description: The plan is already distributed.
title: Plan already distributed
- type: object
properties:
message:
type: string
enum:
- Plan not optimized
code:
type: string
enum:
- plan_not_optimized
required:
- message
- code
description: The plan is not optimized.
title: Plan not optimized
- type: object
properties:
message:
type: string
enum:
- Plan optimization in progress
code:
type: string
enum:
- plan_optimization_in_progress
required:
- message
- code
description: The plan's optimization is in progress.
title: Plan optimization in progress
- type: object
properties:
message:
type: string
enum:
- Plan was modified by a concurrent request. Please retry your request.
code:
type: string
enum:
- plan_concurrent_modification
required:
- message
- code
description: Plan modified whilst processing request
title: Plan modified whilst processing request
description: The plan is not yet optimized, is optimizing, was already distributed or was modified whilst processing request.
'500':
description: An internal server error occurred
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message.
code:
type: string
description: The error code.
param:
type: string
description: The parameter that caused the error.
url:
type: string
description: The URL with more information about the error.
required:
- message
description: An internal server error occurred
default:
description: The default error model
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message.
code:
type: string
description: The error code.
param:
type: string
description: The parameter that caused the error.
url:
type: string
description: The URL with more information about the error.
required:
- message
description: The default error model
/plans/{planId}:save:
post:
operationId: savePlan
summary: Save the plan changes
tags:
- Live Plans
description: Save the plan changes after re-optimization without distributing it. This endpoint is optional since re-distribute already saves the changes.
parameters:
- schema:
type: string
pattern: ^[a-zA-Z0-9---_]{1,50}$
in: path
name: planId
required: true
description: The plan id
responses:
'204':
description: Plan saved successfully
'400':
description: ID format is invalid
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message.
code:
type: string
description: The error code.
param:
type: string
description: The parameter that caused the error.
url:
type: string
description: The URL with more information about the error.
required:
- message
description: ID format is invalid
title: The request is invalid
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message.
url:
type: string
description: The URL with more information about the error.
required:
- message
description: Unauthorized
'403':
description: Plan is no longer accessible due to data access restrictions. Upgrade to a plan that supports a longer delivery history period to access it.
content:
application/json:
schema:
type: object
properties:
message:
type: string
enum:
- Plan is no longer accessible due to data access restrictions. Upgrade to a plan that supports a longer delivery history period to access it.
code:
type: string
enum:
- plan_inaccessible
url:
type: string
enum:
- https://dispatch.spoke.com/paywall
required:
- message
- code
- url
description: Plan is no longer accessible due to data access restrictions. Upgrade to a plan that supports a longer delivery history period to access it.
'404':
description: The provided plan id does not exist
content:
application/json:
schema:
type: object
properties:
message:
type: string
enum:
- Plan not found
required:
- message
description: The provided plan id does not exist
title: Plan not found
'409':
description: The plan is not yet optimized, an optimization is in progress or it was modified whilst processing request.
content:
application/json:
schema:
oneOf:
- type: object
properties:
message:
type: string
enum:
- Plan not optimized
code:
type: string
enum:
- plan_not_optimized
required:
- message
- code
description: The plan is not optimized.
title: Plan not optimized
- type: object
properties:
message:
type: string
enum:
- Plan optimization in progress
code:
type: string
enum:
- plan_optimization_in_progress
required:
- message
- code
description: The plan's optimization is in progress.
title: Plan optimization in progress
- type: object
properties:
message:
type: string
enum:
- Plan was modified by a concurrent request. Please retry your request.
code:
type: string
enum:
- plan_concurrent_modification
required:
- message
- code
description: Plan modified whilst processing request
title: Plan modified whilst processing request
description: The plan is not yet optimized, an optimization is in progress or it was modified whilst processing request.
'500':
description: An internal server error occurred
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message.
code:
type: string
description: The error code.
param:
type: string
description: The parameter that caused the error.
url:
type: string
description: The URL with more information about the error.
required:
- message
description: An internal server error occurred
default:
description: The default error model
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message.
code:
type: string
description: The error code.
param:
type: string
description: The parameter that caused the error.
url:
type: string
description: The URL with more information about the error.
required:
- message
description: The default error model
components:
schemas:
planIdSchema:
type: string
pattern: ^plans\/[a-zA-Z0-9---_]{1,50}$
operationIdSchema:
type: string
pattern: ^operations\/[a-zA-Z0-9---_]{1,50}$
depotIdSchema:
type: string
pattern: ^depots\/[a-zA-Z0-9---_]{1,50}$
planSchema:
type: object
properties:
id:
allOf:
- $ref: '#/components/schemas/planIdSchema'
description: The unique identifier of the plan.
title:
type: string
description: The title of the plan.
starts:
$ref: '#/components/schemas/dateSchema'
depot:
anyOf:
- $ref: '#/components/schemas/depotIdSchema'
- type: 'null'
description: The depot ID of the plan, in the format depots/<id>
distributed:
type: boolean
description: Whether the plan has been distributed.
writable:
type: boolean
description: Whether the plan is writable using the normal Plan APIs. If this is false, you will need to use the [Live Plan APIs](/api/v1#tag/Live-Plans) to edit the plan. Any plan created before 2023-04-01 is not writable.
optimization:
anyOf:
- type: string
enum:
- creating
- editing
- preview
- optimized
- optimizing
- type: 'null'
description: The optimization state of the plan.
drivers:
type: array
items:
$ref: '#/components/schemas/driverIdSchema'
description: The driver IDs of the plan, in the format drivers/<id>.
routes:
type: array
items:
$ref: '#/components/schemas/routeIdSchema'
description: The route IDs of the plan, in the format routes/<id>.
routeOverrides:
anyOf:
- type: object
properties:
startTime:
anyOf:
- type: object
properties:
hour:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: Hour of the day
minute:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: Minute of the hour
required:
- hour
- minute
additionalProperties: false
description: Time of day in hours and minutes. Uses a 24 hour clock.
- type: 'null'
description: Plan's start time.
endTime:
anyOf:
- type: object
properties:
hour:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: Hour of the day
minute:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: Minute of the hour
required:
- hour
- minute
additionalProperties: false
description: Time of day in hours and minutes. Uses a 24 hour clock.
- type: 'null'
description: Plan's end time.
startAddress:
anyOf:
- type: object
properties:
address:
type: string
description: The address of the stop.
addressLineOne:
type: string
description: The first line of the address.
addressLineTwo:
type: string
description: The second line of the address.
latitude:
anyOf:
- type: number
minimum: -90
maximum: 90
- type: 'null'
description: The latitude of the address in decimal degrees.
longitude:
anyOf:
- type: number
minimum: -180
maximum: 180
- type: 'null'
description: The longitude of the address in decimal degrees.
placeId:
anyOf:
- type: string
- type: 'null'
description: The identifier of the place corresponding to this stop on Google Places
placeTypes:
type: array
items:
type: string
description: Array of strings that is provided by the Google AutoCompleteAPI
required:
- address
- addressLineOne
- addressLineTwo
- latitude
- longitude
- placeId
- placeTypes
additionalProperties: false
description: The address of the stop.
- type: 'null'
description: Plan's start location.
endAddress:
anyOf:
- type: object
properties:
address:
type: string
description: The address of the stop.
addressLineOne:
type: string
description: The first line of the address.
addressLineTwo:
type: string
description: The second line of the address.
latitude:
anyOf:
- type: number
minimum: -90
maximum: 90
- type: 'null'
description: The latitude of the address in decimal degrees.
longitude:
anyOf:
- type: number
minimum: -180
maximum: 180
- type: 'null'
description: The longitude of the address in decimal degrees.
placeId:
anyOf:
- type: string
- type: 'null'
# --- truncated at 32 KB (40 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/circuit/refs/heads/main/openapi/circuit-live-plans-api-openapi.yml