This documentation introduces the GraphQL API, which allows you to make an API request for only what you need from your Saagie platform.

1. What is GraphQL?

GraphQL is a query language for APIs that allows clients to request exactly the data they need, making it possible to get all required data in a limited number of requests.

The GraphQL data (fields) can be described in the form of types, allowing clients to use client-side GraphQL libraries to consume the API and avoid manual parsing.

Since there’s no fixed endpoints and data model, new abilities can be added to the API without creating breaking changes. This allows us to have a versionless API as described in the GraphQL documentation.

2. GraphiQL

GraphiQL allows you to run queries directly against the server endpoint with syntax highlighting and autocomplete. It also allows you to explore the schema and types.

3. GraphiQL gateway

Explore the GraphQL API using the interactive gateway explorer on your Saagie platform on

4. Authentication

Most API requests require authentication.

If authentication information is not valid or is missing, Saagie returns an error message with a status code of 401:

There are several ways you can authenticate with the Saagie API:

4.1. Tokens

You can use an token to authenticate with the API by passing it in either the access_token parameter or the Authorization header.

Signing in to the main Saagie application sets a cookie. The API uses this cookie for authentication if it’s present. Using the API to generate a new session cookie isn’t supported.

The primary user of this authentication method is the web frontend of Saagie itself. The web frontend can use the API as the authenticated user to get a list of projects without explicitly passing an access token.