Skip to main content

​
Overview

This endpoint lists the contents of a specific folder within a repository accessible via a viewer token. It enables navigation through the directory structure.

​
Endpoint

GET /view-folder/:token?path={folder_path}

​
Path Parameters

​
token
string
required
The unique viewer token that grants access to the repository

​
Query Parameters

​
path
string
The folder path within the repository (e.g., “src/handlers”). If omitted, returns root contents.

​
How It Works

  1. Token is extracted from URL
  2. Folder path is read from query parameters
  3. Link validity is verified
  4. Expiration and view count limits are checked
  5. Folder contents are fetched from GitHub
  6. Contents array is returned as JSON

​
Response

Returns the raw GitHub API response containing folder contents.
​
name
string
Name of the file or subdirectory
​
path
string
Full path within the repository
​
type
string
Either “file” or “dir”
​
size
number
Size in bytes (for files)
​
sha
string
Git SHA hash of the content
​
url
string
GitHub API URL for this item
​
html_url
string
GitHub web URL for this item
​
git_url
string
Git API URL for this item
​
download_url
string
Direct download URL (for files)

​
Example Request

curl "https://api.privycode.com/view-folder/abc123xyz456?path=src/handlers"

​
Example Response

[
  {
    "name": "user_handler.go",
    "path": "src/handlers/user_handler.go",
    "type": "file",
    "size": 2048,
    "sha": "a1b2c3d4e5f6",
    "url": "https://api.github.com/repos/user/repo/contents/src/handlers/user_handler.go",
    "html_url": "https://github.com/user/repo/blob/main/src/handlers/user_handler.go",
    "git_url": "https://api.github.com/repos/user/repo/git/blobs/a1b2c3d4e5f6",
    "download_url": "https://raw.githubusercontent.com/user/repo/main/src/handlers/user_handler.go"
  },
  {
    "name": "auth_handler.go",
    "path": "src/handlers/auth_handler.go",
    "type": "file",
    "size": 1536,
    "sha": "b2c3d4e5f6a1",
    "url": "https://api.github.com/repos/user/repo/contents/src/handlers/auth_handler.go",
    "html_url": "https://github.com/user/repo/blob/main/src/handlers/auth_handler.go",
    "git_url": "https://api.github.com/repos/user/repo/git/blobs/b2c3d4e5f6a1",
    "download_url": "https://raw.githubusercontent.com/user/repo/main/src/handlers/auth_handler.go"
  }
]

​
Error Responses

​
400
error
Missing token - No token provided in URL
​
404
error
Invalid viewer link - Token not found in database
​
403
error
Link expired or view limit reached - Token has expired or max views exceeded
​
GitHub errors
error
Errors from GitHub API if the folder cannot be accessed

​
Use Case

When a recruiter clicks on a folder in the repository browser, this endpoint fetches the folder’s contents, allowing them to navigate deeper into the project structure.

​
Notes

  • Response is directly proxied from GitHub API
  • Content-Type is set to application/json
  • View count is NOT incremented on folder views (only on initial repo access)

Build docs developers (and LLMs) love

Get started for freeTalk to us