# Usage

## API Access

|          |                                       |
| -------- | ------------------------------------- |
| Headers  | `Authorization: Bearer <api_key>`     |
| Endpoint | `https://app.eduflow.com/api/graphql` |

General requests to the API endpoint will return JSON.

The response will be wrapped in `"data"` and match the shape of the original query.

{% tabs %}
{% tab title="curl" %}
[curl(1)](https://curl.haxx.se/) example:

```javascript
EDUFLOW_API_KEY=<api_key> \
  curl \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${EDUFLOW_API_KEY}" \
  -X POST \
  -d '{"query": "{institution {name}}"}' \
  https://app.eduflow.com/api/graphql
```

{% endtab %}

{% tab title="wget" %}
[wget(1)](https://www.gnu.org/software/wget/) example:

```javascript
EDUFLOW_API_KEY=<api_key> \
 wget -qO- \
 --header 'Content-Type: application/json' \
 --header "Authorization: Bearer ${EDUFLOW_API_KEY}" \
 -X POST \
 --post-data '{"query": "{institution {name}}"}' \
 https://app.eduflow.com/api/graphql
```

{% endtab %}

{% tab title="node" %}

```javascript
#!/bin/env node

if (!process.env.EDUFLOW_API_KEY) {
  console.error(`Enter your EDUFLOW_API_KEY:

  env EDUFLOW_API_KEY=<api_key> node index.js`);
  return;
}

const http =
  process.env.EDUFLOW_API_PROTOCOL === "http"
    ? require("http")
    : require("https");

const query = JSON.stringify({
  query: `{
    institution {
      name
    }
  }`,
});

const options = {
  hostname: process.env.EDUFLOW_API_HOSTNAME || "app.eduflow.com",
  path: "/api/graphql",
  port: process.env.EDUFLOW_API_PORT || 443,
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Content-Length": query.length,
    Authorization: "Bearer " + process.env.EDUFLOW_API_KEY,
    "User-Agent": "Node",
  },
};

const req = http.request(options, (res) => {
  let data = "";
  res.on("data", (d) => {
    data += d;
  });
  res.on("end", () => {
    console.log(JSON.parse(data).data);
  });
});

req.on("error", (error) => {
  console.error(error);
});

req.write(query);
req.end();
```

{% endtab %}

{% tab title="python" %}

```python
#!/bin/env python
import json
import os
import sys
import urllib.request

api_key = os.getenv("EDUFLOW_API_KEY")
if api_key is None:
    sys.exit(
        """Enter your EDUFLOW_API_KEY:

    env EDUFLOW_API_KEY=<api_key> python app.py"""
    )

query = """{
  institution {
    name
  }
}"""

raw_data = {
    "query": query,
    "variables": {},
}
data = json.dumps(raw_data).encode("utf-8")

options = {
    "data": data,
    "headers": {
        "Content-Type": "application/json",
        "Content-Length": len(data),
        "Authorization": f"Bearer {api_key}",
        "User-Agent": "Node",
    },
}

hostname = os.getenv("EDUFLOW_API_HOSTNAME", "app.eduflow.com")
protocol = os.getenv("EDUFLOW_API_PROTOCOL", "https")
port = os.getenv("EDUFLOW_API_PORT", 443)
url = f"{protocol}://{hostname}:{port}/api/graphql"

request = urllib.request.Request(url, **options)

try:
    response = urllib.request.urlopen(request)
    print(response.read().decode())
except urllib.error.HTTPError as e:
    print(e.read().decode())
```

{% endtab %}
{% endtabs %}

Response:

```javascript
{"data":{"institution":{"name":"Test institution"}}}
```

## Session-based / GraphiQL

Institution administrators that are logged into Eduflow can access the API endpoint and query through the graphql interface.

When logged in, go directly to <https://app.eduflow.com/api/graphql>

![Hovering over an object will show an introspection tooltip, typing will show autocompletion hints](/files/-MRzvw-WLh7vAfolbVmN)

![GraphiQL has a searchable documentation available on the sidebar](/files/-MRzwZGQa36N6u66knEe)

If you access via browser, the GraphQL endpoint will show [GraphiQL](https://github.com/graphql/graphiql)

To open GraphiQL's sidebar, mouseover an object in the query and click an object inside a tooltip, or clicking "Doc":

![This is found on the top right of GraphiQL if the sidebar is closed.](/files/-MSFJDpddkkKJ2YTqey1)

GraphiQL works with both session-based (logged into app.eduflow\.com) and by passing authorization headers.


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.eduflow.com/getting-started-1/usage.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.