> For the complete documentation index, see [llms.txt](https://docs.kublau.com/kublau-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kublau.com/kublau-docs/api/examples.md).

# Running examples

The examples documented here can be run using:

* [Our Playground](/kublau-docs/api/playground.md).
* The command line.

#### Command line <a href="#command-line" id="command-line"></a>

You can run GraphQL queries in a `curl` request on the command line on your local machine. A GraphQL request can be made as a `POST` request to `https://api.kublau.com/graphql` with the query as the payload. You can authorize your request by using a [test API key](/kublau-docs/api/authentication.md#api-keys) to use as a bearer token.

Example:

```
GRAPHQL_TOKEN=<ACCESS_TOKEN>
curl "https://api.kublau.com/graphql" --header "Authorization: Bearer $GRAPHQL_TOKEN" --header "Content-Type: application/json" --request POST --data "{\"query\": \"query {workspace {name}}\"}"
```

### Queries and mutations <a href="#queries-and-mutations" id="queries-and-mutations"></a>

The Kublau GraphQL API can be used to perform:

* Queries for data retrieval.
* [Mutations](https://docs.gitlab.com/ee/api/graphql/getting_started.html#mutations) for creating, updating, and deleting data.

**Note:** In the API, `id` refers to a global ID, which is an object identifier in the format of `gid://kublau/ObjectType/xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx`

[Kublau’s GraphQL Schema](/kublau-docs/api/api-reference.md) outlines which objects and fields are available for clients to query and their corresponding data types.

Example: Return a Workspace resource corresponding to the API Key used in request.

```
query {
  workspace {
    id
    name
  }
}
```

#### Mutations

Mutations make changes to data. We can update, delete, or create new records. Mutations generally use InputTypes and variables, neither of which appear here.

Mutations have:

* Inputs. For example, arguments, such as which carrier you’d like to use when creating a shipment.
* Return statements. That is, what you’d like to get back when it’s successful.
* User errors. Always ask for what went wrong, just in case.

**Creation mutations**

Example: Let’s create a shipment **Tracker.**

```
mutation createTracker {
  trackerCreate(input: {
    trackingCode: "K1000000000",
    carrier: ESTAFETA
  }) {
    tracker {
      id
      trackingCode
      status
      estimatedDeliveryAt
      deliveredAt
      carrier
      checkpoints {
        id
        message
        status
        scannedAt
      }
    }
    trackerUserErrors {
      code
      message
      field
    }
  }
}
```

More about mutations: [GraphQL Docs](https://graphql.org/learn/queries/#mutations).

#### Introspective queries

Clients can query the GraphQL endpoint for information about its own schema. by making an [introspective query](https://graphql.org/learn/introspection/).

It is through an introspection query that the [GraphiQL Query Explorer](/kublau-docs/api/playground.md) gets all of its knowledge about our GraphQL schema to do autocompletion and provide its interactive `Docs` tab.

Example: Get all the type names in the schema.

```
{
  __schema {
    types {
      name
    }
  }
}
```

Example: Get all the fields associated with Tracker. `kind` tells us the enum value for the type, like `OBJECT`, `SCALAR` or `INTERFACE`.

```
query TrackerTypes {
  __type(name: "Tracker") {
    kind
    name
    fields {
      name
      description
      type {
        name
      }
    }
  }
}
```

More about introspection: [GraphQL docs](https://graphql.org/learn/introspection/)