GraphQL API

Drok's GraphQL API provides a flexible query interface that lets you request exactly the fields you need in a single request. No over-fetching. No under-fetching. No multiple round-trips.

Endpoint

POST https://drok.us/api/graphql

Authentication

Include your token in the Authorization header:

curl -X POST https://drok.us/api/graphql \
  -H "Authorization: Bearer $Drok_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ viewer { username email } }"}'

Schema Explorer

An interactive GraphQL explorer is available at:

https://drok.us/api/graphql/explorer

The explorer provides schema documentation, query autocompletion, and real-time execution.

Query Examples

Get Current User

query {
  viewer {
    username
    email
    avatarUrl
    organizations {
      nodes {
        name
        role
      }
    }
  }
}

List Repositories

query {
  organization(login: "my-org") {
    repositories(first: 20, orderBy: { field: UPDATED_AT, direction: DESC }) {
      nodes {
        name
        description
        private
        defaultBranch
        primaryLanguage {
          name
          color
        }
        updatedAt
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}

Get Merge Request with Reviews

query {
  repository(owner: "my-org", name: "my-repo") {
    mergeRequest(number: 42) {
      title
      state
      author {
        username
      }
      sourceBranch
      targetBranch
      reviews {
        nodes {
          author { username }
          state
          submittedAt
          comments {
            nodes {
              body
              path
              line
            }
          }
        }
      }
      pipeline {
        status
        stages {
          nodes {
            name
            status
            duration
          }
        }
      }
    }
  }
}

Search Code

query {
  search(query: "fn refresh_token", type: CODE, first: 10) {
    nodes {
      ... on CodeResult {
        repository { fullName }
        path
        lineNumber
        content
        language
      }
    }
    totalCount
  }
}

Mutations

Create a Merge Request

mutation {
  createMergeRequest(input: {
    repositoryId: "repo_01H8XYZ"
    title: "Add new feature"
    sourceBranch: "feature/new-feature"
    targetBranch: "main"
    description: "Implements the new feature as discussed in #15"
  }) {
    mergeRequest {
      number
      url
    }
  }
}

Add a Comment

mutation {
  addComment(input: {
    subjectId: "mr_01H8XYZ"
    body: "Looks good to me. Approved."
  }) {
    comment {
      id
      createdAt
    }
  }
}

Merge a Merge Request

mutation {
  mergeMergeRequest(input: {
    mergeRequestId: "mr_01H8XYZ"
    strategy: SQUASH
    commitMessage: "Add new feature (#42)"
  }) {
    mergeRequest {
      state
      mergedAt
    }
  }
}

Pagination

GraphQL queries use cursor-based pagination:

query {
  repository(owner: "my-org", name: "my-repo") {
    commits(first: 50, after: "cursor_abc123") {
      nodes {
        sha
        message
        author { username }
        committedAt
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}

Use pageInfo.endCursor as the after parameter in subsequent requests to fetch the next page.

Rate Limiting

GraphQL requests are rate-limited by query complexity. See Rate Limiting for cost calculation details.

Check your rate limit status in the response:

{
  "data": { },
  "extensions": {
    "rateLimit": {
      "limit": 5000,
      "remaining": 4950,
      "cost": 50,
      "resetAt": "2024-03-15T15:00:00Z"
    }
  }
}

Introspection

Query the schema itself:

query {
  __schema {
    types {
      name
      description
      fields {
        name
        type { name }
      }
    }
  }
}

Introspection is enabled for all authenticated users. Use it to explore available types, fields, and mutations programmatically.