GitHub API Overview

GitHub's REST API provides programmatic access to repositories, issues, pull requests, and related resources. All operations require authentication via OAuth token with appropriate scopes.

Authentication

Operations use OAuth tokens obtained through Pipedream. The repo scope grants read/write access to repositories, issues, and pull requests. Tokens are injected automatically—code receives them as PLACEHOLDER_TOKEN.

Rate Limits

Authenticated requests allow 5,000 requests per hour per user. Check X-RateLimit-Remaining header to monitor usage. When remaining < 100, log a warning. If rate limited (403), wait until X-RateLimit-Reset timestamp.

Pagination

List endpoints return paginated results. Use per_page (max 100, default 30) and page parameters. The Link header contains URLs for next/prev/first/last pages. For large result sets, follow rel="next" links until exhausted.

Common Patterns

Repository identifier: Always owner/repo format (e.g., octocat/Hello-World). Parse from full URLs if needed.

Issue vs PR numbers: Both use the same number sequence per repository. Issue #5 and PR #5 cannot coexist in the same repo.

State filtering: Issues and PRs accept state parameter: open, closed, or all.

Error Handling

API errors return JSON with message field. Common errors: 404 (not found), 403 (forbidden/rate limited), 422 (validation failed). Surface error messages to the agent via logs for diagnosis.