API Reference
GateDocs API
REST API for GateDocs — secure document sharing with built-in lead capture and analytics.
Authentication
All requests require a Bearer token in the Authorization header:
Authorization: Bearer gd_live_<token>Create tokens in Settings > API, or via POST /tokens.
Rate limiting
- Business: 1,000 requests/minute
- Enterprise: 5,000 requests/minute
Rate limit headers are included on every response:
X-RateLimit-Limit— max requests per windowX-RateLimit-Remaining— remaining requestsX-RateLimit-Reset— Unix timestamp when window resets
Files
Upload, manage, and share files
/filesList files
Returns a paginated list of files for the authenticated organisation. Supports filtering by folder and active status, with sorting options.
Parameters
pagequeryPage number (1-based)per_pagequeryItems per page (max 100)folder_idqueryFilter files by folder IDis_activequeryFilter by active statussortquerySort fieldorderquerySort order
Responses
200— Paginated list of files401— Missing or invalid API token403— Insufficient permissions or organisation suspended429— Rate limit exceeded500— Internal server error
/filesCreate a file record
Creates a new file record with the specified metadata and protection settings. The file must be uploaded separately to Supabase Storage.
Body FileCreate
Responses
201— File created400— Validation error401— Missing or invalid API token403— Insufficient permissions or organisation suspended429— Rate limit exceeded500— Internal server error
/files/{id}Get file details
Returns a single file with view count and lead count.
Parameters
idpath, requiredFile ID
Responses
200— File details401— Missing or invalid API token403— Insufficient permissions or organisation suspended404— Resource not found429— Rate limit exceeded500— Internal server error
/files/{id}Update a file
Updates file metadata and protection settings. All fields are optional.
Body FileUpdate
Parameters
idpath, requiredFile ID
Responses
200— File updated400— Validation error401— Missing or invalid API token403— Insufficient permissions or organisation suspended404— Resource not found429— Rate limit exceeded500— Internal server error
/files/{id}Delete a file
Soft-deletes a file by setting `deleted_at` and `is_active` to false. The file can be restored from trash.
Parameters
idpath, requiredFile ID
Responses
204— File deleted401— Missing or invalid API token403— Insufficient permissions or organisation suspended404— Resource not found429— Rate limit exceeded500— Internal server error
/files/starredList starred file IDs
Returns an array of file IDs that the authenticated user has starred.
Responses
200— Array of starred file IDs401— Missing or invalid API token403— Insufficient permissions or organisation suspended429— Rate limit exceeded500— Internal server error
/files/{id}/starStar a file
Adds the file to the authenticated user's starred list. Returns 409 if already starred.
Parameters
idpath, requiredFile ID
Responses
201— File starred401— Missing or invalid API token403— Insufficient permissions or organisation suspended404— Resource not found409— File is already starred429— Rate limit exceeded500— Internal server error
/files/{id}/starUnstar a file
Removes the file from the authenticated user's starred list.
Parameters
idpath, requiredFile ID
Responses
204— File unstarred401— Missing or invalid API token403— Insufficient permissions or organisation suspended404— Resource not found429— Rate limit exceeded500— Internal server error
/files/{id}/restoreRestore a soft-deleted file
Restores a file from trash by clearing `deleted_at` and setting `is_active` to true.
Parameters
idpath, requiredFile ID
Responses
204— File restored401— Missing or invalid API token403— Insufficient permissions or organisation suspended404— Resource not found429— Rate limit exceeded500— Internal server error
/files/{id}/download-urlGet a signed download URL
Returns a signed URL for downloading the file. The URL expires after 5 minutes (300 seconds).
Parameters
idpath, requiredFile ID
Responses
200— Signed download URL401— Missing or invalid API token403— Insufficient permissions or organisation suspended404— Resource not found429— Rate limit exceeded500— Internal server error
Folders
Organise files into folders
/foldersList folders
Returns all folders for the authenticated organisation, each with a file count.
Responses
200— List of folders401— Missing or invalid API token403— Insufficient permissions or organisation suspended429— Rate limit exceeded500— Internal server error
/foldersCreate a folder
Creates a new folder. The slug is auto-generated from the name.
Body FolderCreate
Responses
201— Folder created400— Validation error401— Missing or invalid API token403— Insufficient permissions or organisation suspended429— Rate limit exceeded500— Internal server error
/folders/{id}Get folder details
Returns a single folder with its file count.
Parameters
idpath, requiredFolder ID
Responses
200— Folder details401— Missing or invalid API token403— Insufficient permissions or organisation suspended404— Resource not found429— Rate limit exceeded500— Internal server error
/folders/{id}Update a folder
Updates folder name, description, or visibility. At least one field is required.
Body FolderUpdate
Parameters
idpath, requiredFolder ID
Responses
200— Folder updated400— Validation error401— Missing or invalid API token403— Insufficient permissions or organisation suspended404— Resource not found429— Rate limit exceeded500— Internal server error
/folders/{id}Delete a folder
Permanently deletes a folder. Files in the folder are unlinked (moved to root), not deleted.
Parameters
idpath, requiredFolder ID
Responses
204— Folder deleted401— Missing or invalid API token403— Insufficient permissions or organisation suspended404— Resource not found429— Rate limit exceeded500— Internal server error
Leads
View and export captured leads
/files/{id}/leadsList leads for a file
Returns a paginated list of leads captured for a specific file.
Parameters
idpath, requiredFile IDpagequeryPage number (1-based)per_pagequeryItems per page (max 100)
Responses
200— Paginated list of leads401— Missing or invalid API token403— Insufficient permissions or organisation suspended404— Resource not found429— Rate limit exceeded500— Internal server error
/leadsList leads
Returns a paginated list of all leads across the organisation. Optionally filter by file ID.
Parameters
pagequeryPage number (1-based)per_pagequeryItems per page (max 100)file_idqueryFilter leads by file ID
Responses
200— Paginated list of leads401— Missing or invalid API token403— Insufficient permissions or organisation suspended429— Rate limit exceeded500— Internal server error
/leads/{id}Delete a lead
Permanently deletes a lead record.
Parameters
idpath, requiredLead ID
Responses
204— Lead deleted401— Missing or invalid API token403— Insufficient permissions or organisation suspended404— Resource not found429— Rate limit exceeded500— Internal server error
/leads/exportExport leads as CSV
Downloads all leads as a CSV file. Limited to 10,000 records per export.
Responses
200— CSV file download401— Missing or invalid API token403— Insufficient permissions or organisation suspended429— Rate limit exceeded500— Internal server error
Analytics
View counts, lead stats, and trends
/analytics/overviewGet analytics overview
Returns aggregate statistics for the entire organisation.
Responses
200— Organisation-wide analytics401— Missing or invalid API token403— Insufficient permissions or organisation suspended429— Rate limit exceeded500— Internal server error
/analytics/files/{id}Get file analytics
Returns detailed analytics for a specific file, including views by date.
Parameters
idpath, requiredFile ID
Responses
200— File analytics401— Missing or invalid API token403— Insufficient permissions or organisation suspended404— Resource not found429— Rate limit exceeded500— Internal server error
/analytics/viewsGet views time series
Returns view counts aggregated by date for a given period. Optionally filter to a specific file.
Parameters
periodqueryTime period for the datafile_idqueryFilter to a specific file
Responses
200— Views time series401— Missing or invalid API token403— Insufficient permissions or organisation suspended429— Rate limit exceeded500— Internal server error
/analytics/top-filesTop files by views
Returns the top N files ranked by total views. Useful for identifying the most popular content.
Parameters
limitqueryNumber of files to return (max 20)
Responses
200— Top files by view count401— Missing or invalid API token403— Insufficient permissions or organisation suspended429— Rate limit exceeded500— Internal server error
/analytics/activityRecent team upload activity
Returns a summary of recent upload activity grouped by team member.
Responses
200— Team upload activity401— Missing or invalid API token403— Insufficient permissions or organisation suspended429— Rate limit exceeded500— Internal server error
Team
List team members and their activity
/teamList team members
Returns all members of the authenticated organisation.
Responses
200— List of team members401— Missing or invalid API token403— Insufficient permissions or organisation suspended429— Rate limit exceeded500— Internal server error
/team/inviteInvite a member by email
Sends an invitation to join the organisation. The invitee receives an email with a magic link. Defaults to the `member` role if not specified.
Body InviteMember
Responses
201— Invitation sent400— Validation error401— Missing or invalid API token403— Insufficient permissions or organisation suspended429— Rate limit exceeded500— Internal server error
/team/{userId}/statsGet team member stats
Returns activity statistics for a specific team member.
Parameters
userIdpath, requiredUser ID
Responses
200— Member statistics401— Missing or invalid API token403— Insufficient permissions or organisation suspended404— Resource not found429— Rate limit exceeded500— Internal server error
Organisation
Organisation settings and configuration
/orgGet organisation settings
Returns the full organisation object for the authenticated team.
Responses
200— Organisation settings401— Missing or invalid API token403— Insufficient permissions or organisation suspended429— Rate limit exceeded500— Internal server error
/orgUpdate organisation settings
Updates organisation settings such as name and brand colour. At least one field is required.
Body OrgUpdate
Responses
200— Organisation updated400— Validation error401— Missing or invalid API token403— Insufficient permissions or organisation suspended429— Rate limit exceeded500— Internal server error
Tokens
Manage API tokens programmatically
/tokensList API tokens
Returns all API tokens for the organisation. Token hashes are never exposed — only the prefix is shown.
Responses
200— List of tokens401— Missing or invalid API token403— Insufficient permissions or organisation suspended429— Rate limit exceeded500— Internal server error
/tokensCreate an API token
Creates a new API token. The full token value is returned **only once** in the response — store it securely, as it cannot be retrieved again.
Body TokenCreate
Responses
201— Token created (full token shown once)400— Validation error401— Missing or invalid API token403— Insufficient permissions or organisation suspended429— Rate limit exceeded500— Internal server error
/tokens/{id}Revoke an API token
Soft-revokes a token by setting `revoked_at`. Returns 409 if the token is already revoked.
Parameters
idpath, requiredToken ID
Responses
204— Token revoked401— Missing or invalid API token403— Insufficient permissions or organisation suspended404— Resource not found409— Token already revoked429— Rate limit exceeded500— Internal server error