Skip to main content

​
API Introduction

The Octokraft API provides programmatic access to code health assessments, PR analysis, architecture insights, and project management. All endpoints return JSON and follow standard REST conventions.

​
Base URL

https://app.octokraft.com/api/v1
For self-hosted deployments: 
https://your-octokraft.com/api/v1

​
Authentication

All API requests require an API key passed as a Bearer token in the Authorization header. 
curl "https://app.octokraft.com/api/v1/projects" \
  -H "Authorization: Bearer ok_live_abc123..."
See the Authentication page for details on creating and managing API keys.

​
Request/Response Format

All request and response bodies use JSON. Include Content-Type: application/json for POST, PATCH, and PUT requests. 
curl "https://app.octokraft.com/api/v1/projects" \
  -H "Authorization: Bearer ok_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"name": "My Project", "key": "my-project"}'

​
Error Responses

Errors return a JSON object with an error field: 
{
  "error": "project not found"
}

​
HTTP Status Codes

CodeDescription
200Success
201Created
204No Content (successful delete)
400Bad Request — invalid input or missing required fields
401Unauthorized — missing or invalid API key
403Forbidden — key lacks access to the requested resource
404Not Found
409Conflict — e.g., removing the last project owner
500Internal Server Error

​
Pagination

List endpoints use limit and offset query parameters for pagination. 
GET /api/v1/projects/{id}/health/assessments?limit=20&offset=0
ParameterTypeDescriptionDefault
limitintegerItems per page (max 100)20
offsetintegerNumber of items to skip0
Paginated responses include total_count (or total), limit, and offset fields alongside the items array.

​
API Endpoints Overview

​
Projects

MethodEndpointDescription
GET/api/v1/projectsList projects
POST/api/v1/projectsCreate project
GET/api/v1/projects/{id}Get project
PATCH/api/v1/projects/{id}Update project
DELETE/api/v1/projects/{id}Delete project
GET/api/v1/projects/{id}/membersList members
POST/api/v1/projects/{id}/invitationsInvite member
PATCH/api/v1/projects/{id}/members/{userId}Update member role
DELETE/api/v1/projects/{id}/members/{userId}Remove member

​
Code Health

MethodEndpointDescription
GET/api/v1/projects/{id}/healthGet health dashboard
GET/api/v1/projects/{id}/health/assessmentsList assessments
GET/api/v1/projects/{id}/health/assessments/{assessmentId}Get assessment
POST/api/v1/projects/{id}/health/triggerTrigger assessment
GET/api/v1/projects/{id}/health/drift-alertsList drift alerts
POST/api/v1/projects/{id}/health/drift-alerts/{alertId}/dismissDismiss drift alert
GET/api/v1/projects/{id}/health/categoriesList health categories

​
Analysis

MethodEndpointDescription
GET/api/v1/projects/{id}/analysis/issuesList issues
GET/api/v1/projects/{id}/analysis/issues/{issueId}Get issue
GET/api/v1/projects/{id}/analysis/issues/statsIssue statistics
POST/api/v1/projects/{id}/analysis/issues/{issueId}/dismissDismiss issue
POST/api/v1/projects/{id}/analysis/issues/{issueId}/restoreRestore dismissed issue
GET/api/v1/projects/{id}/analysis/dismiss-rulesList dismiss rules
POST/api/v1/projects/{id}/analysis/dismiss-rulesCreate dismiss rule
DELETE/api/v1/projects/{id}/analysis/dismiss-rules/{ruleId}Delete dismiss rule

​
Pull Requests

MethodEndpointDescription
GET/api/v1/projects/{id}/pr-analysesList PR analyses
GET/api/v1/projects/{id}/pr-analyses/{analysisId}Get PR analysis
GET/api/v1/projects/{id}/pr-analyses/statsPR statistics
GET/api/v1/projects/{id}/repos/{repoId}/prs/{number}/analysisGet latest analysis for PR
POST/api/v1/projects/{id}/repos/{repoId}/prs/{number}/analyzeTrigger PR analysis

​
Architecture

MethodEndpointDescription
GET/api/v1/projects/{id}/architecture/overviewArchitecture overview
GET/api/v1/projects/{id}/architecture/reviewsList architecture reviews
GET/api/v1/projects/{id}/architecture/reviews/{reviewId}Get architecture review
POST/api/v1/projects/{id}/architecture/reviews/triggerTrigger architecture review
GET/api/v1/projects/{id}/architecture/conventionsList conventions
PATCH/api/v1/projects/{id}/architecture/conventions/{conventionId}Update convention status
POST/api/v1/projects/{id}/architecture/conventions/detectTrigger convention detection
GET/api/v1/projects/{id}/architecture/adrsList ADRs
POST/api/v1/projects/{id}/architecture/adrsCreate ADR
GET/api/v1/projects/{id}/architecture/adrs/{adrId}Get ADR
PATCH/api/v1/projects/{id}/architecture/adrs/{adrId}Update ADR

​
Repositories

MethodEndpointDescription
GET/api/v1/projects/{id}/reposList project repositories
POST/api/v1/projects/{id}/reposLink repository to project
DELETE/api/v1/projects/{id}/repos/{repoId}Unlink repository
GET/api/v1/projects/{id}/repos/availableList available repositories
POST/api/v1/github/installations/syncSync GitHub installations