GitHub REST API
Repos, files, issues, pull requests, Actions workflow runs and search with a fine-grained token on API version 2026-03-10.
Developer toolsGuided#git#repositories#issues#pull-requests#github-actions#ci
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
The GitHub REST API lets you script almost everything you do on github.com: read and create repositories, read and commit files, open and triage issues, open and merge pull requests, start GitHub Actions workflows and watch their runs, and search code, issues and repositories. This guided collection covers the calls most integrations need first, in the order you would normally make them.
Getting a token (fine-grained personal access token)
- Sign in to GitHub and open Settings > Developer settings > Personal access tokens > Fine-grained tokens (direct link: https://github.com/settings/personal-access-tokens/new).
- Give the token a name and an expiry date, and pick the resource owner (your account or an organization that allows fine-grained tokens).
- Under Repository access, choose Only select repositories and pick a test repository.
- Under Permissions, grant what this collection uses: Contents read and write, Issues read and write, Pull requests read and write, Actions read and write (Metadata read is added automatically). Add Workflows write only if you will commit files under
.github/workflows. - Generate the token and copy it once; paste it into the
tokenvariable (marked secret).
Docs: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens and the permission map at https://docs.github.com/en/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens.
Authentication and versioning
Every request sends Authorization: Bearer <token> (set on the collection), Accept: application/vnd.github+json and X-GitHub-Api-Version. The latest REST version is 2026-03-10; if you send no version header GitHub still answers as 2022-11-28, which stays supported until March 2028. Version 2026-03-10 has breaking changes, for example the workflow dispatch call now returns 200 with the new run's ID, the singular assignee field is gone (use assignees), and GET /rate_limit no longer has the top-level rate object. See https://docs.github.com/en/rest/about-the-rest-api/api-versions and https://docs.github.com/en/rest/about-the-rest-api/breaking-changes.
Base URL
https://api.github.com for github.com. GitHub Enterprise Server uses https://<your-host>/api/v3, and GHE.com data residency uses https://api.<subdomain>.ghe.com. There is no separate sandbox: use a throwaway repository.
Variables and run order
Fill token, owner (your user or organization login) and repo (a test repository you own). Run 1. Start here to confirm the token works, then folders 2 to 7 in order. Requests save IDs they create (issueNumber, pullNumber, runId, fileSha) into variables for the next steps. For 6. Actions, set workflowFile to a workflow in your repository that has an on: workflow_dispatch trigger.
Limits
Authenticated users get a per-hour primary rate limit (much higher than the 60 per hour allowed without a token), search has its own smaller per-minute limit, and secondary limits stop bursts of concurrent or content-creating requests. Read the x-ratelimit-* response headers or call Check rate limit. Details: https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api.
Common errors
| Status | Meaning | What to do |
|---|---|---|
| 401 | Bad or expired token | Generate a new token and update token. |
| 403 | Missing permission, or a secondary rate limit | Check the token's permissions; on rate limits wait for retry-after. |
| 404 | Not found, or no access to a private resource | GitHub hides private resources behind 404; check owner, repo and repository access. |
| 409 | Conflict, e.g. stale sha when updating a file | Fetch the file again and resend with the new sha. |
| 410 | API version no longer supported | Update apiVersion. |
| 422 | Validation failed | Read errors[] in the body; usually a missing or invalid field. |
Links
- REST reference: https://docs.github.com/en/rest
- Getting started: https://docs.github.com/en/rest/using-the-rest-api/getting-started-with-the-rest-api
- Best practices: https://docs.github.com/en/rest/using-the-rest-api/best-practices-for-using-the-rest-api
Endpoints 29
1. Start here
- GETGet the authenticated user
/userReturns the account the token belongs to. Run it first: a 200 proves the token and headers are right, and login is the value to put in owner if you are… - GETCheck rate limit
/rate_limitShows how many requests remain in each bucket (core, search, code_search, graphql and others) and when each window resets (reset is a Unix time). Calling this… - GETList supported API versions
/versionsReturns the REST API versions the server accepts, newest first. Use it to check the value of apiVersion; a version that has left support answers every request…
2. Repositories
- GETList your repositories
/user/reposLists repositories the authenticated user can access: owned, collaborator and organization member repositories. Narrow it with type or affiliation, sort with… - GETGet a repository
/repos/{{owner}}/{{repo}}Reads one repository: visibility, default branch, counts, topics and the token's permissions on it. Use default_branch as the base branch for pull requests… - POSTCreate a repository for the authenticated user
/user/reposCreates a new repository under your own account. auto_init: true adds a first commit with a README so the default branch exists right away, which the file and… - GETList branches
/repos/{{owner}}/{{repo}}/branchesLists the branches of the repository with the latest commit SHA of each. Pass protected=true to see only protected branches. The SHA of the default branch is…
3. Contents
- GETGet file contents
/repos/{{owner}}/{{repo}}/contents/{{filePath}}Reads a file at filePath on the branch in ref. The JSON form returns the file Base64 encoded in content plus its blob sha; the sha is saved into fileSha and… - GETGet raw file contents
/repos/{{owner}}/{{repo}}/contents/{{filePath}}Same path as the previous request but with Accept: application/vnd.github.raw+json, so the body is the file itself rather than a JSON wrapper. Handy for… - PUTCreate or update a file
/repos/{{owner}}/{{repo}}/contents/{{filePath}}Commits fileText to filePath on branch. The pre-request script Base64-encodes fileText into fileContentB64, because the API only accepts Base64 content. Leave…
4. Issues
- POSTCreate an issue
/repos/{{owner}}/{{repo}}/issuesOpens an issue in the repository. title is required; body is Markdown; labels and assignees take arrays of names and logins (the singular assignee field was… - GETList repository issues
/repos/{{owner}}/{{repo}}/issuesLists issues in the repository, newest first by default. Filter by state (open, closed, all), labels (comma separated), assignee or since. Note that this… - PATCHUpdate an issue
/repos/{{owner}}/{{repo}}/issues/{{issueNumber}}Edits the issue saved in issueNumber: change the title or body, replace labels or assignees, or close it with state: closed and a state_reason of completed or… - POSTAdd a comment to an issue
/repos/{{owner}}/{{repo}}/issues/{{issueNumber}}/commentsPosts a Markdown comment on the issue or pull request numbered issueNumber (pull requests share the issue number space, so this also comments on PR… - POSTAdd labels to an issue
/repos/{{owner}}/{{repo}}/issues/{{issueNumber}}/labelsAdds labels to the issue without removing the ones already there, unlike the update request which replaces the full list. Send the label names in labels;…
5. Pull requests
- POSTCreate a pull request
/repos/{{owner}}/{{repo}}/pullsOpens a pull request from headBranch into branch. The head branch must exist and contain commits the base does not; for a fork use owner:branch as head. Set… - GETList pull requests
/repos/{{owner}}/{{repo}}/pullsLists pull requests in the repository. Filter by state (open, closed, all), head (user:branch) and base, and sort by created, updated or popularity. Use it to… - GETGet a pull request
/repos/{{owner}}/{{repo}}/pulls/{{pullNumber}}Reads one pull request with its merge state. mergeable is computed in the background and can be null on the first call, so wait a moment and ask again;… - GETList files in a pull request
/repos/{{owner}}/{{repo}}/pulls/{{pullNumber}}/filesLists the files a pull request changes, with per-file status (added, modified, removed, renamed), additions, deletions and the unified diff in patch. Useful… - PUTMerge a pull request
/repos/{{owner}}/{{repo}}/pulls/{{pullNumber}}/mergeMerges the pull request. merge_method is merge, squash or rebase (only the methods enabled on the repository work). Pass sha to merge only if the head is…
6. Actions
- GETList repository workflows
/repos/{{owner}}/{{repo}}/actions/workflowsLists the workflows defined in .github/workflows, with their numeric id, file path and state. You can address a workflow either by that id or by its file name… - POSTRun a workflow (workflow dispatch)
/repos/{{owner}}/{{repo}}/actions/workflows/{{workflowFile}}/dispatchesStarts the workflow in workflowFile on the branch or tag in ref. The workflow must declare an on: workflow_dispatch trigger, and inputs must match the inputs… - GETList runs of a workflow
/repos/{{owner}}/{{repo}}/actions/workflows/{{workflowFile}}/runsLists recent runs of one workflow, newest first. Filter with branch, event (push, workflow_dispatch, schedule ...) or status (queued, in_progress, completed,… - GETGet a workflow run
/repos/{{owner}}/{{repo}}/actions/runs/{{runId}}Reads the run in runId. Poll it until status is completed, then read conclusion (success, failure, cancelled, skipped, timed_out and so on). Poll at a gentle… - POSTCancel a workflow run
/repos/{{owner}}/{{repo}}/actions/runs/{{runId}}/cancelAsks GitHub to cancel the run in runId. It returns 202 Accepted because cancellation happens asynchronously; read the run again to see conclusion: cancelled.… - POSTRe-run a workflow run
/repos/{{owner}}/{{repo}}/actions/runs/{{runId}}/rerunStarts a new attempt of the run in runId with the same commit and inputs; run_attempt goes up by one. Set enable_debug_logging to true to get runner debug…
7. Search
- GETSearch repositories
/search/repositoriesFinds repositories with GitHub's search syntax in q, for example topic:payments language:go stars:>500. Sort by stars, forks, help-wanted-issues or updated.… - GETSearch issues and pull requests
/search/issuesSearches issues and pull requests. Always include is:issue or is:pr in q; the query below finds open bugs in your test repository. Combine qualifiers such as… - GETSearch code
/search/codeSearches file contents in default branches. Requires a token and has the tightest limit (see code_search in the rate limit call). Scope the query with repo:,…
API details
- Base URL
https://api.github.com- Authentication
- A bearer token in the Authorization header
- Operations
- 29 operations on 29 pathsGET 18POST 8PUT 2PATCH 1
- Main resources
- 1. Start here 32. Repositories 43. Contents 34. Issues 55. Pull requests 56. Actions 67. Search 3
- Description format
- Swastik Codes guided collection, API version
checked against the docs on 2026-11-18 - Links
- Documentation
How to test the GitHub REST API in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the GitHub REST API collection, without the publisher's secrets.
- Add your credentialsThis API uses A bearer token in the Authorization header. Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “Get the authenticated user” (GET /user), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the GitHub REST API?
Repos, files, issues, pull requests, Actions workflow runs and search with a fine-grained token on API version 2026-03-10. It is listed under Developer tools and has 29 endpoints.
Who publishes the GitHub REST API?
It is listed from GitHub's public API description (an OpenAPI document), not published by GitHub on Swastik Codes. Anyone who controls github.com can claim the profile by adding a DNS TXT record.
What is the base URL of the GitHub REST API?
Requests go to https://api.github.com. Endpoint paths are added to this base URL.
How do I authenticate with the GitHub REST API?
With A bearer token in the Authorization header.
How many endpoints does the GitHub REST API have?
29 operations on 29 paths (18 GET, 8 POST, 2 PUT, 1 PATCH). The largest groups are 1. Start here, 2. Repositories, 3. Contents, 4. Issues.
Is forking the GitHub REST API free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.