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

# Forming Calls

## Authentication

AdSecure authenticates your API requests using your account’s API key. If you do not include your key when making an API request, or use one that is incorrect or outdated, AdSecure returns an error.

Every account is provided with an API key. Some additional ones can be created by contacting your account manager. In our code examples, we include randomly generated API keys. Replace these with your own to see code examples being executed successfully.

You can use the GraphQL API by adding this API key in a HTTP `POST` request's header as following:

```bash
x-api-key: key
```

## The GraphQL endpoint

The GraphQL API has a single endpoint:

```bash
https://api.adsecure.com/graphql
```

The endpoint remains constant no matter what operation you perform.

## Communicating with GraphQL

In REST, HTTP verbs determine the operation performed. In GraphQL, you'll provide a JSON-encoded body whether you're performing a query or a mutation, so the HTTP verb is `POST`.

To query GraphQL using cURL, make a `POST` request with a JSON payload. The payload must contain a string called `query`:

```bash
curl -H 'x-api-key: nhwQ4taIgNciu3xrabY8BMFXAZGyYGtc8r' -d '
{
  "query":"query { viewer { user { name }}}"
}' -X POST https://api.adsecure.com/graphql
```

And could be represented as following in a GraphQL way:

```bash
query {
  viewer {
    user {
      name
    }
  }
}
```

The resulting response is going to take the following shape, returning in it body the data you've asked for:

```json
{
  "data": {
    "viewer": {
      "user": {
        "name": "Your user's name!"
      }
    }
  }
}
```

> Using cURL is not the only way to communicate with GraphQL, many different [programming languages](https://graphql.org/code/#server-libraries) and [clients](https://graphql.org/code/#graphql-clients) support GraphQL.

## About query and mutation operations

The two types of allowed operations in the GraphQL API are queries and mutations. Comparing GraphQL to REST, queries operate like `GET` requests, while mutations operate like `POST`/`PATCH`/`DELETE`. The mutation name determines which modification is executed.

For information about rate limiting, see - ["GraphQL resource limitations"](#!).

Queries and mutations share similar forms, with some important differences.

### About queries

GraphQL queries return only the data you specify. To form a query, you must specify [fields within fields](/docs/graphql/concepts.md#field) (also known as nested subfields) until you return only [scalars](/api/graphql/scalars.md).

Queries are structured like this:

```bash
query {
  fields
}
```

### About mutations

To form a mutation, you must specify three arguments:

1. *Mutation name*. The type of modification you want to perform.
2. *Input object*. The data you want to send to the server, composed of *input fields*. Pass it as an argument to the mutation name.
3. *Payload object*. The data you want to return from the server, composed of *return fields*. Pass it as the body of the mutation name.

Mutations are structured like this:

```bash
mutation {
  mutationName(input: {MutationNameInput!}) {
    MutationNamePayload
}
```

The input object in this example is `MutationNameInput`, and the payload object is `MutationNamePayload`.

## Discovering the GraphQL API

GraphQL is [introspective](https://graphql.org/learn/introspection/). This means you can query a GraphQL schema for details about itself.

* Query `__schema` to list all types defined in the schema and get details about each:

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

* Query `__type` to get details about any type:

```bash
query {
  __type(name: "Analysis") {
    name
    kind
    description
    fields {
      name
    }
  }
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.adsecure.com/docs/graphql/forming-calls.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.