REST API Reference

OpenCodeHub provides a comprehensive REST API with 140+ endpoints for interacting with repositories, users, pull requests, issues, and more programmatically.

• Base URL: /api
• Authentication: Bearer Token or Personal Access Token (see Authentication)
• Response Format: JSON with standard { success, data, meta? } wrapper
• Rate Limit: 100 requests/minute (authenticated), 20/minute (unauthenticated)

Users

Get Current User

GET /api/user

Response:

{
  "success": true,
  "data": {
    "id": "usr_123abc",
    "username": "johndoe",
    "email": "[email protected]",
    "displayName": "John Doe",
    "avatarUrl": "/uploads/avatars/usr_123.jpg",
    "bio": "Full-stack developer",
    "location": "San Francisco",
    "website": "https://johndoe.dev",
    "company": "Acme Inc",
    "isAdmin": false,
    "createdAt": "2024-01-01T00:00:00Z"
  }
}

Get / Update / Delete Profile

GET    /api/auth/me
PATCH  /api/auth/me
DELETE /api/auth/me

PATCH Body:

{
  "displayName": "John Doe",
  "bio": "Updated bio",
  "location": "New York",
  "website": "https://example.com",
  "company": "New Co"
}

Repositories

List Repositories

GET /api/repos?page=1&per_page=20

Response:

