{ "openapi": "3.1.0", "info": { "title": "Carregados API", "summary": "Agent-ready EV data, route planning, and account workflows.", "version": "1.4.0", "description": "Public Carregados discovery and route-planning APIs plus authenticated, user-scoped APIs for cars, charging locations, and station highlight checkout. OAuth Authorization Code with S256 PKCE is preferred; manually provisioned bearer tokens remain supported." }, "externalDocs": { "description": "API, authentication, MCP, and safety documentation", "url": "https://carregados.com.br/docs/api.md" }, "servers": [ { "url": "https://carregados.com.br" } ], "tags": [ { "name": "Public" }, { "name": "Account" }, { "name": "Cars" }, { "name": "Locations" }, { "name": "Routes" }, { "name": "Garage" }, { "name": "Favorites" }, { "name": "Trips" }, { "name": "Check-ins" }, { "name": "Notifications" }, { "name": "Highlights" }, { "name": "Corrections" }, { "name": "Shares" }, { "name": "Charging connections", "description": "A station owner’s or operator’s charging-platform (OCPI) connections, as in Ajustes → Integrações. Available only when charging integrations are enabled for the account; otherwise every endpoint answers 404. Connecting a platform takes its token, so it happens only in the browser (links.connect); responses never contain platform credentials." } ], "paths": { "/api/public/places": { "get": { "operationId": "searchPublicPlaces", "tags": [ "Public" ], "summary": "Search public place candidates", "description": "Search addresses, place names, matching charging stations, or a caller-provided latitude/longitude pair. Responses return labeled candidates without exact coordinates. A candidate's id can be passed back as placeId (a POST /api/v1/routes/plan waypoint) or nearPlaceId (the station searches): the server keeps its point.", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Place, address, station, or coordinate query.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum results, 1 to 10.", "schema": { "type": "integer" } }, { "name": "countryCodes", "in": "query", "required": false, "description": "Comma-separated ISO two-letter country codes. Street-level results follow this order; by default Brazil comes first, then its neighbours.", "schema": { "type": "string" } }, { "name": "includeStations", "in": "query", "required": false, "description": "Include Carregados station-name matches.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicPlaceSearchResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/public/stations": { "get": { "operationId": "searchPublicStations", "tags": [ "Public" ], "summary": "Search public charging stations", "description": "Search public charging-station data by state, city, or caller-provided origin. Responses do not expose station coordinates.", "parameters": [ { "name": "state", "in": "query", "required": false, "description": "Brazilian state: UF code (\"PR\"), name (\"Paraná\") or \"paraná (pr)\". Unknown states return 400.", "schema": { "type": "string" } }, { "name": "city", "in": "query", "required": false, "description": "City name, for example \"Curitiba\" or \"São Paulo\"; case and accents are ignored. Without state, a city only one state has is found automatically; a name several states share returns 400.", "schema": { "type": "string" } }, { "name": "latitude", "in": "query", "required": false, "description": "Caller origin latitude for distanceKm.", "schema": { "type": "number" } }, { "name": "longitude", "in": "query", "required": false, "description": "Caller origin longitude for distanceKm.", "schema": { "type": "number" } }, { "name": "nearPlaceId", "in": "query", "required": false, "description": "Origin by reference instead of latitude/longitude: the id of a GET /api/public/places result.", "schema": { "type": "string" } }, { "name": "nearStationId", "in": "query", "required": false, "description": "Origin by reference instead of latitude/longitude: a station id.", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, maximum 25; defaults to 10.", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "1-based page number. Only the first 100 results of a search are available; narrow it instead of paging further.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicStationSearchResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/public/stations/map": { "get": { "operationId": "searchPublicStationMap", "tags": [ "Public" ], "summary": "Search stations in a radius or map viewport", "description": "Geospatial station search returning aggregate status, power, distance, and pagination without exact station or search-area coordinates. Pass a center (latitude/longitude, nearPlaceId or nearStationId) or all four viewport bounds, at most 1.5 degrees (about 150 km) on each side. GET /api/public/station-filters lists the connector, amenity, place-type and network ids.", "parameters": [ { "name": "latitude", "in": "query", "required": false, "description": "Radius-search center latitude.", "schema": { "type": "number" } }, { "name": "longitude", "in": "query", "required": false, "description": "Radius-search center longitude.", "schema": { "type": "number" } }, { "name": "nearPlaceId", "in": "query", "required": false, "description": "Radius-search center by reference: the id of a GET /api/public/places result.", "schema": { "type": "string" } }, { "name": "nearStationId", "in": "query", "required": false, "description": "Radius-search center by reference: a station id.", "schema": { "type": "integer" } }, { "name": "radiusKm", "in": "query", "required": false, "description": "Radius in kilometers, maximum 50; defaults to 25.", "schema": { "type": "number" } }, { "name": "north", "in": "query", "required": false, "description": "Viewport north latitude.", "schema": { "type": "number" } }, { "name": "east", "in": "query", "required": false, "description": "Viewport east longitude.", "schema": { "type": "number" } }, { "name": "south", "in": "query", "required": false, "description": "Viewport south latitude.", "schema": { "type": "number" } }, { "name": "west", "in": "query", "required": false, "description": "Viewport west longitude.", "schema": { "type": "number" } }, { "name": "status", "in": "query", "required": false, "description": "Comma-separated operational, limited, unavailable, or unknown values.", "schema": { "type": "string" } }, { "name": "open247", "in": "query", "required": false, "description": "Filter by 24/7 availability.", "schema": { "type": "boolean" } }, { "name": "minPowerKw", "in": "query", "required": false, "description": "Minimum charger power.", "schema": { "type": "number" } }, { "name": "maxPowerKw", "in": "query", "required": false, "description": "Maximum charger power.", "schema": { "type": "number" } }, { "name": "maxPriceKwh", "in": "query", "required": false, "description": "Maximum price per kWh.", "schema": { "type": "number" } }, { "name": "minimumReviews", "in": "query", "required": false, "description": "Minimum station review count.", "schema": { "type": "integer" } }, { "name": "networkId", "in": "query", "required": false, "description": "Charging-network id (GET /api/public/station-filters).", "schema": { "type": "integer" } }, { "name": "connectorIds", "in": "query", "required": false, "description": "Comma-separated connector ids (GET /api/public/station-filters).", "schema": { "type": "string" } }, { "name": "amenityIds", "in": "query", "required": false, "description": "Comma-separated amenity ids (GET /api/public/station-filters).", "schema": { "type": "string" } }, { "name": "poi", "in": "query", "required": false, "description": "Place type, a placeTypes value from GET /api/public/station-filters.", "schema": { "type": "string" } }, { "name": "verified", "in": "query", "required": false, "description": "Filter to verified stations.", "schema": { "type": "boolean" } }, { "name": "photos", "in": "query", "required": false, "description": "Filter stations with or without photos.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, maximum 25; defaults to 25.", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "1-based page number. Only the first 100 results of a search are available; narrow it instead of paging further.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicStationMapResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/public/station-filters": { "get": { "operationId": "getPublicStationFilters", "tags": [ "Public" ], "summary": "List station filter ids", "description": "The ids the station map search and route planning filter by: connectors grouped by plug (pass every id of a plug in connectorIds), amenities, place types (poi) and charging networks with their public station counts. Without networkQuery, the 40 largest networks are listed.", "parameters": [ { "name": "networkQuery", "in": "query", "required": false, "description": "Network name to look up, for example \"Tupinamba\"; case and accents are ignored.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicStationFilters" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/public/stations/{stationId}": { "get": { "operationId": "getPublicStation", "tags": [ "Public" ], "summary": "Get public charging station detail", "parameters": [ { "name": "stationId", "in": "path", "required": true, "description": "Station id or slug containing an id.", "schema": { "type": "integer" } }, { "name": "latitude", "in": "query", "required": false, "description": "Caller origin latitude for distanceKm.", "schema": { "type": "number" } }, { "name": "longitude", "in": "query", "required": false, "description": "Caller origin longitude for distanceKm.", "schema": { "type": "number" } }, { "name": "nearPlaceId", "in": "query", "required": false, "description": "Origin by reference instead of latitude/longitude: the id of a GET /api/public/places result.", "schema": { "type": "string" } }, { "name": "nearStationId", "in": "query", "required": false, "description": "Origin by reference instead of latitude/longitude: a station id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicStationDetailResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/public/vehicles": { "get": { "operationId": "searchPublicVehicles", "tags": [ "Public" ], "summary": "Search route-ready EV catalog vehicles", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Make, model, or variant search text.", "schema": { "type": "string" } }, { "name": "make", "in": "query", "required": false, "description": "Vehicle make.", "schema": { "type": "string" } }, { "name": "minRangeKm", "in": "query", "required": false, "description": "Minimum rated range.", "schema": { "type": "number" } }, { "name": "connectorIds", "in": "query", "required": false, "description": "Comma-separated connector ids.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, maximum 100.", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "1-based page number.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicVehicleSearchResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/public/vehicles/{vehicleId}": { "get": { "operationId": "getPublicVehicle", "tags": [ "Public" ], "summary": "Get a route-ready EV catalog profile", "parameters": [ { "name": "vehicleId", "in": "path", "required": true, "description": "Catalog vehicle id.", "schema": { "type": "integer" } }, { "name": "subtypeId", "in": "query", "required": false, "description": "Optional catalog variant id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicVehicleDetailResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/public/cars": { "get": { "operationId": "searchPublicCars", "tags": [ "Public" ], "summary": "Search public electric-car listings", "description": "Search active public electric-car listings. Responses omit seller private contact fields and owner ids.", "parameters": [ { "name": "maker", "in": "query", "required": false, "description": "Vehicle maker. Alias: marca.", "schema": { "type": "string" } }, { "name": "model", "in": "query", "required": false, "description": "Vehicle model. Alias: modelo.", "schema": { "type": "string" } }, { "name": "version", "in": "query", "required": false, "description": "Vehicle variant/trim.", "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "description": "Listing state. Alias: estado.", "schema": { "type": "string" } }, { "name": "city", "in": "query", "required": false, "description": "Listing city. Alias: cidade.", "schema": { "type": "string" } }, { "name": "condition", "in": "query", "required": false, "description": "Listing condition. Alias: condicao.", "schema": { "type": "string" } }, { "name": "minPrice", "in": "query", "required": false, "description": "Minimum price in BRL.", "schema": { "type": "number" } }, { "name": "maxPrice", "in": "query", "required": false, "description": "Maximum price in BRL.", "schema": { "type": "number" } }, { "name": "minYear", "in": "query", "required": false, "description": "Minimum model year.", "schema": { "type": "integer" } }, { "name": "maxYear", "in": "query", "required": false, "description": "Maximum model year.", "schema": { "type": "integer" } }, { "name": "minRange", "in": "query", "required": false, "description": "Minimum range in km.", "schema": { "type": "number" } }, { "name": "maxRange", "in": "query", "required": false, "description": "Maximum range in km.", "schema": { "type": "number" } }, { "name": "minOdometer", "in": "query", "required": false, "description": "Minimum odometer in km.", "schema": { "type": "number" } }, { "name": "maxOdometer", "in": "query", "required": false, "description": "Maximum odometer in km.", "schema": { "type": "number" } }, { "name": "minBatteryKwh", "in": "query", "required": false, "description": "Minimum battery capacity in kWh, from the listing's catalog version (else its model). Alias: bateria-minima.", "schema": { "type": "integer" } }, { "name": "minDcPowerKw", "in": "query", "required": false, "description": "Minimum DC (fast) charging power in kW, from the listing's catalog version (else its model). Alias: recarga-dc-minima.", "schema": { "type": "integer" } }, { "name": "connector", "in": "query", "required": false, "description": "Plug the car charges with, from its catalog version's native inlets (else its model's). type_2 includes CCS2 cars, whose inlet takes it. Alias: conector (ccs2, tipo-2, gbt).", "schema": { "type": "string", "enum": [ "ccs2", "type_2", "gb_t" ] } }, { "name": "sellerKind", "in": "query", "required": false, "description": "dealer: imported dealer listings and the Plano Lojista; private: everyone else. Alias: vendedor (particular, loja).", "schema": { "type": "string", "enum": [ "private", "dealer" ] } }, { "name": "listingType", "in": "query", "required": false, "description": "particular or concessionaria.", "schema": { "type": "string" } }, { "name": "sellerType", "in": "query", "required": false, "description": "Stored seller type label, for example Professional. Prefer sellerKind.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "newest, price_asc, price_desc, or popular.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, max 25.", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "1-based page number.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCarSearchResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/public/cars/{carId}": { "get": { "operationId": "getPublicCar", "tags": [ "Public" ], "summary": "Get public electric-car listing detail", "description": "Returns public listing details without phone, email, website, owner id, or draft/private listings.", "parameters": [ { "name": "carId", "in": "path", "required": true, "description": "Car id or slug containing an id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCarDetailResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/public/market-data": { "get": { "operationId": "getPublicMarketData", "tags": [ "Public" ], "summary": "Get public EV market data", "description": "Public Brazil EV sales, charging-station distribution, and recent route-demand signals.", "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicMarketDataResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/me": { "get": { "operationId": "getCurrentUser", "tags": [ "Account" ], "summary": "Get current user and token scopes", "security": [ { "oauth2": [] }, { "bearerAuth": [] } ], "x-required-scopes": [], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentUserResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/cars": { "get": { "operationId": "listCarListings", "tags": [ "Cars" ], "summary": "List authenticated user car listings", "description": "Each listing carries its publication status (draft, payment_pending, published, paused, expired), a nextStep sentence, its 12-month term and its views, contacts and favorites.", "security": [ { "oauth2": [ "cars:read" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "cars:read" ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnedCarsResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "createCarListing", "tags": [ "Cars" ], "summary": "Create complete draft car listing", "description": "Creates a complete draft listing for the authenticated user. The user then adds 1 to 20 photos in the browser at links.photos; POST /api/v1/cars/{carId}/checkout publishes it.", "security": [ { "oauth2": [ "cars:write" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "cars:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stable 8-200 character key. Reuse it only for an identical create request; completed responses are replayable for 24 hours.", "schema": { "type": "string", "minLength": 8, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarCreateInput" } } } }, "responses": { "201": { "description": "Created", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnedCarResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/cars/{carId}": { "get": { "operationId": "getCarListing", "tags": [ "Cars" ], "summary": "Get authenticated user car listing", "description": "Also returns marketPrice: the asking-price range of live listings of the same model (null below five listings).", "security": [ { "oauth2": [ "cars:read" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "cars:read" ], "parameters": [ { "name": "carId", "in": "path", "required": true, "description": "Owned car id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnedCarResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "operationId": "updateCarListing", "tags": [ "Cars" ], "summary": "Update authenticated user car listing", "description": "A paid listing keeps its vehicle details (409 lists the locked fields). active: false pauses a published listing, active: true reactivates it for free until its 12-month term ends; a draft or an expired listing answers 409.", "security": [ { "oauth2": [ "cars:write" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "cars:write" ], "parameters": [ { "name": "carId", "in": "path", "required": true, "description": "Owned car id.", "schema": { "type": "integer" } }, { "name": "If-Match", "in": "header", "required": false, "description": "ETag returned by the matching detail endpoint. A stale value receives 412.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarMutationInput" } } } }, "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnedCarResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "archiveCarListing", "tags": [ "Cars" ], "summary": "Delete authenticated user car listing", "description": "A never-published draft is deleted for good (outcome \"deleted\"). A published listing is removed from Carregados permanently (outcome \"removed\"): with an active Plano Lojista as its \"Excluir anúncio\" does, otherwise also hidden. Removal cannot be undone; pause with PATCH active: false to hide a listing for a while. A draft whose payment is processing answers 409.", "security": [ { "oauth2": [ "cars:write" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "cars:write" ], "parameters": [ { "name": "carId", "in": "path", "required": true, "description": "Owned car id.", "schema": { "type": "integer" } }, { "name": "If-Match", "in": "header", "required": false, "description": "ETag returned by the matching detail endpoint. A stale value receives 412.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarDeleteResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/cars/{carId}/checkout": { "post": { "operationId": "publishCarListing", "tags": [ "Cars" ], "summary": "Publish a draft or start its checkout", "description": "Publishes a ready draft (photos added in the browser). With an active Plano Lojista it goes live at no charge (published: true). Otherwise it returns a Stripe Checkout URL the user pays in the browser: plan \"listing\" (default) is R$ 99,90 once; \"empresarial\" subscribes to the Plano Lojista at R$ 299,90/month (an account's first subscription starts with 30 free days; checkout.trialEndsAt is when the first charge falls) and publishes the listing when it starts. Repeating the call returns the same open checkout (reused: true). A draft without photos answers 409 with links.photos.", "security": [ { "oauth2": [ "cars:write", "checkout:create" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "cars:write", "checkout:create" ], "parameters": [ { "name": "carId", "in": "path", "required": true, "description": "Owned draft car id.", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarCheckoutInput" } } } }, "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarCheckoutResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/cars/{carId}/contact": { "post": { "operationId": "contactCarSeller", "tags": [ "Cars" ], "summary": "Email a message to a car seller", "description": "Sends the site's seller-contact email as the signed-in user: the seller receives the user's account name and email (and phone, if given) and replies directly. Only active listings published on Carregados; imported listings answer 409 with the listing link. Limits: 2 messages per listing a day, 10 per account and 5 per token in 24 hours. Send an Idempotency-Key so a retry never emails twice.", "security": [ { "oauth2": [ "cars:contact" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "cars:contact" ], "parameters": [ { "name": "carId", "in": "path", "required": true, "description": "Public car listing id.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stable 8-200 character key. Reuse it only for an identical create request; completed responses are replayable for 24 hours.", "schema": { "type": "string", "minLength": 8, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarContactInput" } } } }, "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarContactResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/routes/plan": { "post": { "operationId": "planRoute", "tags": [ "Routes" ], "summary": "Plan an EV route with manual vehicle parameters", "description": "Route planning using manual parameters, a public catalog vehicleId/subtypeId, or an owned garageVehicleId. Authentication is optional. Anonymous calls use shared client/global abuse limits; if a bearer token is supplied, it must include routes:plan. garageVehicleId additionally requires garage:read. Responses include an overview and a \"see route on map\" link. Anonymous responses also include a claimToken: send it with the routeId to POST /api/v1/trips within 24 hours to save that route after signing in. A waypoint can be latitude/longitude, a placeId (the id of a GET /api/public/places result) or a stationId; a caller can route to 300 different stations a UTC day (2,000 with an account; 429 past that). Responses summarize the trip in stops, destination and notices; set includeRoute to false to leave out the router's full response (route), which is large.", "security": [ {}, { "oauth2": [ "routes:plan" ] }, { "bearerAuth": [] } ], "x-required-scope-when-authenticated": "routes:plan", "x-additional-scope-for-garage-vehicle": "garage:read", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutePlanInput" } } } }, "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutePlanResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/locations": { "get": { "operationId": "listLocations", "tags": [ "Locations" ], "summary": "List authenticated user charging locations", "description": "The stations the user created, owns, or has in a Destaque awaiting activation, newest first. Each carries relationship (created, owner or both), canEdit, highlight {status, activeUntil}, submissionState (pending_review, not_published, merged, activation_pending, managed_elsewhere or published, for stations the user created), pricing in cents with the formatted BRL amount, and links; links.manage appears only where the user can edit in the browser.", "security": [ { "oauth2": [ "locations:read" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "locations:read" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1 to 50 (20).", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "pagination.nextCursor from the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnedLocationsResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "createLocation", "tags": [ "Locations" ], "summary": "Submit a charging location for review", "description": "Applies the add-station form's rules. Place the station with placeId (a GET /api/public/places id; address is then filled from the map when omitted) or latitude/longitude with address. A station: placeId answers 409 Duplicate station with existingStation. Stations within 150 m (published ones, the user's own pending submissions and other people's from the last 14 days) answer 409 Possible duplicate with possibleDuplicates; resend with confirmNotDuplicate: true once the user confirms it is a different station. That 409 is not stored under the Idempotency-Key, so the retry may reuse it.", "security": [ { "oauth2": [ "locations:write" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "locations:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stable 8-200 character key. Reuse it only for an identical create request; completed responses are replayable for 24 hours.", "schema": { "type": "string", "minLength": 8, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationCreateInput" } } } }, "responses": { "201": { "description": "Created", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnedLocationResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/locations/{locationId}": { "get": { "operationId": "getLocation", "tags": [ "Locations" ], "summary": "Get authenticated user charging location", "description": "One station from the list, with chargers and outlet ids, amenities, photos (public URLs), app links (with the user's links awaiting review), highlight and links to the browser-only owner tools: manage, mainPhoto, pinBranding, promotion and analytics.", "security": [ { "oauth2": [ "locations:read" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "locations:read" ], "parameters": [ { "name": "locationId", "in": "path", "required": true, "description": "Owned or managed location id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnedLocationResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "operationId": "updateLocation", "tags": [ "Locations" ], "summary": "Update authenticated user charging location", "description": "Follows the owner dashboard rules. A published station can be updated only by its owner with an active subscription (or a pending one whose first payment succeeded): name sets the public name, the pin and city/state/country are locked (409 lockedFields; suggest a new location as a correction instead) and restricted: true is refused (409) because Destaque stations stay public. Its creator can edit their own submission while it awaits review, unless someone else owns it, pin included (latitude/longitude or placeId). appLinks are sent to moderation like the dashboard's; a request with only appLinks answers 202 once they are queued. Other readable locations return 403.", "security": [ { "oauth2": [ "locations:write" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "locations:write" ], "parameters": [ { "name": "locationId", "in": "path", "required": true, "description": "Location id the user owns with an active subscription, or an own submission still in review.", "schema": { "type": "integer" } }, { "name": "If-Match", "in": "header", "required": false, "description": "ETag returned by the matching detail endpoint. A stale value receives 412.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationUpdateInput" } } } }, "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnedLocationResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/locations/{locationId}/analytics": { "get": { "operationId": "getLocationAnalytics", "tags": [ "Locations" ], "summary": "Owner analytics for a station", "description": "The owner analytics page's numbers for a station the user owns with a Destaque plan (403 otherwise): profile views, directions opened, reviews, favorites and photos for the period and the one before, plus route-planner suggestions.", "security": [ { "oauth2": [ "locations:read" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "locations:read" ], "parameters": [ { "name": "locationId", "in": "path", "required": true, "description": "Owned location id.", "schema": { "type": "integer" } }, { "name": "period", "in": "query", "required": false, "description": "7d, 30d (default), 90d or all.", "schema": { "type": "string" } }, { "name": "daily", "in": "query", "required": false, "description": "true to add the numbers day by day.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationAnalyticsResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/garage": { "get": { "operationId": "listGarageVehicles", "tags": [ "Garage" ], "summary": "List route-planning garage vehicles", "security": [ { "oauth2": [ "garage:read" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "garage:read" ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GarageVehiclesResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "addGarageVehicle", "tags": [ "Garage" ], "summary": "Add a catalog vehicle to the garage", "security": [ { "oauth2": [ "garage:write" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "garage:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stable 8-200 character key. Reuse it only for an identical create request; completed responses are replayable for 24 hours.", "schema": { "type": "string", "minLength": 8, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GarageVehicleCreateInput" } } } }, "responses": { "201": { "description": "Created", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GarageVehicleResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/garage/{vehicleId}": { "get": { "operationId": "getGarageVehicle", "tags": [ "Garage" ], "summary": "Get one garage vehicle and ETag", "security": [ { "oauth2": [ "garage:read" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "garage:read" ], "parameters": [ { "name": "vehicleId", "in": "path", "required": true, "description": "Owned garage vehicle id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GarageVehicleResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "operationId": "updateGarageVehicle", "tags": [ "Garage" ], "summary": "Update a garage vehicle", "security": [ { "oauth2": [ "garage:write" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "garage:write" ], "parameters": [ { "name": "vehicleId", "in": "path", "required": true, "description": "Owned garage vehicle id.", "schema": { "type": "integer" } }, { "name": "If-Match", "in": "header", "required": false, "description": "ETag returned by the matching detail endpoint. A stale value receives 412.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GarageVehicleUpdateInput" } } } }, "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GarageVehicleResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "removeGarageVehicle", "tags": [ "Garage" ], "summary": "Remove a garage vehicle", "security": [ { "oauth2": [ "garage:write" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "garage:write" ], "parameters": [ { "name": "vehicleId", "in": "path", "required": true, "description": "Owned garage vehicle id.", "schema": { "type": "integer" } }, { "name": "If-Match", "in": "header", "required": false, "description": "ETag returned by the matching detail endpoint. A stale value receives 412.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MutationResult" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/favorites": { "get": { "operationId": "listFavoriteStations", "tags": [ "Favorites" ], "summary": "List favorite charging stations", "description": "Return favorite station facts without exact station coordinates.", "security": [ { "oauth2": [ "favorites:read" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "favorites:read" ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FavoriteStationsResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/favorites/{stationId}": { "put": { "operationId": "addFavoriteStation", "tags": [ "Favorites" ], "summary": "Add a favorite station", "security": [ { "oauth2": [ "favorites:write" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "favorites:write" ], "parameters": [ { "name": "stationId", "in": "path", "required": true, "description": "Public station id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FavoriteMutationResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "removeFavoriteStation", "tags": [ "Favorites" ], "summary": "Remove a favorite station", "security": [ { "oauth2": [ "favorites:write" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "favorites:write" ], "parameters": [ { "name": "stationId", "in": "path", "required": true, "description": "Public station id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FavoriteMutationResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/favorites/cars": { "get": { "operationId": "listFavoriteCars", "tags": [ "Favorites" ], "summary": "List favorite car listings", "description": "The 200 most recent cars the user saved with the heart on /carros. forSale is false once a listing closes; removed listings drop out.", "security": [ { "oauth2": [ "favorites:read" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "favorites:read" ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FavoriteCarsResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/favorites/cars/{carId}": { "put": { "operationId": "addFavoriteCar", "tags": [ "Favorites" ], "summary": "Save a car listing to favorites", "description": "Only listings for sale on /carros can be saved (404 otherwise). Saving twice is a no-op.", "security": [ { "oauth2": [ "favorites:write" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "favorites:write" ], "parameters": [ { "name": "carId", "in": "path", "required": true, "description": "Public car listing id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FavoriteCarMutationResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "removeFavoriteCar", "tags": [ "Favorites" ], "summary": "Remove a car listing from favorites", "security": [ { "oauth2": [ "favorites:write" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "favorites:write" ], "parameters": [ { "name": "carId", "in": "path", "required": true, "description": "Public car listing id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FavoriteCarMutationResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/trips": { "get": { "operationId": "listTrips", "tags": [ "Trips" ], "summary": "List saved, recent, or archived trips", "security": [ { "oauth2": [ "trips:read" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "trips:read" ], "parameters": [ { "name": "kind", "in": "query", "required": false, "description": "saved, recent, or archived.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque next-page cursor.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, maximum 100.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TripsResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "saveTrip", "tags": [ "Trips" ], "summary": "Save a planned route as a trip", "description": "Saves a route the token user already owns. A route planned anonymously is saved, and becomes the user’s, only with the claimToken from its plan response, within 24 hours of planning. Any other route id answers 404.", "security": [ { "oauth2": [ "trips:write" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "trips:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stable 8-200 character key. Reuse it only for an identical create request; completed responses are replayable for 24 hours.", "schema": { "type": "string", "minLength": 8, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveTripInput" } } } }, "responses": { "201": { "description": "Created", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TripResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/trips/{tripId}": { "get": { "operationId": "getTrip", "tags": [ "Trips" ], "summary": "Get one trip with its stops, departure alert, open check-in form and ETag", "security": [ { "oauth2": [ "trips:read" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "trips:read" ], "parameters": [ { "name": "tripId", "in": "path", "required": true, "description": "Owned trip id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TripResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "operationId": "updateTrip", "tags": [ "Trips" ], "summary": "Rename, save, archive, restore, or rate a trip, or set its departure alert", "security": [ { "oauth2": [ "trips:write" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "trips:write" ], "parameters": [ { "name": "tripId", "in": "path", "required": true, "description": "Owned trip id.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": false, "description": "ETag returned by the matching detail endpoint. A stale value receives 412.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TripUpdateInput" } } } }, "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TripResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "archiveTrip", "tags": [ "Trips" ], "summary": "Archive a trip", "security": [ { "oauth2": [ "trips:write" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "trips:write" ], "parameters": [ { "name": "tripId", "in": "path", "required": true, "description": "Owned trip id.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": false, "description": "ETag returned by the matching detail endpoint. A stale value receives 412.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TripResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/check-ins": { "get": { "operationId": "listCheckIns", "tags": [ "Check-ins" ], "summary": "List the current user’s station check-ins", "security": [ { "oauth2": [ "checkins:read" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "checkins:read" ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Next-page check-in id cursor.", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, maximum 100.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckInsResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/stations/{stationId}/check-ins": { "post": { "operationId": "createCheckIn", "tags": [ "Check-ins" ], "summary": "Record a station check-in", "security": [ { "oauth2": [ "checkins:write" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "checkins:write" ], "parameters": [ { "name": "stationId", "in": "path", "required": true, "description": "Public station id.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stable 8-200 character key. Reuse it only for an identical create request; completed responses are replayable for 24 hours.", "schema": { "type": "string", "minLength": 8, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckInCreateInput" } } } }, "responses": { "201": { "description": "Created", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckInResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/check-ins/{checkInId}": { "delete": { "operationId": "deleteCheckIn", "tags": [ "Check-ins" ], "summary": "Delete an owned check-in", "security": [ { "oauth2": [ "checkins:write" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "checkins:write" ], "parameters": [ { "name": "checkInId", "in": "path", "required": true, "description": "Owned check-in id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MutationResult" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/check-ins/{checkInId}/replies": { "get": { "operationId": "listCheckInReplies", "tags": [ "Check-ins" ], "summary": "Read the public conversation under a check-in", "description": "The replies under any check-in, oldest first, as the station page shows them. Any valid token.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "checkInId", "in": "path", "required": true, "description": "Check-in id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckInRepliesResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "replyToCheckIn", "tags": [ "Check-ins" ], "summary": "Reply under a check-in", "description": "A public reply, as station owners answer reviews on the station page. Notifies the check-in author, the conversation and @mentioned users. Up to 5 replies a minute, 3 in one conversation.", "security": [ { "oauth2": [ "checkins:write" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "checkins:write" ], "parameters": [ { "name": "checkInId", "in": "path", "required": true, "description": "Check-in id.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stable 8-200 character key. Reuse it only for an identical create request; completed responses are replayable for 24 hours.", "schema": { "type": "string", "minLength": 8, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckInReplyInput" } } } }, "responses": { "201": { "description": "Created", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckInReplyResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/stations/{stationId}/corrections": { "post": { "operationId": "suggestStationCorrections", "tags": [ "Corrections" ], "summary": "Suggest corrections to a public station", "description": "Each field sent becomes a suggestion with the station page rules: a field the station has no value for is applied now (+1 point); changes to existing values and app links wait for moderators. results gives each field its status. Answers 200 when at least one suggestion was taken, otherwise 400 or 409 with the results; 403 when the station has an active owner, and 409 USE_UPDATE_LOCATION for the owner, who edits with PATCH /api/v1/locations/{locationId}.", "security": [ { "oauth2": [ "corrections:write" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "corrections:write" ], "parameters": [ { "name": "stationId", "in": "path", "required": true, "description": "Public station id.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stable 8-200 character key. Reuse it only for an identical create request; completed responses are replayable for 24 hours.", "schema": { "type": "string", "minLength": 8, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StationCorrectionInput" } } } }, "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StationCorrectionResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/corrections": { "get": { "operationId": "listCorrections", "tags": [ "Corrections" ], "summary": "List your station suggestions and their review status", "security": [ { "oauth2": [ "corrections:write" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "corrections:write" ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "pending_review, applied, or rejected.", "schema": { "type": "string" } }, { "name": "stationId", "in": "query", "required": false, "description": "Only this station.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque next-page cursor.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, maximum 100.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CorrectionsResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/trips/{tripId}/outcome": { "post": { "operationId": "reportTripOutcome", "tags": [ "Trips" ], "summary": "Answer \"Como foi a viagem?\" for a saved trip", "description": "Open from the planned arrival (GET /api/v1/trips/{tripId} returns outcome.form) until it is answered or closes. While the trip is recent, charges that worked or failed become the user's check-ins at those stations.", "security": [ { "oauth2": [ "trips:write" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "trips:write" ], "parameters": [ { "name": "tripId", "in": "path", "required": true, "description": "Owned saved trip id.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stable 8-200 character key. Reuse it only for an identical create request; completed responses are replayable for 24 hours.", "schema": { "type": "string", "minLength": 8, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TripOutcomeInput" } } } }, "responses": { "201": { "description": "Created", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TripOutcomeResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/shares": { "post": { "operationId": "createShareLink", "tags": [ "Shares" ], "summary": "Create a share link for a trip, station, or car listing", "description": "Returns the link with WhatsApp copy, valid 30 days. A trip must be the user's saved trip and needs trips:read or trips:write; stations and car listings need any valid token.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stable 8-200 character key. Reuse it only for an identical create request; completed responses are replayable for 24 hours.", "schema": { "type": "string", "minLength": 8, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareCreateInput" } } } }, "responses": { "201": { "description": "Created", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/notifications": { "get": { "operationId": "listNotifications", "tags": [ "Notifications" ], "summary": "List or count notifications", "security": [ { "oauth2": [ "notifications:read" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "notifications:read" ], "parameters": [ { "name": "filter", "in": "query", "required": false, "description": "all, unread, or read.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque next-page cursor.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, maximum 50.", "schema": { "type": "integer" } }, { "name": "action", "in": "query", "required": false, "description": "Use count to return counts only.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationsResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "operationId": "updateNotifications", "tags": [ "Notifications" ], "summary": "Mark notifications read/unread or delete them", "security": [ { "oauth2": [ "notifications:write" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "notifications:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationMutationInput" } } } }, "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationMutationResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/notification-preferences": { "get": { "operationId": "getNotificationPreferences", "tags": [ "Notifications" ], "summary": "Get notification preferences and ETag", "security": [ { "oauth2": [ "notifications:read" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "notifications:read" ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationPreferencesResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "operationId": "updateNotificationPreferences", "tags": [ "Notifications" ], "summary": "Update notification preferences", "description": "carListingAlertsEmail is read-only here (400): change it with PATCH /api/v1/car-alerts.", "security": [ { "oauth2": [ "notifications:write" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "notifications:write" ], "parameters": [ { "name": "If-Match", "in": "header", "required": false, "description": "ETag returned by the matching detail endpoint. A stale value receives 412.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationPreferencePatch" } } } }, "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationPreferencesResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/car-alerts": { "get": { "operationId": "listCarAlerts", "tags": [ "Notifications" ], "summary": "List the car models followed for new-listing emails", "description": "\"Avisar sobre novos anúncios\": whether the alerts are on (enabled), each followed model with its state (active, or paused while the alerts are off) and model page, and the cap of 10 followed models.", "security": [ { "oauth2": [ "notifications:read" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "notifications:read" ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarAlertsResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "followCarModel", "tags": [ "Notifications" ], "summary": "Follow a car model", "description": "Carregados emails the user at most once a day when a new listing of the model is published. Use the maker and model as /carros lists them; case, accents and a trailing year are ignored. Following turns the alerts on (models paused before resume) and records the consent. 201 when it starts following, 200 when it already did, 404 for a model the site does not know, 409 beyond 10 followed models.", "security": [ { "oauth2": [ "notifications:write" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "notifications:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stable 8-200 character key. Reuse it only for an identical create request; completed responses are replayable for 24 hours.", "schema": { "type": "string", "minLength": 8, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarAlertFollowInput" } } } }, "responses": { "201": { "description": "Created", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarAlertFollowResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "operationId": "updateCarAlerts", "tags": [ "Notifications" ], "summary": "Pause or resume car listing alerts", "description": "The Monitoramento switch: pauses or resumes the emails for every followed model and records the consent. Turning the alerts on with no followed model returns 409. This is the only way to change carListingAlertsEmail.", "security": [ { "oauth2": [ "notifications:write" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "notifications:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarAlertsUpdateInput" } } } }, "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarAlertsResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/car-alerts/{alertId}": { "delete": { "operationId": "unfollowCarModel", "tags": [ "Notifications" ], "summary": "Stop following a car model", "description": "Removing the last followed model turns the alerts off.", "security": [ { "oauth2": [ "notifications:write" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "notifications:write" ], "parameters": [ { "name": "alertId", "in": "path", "required": true, "description": "Alert id from GET /api/v1/car-alerts.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarAlertRemoveResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/locations/{locationId}/destaque/checkout": { "post": { "operationId": "createHighlightCheckout", "tags": [ "Highlights" ], "summary": "Create station highlight checkout", "description": "Highlights one station. Without a plan, creates a Stripe Checkout URL the user pays in the browser (status checkout_created). With a Destaque Pro plan, checkout.url opens the website's add flow, where the user confirms the prorated charge (status confirm_in_browser). POST /api/v1/destaques/checkout adds stations directly.", "security": [ { "oauth2": [ "destaques:write", "checkout:create" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "destaques:write", "checkout:create" ], "parameters": [ { "name": "locationId", "in": "path", "required": true, "description": "Location id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HighlightCheckoutResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/destaques": { "get": { "operationId": "getDestaques", "tags": [ "Highlights" ], "summary": "Get the Destaque Pro plan", "description": "The account's Destaque Pro plan as /ajustes/destaque shows it: status, stations, monthly and per-station price, renewal, cancellation, payment method, the open boleto or invoice, a pending addition's payment link and what blocks changes; also an unpaid checkout, individual (legacy) subscriptions, card renewal grace and the price anchors. destaques:write tokens can read it too.", "security": [ { "oauth2": [ "destaques:read" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "destaques:read" ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DestaqueStateResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/destaques/quote": { "post": { "operationId": "quoteDestaques", "tags": [ "Highlights" ], "summary": "Quote adding stations", "description": "Per-station eligibility with English reasons, then the price: a new plan's monthly total, or for an existing plan the prorated charge today and the new monthly total (from Stripe), with a quoteId valid for 10 minutes. The same selection quoted again within 5 minutes returns the same quote. Nothing is charged; confirmationMessage is the Portuguese sentence to show the user.", "security": [ { "oauth2": [ "destaques:read" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "destaques:read" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DestaqueQuoteInput" } } } }, "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DestaqueQuoteResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/destaques/checkout": { "post": { "operationId": "checkoutDestaques", "tags": [ "Highlights" ], "summary": "Start or extend a Destaque Pro plan", "description": "Without a plan: a Stripe Checkout URL for every station (card or boleto, monthly), reusing an open checkout for the same selection. With a plan, adding stations charges its payment method at once, so send the quoteId of the quote the user approved: the stations are added at that prorated amount (status applied), or a payment link comes back when Stripe needs the user (payment_pending). Without a quoteId nothing is charged and the answer is that quote (status quote_required). An individual subscription becomes a plan the same way. Stations already in the plan are skipped (status unchanged when nothing is new). A blocked plan (boleto, unpaid renewal, scheduled cancellation) answers 409 with code, reason and browser links.", "security": [ { "oauth2": [ "destaques:write", "checkout:create" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "destaques:write", "checkout:create" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stable 8-200 character key. Reuse it only for an identical create request; completed responses are replayable for 24 hours.", "schema": { "type": "string", "minLength": 8, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DestaqueCheckoutInput" } } } }, "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DestaqueCheckoutResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/destaques/remove": { "post": { "operationId": "removeDestaques", "tags": [ "Highlights" ], "summary": "Remove stations from the plan", "description": "With preview, returns the new monthly price and the prorated credit (quoteId valid for 10 minutes). Without it, the stations lose the Destaque Pro pin now and the credit goes to the next invoice. A plan keeps at least one station: cancel it in the billing portal instead.", "security": [ { "oauth2": [ "destaques:write" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "destaques:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DestaqueRemoveInput" } } } }, "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DestaqueRemoveResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/destaques/billing-link": { "post": { "operationId": "createDestaqueBillingLink", "tags": [ "Highlights" ], "summary": "Get a billing link", "description": "portal: a short-lived Stripe customer portal URL to cancel the plan, change the card or download invoices. boleto: the open boleto or invoice waiting for payment (the plan's, an addition's, an unpaid checkout's or an individual subscription's), with the page that generates a new boleto when one expired.", "security": [ { "oauth2": [ "destaques:write" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "destaques:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DestaqueBillingLinkInput" } } } }, "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DestaqueBillingLinkResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/charging/connections": { "get": { "operationId": "listChargingConnections", "tags": [ "Charging connections" ], "summary": "List the user’s charging-platform connections", "description": "Status, last updates, problems, station counts and update choices per connection, the integration-terms state, and links.connect: the browser page where the user connects a platform (the API never takes platform credentials).", "security": [ { "oauth2": [ "integrations:read" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "integrations:read" ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargingConnectionsResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/charging/connections/{connectionId}": { "get": { "operationId": "getChargingConnection", "tags": [ "Charging connections" ], "summary": "Get a connection and a page of its platform’s stations", "description": "Each platform station carries its import state (ready, needs_choice, needs_name, needs_position, blocked, imported), nearby Carregados stations it may match, and, once imported, its Carregados station and update state.", "security": [ { "oauth2": [ "integrations:read" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "integrations:read" ], "parameters": [ { "name": "connectionId", "in": "path", "required": true, "description": "Connection id from GET /api/v1/charging/connections.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Search the platform’s stations.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "page.nextCursor of the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargingConnectionResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "operationId": "updateChargingConnection", "tags": [ "Charging connections" ], "summary": "Change what the connection keeps updated", "description": "syncPreferences turns availability, prices, catalogue and map-position updates on or off for the connection’s stations (fields left out keep their value). autoImport sends new platform stations to Carregados review on their own instead of notifying the user.", "security": [ { "oauth2": [ "integrations:write" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "integrations:write" ], "parameters": [ { "name": "connectionId", "in": "path", "required": true, "description": "Connection id from GET /api/v1/charging/connections.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargingConnectionUpdateInput" } } } }, "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargingConnectionMutationResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/charging/connections/{connectionId}/sync": { "post": { "operationId": "syncChargingConnection", "tags": [ "Charging connections" ], "summary": "Fetch the platform’s latest data now", "description": "Works while the platform is connected. Repeated syncs are throttled per account (429 with retryAfterSeconds).", "security": [ { "oauth2": [ "integrations:write" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "integrations:write" ], "parameters": [ { "name": "connectionId", "in": "path", "required": true, "description": "Connection id from GET /api/v1/charging/connections.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargingConnectionMutationResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/charging/connections/{connectionId}/history": { "get": { "operationId": "listChargingConnectionHistory", "tags": [ "Charging connections" ], "summary": "List the connection’s update history", "security": [ { "oauth2": [ "integrations:read" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "integrations:read" ], "parameters": [ { "name": "connectionId", "in": "path", "required": true, "description": "Connection id from GET /api/v1/charging/connections.", "schema": { "type": "string" } }, { "name": "kind", "in": "query", "required": false, "description": "location, availability, connector or tariff.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Search the history.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "nextCursor of the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargingHistoryResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/charging/connections/{connectionId}/imports": { "post": { "operationId": "importChargingStations", "tags": [ "Charging connections" ], "summary": "Send platform stations to Carregados review", "description": "Up to 100 stations by key. preview: true returns the plan without writing. A station near existing Carregados stations needs linkStationId, mergeStationId or distinct: true; one without a usable position is skipped (the user places it at links.import). Importing is free; new stations appear on the map after approval.", "security": [ { "oauth2": [ "integrations:write" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "integrations:write" ], "parameters": [ { "name": "connectionId", "in": "path", "required": true, "description": "Connection id from GET /api/v1/charging/connections.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stable 8-200 character key. Reuse it only for an identical create request; completed responses are replayable for 24 hours.", "schema": { "type": "string", "minLength": 8, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargingImportInput" } } } }, "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargingImportResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/charging/connections/{connectionId}/checkout": { "post": { "operationId": "createChargingStationsCheckout", "tags": [ "Charging connections", "Highlights" ], "summary": "Start Destaque Pro for imported stations", "description": "The highlight checkout of the import page, for stations this account imported through the connection. preview: true returns the monthly price without creating anything. An account that already pays for highlights gets links.plan to review the addition instead. Payment completes only in the browser; stations in review are approved automatically after payment.", "security": [ { "oauth2": [ "integrations:write", "destaques:write", "checkout:create" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "integrations:write", "destaques:write", "checkout:create" ], "parameters": [ { "name": "connectionId", "in": "path", "required": true, "description": "Connection id from GET /api/v1/charging/connections.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargingCheckoutInput" } } } }, "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargingCheckoutResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/charging/stations/{stationId}": { "get": { "operationId": "getChargingStation", "tags": [ "Charging connections" ], "summary": "Get a station’s platform updates and settings", "security": [ { "oauth2": [ "integrations:read" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "integrations:read" ], "parameters": [ { "name": "stationId", "in": "path", "required": true, "description": "A Carregados station this account sends platform updates to.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargingStationResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "operationId": "updateChargingStation", "tags": [ "Charging connections" ], "summary": "Pause, resume or adjust a station’s platform updates", "description": "Send exactly one of updates (paused or active), overrides (per category: inherit the connection’s choice, on or off) or releaseField (let the platform update a field edited on Carregados again).", "security": [ { "oauth2": [ "integrations:write" ] }, { "bearerAuth": [] } ], "x-required-scopes": [ "integrations:write" ], "parameters": [ { "name": "stationId", "in": "path", "required": true, "description": "A Carregados station this account sends platform updates to.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargingStationUpdateInput" } } } }, "responses": { "200": { "description": "OK", "headers": { "ETag": { "description": "Entity revision when the response represents a concurrency-controlled resource.", "schema": { "type": "string" } }, "Idempotency-Key": { "description": "Accepted idempotency key on supported create operations.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "True when this response was replayed from a prior identical request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargingStationResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge with invalid_token details when applicable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token scope missing", "headers": { "WWW-Authenticate": { "description": "Bearer challenge with insufficient_scope and the required scopes.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict or idempotency-key reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "If-Match precondition failed", "headers": { "ETag": { "description": "Current entity revision.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "securitySchemes": { "oauth2": { "type": "oauth2", "description": "OAuth Authorization Code with mandatory S256 PKCE. Discovery: https://carregados.com.br/.well-known/oauth-authorization-server.", "flows": { "authorizationCode": { "authorizationUrl": "https://carregados.com.br/oauth/authorize", "tokenUrl": "https://carregados.com.br/oauth/token", "refreshUrl": "https://carregados.com.br/oauth/token", "scopes": { "cars:read": "Read the user’s car listings.", "cars:write": "Create and update the user’s car listings.", "cars:contact": "Email messages to car sellers as the user, with their name and email.", "locations:read": "Read the user’s charging locations.", "locations:write": "Create and update charging locations.", "routes:plan": "Plan and save EV routes.", "garage:read": "Read route-planning garage vehicles.", "garage:write": "Add, update, and remove garage vehicles.", "favorites:read": "Read favorite charging stations and cars.", "favorites:write": "Add and remove favorite stations and cars.", "trips:read": "Read saved, recent, and archived trips.", "trips:write": "Save and update trips.", "checkins:read": "Read the user’s station check-ins.", "checkins:write": "Create and delete station check-ins.", "corrections:write": "Suggest corrections to public charging stations and read your suggestions.", "notifications:read": "Read notifications and preferences.", "notifications:write": "Update notifications and preferences.", "destaques:read": "Read the Destaque Pro plan, its quotes and open bills.", "destaques:write": "Prepare charging-station highlights.", "checkout:create": "Create a browser checkout handoff.", "integrations:read": "Read the user’s charging-platform connections, their stations and history.", "integrations:write": "Manage the user’s charging-platform connections: sync, update choices, imports and station updates." } } } }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "cg API token", "description": "OAuth access tokens and manually provisioned personal tokens use the same opaque bearer format. Full guidance: https://carregados.com.br/auth.md." } }, "schemas": { "ErrorResponse": { "type": "object", "additionalProperties": true, "properties": { "error": { "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] }, "issues": { "type": "array", "items": { "type": "object" } } } }, "Pagination": { "type": "object", "additionalProperties": true, "properties": { "page": { "type": [ "integer", "null" ] }, "limit": { "type": [ "integer", "null" ] }, "total": { "type": [ "integer", "null" ] }, "hasMore": { "type": [ "boolean", "null" ] } } }, "MutationResult": { "type": "object", "additionalProperties": true, "properties": { "success": { "type": [ "boolean", "null" ] }, "deleted": { "type": [ "boolean", "null" ] }, "archived": { "type": [ "boolean", "null" ] }, "id": { "type": [ "string", "null" ] } } }, "PublicPlaceSearchResponse": { "type": "object", "additionalProperties": true, "properties": { "query": { "type": [ "string", "null" ] }, "places": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": [ "string", "null" ] }, "kind": { "type": [ "string", "null" ] }, "label": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "stationId": { "type": [ "integer", "null" ] } } } }, "providers": { "type": "array", "items": { "type": [ "string", "null" ] } }, "partial": { "type": [ "boolean", "null" ] } } }, "StationType": { "type": "object", "additionalProperties": true, "properties": { "code": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "isPublic": { "type": [ "boolean", "null" ] }, "isFast": { "type": [ "boolean", "null" ] } } }, "ConnectorSummary": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "connector": { "type": [ "integer", "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "count": { "type": [ "integer", "null" ] }, "minPowerKw": { "type": [ "number", "null" ] }, "maxPowerKw": { "type": [ "number", "null" ] }, "statuses": { "type": "array", "items": { "type": [ "string", "null" ] } } } } }, "ReviewSummary": { "type": "object", "additionalProperties": true, "properties": { "total": { "type": [ "integer", "null" ] }, "positives": { "type": [ "integer", "null" ] }, "negatives": { "type": [ "integer", "null" ] }, "positiveRatio": { "type": [ "number", "null" ] } } }, "PublicStation": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "stationType": { "$ref": "#/components/schemas/StationType" }, "status": { "type": [ "string", "null" ] }, "isVerifiedOwned": { "type": [ "boolean", "null" ] }, "averagePowerKw": { "type": [ "number", "null" ] }, "chargerCount": { "type": [ "integer", "null" ] }, "connectorSummary": { "$ref": "#/components/schemas/ConnectorSummary" }, "reviews": { "$ref": "#/components/schemas/ReviewSummary" }, "distanceKm": { "type": [ "number", "null" ], "description": "Present only when the caller sent latitude and longitude." } } }, "PublicStationSearchResponse": { "type": "object", "additionalProperties": true, "properties": { "query": { "type": "object", "additionalProperties": true, "properties": { "mode": { "type": "string", "enum": [ "origin", "city", "state", "country" ], "description": "The search that ran. Coordinates take precedence over state and city." }, "state": { "type": [ "string", "null" ], "description": "The stored state facet applied, e.g. \"paraná (pr)\"." }, "city": { "type": [ "string", "null" ], "description": "The stored city spelling applied, e.g. \"são paulo\"." }, "page": { "type": [ "integer", "null" ] }, "limit": { "type": [ "integer", "null" ] } } }, "notices": { "type": "array", "items": { "type": [ "string", "null" ] }, "description": "Plain-language notes for the caller, such as a city with no listed stations or filters that were not applied." }, "context": { "type": "object" }, "stations": { "type": "array", "items": { "$ref": "#/components/schemas/PublicStation" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "tripPlanning": { "type": "object" } } }, "PublicStationDetail": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "hours": { "type": [ "string", "null" ] }, "parkingLevel": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "stationType": { "$ref": "#/components/schemas/StationType" }, "status": { "type": [ "string", "null" ] }, "isVerifiedOwned": { "type": [ "boolean", "null" ] }, "poiName": { "type": [ "string", "null" ] }, "distanceKm": { "type": [ "number", "null" ], "description": "Present only when the caller sent latitude and longitude." }, "charging": { "type": "object", "additionalProperties": true, "properties": { "averagePowerKw": { "type": [ "number", "null" ] }, "maxReportedPowerKw": { "type": [ "number", "null" ] }, "chargerCount": { "type": [ "integer", "null" ] }, "connectorSummary": { "$ref": "#/components/schemas/ConnectorSummary" } } }, "connectors": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "standard": { "type": [ "string", "null" ] }, "current": { "type": [ "string", "null" ] }, "maxPowerKw": { "type": [ "number", "null" ] }, "status": { "type": [ "string", "null" ], "description": "The operator's live OCPI status, when the operator shares it." }, "statusConfirmedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "description": "One entry per outlet, in outlet order." }, "pricing": { "type": "object", "additionalProperties": true, "properties": { "priceKwh": { "type": [ "number", "null" ] }, "priceIsMinimum": { "type": [ "boolean", "null" ] }, "priceKwhComment": { "type": [ "string", "null" ] }, "activationPrice": { "type": [ "number", "null" ] }, "activationPriceComment": { "type": [ "string", "null" ] }, "costDescription": { "type": [ "string", "null" ] } } }, "reviews": { "type": "object", "additionalProperties": true, "properties": { "total": { "type": [ "integer", "null" ] }, "positives": { "type": [ "integer", "null" ] }, "negatives": { "type": [ "integer", "null" ] }, "positiveRatio": { "type": [ "number", "null" ] }, "recent": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": [ "integer", "null" ] }, "rating": { "type": [ "number", "null" ] }, "comment": { "type": [ "string", "null" ] }, "kilowatts": { "type": [ "number", "null" ] }, "vehicle": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } } } } } }, "tags": { "type": "array", "items": { "type": [ "string", "null" ] } }, "amenities": { "type": "array", "items": { "type": [ "string", "null" ] } }, "openingTimes": { "type": "array", "items": { "type": "object" } }, "photos": { "type": "object", "additionalProperties": true, "properties": { "count": { "type": [ "integer", "null" ] }, "hasMap": { "type": [ "boolean", "null" ] } } }, "links": { "type": "object", "additionalProperties": true, "properties": { "addPhoto": { "type": [ "string", "null" ], "description": "The station page photo section, where a signed-in user uploads photos (faces and plates are blurred)." } } }, "nextStep": { "type": [ "string", "null" ] }, "analysis": { "type": [ "object", "null" ] }, "tripPlanning": { "type": "object" } } }, "PublicStationDetailResponse": { "type": "object", "additionalProperties": true, "properties": { "station": { "$ref": "#/components/schemas/PublicStationDetail" } } }, "PublicStationMapResponse": { "type": "object", "additionalProperties": true, "properties": { "query": { "type": "object" }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "stations": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "maxPowerKw": { "type": [ "number", "null" ] }, "distanceKm": { "type": [ "number", "null" ] } } } }, "revision": { "type": [ "string", "null" ] }, "generatedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "PublicVehicle": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": [ "integer", "null" ] }, "make": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "displayName": { "type": [ "string", "null" ] }, "ratedRangeKm": { "type": [ "number", "null" ] }, "batteryCapacityKwh": { "type": [ "number", "null" ] }, "connectors": { "type": "array", "items": { "type": "object" } }, "variants": { "type": "array", "items": { "type": "object" } } } }, "PublicVehicleSearchResponse": { "type": "object", "additionalProperties": true, "properties": { "query": { "type": "object" }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "vehicles": { "type": "array", "items": { "$ref": "#/components/schemas/PublicVehicle" } } } }, "PublicVehicleDetailResponse": { "type": "object", "additionalProperties": true, "properties": { "vehicle": { "$ref": "#/components/schemas/PublicVehicle" }, "routeProfile": { "type": "object" } } }, "PublicCar": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": [ "integer", "null" ] }, "title": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "maker": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "modelYear": { "type": [ "integer", "null" ] }, "price": { "type": [ "number", "null" ] }, "odometer": { "type": [ "number", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "condition": { "type": [ "string", "null" ] }, "sellerKind": { "type": "string", "enum": [ "private", "dealer" ], "description": "dealer: an imported dealer listing or the Plano Lojista." }, "batteryHealthPercent": { "type": [ "integer", "null" ], "description": "Battery state of health (SoH) in %, 50 to 100, as reported by the seller; null when not reported." }, "batteryWarrantyUntil": { "type": [ "string", "null" ], "description": "Month the battery warranty ends (YYYY-MM), as reported by the seller; null when not reported." }, "vehicle": { "type": "object", "additionalProperties": true, "properties": { "rangeKm": { "type": [ "integer", "null" ] }, "rangeStandard": { "type": [ "string", "null" ], "description": "How the range was measured: inmetro_pbev, wltp, epa, nedc, manufacturer_estimate or other; null when unknown." }, "batteryCapacityKwh": { "type": [ "number", "null" ] }, "maxAcChargingPowerKw": { "type": [ "number", "null" ], "description": "Maximum AC charging power of the catalog version (else model); null when unknown." }, "maxDcChargingPowerKw": { "type": [ "number", "null" ], "description": "Maximum DC (fast) charging power of the catalog version (else model); null when unknown." }, "connectors": { "type": "array", "items": { "type": [ "string", "null" ] }, "description": "Plugs the car charges with (ccs2, type_2, gb_t_dc, gb_t_ac, chademo, ccs1, type_1, nacs), from its native inlets." } } }, "photos": { "type": "object", "additionalProperties": true, "properties": { "count": { "type": [ "integer", "null" ] } } } } }, "PublicCarSearchResponse": { "type": "object", "additionalProperties": true, "properties": { "query": { "type": "object" }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "context": { "type": "object" }, "cars": { "type": "array", "items": { "$ref": "#/components/schemas/PublicCar" } } } }, "PublicCarDetailResponse": { "type": "object", "additionalProperties": true, "properties": { "car": { "$ref": "#/components/schemas/PublicCar" }, "related": { "type": "array", "items": { "$ref": "#/components/schemas/PublicCar" } } } }, "PublicMarketDataResponse": { "type": "object", "additionalProperties": true, "properties": { "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "canonicalUrl": { "type": [ "string", "null" ] }, "stations": { "type": "object" }, "vehicleSales": { "type": "object" }, "routes": { "type": "object" }, "stateMetrics": { "type": "array", "items": { "type": "object" } } } }, "CurrentUserResponse": { "type": "object", "additionalProperties": true, "properties": { "user": { "type": "object" }, "apiToken": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": [ "string", "null" ] }, "scopes": { "type": "array", "items": { "type": [ "string", "null" ] } } } } } }, "CarCreateInput": { "type": "object", "additionalProperties": true, "properties": { "maker": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "modelYear": { "type": [ "integer", "null" ] }, "fabricationYear": { "type": [ "integer", "null" ] }, "color": { "type": [ "string", "null" ] }, "odometer": { "type": [ "number", "null" ] }, "price": { "type": [ "number", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" }, "phone": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "content": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "batteryHealthPercent": { "type": [ "integer", "null" ], "minimum": 50, "maximum": 100, "description": "Battery state of health (SoH) in %, as the seller reports it; null clears it." }, "batteryWarrantyUntil": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}$", "description": "Month the battery warranty ends, as YYYY-MM (2032-08), as the seller reports it; null clears it." } }, "required": [ "maker", "model", "modelYear", "fabricationYear", "color", "odometer", "price", "city", "state", "email", "phone" ] }, "CarMutationInput": { "type": "object", "additionalProperties": true, "properties": { "maker": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "modelYear": { "type": [ "integer", "null" ] }, "fabricationYear": { "type": [ "integer", "null" ] }, "color": { "type": [ "string", "null" ] }, "odometer": { "type": [ "number", "null" ] }, "price": { "type": [ "number", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" }, "phone": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "content": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "batteryHealthPercent": { "type": [ "integer", "null" ], "minimum": 50, "maximum": 100, "description": "Battery state of health (SoH) in %, as the seller reports it; null clears it." }, "batteryWarrantyUntil": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}$", "description": "Month the battery warranty ends, as YYYY-MM (2032-08), as the seller reports it; null clears it." }, "active": { "type": "boolean", "description": "Updates only: false pauses a published listing, true reactivates it for free." } } }, "CarPrice": { "type": "object", "additionalProperties": true, "properties": { "amountCents": { "type": [ "integer", "null" ] }, "currency": { "type": [ "string", "null" ] }, "formatted": { "type": [ "string", "null" ] }, "billing": { "type": "string", "enum": [ "one_time", "monthly" ] } } }, "CarPublication": { "type": "object", "additionalProperties": true, "properties": { "status": { "type": "string", "enum": [ "draft", "payment_pending", "published", "paused", "sold", "expired", "removed" ] }, "message": { "type": [ "string", "null" ] }, "nextStep": { "type": [ "string", "null" ], "description": "What to do next, in plain English with any link included; null when nothing is needed." }, "readyToPublish": { "type": [ "boolean", "null" ] }, "publishWith": { "type": [ "string", "null" ], "enum": [ "payment", "business_plan", null ] }, "prices": { "type": "object", "additionalProperties": true, "properties": { "listing": { "$ref": "#/components/schemas/CarPrice" }, "empresarial": { "$ref": "#/components/schemas/CarPrice" } } }, "inactiveReason": { "type": [ "string", "null" ], "enum": [ "manual", "inactivity", null ] }, "plan": { "type": [ "string", "null" ], "enum": [ "highlight", "business", null ], "description": "highlight: paid listing, until sold for up to 12 months; business: Plano Lojista." }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "OwnedCar": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": [ "integer", "null" ] }, "maker": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "null" ] }, "batteryHealthPercent": { "type": [ "integer", "null" ] }, "batteryWarrantyUntil": { "type": [ "string", "null" ], "description": "Month the battery warranty ends, as YYYY-MM." }, "photoCount": { "type": [ "integer", "null" ] }, "publication": { "$ref": "#/components/schemas/CarPublication" }, "stats": { "type": "object", "additionalProperties": true, "properties": { "views": { "type": [ "integer", "null" ] }, "contacts": { "type": [ "integer", "null" ] }, "favorites": { "type": [ "integer", "null" ] } } }, "links": { "type": "object", "additionalProperties": true, "properties": { "manage": { "type": [ "string", "null" ], "format": "uri" }, "photos": { "type": [ "string", "null" ], "format": "uri" }, "public": { "type": [ "string", "null" ], "format": "uri" }, "boleto": { "type": [ "string", "null" ], "format": "uri" } } }, "marketPrice": { "type": "object", "additionalProperties": true, "properties": { "scope": { "type": "string", "enum": [ "year", "model" ] }, "listingCount": { "type": [ "integer", "null" ] }, "low": { "type": [ "number", "null" ] }, "median": { "type": [ "number", "null" ] }, "high": { "type": [ "number", "null" ] }, "summary": { "type": [ "string", "null" ] } } } } }, "OwnedCarsResponse": { "type": "object", "additionalProperties": true, "properties": { "cars": { "type": "array", "items": { "$ref": "#/components/schemas/OwnedCar" } } } }, "OwnedCarResponse": { "type": "object", "additionalProperties": true, "properties": { "message": { "type": [ "string", "null" ] }, "publication": { "$ref": "#/components/schemas/CarPublication" }, "nextStep": { "type": [ "string", "null" ] }, "links": { "type": "object" }, "car": { "$ref": "#/components/schemas/OwnedCar" } } }, "CarDeleteResponse": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": [ "integer", "null" ] }, "outcome": { "type": "string", "enum": [ "deleted", "removed" ] }, "deleted": { "type": [ "boolean", "null" ] }, "archived": { "type": [ "boolean", "null" ] }, "message": { "type": [ "string", "null" ] } } }, "CarCheckoutInput": { "type": "object", "additionalProperties": true, "properties": { "plan": { "type": "string", "enum": [ "listing", "empresarial" ], "description": "listing (default): one payment, until sold for up to 12 months, first in search; empresarial: the monthly Plano Lojista." } } }, "CarCheckoutResponse": { "type": "object", "additionalProperties": true, "properties": { "published": { "type": [ "boolean", "null" ] }, "plan": { "type": [ "string", "null" ] }, "checkout": { "type": "object", "additionalProperties": true, "properties": { "url": { "type": [ "string", "null" ], "format": "uri" }, "sessionId": { "type": [ "string", "null" ] }, "plan": { "type": "string", "enum": [ "listing", "empresarial" ] }, "amountCents": { "type": [ "integer", "null" ] }, "currency": { "type": [ "string", "null" ] }, "price": { "type": [ "string", "null" ] }, "billing": { "type": "string", "enum": [ "one_time", "monthly" ] }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "reused": { "type": [ "boolean", "null" ] }, "trialEndsAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Plano Lojista with 30 free days: when the first charge falls. Null otherwise." } } }, "message": { "type": [ "string", "null" ] }, "nextStep": { "type": [ "string", "null" ] }, "car": { "$ref": "#/components/schemas/OwnedCar" } } }, "CarContactInput": { "type": "object", "additionalProperties": true, "properties": { "message": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "The message the seller receives." }, "phone": { "type": "string", "description": "Optional phone or WhatsApp with area code, shared with the seller." } }, "required": [ "message" ] }, "CarContactResponse": { "type": "object", "additionalProperties": true, "properties": { "sent": { "type": [ "boolean", "null" ] }, "carId": { "type": [ "integer", "null" ] }, "sentAs": { "type": "object", "additionalProperties": true, "properties": { "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" } } }, "message": { "type": [ "string", "null" ] }, "links": { "type": "object", "additionalProperties": true, "properties": { "listing": { "type": [ "string", "null" ], "format": "uri" } } } } }, "LocationMutationInput": { "type": "object", "additionalProperties": true, "properties": { "name": { "type": [ "string", "null" ], "maxLength": 160 }, "address": { "type": [ "string", "null" ], "maxLength": 500, "description": "Required with latitude/longitude; filled from the map with placeId when omitted." }, "placeId": { "type": [ "string", "null" ], "description": "Where the station is: the id of a GET /api/public/places result, instead of latitude/longitude." }, "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 }, "restricted": { "type": [ "boolean", "null" ] }, "enabled": { "type": [ "boolean", "null" ] }, "open247": { "type": [ "boolean", "null" ], "description": "true clears hours, as the add-station form does." }, "isFree": { "type": [ "boolean", "null" ], "description": "true clears both prices and their comments." }, "description": { "type": [ "string", "null" ], "description": "Plain text or simple HTML, cleaned like the site; up to 3,000 characters of text on create and 10,000 on update." }, "hours": { "type": [ "string", "null" ], "description": "Up to 1,000 characters on create and 500 on update." }, "formattedPhoneNumber": { "type": [ "string", "null" ], "description": "A Brazilian phone with area code on create; any valid phone on update. Also stored as phoneNumber." }, "priceKwh": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1000000, "description": "BRL per kWh, at most 2 decimals." }, "activationPrice": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1000000, "description": "BRL per session, at most 2 decimals." }, "amenityIds": { "type": "array", "items": { "type": [ "integer", "null" ] }, "description": "Every amenity the station has, as ids from GET /api/public/station-filters." }, "appLinks": { "type": "object", "additionalProperties": true, "properties": { "ios": { "type": [ "string", "null" ], "format": "uri" }, "android": { "type": [ "string", "null" ], "format": "uri" }, "website": { "type": [ "string", "null" ], "format": "uri" } }, "description": "App Store, Google Play and HTTPS links, reviewed by Carregados before they appear. Links left out keep their current value." }, "stations": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": [ "integer", "null" ] }, "networkId": { "type": [ "integer", "null" ], "description": "An approved network id." }, "kilowatts": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 1000 }, "outlets": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": [ "integer", "null" ] }, "connector": { "type": [ "integer", "string" ], "description": "A catalog connector id or a plug name: CCS2, Tipo 2, CHAdeMO, Tipo 1 (J-1772), GB/T DC, GB/T AC, CCS1, NACS, Tomada…" } } }, "minItems": 1, "maxItems": 20 } } }, "minItems": 1, "maxItems": 10 }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "confirmNotDuplicate": { "type": [ "boolean", "null" ], "description": "Create only: true after the user confirmed the station is none of the possibleDuplicates." } } }, "LocationUpdateInput": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/LocationMutationInput" }, { "type": "object", "additionalProperties": true, "properties": { "removedStationIds": { "type": "array", "items": { "type": [ "integer", "null" ] }, "description": "Ids of existing chargers left out of stations, confirmed for removal. Without them the API answers 409 with wouldRemove." }, "removedOutletIds": { "type": "array", "items": { "type": [ "integer", "null" ] }, "description": "Ids of existing outlets left out of chargers that stay, confirmed for removal." } } } ] }, "LocationCreateInput": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/LocationMutationInput" } ], "required": [ "name", "restricted", "enabled", "open247", "isFree", "stations" ], "description": "Also send placeId, or latitude and longitude with address." }, "LocationAnalyticsTotals": { "type": "object", "additionalProperties": true, "properties": { "profileViews": { "type": [ "integer", "null" ] }, "directionsOpened": { "type": [ "integer", "null" ] }, "reviews": { "type": [ "integer", "null" ] }, "favorites": { "type": [ "integer", "null" ] }, "photos": { "type": [ "integer", "null" ] } } }, "LocationAnalyticsResponse": { "type": "object", "additionalProperties": true, "properties": { "station": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] } } }, "period": { "type": "string", "enum": [ "7d", "30d", "90d", "all" ] }, "range": { "type": "object", "additionalProperties": true, "properties": { "start": { "type": [ "string", "null" ], "format": "date" }, "end": { "type": [ "string", "null" ], "format": "date" } } }, "totals": { "$ref": "#/components/schemas/LocationAnalyticsTotals" }, "previous": { "type": [ "object", "null" ], "properties": { "range": { "type": "object", "additionalProperties": true, "properties": { "start": { "type": [ "string", "null" ], "format": "date" }, "end": { "type": [ "string", "null" ], "format": "date" } } }, "totals": { "$ref": "#/components/schemas/LocationAnalyticsTotals" } } }, "routeSuggestions": { "type": [ "object", "null" ], "properties": { "plans": { "type": [ "integer", "null" ] }, "appearances": { "type": [ "integer", "null" ] }, "historicalPlans": { "type": [ "integer", "null" ] } } }, "daily": { "type": "array", "items": { "type": "object" } }, "generatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "links": { "type": "object", "additionalProperties": true, "properties": { "analytics": { "type": [ "string", "null" ], "format": "uri" } } } } }, "RoutePlanStop": { "type": "object", "additionalProperties": true, "properties": { "kind": { "type": "string", "enum": [ "charge", "stop" ] }, "stationId": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ], "format": "uri" }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "network": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "selection": { "type": [ "string", "null" ], "enum": [ "required", "preferred", "automatic", null ] }, "distanceFromStartKm": { "type": [ "number", "null" ] }, "arrivalBatteryPercent": { "type": [ "number", "null" ] }, "departureBatteryPercent": { "type": [ "number", "null" ] }, "chargingMinutes": { "type": [ "integer", "null" ] }, "energyAddedKwh": { "type": [ "number", "null" ] }, "chargingPowerKw": { "type": [ "number", "null" ] }, "expectedWaitMinutes": { "type": [ "integer", "null" ] } }, "description": "A charging stop (kind charge) or a stop the request asked for (kind stop), in route order. No coordinates." }, "PublicStationFilters": { "type": "object", "additionalProperties": true, "properties": { "connectors": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "name": { "type": [ "string", "null" ] }, "current": { "type": [ "string", "null" ] }, "connectorIds": { "type": "array", "items": { "type": [ "integer", "null" ] } } } } }, "amenities": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] } } } }, "placeTypes": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "value": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } } } }, "networks": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "stations": { "type": [ "integer", "null" ] } } } }, "networkCount": { "type": [ "integer", "null" ] }, "networkQuery": { "type": [ "string", "null" ] }, "usage": { "type": "object" } } }, "RoutePlanWaypoint": { "type": "object", "additionalProperties": true, "properties": { "latitude": { "type": [ "number", "null" ] }, "longitude": { "type": [ "number", "null" ] }, "placeId": { "type": "string", "description": "The id of a GET /api/public/places result, instead of latitude/longitude." }, "stationId": { "type": [ "integer", "null" ], "description": "A station to route to or charge at, instead of latitude/longitude." }, "label": { "type": [ "string", "null" ] } }, "description": "One of latitude/longitude, placeId or stationId, with an optional label (a station waypoint defaults to its name)." }, "RoutePlanInput": { "type": "object", "additionalProperties": true, "properties": { "waypoints": { "type": "array", "items": { "$ref": "#/components/schemas/RoutePlanWaypoint" } }, "vehicleId": { "type": [ "integer", "null" ] }, "subtypeId": { "type": [ "integer", "null" ] }, "garageVehicleId": { "type": [ "integer", "null" ] }, "rangeKm": { "type": [ "number", "null" ] }, "batteryCapacityKwh": { "type": [ "number", "null" ] }, "initialBatteryPercent": { "type": [ "number", "null" ] }, "minimumReserveSocPercent": { "type": [ "number", "null" ], "minimum": 0, "maximum": 90, "description": "Reserve SOC for router v2. Defaults to min(10, arrival target); cannot exceed the arrival target." }, "arrivalBatteryTargetPercent": { "type": [ "number", "null" ] }, "maximumDcChargePowerKw": { "type": [ "number", "null" ], "exclusiveMinimum": 0, "maximum": 1500, "description": "The car DC charging limit in kW. Filled from vehicleId or garageVehicleId when the catalog knows it; when omitted, no vehicle limit is applied." }, "maximumAcChargePowerKw": { "type": [ "number", "null" ], "minimum": 1, "maximum": 43, "description": "The car onboard (AC) charger limit in kW. Filled from vehicleId or garageVehicleId when the catalog knows it; when omitted, AC stations are planned at their reported power." }, "routeMode": { "type": "string", "enum": [ "fastest", "fewer_stops" ] }, "autoPlan": { "type": [ "boolean", "null" ], "description": "Plan charging stops (default true). A plug-in hybrid or range extender from vehicleId or garageVehicleId is always routed without charging stops: its combustion engine keeps it going once the battery runs low." }, "allowFerries": { "type": [ "boolean", "null" ] }, "blockedStationIds": { "type": "array", "items": { "type": [ "integer", "null" ] } }, "preferredStationIds": { "type": "array", "items": { "type": [ "integer", "null" ] } }, "networkIds": { "type": "array", "items": { "type": [ "integer", "null" ] } }, "includeRoute": { "type": [ "boolean", "null" ], "description": "Include the router's full response as route (default true). It holds the route line and every alternative; stops, destination and notices summarize the trip without it." } }, "required": [ "waypoints" ] }, "RoutePlanResponse": { "type": "object", "additionalProperties": true, "properties": { "route": { "type": [ "object", "null" ], "description": "The router's full response; null when includeRoute is false." }, "routeId": { "type": [ "string", "null" ] }, "claimToken": { "type": "string", "description": "Anonymous plans only. Send it to POST /api/v1/trips within 24 hours to save this route after signing in." }, "saved": { "type": [ "boolean", "null" ] }, "overview": { "type": "object", "additionalProperties": true, "properties": { "totalTimeHours": { "type": [ "number", "null" ] }, "totalTimeText": { "type": [ "string", "null" ] }, "totalDistanceKm": { "type": [ "number", "null" ] }, "totalDistanceText": { "type": [ "string", "null" ] }, "drivingTimeHours": { "type": [ "number", "null" ] }, "drivingTimeText": { "type": [ "string", "null" ] }, "chargingTimeHours": { "type": [ "number", "null" ] }, "chargingTimeText": { "type": [ "string", "null" ] }, "co2SavedKg": { "type": [ "number", "null" ] }, "co2SavedText": { "type": [ "string", "null" ] }, "chargingStopCount": { "type": [ "integer", "null" ] }, "waypointCount": { "type": [ "integer", "null" ] } } }, "stops": { "type": "array", "items": { "$ref": "#/components/schemas/RoutePlanStop" } }, "destination": { "type": "object", "additionalProperties": true, "properties": { "name": { "type": [ "string", "null" ] }, "distanceFromStartKm": { "type": [ "number", "null" ] }, "arrivalBatteryPercent": { "type": [ "number", "null" ] } } }, "notices": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "code": { "type": [ "string", "null" ] }, "severity": { "type": "string", "enum": [ "critical", "warning" ] }, "title": { "type": [ "string", "null" ] }, "text": { "type": [ "string", "null" ] } } } }, "links": { "type": "object", "additionalProperties": true, "properties": { "map": { "type": "object", "additionalProperties": true, "properties": { "label": { "type": [ "string", "null" ] }, "href": { "type": [ "string", "null" ] } } } } }, "controls": { "type": "object", "additionalProperties": true, "properties": { "authRequired": { "type": [ "boolean", "null" ] }, "authOptional": { "type": [ "boolean", "null" ] }, "authenticated": { "type": [ "boolean", "null" ] }, "scope": { "type": [ "string", "null" ] }, "confirmationRequired": { "type": [ "boolean", "null" ] }, "costed": { "type": [ "boolean", "null" ] }, "rateLimited": { "type": [ "boolean", "null" ] }, "persisted": { "type": [ "boolean", "null" ] } } }, "request": { "type": "object" } } }, "OwnedLocationsResponse": { "type": "object", "additionalProperties": true, "properties": { "locations": { "type": "array", "items": { "type": "object" } }, "pagination": { "type": "object", "additionalProperties": true, "properties": { "limit": { "type": [ "integer", "null" ] }, "nextCursor": { "type": [ "string", "null" ] } } } } }, "OwnedLocationResponse": { "type": "object", "additionalProperties": true, "properties": { "message": { "type": [ "string", "null" ] }, "review": { "type": "object" }, "location": { "type": "object" } } }, "GarageVehicleCreateInput": { "type": "object", "additionalProperties": true, "properties": { "catalogVehicleId": { "type": [ "integer", "null" ] }, "subtypeId": { "type": [ "integer", "null" ] }, "ratedRangeKm": { "type": [ "number", "null" ] }, "batteryCapacityKwh": { "type": [ "number", "null" ] }, "isPrimary": { "type": [ "boolean", "null" ] } }, "required": [ "catalogVehicleId" ] }, "GarageVehicleUpdateInput": { "type": "object", "additionalProperties": true, "properties": { "ratedRangeKm": { "type": [ "number", "null" ] }, "batteryCapacityKwh": { "type": [ "number", "null" ] }, "isPrimary": { "type": [ "boolean", "null" ] } } }, "GarageVehicleResponse": { "type": "object", "additionalProperties": true, "properties": { "vehicle": { "type": "object" } } }, "GarageVehiclesResponse": { "type": "object", "additionalProperties": true, "properties": { "vehicles": { "type": "array", "items": { "type": "object" } } } }, "FavoriteStationsResponse": { "type": "object", "additionalProperties": true, "properties": { "favorites": { "type": "array", "items": { "type": "object" } } } }, "FavoriteMutationResponse": { "type": "object", "additionalProperties": true, "properties": { "favorite": { "type": [ "boolean", "null" ] }, "stationId": { "type": [ "integer", "null" ] } } }, "FavoriteCarsResponse": { "type": "object", "additionalProperties": true, "properties": { "favorites": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "car": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": [ "integer", "null" ] }, "title": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "null" ] }, "priceFormatted": { "type": [ "string", "null" ] }, "forSale": { "type": [ "boolean", "null" ] }, "links": { "type": "object", "additionalProperties": true, "properties": { "web": { "type": [ "string", "null" ], "format": "uri" }, "api": { "type": [ "string", "null" ], "format": "uri" } } } } } } } } } }, "FavoriteCarMutationResponse": { "type": "object", "additionalProperties": true, "properties": { "favorite": { "type": [ "boolean", "null" ] }, "carId": { "type": [ "integer", "null" ] } } }, "SaveTripInput": { "type": "object", "additionalProperties": true, "properties": { "routeId": { "type": [ "string", "null" ] }, "claimToken": { "type": "string", "description": "claimToken from the anonymous plan response of this route. Valid for 24 hours after planning." } }, "required": [ "routeId" ] }, "TripUpdateInput": { "type": "object", "additionalProperties": true, "properties": { "title": { "type": [ "string", "null" ] }, "saved": { "type": [ "boolean", "null" ] }, "archived": { "type": [ "boolean", "null" ] }, "rating": { "type": [ "integer", "null" ] }, "departure": { "type": [ "object", "null" ], "description": "Departure alert: a day before, Carregados re-plans the route and emails the result. 30 minutes to 180 days ahead; null removes it. Needs a saved, unarchived trip.", "properties": { "local": { "type": "string", "description": "Local time, \"YYYY-MM-DDTHH:mm\"." }, "timeZone": { "type": "string", "description": "IANA time zone, e.g. America/Sao_Paulo." } }, "required": [ "local", "timeZone" ] } } }, "TripResponse": { "type": "object", "additionalProperties": true, "properties": { "trip": { "type": "object", "description": "The trip summary; the detail and PATCH also return stops, destination, notices, departure, outcome.form and links.view." }, "message": { "type": [ "string", "null" ] } } }, "TripsResponse": { "type": "object", "additionalProperties": true, "properties": { "trips": { "type": "array", "items": { "type": "object" } }, "page": { "type": "object" } } }, "CheckInCreateInput": { "type": "object", "additionalProperties": true, "properties": { "outcome": { "type": "string", "enum": [ "success", "neutral", "failure" ] }, "comment": { "type": [ "string", "null" ] }, "powerKw": { "type": [ "number", "null" ], "minimum": 1, "maximum": 350, "description": "Observed charge power in kW, from 1 to 350, or null." }, "sharedPower": { "type": [ "boolean", "null" ], "description": "A successful charge at powerKw (1 to 350 kW) that shared the charger power with another car." } }, "required": [ "outcome", "comment", "powerKw" ] }, "CheckInResponse": { "type": "object", "additionalProperties": true, "properties": { "checkIn": { "type": "object" } } }, "CheckInsResponse": { "type": "object", "additionalProperties": true, "properties": { "checkIns": { "type": "array", "items": { "type": "object" } }, "page": { "type": "object" } } }, "CheckInReplyInput": { "type": "object", "additionalProperties": true, "properties": { "message": { "type": [ "string", "null" ] } }, "required": [ "message" ] }, "CheckInReplyResponse": { "type": "object", "additionalProperties": true, "properties": { "reply": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": [ "string", "null" ] }, "checkInId": { "type": [ "string", "null" ] }, "stationId": { "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "message": { "type": [ "string", "null" ] }, "links": { "type": "object" } } }, "CheckInRepliesResponse": { "type": "object", "additionalProperties": true, "properties": { "checkIn": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": [ "string", "null" ] }, "stationId": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } } }, "replies": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "author": { "type": "object", "additionalProperties": true, "properties": { "username": { "type": [ "string", "null" ] } } }, "isYours": { "type": [ "boolean", "null" ] } } } } } }, "StationCorrectionInput": { "type": "object", "additionalProperties": true, "properties": { "name": { "type": [ "string", "null" ] }, "location": { "type": "object", "additionalProperties": true, "properties": { "address": { "type": [ "string", "null" ] }, "placeId": { "type": [ "string", "null" ], "description": "A /api/public/places result id." }, "latitude": { "type": [ "number", "null" ] }, "longitude": { "type": [ "number", "null" ] } } }, "hours": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ], "description": "Null when the station has no phone." }, "priceKwh": { "type": [ "number", "null" ] }, "priceKwhComment": { "type": [ "string", "null" ] }, "activationPrice": { "type": [ "number", "null" ] }, "activationPriceComment": { "type": [ "string", "null" ] }, "accessType": { "type": "string", "enum": [ "public", "restricted" ] }, "amenityIds": { "type": "array", "items": { "type": [ "integer", "null" ] } }, "stations": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "kilowatts": { "type": [ "number", "null" ] }, "networkId": { "type": [ "integer", "null" ] }, "outlets": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "connector": { "type": [ "integer", "string" ], "description": "A connector id or a plug name such as CCS2 or Tipo 2." }, "connectorName": { "type": [ "string", "null" ] } } } } } }, "description": "Every charger the station has, without ids; chargers left out are proposed for removal." }, "networkId": { "type": [ "integer", "null" ] }, "kilowatts": { "type": [ "number", "null" ] }, "description": { "type": [ "string", "null" ] }, "appLinks": { "type": "object", "additionalProperties": true, "properties": { "appleAppStoreUrl": { "type": [ "string", "null" ] }, "googlePlayStoreUrl": { "type": [ "string", "null" ] }, "websiteUrl": { "type": [ "string", "null" ] } } }, "comment": { "type": [ "string", "null" ], "description": "Optional note for the reviewers." } } }, "StationCorrectionResponse": { "type": "object", "additionalProperties": true, "properties": { "message": { "type": [ "string", "null" ] }, "stationId": { "type": [ "integer", "null" ] }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "field": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "applied", "pending_review", "rejected" ] }, "correctionId": { "type": [ "string", "null" ] }, "pointsAwarded": { "type": [ "integer", "null" ] }, "reason": { "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] } } } }, "summary": { "type": "object", "additionalProperties": true, "properties": { "applied": { "type": [ "integer", "null" ] }, "pendingReview": { "type": [ "integer", "null" ] }, "rejected": { "type": [ "integer", "null" ] }, "pointsAwarded": { "type": [ "integer", "null" ] } } }, "links": { "type": "object" } } }, "CorrectionsResponse": { "type": "object", "additionalProperties": true, "properties": { "corrections": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": [ "string", "null" ] }, "stationId": { "type": [ "integer", "null" ] }, "station": { "type": "object" }, "field": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "suggestedValue": { "type": [ "string", "null" ] }, "comment": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } } } }, "page": { "type": "object" } } }, "TripOutcomeInput": { "type": "object", "additionalProperties": true, "properties": { "answer": { "type": "string", "enum": [ "report", "not_taken", "not_yet", "later" ] }, "originDepartureSocPercent": { "type": [ "integer", "null" ] }, "stops": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "stationId": { "type": [ "string", "null" ] }, "arrivalSocPercent": { "type": [ "integer", "null" ] }, "chargeOutcome": { "type": [ "string", "null" ], "enum": [ "success", "failure", "skipped", null ] }, "departureSocPercent": { "type": [ "integer", "null" ] }, "failureReason": { "type": [ "string", "null" ], "enum": [ "broken", "busy", "rejected", "other", null ] }, "chargedElsewhere": { "type": [ "boolean", "null" ] }, "elsewhereDepartureSocPercent": { "type": [ "integer", "null" ] } } } }, "destinationArrivalSocPercent": { "type": [ "integer", "null" ] }, "destinationChargedElsewhere": { "type": [ "boolean", "null" ] }, "destinationElsewhereDepartureSocPercent": { "type": [ "integer", "null" ] } }, "required": [ "answer" ] }, "TripOutcomeResponse": { "type": "object", "additionalProperties": true, "properties": { "answer": { "type": [ "string", "null" ] }, "reported": { "type": [ "boolean", "null" ] }, "tripTaken": { "type": [ "boolean", "null" ] }, "checkInsPublished": { "type": [ "integer", "null" ] }, "feedback": { "type": "object" }, "snoozedUntil": { "type": [ "string", "null" ], "format": "date-time" }, "asksAgain": { "type": [ "boolean", "null" ] }, "message": { "type": [ "string", "null" ] } } }, "ShareCreateInput": { "type": "object", "additionalProperties": true, "properties": { "kind": { "type": "string", "enum": [ "trip", "station", "vehicle" ] }, "id": { "type": [ "string", "integer" ], "description": "Trip id, station id, or car listing id." } }, "required": [ "kind", "id" ] }, "ShareResponse": { "type": "object", "additionalProperties": true, "properties": { "share": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": [ "string", "null" ] }, "kind": { "type": [ "string", "null" ] }, "resourceId": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "text": { "type": [ "string", "null" ] }, "whatsappUrl": { "type": [ "string", "null" ] }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "nextStep": { "type": [ "string", "null" ] } } }, "NotificationMutationInput": { "type": "object", "additionalProperties": true, "properties": { "intent": { "type": "string", "enum": [ "mark-as-read", "mark-as-unread", "delete" ] }, "notificationIds": { "type": "array", "items": { "type": [ "string", "null" ] } } }, "required": [ "intent" ] }, "NotificationsResponse": { "type": "object", "additionalProperties": true, "properties": { "notifications": { "type": "array", "items": { "type": "object" } }, "counts": { "type": "object" }, "page": { "type": "object" } } }, "NotificationMutationResponse": { "type": "object", "additionalProperties": true, "properties": { "success": { "type": [ "boolean", "null" ] }, "intent": { "type": [ "string", "null" ] }, "notificationIds": { "type": "array", "items": { "type": [ "string", "null" ] } }, "counts": { "type": "object" } } }, "NotificationPreferencePatch": { "type": "object", "additionalProperties": true, "properties": { "threadMessagesEmail": { "type": [ "boolean", "null" ] }, "threadMessagesInApp": { "type": [ "boolean", "null" ] }, "threadMentionsEmail": { "type": [ "boolean", "null" ] }, "threadMentionsInApp": { "type": [ "boolean", "null" ] }, "reviewRepliesEmail": { "type": [ "boolean", "null" ] }, "reviewRepliesInApp": { "type": [ "boolean", "null" ] }, "stationCheckinsEmail": { "type": [ "boolean", "null" ] }, "stationActivityInApp": { "type": [ "boolean", "null" ] }, "favoriteStationActivityInApp": { "type": [ "boolean", "null" ] }, "favoriteStationDigestEmail": { "type": [ "boolean", "null" ] }, "cityDigestEmail": { "type": [ "boolean", "null" ] }, "savedTripAlertsEmail": { "type": [ "boolean", "null" ] }, "tripCheckInEmail": { "type": [ "boolean", "null" ] }, "nextBestActionsInApp": { "type": [ "boolean", "null" ] }, "engagementEmailWeeklyCap": { "type": [ "integer", "null" ] }, "timeZone": { "type": [ "string", "null" ] }, "quietHoursStartMinute": { "type": [ "integer", "null" ] }, "quietHoursEndMinute": { "type": [ "integer", "null" ] } } }, "NotificationPreferencesResponse": { "type": "object", "additionalProperties": true, "properties": { "preferences": { "type": "object" } } }, "CarAlert": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": [ "string", "null" ] }, "maker": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "label": { "type": [ "string", "null" ] }, "state": { "type": "string", "enum": [ "active", "paused" ] }, "followedAt": { "type": [ "string", "null" ], "format": "date-time" }, "links": { "type": "object", "additionalProperties": true, "properties": { "web": { "type": [ "string", "null" ], "format": "uri" } } } } }, "CarAlertsResponse": { "type": "object", "additionalProperties": true, "properties": { "status": { "type": "string", "enum": [ "changed", "unchanged" ], "description": "PATCH only." }, "message": { "type": "string", "description": "PATCH only." }, "enabled": { "type": [ "boolean", "null" ] }, "limit": { "type": [ "integer", "null" ] }, "count": { "type": [ "integer", "null" ] }, "alerts": { "type": "array", "items": { "$ref": "#/components/schemas/CarAlert" } }, "links": { "type": "object", "additionalProperties": true, "properties": { "manage": { "type": [ "string", "null" ], "format": "uri" } } } } }, "CarAlertFollowInput": { "type": "object", "additionalProperties": true, "properties": { "maker": { "type": "string", "minLength": 1, "maxLength": 80 }, "model": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "maker", "model" ] }, "CarAlertsUpdateInput": { "type": "object", "additionalProperties": true, "properties": { "enabled": { "type": [ "boolean", "null" ] } }, "required": [ "enabled" ] }, "CarAlertFollowResponse": { "type": "object", "additionalProperties": true, "properties": { "status": { "type": "string", "enum": [ "followed", "unchanged" ] }, "message": { "type": [ "string", "null" ] }, "alert": { "$ref": "#/components/schemas/CarAlert" }, "enabled": { "type": [ "boolean", "null" ] }, "count": { "type": [ "integer", "null" ] }, "limit": { "type": [ "integer", "null" ] }, "links": { "type": "object", "additionalProperties": true, "properties": { "manage": { "type": [ "string", "null" ], "format": "uri" } } } } }, "CarAlertRemoveResponse": { "type": "object", "additionalProperties": true, "properties": { "removed": { "type": [ "boolean", "null" ] }, "alertId": { "type": [ "string", "null" ] }, "label": { "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] }, "enabled": { "type": [ "boolean", "null" ] }, "count": { "type": [ "integer", "null" ] }, "links": { "type": "object", "additionalProperties": true, "properties": { "manage": { "type": [ "string", "null" ], "format": "uri" } } } } }, "HighlightCheckoutResponse": { "type": "object", "additionalProperties": true, "properties": { "status": { "type": "string", "enum": [ "checkout_created", "confirm_in_browser" ] }, "message": { "type": [ "string", "null" ] }, "checkout": { "type": "object", "additionalProperties": true, "properties": { "url": { "type": [ "string", "null" ], "format": "uri" }, "sessionId": { "type": [ "string", "null" ] }, "locationId": { "type": [ "integer", "null" ] }, "locationName": { "type": [ "string", "null" ] }, "bundleId": { "type": [ "string", "null" ] }, "reused": { "type": [ "boolean", "null" ] }, "monthlyAmount": { "$ref": "#/components/schemas/Money" } } }, "newMonthlyAmount": { "$ref": "#/components/schemas/Money" }, "links": { "$ref": "#/components/schemas/DestaqueLinks" }, "nextStep": { "type": [ "string", "null" ] } } }, "Money": { "type": "object", "additionalProperties": true, "properties": { "cents": { "type": [ "integer", "null" ] }, "formatted": { "type": [ "string", "null" ] } }, "required": [ "cents", "formatted" ] }, "DestaqueLinks": { "type": "object", "description": "Absolute browser URLs: plan (/ajustes/destaque), picker (multi-station picker, also for whole networks and OCPI connections), and when relevant payment, billing, switchToCard, contact, portal or manage.", "additionalProperties": { "type": "string", "format": "uri" } }, "DestaqueStation": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "available", "in_plan", "individual_subscription", "unavailable", "not_found" ] }, "eligible": { "type": [ "boolean", "null" ] }, "reason": { "type": [ "string", "null" ] } } }, "DestaqueBlocked": { "type": "object", "additionalProperties": true, "properties": { "code": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] } } }, "DestaqueQuote": { "type": "object", "additionalProperties": true, "properties": { "quoteId": { "type": [ "string", "null" ] }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "addCount": { "type": [ "integer", "null" ] }, "locationCount": { "type": [ "integer", "null" ] }, "monthlyAmount": { "$ref": "#/components/schemas/Money" }, "perStationAmount": { "$ref": "#/components/schemas/Money" }, "savingsPercent": { "type": [ "integer", "null" ] }, "currentLocationCount": { "type": [ "integer", "null" ] }, "currentMonthlyAmount": { "$ref": "#/components/schemas/Money" }, "dueNow": { "$ref": "#/components/schemas/Money" }, "prorated": { "type": [ "boolean", "null" ] }, "prorationDate": { "type": [ "string", "null" ], "format": "date-time" }, "renewalDate": { "type": [ "string", "null" ], "format": "date-time" } } }, "DestaqueStateResponse": { "type": "object", "additionalProperties": true, "properties": { "plan": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "statusLabel": { "type": [ "string", "null" ] }, "locationCount": { "type": [ "integer", "null" ] }, "monthlyAmount": { "$ref": "#/components/schemas/Money" }, "perStationAmount": { "$ref": "#/components/schemas/Money" }, "currentPeriodEnd": { "type": [ "string", "null" ], "format": "date-time" }, "cancelAtPeriodEnd": { "type": [ "boolean", "null" ] }, "cardRenewalGraceEndsAt": { "type": [ "string", "null" ], "format": "date-time" }, "paymentMethod": { "type": [ "string", "null" ] }, "canAddStations": { "type": [ "boolean", "null" ] }, "canRemoveStations": { "type": [ "boolean", "null" ] }, "blocked": { "$ref": "#/components/schemas/DestaqueBlocked" }, "stations": { "type": "array", "items": { "$ref": "#/components/schemas/DestaqueStation" } }, "openInvoice": { "type": "object", "additionalProperties": true, "properties": { "url": { "type": [ "string", "null" ], "format": "uri" }, "boleto": { "type": [ "boolean", "null" ] }, "dueDate": { "type": [ "string", "null" ], "format": "date-time" }, "amount": { "$ref": "#/components/schemas/Money" } } }, "pendingChange": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "paymentUrl": { "type": [ "string", "null" ], "format": "uri" } } } } }, "unpaidCheckout": { "type": "object", "additionalProperties": true, "properties": { "locationCount": { "type": [ "integer", "null" ] }, "monthlyAmount": { "$ref": "#/components/schemas/Money" }, "stations": { "type": "array", "items": { "$ref": "#/components/schemas/DestaqueStation" } }, "resumeUrl": { "type": [ "string", "null" ], "format": "uri" } } }, "individualSubscriptions": { "type": "object", "additionalProperties": true, "properties": { "count": { "type": [ "integer", "null" ] }, "status": { "type": [ "string", "null" ] }, "currentPeriodEnd": { "type": [ "string", "null" ], "format": "date-time" }, "cancelAtPeriodEnd": { "type": [ "boolean", "null" ] }, "monthlyAmount": { "$ref": "#/components/schemas/Money" }, "paymentMethod": { "type": [ "string", "null" ] }, "station": { "$ref": "#/components/schemas/DestaqueStation" }, "canAddStations": { "type": [ "boolean", "null" ] }, "blocked": { "$ref": "#/components/schemas/DestaqueBlocked" } } }, "individualCardGrace": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "subscriptionId": { "type": [ "string", "null" ] }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "paymentUrl": { "type": [ "string", "null" ], "format": "uri" } } } }, "pricing": { "type": "object", "additionalProperties": true, "properties": { "anchors": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "locationCount": { "type": [ "integer", "null" ] }, "monthlyAmount": { "$ref": "#/components/schemas/Money" }, "perStationAmount": { "$ref": "#/components/schemas/Money" } } } }, "note": { "type": [ "string", "null" ] } } }, "links": { "$ref": "#/components/schemas/DestaqueLinks" }, "nextStep": { "type": [ "string", "null" ] } } }, "DestaqueQuoteInput": { "type": "object", "additionalProperties": true, "properties": { "locationIds": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "minItems": 1, "maxItems": 2000 } }, "required": [ "locationIds" ] }, "DestaqueQuoteResponse": { "type": "object", "additionalProperties": true, "properties": { "mode": { "type": "string", "enum": [ "new", "add", "individual_subscription", "blocked" ] }, "canCheckout": { "type": [ "boolean", "null" ] }, "stations": { "type": "array", "items": { "$ref": "#/components/schemas/DestaqueStation" } }, "toAdd": { "type": "array", "items": { "type": [ "integer", "null" ] } }, "alreadyInPlan": { "type": "array", "items": { "type": [ "integer", "null" ] } }, "refused": { "type": "array", "items": { "type": [ "integer", "null" ] } }, "blocked": { "$ref": "#/components/schemas/DestaqueBlocked" }, "quote": { "$ref": "#/components/schemas/DestaqueQuote" }, "unpaidCheckout": { "type": "object", "additionalProperties": true, "properties": { "locationCount": { "type": [ "integer", "null" ] }, "monthlyAmount": { "$ref": "#/components/schemas/Money" }, "resumeUrl": { "type": [ "string", "null" ], "format": "uri" }, "replaced": { "type": [ "boolean", "null" ] } } }, "confirmationMessage": { "type": [ "string", "null" ] }, "links": { "$ref": "#/components/schemas/DestaqueLinks" }, "nextStep": { "type": [ "string", "null" ] } } }, "DestaqueCheckoutInput": { "type": "object", "additionalProperties": true, "properties": { "locationIds": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "minItems": 1, "maxItems": 2000 }, "quoteId": { "type": [ "string", "null" ] }, "idempotencyKey": { "type": [ "string", "null" ] } }, "required": [ "locationIds" ] }, "DestaqueCheckoutResponse": { "type": "object", "additionalProperties": true, "properties": { "status": { "type": "string", "enum": [ "checkout_created", "applied", "payment_pending", "quote_required", "unchanged" ] }, "mode": { "type": [ "string", "null" ] }, "planId": { "type": [ "string", "null" ] }, "quoteId": { "type": [ "string", "null" ] }, "quote": { "$ref": "#/components/schemas/DestaqueQuote" }, "confirmationMessage": { "type": [ "string", "null" ] }, "checkout": { "type": "object", "additionalProperties": true, "properties": { "url": { "type": [ "string", "null" ], "format": "uri" }, "sessionId": { "type": [ "string", "null" ] }, "bundleId": { "type": [ "string", "null" ] }, "reused": { "type": [ "boolean", "null" ] }, "locationCount": { "type": [ "integer", "null" ] }, "monthlyAmount": { "$ref": "#/components/schemas/Money" }, "perStationAmount": { "$ref": "#/components/schemas/Money" } } }, "charged": { "$ref": "#/components/schemas/Money" }, "dueNow": { "$ref": "#/components/schemas/Money" }, "paymentUrl": { "type": [ "string", "null" ], "format": "uri" }, "plan": { "type": "object", "additionalProperties": true, "properties": { "locationCount": { "type": [ "integer", "null" ] }, "monthlyAmount": { "$ref": "#/components/schemas/Money" }, "perStationAmount": { "$ref": "#/components/schemas/Money" } } }, "added": { "type": "array", "items": { "$ref": "#/components/schemas/DestaqueStation" } }, "alreadyInPlan": { "type": "array", "items": { "type": [ "integer", "null" ] } }, "links": { "$ref": "#/components/schemas/DestaqueLinks" }, "nextStep": { "type": [ "string", "null" ] } } }, "DestaqueRemoveInput": { "type": "object", "additionalProperties": true, "properties": { "locationIds": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "minItems": 1, "maxItems": 2000 }, "preview": { "type": [ "boolean", "null" ] }, "quoteId": { "type": [ "string", "null" ] } }, "required": [ "locationIds" ] }, "DestaqueRemoveResponse": { "type": "object", "additionalProperties": true, "properties": { "status": { "type": "string", "enum": [ "preview", "applied" ] }, "quoteId": { "type": [ "string", "null" ] }, "quote": { "type": "object", "additionalProperties": true, "properties": { "quoteId": { "type": [ "string", "null" ] }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "removeCount": { "type": [ "integer", "null" ] }, "locationCount": { "type": [ "integer", "null" ] }, "monthlyAmount": { "$ref": "#/components/schemas/Money" }, "perStationAmount": { "$ref": "#/components/schemas/Money" }, "currentLocationCount": { "type": [ "integer", "null" ] }, "currentMonthlyAmount": { "$ref": "#/components/schemas/Money" }, "credit": { "$ref": "#/components/schemas/Money" }, "prorationDate": { "type": [ "string", "null" ], "format": "date-time" }, "renewalDate": { "type": [ "string", "null" ], "format": "date-time" } } }, "confirmationMessage": { "type": [ "string", "null" ] }, "credit": { "$ref": "#/components/schemas/Money" }, "plan": { "type": "object", "additionalProperties": true, "properties": { "locationCount": { "type": [ "integer", "null" ] }, "monthlyAmount": { "$ref": "#/components/schemas/Money" }, "perStationAmount": { "$ref": "#/components/schemas/Money" } } }, "stations": { "type": "array", "items": { "$ref": "#/components/schemas/DestaqueStation" } }, "removed": { "type": "array", "items": { "$ref": "#/components/schemas/DestaqueStation" } }, "links": { "$ref": "#/components/schemas/DestaqueLinks" }, "nextStep": { "type": [ "string", "null" ] } } }, "DestaqueBillingLinkInput": { "type": "object", "additionalProperties": true, "properties": { "kind": { "type": "string", "enum": [ "portal", "boleto" ] } }, "required": [ "kind" ] }, "DestaqueBillingLinkResponse": { "type": "object", "additionalProperties": true, "properties": { "kind": { "type": "string", "enum": [ "portal", "boleto" ] }, "url": { "type": [ "string", "null" ], "format": "uri" }, "payments": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "for": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ], "format": "uri" }, "boleto": { "type": [ "boolean", "null" ] }, "dueDate": { "type": [ "string", "null" ], "format": "date-time" }, "amount": { "$ref": "#/components/schemas/Money" }, "stationId": { "type": [ "integer", "null" ] } } } }, "links": { "$ref": "#/components/schemas/DestaqueLinks" }, "nextStep": { "type": [ "string", "null" ] } } }, "BrlAmount": { "type": "object", "additionalProperties": true, "properties": { "cents": { "type": [ "integer", "null" ] }, "formatted": { "type": [ "string", "null" ] } } }, "ChargingSyncPreferences": { "type": "object", "additionalProperties": true, "properties": { "availability": { "type": [ "boolean", "null" ] }, "prices": { "type": [ "boolean", "null" ] }, "catalogue": { "type": [ "boolean", "null" ] }, "coordinates": { "type": [ "boolean", "null" ] } } }, "ChargingConnection": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": [ "string", "null" ], "format": "uuid" }, "label": { "type": [ "string", "null" ] }, "protocol": { "type": [ "string", "null" ] }, "ocpiVersion": { "type": [ "string", "null" ] }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "enabled": { "type": [ "boolean", "null" ] }, "state": { "type": [ "string", "null" ] }, "online": { "type": [ "boolean", "null" ] }, "status": { "type": "string", "enum": [ "current", "waiting", "stale", "attention", "paused" ] }, "statusLabel": { "type": [ "string", "null" ] }, "problem": { "type": "object", "additionalProperties": true, "properties": { "reason": { "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] } } }, "lastSeenAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastUpdates": { "type": "object" }, "rejectedRecordsLastDay": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "platformStations": { "type": [ "integer", "null" ] }, "tariffs": { "type": [ "integer", "null" ] }, "stations": { "type": "object", "additionalProperties": true, "properties": { "all": { "type": [ "integer", "null" ] }, "enabled": { "type": [ "integer", "null" ] }, "paused": { "type": [ "integer", "null" ] }, "review": { "type": [ "integer", "null" ] }, "withdrawn": { "type": [ "integer", "null" ] }, "notImported": { "type": [ "integer", "null" ] } } }, "dataGaps": { "type": [ "object", "null" ] }, "syncPreferences": { "$ref": "#/components/schemas/ChargingSyncPreferences" }, "autoImport": { "type": [ "boolean", "null" ] }, "stationId": { "type": [ "integer", "null" ] }, "links": { "type": "object" } } }, "ChargingConnectionsResponse": { "type": "object", "additionalProperties": true, "properties": { "connections": { "type": "array", "items": { "$ref": "#/components/schemas/ChargingConnection" } }, "terms": { "type": "object", "additionalProperties": true, "properties": { "accepted": { "type": [ "boolean", "null" ] }, "version": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ], "format": "uri" } } }, "links": { "type": "object", "additionalProperties": true, "properties": { "connect": { "type": [ "string", "null" ], "format": "uri" }, "integrations": { "type": [ "string", "null" ], "format": "uri" }, "publication": { "type": [ "string", "null" ], "format": "uri" }, "terms": { "type": [ "string", "null" ], "format": "uri" } } }, "nextStep": { "type": [ "string", "null" ] } } }, "ChargingPlatformStation": { "type": "object", "additionalProperties": true, "properties": { "key": { "type": [ "string", "null" ] }, "revision": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "points": { "type": [ "integer", "null" ] }, "connectors": { "type": [ "string", "null" ] }, "price": { "type": "object", "additionalProperties": true, "properties": { "perKwh": { "$ref": "#/components/schemas/BrlAmount" }, "activation": { "$ref": "#/components/schemas/BrlAmount" } } }, "importState": { "type": "string", "enum": [ "ready", "needs_choice", "needs_name", "needs_position", "blocked", "imported" ] }, "blockedReason": { "type": [ "string", "null" ] }, "matches": { "type": "array", "items": { "type": "object" } }, "mergeCandidates": { "type": "array", "items": { "type": "object" } }, "suggestedLinkStationId": { "type": [ "integer", "null" ] }, "station": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ], "format": "uri" }, "status": { "type": [ "string", "null" ] }, "statusLabel": { "type": [ "string", "null" ] }, "updates": { "type": [ "string", "null" ] } } } } }, "ChargingConnectionResponse": { "type": "object", "additionalProperties": true, "properties": { "connection": { "$ref": "#/components/schemas/ChargingConnection" }, "stations": { "type": "array", "items": { "$ref": "#/components/schemas/ChargingPlatformStation" } }, "page": { "type": "object", "additionalProperties": true, "properties": { "q": { "type": [ "string", "null" ] }, "cursor": { "type": [ "string", "null" ] }, "nextCursor": { "type": [ "string", "null" ] }, "total": { "type": [ "integer", "null" ] }, "syncing": { "type": [ "boolean", "null" ] } } }, "nextStep": { "type": [ "string", "null" ] } } }, "ChargingConnectionUpdateInput": { "type": "object", "additionalProperties": true, "properties": { "syncPreferences": { "$ref": "#/components/schemas/ChargingSyncPreferences" }, "autoImport": { "type": [ "boolean", "null" ] } } }, "ChargingConnectionMutationResponse": { "type": "object", "additionalProperties": true, "properties": { "message": { "type": [ "string", "null" ] }, "detail": { "type": [ "string", "null" ] }, "connection": { "$ref": "#/components/schemas/ChargingConnection" }, "changes": { "type": "object" } } }, "ChargingHistoryResponse": { "type": "object", "additionalProperties": true, "properties": { "connection": { "type": "object" }, "entries": { "type": "array", "items": { "type": "object" } }, "nextCursor": { "type": [ "string", "null" ] }, "firstRead": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "at": { "type": [ "string", "null" ], "format": "date-time" }, "locations": { "type": [ "integer", "null" ] }, "tariffs": { "type": [ "integer", "null" ] } }, "description": "The platform’s first full read (when it arrived, how many locations and tariffs it brought), summarized instead of listed in entries." }, "links": { "type": "object" } } }, "ChargingImportInput": { "type": "object", "additionalProperties": true, "properties": { "stations": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "key": { "type": [ "string", "null" ] }, "revision": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "linkStationId": { "type": [ "integer", "null" ] }, "mergeStationId": { "type": [ "integer", "null" ] }, "distinct": { "type": [ "boolean", "null" ] } }, "required": [ "key" ] } }, "preview": { "type": [ "boolean", "null" ] } }, "required": [ "stations" ] }, "ChargingImportResponse": { "type": "object", "additionalProperties": true, "properties": { "preview": { "type": [ "boolean", "null" ] }, "ready": { "type": "array", "items": { "type": "object" } }, "imported": { "type": [ "integer", "null" ] }, "results": { "type": "array", "items": { "type": "object" } }, "skipped": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "key": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] } } } }, "message": { "type": [ "string", "null" ] }, "nextStep": { "type": [ "string", "null" ] }, "links": { "type": "object" } } }, "ChargingCheckoutInput": { "type": "object", "additionalProperties": true, "properties": { "stationIds": { "type": "array", "items": { "type": [ "integer", "null" ] } }, "preview": { "type": [ "boolean", "null" ] } }, "required": [ "stationIds" ] }, "ChargingCheckoutResponse": { "type": "object", "additionalProperties": true, "properties": { "preview": { "type": [ "boolean", "null" ] }, "mode": { "type": "string", "enum": [ "checkout", "add_to_plan" ] }, "checkout": { "type": "object", "additionalProperties": true, "properties": { "url": { "type": [ "string", "null" ], "format": "uri" }, "sessionId": { "type": [ "string", "null" ] } } }, "stations": { "type": "array", "items": { "type": "object" } }, "price": { "type": "object", "additionalProperties": true, "properties": { "stations": { "type": [ "integer", "null" ] }, "monthly": { "$ref": "#/components/schemas/BrlAmount" }, "perStation": { "$ref": "#/components/schemas/BrlAmount" }, "interval": { "type": [ "string", "null" ] }, "savingsPercent": { "type": [ "integer", "null" ] } } }, "links": { "type": "object" }, "message": { "type": [ "string", "null" ] }, "nextStep": { "type": [ "string", "null" ] } } }, "ChargingStationResponse": { "type": "object", "additionalProperties": true, "properties": { "message": { "type": [ "string", "null" ] }, "station": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ], "format": "uri" }, "updates": { "type": [ "string", "null" ] }, "updatesLabel": { "type": [ "string", "null" ] }, "points": { "type": "array", "items": { "type": "object" } }, "connections": { "type": "array", "items": { "type": "object" } }, "overrides": { "type": "object" }, "protectedFields": { "type": "array", "items": { "type": [ "string", "null" ] } }, "links": { "type": "object" } } } } }, "ChargingStationUpdateInput": { "type": "object", "additionalProperties": true, "properties": { "updates": { "type": "string", "enum": [ "paused", "active" ] }, "overrides": { "type": "object" }, "releaseField": { "type": "string", "enum": [ "name", "address", "hours", "connectors", "coordinates", "prices", "operator", "siteDetails" ] } } } } } }