{ "openapi": "3.1.0", "info": { "title": "imboard Public API", "version": "1.0.0", "summary": "REST API for board management, meetings, documents, reports, and dashboards", "description": "The imboard REST API for managing boards, meetings, documents, reports, and dashboards.\n\n## Authentication\nAll endpoints require a Bearer token in the `Authorization` header.\nUse a Personal Access Token (PAT) prefixed with `imb_pat_` or a browser JWT.\nSee [authentication docs](authentication.md) for details.\n\n## Conventions\n- Single resources are wrapped in `{ \"data\": { ... } }`\n- Collections are wrapped in `{ \"data\": [...], \"meta\": { ... } }`\n- Errors use a standard envelope: `{ \"error\": { ... } }`\n- Every resource includes an `object` field for type disambiguation\n- All IDs are opaque strings\n- Timestamps are ISO-8601 strings\n", "contact": { "name": "imboard Support", "url": "https://imboard.ai" }, "license": { "name": "Proprietary", "identifier": "LicenseRef-scancode-proprietary-license" } }, "servers": [ { "url": "https://app.imboard.ai/api/v1", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Me", "description": "Authenticated user identity" }, { "name": "Boards", "description": "Board management" }, { "name": "Members", "description": "Board membership and invitations" }, { "name": "Meetings", "description": "Board meeting lifecycle" }, { "name": "Documents", "description": "Board document management" }, { "name": "Reports", "description": "Board report generation and retrieval" }, { "name": "Dashboards", "description": "Dashboard configurations (nested under reports)" } ], "paths": { "/me": { "get": { "summary": "Get current user", "description": "Returns the profile of the user associated with the provided token.", "operationId": "getMe", "tags": [ "Me" ], "responses": { "200": { "description": "Current user profile", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/User" } } }, "example": { "data": { "object": "user", "id": "507f1f77bcf86cd799439011", "email": "jane@example.com", "firstName": "Jane", "lastName": "Doe", "fullName": "Jane Doe", "avatarUrl": "https://example.com/avatar.jpg", "timezone": "America/New_York", "language": "en", "createdAt": "2025-01-15T10:30:00.000Z", "updatedAt": "2025-06-01T14:00:00.000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/boards": { "get": { "summary": "List boards", "description": "Returns a paginated list of boards the authenticated user has access to.", "operationId": "listBoards", "tags": [ "Boards" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Order" } ], "responses": { "200": { "description": "Paginated board list", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Board" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "data": [ { "object": "board", "id": "60d5ec49f1a2c8b1f8e4e1a1", "name": "Acme Corp Board", "description": "Main governance board", "inviteCodeEnabled": true, "billingState": "PAID_ACTIVE", "myRole": "admin", "createdAt": "2025-01-10T08:00:00.000Z", "updatedAt": "2025-06-15T12:00:00.000Z" } ], "meta": { "nextCursor": "eyJpZCI6IjYwZDVlYzQ5ZjFhMmM4YjFmOGU0ZTFhMiJ9", "hasMore": true } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" } } } }, "/boards/{boardId}": { "parameters": [ { "$ref": "#/components/parameters/BoardId" } ], "get": { "summary": "Get a board", "operationId": "getBoard", "tags": [ "Boards" ], "responses": { "200": { "description": "Board details", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Board" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/boards/{boardId}/members": { "parameters": [ { "$ref": "#/components/parameters/BoardId" } ], "get": { "summary": "List board members", "operationId": "listMembers", "tags": [ "Members" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Order" } ], "responses": { "200": { "description": "Paginated member list", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BoardMember" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/boards/{boardId}/members/{memberId}": { "parameters": [ { "$ref": "#/components/parameters/BoardId" }, { "$ref": "#/components/parameters/MemberId" } ], "get": { "summary": "Get a board member", "operationId": "getMember", "tags": [ "Members" ], "responses": { "200": { "description": "Member details", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/BoardMember" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/boards/{boardId}/meetings": { "parameters": [ { "$ref": "#/components/parameters/BoardId" } ], "get": { "summary": "List meetings", "description": "Returns a paginated list of meetings for the given board.", "operationId": "listMeetings", "tags": [ "Meetings" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Order" } ], "responses": { "200": { "description": "Paginated meeting list", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Meeting" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "data": [ { "object": "meeting", "id": "60d5ec49f1a2c8b1f8e4e1b1", "boardId": "60d5ec49f1a2c8b1f8e4e1a1", "title": "Q2 Board Review", "status": "scheduled", "locationType": "virtual", "location": null, "virtualMeetingUrl": "https://zoom.us/j/123456789", "startTime": "2025-07-15T14:00:00.000Z", "endTime": "2025-07-15T16:00:00.000Z", "createdByUserId": "507f1f77bcf86cd799439011", "createdAt": "2025-06-01T10:00:00.000Z", "updatedAt": "2025-06-10T09:30:00.000Z" } ], "meta": { "nextCursor": null, "hasMore": false } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "summary": "Create a meeting", "operationId": "createMeeting", "tags": [ "Meetings" ], "requestBody": { "description": "Meeting details", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "description": "Meeting title (max 200 characters)", "maxLength": 200 }, "status": { "type": "string", "description": "Meeting lifecycle status", "examples": [ "draft", "scheduled", "in_progress", "completed" ] }, "locationType": { "type": [ "string", "null" ], "description": "Location type", "examples": [ "virtual", "in_person", "hybrid" ] }, "location": { "type": [ "string", "null" ], "description": "Physical location (max 255 characters)", "maxLength": 255 }, "virtualMeetingUrl": { "type": [ "string", "null" ], "description": "Virtual meeting URL (max 255 characters)", "maxLength": 255 }, "startTime": { "type": [ "string", "null" ], "description": "Meeting start time", "format": "date-time" }, "endTime": { "type": [ "string", "null" ], "description": "Meeting end time (must be after startTime if both provided)", "format": "date-time" } } }, "example": { "title": "Q3 Board Review", "locationType": "virtual", "virtualMeetingUrl": "https://zoom.us/j/987654321", "startTime": "2025-10-15T14:00:00.000Z", "endTime": "2025-10-15T16:00:00.000Z" } } } }, "responses": { "201": { "description": "Meeting created", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Meeting" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/boards/{boardId}/meetings/{meetingId}": { "parameters": [ { "$ref": "#/components/parameters/BoardId" }, { "$ref": "#/components/parameters/MeetingId" } ], "get": { "summary": "Get a meeting", "operationId": "getMeeting", "tags": [ "Meetings" ], "responses": { "200": { "description": "Meeting details", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Meeting" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "summary": "Update a meeting", "operationId": "updateMeeting", "tags": [ "Meetings" ], "requestBody": { "description": "Fields to update (at least one required)", "required": true, "content": { "application/json": { "schema": { "type": "object", "minProperties": 1, "properties": { "title": { "type": "string", "description": "Meeting title (max 200 characters)", "maxLength": 200 }, "status": { "type": "string", "description": "Meeting lifecycle status", "examples": [ "draft", "scheduled", "in_progress", "completed" ] }, "locationType": { "type": [ "string", "null" ], "description": "Location type", "examples": [ "virtual", "in_person", "hybrid" ] }, "location": { "type": [ "string", "null" ], "description": "Physical location (max 255 characters)", "maxLength": 255 }, "virtualMeetingUrl": { "type": [ "string", "null" ], "description": "Virtual meeting URL (max 255 characters)", "maxLength": 255 }, "startTime": { "type": [ "string", "null" ], "description": "Meeting start time", "format": "date-time" }, "endTime": { "type": [ "string", "null" ], "description": "Meeting end time (must be after startTime if both provided)", "format": "date-time" } } }, "example": { "title": "Q3 Board Review (Updated)", "status": "scheduled" } } } }, "responses": { "200": { "description": "Meeting updated", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Meeting" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/boards/{boardId}/documents": { "parameters": [ { "$ref": "#/components/parameters/BoardId" } ], "get": { "summary": "List documents", "operationId": "listDocuments", "tags": [ "Documents" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Order" } ], "responses": { "200": { "description": "Paginated document list", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Document" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/boards/{boardId}/documents/{documentId}": { "parameters": [ { "$ref": "#/components/parameters/BoardId" }, { "$ref": "#/components/parameters/DocumentId" } ], "get": { "summary": "Get a document", "operationId": "getDocument", "tags": [ "Documents" ], "responses": { "200": { "description": "Document details", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Document" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/boards/{boardId}/reports": { "parameters": [ { "$ref": "#/components/parameters/BoardId" } ], "get": { "summary": "List reports", "operationId": "listReports", "tags": [ "Reports" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Order" } ], "responses": { "200": { "description": "Paginated report list", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Report" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/boards/{boardId}/reports/{reportId}": { "parameters": [ { "$ref": "#/components/parameters/BoardId" }, { "$ref": "#/components/parameters/ReportId" } ], "get": { "summary": "Get a report", "operationId": "getReport", "tags": [ "Reports" ], "responses": { "200": { "description": "Report details", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Report" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/boards/{boardId}/reports/{reportId}/dashboards": { "parameters": [ { "$ref": "#/components/parameters/BoardId" }, { "$ref": "#/components/parameters/ReportId" } ], "get": { "summary": "List dashboards", "operationId": "listDashboards", "tags": [ "Dashboards" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Order" } ], "responses": { "200": { "description": "Paginated dashboard list", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Dashboard" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/boards/{boardId}/reports/{reportId}/dashboards/{dashboardId}": { "parameters": [ { "$ref": "#/components/parameters/BoardId" }, { "$ref": "#/components/parameters/ReportId" }, { "$ref": "#/components/parameters/DashboardId" } ], "get": { "summary": "Get a dashboard", "operationId": "getDashboard", "tags": [ "Dashboards" ], "responses": { "200": { "description": "Dashboard details", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Dashboard" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "PAT or JWT", "description": "Personal access token (`imb_pat_...`) or browser session JWT.\nPATs are recommended for programmatic access.\n" } }, "schemas": { "User": { "type": "object", "description": "Authenticated user profile", "required": [ "object", "id", "email", "fullName", "createdAt", "updatedAt" ], "properties": { "object": { "type": "string", "const": "user" }, "id": { "type": "string", "description": "Opaque user ID" }, "email": { "type": "string", "format": "email" }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "fullName": { "type": "string" }, "avatarUrl": { "type": [ "string", "null" ], "format": "uri" }, "timezone": { "type": [ "string", "null" ], "description": "IANA timezone identifier", "examples": [ "America/New_York", "Europe/London" ] }, "language": { "type": [ "string", "null" ], "description": "ISO 639-1 language code", "examples": [ "en", "he" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "Board": { "type": "object", "description": "A governance board", "required": [ "object", "id", "name", "inviteCodeEnabled", "billingState", "createdAt", "updatedAt" ], "properties": { "object": { "type": "string", "const": "board" }, "id": { "type": "string", "description": "Opaque board ID" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "inviteCodeEnabled": { "type": "boolean" }, "billingState": { "type": "string", "description": "Current billing status of the board", "examples": [ "TRIAL_ACTIVE", "PAID_ACTIVE", "PAST_DUE_GRACE" ] }, "myRole": { "type": [ "string", "null" ], "description": "The requesting user's role on this board", "examples": [ "owner", "admin", "guest" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "BoardMember": { "type": "object", "description": "A member of a board", "required": [ "object", "id", "userId", "boardId", "adminRole", "accessType", "boardPositions", "isInternalMgmt", "createdAt", "updatedAt" ], "properties": { "object": { "type": "string", "const": "board_member" }, "id": { "type": "string", "description": "Opaque membership ID" }, "userId": { "type": "string" }, "boardId": { "type": "string" }, "email": { "type": [ "string", "null" ], "format": "email" }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "adminRole": { "type": "string", "description": "Administrative role on the board" }, "accessType": { "type": "string", "description": "Access level type" }, "boardPositions": { "type": "array", "items": { "type": "string" }, "description": "Positions held on the board (e.g. Chair, Treasurer)" }, "isInternalMgmt": { "type": "boolean", "description": "Whether this member is internal management" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "Meeting": { "type": "object", "description": "A board meeting", "required": [ "object", "id", "boardId", "title", "status", "createdByUserId", "createdAt", "updatedAt" ], "properties": { "object": { "type": "string", "const": "meeting" }, "id": { "type": "string", "description": "Opaque meeting ID" }, "boardId": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "description": "Meeting lifecycle status", "examples": [ "draft", "scheduled", "in_progress", "completed" ] }, "locationType": { "type": [ "string", "null" ], "examples": [ "virtual", "in_person", "hybrid" ] }, "location": { "type": [ "string", "null" ], "description": "Physical location address" }, "virtualMeetingUrl": { "type": [ "string", "null" ], "format": "uri" }, "startTime": { "type": [ "string", "null" ], "format": "date-time" }, "endTime": { "type": [ "string", "null" ], "format": "date-time" }, "createdByUserId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "Document": { "type": "object", "description": "A board document", "required": [ "object", "id", "boardId", "title", "createdByUserId", "createdAt", "updatedAt" ], "properties": { "object": { "type": "string", "const": "document" }, "id": { "type": "string", "description": "Opaque document ID" }, "boardId": { "type": "string" }, "title": { "type": "string" }, "documentType": { "type": [ "string", "null" ], "description": "Type classification of the document" }, "meetingIds": { "type": "array", "items": { "type": "string" }, "description": "Associated meeting IDs, if linked to meetings" }, "latestVersionId": { "type": [ "string", "null" ], "description": "ID of the most recent document version" }, "mimeType": { "type": [ "string", "null" ], "description": "MIME type of the document content", "examples": [ "application/pdf", "text/html" ] }, "createdByUserId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "Report": { "type": "object", "description": "A board report", "required": [ "object", "id", "boardId", "title", "status", "createdByUserId", "createdAt", "updatedAt" ], "properties": { "object": { "type": "string", "const": "report" }, "id": { "type": "string", "description": "Opaque report ID" }, "boardId": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "description": "Report lifecycle status", "examples": [ "draft", "published" ] }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdByUserId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "Dashboard": { "type": "object", "description": "A dashboard configuration (nested under a report)", "required": [ "object", "id", "reportId", "dashboardType", "createdByUserId", "createdAt", "updatedAt" ], "properties": { "object": { "type": "string", "const": "dashboard" }, "id": { "type": "string", "description": "Opaque dashboard ID" }, "boardId": { "type": [ "string", "null" ] }, "reportId": { "type": "string" }, "dashboardType": { "type": "string", "description": "Type of dashboard" }, "title": { "type": [ "string", "null" ] }, "latestVersionId": { "type": [ "string", "null" ] }, "createdByUserId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "ListMeta": { "type": "object", "description": "Pagination metadata for collection responses", "required": [ "hasMore" ], "properties": { "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page. Null when no more results." }, "hasMore": { "type": "boolean", "description": "Whether more results exist beyond this page" } } }, "ErrorEnvelope": { "type": "object", "description": "Standard error response wrapper", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "status", "requestId" ], "properties": { "code": { "type": "string", "description": "Machine-readable error code", "examples": [ "UNAUTHENTICATED", "RESOURCE_NOT_FOUND", "INVALID_REQUEST_BODY", "RATE_LIMITED" ] }, "message": { "type": "string", "description": "Human-readable error description" }, "status": { "type": "integer", "description": "HTTP status code" }, "requestId": { "type": "string", "description": "Unique request identifier for debugging" }, "details": { "description": "Additional error context (validation errors, etc.)" } } } }, "example": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found.", "status": 404, "requestId": "req-abc123", "details": null } } } }, "parameters": { "BoardId": { "name": "boardId", "in": "path", "required": true, "description": "Opaque board identifier", "schema": { "type": "string" } }, "MemberId": { "name": "memberId", "in": "path", "required": true, "description": "Opaque board membership identifier", "schema": { "type": "string" } }, "MeetingId": { "name": "meetingId", "in": "path", "required": true, "description": "Opaque meeting identifier", "schema": { "type": "string" } }, "DocumentId": { "name": "documentId", "in": "path", "required": true, "description": "Opaque document identifier", "schema": { "type": "string" } }, "ReportId": { "name": "reportId", "in": "path", "required": true, "description": "Opaque report identifier", "schema": { "type": "string" } }, "DashboardId": { "name": "dashboardId", "in": "path", "required": true, "description": "Opaque dashboard identifier", "schema": { "type": "string" } }, "Limit": { "name": "limit", "in": "query", "description": "Maximum number of items to return (1-100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, "Cursor": { "name": "cursor", "in": "query", "description": "Opaque cursor from a previous response for pagination", "schema": { "type": "string" } }, "Sort": { "name": "sort", "in": "query", "description": "Field to sort by (available fields vary by endpoint)", "schema": { "type": "string" } }, "Order": { "name": "order", "in": "query", "description": "Sort direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } } }, "responses": { "Unauthenticated": { "description": "Authentication required or token invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "Missing or invalid authentication token.", "status": 401, "requestId": "req-def456", "details": null } } } } }, "Forbidden": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "FORBIDDEN", "message": "You do not have permission to access this resource.", "status": 403, "requestId": "req-ghi789", "details": null } } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found.", "status": 404, "requestId": "req-jkl012", "details": null } } } } }, "BadRequest": { "description": "Invalid request body or parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "INVALID_REQUEST_BODY", "message": "Request body failed validation.", "status": 400, "requestId": "req-mno345", "details": null } } } } }, "RateLimited": { "description": "Too many requests", "headers": { "Retry-After": { "description": "Seconds until the rate limit resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please slow down.", "status": 429, "requestId": "req-pqr678", "details": null } } } } } } } }