{"openapi":"3.1.0","info":{"title":"GateDocs API","version":"1.0","description":"REST API for GateDocs — secure document sharing with built-in lead capture and analytics.\n\n## Authentication\nAll requests require a Bearer token in the `Authorization` header:\n```\nAuthorization: Bearer gd_live_<token>\n```\nCreate tokens in **Settings > API**, or via `POST /tokens`.\n\n## Plan Requirements\nAPI access requires a **Business** or **Enterprise** plan.\n\n## Rate Limiting\n- **Business:** 1,000 requests/minute\n- **Enterprise:** 5,000 requests/minute\n\nRate limit headers are included on every response:\n- `X-RateLimit-Limit` — max requests per window\n- `X-RateLimit-Remaining` — remaining requests\n- `X-RateLimit-Reset` — Unix timestamp when window resets\n\n## Response Format\n**Success:** `{ \"data\": ..., \"meta\": { \"page\", \"per_page\", \"total\" } }`\n\n**Error:** `{ \"error\": { \"message\": \"...\", \"code\": \"ERROR_CODE\" } }`\n\n## Scopes\nTokens are scoped to specific permissions:\n\n| Scope | Description |\n|-------|-------------|\n| `files:read` | Read files |\n| `files:write` | Create, update, and delete files |\n| `leads:read` | Read leads |\n| `leads:write` | Delete leads |\n| `folders:read` | Read folders |\n| `folders:write` | Create, update, and delete folders |\n| `analytics:read` | Read analytics data |\n| `team:read` | Read team members |\n| `tokens:read` | List API tokens |\n| `tokens:write` | Create and revoke API tokens |\n| `team:write` | Invite and manage team members |\n| `org:read` | Read organisation settings |\n| `org:write` | Update organisation settings |\n"},"servers":[{"url":"https://gatedocs.io/api/v1","description":"Production"},{"url":"http://localhost:3000/api/v1","description":"Local development"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Files","description":"Upload, manage, and share files"},{"name":"Folders","description":"Organise files into folders"},{"name":"Leads","description":"View and export captured leads"},{"name":"Analytics","description":"View counts, lead stats, and trends"},{"name":"Team","description":"List team members and their activity"},{"name":"Organisation","description":"Organisation settings and configuration"},{"name":"Tokens","description":"Manage API tokens programmatically"}],"paths":{"/files":{"get":{"operationId":"listFiles","summary":"List files","description":"Returns a paginated list of files for the authenticated organisation. Supports filtering by folder and active status, with sorting options.","tags":["Files"],"security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/PerPageParam"},{"name":"folder_id","in":"query","description":"Filter files by folder ID","schema":{"type":"string","format":"uuid"}},{"name":"is_active","in":"query","description":"Filter by active status","schema":{"type":"boolean"}},{"name":"sort","in":"query","description":"Sort field","schema":{"type":"string","enum":["created_at","filename","download_count"],"default":"created_at"}},{"name":"order","in":"query","description":"Sort order","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}}],"responses":{"200":{"description":"Paginated list of files","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/File"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"operationId":"createFile","summary":"Create a file record","description":"Creates a new file record with the specified metadata and protection settings. The file must be uploaded separately to Supabase Storage.","tags":["Files"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileCreate"}}}},"responses":{"201":{"description":"File created","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/File"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/files/{id}":{"get":{"operationId":"getFile","summary":"Get file details","description":"Returns a single file with view count and lead count.","tags":["Files"],"security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/FileId"}],"responses":{"200":{"description":"File details","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FileDetail"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"patch":{"operationId":"updateFile","summary":"Update a file","description":"Updates file metadata and protection settings. All fields are optional.","tags":["Files"],"security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/FileId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileUpdate"}}}},"responses":{"200":{"description":"File updated","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/File"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"delete":{"operationId":"deleteFile","summary":"Delete a file","description":"Soft-deletes a file by setting `deleted_at` and `is_active` to false. The file can be restored from trash.","tags":["Files"],"security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/FileId"}],"responses":{"204":{"description":"File deleted","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/files/starred":{"get":{"operationId":"listStarredFiles","summary":"List starred file IDs","description":"Returns an array of file IDs that the authenticated user has starred.","tags":["Files"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Array of starred file IDs","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"string","format":"uuid"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/files/{id}/star":{"post":{"operationId":"starFile","summary":"Star a file","description":"Adds the file to the authenticated user's starred list. Returns 409 if already starred.","tags":["Files"],"security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/FileId"}],"responses":{"201":{"description":"File starred","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"File is already starred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"delete":{"operationId":"unstarFile","summary":"Unstar a file","description":"Removes the file from the authenticated user's starred list.","tags":["Files"],"security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/FileId"}],"responses":{"204":{"description":"File unstarred","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/files/{id}/restore":{"post":{"operationId":"restoreFile","summary":"Restore a soft-deleted file","description":"Restores a file from trash by clearing `deleted_at` and setting `is_active` to true.","tags":["Files"],"security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/FileId"}],"responses":{"204":{"description":"File restored","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/files/{id}/download-url":{"get":{"operationId":"getFileDownloadUrl","summary":"Get a signed download URL","description":"Returns a signed URL for downloading the file. The URL expires after 5 minutes (300 seconds).","tags":["Files"],"security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/FileId"}],"responses":{"200":{"description":"Signed download URL","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DownloadUrl"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/files/{id}/leads":{"get":{"operationId":"listFileLeads","summary":"List leads for a file","description":"Returns a paginated list of leads captured for a specific file.","tags":["Leads"],"security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/FileId"},{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/PerPageParam"}],"responses":{"200":{"description":"Paginated list of leads","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Lead"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/folders":{"get":{"operationId":"listFolders","summary":"List folders","description":"Returns all folders for the authenticated organisation, each with a file count.","tags":["Folders"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"List of folders","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Folder"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"operationId":"createFolder","summary":"Create a folder","description":"Creates a new folder. The slug is auto-generated from the name.","tags":["Folders"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FolderCreate"}}}},"responses":{"201":{"description":"Folder created","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Folder"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/folders/{id}":{"get":{"operationId":"getFolder","summary":"Get folder details","description":"Returns a single folder with its file count.","tags":["Folders"],"security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/FolderId"}],"responses":{"200":{"description":"Folder details","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Folder"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"patch":{"operationId":"updateFolder","summary":"Update a folder","description":"Updates folder name, description, or visibility. At least one field is required.","tags":["Folders"],"security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/FolderId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FolderUpdate"}}}},"responses":{"200":{"description":"Folder updated","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Folder"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"delete":{"operationId":"deleteFolder","summary":"Delete a folder","description":"Permanently deletes a folder. Files in the folder are unlinked (moved to root), not deleted.","tags":["Folders"],"security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/FolderId"}],"responses":{"204":{"description":"Folder deleted","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/leads":{"get":{"operationId":"listLeads","summary":"List leads","description":"Returns a paginated list of all leads across the organisation. Optionally filter by file ID.","tags":["Leads"],"security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/PerPageParam"},{"name":"file_id","in":"query","description":"Filter leads by file ID","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Paginated list of leads","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/LeadWithFile"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/leads/{id}":{"delete":{"operationId":"deleteLead","summary":"Delete a lead","description":"Permanently deletes a lead record.","tags":["Leads"],"security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/LeadId"}],"responses":{"204":{"description":"Lead deleted","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/leads/export":{"get":{"operationId":"exportLeads","summary":"Export leads as CSV","description":"Downloads all leads as a CSV file. Limited to 10,000 records per export.","tags":["Leads"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"CSV file download","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Content-Disposition":{"schema":{"type":"string"},"description":"Attachment filename, e.g. `attachment; filename=\"leads-export.csv\"`"}},"content":{"text/csv":{"schema":{"type":"string","description":"CSV with columns email, name, company, job_title, filename, downloaded_at"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/analytics/overview":{"get":{"operationId":"getAnalyticsOverview","summary":"Get analytics overview","description":"Returns aggregate statistics for the entire organisation.","tags":["Analytics"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Organisation-wide analytics","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AnalyticsOverview"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/analytics/files/{id}":{"get":{"operationId":"getFileAnalytics","summary":"Get file analytics","description":"Returns detailed analytics for a specific file, including views by date.","tags":["Analytics"],"security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/FileId"}],"responses":{"200":{"description":"File analytics","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FileAnalytics"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/analytics/views":{"get":{"operationId":"getViewsTimeSeries","summary":"Get views time series","description":"Returns view counts aggregated by date for a given period. Optionally filter to a specific file.","tags":["Analytics"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"period","in":"query","description":"Time period for the data","schema":{"type":"string","enum":["7d","30d","90d"],"default":"7d"}},{"name":"file_id","in":"query","description":"Filter to a specific file","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Views time series","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ViewsTimeSeries"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/analytics/top-files":{"get":{"operationId":"getTopFiles","summary":"Top files by views","description":"Returns the top N files ranked by total views. Useful for identifying the most popular content.","tags":["Analytics"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","description":"Number of files to return (max 20)","schema":{"type":"integer","minimum":1,"maximum":20,"default":5}}],"responses":{"200":{"description":"Top files by view count","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TopFile"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/analytics/activity":{"get":{"operationId":"getTeamActivity","summary":"Recent team upload activity","description":"Returns a summary of recent upload activity grouped by team member.","tags":["Analytics"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Team upload activity","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ActivityEntry"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/team":{"get":{"operationId":"listTeamMembers","summary":"List team members","description":"Returns all members of the authenticated organisation.","tags":["Team"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"List of team members","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"members":{"type":"array","items":{"$ref":"#/components/schemas/TeamMember"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/team/invite":{"post":{"operationId":"inviteTeamMember","summary":"Invite a member by email","description":"Sends an invitation to join the organisation. The invitee receives an email with a magic link. Defaults to the `member` role if not specified.","tags":["Team"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InviteMember"}}}},"responses":{"201":{"description":"Invitation sent","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/team/{userId}/stats":{"get":{"operationId":"getTeamMemberStats","summary":"Get team member stats","description":"Returns activity statistics for a specific team member.","tags":["Team"],"security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/UserId"}],"responses":{"200":{"description":"Member statistics","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MemberStats"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/org":{"get":{"operationId":"getOrgSettings","summary":"Get organisation settings","description":"Returns the full organisation object for the authenticated team.","tags":["Organisation"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Organisation settings","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OrgSettings"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"patch":{"operationId":"updateOrgSettings","summary":"Update organisation settings","description":"Updates organisation settings such as name and brand colour. At least one field is required.","tags":["Organisation"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgUpdate"}}}},"responses":{"200":{"description":"Organisation updated","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OrgSettings"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/tokens":{"get":{"operationId":"listTokens","summary":"List API tokens","description":"Returns all API tokens for the organisation. Token hashes are never exposed — only the prefix is shown.","tags":["Tokens"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"List of tokens","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"tokens":{"type":"array","items":{"$ref":"#/components/schemas/Token"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"operationId":"createToken","summary":"Create an API token","description":"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.\n","tags":["Tokens"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenCreate"}}}},"responses":{"201":{"description":"Token created (full token shown once)","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TokenCreated"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/tokens/{id}":{"delete":{"operationId":"revokeToken","summary":"Revoke an API token","description":"Soft-revokes a token by setting `revoked_at`. Returns 409 if the token is already revoked.","tags":["Tokens"],"security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/TokenId"}],"responses":{"204":{"description":"Token revoked","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Token already revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"gd_live_<hex>","description":"API token created in Settings > API or via POST /tokens"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable error message"},"code":{"type":"string","description":"Machine-readable error code"}},"required":["message","code"]}},"required":["error"]},"PaginationMeta":{"type":"object","properties":{"page":{"type":"integer","description":"Current page number","example":1},"per_page":{"type":"integer","description":"Items per page","example":50},"total":{"type":"integer","description":"Total number of items","example":127}},"required":["page","per_page","total"]},"File":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid"},"uploaded_by":{"type":"string","format":"uuid","nullable":true},"filename":{"type":"string","example":"Q4-Report.pdf"},"storage_path":{"type":"string"},"slug":{"type":"string","example":"q4-report"},"protection_type":{"type":"string","enum":["lead_capture","password"]},"form_fields":{"type":"array","items":{"type":"string","enum":["email","name","company","job_title"]}},"is_active":{"type":"boolean"},"page_title":{"type":"string","nullable":true},"page_description":{"type":"string","nullable":true},"folder_id":{"type":"string","format":"uuid","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"download_limit":{"type":"integer","nullable":true},"download_count":{"type":"integer"},"view_only":{"type":"boolean"},"expiry_reason":{"type":"string","enum":["manual","time","downloads"],"nullable":true},"page_count":{"type":"integer","nullable":true},"deleted_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"FileCreate":{"type":"object","required":["filename"],"properties":{"filename":{"type":"string","description":"Name of the file","example":"Q4-Report.pdf"},"protection_type":{"type":"string","enum":["lead_capture","password"],"default":"lead_capture","description":"Defaults to lead_capture. Lead capture is available on every plan, but Free is capped at 3 gated links (a non-deleted file or space with protection_type lead_capture); Pro and above are unlimited. Free-plan orgs that omit this field, or explicitly request lead_capture, once at the cap receive password protection instead — a `password` must be supplied in that case, or the request is rejected with 400. Upgrade to Pro or above for unlimited gated links."},"form_fields":{"type":"array","items":{"type":"string","enum":["email","name","company","job_title"]},"default":["email"]},"password":{"type":"string","description":"Password for password-protected files (stored as bcrypt hash)"},"page_title":{"type":"string","description":"Custom title shown on the download page"},"page_description":{"type":"string","description":"Custom description shown on the download page"},"folder_id":{"type":"string","format":"uuid","description":"Folder to place the file in"},"expires_at":{"type":"string","format":"date-time","description":"Expiry date for the file link"},"download_limit":{"type":"integer","description":"Maximum number of downloads allowed"},"view_only":{"type":"boolean","default":false,"description":"If true, visitors can view but not download"}}},"FileUpdate":{"type":"object","properties":{"page_title":{"type":"string","nullable":true},"page_description":{"type":"string","nullable":true},"is_active":{"type":"boolean"},"protection_type":{"type":"string","enum":["lead_capture","password"]},"form_fields":{"type":"array","items":{"type":"string","enum":["email","name","company","job_title"]}},"expires_at":{"type":"string","format":"date-time","nullable":true},"download_limit":{"type":"integer","nullable":true},"view_only":{"type":"boolean"},"folder_id":{"type":"string","format":"uuid","nullable":true},"password":{"type":"string","description":"New password (stored as bcrypt hash)"}}},"FileDetail":{"allOf":[{"$ref":"#/components/schemas/File"},{"type":"object","properties":{"view_count":{"type":"integer","description":"Total number of views"},"lead_count":{"type":"integer","description":"Total number of leads captured"}}}]},"Folder":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid"},"name":{"type":"string","example":"Sales Collateral"},"slug":{"type":"string","example":"sales-collateral"},"description":{"type":"string","nullable":true},"visibility":{"type":"string","enum":["public","private"]},"created_by":{"type":"string","format":"uuid"},"file_count":{"type":"integer","description":"Number of files in this folder"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"FolderCreate":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Folder name","example":"Sales Collateral"},"description":{"type":"string","description":"Folder description"},"visibility":{"type":"string","enum":["public","private"],"default":"private"}}},"FolderUpdate":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"visibility":{"type":"string","enum":["public","private"]}}},"Lead":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"file_id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"name":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"job_title":{"type":"string","nullable":true},"downloaded_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"LeadWithFile":{"allOf":[{"$ref":"#/components/schemas/Lead"},{"type":"object","properties":{"files":{"type":"object","description":"Associated file information","properties":{"id":{"type":"string","format":"uuid"},"filename":{"type":"string"},"org_id":{"type":"string","format":"uuid"}}}}}]},"Token":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","example":"CI/CD Pipeline"},"token_prefix":{"type":"string","description":"First 16 characters of the token","example":"gd_live_a1b2c3d4"},"scopes":{"type":"array","items":{"type":"string","enum":["files:read","files:write","leads:read","leads:write","folders:read","folders:write","analytics:read","team:read","team:write","tokens:read","tokens:write","org:read","org:write"]}},"created_at":{"type":"string","format":"date-time"},"last_used_at":{"type":"string","format":"date-time","nullable":true},"revoked_at":{"type":"string","format":"date-time","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true}}},"TokenCreate":{"type":"object","required":["name","scopes"],"properties":{"name":{"type":"string","description":"Human-readable name for the token","example":"CI/CD Pipeline"},"scopes":{"type":"array","minItems":1,"items":{"type":"string","enum":["files:read","files:write","leads:read","leads:write","folders:read","folders:write","analytics:read","team:read","team:write","tokens:read","tokens:write","org:read","org:write"]},"description":"Permissions granted to this token"},"expires_at":{"type":"string","format":"date-time","description":"Optional expiry date"}}},"TokenCreated":{"allOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"token":{"type":"string","description":"Full token value — shown only once. Store it securely.","example":"gd_live_a1b2c3d4e5f6..."},"token_prefix":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time","nullable":true}}}]},"AnalyticsOverview":{"type":"object","properties":{"total_files":{"type":"integer"},"active_files":{"type":"integer"},"total_views":{"type":"integer"},"total_leads":{"type":"integer"},"total_downloads":{"type":"integer"},"storage_bytes":{"type":"integer","description":"Total storage used in bytes"}}},"FileAnalytics":{"type":"object","properties":{"file_id":{"type":"string","format":"uuid"},"filename":{"type":"string"},"total_views":{"type":"integer"},"total_leads":{"type":"integer"},"download_count":{"type":"integer"},"views_by_date":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"2026-02-01"},"count":{"type":"integer"}}}}}},"ViewsTimeSeries":{"type":"object","properties":{"period":{"type":"string","enum":["7d","30d","90d"]},"views":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"count":{"type":"integer"}}}},"total":{"type":"integer"}}},"TeamMember":{"type":"object","properties":{"user_id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"name":{"type":"string","nullable":true},"role":{"type":"string","enum":["admin","member"]},"invited_at":{"type":"string","format":"date-time"},"joined_at":{"type":"string","format":"date-time","nullable":true}}},"MemberStats":{"type":"object","properties":{"user_id":{"type":"string","format":"uuid"},"files_uploaded":{"type":"integer"},"total_views":{"type":"integer"},"total_leads":{"type":"integer"}}},"DownloadUrl":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Signed download URL"},"expires_in":{"type":"integer","description":"Seconds until the URL expires","example":300}}},"TopFile":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"filename":{"type":"string"},"views":{"type":"integer"},"leads":{"type":"integer"}},"required":["id","filename","views","leads"]},"ActivityEntry":{"type":"object","properties":{"userId":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"filesUploaded":{"type":"integer"}},"required":["userId","email","filesUploaded"]},"OrgSettings":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"logo_url":{"type":"string","nullable":true},"brand_color":{"type":"string"},"plan_slug":{"type":"string","enum":["free","pro","business","enterprise"]},"custom_domain":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}},"required":["id","name","brand_color","plan_slug","created_at"]},"OrgUpdate":{"type":"object","properties":{"name":{"type":"string"},"brand_color":{"type":"string"}},"minProperties":1},"InviteMember":{"type":"object","properties":{"email":{"type":"string","format":"email"},"role":{"type":"string","enum":["admin","member"],"default":"member"}},"required":["email"]}},"parameters":{"PageParam":{"name":"page","in":"query","description":"Page number (1-based)","schema":{"type":"integer","minimum":1,"default":1}},"PerPageParam":{"name":"per_page","in":"query","description":"Items per page (max 100)","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},"FileId":{"name":"id","in":"path","required":true,"description":"File ID","schema":{"type":"string","format":"uuid"}},"FolderId":{"name":"id","in":"path","required":true,"description":"Folder ID","schema":{"type":"string","format":"uuid"}},"LeadId":{"name":"id","in":"path","required":true,"description":"Lead ID","schema":{"type":"string","format":"uuid"}},"TokenId":{"name":"id","in":"path","required":true,"description":"Token ID","schema":{"type":"string","format":"uuid"}},"UserId":{"name":"userId","in":"path","required":true,"description":"User ID","schema":{"type":"string","format":"uuid"}}},"responses":{"Unauthorized":{"description":"Missing or invalid API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Invalid or missing API token","code":"UNAUTHORIZED"}}}}},"Forbidden":{"description":"Insufficient permissions or organisation suspended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Insufficient permissions","code":"FORBIDDEN"}}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Resource not found","code":"NOT_FOUND"}}}}},"RateLimited":{"description":"Rate limit exceeded","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED"}}}}},"InternalError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Internal server error","code":"INTERNAL_ERROR"}}}}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Maximum requests per window"},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Remaining requests in current window"},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix timestamp when window resets"}}}}