Base URL

All API requests should use a base URL of https://api.octopus.energy/v1/graphql/ or https://auth.octopus.energy/graphql/ Note, all API requests must be made over HTTPS. If you would like to try out some queries and mutations directly in your browser you can use GraphiQL which is available at: https://api.octopus.energy/v1/graphql/ and https://auth.octopus.energy/graphql/. Unlike the REST API, the GraphQL API only returns the 200 response code. If there is an error, this will be returned in the errors field of the response.

Authentication

Authentication is required for some queries and mutations. This is performed via setting the Authorization header for requests to be the appropriate token for a user. You can get a token for your user by using the ObtainKrakenToken Mutation. This Mutation has several different ways to authenticate, including email/password, an API key, or a pre-signed key.

When you have your token, you can set the Authorization header in the client you are using to make the request. The header should be set to the value of your token. For example, if your token is 12345, you would set the Authorization header to 12345.

{ "Authorization": "12345" }

The token is only valid for 60 minutes from time of issuance. However, the refreshToken is valid for 7 days (you can use the refreshExpiresIn value to know when the refreshToken will expire). The recommended usage is: cache both token and refreshToken based on their expiry time, and use the cached token to make API requests; regenerate the token when it expires using the ObtainKrakenToken Mutation, authenticating with the refreshToken; re-request both tokens using the ObtainKrakenToken Mutation with the original authentication method when the refreshToken expires.

Deprecations

Occasionally, fields and arguments become outdated, and we may mark them as deprecated. In these cases, the field will be visibly deprecated on the schema, and a deprecation reason will be provided on the item's description on the schema. The deprecation reason will likely point to the new type that should be used instead.

Errors

Queries and mutations can return errors. These are returned in the errors field of the response. The errors that a Query or Mutation can return are documented in the description for the relevant field in the reference documentation.

Pagination

Some fields in the API return a list of objects. These are paginated and the pagination information is returned in the pageInfo field of the response. The pageInfo object contains the hasNextPage and hasPreviousPage fields which indicate if there are more pages of results. The startCursor and endCursor fields contain the cursors for the first and last objects in the current page of results. The cursors can be used to paginate through the results.

For example, this is a query for getting account transactions with pagination:

query getTransactions($accountNumber: String!) { account(accountNumber: $accountNumber) { transactions(first: 10, after: "<some-cursor>") { pageInfo { hasNextPage hasPreviousPage startCursor endCursor } edges { cursor node { id } } } } }

Note that when using pagination the hasNextPage and hasPreviousPage fields have slightly unintuitive behaviour. Where if you are paginating forward using the after argument, the hasPreviousPage field will always be false which is behaviour defined in the GraphQL Relay spec. If you would like to read more about this behaviour, please see the PageInfo section of the spec. For fields that have pagination we enforce that pagination is used and that the first argument is set to a value less than 100. If you do not set the first argument, or set it to a value greater than 100, you will receive an error.

Rate limiting

We rate limit requests to the API. Rate limits are applied on specific Queries and Mutations. When rate limited the viewer will receive the KT-CT-1199 error code. If you are rate limited, you should wait for a short period of time before retrying the request.