API Introduction

Drok provides two API interfaces: a REST API for standard CRUD operations and a GraphQL API for complex queries with precise field selection. Both APIs are versioned, authenticated, rate-limited, and documented.

Base URL

https://drok.us/api/v1

All API requests must use HTTPS. HTTP requests are rejected, not redirected.

Authentication

Every API request (except public repository reads) requires authentication. Include your personal access token in the Authorization header:

curl https://drok.us/api/v1/user \
  -H "Authorization: Bearer YOUR_TOKEN"

See Authentication for token creation and scope details.

REST API

The REST API follows standard conventions:

HTTP Methods

Method	Usage
`GET`	Retrieve a resource or list
`POST`	Create a resource
`PUT`	Update a resource (full replacement)
`PATCH`	Update a resource (partial update)
`DELETE`	Delete a resource

Response Format

All responses are JSON:

{
  "id": "repo_01H8XYZ",
  "name": "my-repo",
  "full_name": "my-org/my-repo",
  "private": true,
  "description": "A repository",
  "default_branch": "main",
  "created_at": "2024-03-15T14:30:22Z",
  "updated_at": "2024-03-15T14:30:22Z"
}

Pagination

List endpoints return paginated results:

curl "https://drok.us/api/v1/repos?page=1&per_page=30" \
  -H "Authorization: Bearer $Drok_TOKEN"

Pagination headers:

Link: <https://drok.us/api/v1/repos?page=2&per_page=30>; rel="next"
X-Total-Count: 142
X-Page: 1
X-Per-Page: 30
X-Total-Pages: 5

Error Responses

Errors return appropriate HTTP status codes with a JSON body:

{
  "error": "not_found",
  "message": "Repository 'my-org/nonexistent' not found",
  "documentation_url": "https://docs.drok.us/api-reference"
}

Status	Meaning
400	Bad request — invalid parameters
401	Unauthorized — missing or invalid token
403	Forbidden — insufficient permissions
404	Not found
409	Conflict — resource already exists
422	Unprocessable entity — validation failed
429	Rate limit exceeded
500	Internal server error

GraphQL API

The GraphQL API is available at:

https://drok.us/api/graphql

See GraphQL Overview for query syntax and schema documentation.

Common Endpoints

User

# Get authenticated user
GET /api/v1/user
 
# List user repositories
GET /api/v1/user/repos
 
# List user organizations
GET /api/v1/user/orgs

Repositories

# List organization repos
GET /api/v1/orgs/{org}/repos
 
# Get a repository
GET /api/v1/repos/{owner}/{repo}
 
# Create a repository
POST /api/v1/repos
 
# Get repository contents
GET /api/v1/repos/{owner}/{repo}/contents/{path}
 
# Get a branch
GET /api/v1/repos/{owner}/{repo}/branches/{branch}
 
# List commits
GET /api/v1/repos/{owner}/{repo}/commits

Merge Requests

# List merge requests
GET /api/v1/repos/{owner}/{repo}/merge-requests
 
# Create a merge request
POST /api/v1/repos/{owner}/{repo}/merge-requests
 
# Get a merge request
GET /api/v1/repos/{owner}/{repo}/merge-requests/{number}
 
# Merge a merge request
PUT /api/v1/repos/{owner}/{repo}/merge-requests/{number}/merge
 
# List merge request comments
GET /api/v1/repos/{owner}/{repo}/merge-requests/{number}/comments

Issues

# List issues
GET /api/v1/repos/{owner}/{repo}/issues
 
# Create an issue
POST /api/v1/repos/{owner}/{repo}/issues
 
# Get an issue
GET /api/v1/repos/{owner}/{repo}/issues/{number}
 
# List issue comments
GET /api/v1/repos/{owner}/{repo}/issues/{number}/comments

Pipelines

# List pipeline runs
GET /api/v1/repos/{owner}/{repo}/pipelines
 
# Get a pipeline run
GET /api/v1/repos/{owner}/{repo}/pipelines/{id}
 
# Trigger a pipeline
POST /api/v1/repos/{owner}/{repo}/pipelines
 
# Get pipeline logs
GET /api/v1/repos/{owner}/{repo}/pipelines/{id}/logs

SDKs

Official SDKs are available for:

Language	Package	Install
JavaScript/TypeScript	`@drok/sdk`	`npm install @drok/sdk`
Python	`drok-sdk`	`pip install drok-sdk`
Rust	`drok-sdk`	`cargo add drok-sdk`
Go	`drok-sdk-go`	`go get drok.us/sdk/go`

JavaScript Example

import { Drok } from '@drok/sdk';
 
const drok = new Drok({ token: process.env.Drok_TOKEN });
 
const repos = await drok.repos.list({ org: 'my-org' });
const mr = await drok.mergeRequests.create({
  owner: 'my-org',
  repo: 'my-repo',
  title: 'Add feature',
  source: 'feature-branch',
  target: 'main',
});

Python Example

from drok import Drok
 
client = Drok(token=os.environ["Drok_TOKEN"])
 
repos = client.repos.list(org="my-org")
mr = client.merge_requests.create(
    owner="my-org",
    repo="my-repo",
    title="Add feature",
    source="feature-branch",
    target="main",
)