# GraphQL API

The Duku GraphQL API gives you programmatic access to products, targets, and runs.

### Endpoint

```
POST https://platform.duku.ai/graphql
```

### Authentication

Every request requires a Bearer token in the `Authorization` header. Use the OAuth2 client credentials flow described in [API Keys](/integrations/api-keys.md).

### Request format

All requests use an HTTP `POST` with a JSON body:

```json
{
  "query": "query { subjects { id name } }",
  "variables": {}
}
```

Example request:

```bash
curl -X POST https://platform.duku.ai/graphql \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ subjects { id name } }"}'
```

{% hint style="info" %}
Example IDs such as `smt_...` and `key_...` are placeholders.
{% endhint %}

### Queries

#### List products

```graphql
query {
  subjects {
    id
    name
  }
}
```

#### List targets

```graphql
query GetTargets($subjectId: ID) {
  targets(subjectId: $subjectId) {
    id
    name
    buildUrl
  }
}
```

#### List runs for a target

Use this query to retrieve recent runs for a target.

```graphql
query GetRuns($targetId: ID) {
  runs(targetId: $targetId) {
    runs {
      id
      name
      status
      exceptionCount
      createdAt
      target {
        id
        name
      }
    }
  }
}
```

#### Get run details

```graphql
query GetRun($id: ID!) {
  run(id: $id) {
    id
    name
    status
    exceptionCount
    createdAt
    target {
      id
      buildUrl
    }
  }
}
```

### Mutations

#### Start an exploration

```graphql
mutation StartExploration($input: StartExplorationInput!) {
  startExploration(input: $input) {
    id
    status
    batch {
      id
      runs {
        id
        name
      }
    }
  }
}
```

Variables:

```json
{
  "input": {
    "targetId": "smt_..."
  }
}
```

### End-to-end cURL example

```bash
TOKEN=$(curl -s -X POST https://auth.duku.ai/realms/duku/protocol/openid-connect/token \
  -d "grant_type=client_credentials" \
  -d "client_id=pk_your_client_id" \
  -d "client_secret=your_client_secret" | jq -r '.access_token')

curl -X POST https://platform.duku.ai/graphql \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation StartExploration($input: StartExplorationInput!) { startExploration(input: $input) { id status } }",
    "variables": {
      "input": {
        "targetId": "smt_your_target_id"
      }
    }
  }'
```

### Common errors

| Code              | Meaning                         |
| ----------------- | ------------------------------- |
| `UNAUTHENTICATED` | Missing or invalid access token |
| `FORBIDDEN`       | Insufficient permissions        |
| `NOT_FOUND`       | Resource does not exist         |
| `BAD_USER_INPUT`  | Invalid input                   |


---

# 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.duku.ai/integrations/graphql-api.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.