Skip to content

api.md

Latest commit

 

History

History
390 lines (293 loc) · 6.6 KB

api.md

File metadata and controls

390 lines (293 loc) · 6.6 KB
Raw

API Reference

All endpoints are served from the ForkFind backend. Default base URL is http://127.0.0.1:8787.

Health

GET /api/health

Health check endpoint.

Response 200 OK

{ "status": "ok" }

Config

GET /api/config

Read the current application configuration.

Response 200 OK

{
  "githubToken": "ghp_xxx",
  "llmBaseUrl": "https://api.openai.com/v1",
  "llmApiKey": "sk-xxx",
  "llmAuthType": "bearer",
  "models": ["gpt-4o", "gpt-4o-mini"],
  "embeddingModels": ["text-embedding-3-small"],
  "modelRouting": { ... },
  "webhookUrl": "https://hooks.example.com/webhook",
  "webhookBody": "{ \"text\": \"completed: {{repo}}\" }",
  "scanLimits": { ... },
  "llmStages": { ... }
}

PUT /api/config

Save the application configuration.

Request application/json

{
  "githubToken": "ghp_xxx",
  "llmBaseUrl": "https://api.openai.com/v1",
  "llmApiKey": "sk-xxx",
  ...
}

Response 200 OK

{ "ok": true }

Jobs

POST /api/jobs

Create a new analysis job and enqueue it.

Request application/json

{
  "repo": "QuantumNous/new-api",
  "question": "Did any fork fix issue #4714?",
  "mode": "ask"
}

mode can be "ask" or "discover".

Response 200 OK

{
  "id": "abc123",
  "status": "queued"
}

GET /api/jobs

List all jobs, most recent first.

Response 200 OK

[
  {
    "id": "abc123",
    "repo": "QuantumNous/new-api",
    "question": "Did any fork fix issue #4714?",
    "mode": "ask",
    "status": "completed",
    "createdAt": "2025-01-01T00:00:00.000Z",
    "completedAt": "2025-01-01T00:05:00.000Z"
  }
]

GET /api/jobs/:id

Get detailed job information including fork tasks and stage progress.

Response 200 OK

{
  "id": "abc123",
  "repo": "QuantumNous/new-api",
  "question": "Did any fork fix issue #4714?",
  "mode": "ask",
  "status": "running",
  "forkTasks": [
    {
      "forkName": "user/fork-name",
      "stage": "llm_summary",
      "status": "completed"
    }
  ],
  "events": [ ... ],
  "usage": {
    "githubRequests": 42,
    "llmRequests": 10,
    "llmTokens": 15000
  }
}

GET /api/jobs/:id/result

Get the analysis report for a completed job.

Response 200 OK

{
  "jobId": "abc123",
  "repo": "QuantumNous/new-api",
  "question": "Did any fork fix issue #4714?",
  "candidates": [
    {
      "fork": "user/fork-name",
      "score": 0.85,
      "evidence": "Commit abc123 modifies the file related to issue #4714...",
      "summary": "This fork fixes the turnstile registration bug..."
    }
  ],
  "insights": { ... },
  "usage": { ... }
}

POST /api/jobs/:id/pause

Pause a queued or running analysis job. Running jobs stop at the next checkpoint and keep reusable intermediate progress such as fetched forks, deep fork candidates, and LLM summaries.

Response 200 OK

{
  "job": {
    "id": "abc123",
    "status": "paused"
  }
}

POST /api/jobs/:id/resume

Resume a paused analysis job. The job returns to the queue and reuses saved checkpoint data where available.

Response 200 OK

{
  "job": {
    "id": "abc123",
    "status": "queued"
  }
}

DELETE /api/jobs/:id

Delete an analysis job and its event log.

Response 200 OK

{ "ok": true }

GET /api/jobs/:id/events

Get the event log for a job.

Response 200 OK

[
  {
    "type": "scan_start",
    "message": "Scanning forks...",
    "timestamp": "2025-01-01T00:00:00.000Z"
  },
  {
    "type": "fork_analyzed",
    "message": "Analyzed fork user/fork-name",
    "timestamp": "2025-01-01T00:01:00.000Z"
  }
]

GitHub

POST /api/test/github

Test GitHub token validity.

Request application/json

{
  "token": "ghp_xxx"
}

Response 200 OK

{
  "ok": true,
  "user": "your-username"
}

GET /api/github/rate-limit

View GitHub API rate limits for all resource types.

Response 200 OK

{
  "core": { "limit": 5000, "remaining": 4950, "reset": 1700000000 },
  "search": { "limit": 30, "remaining": 30, "reset": 1700000000 },
  "graphql": { "limit": 5000, "remaining": 5000, "reset": 1700000000 },
  "code_search": { "limit": 10, "remaining": 10, "reset": 1700000000 }
}

LLM

POST /api/test/llm

Test LLM API connectivity.

Request application/json

{
  "baseUrl": "https://api.openai.com/v1",
  "apiKey": "sk-xxx",
  "authType": "bearer",
  "model": "gpt-4o-mini"
}

Response 200 OK

{
  "ok": true,
  "response": "Hello from GPT-4o mini!"
}

POST /api/models/list

Fetch available models from the configured LLM /models endpoint.

Request application/json

{
  "baseUrl": "https://api.openai.com/v1",
  "apiKey": "sk-xxx",
  "authType": "bearer"
}

Response 200 OK

{
  "models": ["gpt-4o", "gpt-4o-mini", "gpt-4-turbo"]
}

Webhook

POST /api/test/webhook

Send a test notification to the configured webhook URL.

Request application/json

{
  "url": "https://hooks.example.com/webhook",
  "body": "{ \"text\": \"Test notification\" }"
}

Response 200 OK

{
  "ok": true
}

Follow-Up

POST /api/follow-up

Ask a follow-up question against a completed job's report.

Request application/json

{
  "jobId": "abc123",
  "question": "Which of these forks has the most stars?"
}

Response 200 OK

{
  "answer": "Based on the report, the fork `user/popular-fork` has 234 stars..."
}

Project Revision APIs

Git is the authoritative source for branches, commits, and diffs. GitHub APIs are optional social metadata providers.

POST /api/projects
GET  /api/projects
POST /api/projects/:projectId/sources
POST /api/sources/:sourceId/sync
GET  /api/sources/:sourceId/refs
POST /api/analyses
GET  /api/analyses/:analysisId
POST /api/analyses/:analysisId/runs
GET  /api/analyses/:analysisId/messages
POST /api/analyses/:analysisId/messages

Create an analysis by selecting a baseline and one or more target refs:

{
  "projectId": "project-id",
  "question": "Which branch implements OAuth?",
  "mode": "ask",
  "scope": {
    "baseline": { "sourceId": "primary", "refName": "main" },
    "targets": [{ "sourceId": "remote-a", "refName": "feature/oauth" }],
    "strategy": "against-baseline"
  }
}

Analysis refs are resolved to immutable commit SHAs. Repeated analyses reuse cached revision comparisons and Git evidence. Messages are persisted against the analysis and reuse the latest completed run:

{ "content": "Why is the first target relevant?", "locale": "en" }