openapi: 3.0.1
info:
  title: Chargetrip GraphQL API (HTTP transport)
  description: >-
    HTTP transport view of the Chargetrip EV routing GraphQL API. Chargetrip is a
    native GraphQL API; all queries and mutations are issued as HTTP POST requests
    to a single `/graphql` endpoint with a JSON body containing `query`,
    `operationName`, and `variables`. Authentication uses the `x-client-id` and
    `x-app-id` headers. Real-time route updates are delivered over a separate
    WebSocket subscription endpoint (wss://api.chargetrip.io/subscription, the
    graphql-transport-ws protocol) and are described in
    asyncapi/chargetrip-asyncapi.yml, not here. Operation-level detail is modeled
    in graphql/chargetrip-graphql.md and graphql/chargetrip-schema.graphql.
  termsOfService: https://www.chargetrip.com/legal/terms-conditions
  contact:
    name: Chargetrip
    url: https://www.chargetrip.com
  version: '1.0'
servers:
  - url: https://api.chargetrip.io
    description: Chargetrip GraphQL endpoint base.
paths:
  /graphql:
    post:
      operationId: postGraphql
      tags:
        - GraphQL
      summary: Execute a GraphQL query or mutation.
      description: >-
        Single GraphQL entry point. Send a JSON body with a `query` string and
        optional `operationName` and `variables`. Documented operations include the
        mutations `newRoute` and `createIsoline`, and the queries `route`, `isoline`,
        `station`, `stationList`, `stationAround`, `vehicleList`, `vehicle`, and
        `operatorList`. Subscriptions (e.g. `routeUpdatedById`) are not available
        over HTTP; use the WebSocket subscription endpoint instead.
      parameters:
        - name: x-client-id
          in: header
          required: true
          description: Chargetrip client identifier for your account.
          schema:
            type: string
        - name: x-app-id
          in: header
          required: true
          description: Chargetrip application identifier.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GraphQLRequest'
            examples:
              newRoute:
                summary: Create a route (newRoute mutation)
                value:
                  operationName: newRoute
                  query: >-
                    mutation newRoute($input: RequestInput!) { newRoute(input:
                    $input) }
                  variables:
                    input:
                      ev:
                        id: 5d161be5c9eef46132d9d20a
                        battery:
                          stateOfCharge:
                            value: 70
                            type: kilowatt_hour
                      routeRequest:
                        origin:
                          type: Feature
                          geometry:
                            type: Point
                            coordinates: [4.8951, 52.3702]
                        destination:
                          type: Feature
                          geometry:
                            type: Point
                            coordinates: [2.3522, 48.8566]
              stationAround:
                summary: Stations around a location (stationAround query)
                value:
                  operationName: stationAround
                  query: >-
                    query stationAround($query: StationAroundQuery!) {
                    stationAround(query: $query, size: 20, page: 0) { id name
                    status } }
                  variables:
                    query:
                      location:
                        type: Point
                        coordinates: [4.8951, 52.3702]
                      distance: 5000
      responses:
        '200':
          description: >-
            GraphQL response. Note that GraphQL returns HTTP 200 even when the
            `errors` array is populated; inspect both `data` and `errors`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphQLResponse'
        '401':
          description: Missing or invalid x-client-id / x-app-id credentials.
        '429':
          description: Rate or quota limit exceeded for the account / API service.
components:
  securitySchemes:
    clientId:
      type: apiKey
      in: header
      name: x-client-id
      description: Chargetrip client identifier sent on every request.
    appId:
      type: apiKey
      in: header
      name: x-app-id
      description: Chargetrip application identifier sent on every request.
  schemas:
    GraphQLRequest:
      type: object
      required:
        - query
      properties:
        query:
          type: string
          description: The GraphQL query or mutation document.
        operationName:
          type: string
          nullable: true
          description: Name of the operation to run when the document defines several.
        variables:
          type: object
          nullable: true
          additionalProperties: true
          description: Variable values referenced by the query document.
    GraphQLResponse:
      type: object
      properties:
        data:
          type: object
          nullable: true
          additionalProperties: true
          description: The data returned by the executed operation, keyed by field name.
        errors:
          type: array
          nullable: true
          description: GraphQL errors, if any. Present even on HTTP 200.
          items:
            $ref: '#/components/schemas/GraphQLError'
    GraphQLError:
      type: object
      properties:
        message:
          type: string
        path:
          type: array
          items:
            type: string
        extensions:
          type: object
          additionalProperties: true
security:
  - clientId: []
    appId: []