{
  "success": true,
  "data": [
    {
      "id": "repo_789xyz",
      "owner": "johndoe",
      "name": "awesome-project",
      "visibility": "public",
      "description": "My awesome project",
      "updatedAt": "2024-03-15T10:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "perPage": 20,
    "total": 45,
    "totalPages": 3
  }
}

Create Repository

POST /api/repos

Body:

{
  "name": "new-project",
  "visibility": "private",
  "description": "Optional description",
  "init": true
}

Get Repository Details

GET /api/repos/{owner}/{repo}

Update Repository

PATCH /api/repos/{owner}/{repo}

Body:

{
  "description": "Updated description",
  "visibility": "public",
  "defaultBranch": "main"
}

Delete Repository

DELETE /api/repos/{owner}/{repo}

Issues

List Issues

GET /api/repos/{owner}/{repo}/issues?state=open&page=1

Query Parameters:

Create Issue

POST /api/repos/{owner}/{repo}/issues

Body:

{
  "title": "Bug report",
  "body": "Something is broken",
  "type": "issue",
  "labels": ["bug"],
  "assignees": ["username"]
}

Get Issue

GET /api/repos/{owner}/{repo}/issues/{number}

Update Issue

PATCH /api/repos/{owner}/{repo}/issues/{number}

Body:

{
  "title": "Updated title",
  "state": "closed",
  "labels": ["bug", "priority"]
}

Add Comment

POST /api/repos/{owner}/{repo}/issues/{number}/comments

Body:

{
  "body": "This is a comment"
}

Pull Requests

List Pull Requests

GET /api/repos/{owner}/{repo}/pulls?state=open

Query Parameters:

Create Pull Request

POST /api/repos/{owner}/{repo}/pulls

Body:

{
  "title": "Fix login bug",
  "body": "Fixes issue #42",
  "head": "feature/login-fix",
  "base": "main"
}

Get Pull Request

GET /api/repos/{owner}/{repo}/pulls/{number}

Update Pull Request

PATCH /api/repos/{owner}/{repo}/pulls/{number}

Merge Pull Request

POST /api/repos/{owner}/{repo}/pulls/{number}/merge

Body:

{
  "method": "squash",
  "message": "Custom merge message"
}

List Reviews

GET /api/repos/{owner}/{repo}/pulls/{number}/reviews

Create Review

POST /api/repos/{owner}/{repo}/pulls/{number}/reviews

Body:

{
  "body": "Looks good!",
  "event": "APPROVE",
  "comments": [
    {
      "path": "src/auth.ts",
      "line": 45,
      "body": "Consider adding error handling here"
    }
  ]
}

Stacked PRs

List Stacks

GET /api/repos/{owner}/{repo}/stacks

Create Stack Entry

POST /api/repos/{owner}/{repo}/stacks

Body:

{
  "prNumber": 124,
  "basePrNumber": 123
}

Sync Stack

POST /api/repos/{owner}/{repo}/stacks/sync

Merge Queue

List Queue

GET /api/repos/{owner}/{repo}/merge-queue

Add to Queue

POST /api/repos/{owner}/{repo}/merge-queue

Body:

{
  "prNumber": 125,
  "priority": "normal"
}

Remove from Queue

DELETE /api/repos/{owner}/{repo}/merge-queue/{entryId}

CI/CD (Actions)

List Workflow Runs

GET /api/repos/{owner}/{repo}/actions/runs

Get Workflow Run

GET /api/repos/{owner}/{repo}/actions/runs/{runId}

List Jobs

GET /api/repos/{owner}/{repo}/actions/runs/{runId}/jobs

Get Job Logs

GET /api/repos/{owner}/{repo}/actions/jobs/{jobId}/logs

Rerun Workflow

POST /api/repos/{owner}/{repo}/actions/runs/{runId}/rerun

Cancel Workflow

POST /api/repos/{owner}/{repo}/actions/runs/{runId}/cancel

Releases

List Releases

GET /api/repos/{owner}/{repo}/releases

Create Release

POST /api/repos/{owner}/{repo}/releases

Body:

{
  "tagName": "v1.0.0",
  "name": "Release 1.0.0",
  "body": "Release notes...",
  "isDraft": false,
  "isPrerelease": false
}

Get Release

GET /api/repos/{owner}/{repo}/releases/{id}

Delete Release

DELETE /api/repos/{owner}/{repo}/releases/{id}

Organizations

List Organizations

GET /api/orgs

Get Organization

GET /api/orgs/{org}

List Members

GET /api/orgs/{org}/members

Add Member

POST /api/orgs/{org}/members

Body:

{
  "username": "newmember",
  "role": "member"
}

Notifications

List Notifications

GET /api/notifications?filter=unread&prioritize=true

Query Parameters:

Response:

{
  "success": true,
  "data": {
    "notifications": [
      {
        "id": "notif_1",
        "type": "comment",
        "priority": "medium",
        "priorityScore": 5,
        "isRead": false,
        "actor": { "username": "bob" },
        "repository": { "name": "my-repo" }
      }
    ],
    "unreadCount": 3,
    "routing": {
      "personalized": true,
      "channelFilter": null
    }
  }
}

Mark as Read

POST /api/notifications/{id}/read

Archive Notification

POST /api/notifications/{id}/archive

Webhooks

List Webhooks

GET /api/repos/{owner}/{repo}/webhooks

Create Webhook

POST /api/repos/{owner}/{repo}/webhooks

Body:

{
  "url": "https://yourapp.com/webhook",
  "events": ["push", "pull_request", "issues"],
  "secret": "your-webhook-secret"
}

Test Webhook

POST /api/repos/{owner}/{repo}/webhooks/{id}/test

Delete Webhook

DELETE /api/repos/{owner}/{repo}/webhooks/{id}

Search

Global Search

GET /api/search?q=keyword&type=repositories

Query Parameters:

Admin

System Stats

GET /api/admin/stats

Response:

{
  "success": true,
  "data": {
    "totalRepos": 45,
    "totalUsers": 12,
    "collaborations": 128,
    "systemStatus": {
      "cpuLoad": 15,
      "memoryUsage": 42,
      "storageUsage": 45,
      "uptime": "5d 3h 12m"
    },
    "quickStats": {
      "commitsToday": 23,
      "prsMerged": 5,
      "issuesClosed": 8,
      "activeUsers": 6
    }
  }
}

Audit Logs

GET /api/admin/audit-logs?page=1

List Runners

GET /api/admin/runners

Error Codes

Error Response:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Repository not found"
  }
}

Pagination

List endpoints support pagination via query parameters:

GET /api/repos?page=2&per_page=50

Pagination metadata is included in the response:

{
  "meta": {
    "page": 2,
    "perPage": 50,
    "total": 127,
    "totalPages": 3
  }
}