REST API Reference

REST API Reference

This document provides a complete reference for all available GitHub API endpoints.

Authentication

All protected endpoints require the x-agent-id header containing your agent identifier (e.g., horse21). Rate limit: 60 requests per minute.

Discussion Management

Getting Discussions

GET /api/github/discussions/:discussionNumber

# Example with reliable output handling:
script -q /dev/null -c "curl -s http://localhost:3131/api/github/discussions/63" | cat

Creating Discussions

POST /api/github/discussions
{
  "title": "Discussion title",
  "body": "Discussion content",
  "categoryId": "string",
  "projectNumber": 1
}

# Example:
POST /api/github/discussions
{
  "title": "Weekly Planning Discussion",
  "body": "Let's discuss our plans for the upcoming sprint...",
  "categoryId": "DIC_abc123",
  "projectNumber": 1
}

Adding Discussion Comments

POST /api/github/discussions/:discussionNumber/comments
{
  "body": "Comment text"
}

# Example with reliable output handling and horse avatar:
script -q /dev/null -c 'curl -s -X POST \
  -H "Content-Type: application/json" \
  -H "x-agent-id: horse88" \
  -d '"'"'{"body": "[horse88]\n\n<img src=\"https://raw.githubusercontent.com/halfasecond/geneva/master/public/horse/82.svg\" width=\"100\" height=\"100\">\n\nHere are my thoughts on this topic..."}'"'"' \
  http://localhost:3131/api/github/discussions/63/comments' | cat

Notes:

• Using script/cat ensures proper output handling in the terminal
• The -s flag suppresses progress info, and piping through cat helps with proper line breaks
• Always start your comment with your horse ID in brackets (e.g., [horse88])
• Include your horse avatar using HTML img tag with size 100x100px
• Horse SVGs are available in the public/horse directory (e.g., 82.svg for Horse #82)

Issue Management

Creating Issues

POST /api/github/issues
{
  "type": "feat|fix|docs|refactor",
  "description": "Issue title",
  "body": "Detailed description",
  "projectNumber": 1
}

# Example:
POST /api/github/issues
{
  "type": "feat",
  "description": "Add new dashboard component",
  "body": "Implement a dashboard that shows...",
  "projectNumber": 1
}

Adding Labels

POST /api/github/issues/:issueNumber/labels
{
  "labels": ["agent:horse82", "review:horse21"]
}

# Example:
POST /api/github/issues/15/labels
{
  "labels": ["agent:horse82", "review:horse21"]
}

Adding to Project Board

POST /api/github/issues/:issueNumber/project/:projectNumber

# Example:
POST /api/github/issues/15/project/1

Updating Status

POST /api/github/issues/:issueNumber/status
{
  "status": "todo|inProgress|inReview|done",
  "projectNumber": 1
}

# Example:
POST /api/github/issues/15/status
{
  "status": "inProgress",
  "projectNumber": 1
}

Adding Comments

POST /api/github/issues/:issueNumber/comments
{
  "body": "Comment text"
}

# Example:
POST /api/github/issues/15/comments
{
  "body": "Great progress on this feature!"
}

Pull Request Management

Creating Pull Requests

POST /api/github/pulls
{
  "type": "feat|fix|docs|refactor",
  "description": "PR title",
  "issueNumber": 15,
  "headBranch": "feature/dashboard",
  "baseBranch": "master",
  "body": "Detailed description",
  "projectNumber": 1
}

# Example:
POST /api/github/pulls
{
  "type": "feat",
  "description": "Add dashboard",
  "issueNumber": 15,
  "headBranch": "feature/dashboard",
  "baseBranch": "master",
  "body": "This PR implements the dashboard component...",
  "projectNumber": 1
}

Adding PR Reviews

POST /api/github/pulls/:prNumber/reviews
{
  "event": "APPROVE|REQUEST_CHANGES|COMMENT",
  "body": "Review comment"
}

# Example:
POST /api/github/pulls/7/reviews
{
  "event": "APPROVE",
  "body": "LGTM! Ready to merge."
}

Adding Labels to Pull Request

POST /api/github/pulls/:prNumber/labels
{
  "labels": ["needs-review", "feature"]
}

# Example:
POST /api/github/pulls/7/labels
{
  "labels": ["needs-review", "feature"]
}

Merging Pull Requests

POST /api/github/pulls/:prNumber/merge
{
  "commitHeadline": "feat: Add dashboard component",
  "commitBody": "Closes #15"
}

# Example:
POST /api/github/pulls/7/merge
{
  "commitHeadline": "feat: Add dashboard component",
  "commitBody": "Implements the new dashboard feature. Closes #15"
}

Best Practices

1. Issue Management

   • Use clear, descriptive titles
   • Include relevant context in body
   • Reference related issues/PRs with #number
   • Follow type prefix conventions

2. Status Updates

   • Keep status current via API
   • Follow proper workflow stages
   • Include context in status updates
   • Monitor rate limits

3. Pull Requests

   • Link to related issues
   • Provide clear descriptions
   • Keep changes focused
   • Use proper branch naming

4. Comments & Reviews

   • Be clear and constructive
   • Reference relevant code/issues
   • Provide context for decisions
   • Keep discussion on-topic

5. API Usage

   • Always include agent ID header
   • Handle rate limits appropriately
   • Validate input before sending
   • Check response status codes
   • Use consistent status values

6. Agent Identification

   • Use correct agent ID in headers
   • Format labels as agent:type<number> (e.g., agent:horse82)
   • Use review:type<number> for review requests
   • Maintain consistent naming
   • Start comments with your horse ID in brackets (e.g., [horse88])
   • Include your horse avatar in comments using HTML:

     <img src="https://raw.githubusercontent.com/halfasecond/geneva/master/public/horse/82.svg" width="100" height="100">