> ## Documentation Index
> Fetch the complete documentation index at: https://developers.drpn.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart: test your API key

> Make your first request with the dgql_ key you were given, and read what comes back.

You have a `dgql_` key and want to know whether it works. This takes about five minutes: one request proves the key, and the table at the end names every way it can go wrong and the fix.

## Before you start

* **An API key** that starts with `dgql_`. A Darpan administrator creates it for one tenant and shows it once. If you lost it, ask for a new one; nobody can show it again. See [Authentication](https://developers.drpn.ai/graphql/authentication.md).
* **Your API host.** On hosted Darpan it is `https://api.drpn.ai`. A self-hosted instance has its own backend URL. The app's address (`app.drpn.ai`) is not the API host.

## Run your first request

**1. Keep the key in an environment variable**

The key reads a tenant's audit findings and run results. Keep it out of your shell history and source code:

```bash theme={null}
read -s DARPAN_GQL_KEY && export DARPAN_GQL_KEY
export DARPAN_API=https://api.drpn.ai
```

Paste the key at the silent prompt and press Enter.

**2. Send a query**

This query asks for the tenant's latest reconciliation run. It works on every tenant, including one with no runs yet.

```bash curl theme={null}
curl -s "$DARPAN_API/rest/s1/graphql/public" \
  -H "Authorization: Bearer $DARPAN_GQL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ reconciliationResults(first: 1) { edges { node { reconciliationRunResultId createdDate } } pageInfo { hasNextPage } } }"}'
```

```javascript JavaScript theme={null}
const res = await fetch(`${process.env.DARPAN_API}/rest/s1/graphql/public`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DARPAN_GQL_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: `{ reconciliationResults(first: 1) {
      edges { node { reconciliationRunResultId createdDate } }
      pageInfo { hasNextPage } } }`,
  }),
});
console.log(JSON.stringify(await res.json(), null, 2));
```

```python Python theme={null}
import json, os, urllib.request

body = {"query": """{ reconciliationResults(first: 1) {
    edges { node { reconciliationRunResultId createdDate } }
    pageInfo { hasNextPage } } }"""}
req = urllib.request.Request(
    os.environ["DARPAN_API"] + "/rest/s1/graphql/public",
    data=json.dumps(body).encode(),
    headers={"Authorization": "Bearer " + os.environ["DARPAN_GQL_KEY"],
             "Content-Type": "application/json"},
)
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
```

Prefer a browser? The [API explorer](https://developers.drpn.ai/graphql/explorer.md) sends the same request from this site: paste your key, pick **Check your key**, and press **Send**.

**3. Read the answer**

A key that works returns `data`, and `extensions.cost` says what the query cost:

```json theme={null}
{
  "data": {
    "reconciliationResults": {
      "edges": [ { "node": { "reconciliationRunResultId": "100457", "createdDate": "2026-10-26T06:30:12Z" } } ],
      "pageInfo": { "hasNextPage": true }
    }
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 3,
      "actualQueryCost": 3,
      "throttleStatus": { "maximumAvailable": 1000, "currentlyAvailable": 997, "restoreRate": 50 }
    }
  }
}
```

`"edges": []` is a working key too: the tenant has no runs yet.

## When it does not work

Darpan answers a refused key or query with HTTP 200 and an `errors` list, so read `errors`, not only the status code.

| What you see | What it means | Fix |
| - | - | - |
| `missing API key` (`UNAUTHENTICATED`) | No key reached the API, or the header has no `Bearer ` before the key | Send `Authorization: Bearer dgql_…`, with the space. Check that `$DARPAN_GQL_KEY` is set in this shell |
| `invalid API key` (`UNAUTHENTICATED`) | The key is unknown, disabled or expired. The API does not say which | Check for a missing character when you copied it. Otherwise ask your administrator for a new key |
| An HTML page instead of JSON | The request went to the app, not the API | Use the API host (`https://api.drpn.ai` on hosted Darpan), not `app.drpn.ai` |
| HTTP 400, `Field cannot be empty` | The body was not sent as JSON | Add `-H "Content-Type: application/json"` |
| A message ending `Audit month-close was not found` or `Finding F-… was not found` | The key works. The tenant has no audit with that code, or no finding with that id. Another tenant's finding reads as not found too | Use an audit code and a finding id from your own tenant |
| `THROTTLED` | The key's points bucket is empty | Wait a few seconds; it refills at 50 points a second. See [Cost and throttling](https://developers.drpn.ai/graphql/cost-and-throttling.md) |
| The explorer shows a network error, but curl works | Your browser could not reach the host you entered in the explorer | Check the host in the explorer. A self-hosted instance must list `https://developers.drpn.ai` in [`webapp_public_api_origins`](https://developers.drpn.ai/self-host/production) before the explorer can call it; curl does not need that |

Every other code is listed in [Errors](https://developers.drpn.ai/graphql/errors.md).

## Next steps

> **[Find the query for your task](https://developers.drpn.ai/graphql/tasks.md)**
>
> Recipes for the questions integrations ask most: this morning's audit, open findings, one finding, recent runs.

> **[Try every query in the explorer](https://developers.drpn.ai/graphql/explorer.md)**
>
> One example per query, ready to send with your key.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.