Getting started with Deel’s GraphQL APIs

GraphQL is an alternative to REST for interacting with APIs. It allows you to send a single request and specify the exact data you want returned. Deel’s GraphQL APIs follow the GraphQL specification and expose an introspectable schema, so you can explore available types and fields directly.

The GraphQL API powers the Wiki API, which lets you retrieve and render Deel’s internal knowledge base content in your application.

Terminology

This guide introduces common GraphQL terminology, explains how to form requests, and shows how to work with Deel’s GraphQL endpoints. The Wiki API is used as an example later in this document.

Schema

A schema defines the type system. It describes all objects, fields, and relationships in the API. Client requests are validated and executed against the schema.

Field

A field is a unit of data you can retrieve from an object. As the official GraphQL docs say:
"The GraphQL query language is basically about selecting fields on objects."

As stated in the official specification, all GraphQL operations must specify their selections down to fields which return scalar values to ensure an unambiguously shaped response.

This means that if you try to return a field that is not a scalar, schema validation will throw an error. You must add nested subfields until all fields return scalars.

Argument

An argument is a set of key-value pairs attached to a specific field. Some fields require an argument. Mutations require an input object as an argument.

Connection

Connections let you fetch related objects in one query. In REST, the same operation might require multiple requests.

A graph can be pictured as nodes (dots) linked by edges (lines). A connection defines those connections.

Edge

Edges define relationships between nodes. A connection query traverses edges to access nodes. Each edges field includes a node and a cursor.

Node

A node is any object. You can query nodes directly or reach them through connections. If a node does not return a scalar, you must include subfields until all fields are scalars.

Working with the Wiki API

The Wiki API is a service for working with knowledge articles. It provides a single endpoint for queries and mutations, and the schema is fully introspectable. This section explains how to access the API, explore its schema, and run queries using standard GraphQL clients.

Before you begin

Make sure you have valid token to authenticate your requests. This token is provided by Deel and you need to include it in the Authorization header.

Endpoints

All queries and mutations use a single HTTP endpoint. The URL depends on whether you are working in the sandbox environment or in production.

Use the POST method for all requests.

Schema

GraphQL is introspective, which means you can query the schema for details about itself.

To list all types and their fields, query __schema:

query {
  __schema {
    types {
      name
      kind
      description
      fields {
        name
      }
    }
  }
}

To inspect a specific type, query __type:

query {
  __type(name: "Repository") {
    name
    kind
    description
    fields {
      name
    }
  }
}

📘

Using a client IDE

You can use many open-source GraphQL clients with Deel’s APIs. Examples include Postman, GraphiQL, Insomnia, and Altair. For more tools, see the GraphQL tools directory.

General setup steps:

1. Set the endpoint to https://wiki.deel.network/graphql. Replace URL with the correct environment.
2. Add an Authorization header: Authorization: Bearer {API_TOKEN}.
3. Set the request method to POST, or use the client’s GraphQL mode if available.
4. Set the Content-Type to application/json.
5. Enter your query or mutation in the editor. If needed, add variables in the Variables panel. Example:

query {
  pages {
    list {
      items {
        id
        locale
        path
        title
      }
      totalCount
    }
  }
}

6. (Optional) To enable autocomplete or documentation in the client, fetch the schema using an introspection query. Many clients handle this automatically. Minimal introspection query:

query IntrospectionQuery {  
  __schema {  
    types {  
      name  
    }  
  }  
}

7. Run the query and review the JSON response. The example above returns a list of Wiki articles.

Use the client UI to explore docs, run queries, and save requests as needed.

Rate limiting

The API enforces a limit of 12 queries per second (QPS).