GraphQL API

Query Duku data and trigger runs programmatically.

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.

Request format

All requests use an HTTP POST with a JSON body:

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

Example request:

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

Example IDs such as smt_... and key_... are placeholders.

Queries

List products

query {
  subjects {
    id
    name
  }
}

List targets

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.

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

Get run details

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

Mutations

Create or update a target

Use upsertSimulationTarget to create a target the first time, then update it on later runs.

buildKey is the stable identity key for the target. Duku deduplicates by subjectId + buildKey. If you call the mutation again with the same pair, Duku updates the existing target instead of creating a duplicate.

For per-PR targets, use a stable key such as github:repo=owner/repo:pr=123.

Required input fields:

• subjectId: your Product ID

• buildKey: the stable identity key

• name: the target name shown in Viewport

Optional input fields:

• buildUrl

• version

• environment

• buildNumber

• description

• metadata

mutation Upsert($input: UpsertSimulationTargetInput!) {
  upsertSimulationTarget(input: $input) {
    id
    name
    version
    buildUrl
  }
}

Example variables:

{
  "input": {
    "subjectId": "smt_product_id",
    "buildKey": "github:repo=owner/repo:pr=123",
    "name": "PR #123",
    "buildUrl": "https://preview.example.com"
  }
}

Start an exploration

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

Variables:

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

PR comment fields:

• githubRepository: repository in owner/repo format

• githubPrNumber: pull request number as an integer

• serverManagedComment: boolean

• triggerSource: optional. The only valid value is GITHUB_ACTION

• githubInstallationId: optional integer

When you send serverManagedComment: true together with githubRepository and githubPrNumber, Duku posts the PR comment itself and updates the same comment when the run finishes.

PR comments are posted by the Duku GitHub App, not GitHub Actions

The App is a one-time install on the repository that lets Duku's platform post comments through the GitHub API. It is not GitHub Actions and uses no CI minutes.

There is one sticky comment per PR, identified by repository and PR number, not per target. Duku updates that comment in place when the run finishes.

Trigger from any CI

Use this flow from CircleCI, GitLab CI, Jenkins, or any other pipeline. No GitHub Action is required.

1. Exchange the API key for an access token.

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

1. Create or update the target, then capture the target ID.

TARGET_ID=$(curl -s -X POST https://platform.duku.ai/graphql \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation Upsert($input: UpsertSimulationTargetInput!) { upsertSimulationTarget(input: $input) { id } }",
    "variables": {
      "input": {
        "subjectId": "smt_product_id",
        "buildKey": "github:repo=owner/repo:pr=123",
        "name": "PR #123",
        "buildUrl": "https://preview.example.com"
      }
    }
  }' | jq -r '.data.upsertSimulationTarget.id')

1. Start the exploration with the target ID, URL, and PR metadata.

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\": \"$TARGET_ID\",
        \"url\": \"https://preview.example.com\",
        \"githubRepository\": \"owner/repo\",
        \"githubPrNumber\": 123,
        \"serverManagedComment\": true
      }
    }
  }"

End-to-end cURL example

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