openapi: 3.0.1
info:
  title: Chargetrip API (HTTP transport) GraphQL API
  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.
security:
- clientId: []
  appId: []
tags:
- name: GraphQL
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:
  schemas:
    GraphQLError:
      type: object
      properties:
        message:
          type: string
        path:
          type: array
          items:
            type: string
        extensions:
          type: object
          additionalProperties: true
    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'
  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.