{ "components": { "schemas": { "TypeId": { "description": "UUID with type prefix", "type": "string", "example": "us_01hxcvk1hjexere4pvtrj0ymqq" }, "AIAgent": { "description": "Combined AI agent representation with user profile, configuration, and assigned model/provider details.", "required": [ "user", "profile", "latestVersion", "isLatest" ], "type": "object", "properties": { "user": { "description": "Bot user profile", "type": "object", "allOf": [ { "$ref": "#/components/schemas/UserFull" } ] }, "profile": { "description": "Bot configuration profile", "type": "object", "allOf": [ { "$ref": "#/components/schemas/AIAgentProfile" } ] }, "model": { "description": "Assigned model details, if profile has model", "type": "object", "allOf": [ { "$ref": "#/components/schemas/AIAgentAssignedModel" } ], "nullable": true }, "provider": { "description": "Assigned provider details, if profile has model", "type": "object", "allOf": [ { "$ref": "#/components/schemas/AIAgentAssignedProvider" } ], "nullable": true }, "latestVersion": { "format": "int32", "description": "Latest profile version number for this agent", "type": "integer" }, "isLatest": { "description": "True if current profile is the latest profile version", "type": "boolean" } } }, "AIAgentAssignedModel": { "description": "Model assignment details for the bot.", "required": [ "modelId", "enabled" ], "type": "object", "properties": { "modelId": { "description": "Assigned model identifier", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "mdl_01hz1f0kw36f82k9s4nzpc4s92n" }, "name": { "description": "Assigned model name from catalog", "type": "string", "example": "GPT-4o", "nullable": true }, "enabled": { "description": "Whether assigned model is currently enabled in this scope", "type": "boolean", "example": true } } }, "AIAgentAssignedProvider": { "description": "Provider details for the assigned model.", "type": "object", "properties": { "type": { "description": "Provider type for the assigned model", "enum": [ "OPENAI", "OPENROUTER", "GOOGLE", "ANTHROPIC" ], "type": "string", "nullable": true }, "name": { "description": "Provider display name", "type": "string", "example": "OpenAI", "nullable": true }, "logoUrl": { "description": "Provider logo URL", "type": "string", "example": "https://wellesley.ai/logos/openai.svg", "nullable": true } } }, "AIAgentBudgetLimits": { "description": "Budget limits in USD cents for AI agent executions.", "type": "object", "properties": { "dailyBudgetCents": { "description": "Daily budget in USD cents (null = unlimited)", "type": "integer", "example": "1000" }, "monthlyBudgetCents": { "description": "Monthly budget in USD cents (null = unlimited)", "type": "integer", "example": "10000" } } }, "AIAgentCreate": { "description": "Request payload for creating a new AI agent with profile configuration and scope.", "required": [ "username", "displayName" ], "type": "object", "properties": { "tools": { "description": "List of tools enabled for this bot", "type": "array", "items": { "$ref": "#/components/schemas/AIAgentTool" }, "example": [ "VECTOR_SEARCH", "REPLY" ] }, "triggers": { "description": "Configured triggers for this bot", "type": "array", "items": { "$ref": "#/components/schemas/AIAgentTrigger" } }, "modelId": { "description": "Model identifier (ai_models.model_id); must be enabled in this scope", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "mdl_01hz1f0kw36f82k9s4nzpc4s92n", "nullable": true }, "uploadIds": { "description": "List of uploads (documents) attached to the bot", "type": "array", "items": { "$ref": "#/components/schemas/TypeId" }, "example": [ "up_01hz1f0kw36f82k9s4nzpc4s92n" ] }, "dailyBudget": { "format": "int64", "description": "Daily budget in USD cents (null = unlimited)", "type": "integer", "example": 1000, "nullable": true }, "monthlyBudget": { "format": "int64", "description": "Monthly budget in USD cents (null = unlimited)", "type": "integer", "example": 10000, "nullable": true }, "rateLimitHourly": { "format": "int32", "description": "Maximum invocations per hour (null = unlimited)", "type": "integer", "example": 100, "nullable": true }, "rateLimitDaily": { "format": "int32", "description": "Maximum invocations per day (null = unlimited)", "type": "integer", "example": 1000, "nullable": true }, "role": { "description": "Role/instruction directives for the agent", "type": "array", "items": { "type": "string" }, "example": [ "Skeptical engineer" ] }, "personality": { "description": "Personality traits used when building agent instructions", "type": "array", "items": { "type": "string" }, "example": [ "Friendly", "Fact-checking" ] }, "style": { "description": "Writing/response style directives", "type": "array", "items": { "type": "string" }, "example": [ "Clear paragraphs", "Simple language" ] }, "behavior": { "description": "Behavior directives", "type": "array", "items": { "type": "string" }, "example": [ "Explain first", "Ask clarifying questions" ] }, "prompt": { "description": "Additional free-form prompt/instructions", "type": "string", "example": "Prioritize concise actionable guidance.", "nullable": true }, "resourceIds": { "description": "Group scope resource ids (group channels). Empty means whole group.", "type": "array", "items": { "$ref": "#/components/schemas/TypeId" }, "example": [ "gc_01hz1f0kw36f82k9s4nzpc4s92n" ] }, "username": { "description": "Bot username (without group prefix)", "type": "string", "example": "helpbot" }, "displayName": { "description": "Bot display name", "pattern": "\\S", "type": "string", "example": "Help Bot" }, "summary": { "description": "Bot bio", "maxLength": 1024, "type": "string", "example": "Automated support assistant", "nullable": true }, "avatarId": { "description": "Avatar upload id", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "headerId": { "description": "Header upload id", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } }, "AIAgentJobResultCallback": { "description": "Job result callback payload reported by the external AI worker service.", "required": [ "jobId", "agentId", "profileVersion", "status", "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "postsCreated", "imagesGenerated" ], "type": "object", "properties": { "jobId": { "description": "Processed job id", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "agentId": { "description": "Bot user id", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "profileVersion": { "format": "int32", "description": "Profile version that produced this job", "type": "integer" }, "status": { "description": "Job result status", "type": "string", "allOf": [ { "$ref": "#/components/schemas/AIAgentJobResultStatus" } ] }, "outCode": { "description": "Worker-defined output code or error code", "type": "string", "nullable": true }, "message": { "description": "Optional worker message", "type": "string", "nullable": true }, "inputTokens": { "format": "int64", "description": "Input tokens consumed by the job", "minimum": 0, "type": "integer" }, "outputTokens": { "format": "int64", "description": "Output tokens produced by the job", "minimum": 0, "type": "integer" }, "cacheReadTokens": { "format": "int64", "description": "Cached read tokens consumed by the job", "minimum": 0, "type": "integer" }, "cacheWriteTokens": { "format": "int64", "description": "Cached write tokens consumed by the job", "minimum": 0, "type": "integer" }, "postsCreated": { "format": "int64", "description": "Number of posts created by the job", "minimum": 0, "type": "integer" }, "imagesGenerated": { "format": "int64", "description": "Number of images generated by the job", "minimum": 0, "type": "integer" }, "details": { "description": "Arbitrary structured worker metadata", "type": "object", "additionalProperties": {}, "nullable": true } } }, "AIAgentJobResultStatus": { "description": "Outcome status reported by the external AI worker.", "enum": [ "SUCCESS", "FAILURE" ], "type": "string" }, "AIAgentProfile": { "description": "Configuration profile for an AI agent (tools, triggers, budgets, rate limits, scope).", "required": [ "agentId", "version", "stats", "versionStats", "enabled", "isCurrent", "createdAt" ], "type": "object", "properties": { "resourceIds": { "description": "Group scope resource ids (group channels). Empty means whole group.", "type": "array", "items": { "$ref": "#/components/schemas/TypeId" }, "example": [ "gc_01hz1f0kw36f82k9s4nzpc4s92n" ] }, "tools": { "description": "List of tools enabled for this bot", "type": "array", "items": { "$ref": "#/components/schemas/AIAgentTool" }, "example": [ "VECTOR_SEARCH", "REPLY" ] }, "triggers": { "description": "Configured triggers for this bot", "type": "array", "items": { "$ref": "#/components/schemas/AIAgentTrigger" } }, "modelId": { "description": "Model identifier (ai_models.model_id); must be enabled in this scope", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "mdl_01hz1f0kw36f82k9s4nzpc4s92n", "nullable": true }, "uploadIds": { "description": "List of uploads (documents) attached to the bot", "type": "array", "items": { "$ref": "#/components/schemas/TypeId" }, "example": [ "up_01hz1f0kw36f82k9s4nzpc4s92n" ] }, "dailyBudget": { "format": "int64", "description": "Daily budget in USD cents (null = unlimited)", "type": "integer", "example": 1000, "nullable": true }, "monthlyBudget": { "format": "int64", "description": "Monthly budget in USD cents (null = unlimited)", "type": "integer", "example": 10000, "nullable": true }, "rateLimitHourly": { "format": "int32", "description": "Maximum invocations per hour (null = unlimited)", "type": "integer", "example": 100, "nullable": true }, "rateLimitDaily": { "format": "int32", "description": "Maximum invocations per day (null = unlimited)", "type": "integer", "example": 1000, "nullable": true }, "role": { "description": "Role/instruction directives for the agent", "type": "array", "items": { "type": "string" }, "example": [ "Skeptical engineer" ] }, "personality": { "description": "Personality traits used when building agent instructions", "type": "array", "items": { "type": "string" }, "example": [ "Friendly", "Fact-checking" ] }, "style": { "description": "Writing/response style directives", "type": "array", "items": { "type": "string" }, "example": [ "Clear paragraphs", "Simple language" ] }, "behavior": { "description": "Behavior directives", "type": "array", "items": { "type": "string" }, "example": [ "Explain first", "Ask clarifying questions" ] }, "prompt": { "description": "Additional free-form prompt/instructions", "type": "string", "example": "Prioritize concise actionable guidance.", "nullable": true }, "agentId": { "description": "Bot user id", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "us_01hz1f0kw36f82k9s4nzpc4s92n" }, "groupId": { "description": "Group id for group-scoped bots", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "gr_01hz1f0kw36f82k9s4nzpc4s92n", "nullable": true }, "version": { "format": "int32", "description": "Immutable profile version number for this agent", "type": "integer", "example": 1 }, "stats": { "description": "Combined stats across all profile versions for the current agent state", "type": "object", "allOf": [ { "$ref": "#/components/schemas/AIAgentProfileStats" } ] }, "versionStats": { "description": "Stats for this exact profile version", "type": "object", "allOf": [ { "$ref": "#/components/schemas/AIAgentProfileVersionStats" } ] }, "enabled": { "description": "Whether this bot is enabled", "type": "boolean", "example": true }, "currentAt": { "description": "When this profile version became current (null for non-current versions)", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "example": "2024-01-15T10:30:00Z", "nullable": true }, "isCurrent": { "description": "Whether this profile version is currently active", "type": "boolean", "example": false }, "createdAt": { "description": "ISO 8601 timestamp when this profile was created", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "example": "2024-01-15T10:30:00Z" } } }, "AIAgentProfileStats": { "description": "Combined current-state stats across all profile versions for an AI agent.", "required": [ "runs", "costCents", "postsCreated", "imagesGenerated", "runs7d", "costCents7d", "postsCreated7d", "imagesGenerated7d" ], "type": "object", "properties": { "runs": { "format": "int64", "description": "Total number of job invocations", "type": "integer" }, "costCents": { "format": "int64", "description": "Total cost in USD cents", "type": "integer" }, "postsCreated": { "format": "int64", "description": "Total number of posts created", "type": "integer" }, "imagesGenerated": { "format": "int64", "description": "Total number of images generated", "type": "integer" }, "runs7d": { "format": "int64", "description": "Number of job invocations in the last 7 days", "type": "integer" }, "costCents7d": { "format": "int64", "description": "Total cost in USD cents in the last 7 days", "type": "integer" }, "postsCreated7d": { "format": "int64", "description": "Number of posts created in the last 7 days", "type": "integer" }, "imagesGenerated7d": { "format": "int64", "description": "Number of images generated in the last 7 days", "type": "integer" } } }, "AIAgentProfileUpdate": { "description": "Request payload for updating AI agent profile configuration.", "type": "object", "properties": { "tools": { "description": "List of tools enabled for this bot", "type": "array", "items": { "$ref": "#/components/schemas/AIAgentTool" }, "example": [ "VECTOR_SEARCH", "REPLY" ] }, "triggers": { "description": "Configured triggers for this bot", "type": "array", "items": { "$ref": "#/components/schemas/AIAgentTrigger" } }, "modelId": { "description": "Model identifier (ai_models.model_id); must be enabled in this scope", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "mdl_01hz1f0kw36f82k9s4nzpc4s92n", "nullable": true }, "uploadIds": { "description": "List of uploads (documents) attached to the bot", "type": "array", "items": { "$ref": "#/components/schemas/TypeId" }, "example": [ "up_01hz1f0kw36f82k9s4nzpc4s92n" ] }, "dailyBudget": { "format": "int64", "description": "Daily budget in USD cents (null = unlimited)", "type": "integer", "example": 1000, "nullable": true }, "monthlyBudget": { "format": "int64", "description": "Monthly budget in USD cents (null = unlimited)", "type": "integer", "example": 10000, "nullable": true }, "rateLimitHourly": { "format": "int32", "description": "Maximum invocations per hour (null = unlimited)", "type": "integer", "example": 100, "nullable": true }, "rateLimitDaily": { "format": "int32", "description": "Maximum invocations per day (null = unlimited)", "type": "integer", "example": 1000, "nullable": true }, "role": { "description": "Role/instruction directives for the agent", "type": "array", "items": { "type": "string" }, "example": [ "Skeptical engineer" ] }, "personality": { "description": "Personality traits used when building agent instructions", "type": "array", "items": { "type": "string" }, "example": [ "Friendly", "Fact-checking" ] }, "style": { "description": "Writing/response style directives", "type": "array", "items": { "type": "string" }, "example": [ "Clear paragraphs", "Simple language" ] }, "behavior": { "description": "Behavior directives", "type": "array", "items": { "type": "string" }, "example": [ "Explain first", "Ask clarifying questions" ] }, "prompt": { "description": "Additional free-form prompt/instructions", "type": "string", "example": "Prioritize concise actionable guidance.", "nullable": true }, "resourceIds": { "description": "Group scope resource ids (group channels). Empty means whole group.", "type": "array", "items": { "$ref": "#/components/schemas/TypeId" }, "example": [ "gc_01hz1f0kw36f82k9s4nzpc4s92n" ] } } }, "AIAgentProfileVersionCreated": { "required": [ "version" ], "type": "object", "properties": { "version": { "format": "int32", "description": "Newly created profile version number", "type": "integer" } } }, "AIAgentProfileVersionStats": { "description": "All-time stats for a specific AI agent profile version.", "required": [ "runs", "costCents", "postsCreated", "imagesGenerated" ], "type": "object", "properties": { "runs": { "format": "int64", "description": "Total number of job invocations", "type": "integer" }, "costCents": { "format": "int64", "description": "Total cost in USD cents", "type": "integer" }, "postsCreated": { "format": "int64", "description": "Total number of posts created", "type": "integer" }, "imagesGenerated": { "format": "int64", "description": "Total number of images generated", "type": "integer" } } }, "AIAgentThresholdMetric": { "description": "Metric to evaluate", "enum": [ "LIKES", "REPOSTS", "THREAD_LENGTH" ], "type": "string" }, "AIAgentTool": { "description": "Tool names available for AI agents. Tools are explicitly enabled per bot.", "enum": [ "VECTOR_SEARCH", "REGULAR_SEARCH", "ENTITY_SEARCH", "WEB_SEARCH", "POSTS_SINCE_LAST_INVOCATION", "POSTS_IN_TIME_RANGE", "LIST_GROUP_STRUCTURE", "REPLY", "LIKE", "REPORT", "QUOTE", "CREATE_OR_UPDATE_POST", "GENERATE_IMAGES", "REPORT_CONTENT", "ADD_REPORT_NOTE", "API_ACCESS" ], "type": "string" }, "AIAgentTrigger": { "description": "Trigger configuration for an AI agent.", "required": [ "type" ], "type": "object", "properties": { "type": { "description": "Trigger type", "type": "string", "allOf": [ { "$ref": "#/components/schemas/AIAgentTriggerType" } ] }, "prompt": { "description": "Optional trigger-level prompt appended to instructions when this trigger matches", "type": "string", "example": "Prioritize concise replies for this trigger.", "nullable": true } }, "oneOf": [ { "$ref": "#/components/schemas/AIAgentTriggerPostCreated" }, { "$ref": "#/components/schemas/AIAgentTriggerReplyCreated" }, { "$ref": "#/components/schemas/AIAgentTriggerPostEdited" }, { "$ref": "#/components/schemas/AIAgentTriggerMentioned" }, { "$ref": "#/components/schemas/AIAgentTriggerQuestionDetected" }, { "$ref": "#/components/schemas/AIAgentTriggerKeywordMatch" }, { "$ref": "#/components/schemas/AIAgentTriggerIntentMatch" }, { "$ref": "#/components/schemas/AIAgentTriggerReportedContent" }, { "$ref": "#/components/schemas/AIAgentTriggerThreshold" }, { "$ref": "#/components/schemas/AIAgentTriggerUnanswered" }, { "$ref": "#/components/schemas/AIAgentTriggerCron" }, { "$ref": "#/components/schemas/AIAgentTriggerNewGroupMember" } ] }, "AIAgentTriggerCron": { "description": "Cron schedule trigger", "required": [ "type", "schedule", "timeZone" ], "type": "object", "properties": { "type": { "description": "Trigger type", "type": "string", "allOf": [ { "$ref": "#/components/schemas/AIAgentTriggerType" } ] }, "prompt": { "description": "Optional trigger-level prompt appended to instructions when this trigger matches", "type": "string", "example": "Prioritize concise replies for this trigger.", "nullable": true }, "schedule": { "description": "Cron expression in ' ' format.", "pattern": "\\S", "type": "string", "example": "*/15 * * * *" }, "timeZone": { "description": "IANA timezone identifier.", "pattern": "\\S", "type": "string", "example": "America/New_York" } } }, "AIAgentTriggerIntentMatch": { "description": "Post matches a configured intent.", "required": [ "type", "match" ], "type": "object", "properties": { "type": { "description": "Trigger type", "type": "string", "allOf": [ { "$ref": "#/components/schemas/AIAgentTriggerType" } ] }, "prompt": { "description": "Optional trigger-level prompt appended to instructions when this trigger matches", "type": "string", "example": "Prioritize concise replies for this trigger.", "nullable": true }, "match": { "description": "Intent match string.", "pattern": "\\S", "type": "string", "example": "support" } } }, "AIAgentTriggerKeywordMatch": { "description": "Post contains configured keywords/topics", "required": [ "type", "keywords" ], "type": "object", "properties": { "type": { "description": "Trigger type", "type": "string", "allOf": [ { "$ref": "#/components/schemas/AIAgentTriggerType" } ] }, "prompt": { "description": "Optional trigger-level prompt appended to instructions when this trigger matches", "type": "string", "example": "Prioritize concise replies for this trigger.", "nullable": true }, "keywords": { "description": "Keywords to match.", "minItems": 1, "type": "array", "items": { "type": "string" }, "example": [ "help", "support" ] } } }, "AIAgentTriggerMentioned": { "description": "Bot is mentioned in a post", "required": [ "type" ], "type": "object", "properties": { "type": { "description": "Trigger type", "type": "string", "allOf": [ { "$ref": "#/components/schemas/AIAgentTriggerType" } ] }, "prompt": { "description": "Optional trigger-level prompt appended to instructions when this trigger matches", "type": "string", "example": "Prioritize concise replies for this trigger.", "nullable": true } } }, "AIAgentTriggerNewGroupMember": { "description": "New group member joined", "required": [ "type" ], "type": "object", "properties": { "type": { "description": "Trigger type", "type": "string", "allOf": [ { "$ref": "#/components/schemas/AIAgentTriggerType" } ] }, "prompt": { "description": "Optional trigger-level prompt appended to instructions when this trigger matches", "type": "string", "example": "Prioritize concise replies for this trigger.", "nullable": true } } }, "AIAgentTriggerPostCreated": { "description": "New top-level post created", "required": [ "type" ], "type": "object", "properties": { "type": { "description": "Trigger type", "type": "string", "allOf": [ { "$ref": "#/components/schemas/AIAgentTriggerType" } ] }, "prompt": { "description": "Optional trigger-level prompt appended to instructions when this trigger matches", "type": "string", "example": "Prioritize concise replies for this trigger.", "nullable": true } } }, "AIAgentTriggerPostEdited": { "description": "Existing top-level post edited", "required": [ "type" ], "type": "object", "properties": { "type": { "description": "Trigger type", "type": "string", "allOf": [ { "$ref": "#/components/schemas/AIAgentTriggerType" } ] }, "prompt": { "description": "Optional trigger-level prompt appended to instructions when this trigger matches", "type": "string", "example": "Prioritize concise replies for this trigger.", "nullable": true } } }, "AIAgentTriggerQuestionDetected": { "description": "Post looks like a question", "required": [ "type" ], "type": "object", "properties": { "type": { "description": "Trigger type", "type": "string", "allOf": [ { "$ref": "#/components/schemas/AIAgentTriggerType" } ] }, "prompt": { "description": "Optional trigger-level prompt appended to instructions when this trigger matches", "type": "string", "example": "Prioritize concise replies for this trigger.", "nullable": true } } }, "AIAgentTriggerReplyCreated": { "description": "New reply/comment created", "required": [ "type" ], "type": "object", "properties": { "type": { "description": "Trigger type", "type": "string", "allOf": [ { "$ref": "#/components/schemas/AIAgentTriggerType" } ] }, "prompt": { "description": "Optional trigger-level prompt appended to instructions when this trigger matches", "type": "string", "example": "Prioritize concise replies for this trigger.", "nullable": true } } }, "AIAgentTriggerReportedContent": { "description": "Moderation report created", "required": [ "type" ], "type": "object", "properties": { "type": { "description": "Trigger type", "type": "string", "allOf": [ { "$ref": "#/components/schemas/AIAgentTriggerType" } ] }, "prompt": { "description": "Optional trigger-level prompt appended to instructions when this trigger matches", "type": "string", "example": "Prioritize concise replies for this trigger.", "nullable": true } } }, "AIAgentTriggerThreshold": { "description": "Threshold reached (likes/comments/reposts)", "required": [ "type", "metric", "threshold" ], "type": "object", "properties": { "type": { "description": "Trigger type", "type": "string", "allOf": [ { "$ref": "#/components/schemas/AIAgentTriggerType" } ] }, "prompt": { "description": "Optional trigger-level prompt appended to instructions when this trigger matches", "type": "string", "example": "Prioritize concise replies for this trigger.", "nullable": true }, "metric": { "description": "Metric to evaluate", "enum": [ "LIKES", "REPOSTS", "THREAD_LENGTH" ], "type": "string" }, "threshold": { "format": "int64", "description": "Threshold value", "minimum": 0, "exclusiveMinimum": true, "type": "integer", "example": 300 } } }, "AIAgentTriggerType": { "description": "Trigger types that can activate an AI agent.", "enum": [ "POST_CREATED", "REPLY_CREATED", "POST_EDITED", "MENTIONED", "QUESTION_DETECTED", "KEYWORD_MATCH", "INTENT_MATCH", "REPORTED_CONTENT", "THRESHOLD", "UNANSWERED", "CRON", "NEW_GROUP_MEMBER", "DIRECT_REPLY" ], "type": "string" }, "AIAgentTriggerUnanswered": { "description": "Post unanswered for N minutes (group scope only)", "required": [ "type", "minutes" ], "type": "object", "properties": { "type": { "description": "Trigger type", "type": "string", "allOf": [ { "$ref": "#/components/schemas/AIAgentTriggerType" } ] }, "prompt": { "description": "Optional trigger-level prompt appended to instructions when this trigger matches", "type": "string", "example": "Prioritize concise replies for this trigger.", "nullable": true }, "minutes": { "format": "int64", "description": "Minutes before unanswered trigger fires", "minimum": 0, "exclusiveMinimum": true, "type": "integer", "example": 15 } } }, "AIAuthType": { "description": "Authentication method for AI provider", "enum": [ "API_KEY", "OAUTH2", "NONE" ], "type": "string" }, "AIBuiltInTool": { "description": "Built-in tool type supported natively by an AI provider", "enum": [ "WEB_SEARCH", "CODE_EXECUTION", "FILE_SEARCH", "COMPUTER_USE", "IMAGE_GENERATION", "TEXT_EDITOR", "BASH", "URL_CONTEXT", "MCP" ], "type": "string" }, "AIModality": { "description": "Input/output modality supported by model", "enum": [ "TEXT", "IMAGE", "AUDIO", "VIDEO", "PDF" ], "type": "string" }, "AIModel": { "description": "AI model configuration", "required": [ "modelId", "providerId", "externalId", "name", "enabled", "deprecated", "successorModelId", "capabilities", "modalities", "builtInTools", "limits", "pricing", "family", "releaseDate", "knowledgeCutoff", "openWeights", "createdAt", "updatedAt" ], "type": "object", "properties": { "modelId": { "description": "Model unique identifier", "type": "object", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "providerId": { "description": "Provider this model belongs to", "type": "object", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "externalId": { "description": "External model ID used by the provider (e.g., 'gpt-4.1')", "type": "string" }, "name": { "description": "Display name for the model", "type": "string" }, "enabled": { "description": "Whether the model is enabled in the requested scope (null if no scoped record)", "type": "boolean", "nullable": true }, "deprecated": { "description": "Whether the model is deprecated", "type": "boolean" }, "successorModelId": { "description": "Successor model ID if deprecated", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "capabilities": { "description": "Model capabilities", "type": "object", "allOf": [ { "$ref": "#/components/schemas/AIModelCapabilities" } ] }, "modalities": { "description": "Supported input/output modalities", "type": "array", "items": { "$ref": "#/components/schemas/AIModality" } }, "builtInTools": { "description": "Built-in tools supported natively by the provider for this model", "type": "array", "items": { "$ref": "#/components/schemas/AIBuiltInTool" } }, "limits": { "description": "Token limits", "type": "object", "allOf": [ { "$ref": "#/components/schemas/AIModelLimits" } ] }, "pricing": { "description": "Pricing information", "type": "object", "allOf": [ { "$ref": "#/components/schemas/AIModelPricing" } ], "nullable": true }, "family": { "description": "Model family (e.g., 'gpt-4o', 'claude-opus')", "type": "string", "nullable": true }, "releaseDate": { "description": "Model release date", "type": "string", "nullable": true }, "knowledgeCutoff": { "description": "Knowledge cutoff date", "type": "string", "nullable": true }, "openWeights": { "description": "Whether model has open weights", "type": "boolean" }, "createdAt": { "description": "When the model was created", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] }, "updatedAt": { "description": "When the model was last updated", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] } } }, "AIModelCapabilities": { "description": "Capabilities supported by the AI model", "type": "object", "properties": { "supportsChat": { "description": "Supports chat completions", "type": "boolean" }, "supportsEmbeddings": { "description": "Supports embeddings generation", "type": "boolean" }, "supportsTools": { "description": "Supports tool/function calling", "type": "boolean" }, "supportsJsonSchema": { "description": "Supports JSON schema response format", "type": "boolean" }, "supportsVision": { "description": "Supports image input (vision)", "type": "boolean" }, "supportsStreaming": { "description": "Supports streaming responses", "type": "boolean" }, "supportsReasoning": { "description": "Supports reasoning/chain-of-thought", "type": "boolean" }, "supportsAttachments": { "description": "Supports file attachments (images, PDFs, etc.)", "type": "boolean" }, "supportsTemperature": { "description": "Supports temperature parameter", "type": "boolean" } } }, "AIModelCapabilityFilter": { "description": "Available capability filters for model search", "enum": [ "CHAT", "EMBEDDINGS", "TOOLS", "JSON_SCHEMA", "VISION", "STREAMING", "REASONING", "ATTACHMENTS", "TEMPERATURE" ], "type": "string" }, "AIModelFilter": { "description": "Filter parameters for searching AI models", "type": "object", "properties": { "providerId": { "description": "Filter by provider ID", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "search": { "description": "Search in name, family, and external ID (case-insensitive partial match)", "type": "string", "nullable": true }, "capabilities": { "description": "Filter by capabilities (models must have ALL specified capabilities)", "type": "array", "items": { "$ref": "#/components/schemas/AIModelCapabilityFilter" }, "nullable": true }, "modalities": { "description": "Filter by modalities (models must support ALL specified modalities)", "type": "array", "items": { "$ref": "#/components/schemas/AIModality" }, "nullable": true }, "builtInTools": { "description": "Filter by built-in tools (models must support ALL specified tools)", "type": "array", "items": { "$ref": "#/components/schemas/AIBuiltInTool" }, "nullable": true }, "deprecated": { "description": "Filter by deprecated status", "type": "boolean", "nullable": true }, "openWeights": { "description": "Filter by open weights status", "type": "boolean", "nullable": true }, "minContextWindow": { "format": "int32", "description": "Minimum context window size", "type": "integer", "nullable": true }, "maxContextWindow": { "format": "int32", "description": "Maximum context window size", "type": "integer", "nullable": true }, "minMaxOutputTokens": { "format": "int32", "description": "Minimum max output tokens", "type": "integer", "nullable": true }, "maxMaxOutputTokens": { "format": "int32", "description": "Maximum max output tokens", "type": "integer", "nullable": true }, "maxInputPrice": { "format": "double", "description": "Maximum input price per 1M tokens (USD)", "type": "number", "nullable": true }, "maxOutputPrice": { "format": "double", "description": "Maximum output price per 1M tokens (USD)", "type": "number", "nullable": true }, "enabled": { "description": "Filter by enablement state in the requested scope (true=enabled only, false=disabled/unconfigured only, null=all)", "type": "boolean", "nullable": true } } }, "AIModelLimits": { "description": "Token and context limits for the AI model", "type": "object", "properties": { "maxInputTokens": { "format": "int32", "description": "Maximum input tokens", "type": "integer", "nullable": true }, "maxOutputTokens": { "format": "int32", "description": "Maximum output tokens", "type": "integer", "nullable": true }, "contextWindow": { "format": "int32", "description": "Total context window size", "type": "integer", "nullable": true } } }, "AIModelPagedResponse": { "description": "Paginated response containing AI models", "required": [ "models", "totalCount", "pageCount", "page", "pageSize" ], "type": "object", "properties": { "models": { "description": "List of AI models matching the filter criteria", "type": "array", "items": { "$ref": "#/components/schemas/AIModel" } }, "totalCount": { "format": "int64", "description": "Total number of models matching the filter (before pagination)", "type": "integer" }, "pageCount": { "format": "int32", "description": "Total number of pages", "type": "integer" }, "page": { "format": "int32", "description": "Current page number (0-indexed)", "type": "integer" }, "pageSize": { "format": "int32", "description": "Number of items per page", "type": "integer" } } }, "AIModelPricing": { "description": "Pricing information for the AI model (per 1M tokens)", "type": "object", "properties": { "inputPer1MTokens": { "format": "double", "description": "Cost per 1M input tokens in USD", "type": "number", "nullable": true }, "outputPer1MTokens": { "format": "double", "description": "Cost per 1M output tokens in USD", "type": "number", "nullable": true }, "cacheReadPer1MTokens": { "format": "double", "description": "Cost per 1M cached read tokens in USD", "type": "number", "nullable": true }, "cacheWritePer1MTokens": { "format": "double", "description": "Cost per 1M cached write tokens in USD", "type": "number", "nullable": true } } }, "AIProvider": { "description": "AI provider configuration", "required": [ "providerId", "providerType", "name", "configured", "hasApiKey", "apiKeyPreview", "apiKeyFormatHint", "logoUrl", "createdAt", "updatedAt" ], "type": "object", "properties": { "providerId": { "description": "Provider unique identifier (catalog)", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "providerType": { "description": "Type of the AI provider", "type": "string", "allOf": [ { "$ref": "#/components/schemas/AIProviderType" } ] }, "name": { "description": "Display name for the provider", "type": "string" }, "configured": { "description": "Whether provider is configured (has a scoped record) in this scope", "type": "boolean" }, "hasApiKey": { "description": "Whether this provider has an API key configured in this scope", "type": "boolean" }, "apiKeyPreview": { "description": "Masked preview of the stored API key (provider prefix + first few unique chars)", "type": "string", "example": "sk-abcd...", "nullable": true }, "apiKeyFormatHint": { "description": "Lightweight API key format hint for this provider type", "type": "object", "allOf": [ { "$ref": "#/components/schemas/APIKeyFormatHint" } ] }, "logoUrl": { "description": "URL to provider logo", "type": "string", "example": "https://models.dev/logos/openai.svg", "nullable": true }, "createdAt": { "description": "When the provider was created", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] }, "updatedAt": { "description": "When the provider was last updated", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] } } }, "AIProviderType": { "description": "Supported AI provider types", "enum": [ "OPENAI", "OPENROUTER", "GOOGLE", "ANTHROPIC" ], "type": "string" }, "AIScopedProviderConfigure": { "description": "Request to configure a provider for a scope", "type": "object", "properties": { "authType": { "description": "Authentication type", "type": "string", "allOf": [ { "$ref": "#/components/schemas/AIAuthType" } ] }, "authSecret": { "description": "API key or secret (will be encrypted)", "type": "string", "nullable": true }, "clearAuthSecret": { "description": "Clear stored auth secret", "type": "boolean" } } }, "APIKeyFormatHint": { "description": "Provider-specific API key format hints", "required": [ "prefixes", "exampleMasked", "rule", "docsUrl", "regexHint" ], "type": "object", "properties": { "prefixes": { "description": "Accepted key prefixes", "type": "array", "items": { "type": "string" }, "example": [ "sk-" ] }, "exampleMasked": { "description": "Masked key example", "type": "string", "example": "sk-...abcd" }, "rule": { "description": "Human-readable format guidance", "type": "string" }, "docsUrl": { "description": "Documentation URL for obtaining and managing keys", "type": "string" }, "regexHint": { "description": "Loose validation regex hint", "type": "string" } } }, "Account": { "required": [ "id", "password", "createdAt", "updatedAt" ], "type": "object", "properties": { "id": { "description": "Internal account id", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "act_ytweuysdjfhguyt" }, "email": { "description": "Account email", "type": "string", "example": "john@example.com", "nullable": true }, "password": { "type": "string", "nullable": true }, "phone": { "description": "Account phone", "type": "string", "example": "+12345678901", "nullable": true }, "createdAt": { "$ref": "#/components/schemas/Instant" }, "updatedAt": { "$ref": "#/components/schemas/Instant" } } }, "AccountCreate": { "description": "Parameters for creating a new account with a primary user. The account will be created with email/password authentication and a single user profile.", "required": [ "username", "displayName", "email", "password" ], "type": "object", "properties": { "username": { "description": "Username of the main user", "type": "string", "example": "john_smith" }, "displayName": { "description": "Display Name of the main user", "maxLength": 56, "minLength": 1, "type": "string", "example": "John Smith" }, "email": { "description": "Accounts' email", "type": "string", "example": "email@gmail.com" }, "password": { "description": "Account password, enforced by password policy", "type": "string", "example": "PassW0rd!" }, "inviteCode": { "description": "Optional invite code", "type": "string", "example": "abcd-efgh-1234", "nullable": true } } }, "AccountUsersWithOwnedGroups": { "description": "Account details with all account users and groups owned by each user.", "required": [ "account", "users" ], "type": "object", "properties": { "account": { "description": "Account details", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Account" } ] }, "users": { "description": "Users under this account with their owned groups", "type": "array", "items": { "$ref": "#/components/schemas/UserWithOwnedGroups" } }, "selectedUserId": { "description": "Currently selected user ID for this account", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "us_kjhauygmxcvkhwe", "nullable": true } } }, "AccountWithUser": { "description": "Complete account information including the account details and all associated users. An account represents the authentication entity while users represent the public profiles.", "required": [ "account", "users" ], "type": "object", "properties": { "account": { "description": "Account details including email, login type, and creation date", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Account" } ] }, "users": { "description": "Non-empty list of users associated with this account. Most accounts have one user, but multiple users are supported.", "type": "array", "items": { "$ref": "#/components/schemas/UserFull" } }, "selectedUserId": { "description": "ID of currently selected user. If not provided, the first user is selected", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "usr_kjhauygmxcvkhwe", "nullable": true } } }, "AccountWithUserAndToken": { "required": [ "account", "users", "token" ], "type": "object", "properties": { "account": { "$ref": "#/components/schemas/Account" }, "users": { "type": "array", "items": { "$ref": "#/components/schemas/UserFull" } }, "token": { "$ref": "#/components/schemas/Token" } } }, "ActionModel": { "required": [ "name", "description" ], "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } } }, "ActionProperties": { "required": [ "extension" ], "type": "object", "properties": { "extension": { "type": "string" }, "width": { "format": "int32", "type": "integer", "nullable": true }, "height": { "format": "int32", "type": "integer", "nullable": true }, "rotation": { "format": "int32", "type": "integer" }, "thumbnailSecond": { "format": "double", "type": "number", "nullable": true } } }, "ActorType": { "description": "\n Types that an Actor can be assigned. Coincide with ActivityPub Actor types:\n * APPLICATION: Apps will have this type\n * GROUP: Interest Groups and Generic Groups wil have this type\n * ORGANIZATION: Formal Organizations such as Companies, Institutions, etc. will have this type\n * PERSON: Individual people will have this type\n * SERVICE: Bots, Services, and other automated tools which are not also Apps will have this type\n ", "enum": [ "Application", "Group", "Organization", "Person", "Service" ], "type": "string" }, "AddEmailRequest": { "description": "Params to add email to account", "required": [ "email", "password" ], "type": "object", "properties": { "email": { "description": "New email", "type": "string", "example": "user@gmail.com" }, "password": { "description": "New password, enforced by password policy", "type": "string", "example": "PassW0rd!" } } }, "AddPhoneRequest": { "required": [ "phone" ], "type": "object", "properties": { "phone": { "description": "Phone number", "type": "string", "example": "+12345678901" }, "code": { "format": "int32", "description": "Confirmation code", "type": "integer", "example": 854882, "nullable": true } } }, "Address": { "description": "Physical address", "required": [ "id", "data", "createdAt", "updatedAt" ], "type": "object", "properties": { "id": { "format": "int32", "description": "Internal address id", "type": "integer" }, "data": { "description": "Address data", "type": "object", "allOf": [ { "$ref": "#/components/schemas/AddressData" } ] }, "latitude": { "format": "double", "description": "Address latitude", "type": "number", "nullable": true }, "longitude": { "format": "double", "description": "Address longitude", "type": "number", "nullable": true }, "createdAt": { "$ref": "#/components/schemas/Instant" }, "updatedAt": { "$ref": "#/components/schemas/Instant" } } }, "AddressData": { "description": "Address variant", "required": [ "formatted" ], "type": "object", "properties": { "formatted": { "description": "Formatted address", "type": "string", "example": "Adriaen Van Ostadestraat 53, 4703 NT Roosendaal, Netherlands" }, "name": { "description": "Name", "type": "string", "example": "Casa Vacanze", "nullable": true }, "country": { "description": "Country", "type": "string", "example": "USA", "nullable": true }, "countryCode": { "description": "Country two letter name", "type": "string", "example": "us", "nullable": true }, "region": { "description": "Region", "type": "string", "example": "Massachusetts", "nullable": true }, "regionCode": { "description": "Region Code", "type": "string", "example": "MA", "nullable": true }, "subRegion": { "description": "Sub-region", "type": "string", "example": "Newton Heights", "nullable": true }, "locality": { "description": "Locality", "type": "string", "example": "Madrid", "nullable": true }, "street": { "description": "Street", "type": "string", "example": "Adriaen Van Ostadestraat", "nullable": true }, "postalCode": { "description": "Address postal code", "type": "string", "example": "4703 NT", "nullable": true }, "houseNumber": { "description": "House number", "type": "string", "example": "23", "nullable": true }, "longitude": { "format": "double", "description": "Longitude", "type": "number", "example": 4.437564, "nullable": true }, "latitude": { "format": "double", "description": "Latitude", "type": "number", "example": 51.534581, "nullable": true }, "timeZone": { "description": "Time zone name", "type": "string", "example": "Europe/Amsterdam", "nullable": true }, "plusCode": { "description": "Short code", "type": "string", "example": "9F36GCMQ+R2", "nullable": true }, "serviceId": { "description": "Service ID", "type": "string", "example": "geoapify", "nullable": true }, "placeId": { "description": "Service place id", "type": "string", "nullable": true } } }, "AddressFromCoordinatesResponse": { "required": [ "address" ], "type": "object", "properties": { "address": { "type": "string" } } }, "AllowedDomain": { "required": [ "domain", "createdAt" ], "type": "object", "properties": { "domain": { "description": "The domain name that is allowed to federate with this instance", "type": "string", "example": "mastodon.social" }, "createdAt": { "description": "Timestamp when the domain was added to the allowlist", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "example": "2024-01-15T10:30:00Z" } } }, "AllowedDomainReq": { "required": [ "domain" ], "type": "object", "properties": { "domain": { "description": "The domain name to add to the allowlist", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9-]{0,61}[a-zA-Z0-9]?(?:\\.[a-zA-Z0-9][a-zA-Z0-9-]{0,61}[a-zA-Z0-9]?)*$", "type": "string", "example": "example.com" } } }, "Answer": { "description": "An answer to a specific group entry question. The answer format must match the question type: TEXT questions require textAnswer, SINGLE_CHOICE requires exactly one selectedChoice index, MULTIPLE_CHOICE requires one or more selectedChoice indices.", "required": [ "questionId", "questionType" ], "type": "object", "properties": { "questionId": { "description": "The unique identifier of the question being answered", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "qu_01hz1f0gs9fe4a37jzvzn9m96k" }, "questionType": { "description": "The type of the question - must match the actual question type", "type": "string", "allOf": [ { "$ref": "#/components/schemas/QuestionType" } ] }, "textAnswer": { "description": "Free-form text answer for TEXT type questions (max 500 characters)", "type": "string", "example": "I want to join to share my expertise and learn from others", "nullable": true }, "selectedChoices": { "description": "Zero-based indices of selected choices for SINGLE_CHOICE or MULTIPLE_CHOICE questions", "type": "array", "items": { "format": "int32", "type": "integer" }, "example": [ 0, 2 ] } } }, "AppData": { "required": [ "id", "ownerId", "type", "data", "createdAt", "updatedAt" ], "type": "object", "properties": { "id": { "description": "Unique identifier for the app data", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "ad_01hq8c8em5hj1vr2f4h1t9db9q" }, "applicationId": { "description": "Optional application ID that this data belongs to", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "ap_01hq8c8em5hj1vr2f4h1t9db9q", "nullable": true }, "ownerId": { "description": "Owner identifier of the data. Can be a user ID, group ID, user-in-group format userId:groupId, or 'platform'", "type": "string", "example": "us_01hq8c8em5hj1vr2f4h1t9db9q" }, "type": { "description": "Type identifier for categorizing the data", "type": "string", "example": "user_profile" }, "tags": { "description": "Optional list of tags for additional categorization", "type": "array", "items": { "type": "string" }, "example": [ "personal", "profile" ], "nullable": true }, "data": { "description": "JSON string containing the actual data payload", "type": "string", "example": "{\"name\": \"John Doe\", \"bio\": \"Developer\"}" }, "createdAt": { "description": "Timestamp when the data was created", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "example": "2024-03-20T10:15:30Z" }, "updatedAt": { "description": "Timestamp when the data was last updated", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "example": "2024-03-20T10:15:30Z" } } }, "AppMeta": { "description": "Structured metadata keyed by dotted namespace (e.g. 'wellesley.group.channel', 'wellesley.group.forum'). Each value is a JSON object with namespace-specific fields.", "type": "object", "additionalProperties": true }, "AppScheme": { "enum": [ "http", "https" ], "type": "string" }, "Application": { "required": [ "id", "name", "manifest", "updatedAt" ], "type": "object", "properties": { "id": { "$ref": "#/components/schemas/TypeId" }, "name": { "type": "string" }, "manifest": { "$ref": "#/components/schemas/Manifest" }, "enabled": { "type": "boolean" }, "updatedAt": { "$ref": "#/components/schemas/Instant" } } }, "ApplicationDeveloper": { "required": [ "name", "website" ], "type": "object", "properties": { "name": { "type": "string" }, "website": { "type": "string" } } }, "ApplicationTrustLevel": { "enum": [ "STANDARD", "TRUSTED", "SYSTEM" ], "type": "string" }, "ApplicationType": { "enum": [ "REGULAR", "ERROR", "TOOLBAR" ], "type": "string" }, "ApplicationVisibility": { "enum": [ "PUBLIC", "UNLISTED" ], "type": "string" }, "ApplicationWithStats": { "required": [ "id", "name", "manifest", "updatedAt", "usersCount" ], "type": "object", "properties": { "id": { "$ref": "#/components/schemas/TypeId" }, "name": { "type": "string" }, "manifest": { "$ref": "#/components/schemas/Manifest" }, "enabled": { "type": "boolean" }, "updatedAt": { "$ref": "#/components/schemas/Instant" }, "usersCount": { "format": "int32", "type": "integer" } } }, "AssignGlobalUsernameRequest": { "description": "Request payload for assigning or unassigning a global username to a channel. Global usernames provide platform-wide access to public channels and must be unique across the entire system.", "type": "object", "properties": { "globalUsername": { "description": "Global username to assign to the channel. Must be unique platform-wide. Set to null to remove the global username. Only available for public channels in public groups.", "type": "string", "example": "platform-updates", "nullable": true } } }, "AsyncRefresh": { "description": "Represents an asynchronous background operation whose status can be polled", "required": [ "id", "category", "status", "createdAt", "updatedAt" ], "type": "object", "properties": { "id": { "description": "Unique identifier for this async refresh", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "category": { "description": "Category of the async operation", "type": "string", "allOf": [ { "$ref": "#/components/schemas/AsyncRefreshCategory" } ] }, "status": { "description": "Current status of the operation", "type": "string", "allOf": [ { "$ref": "#/components/schemas/AsyncRefreshStatus" } ] }, "createdAt": { "description": "When the operation was created", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] }, "updatedAt": { "description": "When the operation status was last updated", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] }, "completedAt": { "description": "When the operation completed (null if not yet completed)", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true }, "error": { "description": "Error message if the operation failed", "type": "string", "nullable": true }, "userId": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "resourceId": { "type": "string", "nullable": true } } }, "AsyncRefreshCategory": { "description": "Category of async refresh operation", "enum": [ "HOME_FEED_REGENERATION", "FASP_SEARCH" ], "type": "string" }, "AsyncRefreshResponse": { "description": "Public API response for async refresh status", "required": [ "id", "category", "status", "createdAt", "updatedAt" ], "type": "object", "properties": { "id": { "description": "Unique identifier for this async refresh", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "category": { "description": "Category of the async operation", "type": "string", "allOf": [ { "$ref": "#/components/schemas/AsyncRefreshCategory" } ] }, "status": { "description": "Current status of the operation", "type": "string", "allOf": [ { "$ref": "#/components/schemas/AsyncRefreshStatus" } ] }, "createdAt": { "description": "When the operation was created", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] }, "updatedAt": { "description": "When the operation status was last updated", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] }, "completedAt": { "description": "When the operation completed (null if not yet completed)", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true }, "error": { "description": "Error message if the operation failed", "type": "string", "nullable": true } } }, "AsyncRefreshStatus": { "description": "Status of an async refresh operation", "enum": [ "PENDING", "IN_PROGRESS", "COMPLETED", "FAILED" ], "type": "string" }, "AsyncRefreshUpdate": { "description": "Websocket payload for a terminal async refresh status update", "required": [ "id", "category", "status", "completedAt" ], "type": "object", "properties": { "id": { "description": "Async refresh ID", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "category": { "description": "Category of async operation", "type": "string", "allOf": [ { "$ref": "#/components/schemas/AsyncRefreshCategory" } ] }, "status": { "description": "Terminal status (COMPLETED or FAILED)", "type": "string", "allOf": [ { "$ref": "#/components/schemas/AsyncRefreshStatus" } ] }, "completedAt": { "description": "Completion timestamp", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] }, "error": { "description": "Error details when status is FAILED", "type": "string", "nullable": true } } }, "Attachment": { "required": [ "id", "description" ], "type": "object", "properties": { "id": { "type": "string" }, "description": { "type": "string", "nullable": true } } }, "AuditLogAction": { "enum": [ "CREATE", "UPDATE", "DELETE", "PURGE", "ROLE_CHANGE", "USERNAME_CHANGE", "EMAIL_CHANGE", "PHONE_CHANGE", "STATE_CHANGE", "APPROVE", "REJECT", "BLOCK", "DEPLOY", "INSTALL", "ENABLE", "DISABLE", "IMPERSONATE_REQUEST", "IMPERSONATE", "ACTION", "JOIN", "LEAVE", "INVITE", "JOIN_REQUEST", "TOKEN_ROTATE" ], "type": "string" }, "AuditLogGroup": { "enum": [ "ACCOUNT", "USER", "APP", "RULE", "SIGNUP", "POST", "DOMAIN_BLOCK", "EMAIL_BLOCK", "EMAIL_ALLOW", "GROUP", "GROUP_MEMBER", "GROUP_QUESTION", "GROUP_BLOCK", "REPORT", "SERVICE", "AIAGENT", "AIAGENT_JOB", "AIAGENT_SIGNAL", "FASP", "FASP_REMOTE", "EMBEDDING", "FEDERATION" ], "type": "string" }, "AuditLogRecord": { "required": [ "logGroup", "logAction", "happenedAt", "ip", "executor", "data" ], "type": "object", "properties": { "logGroup": { "description": "Group of the audit log", "type": "string", "allOf": [ { "$ref": "#/components/schemas/AuditLogGroup" } ], "example": "ACCOUNT" }, "logAction": { "description": "Action performed in the audit log", "type": "string", "allOf": [ { "$ref": "#/components/schemas/AuditLogAction" } ], "example": "CREATE" }, "happenedAt": { "description": "Timestamp when the action happened", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "example": "2023-01-01T00:00:00Z" }, "ip": { "description": "IP address from which the action was performed", "type": "object", "allOf": [ { "$ref": "#/components/schemas/InetAddress" } ] }, "executor": { "description": "Entity that executed the action", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Executor" } ] }, "data": { "description": "Additional data related to the action", "type": "object", "additionalProperties": {} } } }, "AuditLogResult": { "required": [ "list", "total" ], "type": "object", "properties": { "list": { "description": "List of audit log records", "type": "array", "items": { "$ref": "#/components/schemas/AuditLogRecord" } }, "total": { "format": "int32", "description": "Total number of records matching the query", "type": "integer", "example": 42 } } }, "AuthPhoneRequest": { "required": [ "phone" ], "type": "object", "properties": { "phone": { "description": "Phone number", "type": "string", "example": "+12345678901" }, "code": { "format": "int32", "description": "Confirmation code", "type": "integer", "example": 854882, "nullable": true } } }, "AuthRequest": { "description": "Authentication with email/username & password", "required": [ "login", "password" ], "type": "object", "properties": { "login": { "description": "Email or username", "maxLength": 255, "minLength": 1, "type": "string", "example": "john_smith@gmail.com or jonh_smith" }, "password": { "description": "Account's password", "maxLength": 64, "minLength": 1, "type": "string", "example": "PassW0rd!" } } }, "AuthenticatorSelectionCriteria": { "required": [ "authenticatorAttachment", "requireResidentKey", "residentKey", "userVerification" ], "type": "object", "properties": { "authenticatorAttachment": { "type": "string", "nullable": true }, "requireResidentKey": { "type": "boolean", "nullable": true }, "residentKey": { "type": "string", "nullable": true }, "userVerification": { "type": "string", "nullable": true } } }, "BackfillRequest": { "required": [ "category" ], "type": "object", "properties": { "category": { "description": "Content category to backfill", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Category" } ] } } }, "BackfillRequest1": { "required": [ "category" ], "type": "object", "properties": { "category": { "description": "Category to backfill (content/account/group; aliases: posts/users/groups)", "type": "string" } } }, "BackfillView": { "required": [ "id", "category", "fulfilled", "processedCount", "createdAt", "updatedAt" ], "type": "object", "properties": { "id": { "format": "int64", "description": "Backfill request ID", "type": "integer" }, "category": { "description": "Content category", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Category" } ] }, "fulfilled": { "description": "Whether backfill is fulfilled", "type": "boolean" }, "processedCount": { "format": "int32", "description": "Number of items processed", "type": "integer" }, "createdAt": { "description": "When the backfill was requested", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] }, "updatedAt": { "description": "When the backfill was last updated", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] } } }, "Birthday": { "description": "User's birthday preferences", "required": [ "date", "show" ], "type": "object", "properties": { "date": { "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true }, "show": { "$ref": "#/components/schemas/BirthdayShowOptions" } } }, "BirthdayShowOptions": { "enum": [ "NONE", "YEAR", "FULL", "DATE" ], "type": "string" }, "BlockDomainReq": { "description": "Params to block domain", "required": [ "domain", "publicComment" ], "type": "object", "properties": { "domain": { "description": "Domain to block. Can be subdomain, i.e. example.com will block sub.example.com", "pattern": "\\S", "type": "string", "example": "example.com" }, "publicComment": { "description": "A comment visible to the general public", "type": "string", "example": "Violence" }, "state": { "$ref": "#/components/schemas/DomainBlockState" }, "rejectMedia": { "description": "Rejects any media coming from the domain and removes already downloaded. Ignored for SUSPEND", "type": "boolean" }, "rejectReports": { "description": "Ignore all reports coming from this domain. Ignored for SUSPEND", "type": "boolean" }, "privateComment": { "description": "Comment available only for moderators", "type": "string" }, "obfuscate": { "description": "Partially obfuscate the domain name in the list", "type": "boolean" } } }, "BlockEmailRequest": { "description": "Request to block an email pattern", "required": [ "pattern", "reason" ], "type": "object", "properties": { "pattern": { "description": "Email pattern to block (can be full email or domain)", "pattern": "\\S", "type": "string", "example": "baduser@example.com" }, "reason": { "description": "Reason for blocking this email pattern", "pattern": "\\S", "type": "string", "example": "Spam account" } } }, "BlockedDomain": { "required": [ "domain", "publicComment", "state", "rejectMedia", "rejectReports", "privateComment", "obfuscate", "createdAt", "updatedAt" ], "type": "object", "properties": { "domain": { "description": "The blocked domain name. May be obfuscated in public endpoints if obfuscate flag is set.", "type": "string", "example": "spam.example" }, "publicComment": { "description": "Public-facing comment explaining why the domain was blocked", "type": "string", "example": "Repeated spam violations" }, "state": { "description": "The severity level of the domain block", "enum": [ "SUSPEND", "LIMIT", "NOOP" ], "type": "string" }, "rejectMedia": { "description": "Whether to reject and remove media files from this domain", "type": "boolean", "example": true }, "rejectReports": { "description": "Whether to ignore reports coming from this domain", "type": "boolean", "example": false }, "privateComment": { "description": "Internal comment visible only to moderators and administrators", "type": "string", "example": "Multiple verified spam reports from trusted instances" }, "obfuscate": { "description": "Whether to partially obfuscate the domain name in public listings", "type": "boolean", "example": false }, "createdAt": { "description": "Timestamp when the domain block was created", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "example": "2024-01-15T10:30:00Z" }, "updatedAt": { "description": "Timestamp when the domain block was last updated", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "example": "2024-01-16T14:20:00Z" } } }, "BulkImport": { "required": [ "bulkImportId", "userId", "type", "state", "overwrite", "originalFilename", "likelyMismatched", "totalItems", "importedItems", "processedItems", "createdAt", "updatedAt" ], "type": "object", "properties": { "bulkImportId": { "format": "int64", "type": "integer" }, "userId": { "$ref": "#/components/schemas/TypeId" }, "type": { "$ref": "#/components/schemas/BulkImportType" }, "state": { "$ref": "#/components/schemas/BulkImportState" }, "overwrite": { "type": "boolean" }, "originalFilename": { "type": "string", "nullable": true }, "likelyMismatched": { "type": "boolean" }, "totalItems": { "format": "int64", "type": "integer", "nullable": true }, "importedItems": { "format": "int64", "type": "integer", "nullable": true }, "processedItems": { "format": "int64", "type": "integer", "nullable": true }, "createdAt": { "$ref": "#/components/schemas/Instant" }, "updatedAt": { "$ref": "#/components/schemas/Instant" } } }, "BulkImportState": { "enum": [ "PENDING", "SCHEDULED", "IN_PROGRESS", "COMPLETED" ], "type": "string" }, "BulkImportType": { "enum": [ "FOLLOWING", "BLOCK", "MUTE", "DOMAIN_BLOCK", "BOOKMARKS", "LISTS" ], "type": "string" }, "CPCertification": { "description": "Candidate's Certifications", "required": [ "name", "authority", "dateObtained" ], "type": "object", "properties": { "name": { "description": "The name of the certificate", "maxLength": 256, "type": "string", "nullable": true }, "authority": { "description": "The name of the authority that granted the certificate", "maxLength": 256, "type": "string", "nullable": true }, "dateObtained": { "description": "The date the certificate was obtained", "type": "string", "allOf": [ { "$ref": "#/components/schemas/LocalDate" } ], "nullable": true } } }, "CPContact": { "description": "Candidate's Contact Info", "type": "object", "properties": { "email": { "description": "Candidate's email", "maxLength": 256, "pattern": "^[A-Za-z0-9+_.-]+@(.+)$", "type": "string", "nullable": true }, "phone": { "description": "Candidate's phone number", "maxLength": 32, "pattern": "^\\+[1-9]{1}[0-9\\s]{3,14}$", "type": "string", "nullable": true }, "website": { "description": "Candidate's website", "maxLength": 256, "pattern": "^(https?|ftp)://[^\\s/$.?#].[^\\s]*$", "type": "string", "nullable": true }, "linkedin": { "description": "Candidate's linkedin", "maxLength": 128, "pattern": "^(https?|ftp)://[^\\s/$.?#].[^\\s]*$", "type": "string", "nullable": true }, "github": { "description": "Candidate's github", "maxLength": 128, "pattern": "^(https?|ftp)://[^\\s/$.?#].[^\\s]*$", "type": "string", "nullable": true }, "bitbucket": { "description": "Candidate's bitbucket", "maxLength": 128, "pattern": "^(https?|ftp)://[^\\s/$.?#].[^\\s]*$", "type": "string", "nullable": true }, "x": { "description": "Candidate's X", "maxLength": 128, "pattern": "^(https?|ftp)://[^\\s/$.?#].[^\\s]*$", "type": "string", "nullable": true } } }, "CPCourse": { "description": "Candidate's courses", "required": [ "name", "institution", "startDate" ], "type": "object", "properties": { "name": { "description": "The name of the course", "maxLength": 256, "type": "string", "nullable": true }, "institution": { "description": "The name of the institution/organization supplying the course", "maxLength": 256, "type": "string", "nullable": true }, "startDate": { "description": "The start date", "type": "string", "allOf": [ { "$ref": "#/components/schemas/LocalDate" } ], "nullable": true }, "endDate": { "description": "The graduation/end date", "type": "string", "allOf": [ { "$ref": "#/components/schemas/LocalDate" } ], "nullable": true } } }, "CPData": { "description": "Employee Profile data", "required": [ "firstName", "lastName", "contact", "location", "occupation" ], "type": "object", "properties": { "firstName": { "description": "The first name of the employee", "maxLength": 64, "type": "string", "nullable": true }, "lastName": { "description": "The last name of the employee", "maxLength": 64, "type": "string", "nullable": true }, "fullName": { "description": "The full name of the candidate", "maxLength": 129, "type": "string", "nullable": true }, "contact": { "description": "Contact information. Phones, emails, websites, etc...", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CPContact" } ], "nullable": true }, "location": { "description": "Location/Address", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CPLocation" } ], "nullable": true }, "occupation": { "description": "Current title/position/job", "maxLength": 128, "type": "string", "nullable": true }, "personal": { "description": "Any relevant personal information", "maxLength": 4092, "type": "string", "nullable": true }, "summary": { "description": "Summary of candidate's offering and goals", "maxLength": 4092, "type": "string", "nullable": true }, "skills": { "description": "The list of candidate's skills", "maxItems": 128, "type": "array", "items": { "$ref": "#/components/schemas/CPSkill" }, "nullable": true }, "history": { "description": "The list of candidate's previous jobs", "maxItems": 64, "type": "array", "items": { "$ref": "#/components/schemas/CPHistory" }, "nullable": true }, "education": { "description": "The list of candidate's education items", "maxItems": 64, "type": "array", "items": { "$ref": "#/components/schemas/CPEducation" }, "nullable": true }, "courses": { "description": "The list of candidate's completed courses", "maxItems": 64, "type": "array", "items": { "$ref": "#/components/schemas/CPCourse" }, "nullable": true }, "languages": { "description": "The list of candidate's languages", "maxItems": 32, "type": "array", "items": { "$ref": "#/components/schemas/CPLanguage" }, "nullable": true }, "certifications": { "description": "The list of candidate's certification", "maxItems": 64, "type": "array", "items": { "$ref": "#/components/schemas/CPCertification" }, "nullable": true }, "projects": { "description": "The list of candidate's projects", "maxItems": 64, "type": "array", "items": { "$ref": "#/components/schemas/CPProject" }, "nullable": true } } }, "CPEducation": { "description": "Candidate's Education", "required": [ "school", "degree", "location", "startDate" ], "type": "object", "properties": { "school": { "description": "The name of the school", "maxLength": 128, "type": "string", "nullable": true }, "degree": { "description": "The earned degree", "maxLength": 128, "type": "string", "nullable": true }, "location": { "description": "The location of the school", "maxLength": 128, "type": "string", "nullable": true }, "startDate": { "description": "The start date", "type": "string", "allOf": [ { "$ref": "#/components/schemas/LocalDate" } ], "nullable": true }, "endDate": { "description": "The graduation/end date", "type": "string", "allOf": [ { "$ref": "#/components/schemas/LocalDate" } ], "nullable": true }, "description": { "description": "The additional description", "maxLength": 4092, "type": "string", "nullable": true } } }, "CPHistory": { "description": "Candidate's Work history", "required": [ "title", "company", "location", "startDate" ], "type": "object", "properties": { "title": { "description": "Position held/Title", "maxLength": 256, "type": "string", "nullable": true }, "company": { "description": "Company name", "maxLength": 256, "type": "string", "nullable": true }, "location": { "description": "Company location/country/state/city", "maxLength": 128, "type": "string", "nullable": true }, "startDate": { "description": "Candidate's start date for the position", "type": "string", "allOf": [ { "$ref": "#/components/schemas/LocalDate" } ], "nullable": true }, "endDate": { "description": "Candidate's end date for the position", "type": "string", "allOf": [ { "$ref": "#/components/schemas/LocalDate" } ], "nullable": true }, "description": { "description": "The position description, candidate's responsibilities, etc.", "maxLength": 9184, "type": "string", "nullable": true } } }, "CPLanguage": { "description": "Candidate's Languages", "required": [ "name", "level" ], "type": "object", "properties": { "name": { "description": "The official name of language", "maxLength": 64, "type": "string", "nullable": true }, "level": { "description": "The mastery level achieved", "maxLength": 64, "type": "string", "nullable": true } } }, "CPLocation": { "description": "Candidate's CPLocation/Address Info", "required": [ "city", "stateProvince", "country" ], "type": "object", "properties": { "city": { "description": "Candidate's city", "maxLength": 64, "type": "string", "nullable": true }, "stateProvince": { "description": "Candidate's state/province", "maxLength": 64, "type": "string", "nullable": true }, "country": { "description": "Candidate's country", "maxLength": 64, "type": "string", "nullable": true }, "postcode": { "description": "Candidate's postal code", "maxLength": 32, "type": "string", "nullable": true }, "timezone": { "description": "Candidate's time zone", "maxLength": 32, "type": "string", "nullable": true } } }, "CPProject": { "description": "Candidate's Projects", "required": [ "name" ], "type": "object", "properties": { "name": { "description": "The name of the project", "maxLength": 256, "type": "string", "nullable": true }, "description": { "description": "The description of the project", "maxLength": 4092, "type": "string", "nullable": true }, "url": { "description": "The URL/website of the project", "maxLength": 256, "type": "string", "nullable": true } } }, "CPSkill": { "description": "Candidate's skill", "required": [ "name", "level" ], "type": "object", "properties": { "name": { "description": "Skill name", "maxLength": 128, "type": "string", "nullable": true }, "level": { "description": "Mastery level", "maxLength": 64, "type": "string", "nullable": true } } }, "Capability": { "required": [ "id", "version" ], "type": "object", "properties": { "id": { "type": "string" }, "version": { "type": "string" }, "enabled": { "type": "boolean" } } }, "CapabilityView": { "required": [ "id", "version", "enabled" ], "type": "object", "properties": { "id": { "description": "Capability ID", "type": "string" }, "version": { "description": "Capability version", "type": "string" }, "enabled": { "description": "Whether capability is enabled", "type": "boolean" } } }, "CaptchaVerificationParams": { "description": "Params to verify captcha", "required": [ "hash", "captchaToken" ], "type": "object", "properties": { "hash": { "description": "Registration hash", "pattern": "\\S", "type": "string", "example": "aaaaaaa-ccccccccccccc-wwwwwwwww" }, "captchaToken": { "description": "Captcha token", "pattern": "\\S", "type": "string", "example": "10010101-aaaa-bbbb-cccc-100000000001" } } }, "Card": { "description": "Link preview card for displaying metadata about an external URL embedded in a post", "required": [ "url", "title", "description", "icon", "image", "imageAlt", "publisher", "createdAt", "expiresAt" ], "type": "object", "properties": { "url": { "description": "URL being referenced", "type": "string", "nullable": true }, "title": { "description": "Title of the linked resource", "type": "string", "nullable": true }, "description": { "description": "Description of the linked resource", "type": "string", "nullable": true }, "icon": { "description": "Favicon URL", "type": "string", "nullable": true }, "image": { "description": "Preview image URL", "type": "string", "nullable": true }, "imageAlt": { "description": "Alt text for the preview image", "type": "string", "nullable": true }, "publisher": { "description": "Information about the website/provider", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Publisher" } ], "nullable": true }, "oembedHtml": { "description": "HTML snippet to embed the link (from oEmbed), e.g., an iframe", "type": "string", "nullable": true }, "createdAt": { "description": "When the card data was fetched/created", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] }, "expiresAt": { "description": "When the card data should be considered stale", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true } } }, "Category": { "enum": [ "content", "account", "group", "unknown" ], "type": "string" }, "ChangeUserState": { "description": "Request to change a user's moderation state. Used for suspending, limiting, or reactivating user accounts.", "required": [ "newState", "userId" ], "type": "object", "properties": { "newState": { "description": "New moderation state for the user(s).", "type": "string", "allOf": [ { "$ref": "#/components/schemas/UserState" } ], "example": "SUSPENDED" }, "reportId": { "description": "Optional report ID if this action is in response to a moderation report.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "report_01234567890abcdef", "nullable": true }, "reason": { "description": "Optional reason for the state change. Limited to 120 characters. Logged in audit trail.", "maxLength": 120, "minLength": 1, "type": "string", "example": "Violation of community guidelines - spam behavior", "nullable": true }, "userId": { "description": "User ID to change state for. Must be a valid USER type TypeId.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "user_01234567890abcdef" } } }, "ChangeUserStateBase": { "description": "Base request for changing user moderation state.", "required": [ "newState" ], "type": "object", "properties": { "newState": { "description": "New moderation state for the user(s).", "type": "string", "allOf": [ { "$ref": "#/components/schemas/UserState" } ], "example": "SUSPENDED" }, "reportId": { "description": "Optional report ID if this action is in response to a moderation report.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "report_01234567890abcdef", "nullable": true }, "reason": { "description": "Optional reason for the state change. Limited to 120 characters. Logged in audit trail.", "maxLength": 120, "minLength": 1, "type": "string", "example": "Violation of community guidelines - spam behavior", "nullable": true } } }, "ChangeUserStateBulk": { "description": "Request to change moderation state for multiple users in one operation.", "required": [ "newState", "userIds" ], "type": "object", "properties": { "newState": { "description": "New moderation state for the user(s).", "type": "string", "allOf": [ { "$ref": "#/components/schemas/UserState" } ], "example": "SUSPENDED" }, "reportId": { "description": "Optional report ID if this action is in response to a moderation report.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "report_01234567890abcdef", "nullable": true }, "reason": { "description": "Optional reason for the state change. Limited to 120 characters. Logged in audit trail.", "maxLength": 120, "minLength": 1, "type": "string", "example": "Violation of community guidelines - spam behavior", "nullable": true }, "userIds": { "description": "List of user IDs to change state for. Must be valid USER TypeIds. Maximum 50.", "maxItems": 50, "minItems": 1, "uniqueItems": true, "type": "array", "items": { "$ref": "#/components/schemas/TypeId" } } } }, "ChangeUsersStateResult": { "description": "Result of a bulk user state change operation.", "required": [ "totalRequested", "totalUpdated", "notFound" ], "type": "object", "properties": { "totalRequested": { "format": "int32", "description": "Total number of user IDs requested", "type": "integer" }, "totalUpdated": { "format": "int32", "description": "Total number of users updated in DB", "type": "integer" }, "notFound": { "description": "User IDs that were not found or already deleted", "type": "array", "items": { "$ref": "#/components/schemas/TypeId" } } } }, "ChangeVideoThumbnail": { "description": "Change video thumbnail request. Contains the time in seconds.", "required": [ "time" ], "type": "object", "properties": { "time": { "format": "double", "type": "number" } } }, "Choice": { "description": "A selectable option for single-choice or multiple-choice questions. Each choice has display text and an order value for consistent presentation.", "required": [ "text", "order" ], "type": "object", "properties": { "text": { "description": "The display text for this choice option (max 60 characters)", "maxLength": 60, "pattern": "\\S", "type": "string", "example": "I want to learn from others" }, "order": { "format": "int32", "description": "Display order for this choice (lower values appear first)", "minimum": 0, "type": "integer", "example": 0 } } }, "CodeVerificationParams": { "description": "Params to verify email or phone number", "required": [ "hash", "code" ], "type": "object", "properties": { "hash": { "description": "Registration hash", "pattern": "\\S", "type": "string", "example": "aaaaaaa-ccccccccccccc-wwwwwwwww" }, "code": { "format": "int32", "description": "Confirmation code", "type": "integer", "example": 854882 } } }, "CompatResponse": { "description": "API compatibility information response", "required": [ "breaking_generation", "min_supported_generation", "api_surface" ], "type": "object", "properties": { "breaking_generation": { "format": "int32", "description": "Current backend breaking generation. Monotonically increasing integer that is incremented whenever a breaking API change is introduced.", "type": "integer", "example": 1 }, "min_supported_generation": { "format": "int32", "description": "Minimum generation that clients must have been compiled against to be allowed to operate. Clients compiled against a lower generation must update.", "type": "integer", "example": 1 }, "api_surface": { "description": "Informational string indicating the latest API surface version.", "type": "string", "example": "v1" } } }, "ConfigureFaspRemoteRequest": { "required": [ "baseUrl", "adminToken" ], "type": "object", "properties": { "baseUrl": { "format": "uri", "description": "Base URL of the FASP server", "type": "string" }, "adminToken": { "description": "Admin token for authentication", "type": "string" }, "serverName": { "description": "Friendly name for the FASP server", "type": "string", "nullable": true } } }, "ConfigureRequest": { "required": [ "url" ], "type": "object", "properties": { "url": { "description": "Base URL of the remote link provider (must include http:// or https://)", "type": "string", "example": "https://link.example.com" } } }, "ConfirmationCodeRequest": { "description": "Request body with confirmation code", "required": [ "code" ], "type": "object", "properties": { "code": { "format": "int32", "description": "Confirmation code", "type": "integer", "example": 854882 } } }, "ConversationActiveUser": { "description": "User active in a conversation thread with engagement metrics", "required": [ "userId", "replyCount", "lastPostAt" ], "type": "object", "properties": { "userId": { "description": "User ID", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "avatar": { "description": "User's avatar upload", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Upload" } ], "nullable": true }, "replyCount": { "format": "int32", "description": "Number of replies by this user in the thread", "type": "integer" }, "lastPostAt": { "description": "Timestamp of user's most recent post in the thread", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] } } }, "ConversationActiveUserSortBy": { "description": "Sort options for conversation active users", "enum": [ "REPLY_COUNT", "LAST_POST" ], "type": "string" }, "ConversationActiveUsersResult": { "description": "List of users active in a conversation thread", "required": [ "users", "count", "totalCount" ], "type": "object", "properties": { "users": { "description": "Active users in the thread", "type": "array", "items": { "$ref": "#/components/schemas/ConversationActiveUser" } }, "count": { "format": "int32", "description": "Number of active users returned in this page", "type": "integer" }, "totalCount": { "format": "int32", "description": "Total number of active users across all pages", "type": "integer" } } }, "CountryInfo": { "required": [ "flags", "name", "idd" ], "type": "object", "properties": { "flags": { "$ref": "#/components/schemas/Flags" }, "name": { "$ref": "#/components/schemas/Name" }, "idd": { "$ref": "#/components/schemas/Idd" } } }, "CreateEvent": { "description": "Event params for creating new event", "required": [ "name", "startTime", "ianaTimeZone" ], "type": "object", "properties": { "groupId": { "description": "Group id, not required for personal events", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "name": { "description": "Event name", "type": "string", "example": "New Event Name" }, "startTime": { "description": "Event start time in UTC", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "example": "2024-02-18T15:00:00Z" }, "endTime": { "description": "Event end time in UTC", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "example": "2024-02-18T18:00:00Z", "nullable": true }, "ianaTimeZone": { "description": "Event IANA time zone name", "type": "string", "example": "Europe/Paris" }, "description": { "description": "Event's description", "type": "string", "example": "This is a birthday party", "nullable": true }, "url": { "format": "uri", "description": "Event URL", "type": "string", "nullable": true }, "address": { "description": "Event address", "type": "object", "allOf": [ { "$ref": "#/components/schemas/AddressData" } ], "nullable": true }, "imageId": { "description": "Event cover image", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "status": { "description": "Event status", "type": "string", "allOf": [ { "$ref": "#/components/schemas/EventStatus" } ], "example": "CONFIRMED" }, "privacy": { "description": "Event visibility: PUBLIC, UNLISTED or DIRECT", "type": "string", "allOf": [ { "$ref": "#/components/schemas/PostPrivacy" } ], "example": "PUBLIC" }, "invitees": { "description": "Users to invite to an invite-only event", "type": "array", "items": { "$ref": "#/components/schemas/TypeId" }, "nullable": true } } }, "CreatePost": { "description": "Post creation params", "required": [ "text", "privacy", "kind" ], "type": "object", "properties": { "text": { "description": "Post text", "type": "string", "example": "Hello World" }, "privacy": { "description": "Post privacy", "type": "string", "allOf": [ { "$ref": "#/components/schemas/PostPrivacy" } ], "example": "PUBLIC" }, "kind": { "description": "Note or Article", "type": "string", "allOf": [ { "$ref": "#/components/schemas/PostKind" } ], "example": "Note" }, "attachments": { "description": "List with upload ids of attachments", "maxItems": 256, "type": "array", "items": { "$ref": "#/components/schemas/TypeId" }, "nullable": true }, "poll": { "description": "Poll parameters", "type": "object", "allOf": [ { "$ref": "#/components/schemas/PollCreate" } ], "nullable": true }, "commentsEnabled": { "description": "Enable/disable comments for the post", "type": "boolean" }, "sensitive": { "description": "Mark status and attached media as sensitive. contentWarning should be provided when this flag is true. Defaults to false.", "type": "boolean" }, "contentWarning": { "description": "Content warning. The post content and media will be hidden under the warning.", "type": "string", "nullable": true }, "ownerId": { "description": "Null if regular post. event_id for events", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "title": { "description": "Title of a post", "type": "string", "nullable": true }, "tags": { "description": "List of tags. The other way to add tags is using '#' hashtags in text", "type": "array", "items": { "type": "string" }, "nullable": true }, "withPreview": { "description": "Create Preview Card for for link in the post", "type": "boolean" }, "mediaType": { "description": "Post media type. Default for Note is text/plain, for Article text/markdown", "type": "string", "allOf": [ { "$ref": "#/components/schemas/PostMediaType" } ], "nullable": true }, "imageUploadId": { "description": "Upload ID for the article image (will also be included in attachments)", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "postAsOwner": { "description": "When true, the post is attributed to the group channel specified by ownerId. Only available to channel moderators/admins. Supported for top-level posts and comments.", "type": "boolean" }, "quoteApprovalPolicy": { "description": "Quote approval policy for this post. Omit to use account default. Values: PUBLIC, FOLLOWERS, NOBODY", "type": "string", "allOf": [ { "$ref": "#/components/schemas/QuotePolicyLevel" } ], "nullable": true }, "address": { "description": "Location address for the post", "type": "object", "allOf": [ { "$ref": "#/components/schemas/AddressData" } ], "nullable": true }, "removeAddress": { "description": "Remove existing address from the post", "type": "boolean" } } }, "CreateReport": { "description": "Request to create a new report", "required": [ "comment", "type", "targetId" ], "type": "object", "properties": { "comment": { "description": "Report comment/reason text", "type": "string" }, "type": { "description": "Type/reason for the report", "type": "string", "allOf": [ { "$ref": "#/components/schemas/ReportType" } ] }, "groupId": { "description": "Group context for user reports (optional)", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "gr_01hz1f0kw36f82k9s4nzpc4s92n", "nullable": true }, "targetId": { "description": "Target being reported (post, user, or group TypeId)", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "pt_01hz1f0jkdw3h27a2kdr8sn2kt" }, "uploadIds": { "description": "Attachment upload IDs", "type": "array", "items": { "$ref": "#/components/schemas/TypeId" } }, "forward": { "description": "Whether to forward the report to the remote instance (ignored for group reports)", "type": "boolean" } } }, "CreateTagReportRequest": { "description": "Request to report a tag", "required": [ "reason" ], "type": "object", "properties": { "reason": { "description": "Reason for reporting the tag", "type": "string", "example": "spam/abuse" } } }, "CreateUpload": { "description": "Create upload request", "required": [ "extension" ], "type": "object", "properties": { "extension": { "type": "string" }, "isGzipped": { "type": "boolean" }, "meta": { "description": "User meta attached to upload. Can contain information like name etc.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Meta" } ], "example": { "name": "value" }, "nullable": true }, "tags": { "description": "Tags attached to the upload", "uniqueItems": true, "type": "array", "items": { "$ref": "#/components/schemas/UploadsTags" }, "example": [ "$post", "$avatar" ] }, "privacy": { "description": "Privacy of the upload. Possible values: PUBLIC, PRIVATE, DIRECT.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/UploadPrivacy" } ], "example": "PUBLIC", "nullable": true }, "allowedUsers": { "description": "\n Can contain a list of users who are allowed to access the upload.\n Works only for uploads with privacy set to DIRECT.\n ", "uniqueItems": true, "type": "array", "items": { "type": "string" }, "nullable": true }, "ownerId": { "description": "Optional owner entity for this upload. When not provided, defaults to the uploading user. Can be a channel, category, or event TypeID. The uploader must have permission to upload for this owner.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "us_97234khddqdkuhqwij", "nullable": true } } }, "CreateUploadFromRemote": { "description": "Create upload from remote request", "required": [ "originalFile" ], "type": "object", "properties": { "originalFile": { "$ref": "#/components/schemas/RemoteFileInfo" }, "otherFiles": { "type": "array", "items": { "$ref": "#/components/schemas/RemoteFileInfo" } }, "meta": { "description": "Can contain any meta information about the upload", "type": "object", "additionalProperties": {}, "nullable": true }, "tags": { "uniqueItems": true, "type": "array", "items": { "$ref": "#/components/schemas/UploadsTags" } } } }, "CreateUploadResult": { "description": "Result of creating an upload. Contains the upload URI and the upload object.", "required": [ "uri", "upload" ], "type": "object", "properties": { "uri": { "format": "uri", "type": "string" }, "upload": { "$ref": "#/components/schemas/Upload" } } }, "DataCreate": { "required": [ "ownerId", "type", "data" ], "type": "object", "properties": { "ownerId": { "description": "Owner identifier of the data. Can be a user ID, group ID, user-in-group format userId:groupId, or 'platform'", "type": "string", "example": "usr_01hq8c8em5hj1vr2f4h1t9db9q" }, "type": { "description": "Type identifier for categorizing the data", "type": "string", "example": "user_profile" }, "tags": { "description": "Optional list of tags for additional categorization", "type": "array", "items": { "type": "string" }, "example": [ "personal", "profile" ], "nullable": true }, "data": { "description": "JSON string containing the actual data payload", "type": "string", "example": "{\"name\": \"John Doe\", \"bio\": \"Developer\"}" } } }, "DeepSyncResponse": { "description": "Response from a deep sync trigger", "required": [ "syncState" ], "type": "object", "properties": { "syncState": { "description": "Current sync state of the remote user", "type": "string", "allOf": [ { "$ref": "#/components/schemas/SyncState" } ], "nullable": true } } }, "DeleteUploadResponse": { "description": "Delete upload response", "required": [ "id" ], "type": "object", "properties": { "id": { "description": "ID of deleted upload", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] } } }, "DeviceKeys": { "required": [ "p256dh", "auth" ], "type": "object", "properties": { "p256dh": { "description": "Base64url-encoded P-256 ECDH public key", "pattern": "[A-Za-z0-9_-]+", "type": "string" }, "auth": { "description": "Base64url-encoded auth secret (16 bytes)", "pattern": "[A-Za-z0-9_-]+", "type": "string" } } }, "DevicePlatform": { "enum": [ "android", "ios", "web" ], "type": "string" }, "DeviceRegistrationRequest": { "required": [ "deviceId", "fcmToken", "endpoint", "keys", "platform" ], "type": "object", "properties": { "deviceId": { "description": "Unique device identifier from client (FID)", "maxLength": 255, "pattern": "\\S", "type": "string" }, "fcmToken": { "description": "Firebase Cloud Messaging token", "maxLength": 1024, "pattern": "\\S", "type": "string" }, "endpoint": { "description": "Push service endpoint URL", "maxLength": 2048, "pattern": "https://.*", "type": "string" }, "keys": { "description": "Encryption keys for push messages", "type": "object", "allOf": [ { "$ref": "#/components/schemas/DeviceKeys" } ] }, "platform": { "description": "Device platform", "type": "string", "allOf": [ { "$ref": "#/components/schemas/DevicePlatform" } ] }, "device": { "description": "Optional device description", "maxLength": 255, "type": "string", "nullable": true } } }, "DomainBlockState": { "description": "\n Registration mode:\n * SUSPEND - removes all content, media, and profile data for this domain's accounts from your server.\n * LIMIT - makes posts from accounts at this domain invisible to anyone who isn't following them.\n * NOOP - when you just want to reject media files or reports.\n ", "enum": [ "SUSPEND", "LIMIT", "NOOP" ], "type": "string" }, "DomainBlocksAccess": { "enum": [ "NONE", "USER", "ALL" ], "type": "string" }, "Draft": { "required": [ "id", "userId", "ownerId", "items", "createdAt", "updatedAt" ], "type": "object", "properties": { "id": { "description": "internal draft id", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "userId": { "description": "ID of the user who owns this draft", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "ownerId": { "description": "Owner context where this draft will be published", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "items": { "description": "Draft items (single post or chain)", "type": "array", "items": { "$ref": "#/components/schemas/CreatePost" } }, "createdAt": { "description": "When the draft was created", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] }, "updatedAt": { "description": "When the draft was last updated", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] } } }, "EPData": { "description": "Employer Profile data", "required": [ "name", "industry", "size" ], "type": "object", "properties": { "name": { "description": "The name of the company/firm", "maxLength": 256, "type": "string", "nullable": true }, "industry": { "description": "The industry", "maxLength": 128, "type": "string", "nullable": true }, "size": { "format": "int32", "description": "The number of employees", "maximum": 100000000, "minimum": 1, "type": "integer", "nullable": true }, "yearFounded": { "format": "int32", "description": "The year of the company foundation", "maximum": 2050, "minimum": 999, "type": "integer", "nullable": true }, "website": { "description": "The company's website", "maxLength": 256, "pattern": "^(https?|ftp)://[^\\s/$.?#].[^\\s]*$", "type": "string", "nullable": true }, "description": { "description": "The company's free text description", "maxLength": 9184, "type": "string", "nullable": true }, "specialties": { "description": "The list of company specialties", "maxItems": 128, "type": "array", "items": { "type": "string" }, "nullable": true }, "location": { "description": "The company's location/address", "type": "object", "allOf": [ { "$ref": "#/components/schemas/EPLocation" } ], "nullable": true } } }, "EPLocation": { "description": "Employer Profile location", "required": [ "city", "stateProvince", "country", "timezone", "postcode" ], "type": "object", "properties": { "city": { "description": "The company's home city/town", "maxLength": 256, "type": "string", "nullable": true }, "stateProvince": { "description": "The company's state/province/region", "maxLength": 256, "type": "string", "nullable": true }, "country": { "description": "The company's country", "maxLength": 256, "type": "string", "nullable": true }, "timezone": { "description": "The company's time zone", "maxLength": 32, "type": "string", "nullable": true }, "postcode": { "description": "The company's postal code", "maxLength": 64, "type": "string", "nullable": true } } }, "Ed25519PublicKey": { "required": [ "key" ], "type": "object", "properties": { "key": { "$ref": "#/components/schemas/Ed25519PublicKeyParameters" }, "encoded": { "format": "binary", "type": "string" } } }, "Ed25519PublicKeyParameters": { "type": "object", "properties": { "privateKey": { "type": "boolean" }, "private": { "type": "boolean" }, "publicPoint": { "$ref": "#/components/schemas/PublicPoint" }, "encoded": { "format": "binary", "type": "string" } } }, "EditReportComment": { "description": "Request to edit your existing comment on a report", "required": [ "comment", "type" ], "type": "object", "properties": { "comment": { "description": "Updated report comment/reason text", "type": "string" }, "type": { "description": "Updated type/reason for the report", "type": "string", "allOf": [ { "$ref": "#/components/schemas/ReportType" } ] }, "uploadIds": { "description": "Updated attachment upload IDs", "type": "array", "items": { "$ref": "#/components/schemas/TypeId" } } } }, "EmailBlock": { "description": "Represents a blocked email pattern used to prevent signups", "required": [ "pattern", "reason", "createdAt" ], "type": "object", "properties": { "pattern": { "description": "The normalized email pattern that is blocked. Can be a specific email or a domain", "type": "string", "example": "spam-domain.com" }, "reason": { "description": "The reason why this email pattern was blocked", "type": "string", "example": "Known spam domain" }, "createdAt": { "description": "Timestamp when the email block was created", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "example": "2024-01-15T10:30:00Z" } } }, "EmailChangeRequest": { "description": "Params to change account email", "required": [ "newEmail", "password" ], "type": "object", "properties": { "newEmail": { "description": "New email", "type": "string", "example": "john_smith@gmail.com" }, "password": { "description": "Current account password", "maxLength": 64, "minLength": 1, "type": "string", "example": "PassW0rd!" } } }, "EmbeddingConfigUpdate": { "description": "Request to update embedding configuration", "required": [ "enabled", "modelId" ], "type": "object", "properties": { "enabled": { "description": "Whether to enable or disable embeddings", "type": "boolean" }, "modelId": { "description": "Model ID to use for embeddings (required if enabling)", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } }, "EmbeddingCostEstimate": { "description": "Cost estimate for embedding generation", "required": [ "modelId", "modelExternalId", "modelName", "postsToProcess", "estimatedTokens", "estimatedCostUsd", "inputPer1MTokens", "vectorDimensions", "isFullRecalculation" ], "type": "object", "properties": { "modelId": { "description": "Model ID used for estimation", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "modelExternalId": { "description": "Model external ID (e.g., text-embedding-3-small)", "type": "string" }, "modelName": { "description": "Model name", "type": "string" }, "postsToProcess": { "format": "int64", "description": "Number of posts to process", "type": "integer" }, "estimatedTokens": { "format": "int64", "description": "Estimated total tokens", "type": "integer" }, "estimatedCostUsd": { "format": "double", "description": "Estimated cost in USD", "type": "number" }, "inputPer1MTokens": { "format": "double", "description": "Price per 1M input tokens in USD", "type": "number", "nullable": true }, "vectorDimensions": { "format": "int32", "description": "Vector dimensions for this model", "type": "integer" }, "isFullRecalculation": { "description": "Whether this is a full recalculation (new model) or partial (only missing embeddings)", "type": "boolean" } } }, "EmbeddingStatus": { "description": "Complete embedding system status", "required": [ "enabled", "modelId", "modelExternalId", "modelName", "vectorDimensions", "totalPosts", "postsWithEmbeddings", "postsNeedingEmbeddings", "recalculation" ], "type": "object", "properties": { "enabled": { "description": "Whether embeddings are enabled", "type": "boolean" }, "modelId": { "description": "Current model ID (null if not configured)", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "modelExternalId": { "description": "Current model external ID (e.g., text-embedding-3-small)", "type": "string", "nullable": true }, "modelName": { "description": "Current model name", "type": "string", "nullable": true }, "vectorDimensions": { "format": "int32", "description": "Current vector dimensions", "type": "integer", "nullable": true }, "totalPosts": { "format": "int64", "description": "Total posts in the system", "type": "integer" }, "postsWithEmbeddings": { "format": "int64", "description": "Posts that have embeddings", "type": "integer" }, "postsNeedingEmbeddings": { "format": "int64", "description": "Posts that need embeddings generated", "type": "integer" }, "recalculation": { "description": "Current recalculation job progress (null if no job running)", "type": "object", "allOf": [ { "$ref": "#/components/schemas/RecalculationInfo" } ], "nullable": true } } }, "Emoji": { "required": [ "shortcode", "category", "url", "staticUrl", "visibleInPicker" ], "type": "object", "properties": { "shortcode": { "type": "string" }, "category": { "type": "string", "nullable": true }, "url": { "format": "uri", "type": "string" }, "staticUrl": { "type": "string" }, "visibleInPicker": { "type": "boolean" } } }, "EmojiPaginatedResponse": { "required": [ "items", "total", "totalItems" ], "type": "object", "properties": { "items": { "description": "Paginated list of emojis for the current page", "type": "array", "items": { "$ref": "#/components/schemas/Emoji" } }, "total": { "format": "int32", "description": "Total number of emojis that satisfy the filter", "type": "integer" }, "totalItems": { "format": "int32", "description": "Total number of all emojis in the system", "type": "integer" } } }, "EmojiPatchRequest": { "type": "object", "properties": { "category": { "description": "New category for the emoji", "type": "string", "nullable": true }, "visibleInPicker": { "description": "Visibility in emoji picker", "type": "boolean", "nullable": true }, "domain": { "description": "Domain for federated emoji metadata", "type": "string", "nullable": true } } }, "EmployeeProfile": { "description": "The profile of the employee", "required": [ "profileId", "cpData" ], "type": "object", "properties": { "profileId": { "description": "Internal Employer Profile id", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "current": { "description": "Flag marking the 'current' profile", "type": "boolean" }, "cpData": { "description": "Employee Profile data", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CPData" } ] } } }, "EmployerProfile": { "description": "The profile of the employer", "required": [ "profileId", "EPData" ], "type": "object", "properties": { "profileId": { "description": "internal Employer Profile id", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "current": { "description": "Flag marking the 'current' profile", "type": "boolean" }, "EPData": { "description": "Employer Profile data", "type": "object", "allOf": [ { "$ref": "#/components/schemas/EPData" } ] } } }, "EntityStats": { "description": "Common aggregate statistics fields", "required": [ "posts", "postsLast24h", "comments", "totalStorageBytes", "avgPostsPerDay", "avgBytesPerDay" ], "type": "object", "properties": { "posts": { "format": "int64", "description": "Total number of posts", "type": "integer" }, "postsLast24h": { "format": "int64", "description": "Posts created in the last 24 hours", "type": "integer" }, "comments": { "format": "int64", "description": "Total number of comments", "type": "integer" }, "totalStorageBytes": { "format": "int64", "description": "Total uploaded bytes", "type": "integer" }, "avgPostsPerDay": { "format": "double", "description": "Average posts per day over the last 30 days", "type": "number" }, "avgBytesPerDay": { "format": "double", "description": "Average uploaded bytes per day over the last 30 days", "type": "number" } } }, "EntityType": { "enum": [ "USER", "BOT", "APPLICATION", "GROUP_CHANNEL" ], "type": "string" }, "EntryPoint": { "enum": [ "GLOBAL", "USER", "GROUP" ], "type": "string" }, "Event": { "description": "User's Event", "required": [ "id", "uri", "name", "startTime", "timeZoneOffsetSeconds", "stats", "status", "privacy", "translation", "createdAt", "updatedAt", "deletedAt", "lang", "organizer", "cover", "address" ], "type": "object", "properties": { "id": { "description": "Internal event id", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "uri": { "format": "uri", "description": "Unique event uri", "type": "string" }, "groupId": { "description": "Group id", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "name": { "description": "Event's name", "type": "string" }, "startTime": { "description": "Event's start time", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] }, "endTime": { "description": "Event's end time", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true }, "ianaTimeZone": { "description": "Event's IANA time zone", "type": "string", "nullable": true }, "timeZoneOffsetSeconds": { "format": "int32", "description": "Event's time zone offset (in seconds)", "type": "integer" }, "description": { "description": "Event's Markdown description (absent for non-local events)", "type": "string", "nullable": true }, "descriptionHtml": { "description": "Event's HTML description", "type": "string", "nullable": true }, "url": { "format": "uri", "description": "Event's virtual location URL", "type": "string", "nullable": true }, "addressId": { "format": "int32", "description": "Event's address id", "type": "integer", "nullable": true }, "tags": { "description": "Event's tags", "type": "array", "items": { "type": "string" }, "nullable": true }, "mentions": { "description": "Event's mentions", "type": "array", "items": { "format": "uri", "type": "string" }, "nullable": true }, "stats": { "description": "Stats", "type": "object", "allOf": [ { "$ref": "#/components/schemas/EventStats" } ] }, "status": { "description": "Event status", "type": "string", "allOf": [ { "$ref": "#/components/schemas/EventStatus" } ], "example": "CONFIRMED" }, "attendeeStatus": { "description": "Viewer user's event attendance status", "type": "string", "allOf": [ { "$ref": "#/components/schemas/EventAttendeeStatus" } ], "example": "INVITED", "nullable": true }, "commentCount": { "format": "int32", "description": "Event comment count", "type": "integer", "nullable": true }, "privacy": { "$ref": "#/components/schemas/PostPrivacy" }, "translation": { "allOf": [ { "$ref": "#/components/schemas/EventTranslation" } ], "nullable": true }, "createdAt": { "$ref": "#/components/schemas/Instant" }, "updatedAt": { "$ref": "#/components/schemas/Instant" }, "deletedAt": { "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true }, "lang": { "allOf": [ { "$ref": "#/components/schemas/Language" } ], "nullable": true }, "organizer": { "$ref": "#/components/schemas/User" }, "cover": { "allOf": [ { "$ref": "#/components/schemas/Upload" } ], "nullable": true }, "address": { "allOf": [ { "$ref": "#/components/schemas/AddressData" } ], "nullable": true }, "emojis": { "type": "array", "items": { "$ref": "#/components/schemas/Emoji" }, "nullable": true } } }, "EventAttendee": { "description": "Event attendee status", "required": [ "uri", "status" ], "type": "object", "properties": { "user": { "allOf": [ { "$ref": "#/components/schemas/User" } ], "nullable": true }, "uri": { "format": "uri", "type": "string" }, "status": { "$ref": "#/components/schemas/EventAttendeeStatus" } } }, "EventAttendeeStatus": { "description": "\n Event attendee statuses\n\n * INVITED - a user has been invited to an event (for invite-only events only).\n * JOINED - a user has joined and thus attending an event.\n * JOINED_TENTATIVELY - a user has tentatively joined / show an interest in an event.\n * REJECTED - a user has rejected an event invitation, and won't attend an event (for invite-only events only).\n ", "enum": [ "INVITED", "JOINED", "JOINED_TENTATIVELY", "REJECTED" ], "type": "string" }, "EventSearchMode": { "enum": [ "following", "local", "fasp" ], "type": "string" }, "EventStats": { "required": [ "interests", "joins" ], "type": "object", "properties": { "interests": { "format": "int32", "type": "integer" }, "joins": { "format": "int32", "type": "integer" } } }, "EventStatus": { "description": "Event's status", "enum": [ "CONFIRMED", "CANCELLED" ], "type": "string" }, "EventTranslation": { "description": "Event translation", "required": [ "name", "descriptionHtml" ], "type": "object", "properties": { "name": { "type": "string" }, "descriptionHtml": { "type": "string", "nullable": true } } }, "EventsSettings": { "description": "Events app settings", "required": [ "ownerId", "exportPublicCalendar", "exportPublicDetails", "exportPublicEvents", "exportPrivateCalendar", "exportPrivateEvents" ], "type": "object", "properties": { "ownerId": { "description": "Owner ID", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "exportPublicCalendar": { "description": "Enable public calendar export", "type": "boolean" }, "exportPublicDetails": { "description": "Enable public calendar export with full event details", "type": "boolean" }, "exportPublicEvents": { "description": "Events to export in public calendar", "type": "string", "allOf": [ { "$ref": "#/components/schemas/ExportCalendarEvents" } ] }, "exportPrivateCalendar": { "description": "Enable private calendar export", "type": "boolean" }, "exportPrivateEvents": { "description": "Events to export in private calendar", "type": "string", "allOf": [ { "$ref": "#/components/schemas/ExportCalendarEvents" } ] }, "exportPrivateCalendarUniqueId": { "description": "Private calendar unique id", "type": "string", "nullable": true } } }, "Executor": { "type": "object", "properties": { "accountId": { "description": "ID of the account that performed the action", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "ac_01hxcvk1hjexere4pvtrj0ymqq", "nullable": true }, "userId": { "description": "ID of the user that performed the action", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "username": { "description": "Username of the user that performed the action", "type": "string", "example": "john_smith", "nullable": true }, "serviceName": { "description": "Name of the service that performed the action", "type": "string", "example": "system", "nullable": true } } }, "ExportCalendarEvents": { "description": "\n Events to export.\n\n * OWN - export own events only (the only option for groups).\n * JOINED - export own and joined events (not applicable to groups).\n * INTERESTED - export own, joined and events user is interested in (not applicable to groups).\n ", "enum": [ "OWN", "JOINED", "INTERESTED" ], "type": "string" }, "FaspBackfill": { "required": [ "serverId", "serverDomain", "remoteId", "category", "maxCount", "fulfilled", "syncedCount", "createdAt", "updatedAt" ], "type": "object", "properties": { "serverId": { "description": "Server ID on the FASP system", "type": "string" }, "serverDomain": { "description": "Domain of the server", "type": "string" }, "remoteId": { "description": "Remote backfill ID", "type": "string" }, "category": { "description": "Backfill category (content, account, group)", "type": "string" }, "maxCount": { "format": "int32", "description": "Maximum count of items to backfill", "type": "integer" }, "fulfilled": { "description": "Whether the backfill has been fulfilled", "type": "boolean" }, "syncedCount": { "format": "int32", "description": "Number of items synced during the backfill", "type": "integer" }, "createdAt": { "description": "When the backfill was created", "type": "string" }, "updatedAt": { "description": "When the backfill was last updated", "type": "string" } } }, "FaspBackfillsResponse": { "required": [ "backfills" ], "type": "object", "properties": { "backfills": { "description": "List of backfill requests", "type": "array", "items": { "$ref": "#/components/schemas/FaspBackfill" } } } }, "FaspBlocklistResponse": { "required": [ "domains" ], "type": "object", "properties": { "domains": { "description": "List of blocked domains", "type": "array", "items": { "type": "string" } } } }, "FaspDefaultProviderView": { "required": [ "capability", "providerId", "providerName", "providerState", "createdAt", "updatedAt" ], "type": "object", "properties": { "capability": { "description": "Capability name", "type": "string" }, "providerId": { "format": "int64", "description": "Provider ID", "type": "integer" }, "providerName": { "description": "Provider name", "type": "string" }, "providerState": { "description": "Provider state", "type": "string", "allOf": [ { "$ref": "#/components/schemas/FaspProviderState" } ] }, "createdAt": { "description": "When the default was created", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] }, "updatedAt": { "description": "When the default was last updated", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] } } }, "FaspDefaultsResponse": { "required": [ "defaults" ], "type": "object", "properties": { "defaults": { "description": "List of default providers", "type": "array", "items": { "$ref": "#/components/schemas/FaspDefaultProviderView" } } } }, "FaspProviderState": { "enum": [ "PENDING", "ACCEPTED", "BLOCKED" ], "type": "string" }, "FaspProviderView": { "required": [ "id", "state", "name", "baseUrl", "signInUrl", "capabilities", "contactEmail", "fediverseAccount", "subscriptions", "backfills", "lastErrorAt", "createdAt", "updatedAt" ], "type": "object", "properties": { "id": { "format": "int64", "description": "Provider ID", "type": "integer" }, "state": { "description": "Provider state", "type": "string", "allOf": [ { "$ref": "#/components/schemas/FaspProviderState" } ] }, "name": { "description": "Provider name", "type": "string" }, "baseUrl": { "description": "Provider base URL", "type": "string" }, "signInUrl": { "description": "Provider sign-in URL", "type": "string", "nullable": true }, "capabilities": { "description": "Provider capabilities", "type": "array", "items": { "$ref": "#/components/schemas/CapabilityView" } }, "contactEmail": { "description": "Contact email", "type": "string", "nullable": true }, "fediverseAccount": { "description": "Fediverse account", "type": "string", "nullable": true }, "subscriptions": { "description": "Active subscriptions for this provider", "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionView" } }, "backfills": { "description": "Backfill requests for this provider", "type": "array", "items": { "$ref": "#/components/schemas/BackfillView" } }, "lastErrorAt": { "description": "When the last client error occurred (null = healthy)", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true }, "createdAt": { "description": "When the provider was registered", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] }, "updatedAt": { "description": "When the provider was last updated", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] } } }, "FaspProvidersResponse": { "required": [ "providers" ], "type": "object", "properties": { "providers": { "description": "List of FASP providers", "type": "array", "items": { "$ref": "#/components/schemas/FaspProviderView" } } } }, "FaspRegistrationsResponse": { "required": [ "registrations" ], "type": "object", "properties": { "registrations": { "description": "List of server registrations", "type": "array", "items": { "$ref": "#/components/schemas/FaspServerRegistration" } } } }, "FaspRemoteConfigResponse": { "required": [ "configured" ], "type": "object", "properties": { "configured": { "description": "Whether FASP remote is configured", "type": "boolean" }, "baseUrl": { "format": "uri", "description": "Base URL of the FASP server", "type": "string", "nullable": true }, "serverName": { "description": "Friendly name for the FASP server", "type": "string", "nullable": true }, "adminTokenMasked": { "description": "Masked admin token (first 8 chars + ...)", "type": "string", "nullable": true }, "configuredAt": { "description": "When this configuration was set", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true } } }, "FaspRemoteSubscription": { "required": [ "serverId", "serverDomain", "remoteId", "category", "subscriptionType" ], "type": "object", "properties": { "serverId": { "description": "Server ID on the FASP system", "type": "string" }, "serverDomain": { "description": "Domain of the server", "type": "string" }, "remoteId": { "description": "Remote subscription ID", "type": "string" }, "category": { "description": "Subscription category (content, account, group)", "type": "string" }, "subscriptionType": { "description": "Subscription type (lifecycle, trends)", "type": "string" }, "maxBatchSize": { "format": "int32", "description": "Maximum batch size for notifications", "type": "integer", "nullable": true }, "threshold": { "description": "Threshold configuration", "type": "object", "allOf": [ { "$ref": "#/components/schemas/FaspSubscriptionThreshold" } ], "nullable": true } } }, "FaspServerRegistration": { "required": [ "id", "baseUrl", "domain", "status" ], "type": "object", "properties": { "id": { "description": "Server ID on the FASP system", "type": "string" }, "baseUrl": { "format": "uri", "description": "Base URL of the registered server", "type": "string" }, "domain": { "description": "Domain of the registered server", "type": "string" }, "status": { "description": "Registration status", "type": "string", "allOf": [ { "$ref": "#/components/schemas/FaspServerStatus" } ] }, "email": { "description": "Contact email for the server", "type": "string", "nullable": true }, "capabilities": { "description": "Server capabilities", "type": "array", "items": { "type": "string" } } } }, "FaspServerStatus": { "enum": [ "pending", "approved", "blocked" ], "type": "string" }, "FaspSubscriptionThreshold": { "type": "object", "properties": { "timeframe": { "format": "int32", "description": "Timeframe in minutes", "type": "integer", "nullable": true }, "shares": { "format": "int32", "description": "Share count threshold", "type": "integer", "nullable": true }, "likes": { "format": "int32", "description": "Like count threshold", "type": "integer", "nullable": true }, "replies": { "format": "int32", "description": "Reply count threshold", "type": "integer", "nullable": true } } }, "FaspSubscriptionsResponse": { "required": [ "subscriptions" ], "type": "object", "properties": { "subscriptions": { "description": "List of subscriptions", "type": "array", "items": { "$ref": "#/components/schemas/FaspRemoteSubscription" } } } }, "FaspUpdateCheckResponse": { "type": "object", "properties": { "currentVersion": { "description": "Current app version", "type": "string", "nullable": true }, "buildNumber": { "description": "Build number", "type": "string", "nullable": true }, "imageRepo": { "description": "Docker image repository", "type": "string", "nullable": true }, "currentImageTag": { "description": "Current image tag", "type": "string", "nullable": true }, "updateCheckTag": { "description": "Tag used for update checking", "type": "string", "nullable": true }, "currentDigest": { "description": "Current FASP server image digest (nullable when unavailable)", "type": "string", "nullable": true }, "latestDigest": { "description": "Latest available image digest (nullable when unavailable)", "type": "string", "nullable": true }, "latestTag": { "description": "Latest version tag from the registry", "type": "string", "nullable": true }, "updateAvailable": { "description": "Whether an update is available (nullable when unknown)", "type": "boolean", "nullable": true }, "checkedAt": { "description": "When the update was last checked", "type": "string", "nullable": true }, "error": { "description": "Error message from update check", "type": "string", "nullable": true } } }, "FederationConfigRequest": { "description": "Federation config update request", "required": [ "mode", "allowlist" ], "type": "object", "properties": { "mode": { "description": "Target federation mode", "type": "string", "allOf": [ { "$ref": "#/components/schemas/FederationMode" } ] }, "allowlist": { "description": "Full allowlist to apply", "type": "array", "items": { "type": "string" } }, "purgeNonAllowlisted": { "description": "Whether to purge all non-allowlisted content after applying updates", "type": "boolean" } } }, "FederationConfigResponse": { "description": "Federation config response", "required": [ "mode", "allowlist" ], "type": "object", "properties": { "mode": { "description": "Current federation mode", "type": "string", "allOf": [ { "$ref": "#/components/schemas/FederationMode" } ] }, "allowlist": { "description": "Current allowlist", "type": "array", "items": { "type": "string" } } } }, "FederationMode": { "enum": [ "OPEN", "LIMITED", "CLOSED" ], "type": "string" }, "FederationModeRequest": { "description": "Federation mode change request", "required": [ "mode" ], "type": "object", "properties": { "mode": { "description": "Target federation mode", "type": "string", "allOf": [ { "$ref": "#/components/schemas/FederationMode" } ] } } }, "FederationModeResponse": { "description": "Federation mode response", "required": [ "mode" ], "type": "object", "properties": { "mode": { "description": "Current federation mode", "type": "string", "allOf": [ { "$ref": "#/components/schemas/FederationMode" } ] } } }, "FeedCompareResult": { "required": [ "redisIds", "dbIds", "onlyInRedis", "onlyInDb", "orderMismatch", "matchesExact", "redisCount", "dbCount" ], "type": "object", "properties": { "redisIds": { "type": "array", "items": { "$ref": "#/components/schemas/TypeId" } }, "dbIds": { "type": "array", "items": { "$ref": "#/components/schemas/TypeId" } }, "onlyInRedis": { "type": "array", "items": { "$ref": "#/components/schemas/TypeId" } }, "onlyInDb": { "type": "array", "items": { "$ref": "#/components/schemas/TypeId" } }, "orderMismatch": { "type": "boolean" }, "matchesExact": { "type": "boolean" }, "redisCount": { "format": "int32", "type": "integer" }, "dbCount": { "format": "int32", "type": "integer" } } }, "FeedMetrics": { "required": [ "time", "count", "op", "ts" ], "type": "object", "properties": { "time": { "format": "int64", "type": "integer" }, "count": { "format": "int32", "type": "integer" }, "op": { "$ref": "#/components/schemas/FeedOperation" }, "ts": { "$ref": "#/components/schemas/Instant" } } }, "FeedOperation": { "enum": [ "populate", "merge", "unmerge", "redis", "redisLex", "cache", "idsDb", "db", "add", "remove" ], "type": "string" }, "FeedType": { "enum": [ "home" ], "type": "string" }, "FileDesc": { "description": "File of the upload", "required": [ "uri", "fileId", "extension", "original", "meta", "size", "createdAt", "updatedAt", "type" ], "type": "object", "properties": { "uri": { "description": "Full url of the file", "type": "string", "nullable": true }, "fileId": { "description": "File id", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "extension": { "description": "File extension", "type": "string", "example": "mp4" }, "original": { "description": "true if this file is original, false if it is a derivative", "type": "boolean" }, "meta": { "description": "File metadata. Contains optional values for width, height etc.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Meta1" } ] }, "size": { "format": "int64", "description": "File size in bytes", "type": "integer" }, "createdAt": { "$ref": "#/components/schemas/Instant" }, "updatedAt": { "$ref": "#/components/schemas/Instant" }, "type": { "description": "File type", "type": "string", "allOf": [ { "$ref": "#/components/schemas/UploadType" } ], "example": "VIDEO" } } }, "FileExtension": { "description": "File extension", "type": "string", "example": "mp4" }, "FinishCreatingAccountParams": { "description": "Finish creating account with an option to change username", "required": [ "hash" ], "type": "object", "properties": { "hash": { "description": "Registration hash", "pattern": "\\S", "type": "string", "example": "aaaaaaa-ccccccccccccc-wwwwwwwww" }, "username": { "description": "Another username", "type": "string", "nullable": true } } }, "Flags": { "required": [ "png", "svg", "alt" ], "type": "object", "properties": { "png": { "type": "string" }, "svg": { "type": "string" }, "alt": { "type": "string" } } }, "FollowApprovalMode": { "description": "Whether a user manually approves followers or auto-accepts them", "enum": [ "AUTO_APPROVE", "MANUALLY_APPROVES", "UNKNOWN" ], "type": "string" }, "FollowResult": { "required": [ "result" ], "type": "object", "properties": { "result": { "type": "string" } } }, "FollowingStatus": { "enum": [ "PENDING", "ACCEPTED", "REJECTED" ], "type": "string" }, "Geo": { "description": "Coordinates and other geo data", "required": [ "latitude", "longitude" ], "type": "object", "properties": { "latitude": { "format": "double", "type": "number" }, "longitude": { "format": "double", "type": "number" }, "altitude": { "format": "double", "type": "number", "nullable": true }, "accuracy": { "format": "double", "type": "number", "nullable": true }, "verticalAccuracy": { "format": "double", "type": "number", "nullable": true }, "speed": { "format": "double", "type": "number", "nullable": true }, "bearing": { "format": "double", "type": "number", "nullable": true }, "timestamp": { "format": "int64", "type": "integer", "nullable": true } } }, "GeoData": { "description": "Geographic location data including country, city, and timezone information", "type": "object", "properties": { "countryCode": { "description": "ISO country code", "type": "string", "nullable": true }, "country": { "description": "Country name", "type": "string", "nullable": true }, "subdivision": { "description": "Subdivision or state/province name", "type": "string", "nullable": true }, "city": { "description": "City name", "type": "string", "nullable": true }, "timeZone": { "description": "IANA timezone identifier", "type": "string", "nullable": true } } }, "GlobalAggregatedMetrics": { "required": [ "globalAverage", "totalMeasurements", "totalTime", "userCount", "lastUpdated", "operation" ], "type": "object", "properties": { "globalAverage": { "format": "double", "type": "number" }, "totalMeasurements": { "format": "int64", "type": "integer" }, "totalTime": { "format": "int64", "type": "integer" }, "userCount": { "format": "int64", "type": "integer" }, "lastUpdated": { "$ref": "#/components/schemas/Instant" }, "operation": { "$ref": "#/components/schemas/FeedOperation" } } }, "Group": { "description": "Detailed information about a group including internal data", "required": [ "meta", "privacy", "visibility", "joinMode", "groupId", "groupName", "domain", "local", "displayName", "summary", "uri", "publicKey", "type", "membersUrl" ], "type": "object", "properties": { "stats": { "description": "Group statistics", "type": "object", "allOf": [ { "$ref": "#/components/schemas/GroupStats" } ] }, "meta": { "description": "group metadata including color", "type": "object", "allOf": [ { "$ref": "#/components/schemas/GroupMeta" } ] }, "privacy": { "description": "who can access the group's content", "type": "string", "allOf": [ { "$ref": "#/components/schemas/GroupPrivacy" } ] }, "visibility": { "description": "how discoverable the group is", "type": "string", "allOf": [ { "$ref": "#/components/schemas/GroupVisibility" } ] }, "joinMode": { "description": "how users can join the group", "type": "string", "allOf": [ { "$ref": "#/components/schemas/GroupJoinMode" } ] }, "location": { "description": "group's location", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Location" } ], "nullable": true }, "timezone": { "description": "group's timezone", "type": "object", "allOf": [ { "$ref": "#/components/schemas/TimeZone" } ], "nullable": true }, "isMember": { "description": "Whether the current viewer is a member of the group", "type": "boolean", "nullable": true }, "pin": { "format": "int32", "description": "Pin order number if group is pinned by viewer (null if not pinned)", "type": "integer", "nullable": true }, "canManage": { "description": "Whether the current viewer can manage this group (owner, admin, or moderator)", "type": "boolean", "nullable": true }, "isOwner": { "description": "Whether the current viewer is an owner or admin of this group", "type": "boolean", "nullable": true }, "roles": { "description": "Viewer's roles in this group. Only populated in admin endpoints.", "type": "array", "items": { "type": "string" }, "nullable": true }, "groupId": { "description": "internal id of this group", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "groupName": { "description": "unique group name", "type": "string" }, "domain": { "description": "Group's domain", "type": "string" }, "local": { "description": "Whether this group is local to this server", "type": "boolean" }, "displayName": { "description": "full name of the group", "type": "string" }, "summary": { "description": "Group description", "type": "string" }, "uri": { "format": "uri", "description": "URI of this group", "type": "string" }, "publicKey": { "description": "Group's public key for ActivityPub", "type": "string" }, "privateKey": { "description": "Group's private key for ActivityPub", "type": "string", "nullable": true, "writeOnly": true }, "fields": { "description": "Custom fields for the group", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/UserField" } }, "type": { "description": "the type of this group", "type": "string", "allOf": [ { "$ref": "#/components/schemas/GroupType" } ] }, "membersUrl": { "description": "URL to group members", "type": "string" }, "banner": { "description": "Group's header/banner upload", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Upload" } ], "nullable": true }, "avatar": { "description": "Group's avatar", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Upload" } ], "nullable": true }, "deletedAt": { "description": "Group deletion timestamp", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true }, "createdAt": { "description": "Group's creation timestamp", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] }, "updatedAt": { "description": "Group's last update timestamp", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] }, "refreshedAt": { "description": "Group's last refresh timestamp", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] }, "secret": { "type": "boolean" } } }, "GroupBlockCreateRequest": { "description": "Request to create a group block", "type": "object", "properties": { "uri": { "description": "Block by URI (ActivityPub actor URI)", "type": "string", "example": "https://example.com/users/alice", "nullable": true }, "email": { "description": "Block by email address", "type": "string", "example": "user@example.com", "nullable": true }, "username": { "description": "Block by username (local or username@domain format)", "type": "string", "example": "alice@example.com", "nullable": true }, "domain": { "description": "Block by domain", "type": "string", "example": "example.com", "nullable": true }, "userId": { "description": "Block by user ID", "type": "string", "example": "us_01hxcvk1hjexere4pvtrj0ymqq", "nullable": true }, "reason": { "description": "Reason for the block", "type": "string", "example": "Repeated spam violations", "nullable": true }, "preflight": { "description": "Preflight mode - preview affected users without applying changes", "type": "boolean", "example": false } } }, "GroupBlockListResponse": { "description": "List of group blocks with pagination", "required": [ "list", "total" ], "type": "object", "properties": { "list": { "description": "List of blocks", "type": "array", "items": { "$ref": "#/components/schemas/GroupBlockResponse" } }, "total": { "format": "int64", "description": "Total count of blocks", "type": "integer", "example": 42 } } }, "GroupBlockResponse": { "description": "Individual block entry", "required": [ "type", "value", "reason" ], "type": "object", "properties": { "type": { "description": "Type of block", "type": "string", "example": "email" }, "value": { "description": "Value being blocked", "type": "string", "example": "spam@example.com" }, "reason": { "description": "Reason for the block", "type": "string", "example": "Repeated spam violations" } } }, "GroupBlockType": { "enum": [ "URI", "EMAIL", "DOMAIN", "USERNAME", "USERID" ], "type": "string" }, "GroupBrandingUpdate": { "description": "Request payload for updating a group's visual branding elements. All fields are optional - only provide the fields you want to update. Null values are ignored and existing values are preserved.", "type": "object", "properties": { "color": { "description": "Theme color for the group in 6-character HEX format with # prefix. Used for UI theming. Null to keep existing color.", "pattern": "^#[0-9A-Fa-f]{6}$", "type": "string", "example": "#FF5733", "nullable": true }, "bannerId": { "description": "Upload ID of the banner image. Must be a previously uploaded image. Null to keep existing banner.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "up_01hz1f0kw36f82k9s4nzpc4s92n", "nullable": true }, "avatarId": { "description": "Upload ID of the avatar image. Must be a previously uploaded image. Null to keep existing avatar.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "up_01hz1f0kw36f82k9s4nzpc4s92n", "nullable": true } } }, "GroupChannelCreateRequest": { "description": "Request payload for creating a new channel within a group. Channels are specialized users that enable organized content distribution within groups. They support both public and private visibility, with automatic constraints based on the parent group's privacy settings.", "required": [ "username", "displayName" ], "type": "object", "properties": { "username": { "description": "Channel identifier scoped to the group. Must be unique within the group. Used to generate the channel's username in format 'groupname:channelname' for private channels.", "pattern": "\\S", "type": "string", "example": "news" }, "displayName": { "description": "Human-readable display name for the channel. Shown in channel listings and UI.", "pattern": "\\S", "type": "string", "example": "Group News" }, "summary": { "description": "Brief description of the channel's purpose and content (max 1024 characters)", "maxLength": 1024, "type": "string", "example": "Read group news and announcements here" }, "privacy": { "description": "Channel privacy level. PUBLIC channels are visible to everyone, PRIVATE channels only to group members. Private groups can only have private channels.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/GroupChannelPrivacy" } ], "example": "PUBLIC" }, "isPrimary": { "description": "Whether this channel should be the primary channel for the group. Only one primary channel allowed per group. The first channel created is automatically made primary.", "default": false, "type": "boolean", "example": false }, "isAutoSubscribe": { "description": "Whether this channel should be an auto-subscribe channel. Auto-subscribe channels are automatically followed by new group members. The first channel created is automatically made auto-subscribe.", "default": false, "type": "boolean", "example": true }, "globalUsername": { "description": "Global username for public channels. Must be unique across the entire platform. Allows the channel to be accessed via '@globalUsername' in addition to the scoped username. Only available for public channels in public groups.", "type": "string", "example": "platform-news", "nullable": true }, "color": { "description": "Theme color for the channel in 6-character HEX format with # prefix", "pattern": "^#[0-9A-Fa-f]{6}$", "type": "string", "example": "#FF5733", "nullable": true }, "subscribeExistingMembers": { "description": "When creating an auto-subscribe channel, whether to subscribe all existing group members. Default: true.", "type": "boolean", "nullable": true }, "kind": { "description": "Kind of channel: 'channel' for regular group channels, 'category' for forum categories. When set to 'category', the 'wellesley.group.forum' namespace is written to app_meta, making the channel filterable via appMetaHas/appMetaLacks. Default: channel.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/GroupChannelKind" } ], "example": "channel" } } }, "GroupChannelKind": { "description": "\n Distinguishes regular group channels from forum-category channels.\n * CHANNEL - A regular group channel for posting content.\n * CATEGORY - A forum category channel for threaded discussions.\n ", "enum": [ "channel", "category" ], "type": "string" }, "GroupChannelPrivacy": { "description": "\n * PUBLIC - Channel is visible to everyone and can be followed by anyone.\n * PRIVATE - Channel is visible only to group members and can only be followed by group members.\n ", "enum": [ "PUBLIC", "PRIVATE" ], "type": "string" }, "GroupChannelUpdateRequest": { "description": "Request payload for updating an existing group channel. Only include fields that need to be modified. Null fields are ignored, preserving existing values. Changes to privacy settings are constrained by the parent group's privacy level.", "type": "object", "properties": { "displayName": { "description": "New display name for the channel. Updates how the channel appears in UI.", "type": "string", "example": "Group Announcements", "nullable": true }, "summary": { "description": "New channel description (max 1024 characters)", "maxLength": 1024, "type": "string", "example": "Important announcements and updates", "nullable": true }, "privacy": { "description": "New privacy level. Cannot make a channel public if the parent group is private. Changing from public to private affects visibility and access.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/GroupChannelPrivacy" } ], "example": "PRIVATE", "nullable": true }, "isAutoSubscribe": { "description": "Whether this channel should be an auto-subscribe channel (auto-followed by new members)", "type": "boolean", "example": true, "nullable": true }, "avatarId": { "description": "Upload ID for the channel avatar image. Must be a previously uploaded image. Set to null to remove the avatar.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "headerId": { "description": "Upload ID for the channel header/banner image. Must be a previously uploaded image. Set to null to remove the header.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "fields": { "description": "Channel profile fields (key-value pairs for additional information)", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/UserField" }, "nullable": true }, "location": { "description": "Channel location information", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Location" } ], "nullable": true }, "timezone": { "description": "Channel timezone preferences", "type": "object", "allOf": [ { "$ref": "#/components/schemas/TimeZone" } ], "nullable": true }, "groupUsername": { "description": "New group-scoped username (channel slug). Must be unique within the group. Used to generate the channel's scoped username in format 'groupname:channelname'. This is the channel identifier within the group context.", "type": "string", "example": "news", "nullable": true }, "globalUsername": { "description": "Global username for the channel. Must be unique platform-wide. Only available for public channels in public groups. Null or omitted means no change. To remove the global username, use the dedicated PUT /channels/{channelId}/username endpoint.", "type": "string", "example": "platform-news", "nullable": true }, "color": { "description": "Theme color for the channel in 6-character HEX format with # prefix", "pattern": "^#[0-9A-Fa-f]{6}$", "type": "string", "example": "#FF5733", "nullable": true }, "subscribeExistingMembers": { "description": "When enabling auto-subscribe, whether to subscribe existing members. Only applies when isAutoSubscribe changes to true. Default: true when isAutoSubscribe is true.", "type": "boolean", "nullable": true } } }, "GroupCreate": { "description": "\n Request payload for creating a new group. Contains the minimum required information to establish\n a group with default settings. Additional configuration can be done through update endpoints.\n ", "required": [ "privacy", "visibility", "joinMode", "name", "displayName", "type" ], "type": "object", "properties": { "privacy": { "description": "who can access the group's content", "type": "string", "allOf": [ { "$ref": "#/components/schemas/GroupPrivacy" } ] }, "visibility": { "description": "how discoverable the group is", "type": "string", "allOf": [ { "$ref": "#/components/schemas/GroupVisibility" } ] }, "joinMode": { "description": "how users can join the group", "type": "string", "allOf": [ { "$ref": "#/components/schemas/GroupJoinMode" } ] }, "bannerId": { "description": "Banner upload id or null to remove", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "avatarId": { "description": "Avatar upload id or null to remove", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "location": { "description": "group's location", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Location" } ], "nullable": true }, "timezone": { "description": "group's timezone", "type": "object", "allOf": [ { "$ref": "#/components/schemas/TimeZone" } ], "nullable": true }, "name": { "description": "Unique group name used in URLs. Must be alphanumeric with underscores/hyphens, 3-30 characters.", "type": "string" }, "displayName": { "description": "Human-readable display name for the group. Can contain spaces and special characters.", "type": "string" }, "description": { "description": "Detailed description of the group's purpose and activities. Supports markdown formatting.", "type": "string", "nullable": true }, "fields": { "description": "Custom fields for the group", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/UserField" } }, "meta": { "description": "Additional metadata for the group including rules, guidelines, and custom fields", "type": "object", "allOf": [ { "$ref": "#/components/schemas/GroupMeta" } ] }, "type": { "description": "The type/category of the group (ORGANIZATION, COMMUNITY, PROJECT, etc.)", "type": "string", "allOf": [ { "$ref": "#/components/schemas/GroupType" } ] }, "secret": { "type": "boolean" } } }, "GroupFederationTokenRequest": { "description": "Request to obtain a group federation token", "required": [ "groupId" ], "type": "object", "properties": { "groupId": { "description": "ID of the group to access", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] } } }, "GroupInvite": { "description": "A group invitation with full details about the inviter, invitee, and group", "required": [ "groupInviteId", "groupId", "inviterId", "status", "inviterName", "inviterDisplayName", "groupName", "groupDisplayName", "createdAt", "updatedAt" ], "type": "object", "properties": { "groupInviteId": { "description": "Unique identifier for this invitation", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "groupId": { "description": "ID of the group", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "inviterId": { "description": "ID of the user who sent the invitation", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "inviteeId": { "description": "ID of the user being invited (null for email-only invites)", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "status": { "description": "Current status of the invitation", "type": "string", "allOf": [ { "$ref": "#/components/schemas/GroupInviteStatus" } ] }, "message": { "description": "Optional message from the inviter", "type": "string", "nullable": true }, "email": { "description": "Email address of the invitee (present for email-based invites)", "type": "string", "nullable": true }, "inviterName": { "description": "Username of the inviter", "type": "string" }, "inviterDisplayName": { "description": "Display name of the inviter", "type": "string" }, "inviterAvatar": { "description": "Avatar of the inviter", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Upload" } ], "nullable": true }, "inviteeName": { "description": "Username of the invitee (null for unclaimed email-only invites)", "type": "string", "nullable": true }, "inviteeDisplayName": { "description": "Display name of the invitee (null for unclaimed email-only invites)", "type": "string", "nullable": true }, "inviteeAvatar": { "description": "Avatar of the invitee", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Upload" } ], "nullable": true }, "groupName": { "description": "Name of the group", "type": "string" }, "groupDisplayName": { "description": "Display name of the group", "type": "string" }, "groupAvatar": { "description": "Avatar of the group", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Upload" } ], "nullable": true }, "createdAt": { "description": "When the invitation was created", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] }, "updatedAt": { "description": "When the invitation was last updated", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] } } }, "GroupInviteCreate": { "description": "\n Request payload for inviting a user to a group.\n Provide exactly ONE of: inviteeId or inviteeEmail\n ", "type": "object", "properties": { "inviteeId": { "description": "ID of the user to invite", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "inviteeEmail": { "description": "Email address to invite (local users only)", "type": "string", "nullable": true }, "message": { "description": "Optional message to include with the invitation", "maxLength": 500, "type": "string", "nullable": true } } }, "GroupInviteCreateResult": { "description": "Result of a group invite creation request.", "required": [ "invite", "emailSent" ], "type": "object", "properties": { "invite": { "description": "The created invitation", "type": "object", "allOf": [ { "$ref": "#/components/schemas/GroupInvite" } ] }, "emailSent": { "description": "Whether an invitation email was sent from this server", "type": "boolean" } } }, "GroupInviteStatus": { "description": "\n Status of a group invitation:\n * PENDING - Invitation sent, awaiting response\n * ACCEPTED - Invitee accepted the invitation\n * REJECTED - Invitee rejected the invitation\n ", "enum": [ "PENDING", "ACCEPTED", "REJECTED" ], "type": "string" }, "GroupJoinMode": { "description": "\n * OPEN - Anyone can join the group immediately without approval.\n * APPROVAL - User requests must be approved by a group admin or moderator.\n * INVITE_ONLY - Only users with an invitation from a member can join.\n ", "enum": [ "OPEN", "APPROVAL", "INVITE_ONLY" ], "type": "string" }, "GroupJoinRequest": { "description": "\n A group join request with user information.\n Requests can have status: PENDING (awaiting decision), APPROVED (accepted), or REJECTED (denied).\n ", "required": [ "groupJoinRequestId", "userId", "groupId", "username", "displayName", "status", "createdAt", "updatedAt" ], "type": "object", "properties": { "groupJoinRequestId": { "description": "Unique identifier for this group join request", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "userId": { "description": "ID of the user requesting to join", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "groupId": { "description": "ID of the group being requested to join", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "username": { "description": "Username of the user requesting to join", "pattern": "\\S", "type": "string" }, "displayName": { "description": "Display name of the user requesting to join", "pattern": "\\S", "type": "string" }, "avatarId": { "description": "Avatar upload ID of the user", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "answerToken": { "description": "Answer token from completing group questions (if questions were required)", "type": "string", "nullable": true }, "status": { "description": "Current status of the join request", "type": "string", "allOf": [ { "$ref": "#/components/schemas/GroupJoinRequestStatus" } ] }, "reason": { "description": "Reason provided for approval or rejection", "type": "string", "example": "Approved - meets community guidelines", "nullable": true }, "createdAt": { "description": "When the join request was created", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "example": "2025-09-17T12:43:53.395287Z" }, "updatedAt": { "description": "When the join request was last updated (status change, etc)", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "example": "2025-09-17T12:43:53.395287Z" } } }, "GroupJoinRequestStatus": { "description": "\n * PENDING - Request is pending awaiting approval or rejection by group admin.\n * APPROVED - Request is approved by group admin.\n * REJECTED - Request is rejected by group admin.\n ", "enum": [ "PENDING", "APPROVED", "REJECTED" ], "type": "string" }, "GroupJoinRequestsListResponse": { "description": "\n Response object for listing group join requests with pagination support and filtering.\n Includes both filtered results and total counts (with and without filters).\n ", "required": [ "requests", "grandTotal", "total" ], "type": "object", "properties": { "requests": { "description": "Array of group join request objects", "type": "array", "items": { "$ref": "#/components/schemas/GroupJoinRequest" } }, "grandTotal": { "format": "int32", "description": "Total number of join requests for the specified group (no filters applied)", "type": "integer" }, "total": { "format": "int32", "description": "Total number of join requests matching the applied filters", "type": "integer" } } }, "GroupMember": { "description": "\n Represents an active member's participation in a group, including their role and associated metadata.\n This object links a user to a group and defines their permissions within it.\n Note: This only represents active members. For pending join requests, see GroupJoinRequest.\n For pending invites, see GroupInvite. Use MembershipInfo to get a user's full relationship with a group.\n ", "required": [ "groupName", "groupDisplayName", "username", "displayName", "groupId", "memberId" ], "type": "object", "properties": { "groupName": { "description": "Group name", "type": "string" }, "groupDisplayName": { "description": "Group display name", "type": "string" }, "username": { "description": "User name (username)", "type": "string" }, "displayName": { "description": "User display name", "type": "string" }, "domain": { "description": "User domain", "type": "string", "nullable": true }, "local": { "description": "Whether the user is local or not", "type": "boolean" }, "groupAvatar": { "description": "Group avatar upload object", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Upload" } ], "nullable": true }, "userAvatar": { "description": "User avatar upload object", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Upload" } ], "nullable": true }, "groupId": { "description": "Group ID", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "memberId": { "description": "User who is a member of the group", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "roles": { "description": "\n All role identifiers for this member in the group.\n Includes both predefined roles (owner, admin, moderator, member, viewer)\n and custom roles.\n ", "type": "array", "items": { "type": "string" } }, "meta": { "description": "Additional metadata about this membership", "type": "object", "allOf": [ { "$ref": "#/components/schemas/GroupMemberMeta" } ], "nullable": true }, "createdAt": { "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true }, "updatedAt": { "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true } } }, "GroupMemberCreate": { "description": "\n Request payload for adding a new member to a group. Contains the user to add,\n their initial role (assigned via RBAC), and optional metadata.\n The groupId is provided in the URL path.\n ", "required": [ "memberId" ], "type": "object", "properties": { "memberId": { "description": "User who will be added as a member of the group", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "role": { "description": "The initial role to assign via RBAC. Defaults to GROUP_VIEWER if not specified", "type": "string", "nullable": true }, "meta": { "description": "Optional metadata to attach to this membership", "type": "object", "allOf": [ { "$ref": "#/components/schemas/GroupMemberMeta" } ], "nullable": true } } }, "GroupMemberMeta": { "description": "Additional metadata for a group member, such as custom descriptions or notes about their membership", "type": "object", "properties": { "description": { "description": "Optional description or note about this member's role or participation in the group", "type": "string" } } }, "GroupMemberRoleFilter": { "description": "\n Role filter for group members:\n * MEMBER - Returns only regular members of the group\n * ADMIN - Returns all non-regular members (any admin role)\n ", "enum": [ "MEMBER", "ADMIN" ], "type": "string" }, "GroupMemberSearchDetails": { "description": "Search results for group members with pagination", "required": [ "list", "total" ], "type": "object", "properties": { "list": { "description": "List of group member search results matching the search criteria", "type": "array", "items": { "$ref": "#/components/schemas/GroupMemberSearchResult" } }, "total": { "format": "int32", "description": "Total number of results for the current search", "type": "integer" } } }, "GroupMemberSearchResult": { "description": "Detailed group member information for admin search results", "required": [ "memberId", "roles", "meta", "username", "displayName", "entityType", "createdAt", "stats" ], "type": "object", "properties": { "memberId": { "description": "Member user ID", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "roles": { "description": "Roles in the group", "type": "array", "items": { "type": "string" } }, "meta": { "description": "Group member metadata", "type": "object", "allOf": [ { "$ref": "#/components/schemas/GroupMemberMeta" } ] }, "avatar": { "description": "User avatar", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Upload" } ], "nullable": true }, "username": { "description": "User full username", "type": "string" }, "displayName": { "description": "User display name", "type": "string" }, "entityType": { "description": "Entity type", "type": "string", "allOf": [ { "$ref": "#/components/schemas/EntityType" } ] }, "createdAt": { "description": "When joined the group", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] }, "lastActiveAt": { "description": "Last active in the group (timestamp of latest post, comment, like, repost etc)", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true }, "stats": { "description": "Member statistics in the group", "type": "object", "allOf": [ { "$ref": "#/components/schemas/GroupMemberStats" } ] }, "location": { "description": "Last login location from IP, not from user profile", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Location" } ], "nullable": true } } }, "GroupMemberStats": { "description": "Statistics for a group member's activity within the group", "required": [ "posts", "comments", "likes", "votes", "uploads", "uploadsSize" ], "type": "object", "properties": { "posts": { "format": "int32", "description": "Number of posts in the group", "type": "integer" }, "comments": { "format": "int32", "description": "Number of comments in the group", "type": "integer" }, "likes": { "format": "int32", "description": "Number of likes in the group", "type": "integer" }, "votes": { "format": "int32", "description": "Number of votes in the group", "type": "integer" }, "uploads": { "format": "int32", "description": "Number of uploads in the group", "type": "integer" }, "uploadsSize": { "format": "int64", "description": "Total size of uploads by this user in the group (in bytes)", "type": "integer" } } }, "GroupMemberUpdate": { "description": "\n Request payload for updating an existing group member.\n All fields are optional - only provide the fields you want to update.\n ", "type": "object", "properties": { "role": { "description": "New role to assign to the member via RBAC. If null, role remains unchanged", "type": "string", "nullable": true }, "meta": { "description": "Updated metadata for this membership. If null, metadata remains unchanged", "type": "object", "allOf": [ { "$ref": "#/components/schemas/GroupMemberMeta" } ], "nullable": true } } }, "GroupMembersSortBy": { "description": "\n Sort options for group members list:\n * JOIN - Sort by join time\n * POSTS - Sort by number of posts in this group (channels)\n * FOLLOWERS - Sort to show current user's followers first, secondary sort by updated_at\n * FOLLOWING - Sort to show users current user is following first, secondary sort by updated_at\n * RELATIONS - Sort to show users with any relationship (followers or following) first, secondary sort by updated_at\n * DOMAIN - Sort by user domain\n * DISPLAY_NAME - Sort by user display name\n * USERNAME - Sort by username\n * CREATED_AT - Sort by member join time (same as JOIN)\n * ACTOR_TYPE - Sort by actor type\n ", "enum": [ "JOIN", "POSTS", "FOLLOWERS", "FOLLOWING", "RELATIONS", "DOMAIN", "DISPLAY_NAME", "USERNAME", "CREATED_AT", "ACTOR_TYPE" ], "type": "string" }, "GroupMeta": { "description": "Group Details additional data", "required": [ "color" ], "type": "object", "properties": { "color": { "description": "Group color in HEX format", "type": "string" } } }, "GroupPin": { "description": "Represents a user's pinned group with ordering information", "required": [ "userId", "groupId", "pin", "createdAt", "updatedAt" ], "type": "object", "properties": { "userId": { "description": "ID of the user who pinned the group", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "groupId": { "description": "ID of the pinned group", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "pin": { "format": "int32", "description": "Pin order number (positive integer for sorting)", "minimum": 0, "type": "integer" }, "createdAt": { "description": "When the group was pinned", "type": "string", "allOf": [ { "$ref": "#/components/schemas/LocalDateTime" } ] }, "updatedAt": { "description": "When the pin was last updated", "type": "string", "allOf": [ { "$ref": "#/components/schemas/LocalDateTime" } ] } } }, "GroupPrivacy": { "description": "\n * PUBLIC - Open Content. Content and membership are viewable by anyone.\n * PRIVATE - Members-Only Content. Outsiders cannot see posts or members unless they join.\n ", "enum": [ "PUBLIC", "PRIVATE" ], "type": "string" }, "GroupStats": { "description": "Aggregated group-level activity stats", "required": [ "posts", "postsLast24h", "comments", "totalStorageBytes", "avgPostsPerDay", "avgBytesPerDay", "members", "totalEvents" ], "type": "object", "properties": { "posts": { "format": "int64", "description": "Total number of posts", "type": "integer" }, "postsLast24h": { "format": "int64", "description": "Posts created in the last 24 hours", "type": "integer" }, "comments": { "format": "int64", "description": "Total number of comments", "type": "integer" }, "totalStorageBytes": { "format": "int64", "description": "Total uploaded bytes", "type": "integer" }, "avgPostsPerDay": { "format": "double", "description": "Average posts per day over the last 30 days", "type": "number" }, "avgBytesPerDay": { "format": "double", "description": "Average uploaded bytes per day over the last 30 days", "type": "number" }, "lastFlushVersion": { "format": "int64", "type": "integer", "nullable": true, "writeOnly": true }, "members": { "format": "int32", "description": "Count of active members in the group", "type": "integer" }, "totalEvents": { "format": "int64", "description": "Total group events recorded", "type": "integer" } } }, "GroupType": { "enum": [ "CHANNEL", "INTEREST_GROUP", "ORGANIZATION" ], "type": "string" }, "GroupUpdate": { "description": "\n Request payload for updating an existing group. All fields are optional - only provide\n the fields you want to update. Null values are ignored and the existing values are preserved.\n Changes to privacy settings may affect member access. Name changes update the group's URL.\n ", "type": "object", "properties": { "name": { "description": "New unique group name. This will update the group's URL. Must be unique across the platform. Null to keep existing name.", "type": "string", "nullable": true }, "displayName": { "description": "Updated display name for the group. This is what users see in the UI. Null to keep existing.", "type": "string", "nullable": true }, "description": { "description": "Updated group description. Null to keep existing description.", "type": "string", "nullable": true }, "fields": { "description": "Custom fields for the group; processed like user's fields. Null to keep existing.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/UserField" }, "nullable": true }, "refreshedAt": { "description": "Group's last refresh timestamp. Null to keep existing.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true }, "meta": { "description": "Group metadata including color. Null to keep existing.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/GroupMeta" } ], "nullable": true }, "privacy": { "description": "Who can access the group's content. Null to keep existing.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/GroupPrivacy" } ], "nullable": true }, "visibility": { "description": "How discoverable the group is. Null to keep existing.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/GroupVisibility" } ], "nullable": true }, "joinMode": { "description": "How users can join the group. Null to keep existing.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/GroupJoinMode" } ], "nullable": true }, "bannerId": { "description": "Banner upload id. Null to keep existing.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "avatarId": { "description": "Avatar upload id. Null to keep existing.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "location": { "description": "Group's location. Null to keep existing.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Location" } ], "nullable": true }, "timezone": { "description": "Group's timezone. Null to keep existing.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/TimeZone" } ], "nullable": true } } }, "GroupVisibility": { "description": "\n * VISIBLE - The group is listed openly. It shows up in search results or directory listings, no matter if it's\n privacy is PUBLIC or PRIVATE.\n * UNLISTED - The group does not appear in public lists or searches but is accessible via direct link.\n * HIDDEN - The group is completely hidden and invite-only. Shared links will return 404 for non-members.\n ", "enum": [ "VISIBLE", "UNLISTED", "HIDDEN" ], "type": "string" }, "GroupWithMembership": { "description": "\n Group details combined with the viewer's membership information.\n Used for displaying group pages where the viewer's relationship to the group is relevant,\n such as pending invites or join requests.\n ", "required": [ "group", "membershipInfo" ], "type": "object", "properties": { "group": { "description": "The group details", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Group" } ] }, "membershipInfo": { "description": "Viewer's membership state and related info", "type": "object", "allOf": [ { "$ref": "#/components/schemas/MembershipInfo" } ] } } }, "GroupnameCheck": { "description": "Response for checking if a group name (slug) is already in use", "required": [ "exists" ], "type": "object", "properties": { "exists": { "description": "Whether the group name already exists in the database", "type": "boolean", "example": true } } }, "Idd": { "required": [ "root", "suffixes" ], "type": "object", "properties": { "root": { "type": "string" }, "suffixes": { "type": "array", "items": { "type": "string" } } } }, "InetAddress": { "type": "object", "properties": { "multicastAddress": { "type": "boolean" }, "anyLocalAddress": { "type": "boolean" }, "loopbackAddress": { "type": "boolean" }, "linkLocalAddress": { "type": "boolean" }, "siteLocalAddress": { "type": "boolean" }, "MCGlobal": { "type": "boolean" }, "MCNodeLocal": { "type": "boolean" }, "MCLinkLocal": { "type": "boolean" }, "MCSiteLocal": { "type": "boolean" }, "MCOrgLocal": { "type": "boolean" }, "hostName": { "type": "string" }, "address": { "format": "binary", "type": "string" }, "hostAddress": { "type": "string" } } }, "Instance": { "required": [ "uri", "version", "build", "buildTimestamp", "configuration", "rules" ], "type": "object", "properties": { "uri": { "description": "URI of this instance", "type": "string", "example": "https://wellesley.social" }, "title": { "type": "string" }, "short_description": { "type": "string" }, "description": { "type": "string" }, "email": { "type": "string" }, "version": { "description": "Version of the platform", "type": "string", "example": "1.0" }, "build": { "description": "Build # of the platform", "type": "string", "example": "777" }, "buildTimestamp": { "format": "int64", "description": "Build timestamp", "type": "integer", "example": 681486960000 }, "urls": { "type": "object", "additionalProperties": { "type": "string" } }, "stats": { "$ref": "#/components/schemas/InstanceStats" }, "thumbnail": { "type": "string" }, "languages": { "type": "array", "items": { "type": "string" } }, "configuration": { "description": "This instance configuration", "type": "object", "allOf": [ { "$ref": "#/components/schemas/InstanceConfiguration" } ] }, "contact_account": { "allOf": [ { "$ref": "#/components/schemas/User" } ], "nullable": true }, "rules": { "description": "List of instance rules", "type": "array", "items": { "$ref": "#/components/schemas/Rule" } } } }, "InstanceAccess": { "required": [ "visibility" ], "type": "object", "properties": { "visibility": { "description": "Whether the server is visible to the public", "enum": [ "PUBLIC", "PRIVATE" ], "type": "string" } } }, "InstanceBranding": { "required": [ "color", "description", "displayName", "image", "imageThumbnail", "shortDescription" ], "type": "object", "properties": { "color": { "description": "Color theme of the homepage in HEX format", "type": "string" }, "description": { "description": "Server description shown on the homepage", "maxLength": 16384, "type": "string" }, "displayName": { "description": "Display name shown on the homepage", "type": "string" }, "image": { "description": "Image URL shown on the homepage", "type": "string" }, "imageThumbnail": { "description": "Thumbnail of the image URL shown on the homepage", "type": "string" }, "shortDescription": { "description": "Short description shown on the homepage", "type": "string" } } }, "InstanceConfiguration": { "required": [ "registrations", "passwordPolicy", "access", "branding", "domainBlocksPolicy", "contacts" ], "type": "object", "properties": { "registrations": { "description": "Registration configuration", "type": "object", "allOf": [ { "$ref": "#/components/schemas/InstanceRegistration" } ] }, "passwordPolicy": { "description": "Password policy configuration", "type": "string", "allOf": [ { "$ref": "#/components/schemas/PasswordPolicy" } ] }, "access": { "description": "Access configuration", "type": "object", "allOf": [ { "$ref": "#/components/schemas/InstanceAccess" } ] }, "branding": { "description": "Branding configuration", "type": "object", "allOf": [ { "$ref": "#/components/schemas/InstanceBranding" } ] }, "domainBlocksPolicy": { "description": "Domain blocks policy configuration", "type": "object", "allOf": [ { "$ref": "#/components/schemas/InstanceDomainBlocksPolicy" } ] }, "contacts": { "description": "Instance contacts configuration", "type": "object", "allOf": [ { "$ref": "#/components/schemas/InstanceContacts" } ] } } }, "InstanceContacts": { "required": [ "email", "username" ], "type": "object", "properties": { "email": { "description": "Contact email for the server", "type": "string" }, "username": { "description": "Contact username for the server", "type": "string" } } }, "InstanceDomainBlocksPolicy": { "required": [ "domainBlocksAccess", "domainBlocksReasonAccess" ], "type": "object", "properties": { "domainBlocksAccess": { "description": "Who can see domains that are blocked by this instance", "enum": [ "NONE", "USER", "ALL" ], "type": "string" }, "domainBlocksReasonAccess": { "description": "Who can see reasons for domain blocks by this instance", "enum": [ "NONE", "USER", "ALL" ], "type": "string" } } }, "InstanceRegistration": { "required": [ "ask_for_info", "captcha", "invites", "message", "mode" ], "type": "object", "properties": { "ask_for_info": { "description": "Whether reason to join should be provided when signing up", "type": "boolean" }, "captcha": { "description": "Whether captcha is shown to new users when signing up", "type": "boolean" }, "invites": { "description": "Whether existing users can invite other users to join", "type": "boolean" }, "message": { "description": "Message shown to guests when registration is closed", "type": "string" }, "mode": { "description": "Registration mode on this instance", "enum": [ "OPEN", "APPROVAL", "EMAIL_DOMAIN_ALLOWLIST", "CLOSED" ], "type": "string", "example": "OPEN" } } }, "InstanceStats": { "required": [ "active30_user_count", "active180_user_count" ], "type": "object", "properties": { "user_count": { "format": "int64", "description": "Total number of local users on this day", "type": "integer", "nullable": true }, "active30_user_count": { "format": "int64", "description": "Total number of active local users in the last 30 days on this day", "type": "integer", "nullable": true }, "active180_user_count": { "format": "int64", "description": "Total number of active local users in the last 180 days on this day", "type": "integer", "nullable": true }, "group_count": { "format": "int64", "description": "Total number of local groups on this day", "type": "integer", "nullable": true }, "post_count": { "format": "int64", "description": "Local top-level posts created this day", "type": "integer", "nullable": true }, "post_count_total": { "format": "int64", "description": "Cumulative local top-level posts up to this day", "type": "integer", "nullable": true }, "comment_count": { "format": "int64", "description": "Comments by local users created this day", "type": "integer", "nullable": true }, "remote_comment_count": { "format": "int64", "description": "Comments by remote users created this day", "type": "integer", "nullable": true }, "comment_count_total": { "format": "int64", "description": "Cumulative comments by local users up to this day", "type": "integer", "nullable": true }, "remote_comment_count_total": { "format": "int64", "description": "Cumulative comments by remote users up to this day", "type": "integer", "nullable": true }, "domain_count": { "format": "int64", "description": "Total number of external domains on this day", "type": "integer", "nullable": true } } }, "InstanceVisibility": { "enum": [ "PUBLIC", "PRIVATE" ], "type": "string" }, "Instant": { "format": "date-time", "type": "string", "example": "2022-03-10T16:15:50Z" }, "JAAttachment": { "description": "Job Application attachment", "required": [ "name" ], "type": "object", "properties": { "name": { "description": "The Attachment name", "maxLength": 256, "type": "string" }, "url": { "description": "The Attachment's URL", "maxLength": 256, "pattern": "^(https?|ftp)://[^\\s/$.?#].[^\\s]*$", "type": "string", "nullable": true }, "text": { "description": "The Attachment text", "maxLength": 10240, "type": "string", "nullable": true } } }, "JAData": { "description": "Job Application data", "type": "object", "properties": { "attachments": { "description": "The list of the attachments", "maxItems": 128, "type": "array", "items": { "$ref": "#/components/schemas/JAAttachment" }, "nullable": true } } }, "JPData": { "description": "Job Posting data", "required": [ "title", "location", "employmentType", "jobDescription", "responsibilities", "salary" ], "type": "object", "properties": { "title": { "description": "The offered title", "maxLength": 256, "type": "string", "nullable": true }, "location": { "description": "The location of the job", "maxLength": 512, "type": "string", "nullable": true }, "employmentType": { "description": "The employment type", "maxLength": 256, "type": "string", "example": "Full time/Part time/Contract, etc.", "nullable": true }, "jobDescription": { "description": "The job description", "maxLength": 9184, "type": "string", "nullable": true }, "responsibilities": { "description": "The list of responsibilities", "maxItems": 128, "type": "array", "items": { "type": "string" }, "nullable": true }, "qualificationsRequired": { "description": "The list of required qualifications", "maxItems": 128, "type": "array", "items": { "type": "string" }, "nullable": true }, "skillsRequired": { "description": "The list of required skills", "maxItems": 128, "type": "array", "items": { "type": "string" }, "nullable": true }, "educationRequired": { "description": "The list of required educations", "maxItems": 128, "type": "array", "items": { "type": "string" }, "nullable": true }, "experienceRequired": { "description": "The list of required experiences", "maxItems": 128, "type": "array", "items": { "type": "string" }, "nullable": true }, "salary": { "description": "Monetary compensation offered", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Salary" } ], "nullable": true }, "benefits": { "description": "The list of benefits offered", "maxItems": 128, "type": "array", "items": { "type": "string" }, "nullable": true }, "datePosted": { "description": "The date of the posting", "type": "string", "allOf": [ { "$ref": "#/components/schemas/LocalDate" } ], "nullable": true }, "applicationDeadline": { "description": "The deadline for the application", "type": "string", "allOf": [ { "$ref": "#/components/schemas/LocalDate" } ], "nullable": true } } }, "JobApplication": { "description": "Job Application", "required": [ "jobApplicationId", "jobPostingId", "jaData" ], "type": "object", "properties": { "jobApplicationId": { "description": "Internal Job Application id", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "jobPostingId": { "description": "Internal Job Posting id", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "jaData": { "description": "Job Application data", "type": "object", "allOf": [ { "$ref": "#/components/schemas/JAData" } ] } } }, "JobListResult": { "required": [ "list", "total" ], "type": "object", "properties": { "list": { "type": "array", "items": { "type": "string" } }, "total": { "format": "int32", "type": "integer" } } }, "JobPosting": { "description": "Job Posting", "required": [ "jobPostingId", "jpData" ], "type": "object", "properties": { "jobPostingId": { "description": "internal Job Posting id", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "jpData": { "description": "Job Posting data", "type": "object", "allOf": [ { "$ref": "#/components/schemas/JPData" } ] } } }, "JsonNode": { "type": "object", "properties": { "empty": { "type": "boolean" }, "valueNode": { "type": "boolean" }, "containerNode": { "type": "boolean" }, "missingNode": { "type": "boolean" }, "array": { "type": "boolean" }, "object": { "type": "boolean" }, "nodeType": { "$ref": "#/components/schemas/JsonNodeType" }, "pojo": { "type": "boolean" }, "number": { "type": "boolean" }, "integralNumber": { "type": "boolean" }, "floatingPointNumber": { "type": "boolean" }, "short": { "type": "boolean" }, "int": { "type": "boolean" }, "long": { "type": "boolean" }, "float": { "type": "boolean" }, "double": { "type": "boolean" }, "bigDecimal": { "type": "boolean" }, "bigInteger": { "type": "boolean" }, "textual": { "type": "boolean" }, "boolean": { "type": "boolean" }, "null": { "type": "boolean" }, "binary": { "type": "boolean" } } }, "JsonNodeType": { "enum": [ "ARRAY", "BINARY", "BOOLEAN", "MISSING", "NULL", "NUMBER", "OBJECT", "POJO", "STRING" ], "type": "string" }, "JsonObject": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": {} } } }, "Kind": { "enum": [ "CHANNEL", "USER", "ALL" ], "type": "string" }, "Language": { "enum": [ "BG", "CS", "DA", "DE", "EL", "EN", "ES", "ET", "FI", "FR", "HU", "ID", "IT", "JA", "KO", "LT", "LV", "NB", "NL", "PL", "PT", "RO", "RU", "SK", "SL", "SV", "TR", "UK", "ZH" ], "type": "string" }, "ListUploadJobsResult": { "description": "List of the upload jobs", "required": [ "list", "total", "totalJobs" ], "type": "object", "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/ProcessJob" } }, "total": { "format": "int32", "description": "Total number of jobs in the queue.", "type": "integer" }, "totalJobs": { "format": "int32", "description": "Total number of jobs in the queue with specified filter.", "type": "integer" } } }, "ListUploadsResult": { "description": "List uploads result", "required": [ "list", "total" ], "type": "object", "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/Upload" } }, "total": { "format": "int64", "type": "integer" } } }, "LocalDate": { "format": "date", "type": "string", "example": "2022-03-10" }, "LocalDateTime": { "format": "date-time", "type": "string", "example": "2022-03-10T12:15:50" }, "Location": { "description": "User's location preferences", "required": [ "geo", "name", "autoUpdate", "show" ], "type": "object", "properties": { "geo": { "allOf": [ { "$ref": "#/components/schemas/Geo" } ], "nullable": true }, "name": { "type": "string", "nullable": true }, "autoUpdate": { "type": "boolean" }, "show": { "type": "boolean" } } }, "LoginType": { "enum": [ "EMAIL", "USERNAME", "PHONE", "PASSKEY", "IMPERSONATE", "FEDERATION" ], "type": "string" }, "Manifest": { "required": [ "id", "name", "description", "version", "releasedOn", "developer" ], "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "version": { "type": "string" }, "releasedOn": { "$ref": "#/components/schemas/Instant" }, "developer": { "$ref": "#/components/schemas/ApplicationDeveloper" }, "icons": { "type": "array", "items": { "type": "string" } }, "previews": { "type": "array", "items": { "type": "string" } }, "routes": { "type": "array", "items": { "$ref": "#/components/schemas/Route" } }, "visibility": { "$ref": "#/components/schemas/ApplicationVisibility" }, "type": { "$ref": "#/components/schemas/ApplicationType" }, "trust-level": { "$ref": "#/components/schemas/ApplicationTrustLevel" }, "standard": { "type": "boolean" } } }, "MembershipInfo": { "description": "\n Represents a user's current relationship with a group.\n Contains the membership state and the relevant object (member, join request, or invite).\n ", "required": [ "state" ], "type": "object", "properties": { "state": { "description": "The current state of the user's relationship with the group", "type": "string", "allOf": [ { "$ref": "#/components/schemas/MembershipState" } ] }, "member": { "description": "The membership object, present if state is MEMBER", "type": "object", "allOf": [ { "$ref": "#/components/schemas/GroupMember" } ], "nullable": true }, "joinRequest": { "description": "The join request object, present if state is PENDING_JOIN", "type": "object", "allOf": [ { "$ref": "#/components/schemas/GroupJoinRequest" } ], "nullable": true }, "invite": { "description": "The invite object, present if state is PENDING_INVITE", "type": "object", "allOf": [ { "$ref": "#/components/schemas/GroupInvite" } ], "nullable": true } } }, "MembershipState": { "description": "The current state of a user's relationship with a group", "enum": [ "MEMBER", "PENDING_JOIN", "PENDING_INVITE", "NONE" ], "type": "string" }, "Meta": { "type": "object", "properties": { "blurhash": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "altText": { "type": "string", "nullable": true } } }, "Meta1": { "type": "object", "properties": { "duration": { "format": "double", "description": "Video duration in seconds", "type": "number", "nullable": true }, "width": { "format": "int32", "description": "Media width", "type": "integer", "nullable": true }, "height": { "format": "int32", "description": "Media height", "type": "integer", "nullable": true }, "codec": { "description": "Video codec", "type": "string", "nullable": true }, "rotate": { "format": "int32", "description": "Rotation in degrees", "type": "integer", "nullable": true } } }, "MetricsData": { "description": "Metrics data for a specific time period", "required": [ "granularity", "timeSlot" ], "type": "object", "properties": { "granularity": { "description": "Time granularity of the metrics", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TimeGranularity" } ] }, "timeSlot": { "description": "Time slot for which metrics are calculated", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] }, "newSignups": { "format": "int64", "description": "Number of new signups", "type": "integer", "nullable": true }, "activeUsers": { "format": "int64", "description": "Number of active users", "type": "integer", "nullable": true }, "userCreations": { "format": "int64", "description": "Number of users created", "type": "integer", "nullable": true }, "userDeletions": { "format": "int64", "description": "Number of users deleted", "type": "integer", "nullable": true }, "usersWhoPosted": { "format": "int64", "description": "Number of unique users who posted", "type": "integer", "nullable": true }, "mediaPosts": { "format": "int64", "description": "Number of posts with media attachments", "type": "integer", "nullable": true }, "likes": { "format": "int64", "description": "Number of likes", "type": "integer", "nullable": true }, "reposts": { "format": "int64", "description": "Number of reposts", "type": "integer", "nullable": true }, "quotes": { "format": "int64", "description": "Number of quote posts", "type": "integer", "nullable": true }, "replies": { "format": "int64", "description": "Number of replies", "type": "integer", "nullable": true }, "conversations": { "format": "int64", "description": "Number of conversations", "type": "integer", "nullable": true }, "users": { "format": "int64", "description": "Total number of local users on this day", "type": "integer", "nullable": true }, "groups": { "format": "int64", "description": "Total number of local groups (not deleted) on this day", "type": "integer", "nullable": true }, "localPostsCreated": { "format": "int64", "description": "Local top-level posts created this day", "type": "integer", "nullable": true }, "localPostsTotal": { "format": "int64", "description": "Cumulative local top-level posts up to this day", "type": "integer", "nullable": true }, "remotePostsCreated": { "format": "int64", "description": "Remote top-level posts created this day", "type": "integer", "nullable": true }, "remotePostsTotal": { "format": "int64", "description": "Cumulative remote top-level posts up to this day", "type": "integer", "nullable": true }, "localComments": { "format": "int64", "description": "Comments by local users created this day", "type": "integer", "nullable": true }, "remoteComments": { "format": "int64", "description": "Comments by remote users created this day", "type": "integer", "nullable": true }, "localCommentsTotal": { "format": "int64", "description": "Cumulative comments by local users up to this day", "type": "integer", "nullable": true }, "remoteCommentsTotal": { "format": "int64", "description": "Cumulative comments by remote users up to this day", "type": "integer", "nullable": true }, "domains": { "format": "int64", "description": "Total number of external domains on this day", "type": "integer", "nullable": true } } }, "MetricsPeriod": { "description": "Predefined time periods for metrics queries", "enum": [ "LAST_DAY", "LAST_WEEK", "LAST_MONTH" ], "type": "string" }, "MetricsSummary": { "required": [ "operationMetrics", "totals" ], "type": "object", "properties": { "operationMetrics": { "type": "array", "items": { "$ref": "#/components/schemas/GlobalAggregatedMetrics" } }, "totals": { "$ref": "#/components/schemas/MetricsSummaryTotals" } } }, "MetricsSummaryTotals": { "required": [ "totalMeasurements", "totalTime", "overallAverage", "operationCount" ], "type": "object", "properties": { "totalMeasurements": { "format": "int64", "type": "integer" }, "totalTime": { "format": "int64", "type": "integer" }, "overallAverage": { "format": "double", "type": "number" }, "operationCount": { "format": "int32", "type": "integer" } } }, "MuteState": { "required": [ "state" ], "type": "object", "properties": { "state": { "type": "boolean" }, "expiresAt": { "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true } } }, "Name": { "required": [ "common", "official", "nativeName" ], "type": "object", "properties": { "common": { "type": "string" }, "official": { "type": "string" }, "nativeName": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/NativeName" } } } }, "NameCheckResult": { "description": "Result of validating a name for availability and reserved word checks", "required": [ "available", "reserved", "taken" ], "type": "object", "properties": { "available": { "description": "Whether the name is available for use (not reserved and not taken)", "type": "boolean" }, "reserved": { "description": "Whether the name is a reserved word that cannot be used", "type": "boolean" }, "taken": { "description": "Whether the name is already in use by another entity", "type": "boolean" } } }, "NameScope": { "description": "\n Scope for name validation in the unified name check endpoint.\n * USER - Check user or channel username availability. Without scope: checks global user/channel namespace. With scope (groupId): checks channel username within the specified group.\n * GROUP - Check group name availability. scope parameter is not allowed with this scope.\n ", "enum": [ "USER", "GROUP" ], "type": "string" }, "Namespace": { "enum": [ "Platform", "User", "Group", "GroupMember" ], "type": "string" }, "NativeName": { "required": [ "official", "common" ], "type": "object", "properties": { "official": { "type": "string" }, "common": { "type": "string" } } }, "NoteUpdate": { "required": [ "userId", "text" ], "type": "object", "properties": { "userId": { "description": "User id to set note for", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "text": { "description": "Note text", "maxLength": 500, "minLength": 1, "pattern": "\\S", "type": "string" } } }, "Notification": { "required": [ "id", "userId", "type", "status", "activityId", "fromUserId", "meta", "createdAt", "updatedAt" ], "type": "object", "properties": { "id": { "description": "Internal notification id", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "nt_01hz1f0sj42k87a6s2nzpc4s92n" }, "userId": { "description": "User receiving the notification", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "us_01hz1fkfg82hf89s2nzqwer02r" }, "type": { "$ref": "#/components/schemas/NotificationType" }, "status": { "$ref": "#/components/schemas/NotificationStatus" }, "activityId": { "description": "Related activity id (usually a post)", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "pt_01hz1f0jkdw3h27a2kdr8sn2kt", "nullable": true }, "fromUserId": { "description": "User who triggered the notification", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "us_01hz1frg9sf48d7a8sn2kdr8w3h", "nullable": true }, "groupId": { "description": "Related group id, if available", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "gp_01hz1f0jkdw3h27a2kdr8sn2kt", "nullable": true }, "channelId": { "description": "Related channel(user) id, if available", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "us_01hz1frg9sf48d7a8sn2kdr8w3h", "nullable": true }, "meta": { "$ref": "#/components/schemas/NotificationMeta" }, "createdAt": { "$ref": "#/components/schemas/Instant" }, "updatedAt": { "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true }, "fromUser": { "allOf": [ { "$ref": "#/components/schemas/User" } ], "nullable": true }, "post": { "allOf": [ { "$ref": "#/components/schemas/Post" } ], "nullable": true }, "event": { "allOf": [ { "$ref": "#/components/schemas/Event" } ], "nullable": true }, "groupInvite": { "allOf": [ { "$ref": "#/components/schemas/GroupInvite" } ], "nullable": true }, "context": { "allOf": [ { "$ref": "#/components/schemas/NotificationContext" } ], "nullable": true } } }, "NotificationAction": { "required": [ "action", "text" ], "type": "object", "properties": { "action": { "type": "string" }, "text": { "type": "string" } } }, "NotificationContext": { "description": "Optional group/channel context for notification rendering", "required": [ "groupId", "groupName", "groupDisplayName" ], "type": "object", "properties": { "groupId": { "$ref": "#/components/schemas/TypeId" }, "groupName": { "type": "string" }, "groupDisplayName": { "type": "string" }, "groupAvatar": { "allOf": [ { "$ref": "#/components/schemas/Upload" } ], "nullable": true }, "channelName": { "type": "string", "nullable": true }, "channelDisplayName": { "type": "string", "nullable": true } } }, "NotificationDelivery": { "description": "\n IMMEDIATELY\n Notification is delivered immediately.\n BUFFERED\n Notification delivery is delayed, notifications are buffered and might not\n be delivered if expired during buffering.\n ", "enum": [ "IMMEDIATELY", "BUFFERED" ], "type": "string" }, "NotificationMeta": { "type": "object", "properties": { "actionsAvailable": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationAction" }, "nullable": true }, "actionsTaken": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationAction" }, "nullable": true }, "empty": { "type": "boolean" } } }, "NotificationStatus": { "enum": [ "UNREAD", "READ", "BLOCKED", "HIDDEN" ], "type": "string" }, "NotificationStrategy": { "description": "\n FIRST\n First notification is delivered only. All consecutive notifications are ignored.\n LAST\n New notification is delivered. Previous notifications are removed.\n MANY\n New notification is delivered. Old notifications are kept intact.\n ", "enum": [ "FIRST", "LAST", "MANY" ], "type": "string" }, "NotificationType": { "description": "\n FOLLOW\n New follower\n\n Send to the user who got a new follower.\n\n FOLLOW_REQUEST\n New follower request\n\n Similar to FOLLOW, send to the user who got a new follower,\n but in cases where followers need to be explicitly approved.\n\n GROUP_INVITE\n User got an invitation\n\n Send to the user who received the ActivityPub invitation activity.\n\n LIKE\n Post has been liked\n\n Send to the post's author as soon as another user likes their post.\n\n COMMENT\n Post has been commented on\n\n Send to the post's author and all users subscribed to the post.\n\n MENTION\n User has been mentioned in a post or comment\n\n Send to the user who was mentioned in the post or comment.\n\n REPOST\n Post has been reposted\n\n Send to the author of the post that was reposted.\n\n LIST_POST_CREATE\n New post or comment in list\n\n Send to the list owner when a new post is created by a list user.\n\n GROUP_CHANNEL_POST_CREATE\n New post in a subscribed group channel\n\n Send to users following the group channel when a new top-level post is created there.\n\n POST_UPDATE\n Post or comment has been updated\n\n Send to users subscribed to the post or comment.\n\n POLL\n Poll has been closed (expired)\n\n Send to the poll's author and all voters.\n\n POLL_VOTE\n Someone voted on your poll\n\n Send to the poll's author when another user votes.\n\n POST_VOTE\n Someone voted (upvote/downvote) on your post\n\n Send to the post's author when another user votes on their post.\n\n EVENT_INVITE\n User has been invited to a private event\n\n Send to the invitee, i.e., the user invited to the event.\n\n EVENT_REVOKE\n User's invitation has been revoked\n\n Send to the invitee, i.e., the user whose invitation was revoked.\n\n EVENT_JOIN\n User joined a public event\n\n Send to the event organizer.\n\n EVENT_CANCEL\n Event has been cancelled\n\n Send to all event attendees (for public events, to users who joined).\n\n EVENT_UPDATE\n Event has been updated\n\n Send to all event attendees (for public events, to users who joined).\n\n FOLLOW_FAILED\n Follow request delivery failed\n\n Send to the user who initiated a follow request when delivery\n to the remote server permanently fails after all retries are exhausted.\n The pending follow record is removed so the user can retry.\n ", "enum": [ "FOLLOW", "FOLLOW_REQUEST", "GROUP_INVITE", "LIKE", "COMMENT", "MENTION", "REPOST", "LIST_POST_CREATE", "GROUP_CHANNEL_POST_CREATE", "POST_UPDATE", "POLL", "POLL_VOTE", "POST_VOTE", "EVENT_INVITE", "EVENT_JOIN", "EVENT_CANCEL", "EVENT_UPDATE", "FOLLOW_FAILED" ], "type": "string" }, "Option": { "required": [ "title" ], "type": "object", "properties": { "title": { "type": "string" } } }, "OverallStats": { "required": [ "finished", "failed" ], "type": "object", "properties": { "finished": { "type": "object", "additionalProperties": { "format": "int64", "type": "integer" } }, "failed": { "type": "object", "additionalProperties": { "format": "int64", "type": "integer" } } } }, "Passkey": { "required": [ "credentialId", "accountId", "userId", "publicKeyCose", "publicKeyAlg", "aaguid", "signCount" ], "type": "object", "properties": { "credentialId": { "type": "string" }, "accountId": { "$ref": "#/components/schemas/TypeId" }, "userId": { "$ref": "#/components/schemas/TypeId" }, "publicKeyCose": { "format": "binary", "type": "string" }, "publicKeyAlg": { "format": "int64", "type": "integer" }, "aaguid": { "type": "string", "nullable": true }, "signCount": { "format": "int64", "type": "integer" } } }, "PasswordChangeRequest": { "description": "Params to change account password", "required": [ "currentPassword", "newPassword" ], "type": "object", "properties": { "currentPassword": { "description": "Current account password", "maxLength": 64, "minLength": 1, "type": "string", "example": "PassW0rd!" }, "newPassword": { "description": "New password, enforced by password policy", "type": "string", "example": "PassW0rd!" } } }, "PasswordPolicy": { "enum": [ "ANY", "STRICT" ], "type": "string" }, "PasswordRecoveryChange": { "description": "Params to change account password after recovery", "required": [ "login", "newPassword" ], "type": "object", "properties": { "login": { "description": "Email or username", "type": "string", "example": "user@gmail.com or john_smith" }, "newPassword": { "description": "New password, enforced by password policy", "type": "string", "example": "PassW0rd!" } } }, "PasswordRecoveryCode": { "description": "Params to confirm request to change password with recovery code", "required": [ "login", "code" ], "type": "object", "properties": { "login": { "description": "Email or username", "type": "string", "example": "user@gmail.com or john_smith" }, "code": { "format": "int32", "description": "Confirmation code", "type": "integer", "example": 854882 } } }, "PasswordRecoveryRequest": { "description": "Params to recover account password", "required": [ "login" ], "type": "object", "properties": { "login": { "description": "Email or username", "type": "string", "example": "user@gmail.com or john_smith" } } }, "PhoneSignup": { "required": [ "phone", "username", "displayName" ], "type": "object", "properties": { "phone": { "description": "Phone number", "type": "string", "example": "+12345678901" }, "username": { "description": "Username of the main user", "type": "string", "example": "john_smith" }, "displayName": { "description": "Display Name of the main user", "maxLength": 56, "minLength": 1, "type": "string", "example": "John Smith" }, "inviteCode": { "description": "Optional invite code", "type": "string", "example": "abcd-efgh-1234", "nullable": true } } }, "PinnedParam": { "description": "\n Options for '?pinned' param when loading requests list of posts. Applied only if ?userId is present.\n * ONLY - load only pinned posts\n * SKIP - skip pinned posts\n * ALL - both, has the same effect as omitting the param\n ", "enum": [ "ONLY", "SKIP", "ALL" ], "type": "string" }, "Poll": { "required": [ "id", "startedAt", "expiresAt", "multiple", "votersCount", "options", "hideTotals" ], "type": "object", "properties": { "id": { "description": "Internal poll id", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "pl_01hz1f0jnm2f87w2mzpc4s92kt" }, "startedAt": { "description": "Time when poll starts. Poll is valid from startedAt until expiresAt.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] }, "expiresAt": { "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true }, "multiple": { "type": "boolean" }, "votersCount": { "format": "int64", "type": "integer" }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/PollOption" } }, "hideTotals": { "type": "boolean" }, "ownVotes": { "type": "array", "items": { "format": "int32", "type": "integer" }, "nullable": true }, "emojis": { "type": "array", "items": { "$ref": "#/components/schemas/Emoji" }, "nullable": true } } }, "Poll1": { "required": [ "id", "options" ], "type": "object", "properties": { "id": { "type": "string" }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/Option" } } } }, "PollCreate": { "description": "Poll creation params", "required": [ "options", "expiresIn", "multiple", "hideTotals" ], "type": "object", "properties": { "options": { "description": "List of poll options", "maxItems": 5, "minItems": 2, "type": "array", "items": { "type": "string" } }, "expiresIn": { "format": "double", "description": "Duration in seconds", "type": "number", "allOf": [ { "$ref": "#/components/schemas/Duration" } ] }, "multiple": { "description": "Allow multiple choices", "type": "boolean" }, "hideTotals": { "description": "Hide totals until poll finishes", "type": "boolean" } } }, "PollOption": { "required": [ "title", "votesCount" ], "type": "object", "properties": { "title": { "type": "string" }, "votesCount": { "format": "int64", "type": "integer" } } }, "Post": { "description": "User's post", "required": [ "id", "uri", "text", "path", "privacy", "effectivePrivacy", "kind", "software", "ownerId", "ownerType", "groupId", "title", "tags", "mentions", "stats", "settings", "lang", "poll", "card", "mediaType", "translations", "createdAt", "updatedAt", "author", "uploads", "deleted" ], "type": "object", "properties": { "id": { "description": "internal post id", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "uri": { "format": "uri", "description": "unique post uri", "type": "string" }, "text": { "description": "post text, raw or html depending on how it was requested", "type": "string" }, "path": { "description": "replies path", "type": "array", "items": { "$ref": "#/components/schemas/TypeId" } }, "privacy": { "description": "post privacy level", "type": "string", "allOf": [ { "$ref": "#/components/schemas/PostPrivacy" } ], "example": "PUBLIC" }, "effectivePrivacy": { "description": "Resolved privacy that never contains FOLLOW_POST. For FOLLOW_POST posts, this is the root post's privacy. For all other posts, this equals privacy.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/PostPrivacy" } ], "example": "PUBLIC" }, "kind": { "description": "Article or Note", "type": "string", "allOf": [ { "$ref": "#/components/schemas/PostKind" } ], "example": "Note" }, "software": { "description": "post software", "type": "string", "example": "wellesley" }, "repostOf": { "description": "id of a post this one was reposted from", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "ownerId": { "$ref": "#/components/schemas/TypeId" }, "ownerType": { "$ref": "#/components/schemas/PostOwnerType" }, "groupId": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "title": { "type": "string", "nullable": true }, "summary": { "description": "Subject or summary line, below which post content is collapsed until expanded.", "type": "string", "nullable": true }, "tags": { "description": "List of tags", "type": "array", "items": { "type": "string" } }, "mentions": { "description": "List of mentions", "type": "array", "items": { "format": "uri", "type": "string" } }, "stats": { "description": "Stats", "type": "object", "allOf": [ { "$ref": "#/components/schemas/PostStats" } ] }, "settings": { "description": "Settings", "type": "object", "allOf": [ { "$ref": "#/components/schemas/PostSettings" } ] }, "lang": { "allOf": [ { "$ref": "#/components/schemas/Language" } ], "nullable": true }, "poll": { "allOf": [ { "$ref": "#/components/schemas/Poll" } ], "nullable": true }, "card": { "description": "Preview card for any links in the post", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Card" } ], "nullable": true }, "mediaType": { "description": "Post media type. Default for Note is text/plain, for Article text/markdown", "type": "string", "allOf": [ { "$ref": "#/components/schemas/PostMediaType" } ] }, "translations": { "type": "object", "additionalProperties": { "type": "string" }, "nullable": true }, "createdAt": { "$ref": "#/components/schemas/Instant" }, "updatedAt": { "$ref": "#/components/schemas/Instant" }, "author": { "$ref": "#/components/schemas/User" }, "uploads": { "type": "array", "items": { "$ref": "#/components/schemas/Upload" } }, "liked": { "description": "Whether the current user liked it or not", "type": "boolean", "nullable": true }, "reposted": { "description": "Whether the current user reposted it or not", "type": "boolean", "nullable": true }, "quoted": { "description": "Whether the current user quoted it or not", "type": "boolean", "nullable": true }, "muted": { "description": "Whether the current user muted the author of the post", "type": "boolean", "nullable": true }, "blocked": { "description": "Whether the current user blocked the author of the post", "type": "boolean", "nullable": true }, "visible": { "description": "Whether the current user can see it or not (e.g. FOLLOWERS_ONLY", "type": "boolean", "nullable": true }, "pinned": { "description": "Whether the current user pinned it or not", "type": "boolean", "nullable": true }, "pinnedAt": { "description": "Timestamp when the post was pinned/highlighted (from post_pins)", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true }, "bookmarked": { "description": "Whether the current user bookmarked it or not", "type": "boolean", "nullable": true }, "subscribed": { "description": "Whether the current user is subscribed to post updates", "type": "boolean", "nullable": true }, "canManage": { "description": "Whether the current user can edit/delete this post", "type": "boolean", "nullable": true }, "edited": { "description": "Whether the post was edited", "type": "boolean", "nullable": true }, "deleted": { "type": "boolean", "nullable": true }, "emojis": { "type": "array", "items": { "$ref": "#/components/schemas/Emoji" }, "nullable": true }, "replies": { "type": "array", "items": { "$ref": "#/components/schemas/Post" }, "nullable": true }, "repostedBy": { "description": "List of users who reposted this post", "type": "array", "items": { "$ref": "#/components/schemas/UserLite" }, "nullable": true }, "originalPost": { "description": "Original post of repost/quote (the post being reposted or quoted). Related to repostOf field.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Post" } ], "nullable": true }, "parent": { "description": "Parent post for comments/replies. Related to replyTo (last element in path).", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Post" } ], "nullable": true }, "votes": { "description": "Votes summary", "type": "object", "allOf": [ { "$ref": "#/components/schemas/PostVotesSummary" } ], "nullable": true }, "publisher": { "description": "Publisher context for mixed-scope lists (e.g. search). Contains channel or group branding.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/PostPublisher" } ], "nullable": true }, "isHighlightCopy": { "description": "Whether this is a copy of a highlighted (pinned) reply\n (used to surface deep (2nd+ lvl) highlights under the root post).", "type": "boolean", "nullable": true }, "quoteApproval": { "description": "Quote approval policy info, including viewer's approval status", "type": "object", "allOf": [ { "$ref": "#/components/schemas/QuoteApproval" } ], "nullable": true }, "address": { "description": "Post location", "type": "object", "allOf": [ { "$ref": "#/components/schemas/AddressData" } ], "nullable": true }, "replyTo": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "conversationId": { "$ref": "#/components/schemas/TypeId" } } }, "PostActivity": { "required": [ "user", "createdAt" ], "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" }, "createdAt": { "$ref": "#/components/schemas/Instant" } } }, "PostAttachment": { "required": [ "postId", "uploadId" ], "type": "object", "properties": { "postId": { "$ref": "#/components/schemas/TypeId" }, "uploadId": { "$ref": "#/components/schemas/TypeId" } } }, "PostDelete": { "required": [ "reason" ], "type": "object", "properties": { "postId": { "description": "ID of a specific post to delete. Mutually exclusive with reportId.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "ps_01hxcvk1hjexere4pvtrj0ymqq", "nullable": true }, "reportId": { "description": "ID of a report whose associated posts should be deleted. Mutually exclusive with postId.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "rp_01hxcvk1hjexere4pvtrj0ymqq", "nullable": true }, "reason": { "description": "Reason for deleting the post(s). Will be recorded in audit logs and report notes.", "type": "string", "example": "Violates community guidelines - hate speech" } } }, "PostEdit": { "required": [ "id", "text", "summary", "sensitive", "uploads", "mentions", "pollOptions", "createdAt", "ownerType" ], "type": "object", "properties": { "id": { "$ref": "#/components/schemas/TypeId" }, "text": { "type": "string" }, "summary": { "type": "string", "nullable": true }, "sensitive": { "type": "boolean", "nullable": true }, "uploads": { "type": "array", "items": { "$ref": "#/components/schemas/Upload" } }, "mentions": { "type": "array", "items": { "format": "uri", "type": "string" } }, "pollOptions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "$ref": "#/components/schemas/Instant" }, "card": { "allOf": [ { "$ref": "#/components/schemas/Card" } ], "nullable": true }, "emojis": { "type": "array", "items": { "$ref": "#/components/schemas/Emoji" }, "nullable": true }, "ownerType": { "$ref": "#/components/schemas/PostOwnerType" }, "kind": { "$ref": "#/components/schemas/PostKind" }, "mediaType": { "$ref": "#/components/schemas/PostMediaType" } } }, "PostKind": { "enum": [ "Note", "Article" ], "type": "string" }, "PostMediaType": { "enum": [ "TEXT_PLAIN", "MARKDOWN" ], "type": "string" }, "PostOwnerType": { "description": "\n Owner types for posts and drafts:\n * USER - user's channel (personal or group channel)\n * EVENT - event (personal or group)\n\n ** POST OWNER: **\n - Personal channel\n - userId = author\n - ownerId = userId (Type.USER)\n - ownerType = USER\n - groupId = null\n - Personal event\n - userId = author\n - ownerId = eventId (Type.EVENT)\n - ownerType = EVENT\n - groupId = null\n - Group channel\n - userId = author\n - ownerId = channel userId (Type.GROUP_CHANNEL, gc_ prefix)\n - ownerType = USER\n - groupId = groupId\n - Group event\n - userId = author\n - ownerId = eventId (Type.EVENT)\n - ownerType = EVENT\n - groupId = groupId\n ", "enum": [ "USER", "EVENT" ], "type": "string" }, "PostPrivacy": { "description": "\n Privacy levels for posts:\n * PUBLIC - post is visible to anyone, including people who are not logged in and those who do not follow the user.\n It appears in the public timelines (home, local, and federated).\n * UNLISTED - post is visible to anyone who visits the user's profile, but it does not appear in public timelines.\n Only followers and those who visit the user's profile directly can see it.\n * PRIVATE - post is only visible to the user's followers. It does not appear in public timelines or on the user's profile for non-followers.\n * DIRECT - post is visible only to the mentioned users. It functions like a direct message and is not visible on public timelines, the user's profile, or to followers.\n * FOLLOW_POST - comment only. Follow parent post visibility\n * HIDDEN - post is visible only to the author. It is never federated on create/delete. Transitioning to a visible privacy sends\n * Create for born-hidden posts and Update for re-unhide. Visible-to-HIDDEN is allowed only for personal root posts.\n ", "enum": [ "PUBLIC", "UNLISTED", "PRIVATE", "DIRECT", "FOLLOW_POST", "HIDDEN" ], "type": "string" }, "PostPublisher": { "description": "Publisher (channel or group) shown for mixed-scope lists such as search results", "required": [ "id", "type", "username", "displayName", "domain" ], "type": "object", "properties": { "id": { "description": "Publisher id (user id for channels, group id for groups)", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "type": { "description": "Publisher type (USER or GROUP)", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Type" } ] }, "username": { "description": "Publisher username (channel username or group name)", "type": "string" }, "displayName": { "description": "Publisher display name", "type": "string" }, "domain": { "description": "Publisher domain", "type": "string" }, "avatar": { "description": "Publisher avatar (channel avatar or group avatar)", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Upload" } ], "nullable": true }, "groupAvatar": { "description": "Group avatar (only present for group channels)", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Upload" } ], "nullable": true }, "groupId": { "description": "Group id (only present for group channels)", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "groupName": { "description": "Group name (only present for group channels)", "type": "string", "nullable": true }, "groupDisplayName": { "description": "Group display name (only present for group channels)", "type": "string", "nullable": true }, "groupPrivacy": { "description": "Channel privacy within a group (PUBLIC or PRIVATE)", "type": "string", "allOf": [ { "$ref": "#/components/schemas/GroupChannelPrivacy" } ], "nullable": true }, "groupUserName": { "description": "Channel username within a group (only present for group channels)", "type": "string", "nullable": true } } }, "PostSettings": { "type": "object", "properties": { "commentsEnabled": { "type": "boolean" }, "sensitive": { "type": "boolean" }, "hiddenFrom": { "allOf": [ { "$ref": "#/components/schemas/PostPrivacy" } ], "nullable": true } } }, "PostStats": { "type": "object", "properties": { "likes": { "format": "int32", "type": "integer" }, "reposts": { "format": "int32", "type": "integer" }, "quotes": { "format": "int32", "type": "integer" }, "comments": { "format": "int32", "type": "integer" }, "views": { "format": "int32", "type": "integer" }, "bookmarks": { "format": "int32", "type": "integer" }, "reactions": { "type": "object", "additionalProperties": { "format": "int32", "type": "integer" } }, "watchTime": { "format": "int64", "type": "integer", "nullable": true }, "secondsToFirstAnswer": { "format": "int32", "type": "integer", "nullable": true }, "secondsToAccepted": { "format": "int32", "type": "integer", "nullable": true }, "lastActivity": { "$ref": "#/components/schemas/Instant" }, "lastViewTimestamp": { "$ref": "#/components/schemas/Instant" } } }, "PostTranslation": { "required": [ "text" ], "type": "object", "properties": { "text": { "type": "string" }, "spoiler_text": { "type": "string", "nullable": true }, "media_attachments": { "type": "array", "items": { "$ref": "#/components/schemas/Attachment" } }, "poll": { "allOf": [ { "$ref": "#/components/schemas/Poll1" } ], "nullable": true }, "detected_source_language": { "type": "string", "nullable": true }, "provider": { "type": "string", "nullable": true } } }, "PostVotesSummary": { "required": [ "upvotes", "downvotes" ], "type": "object", "properties": { "upvotes": { "format": "int32", "description": "upvotes count", "type": "integer" }, "downvotes": { "format": "int32", "description": "downvotes count", "type": "integer" }, "ownVote": { "format": "int32", "description": "current user's vote, if any", "type": "integer", "nullable": true } } }, "ProcessJob": { "required": [ "uploadId", "uploadType", "properties" ], "type": "object", "properties": { "jobId": { "$ref": "#/components/schemas/TypeId" }, "uploadId": { "$ref": "#/components/schemas/TypeId" }, "uploadType": { "$ref": "#/components/schemas/UploadType" }, "originalFileSize": { "format": "int64", "type": "integer" }, "attempts": { "format": "int32", "type": "integer" }, "progress": { "format": "double", "type": "number" }, "properties": { "type": "array", "items": { "$ref": "#/components/schemas/ActionProperties" } }, "deleteOriginal": { "type": "boolean" }, "error": { "type": "string", "nullable": true }, "startedAt": { "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true }, "finishedAt": { "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true }, "createdAt": { "$ref": "#/components/schemas/Instant" }, "updatedAt": { "$ref": "#/components/schemas/Instant" }, "upload": { "allOf": [ { "$ref": "#/components/schemas/Upload" } ], "nullable": true } } }, "PubKeyCredParam": { "required": [ "type", "alg" ], "type": "object", "properties": { "type": { "type": "string", "nullable": true }, "alg": { "format": "int64", "type": "integer", "nullable": true } } }, "PublicKeyCredentialCreationOptions": { "required": [ "challenge", "rp", "user", "pubKeyCredParams", "timeout", "attestation", "authenticatorSelection", "excludeCredentials", "extensions" ], "type": "object", "properties": { "challenge": { "description": "Base64url-encoded server challenge", "type": "string" }, "rp": { "description": "Relying Party entity (name and id)", "type": "object", "allOf": [ { "$ref": "#/components/schemas/RpEntity" } ], "nullable": true }, "user": { "description": "User entity; id is base64url-encoded", "type": "object", "allOf": [ { "$ref": "#/components/schemas/UserEntity" } ], "nullable": true }, "pubKeyCredParams": { "description": "List of acceptable credential parameters (type and COSE alg)", "type": "array", "items": { "$ref": "#/components/schemas/PubKeyCredParam" }, "nullable": true }, "timeout": { "format": "int64", "description": "Timeout in milliseconds", "type": "integer", "nullable": true }, "attestation": { "description": "Attestation conveyance preference", "type": "string", "nullable": true }, "authenticatorSelection": { "description": "Authenticator selection constraints", "type": "object", "allOf": [ { "$ref": "#/components/schemas/AuthenticatorSelectionCriteria" } ], "nullable": true }, "excludeCredentials": { "description": "Credentials to exclude from creation (by descriptor)", "type": "array", "items": { "$ref": "#/components/schemas/PublicKeyCredentialDescriptor" }, "nullable": true }, "extensions": { "description": "Extension inputs keyed by extension name", "type": "object", "additionalProperties": {}, "nullable": true } } }, "PublicKeyCredentialDescriptor": { "required": [ "type", "id", "transports" ], "type": "object", "properties": { "type": { "type": "string", "nullable": true }, "id": { "type": "string", "nullable": true }, "transports": { "type": "array", "items": { "type": "string" }, "nullable": true } } }, "PublicKeyCredentialRequestOptions": { "description": "Options for passkey authentication", "required": [ "challenge", "timeout", "rpId", "allowCredentials", "userVerification", "extensions" ], "type": "object", "properties": { "challenge": { "description": "Base64url-encoded challenge", "type": "string" }, "timeout": { "format": "int64", "description": "Timeout in milliseconds", "type": "integer" }, "rpId": { "description": "Relying Party ID", "type": "string" }, "allowCredentials": { "description": "List of allowed credentials for assertion (by descriptor)", "type": "array", "items": { "$ref": "#/components/schemas/PublicKeyCredentialDescriptor" }, "nullable": true }, "userVerification": { "description": "User verification requirement (preferred/required/discouraged)", "type": "string", "nullable": true }, "extensions": { "description": "Extension inputs keyed by extension name", "type": "object", "additionalProperties": {}, "nullable": true } } }, "PublicPoint": { "type": "object", "properties": { "data": { "type": "array", "items": { "format": "int32", "type": "integer" } } } }, "Publisher": { "required": [ "name", "url" ], "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "url": { "type": "string", "nullable": true }, "logo": { "type": "string", "nullable": true }, "type": { "type": "string", "nullable": true } } }, "Question": { "description": "A question that prospective group members must answer during the join process. Questions are used to screen members when a group's join mode is set to QUESTIONS.", "required": [ "questionText", "type", "ordering", "id" ], "type": "object", "properties": { "questionText": { "description": "The question text displayed to users (max 200 characters)", "maxLength": 200, "pattern": "\\S", "type": "string", "example": "Why do you want to join this group?" }, "type": { "description": "Question type determining the answer format (TEXT, SINGLE_CHOICE, MULTIPLE_CHOICE)", "type": "string", "allOf": [ { "$ref": "#/components/schemas/QuestionType" } ] }, "choices": { "description": "Available choices for SINGLE_CHOICE or MULTIPLE_CHOICE questions. Empty for TEXT questions.", "type": "array", "items": { "$ref": "#/components/schemas/Choice" } }, "ordering": { "format": "int32", "description": "Display order position - questions with lower values appear first", "minimum": 0, "type": "integer", "example": 1000 }, "id": { "description": "Unique identifier for the question", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "qu_01hz1f0gs9fe4a37jzvzn9m96k" } } }, "QuestionAnswer": { "description": "Stored question answers for a user and group", "required": [ "answerId", "groupId", "userId", "answers", "answerToken", "createdAt" ], "type": "object", "properties": { "answerId": { "description": "Unique answer ID", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "groupId": { "description": "Group ID the answers are for", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "userId": { "description": "User ID who submitted the answers", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "answers": { "description": "The submitted answers", "type": "array", "items": { "$ref": "#/components/schemas/Answer" } }, "answerToken": { "description": "Token for group joining", "type": "string" }, "createdAt": { "description": "When the answers were submitted", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] } } }, "QuestionAnswerCreate": { "description": "Request payload for submitting answers to all required group entry questions. Must include an answer for each active question in the group.", "required": [ "answers" ], "type": "object", "properties": { "answers": { "description": "Complete list of answers corresponding to all group questions", "type": "array", "items": { "$ref": "#/components/schemas/Answer" } } } }, "QuestionAnswerResponse": { "description": "Response returned after successfully submitting answers to group questions. Contains a token that must be provided when calling the group join endpoint.", "required": [ "answerToken", "submittedAt" ], "type": "object", "properties": { "answerToken": { "description": "Authentication token to be used with the group join endpoint. Has a limited validity period.", "type": "string", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }, "submittedAt": { "description": "ISO 8601 timestamp indicating when the answers were submitted", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "example": "2024-01-15T10:30:00Z" } } }, "QuestionCreate": { "description": "Request payload for creating a new group question. Provide choices only for SINGLE_CHOICE and MULTIPLE_CHOICE question types.", "required": [ "questionText", "type", "ordering" ], "type": "object", "properties": { "questionText": { "description": "The question text displayed to users (max 200 characters)", "maxLength": 200, "pattern": "\\S", "type": "string", "example": "Why do you want to join this group?" }, "type": { "description": "Question type determining the answer format (TEXT, SINGLE_CHOICE, MULTIPLE_CHOICE)", "type": "string", "allOf": [ { "$ref": "#/components/schemas/QuestionType" } ] }, "choices": { "description": "Available choices for SINGLE_CHOICE or MULTIPLE_CHOICE questions. Empty for TEXT questions.", "type": "array", "items": { "$ref": "#/components/schemas/Choice" } }, "ordering": { "format": "int32", "description": "Display order position - questions with lower values appear first", "minimum": 0, "type": "integer", "example": 1000 } } }, "QuestionType": { "description": "The type of question that determines the expected answer format and validation rules", "enum": [ "TEXT", "MULTIPLE_CHOICE", "SINGLE_CHOICE" ], "type": "string" }, "QuestionUpdate": { "description": "Request payload for updating an existing question. All fields are required and will replace the current values. Ensure choices array matches the question type.", "required": [ "questionText", "type", "ordering" ], "type": "object", "properties": { "questionText": { "description": "The question text displayed to users (max 200 characters)", "maxLength": 200, "pattern": "\\S", "type": "string", "example": "Why do you want to join this group?" }, "type": { "description": "Question type determining the answer format (TEXT, SINGLE_CHOICE, MULTIPLE_CHOICE)", "type": "string", "allOf": [ { "$ref": "#/components/schemas/QuestionType" } ] }, "choices": { "description": "Available choices for SINGLE_CHOICE or MULTIPLE_CHOICE questions. Empty for TEXT questions.", "type": "array", "items": { "$ref": "#/components/schemas/Choice" } }, "ordering": { "format": "int32", "description": "Display order position - questions with lower values appear first", "minimum": 0, "type": "integer", "example": 1000 } } }, "QueueSummary": { "required": [ "queue", "count", "averageTimeInQueueMillis", "oldestTimeInQueueMillis" ], "type": "object", "properties": { "queue": { "$ref": "#/components/schemas/UploadJobsQueue" }, "count": { "format": "int32", "type": "integer" }, "averageTimeInQueueMillis": { "format": "int64", "type": "integer" }, "oldestTimeInQueueMillis": { "format": "int64", "type": "integer" }, "averageProcessingTimeMillis": { "format": "int64", "type": "integer" }, "averageWaitingTimeMillis": { "format": "int64", "type": "integer" }, "p95TimeInQueueMillis": { "format": "int64", "type": "integer" }, "successCount": { "format": "int32", "type": "integer" }, "failureCount": { "format": "int32", "type": "integer" } } }, "QuoteApproval": { "description": "Quote approval policy and viewer status for a post", "required": [ "policy", "automatic", "manual" ], "type": "object", "properties": { "policy": { "description": "Effective quote policy for this post", "type": "string", "allOf": [ { "$ref": "#/components/schemas/QuotePolicyLevel" } ] }, "automatic": { "description": "Categories that get automatic approval (e.g. 'public', 'followers')", "type": "array", "items": { "type": "string" } }, "manual": { "description": "Categories that require manual approval", "type": "array", "items": { "type": "string" } }, "currentUser": { "description": "Current user's approval status: 'automatic', 'manual', or null", "type": "string", "nullable": true } } }, "QuotePolicyLevel": { "enum": [ "PUBLIC", "FOLLOWERS", "NOBODY" ], "type": "string" }, "RBACPermissions": { "description": "Type-safe collection of resource-specific access permissions", "required": [ "resourceAccess" ], "type": "object", "properties": { "resourceAccess": { "description": "List of type-safe resource-specific access controls", "type": "array", "items": { "$ref": "#/components/schemas/RBACResourceAccess" } } } }, "RBACResourceAccess": { "description": "Defines type-safe access permissions for a specific resource", "required": [ "resource", "actions" ], "type": "object", "properties": { "resource": { "description": "The type-safe resource being controlled", "allOf": [ { "$ref": "#/components/schemas/RbacResource" } ] }, "actions": { "description": "List of allowed type-safe actions for this resource", "type": "array", "items": { "$ref": "#/components/schemas/RbacAction" } } } }, "RBACRole": { "description": "Represents a role within the RBAC (Role-Based Access Control) system", "required": [ "roleId", "name", "permissions", "createdAt", "updatedAt" ], "type": "object", "properties": { "roleId": { "description": "Unique identifier for the role", "type": "string", "allOf": [ { "$ref": "#/components/schemas/RoleId" } ], "example": "rr_01hxcvk1hjexere4pvtrj0ymqq" }, "name": { "description": "Name of the role, unique within its scope", "type": "string", "example": "ADMIN" }, "description": { "description": "Optional description of the role's purpose and responsibilities", "type": "string", "example": "System administrator with full access", "nullable": true }, "permissions": { "description": "Set of permissions assigned to this role", "type": "object", "allOf": [ { "$ref": "#/components/schemas/RBACPermissions" } ] }, "isAdmin": { "description": "Whether this custom role has admin-level permissions. For group-scoped roles, compared against GROUP_MEMBER baseline. For global-scoped roles, compared against SYSTEM_USER baseline. Auto-computed at creation/update time.", "type": "boolean", "example": true }, "createdAt": { "description": "Timestamp when the role was created", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "example": "2023-01-01T00:00:00Z" }, "updatedAt": { "description": "Timestamp when the role was last updated", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "example": "2023-01-01T00:00:00Z" } } }, "RBACRoleTemplate": { "description": "Template for creating new RBAC roles", "required": [ "name", "scope", "permissions" ], "type": "object", "properties": { "name": { "description": "Name of the role, unique within its scope", "type": "string", "example": "user" }, "description": { "description": "Optional description of the role's purpose and responsibilities", "type": "string", "example": "The regular user", "nullable": true }, "scope": { "description": "\n The scope in which the role is valid.\n The scope can be Global (hardcoded), currently the only one is \"global\".\n Also the scope can be dynamic, currently we use Group Id, like \"gr_05hxcvk1hjexere4pvtrj0hggt\"\n ", "type": "string", "example": "global" }, "permissions": { "description": "Set of permissions to be assigned to this role", "type": "object", "allOf": [ { "$ref": "#/components/schemas/RBACPermissions" } ] } } }, "RecalculationInfo": { "description": "Recalculation job progress information", "required": [ "status", "processedPosts", "totalToProcess", "startedAt", "estimatedSecondsRemaining", "errorMessage" ], "type": "object", "properties": { "status": { "description": "Job status", "type": "string", "allOf": [ { "$ref": "#/components/schemas/RecalculationStatus" } ] }, "processedPosts": { "format": "int64", "description": "Posts processed so far", "type": "integer" }, "totalToProcess": { "format": "int64", "description": "Total posts to process in this job", "type": "integer" }, "startedAt": { "description": "When the job started", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true }, "estimatedSecondsRemaining": { "format": "int64", "description": "Estimated seconds remaining (null if not calculable)", "type": "integer", "nullable": true }, "errorMessage": { "description": "Error message if job failed", "type": "string", "nullable": true } } }, "RecalculationStatus": { "enum": [ "IDLE", "PENDING", "RUNNING", "COMPLETED", "CANCELLED", "FAILED" ], "type": "string" }, "RedisJob": { "required": [ "jobHash", "job", "queueName" ], "type": "object", "properties": { "jobHash": { "$ref": "#/components/schemas/UUID" }, "job": { "type": "string" }, "queueName": { "type": "string" }, "tries": { "format": "int32", "type": "integer" }, "createdAt": { "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true }, "startTime": { "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true }, "lastTryAt": { "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true }, "lastError": { "type": "string", "nullable": true }, "endTime": { "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true } } }, "RedisJobsResult": { "required": [ "list", "total" ], "type": "object", "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/RedisJob" } }, "total": { "format": "int32", "type": "integer" } } }, "RegistrationMode": { "description": "\n Registration mode:\n * OPEN - everybody can sign up.\n * APPROVAL - approval is required for sign up.\n * EMAIL_DOMAIN_ALLOWLIST - only users with emails from the configured allowlist can sign up.\n * CLOSED - new sign ups are closed.\n ", "enum": [ "OPEN", "APPROVAL", "EMAIL_DOMAIN_ALLOWLIST", "CLOSED" ], "type": "string" }, "RegistrationRequest": { "required": [ "name", "baseUrl", "serverId", "publicKey" ], "type": "object", "properties": { "name": { "type": "string" }, "baseUrl": { "format": "uri", "type": "string" }, "serverId": { "type": "string" }, "publicKey": { "$ref": "#/components/schemas/Ed25519PublicKey" } } }, "RegistrationResponse": { "required": [ "hash", "nextStep" ], "type": "object", "properties": { "hash": { "type": "string" }, "nextStep": { "$ref": "#/components/schemas/SignupRequestStep" } } }, "Relationship": { "description": "Relationship between the viewer and a target user", "type": "object", "properties": { "following": { "description": "Does the viewer follow the target?", "type": "string", "allOf": [ { "$ref": "#/components/schemas/FollowingStatus" } ], "nullable": true }, "followed": { "description": "Does the target follow the viewer?", "type": "string", "allOf": [ { "$ref": "#/components/schemas/FollowingStatus" } ], "nullable": true }, "blocked": { "description": "Viewer blocked the target", "type": "boolean", "nullable": true }, "blockedBy": { "description": "Target blocked the viewer", "type": "boolean", "nullable": true }, "muted": { "description": "Viewer mutes the target", "type": "object", "allOf": [ { "$ref": "#/components/schemas/MuteState" } ], "nullable": true }, "note": { "description": "Viewer's private note about the target", "type": "string", "nullable": true } } }, "RemoteFileInfo": { "description": "Contains uri and file extension of the remote file. The uri should be a valid URL.", "required": [ "uri", "extension" ], "type": "object", "properties": { "uri": { "format": "uri", "type": "string" }, "extension": { "type": "string" } } }, "Report": { "description": "A report for a post, user, or group", "required": [ "id", "uri", "targetId", "groupId", "state", "assignedUserId", "actionTakenBy", "actionTakenAt", "forwarded", "createdAt", "updatedAt" ], "type": "object", "properties": { "id": { "description": "Internal report ID", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "rp_01hz1f0kw36f82k9s4nzpc4s92n" }, "uri": { "format": "uri", "description": "Report URI", "type": "string" }, "targetId": { "description": "Target being reported (post, user, or group TypeId)", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "pt_01hz1f0jkdw3h27a2kdr8sn2kt" }, "groupId": { "description": "\n Report scope.\n If null the scope is global (server admins handle it).\n If set the scope is group (group admins handle it).\n ", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "state": { "description": "Current state of the report", "type": "string", "allOf": [ { "$ref": "#/components/schemas/ReportState" } ] }, "assignedUserId": { "description": "Moderator assigned to handle the report", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "us_01hz1fkfg82hf89s2nzqwer02r", "nullable": true }, "actionTakenBy": { "description": "Moderator who took action on the report", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "us_01hz1fkfg82hf89s2nzqwer02r", "nullable": true }, "actionTakenAt": { "description": "When action was taken on the report", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true }, "forwarded": { "description": "Whether this report was forwarded via ActivityPub", "type": "boolean" }, "notes": { "description": "Internal admin notes", "type": "array", "items": { "$ref": "#/components/schemas/ReportNote" } }, "createdAt": { "description": "When the report was created", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] }, "updatedAt": { "description": "When the report was last updated", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] }, "post": { "description": "Target post (if targetId is a post)", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Post" } ], "nullable": true }, "targetUser": { "description": "Target user (if targetId is a user)", "type": "object", "allOf": [ { "$ref": "#/components/schemas/User" } ], "nullable": true }, "targetGroup": { "description": "Target group (if targetId is a group)", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Group" } ], "nullable": true }, "assignedUser": { "description": "Assigned admin (populated)", "type": "object", "allOf": [ { "$ref": "#/components/schemas/User" } ], "nullable": true }, "comments": { "description": "Report comments/submissions from users", "type": "array", "items": { "$ref": "#/components/schemas/ReportComment" }, "nullable": true } } }, "ReportComment": { "description": "A comment/submission on a report from a user", "required": [ "id", "reportId", "userId", "comment", "type", "createdAt" ], "type": "object", "properties": { "id": { "description": "Comment ID", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "rc_01hz1f0kw36f82k9s4nzpc4s92n" }, "reportId": { "description": "Report this comment belongs to", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "userId": { "description": "User who submitted this report (local or remote)", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "comment": { "description": "The report comment/reason text", "type": "string" }, "type": { "description": "Type/reason for the report", "type": "string", "allOf": [ { "$ref": "#/components/schemas/ReportType" } ] }, "uploadIds": { "description": "Attachment upload IDs", "type": "array", "items": { "$ref": "#/components/schemas/TypeId" } }, "createdAt": { "description": "When this comment was created", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] }, "user": { "description": "User who submitted this report (populated)", "type": "object", "allOf": [ { "$ref": "#/components/schemas/User" } ], "nullable": true }, "uploads": { "description": "Attachments (populated)", "type": "array", "items": { "$ref": "#/components/schemas/Upload" }, "nullable": true } } }, "ReportNote": { "description": "Internal admin note on a report", "required": [ "userId", "note", "createdAt" ], "type": "object", "properties": { "userId": { "description": "User who added the note", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "note": { "description": "Note text", "type": "string" }, "createdAt": { "description": "When the note was added", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] }, "user": { "description": "User who added the note (populated)", "type": "object", "allOf": [ { "$ref": "#/components/schemas/User" } ], "nullable": true } } }, "ReportSortBy": { "description": "\n Sort options for aggregated report views:\n * TARGET_UPDATED - Sort by target's last update date\n * REPORTED_DATE - Sort by most recent report date\n * LAST_NOTE_DATE - Sort by most recent admin note date\n ", "enum": [ "TARGET_UPDATED", "REPORTED_DATE", "LAST_NOTE_DATE" ], "type": "string" }, "ReportState": { "description": "\n State of the report:\n * OPEN - Report is open and unassigned\n * UNDER_REVIEW - Report is assigned to an admin or moderator and is being reviewed\n * DISMISSED - Report was closed without action taken\n * RESOLVED - Report was closed with action taken\n ", "enum": [ "OPEN", "UNDER_REVIEW", "DISMISSED", "RESOLVED" ], "type": "string" }, "ReportType": { "description": "\n Type/reason for the report:\n * SPAM - Content is spam or unwanted commercial content\n * SERVER_RULES - Content violates server rules\n * GROUP_RULES - Content violates group rules\n * ILLEGAL - Content is illegal\n * OTHER - Other reason (see comment for details)\n ", "enum": [ "SPAM", "SERVER_RULES", "GROUP_RULES", "ILLEGAL", "OTHER" ], "type": "string" }, "ReportedGroup": { "description": "Aggregated view of a reported group", "required": [ "group", "report", "latestReportDate", "latestNoteDate", "openReportCount", "totalReportCount" ], "type": "object", "properties": { "group": { "description": "The reported group", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Group" } ] }, "report": { "description": "The report for this group", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Report" } ] }, "latestReportDate": { "description": "Most recent report timestamp", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] }, "latestNoteDate": { "description": "Most recent admin note timestamp", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true }, "openReportCount": { "format": "int32", "description": "Number of open reports", "type": "integer" }, "totalReportCount": { "format": "int32", "description": "Total number of reports", "type": "integer" } } }, "ReportedGroupsPaginatedResponse": { "description": "Paginated list of reported groups", "required": [ "list", "total" ], "type": "object", "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/ReportedGroup" } }, "total": { "format": "int32", "type": "integer" }, "offset": { "format": "int32", "type": "integer", "nullable": true } } }, "ReportedPost": { "description": "Aggregated view of a reported post", "required": [ "post", "report", "latestReportDate", "latestNoteDate", "openReportCount", "totalReportCount" ], "type": "object", "properties": { "post": { "description": "The reported post", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Post" } ] }, "report": { "description": "The report for this post", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Report" } ] }, "latestReportDate": { "description": "Most recent report timestamp", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] }, "latestNoteDate": { "description": "Most recent admin note timestamp", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true }, "openReportCount": { "format": "int32", "description": "Number of open reports", "type": "integer" }, "totalReportCount": { "format": "int32", "description": "Total number of reports", "type": "integer" } } }, "ReportedPostsPaginatedResponse": { "description": "Paginated list of reported posts", "required": [ "list", "total" ], "type": "object", "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/ReportedPost" } }, "total": { "format": "int32", "type": "integer" }, "offset": { "format": "int32", "type": "integer", "nullable": true } } }, "ReportedUser": { "description": "Aggregated view of a reported user", "required": [ "user", "report", "latestReportDate", "latestNoteDate", "openReportCount", "totalReportCount" ], "type": "object", "properties": { "user": { "description": "The reported user", "type": "object", "allOf": [ { "$ref": "#/components/schemas/User" } ] }, "report": { "description": "The report for this user", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Report" } ] }, "latestReportDate": { "description": "Most recent report timestamp", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] }, "latestNoteDate": { "description": "Most recent admin note timestamp", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true }, "openReportCount": { "format": "int32", "description": "Number of open reports", "type": "integer" }, "totalReportCount": { "format": "int32", "description": "Total number of reports", "type": "integer" } } }, "ReportedUsersPaginatedResponse": { "description": "Paginated list of reported users", "required": [ "list", "total" ], "type": "object", "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/ReportedUser" } }, "total": { "format": "int32", "type": "integer" }, "offset": { "format": "int32", "type": "integer", "nullable": true } } }, "ReportsPaginatedResponse": { "description": "Paginated list of reports", "required": [ "list", "total" ], "type": "object", "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/Report" } }, "total": { "format": "int32", "type": "integer" }, "offset": { "format": "int32", "type": "integer", "nullable": true } } }, "RepostParam": { "description": "\n Options for '?repostKind' param\n * REPOST - repost only\n * QUOTE - quote only\n * ALL - any, has the same effect as omitting the param\n ", "enum": [ "REPOST", "QUOTE", "ALL" ], "type": "string" }, "ResourceModel": { "required": [ "name", "description", "actions" ], "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/ActionModel" } } } }, "RoleId": { "description": "Fully qualified (scope:id) pre-defined role ID or UUID with type prefix 'rr_' ", "type": "string", "example": "\n 'admin',\n 'System:admin',\n 'rr_01hxcvk1hjexere4pvtrj0ymqq',\n 'System:rr_01hxcvk1hjexere4pvtrj0ymqq',\n 'gr_1lkjvfdoibb126576:rr_01hxcvk1hjexere4pvtrj0ymqq',\n " }, "Route": { "required": [ "path", "handler", "description" ], "type": "object", "properties": { "path": { "type": "string" }, "handler": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "entryPointFor": { "allOf": [ { "$ref": "#/components/schemas/EntryPoint" } ], "nullable": true }, "order": { "format": "int32", "type": "integer" }, "permissions": { "allOf": [ { "$ref": "#/components/schemas/RoutePermissions" } ], "nullable": true } } }, "RoutePermissions": { "type": "object", "properties": { "anyOf": { "type": "array", "items": { "$ref": "#/components/schemas/RBACResourceAccess" }, "nullable": true }, "allOf": { "type": "array", "items": { "$ref": "#/components/schemas/RBACResourceAccess" }, "nullable": true } } }, "RpEntity": { "required": [ "id", "name" ], "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true } } }, "Rule": { "description": "A rule that governs member conduct and content policies within a group or platform. Rules help establish community guidelines and expected behavior standards.", "required": [ "text", "hint", "ordering", "id" ], "type": "object", "properties": { "text": { "description": "The rule text that defines expected behavior or policy (max 500 characters)", "maxLength": 500, "type": "string", "example": "Be respectful to all members" }, "hint": { "description": "Additional context or clarification for the rule (max 500 characters)", "maxLength": 500, "type": "string", "example": "This includes no harassment, personal attacks, or discriminatory language" }, "ordering": { "format": "int32", "description": "Display order position - rules with lower values appear first", "minimum": 0, "type": "integer", "example": 1000 }, "id": { "description": "Unique identifier for the rule", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "rl_01hz1f0gs9fe4a37jzvzn9m96k" } } }, "RuleCreate": { "description": "Request payload for creating a new rule. Provide text, hint, and ordering.", "required": [ "text", "hint", "ordering" ], "type": "object", "properties": { "text": { "description": "The rule text that defines expected behavior or policy (max 500 characters)", "maxLength": 500, "type": "string", "example": "Be respectful to all members" }, "hint": { "description": "Additional context or clarification for the rule (max 500 characters)", "maxLength": 500, "type": "string", "example": "This includes no harassment, personal attacks, or discriminatory language" }, "ordering": { "format": "int32", "description": "Display order position - rules with lower values appear first", "minimum": 0, "type": "integer", "example": 1000 } } }, "RuleOrderingRequest": { "description": "Request payload for updating a rule's display order position", "required": [ "id", "ordering" ], "type": "object", "properties": { "id": { "description": "The unique identifier of the rule to reorder", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "rl_01hz1f0gs9fe4a37jzvzn9m96k" }, "ordering": { "format": "int32", "description": "New display order position (lower values appear first)", "minimum": 0, "type": "integer", "example": 1000 } } }, "RuleUpdate": { "description": "Request payload for updating an existing rule. All fields are required and will replace the current values. To maintain existing values, provide the current content.", "required": [ "text", "hint", "ordering" ], "type": "object", "properties": { "text": { "description": "The rule text that defines expected behavior or policy (max 500 characters)", "maxLength": 500, "type": "string", "example": "Be respectful to all members" }, "hint": { "description": "Additional context or clarification for the rule (max 500 characters)", "maxLength": 500, "type": "string", "example": "This includes no harassment, personal attacks, or discriminatory language" }, "ordering": { "format": "int32", "description": "Display order position - rules with lower values appear first", "minimum": 0, "type": "integer", "example": 1000 } } }, "Salary": { "description": "Salary data", "required": [ "min", "max", "currency", "payType" ], "type": "object", "properties": { "min": { "format": "double", "description": "The lower boundary of the salary range", "maximum": 10000000, "minimum": 0, "type": "number", "nullable": true }, "max": { "format": "double", "description": "The upper boundary of the salary range", "maximum": 10000000, "minimum": 0, "type": "number", "nullable": true }, "currency": { "description": "The currency in which the salary is paid", "maxLength": 64, "type": "string", "example": "USD, EURO...", "nullable": true }, "payType": { "description": "The pay type/period", "maxLength": 128, "type": "string", "example": "Hourly, Weekly, Annually", "nullable": true } } }, "SearchDetails": { "description": "Search results for users", "required": [ "list", "total", "totalUsers" ], "type": "object", "properties": { "list": { "description": "List of user details matching the search criteria", "type": "array", "items": { "$ref": "#/components/schemas/UserDetails" } }, "total": { "format": "int32", "description": "Total number of results for the current search", "type": "integer" }, "totalUsers": { "format": "int32", "description": "Total number of users in the system", "type": "integer" } } }, "SearchFilter": { "enum": [ "users", "posts", "tags", "events", "groups" ], "type": "string" }, "SearchResult": { "type": "object", "properties": { "users": { "type": "array", "items": { "$ref": "#/components/schemas/UserFull" } }, "posts": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } }, "tags": { "type": "array", "items": { "type": "string" } }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/Group" } } } }, "ServerInfo": { "required": [ "users", "posts", "followers", "followings", "reports", "available", "failureDays", "failureThreshold" ], "type": "object", "properties": { "users": { "format": "int64", "type": "integer" }, "posts": { "format": "int64", "type": "integer" }, "followers": { "format": "int64", "description": "N of remote users who are being followed from this server", "type": "integer" }, "followings": { "format": "int64", "description": "N of local users who follow users on this domain", "type": "integer" }, "reports": { "format": "int32", "description": "N of reports against users of this domain", "type": "integer" }, "available": { "description": "Whether it's whitelisted when limited federation mode is on", "type": "boolean" }, "failureDays": { "format": "int32", "description": "N of days federation has been unavailable for this domain", "type": "integer" }, "failureThreshold": { "format": "double", "description": "Duration in seconds", "type": "number", "allOf": [ { "$ref": "#/components/schemas/Duration" } ] }, "blocked": { "allOf": [ { "$ref": "#/components/schemas/BlockedDomain" } ], "nullable": true } } }, "ServerTotals": { "description": "Current server totals for users and posts", "required": [ "users", "localPosts", "remotePosts", "groups", "localComments", "remoteComments", "updatedAt" ], "type": "object", "properties": { "users": { "format": "int64", "description": "Total number of users on the server", "type": "integer" }, "localPosts": { "format": "int64", "description": "Total number of local posts on the server", "type": "integer" }, "remotePosts": { "format": "int64", "description": "Total number of remote posts on the server", "type": "integer" }, "groups": { "format": "int64", "description": "Total number of groups on the server", "type": "integer" }, "localComments": { "format": "int64", "description": "Total number of local comments on the server", "type": "integer" }, "remoteComments": { "format": "int64", "description": "Total number of remote comments on the server", "type": "integer" }, "updatedAt": { "description": "Last updated timestamp", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] } } }, "ServersResult": { "required": [ "list", "total", "failureThreshold" ], "type": "object", "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/ServersResultInfo" } }, "total": { "format": "int32", "type": "integer" }, "failureThreshold": { "format": "double", "description": "Duration in seconds", "type": "number", "allOf": [ { "$ref": "#/components/schemas/Duration" } ] } } }, "ServersResultInfo": { "required": [ "domain", "users", "failureDays", "available", "allowed", "blocked", "reports" ], "type": "object", "properties": { "domain": { "type": "string" }, "users": { "format": "int64", "type": "integer" }, "failureDays": { "format": "int32", "description": "N of days federation has been unavailable for this domain", "type": "integer" }, "available": { "type": "boolean" }, "allowed": { "description": "Whether it's whitelisted when limited federation mode is on", "type": "boolean" }, "blocked": { "allOf": [ { "$ref": "#/components/schemas/DomainBlockState" } ], "nullable": true }, "reports": { "format": "int32", "type": "integer" }, "rejectMedia": { "description": "Whether media files from this domain are rejected", "type": "boolean", "nullable": true }, "rejectReports": { "description": "Whether reports from this domain are rejected", "type": "boolean", "nullable": true } } }, "SessionExtra": { "type": "object", "properties": { "userAgent": { "type": "string", "nullable": true }, "os": { "type": "string", "nullable": true } } }, "SessionInfo": { "required": [ "sessionKey", "state", "accountId", "userId", "loginType", "ip", "createdAt", "countryCode", "countryName", "subdivision", "city", "extra" ], "type": "object", "properties": { "sessionKey": { "type": "string" }, "state": { "$ref": "#/components/schemas/SessionState" }, "accountId": { "$ref": "#/components/schemas/TypeId" }, "userId": { "$ref": "#/components/schemas/TypeId" }, "loginType": { "$ref": "#/components/schemas/LoginType" }, "ip": { "$ref": "#/components/schemas/InetAddress" }, "createdAt": { "$ref": "#/components/schemas/Instant" }, "countryCode": { "type": "string", "nullable": true }, "countryName": { "type": "string", "nullable": true }, "subdivision": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "extra": { "$ref": "#/components/schemas/SessionExtra" }, "lastUsed": { "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true } } }, "SessionState": { "enum": [ "ACTIVE", "EXPIRED" ], "type": "string" }, "SetDefaultRequest": { "required": [ "providerId" ], "type": "object", "properties": { "providerId": { "format": "int64", "description": "Provider ID to set as default", "type": "integer" } } }, "SetTagPolicyRequest": { "description": "Request to set tag policy mode for a scope", "required": [ "mode" ], "type": "object", "properties": { "mode": { "description": "Policy mode: 'whitelist' or 'blacklist'", "enum": [ "WHITELIST", "BLACKLIST" ], "type": "string", "example": "blacklist" } } }, "SignupInviteLink": { "description": "Invite link for user signups", "required": [ "code", "ownerUserId", "usedCount", "active", "createdAt", "accounts" ], "type": "object", "properties": { "code": { "description": "Unique invite code", "type": "string" }, "ownerUserId": { "description": "Owner user id who created the link", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "expiresAt": { "description": "Expiration timestamp (UTC)", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true }, "maxUses": { "format": "int32", "description": "Maximum number of uses. Null means unlimited.", "type": "integer", "nullable": true }, "usedCount": { "format": "int32", "description": "Number of uses so far", "type": "integer" }, "active": { "description": "Whether link is active (not deactivated)", "type": "boolean" }, "createdAt": { "description": "Creation timestamp (UTC)", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] }, "deactivatedAt": { "description": "Deactivation timestamp (UTC)", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true }, "accounts": { "description": "List of account IDs created using this link", "type": "array", "items": { "$ref": "#/components/schemas/TypeId" } } } }, "SignupInviteLinkCreate": { "description": "Create a signup invite link", "type": "object", "properties": { "expiresAt": { "description": "Expiration timestamp (UTC). Must be in the future if provided.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true }, "maxUses": { "format": "int32", "description": "Maximum number of uses. Use null or 0 for unlimited", "minimum": 0, "type": "integer", "example": 3, "nullable": true } } }, "SignupInviteLinkList": { "description": "Paginated list of signup invite links", "required": [ "links", "total" ], "type": "object", "properties": { "links": { "type": "array", "items": { "$ref": "#/components/schemas/SignupInviteLink" } }, "total": { "format": "int32", "type": "integer" } } }, "SignupReasonParams": { "description": "Reason for signing up for admin approval", "required": [ "hash", "reason" ], "type": "object", "properties": { "hash": { "description": "Registration hash", "pattern": "\\S", "type": "string", "example": "aaaaaaa-ccccccccccccc-wwwwwwwww" }, "reason": { "description": "Reason for signing up for admin approval", "maxLength": 1024, "pattern": "\\S", "type": "string" } } }, "SignupRequest": { "required": [ "hash", "username", "displayName", "password", "confirmationType", "reason", "ip", "userAgent", "createdAt" ], "type": "object", "properties": { "hash": { "description": "Unique hash for the signup request", "type": "string", "example": "hash123" }, "email": { "description": "Email address for the account", "type": "string", "example": "john@example.com", "nullable": true }, "phone": { "description": "Phone number for the account", "type": "string", "example": "+12345678901", "nullable": true }, "username": { "description": "Username for the first user", "type": "string", "example": "john_smith" }, "displayName": { "description": "Display name for the first user", "maxLength": 56, "minLength": 1, "type": "string", "example": "John Smith" }, "password": { "description": "Account password, enforced by password policy", "type": "string", "example": "PassW0rd!", "nullable": true }, "confirmationType": { "description": "Current step in the signup flow", "type": "string", "allOf": [ { "$ref": "#/components/schemas/SignupRequestStep" } ], "example": "EMAIL" }, "reason": { "description": "Reason for creating account", "type": "string", "example": "Reason for signup" }, "ip": { "description": "IP address of the user", "type": "object", "allOf": [ { "$ref": "#/components/schemas/InetAddress" } ] }, "userAgent": { "description": "User agent of the user", "type": "string", "example": "Mozilla/5.0" }, "geoData": { "description": "Geolocation data of the user", "type": "object", "allOf": [ { "$ref": "#/components/schemas/GeoData" } ], "nullable": true }, "createdAt": { "description": "Creation timestamp of the request", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "example": "2023-01-01T00:00:00Z" }, "inviteCode": { "description": "Invite code if provided", "type": "string", "example": "abcd-efgh-1234", "nullable": true } } }, "SignupRequestResult": { "required": [ "list", "total" ], "type": "object", "properties": { "list": { "description": "List of signup requests", "type": "array", "items": { "$ref": "#/components/schemas/SignupRequest" } }, "total": { "format": "int32", "description": "Total number of signup requests matching the query", "type": "integer", "example": 42 } } }, "SignupRequestStep": { "description": "\n Shows the current step in the signup flow:\n * EMAIL – We sent an email to the user with a verification code. The user must enter the code\n to confirm their email.\n * PHONE – We sent a text to the user with a verification code. The user must enter the code\n to confirm their phone number.\n * CAPTCHA – The user must complete a CAPTCHA verification.\n * REASON – The user must provide a reason for admins to approve their signup request.\n * ADMIN – Admins must approve or reject the user's signup request. No action is required from the user.\n * USER – The final step that creates the account. Most of the time, no action is required from the user.\n If the account can't be created because the username is already taken, the user can\n provide a different username at this step.\n ", "enum": [ "EMAIL", "PHONE", "CAPTCHA", "REASON", "ADMIN", "USER" ], "type": "string" }, "SlidingWindowMetrics": { "description": "\n Wall-clock aligned tumbling window metrics for monitoring operation performance over time periods.\n\n **Key Features:**\n - Windows are aligned to wall-clock boundaries (e.g., 10:00-10:10, 10:10-10:20)\n - All operations share the same window boundaries for consistent comparison\n - Windows reset completely when they expire (tumbling, not sliding)\n - Memory-efficient with constant storage per operation per window\n\n **Synchronous Boundaries:** All operations use identical window start/end times\n ```\n 10:05 - \"follow\" metric → Window: 10:00-10:10\n 10:07 - \"create-note\" metric → Window: 10:00-10:10 (same window)\n 10:11 - \"follow\" metric → Window: 10:10-10:20 (new window)\n ```\n\n **Complete Reset on Expiration:**\n ```\n Window 10:00-10:10: follow(avg=150ms, count=45)\n Window 10:10-10:20: follow(avg=200ms, count=12) ← Fresh start\n ```\n\n **Gap Handling:**\n ```\n 10:05 - Metrics recorded → Window: 10:00-10:10\n [No activity for 25 minutes]\n 10:35 - New metric → Window: 10:30-10:40 ← Fresh window\n ```\n Previous windows (10:10-10:20, 10:20-10:30) remain empty/non-existent.\n\n **Limitations:**\n - **Not true sliding**: Old data is completely lost when windows expire\n - **Coarse granularity**: Only shows averages per window, not sub-window patterns\n - **No historical depth**: Only current window data is retained\n\n **UI Display Recommendations:**\n ```\n \"Follow operations: 150ms avg (45 ops, 10:00-10:10, last updated 10:08:30)\"\n ```\n Use windowCreated and lastUpdated to show clear time boundaries and data freshness.\n ", "required": [ "average", "count", "totalTime", "lastUpdated", "operation", "windowCreated" ], "type": "object", "properties": { "average": { "format": "double", "description": "Average duration in milliseconds for operations in this window", "type": "number" }, "count": { "format": "int64", "description": "Total number of operations recorded in this window", "type": "integer" }, "totalTime": { "format": "int64", "description": "Sum of all operation durations in milliseconds", "type": "integer" }, "lastUpdated": { "description": "When the last metric was added to this window", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] }, "operation": { "description": "The operation name being tracked", "type": "string" }, "windowCreated": { "description": "When this window was created (first metric timestamp)", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] } } }, "SlowestOperationsResponse": { "required": [ "slowestOperations", "totalOperationsAnalyzed" ], "type": "object", "properties": { "slowestOperations": { "type": "array", "items": { "$ref": "#/components/schemas/GlobalAggregatedMetrics" } }, "totalOperationsAnalyzed": { "format": "int32", "type": "integer" } } }, "SlowestUsersResponse": { "required": [ "slowestUsers", "operation", "limit" ], "type": "object", "properties": { "slowestUsers": { "type": "array", "items": { "$ref": "#/components/schemas/UserMetrics" } }, "operation": { "allOf": [ { "$ref": "#/components/schemas/FeedOperation" } ], "nullable": true }, "limit": { "format": "int32", "type": "integer" } } }, "SortOrder": { "description": "\n Sort order for query results:\n * ASC - Ascending order (smallest to largest, oldest to newest)\n * DESC - Descending order (largest to smallest, newest to oldest)\n ", "enum": [ "ASC", "DESC" ], "type": "string" }, "StreamingData": { "description": "Incoming message from a websocket subscription. Streamable API.\n `data` can be User, Post, Notification depending on the type and context.\n ", "required": [ "type", "topic", "data" ], "type": "object", "properties": { "type": { "$ref": "#/components/schemas/StreamingType" }, "topic": { "type": "string" }, "data": { "oneOf": [ { "$ref": "#/components/schemas/Post" }, { "$ref": "#/components/schemas/UserFull" }, { "$ref": "#/components/schemas/TypeId" }, { "$ref": "#/components/schemas/Notification" }, { "$ref": "#/components/schemas/AsyncRefreshUpdate" } ] }, "meta": { "type": "object", "additionalProperties": {}, "nullable": true } } }, "StreamingType": { "description": "\n Type of the incoming websocket message.\n dictionary:\n * POST_NEW - feed:* topics new post, add to the feed, check sorting. `data` is Post.\n * POST_UPDATE - post:* and feed:* topics. If topic is feed, update inside the feed. `data` is Post.\n * POST_REMOVE - feed:* topics. `data` is TypeId (postId)\n * REPOST - post: and feed: topics. `data` Post (repost/quote with originalPost as repostOf)\n * LIKE - post:* and feed:* topics. `data` is Post with the new likes count.\n * COMMENT - post:* and feed:* topics. `data` is Post (comment with originalPost as replyTo)\n * COMMENT_REMOVE - post:* and feed:* topics. `data` is TypeId (comment ID)\n * USER_UPDATE - user:* topic, updated user data. `data` is UserView\n * USER_REMOVE - user:* topic, updated user data. `data` is TypeId (userId)\n * ACCOUNT - account:* topic, updated account data. `data` is AccountWithUser\n * NOTIFICATION - notification:* topic, new notification. `data` is Notification\n * NOTIFICATION_UNDO - notification:* topic, removed notifications. `data` is TypeId (notificationId)\n * ASYNC_REFRESH_UPDATE - async_refresh:* topic, terminal async refresh status update. `data` is AsyncRefreshUpdate\n * EVENT_NEW - events:* topics, new event. `data` is Event\n * EVENT_UPDATE - event:* and events:* topics, updated event. `data` is Event\n * EVENT_CANCEL - event:* and events:* topics, cancelled event. `data` is Event\n * EVENT_ATTENDEES - event:* and events:* topics, updated attendees or join/interest. `data` is Event\n * EVENT_DELETE - event:* and events:* topics, deleted event. `data` is TypeId (eventId)\n ", "enum": [ "POST_NEW", "POST_UPDATE", "POST_REMOVE", "REPOST", "LIKE", "COMMENT_NEW", "COMMENT_UPDATE", "COMMENT_REMOVE", "USER_UPDATE", "USER_REMOVE", "ACCOUNT", "NOTIFICATION", "NOTIFICATION_UNDO", "ASYNC_REFRESH_UPDATE", "EVENT_NEW", "EVENT_UPDATE", "EVENT_CANCEL", "EVENT_DELETE", "EVENT_ATTENDEES" ], "type": "string" }, "SubscriptionType": { "enum": [ "lifecycle", "trends" ], "type": "string" }, "SubscriptionView": { "required": [ "id", "category", "subscriptionType", "createdAt", "updatedAt" ], "type": "object", "properties": { "id": { "format": "int64", "description": "Subscription ID", "type": "integer" }, "category": { "description": "Content category", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Category" } ] }, "subscriptionType": { "description": "Subscription type", "type": "string", "allOf": [ { "$ref": "#/components/schemas/SubscriptionType" } ] }, "createdAt": { "description": "When the subscription was created", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] }, "updatedAt": { "description": "When the subscription was last updated", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] } } }, "SupportedLanguage": { "required": [ "code", "nativeName" ], "type": "object", "properties": { "code": { "type": "string" }, "nativeName": { "type": "string" } } }, "SyncState": { "description": "\n Sync state for remote users:\n * SHALLOW_SYNCED - Profile fetched, only first page of outbox loaded\n * SYNC_IN_PROGRESS - Deep sync is currently running\n * DEEP_SYNCED - Full outbox has been fetched\n * DEEP_SYNC_FAILED - Deep sync attempted but failed (retryable)\n ", "enum": [ "SHALLOW_SYNCED", "SYNC_IN_PROGRESS", "DEEP_SYNCED", "DEEP_SYNC_FAILED" ], "type": "string" }, "Tag": { "required": [ "name" ], "type": "object", "properties": { "name": { "type": "string" }, "totalUses": { "format": "int32", "type": "integer", "nullable": true }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/TagHistory" }, "nullable": true } } }, "TagHistory": { "required": [ "uses", "date" ], "type": "object", "properties": { "uses": { "format": "int32", "type": "integer" }, "date": { "$ref": "#/components/schemas/LocalDate" } } }, "TagPolicyMode": { "enum": [ "WHITELIST", "BLACKLIST" ], "type": "string" }, "TimeGranularity": { "description": "Time granularity for metrics aggregation", "enum": [ "HOUR", "DAY", "MONTH" ], "type": "string" }, "TimeZone": { "description": "User's timezone preferences", "required": [ "ianaTimezone", "autoUpdate", "show" ], "type": "object", "properties": { "ianaTimezone": { "type": "string", "nullable": true }, "autoUpdate": { "type": "boolean" }, "show": { "type": "boolean" } } }, "TimezoneInfo": { "required": [ "value", "abbr", "offset", "isdst", "text", "utc" ], "type": "object", "properties": { "value": { "type": "string" }, "abbr": { "type": "string" }, "offset": { "format": "float", "type": "number" }, "isdst": { "type": "boolean" }, "text": { "type": "string" }, "utc": { "type": "array", "items": { "type": "string" } } } }, "Token": { "required": [ "sessionKey" ], "type": "object", "properties": { "sessionKey": { "description": "Persistent Token", "type": "string" } } }, "TokenRecoverConfirmRequest": { "required": [ "email", "code" ], "type": "object", "properties": { "email": { "description": "Admin email address", "type": "string" }, "code": { "description": "Verification code received via email", "type": "string" } } }, "TokenRecoverRequest": { "required": [ "email" ], "type": "object", "properties": { "email": { "description": "Admin email address for recovery", "type": "string" } } }, "TokenRotationConfirmRequest": { "required": [ "code" ], "type": "object", "properties": { "code": { "description": "Verification code received via email", "type": "string" } } }, "TokenRotationConfirmResponse": { "required": [ "success" ], "type": "object", "properties": { "success": { "description": "Whether the token rotation was successful", "type": "boolean" }, "newTokenMasked": { "description": "Masked new admin token", "type": "string", "nullable": true } } }, "TranslationRequest": { "required": [ "text", "language" ], "type": "object", "properties": { "text": { "type": "string" }, "language": { "$ref": "#/components/schemas/Language" }, "isHtml": { "type": "boolean" } } }, "TranslationResponse": { "required": [ "text" ], "type": "object", "properties": { "text": { "type": "string" } } }, "Type": { "enum": [ "USER", "ACCOUNT", "PLATFORM_APP", "APPLICATION", "BOT", "GROUP_CHANNEL", "APP_DATA", "POST", "POLL", "TAG", "TAG_REPORT", "USER_LIST", "NOTIFICATION", "REPORT", "REPORT_COMMENT", "RULE", "QUESTION", "ANSWER", "GROUP", "DRAFT", "UPLOAD", "FILE", "UPLOAD_ACTION", "UPLOAD_JOB", "EXECUTION", "EMPLOYEE_PROFILE", "EMPLOYER_PROFILE", "JOB_POSTING", "JOB_APPLICATION", "MEMBER_LIST", "RBAC_ROLE", "JOIN_REQUEST", "GROUP_INVITE", "EVENT", "AI_PROVIDER", "AI_MODEL", "AI_JOB", "AI_SIGNAL", "AI_SCOPED_PROVIDER", "AI_SCOPED_MODEL", "EMBEDDING_RECALC", "ASYNC_REFRESH", "QUOTE_AUTH", "EMPTY" ], "type": "string" }, "UUID": { "format": "uuid", "pattern": "[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}", "type": "string" }, "UpdateEvent": { "description": "Event params that can be changed", "type": "object", "properties": { "name": { "description": "Event name", "type": "string", "example": "New Event Name", "nullable": true }, "startTime": { "description": "Event start time in UTC", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "example": "2024-02-18T15:00:00Z", "nullable": true }, "endTime": { "description": "Event end time in UTC.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "example": "2024-02-18T18:00:00Z", "nullable": true }, "ianaTimeZone": { "description": "Event IANA time zone name", "type": "string", "example": "Europe/Paris", "nullable": true }, "description": { "description": "Event's description", "type": "string", "example": "This is a birthday party", "nullable": true }, "url": { "format": "uri", "description": "Event URL", "type": "string", "nullable": true }, "address": { "description": "Event address", "type": "object", "allOf": [ { "$ref": "#/components/schemas/AddressData" } ], "nullable": true }, "imageId": { "description": "Event cover image id.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "removeEndTime": { "description": "Remove event's endTime.", "type": "boolean" }, "removeImage": { "description": "Remove event's image.", "type": "boolean" }, "removeAddress": { "description": "Remove event's address.", "type": "boolean" }, "removeDescription": { "description": "Remove event's description.", "type": "boolean" } } }, "UpdateEventsSettings": { "description": "Events Settings update", "required": [ "exportPublicCalendar", "exportPublicDetails", "exportPublicEvents", "exportPrivateCalendar", "exportPrivateEvents" ], "type": "object", "properties": { "exportPublicCalendar": { "description": "Enable public calendar export", "type": "boolean" }, "exportPublicDetails": { "description": "Enable public calendar export with full event details", "type": "boolean" }, "exportPublicEvents": { "description": "Events to export in public calendar", "type": "string", "allOf": [ { "$ref": "#/components/schemas/ExportCalendarEvents" } ] }, "exportPrivateCalendar": { "description": "Enable private calendar export", "type": "boolean" }, "exportPrivateEvents": { "description": "Events to export in private calendar", "type": "string", "allOf": [ { "$ref": "#/components/schemas/ExportCalendarEvents" } ] }, "exportPrivateCalendarUniqueId": { "description": "Private calendar unique id", "type": "string", "nullable": true } } }, "UpdateInteractionPolicy": { "description": "Update quote approval policy on an existing post", "required": [ "quoteApprovalPolicy" ], "type": "object", "properties": { "quoteApprovalPolicy": { "description": "Quote approval policy: PUBLIC, FOLLOWERS, or NOBODY", "type": "string", "allOf": [ { "$ref": "#/components/schemas/QuotePolicyLevel" } ] } } }, "UpdateUploadOwner": { "description": "Request body for changing upload owner", "required": [ "newOwnerId" ], "type": "object", "properties": { "newOwnerId": { "description": "New owner ID for the upload", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] } } }, "UpdateUploadPrivacy": { "description": "Update upload privacy request", "required": [ "privacy" ], "type": "object", "properties": { "privacy": { "description": "New privacy of the upload. Possible values: PUBLIC, PRIVATE, DIRECT.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/UploadPrivacy" } ], "example": "PUBLIC" }, "allowedUsers": { "description": "\n Can contain a list of users who are allowed to access the upload.\n Works only for uploads with privacy set to DIRECT.\n ", "uniqueItems": true, "type": "array", "items": { "type": "string" }, "nullable": true } } }, "Upload": { "description": "Uploaded file", "required": [ "uploadId", "ownerId", "uploadType", "size", "files", "tags", "createdAt", "updatedAt" ], "type": "object", "properties": { "uploadId": { "description": "Internal id", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "up_kjhwieuy2387928371" }, "uploaderId": { "description": "User who physically uploaded this file. Null for platform-owned uploads (e.g., default covers). This is an audit/meta field — use ownerId for authorization.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "us_97234khddqdkuhqwij", "nullable": true }, "ownerId": { "description": "Entity that owns this upload (user, channel/group, or event). TypeID prefix indicates the owner type.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "us_97234khddqdkuhqwij" }, "attachedToId": { "description": "Entity this upload is attached to (e.g., a post or event). NULL for standalone uploads like avatars, covers, or media library items.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "pt_97234khddqdkuhqwij", "nullable": true }, "uploadType": { "description": "Type of the upload", "type": "string", "allOf": [ { "$ref": "#/components/schemas/UploadType" } ] }, "meta": { "description": "Meta data", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Meta" } ] }, "size": { "format": "int64", "description": "Size in bytes of all the files in this upload", "type": "integer" }, "files": { "description": "List of all the files this upload has", "type": "array", "items": { "$ref": "#/components/schemas/FileDesc" } }, "tags": { "description": "List of tags attached to upload", "uniqueItems": true, "type": "array", "items": { "$ref": "#/components/schemas/UploadsTags" } }, "error": { "description": "Upload processing error", "type": "string", "nullable": true }, "cached": { "description": "true if cached", "type": "boolean" }, "logs": { "description": "Logs", "type": "string", "nullable": true }, "remote": { "description": "true if this upload is remote", "type": "boolean" }, "createdAt": { "$ref": "#/components/schemas/Instant" }, "updatedAt": { "$ref": "#/components/schemas/Instant" } } }, "UploadJobsQueue": { "enum": [ "Submitted", "InProgress", "Completed" ], "type": "string" }, "UploadList": { "description": "Upload list request", "required": [ "userId" ], "type": "object", "properties": { "userId": { "$ref": "#/components/schemas/TypeId" }, "tags": { "uniqueItems": true, "type": "array", "items": { "$ref": "#/components/schemas/UploadsTags" } }, "orderType": { "type": "string" }, "page": { "format": "int32", "type": "integer" }, "limit": { "format": "int32", "type": "integer" } } }, "UploadLog": { "required": [ "message" ], "type": "object", "properties": { "createdAt": { "$ref": "#/components/schemas/Instant" }, "message": { "type": "string" } } }, "UploadPrivacy": { "enum": [ "Public", "Private", "Direct" ], "type": "string" }, "UploadType": { "description": "Upload type: IMAGE, VIDEO, AUDIO, DOCUMENT", "enum": [ "VIDEO", "IMAGE", "AUDIO", "DOCUMENT", "OTHER" ], "type": "string", "example": "video" }, "UploadUsages": { "required": [ "posts", "avatars", "headers" ], "type": "object", "properties": { "posts": { "type": "array", "items": { "$ref": "#/components/schemas/PostAttachment" } }, "avatars": { "type": "array", "items": { "$ref": "#/components/schemas/TypeId" }, "nullable": true }, "headers": { "type": "array", "items": { "$ref": "#/components/schemas/TypeId" }, "nullable": true } } }, "UploadsTags": { "description": "Tags attached to the upload", "enum": [ "Post", "Avatar", "Header", "Album", "Emoji", "Event" ], "type": "string", "example": "$post" }, "UpsertDraftRequest": { "required": [ "items" ], "type": "object", "properties": { "items": { "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/CreatePost" } } } }, "User": { "description": "One of account's users.\n Can be multiple per account", "required": [ "id", "username", "domain", "local", "displayName", "uri", "createdAt", "state", "channel", "followApproval" ], "type": "object", "properties": { "id": { "description": "internal id of this user", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "username": { "description": "unique user name", "type": "string", "example": "john_smith" }, "domain": { "description": "User's domain", "type": "string", "example": "wlsly1.net" }, "local": { "description": "Whether this user is local to this server", "type": "boolean" }, "displayName": { "description": "full name of the user", "type": "string", "example": "John Smith" }, "uri": { "format": "uri", "description": "URI of this user", "type": "string", "example": "https://wlsly1.net/users/john_smith" }, "avatar": { "description": "User's avatar", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Upload" } ], "nullable": true }, "createdAt": { "description": "User's creation time", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] }, "state": { "description": "User's moderation state", "type": "string", "allOf": [ { "$ref": "#/components/schemas/UserState" } ] }, "relationship": { "description": "Relationship with this user", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Relationship" } ], "nullable": true }, "entityType": { "description": "Entity type: USER, BOT, APPLICATION, GROUP_CHANNEL", "type": "string", "allOf": [ { "$ref": "#/components/schemas/EntityType" } ] }, "appMeta": { "description": "Structured metadata (channel flags, channel color, etc.)", "type": "object", "allOf": [ { "$ref": "#/components/schemas/AppMeta" } ] }, "groupId": { "description": "Group ID if this is a group channel or group user.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "groupPrivacy": { "description": "Privacy of this channel in a group.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/GroupChannelPrivacy" } ], "nullable": true }, "groupUserName": { "description": "Name of the channel inside a group", "type": "string", "nullable": true }, "actorType": { "description": "Whether this user is a person, application or a service", "type": "string", "allOf": [ { "$ref": "#/components/schemas/ActorType" } ], "nullable": true }, "channel": { "description": "Whether this is a channel or a user. Deprecated: use 'entityType' instead.", "type": "boolean", "deprecated": true }, "deleted": { "type": "boolean", "nullable": true }, "groupAvatar": { "description": "Group avatar (only present for group channels)", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Upload" } ], "nullable": true }, "groupName": { "description": "Group name (only present for group channels)", "type": "string", "nullable": true }, "groupDisplayName": { "description": "Group display name (only present for group channels)", "type": "string", "nullable": true }, "followApproval": { "description": "Follow approval mode: AUTO_APPROVE, MANUALLY_APPROVES, or UNKNOWN", "type": "string", "allOf": [ { "$ref": "#/components/schemas/FollowApprovalMode" } ] }, "groupPrimary": { "description": "true if this is primary group channel.", "type": "boolean", "nullable": true }, "groupAutoSubscribe": { "description": "true if this is auto-subscribe group channel.", "type": "boolean", "nullable": true } } }, "UserCountResponse": { "required": [ "operation", "userCount" ], "type": "object", "properties": { "operation": { "$ref": "#/components/schemas/FeedOperation" }, "userCount": { "format": "int64", "type": "integer" } } }, "UserCreate": { "description": "Params to create new user. Can be multiple per account", "required": [ "username", "displayName" ], "type": "object", "properties": { "username": { "description": "Username", "type": "string", "example": "john_smith" }, "displayName": { "description": "Display Name", "pattern": "\\S", "type": "string", "example": "John Smith" }, "summary": { "description": "User's bio", "maxLength": 1024, "type": "string", "example": "I work in IT", "nullable": true }, "avatarId": { "description": "Avatar upload id or null to remove", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "headerId": { "description": "Header upload id or null to remove", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "channel": { "description": "Marks a USER entity as a user channel", "type": "boolean" }, "entityType": { "description": "Entity type: USER or APPLICATION", "type": "string", "allOf": [ { "$ref": "#/components/schemas/EntityType" } ] } } }, "UserDetails": { "description": "Detailed user information", "required": [ "userId", "username", "displayName", "local", "numPosts", "numFollowers", "createdAt", "state", "actorType" ], "type": "object", "properties": { "userId": { "description": "Internal ID of this user", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "accountId": { "description": "ID of the account this user belongs to, empty for remote users", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "username": { "description": "Unique username", "type": "string", "example": "john_smith" }, "displayName": { "description": "Full name of the user", "type": "string", "example": "John Smith" }, "email": { "description": "User's email address", "type": "string", "example": "john@example.com", "nullable": true }, "domain": { "description": "User's domain", "type": "string", "example": "domain.net", "nullable": true }, "local": { "description": "Whether this user is local to this server", "type": "boolean" }, "numPosts": { "format": "int64", "description": "Number of posts by this user", "type": "integer" }, "numFollowers": { "format": "int32", "description": "Number of followers this user has", "type": "integer" }, "createdAt": { "description": "When this user was created", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] }, "deletedAt": { "description": "When this user was deleted, if applicable", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true }, "lastActive": { "description": "When this user was last active", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true }, "lastIP": { "description": "Last IP address used by this user", "type": "object", "allOf": [ { "$ref": "#/components/schemas/InetAddress" } ], "nullable": true }, "lastGeoData": { "description": "Last geo data from which this user accessed the system", "type": "object", "allOf": [ { "$ref": "#/components/schemas/GeoData" } ], "nullable": true }, "state": { "description": "User's moderation state", "type": "string", "allOf": [ { "$ref": "#/components/schemas/UserState" } ] }, "entityType": { "description": "Entity type: USER, BOT, APPLICATION, GROUP_CHANNEL", "type": "string", "allOf": [ { "$ref": "#/components/schemas/EntityType" } ] }, "actorType": { "description": "Actor type derived from entity type", "type": "string", "allOf": [ { "$ref": "#/components/schemas/ActorType" } ] }, "channel": { "description": "Whether this is a channel. Deprecated: use 'entityType' instead.", "type": "boolean", "deprecated": true }, "groupId": { "description": "Group id if this user is a group channel", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "roles": { "description": "Roles assigned to this user", "type": "array", "items": { "$ref": "#/components/schemas/UserRole" } }, "avatar": { "description": "User's avatar", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Upload" } ], "nullable": true } } }, "UserDevice": { "required": [ "userId", "deviceId", "fcmToken", "endpoint", "p256dh", "auth", "platform", "createdAt", "updatedAt" ], "type": "object", "properties": { "userId": { "description": "User ID owning this device", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "deviceId": { "description": "Unique device identifier from client (fid)", "type": "string" }, "fcmToken": { "description": "FCM token for the device", "type": "string" }, "endpoint": { "description": "Relay endpoint to deliver to FCM", "type": "string" }, "p256dh": { "description": "User public key for encrypted push", "type": "string" }, "auth": { "description": "User auth secret for encrypted push", "type": "string" }, "platform": { "description": "Device platform", "type": "string", "allOf": [ { "$ref": "#/components/schemas/DevicePlatform" } ] }, "device": { "description": "Optional device description", "type": "string", "nullable": true }, "createdAt": { "$ref": "#/components/schemas/Instant" }, "updatedAt": { "$ref": "#/components/schemas/Instant" } } }, "UserEntity": { "required": [ "id", "name", "displayName" ], "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "displayName": { "type": "string", "nullable": true } } }, "UserFeedCountResponse": { "required": [ "userId", "username", "cachedPostCount", "feedType" ], "type": "object", "properties": { "userId": { "$ref": "#/components/schemas/TypeId" }, "username": { "type": "string" }, "cachedPostCount": { "format": "int64", "type": "integer" }, "feedType": { "$ref": "#/components/schemas/FeedType" } } }, "UserField": { "required": [ "value" ], "type": "object", "properties": { "value": { "type": "string" }, "verifiedAt": { "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true } } }, "UserFull": { "description": "One of account's users.\n Can be multiple per account", "required": [ "id", "username", "domain", "local", "displayName", "uri", "createdAt", "state", "channel", "summary", "software", "followApproval" ], "type": "object", "properties": { "id": { "description": "internal id of this user", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "username": { "description": "unique user name", "type": "string", "example": "john_smith" }, "domain": { "description": "User's domain", "type": "string", "example": "wlsly1.net" }, "local": { "description": "Whether this user is local to this server", "type": "boolean" }, "displayName": { "description": "full name of the user", "type": "string", "example": "John Smith" }, "uri": { "format": "uri", "description": "URI of this user", "type": "string", "example": "https://wlsly1.net/users/john_smith" }, "avatar": { "description": "User's avatar", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Upload" } ], "nullable": true }, "createdAt": { "description": "User's creation time", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] }, "state": { "description": "User's moderation state", "type": "string", "allOf": [ { "$ref": "#/components/schemas/UserState" } ] }, "relationship": { "description": "Relationship with this user", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Relationship" } ], "nullable": true }, "entityType": { "description": "Entity type: USER, BOT, APPLICATION, GROUP_CHANNEL", "type": "string", "allOf": [ { "$ref": "#/components/schemas/EntityType" } ] }, "appMeta": { "description": "Structured metadata (channel flags, channel color, etc.)", "type": "object", "allOf": [ { "$ref": "#/components/schemas/AppMeta" } ] }, "groupId": { "description": "Group ID if this is a group channel or group user.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "groupPrivacy": { "description": "Privacy of this channel in a group.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/GroupChannelPrivacy" } ], "nullable": true }, "groupUserName": { "description": "Name of the channel inside a group", "type": "string", "nullable": true }, "actorType": { "description": "Whether this user is a person, application or a service", "type": "string", "allOf": [ { "$ref": "#/components/schemas/ActorType" } ], "nullable": true }, "channel": { "description": "Whether this is a channel or a user. Deprecated: use 'entityType' instead.", "type": "boolean", "deprecated": true }, "summary": { "description": "User's summary or bio", "type": "string", "example": "Pixels are my paint, code is my canvas, creativity is my brush." }, "stats": { "description": "User stats", "type": "object", "allOf": [ { "$ref": "#/components/schemas/UserStats" } ] }, "fields": { "description": "User fields", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/UserField" } }, "header": { "description": "User's header", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Upload" } ], "nullable": true }, "deleted": { "type": "boolean", "nullable": true }, "emojis": { "type": "array", "items": { "$ref": "#/components/schemas/Emoji" }, "nullable": true }, "location": { "description": "User's location, geo and name", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Location" } ], "nullable": true }, "timezone": { "description": "User's timezone", "type": "object", "allOf": [ { "$ref": "#/components/schemas/TimeZone" } ], "nullable": true }, "birthday": { "description": "User's birthday", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Birthday" } ], "nullable": true }, "software": { "description": "Software platform type (wellesley, mastodon, threads.net)", "type": "string", "example": "wellesley" }, "groupAvatar": { "description": "Group avatar (only present for group channels)", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Upload" } ], "nullable": true }, "groupName": { "description": "Group name (only present for group channels)", "type": "string", "nullable": true }, "groupDisplayName": { "description": "Group display name (only present for group channels)", "type": "string", "nullable": true }, "syncState": { "description": "Sync state for remote users (null for local users). SHALLOW_SYNCED = profile fetched, SYNC_IN_PROGRESS = deep sync running, DEEP_SYNCED = full outbox fetched, DEEP_SYNC_FAILED = deep sync failed", "type": "string", "allOf": [ { "$ref": "#/components/schemas/SyncState" } ], "nullable": true }, "deepSyncedAt": { "description": "When the last deep sync completed (null if never deep-synced)", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true }, "followApproval": { "description": "Follow approval mode: AUTO_APPROVE, MANUALLY_APPROVES, or UNKNOWN", "type": "string", "allOf": [ { "$ref": "#/components/schemas/FollowApprovalMode" } ] }, "groupPrimary": { "description": "true if this is primary group channel.", "type": "boolean", "nullable": true }, "groupAutoSubscribe": { "description": "true if this is auto-subscribe group channel.", "type": "boolean", "nullable": true } } }, "UserGroupsFilter": { "description": "\n Filter options for retrieving user's groups:\n * ALL_SORTED - Returns all groups the user is a member of, sorted: pinned first (by pin order), then admins/owners, then regular members\n * PINNED_ONLY - Returns only groups the user has pinned, sorted by pin order\n ", "enum": [ "ALL_SORTED", "PINNED_ONLY" ], "type": "string" }, "UserListCreate": { "required": [ "name", "description", "icon" ], "type": "object", "properties": { "name": { "maxLength": 64, "minLength": 1, "type": "string" }, "description": { "maxLength": 512, "type": "string", "nullable": true }, "icon": { "maxLength": 256, "type": "string", "nullable": true }, "private": { "type": "boolean" }, "pinned": { "type": "boolean" } } }, "UserLite": { "required": [ "id", "displayName", "username", "domain" ], "type": "object", "properties": { "id": { "$ref": "#/components/schemas/TypeId" }, "displayName": { "type": "string" }, "username": { "type": "string" }, "domain": { "type": "string" } } }, "UserMetrics": { "type": "object" }, "UserNote": { "required": [ "ownerId", "userId", "text" ], "type": "object", "properties": { "ownerId": { "$ref": "#/components/schemas/TypeId" }, "userId": { "$ref": "#/components/schemas/TypeId" }, "text": { "maxLength": 500, "minLength": 1, "type": "string" } } }, "UserPerformanceMetrics": { "required": [ "userId", "averageTime", "totalMeasurements" ], "type": "object", "properties": { "userId": { "$ref": "#/components/schemas/TypeId" }, "averageTime": { "format": "double", "type": "number" }, "totalMeasurements": { "format": "int64", "type": "integer" } } }, "UserRole": { "description": "User role information", "required": [ "roleId", "name" ], "type": "object", "properties": { "roleId": { "description": "Internal ID of this role", "type": "string" }, "name": { "description": "Name of the role", "type": "string", "example": "ADMIN" }, "description": { "description": "The description of the role", "type": "string", "example": "The Admin role in the \"system\" scope", "nullable": true } } }, "UserState": { "description": "\n Registration mode:\n * REGULAR - just regular state\n * SENSITIVE - all media attachments are flagged as sensitive, i.e. all user's posts should be marked as sensitive, old posts and all future ones.\n * LIMITED - all user's old and future posts should be set maximum to followers only unless user set it to direct himself. non-followers should not be notified, i.e. if user mentions non-follower we do not create notification.\n * SUSPENDED - User can login, but cannot do anything in his account except to read, cannot change anything, cannot create new posts or comments etc. All his posts are marked as deleted, but we do not delete them just yet. User is scheduled to be deleted in one month. During this month it is possible to restore it via admin.\n ", "enum": [ "REGULAR", "SENSITIVE", "LIMITED", "SUSPENDED" ], "type": "string" }, "UserStats": { "description": "User stats", "required": [ "posts", "postsLast24h", "totalStorageBytes", "comments", "avgPostsPerDay", "avgBytesPerDay", "followers", "following", "followingHidden", "totalEvents" ], "type": "object", "properties": { "posts": { "format": "int64", "description": "Total number of posts", "type": "integer" }, "postsLast24h": { "format": "int64", "description": "Posts created in the last 24 hours", "type": "integer" }, "totalStorageBytes": { "format": "int64", "description": "Total uploaded bytes", "type": "integer" }, "comments": { "format": "int64", "description": "Total number of comments", "type": "integer" }, "avgPostsPerDay": { "format": "double", "description": "Average posts per day over the last 30 days", "type": "number" }, "avgBytesPerDay": { "format": "double", "description": "Average uploaded bytes per day over the last 30 days", "type": "number" }, "lastFlushVersion": { "format": "int64", "type": "integer", "nullable": true, "writeOnly": true }, "followers": { "format": "int32", "description": "number of followers", "type": "integer" }, "following": { "format": "int32", "description": "number of following", "type": "integer" }, "followingHidden": { "description": "privacy setting to hide followings", "type": "boolean" }, "totalEvents": { "format": "int64", "description": "total number of events (group/user) emitted", "type": "integer" } } }, "UserStorage": { "description": "User upload storage information, split by upload type", "required": [ "video", "image", "audio", "document", "other" ], "type": "object", "properties": { "video": { "format": "int64", "type": "integer" }, "image": { "format": "int64", "type": "integer" }, "audio": { "format": "int64", "type": "integer" }, "document": { "format": "int64", "type": "integer" }, "other": { "format": "int64", "type": "integer" } } }, "UserUpdate": { "description": "Params to update user info", "required": [ "displayName", "summary", "fields" ], "type": "object", "properties": { "displayName": { "description": "Display Name", "pattern": "\\S", "type": "string", "example": "John Smith" }, "summary": { "description": "User's bio", "maxLength": 1024, "type": "string", "example": "I work in IT" }, "avatarId": { "description": "Avatar upload id or null to remove", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "headerId": { "description": "Header upload id or null to remove", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "fields": { "description": "User fields", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/UserField" } }, "username": { "description": "Username", "type": "string", "example": "john_smith", "nullable": true }, "location": { "allOf": [ { "$ref": "#/components/schemas/Location" } ], "nullable": true }, "timezone": { "allOf": [ { "$ref": "#/components/schemas/TimeZone" } ], "nullable": true }, "birthday": { "allOf": [ { "$ref": "#/components/schemas/Birthday" } ], "nullable": true }, "appMeta": { "description": "Application metadata namespaced by reverse-domain keys", "type": "object", "allOf": [ { "$ref": "#/components/schemas/AppMeta" } ], "nullable": true } } }, "UserUpdateMedia": { "description": "Params to update user media", "type": "object", "properties": { "avatarId": { "description": "Avatar upload id or null to remove", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "headerId": { "description": "Header upload id or null to remove", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } }, "UserView": { "required": [ "state", "channel", "followApproval", "id", "username", "domain", "local", "displayName", "uri", "createdAt" ], "type": "object", "properties": { "state": { "description": "User's moderation state", "type": "string", "allOf": [ { "$ref": "#/components/schemas/UserState" } ] }, "actorType": { "description": "Whether this user is a person, application or a service", "type": "string", "allOf": [ { "$ref": "#/components/schemas/ActorType" } ], "nullable": true }, "entityType": { "description": "Entity type: USER, BOT, APPLICATION, GROUP_CHANNEL", "type": "string", "allOf": [ { "$ref": "#/components/schemas/EntityType" } ] }, "appMeta": { "description": "Structured metadata (channel flags, channel color, etc.)", "type": "object", "allOf": [ { "$ref": "#/components/schemas/AppMeta" } ] }, "channel": { "description": "Whether this is a channel or a user. Deprecated: use 'entityType' instead.", "type": "boolean", "deprecated": true }, "groupId": { "description": "Group ID if this is a group channel or group user.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "groupPrivacy": { "description": "Privacy of this channel in a group.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/GroupChannelPrivacy" } ], "nullable": true }, "groupUserName": { "description": "Name of the channel inside a group", "type": "string", "nullable": true }, "followApproval": { "description": "Follow approval mode: AUTO_APPROVE, MANUALLY_APPROVES, or UNKNOWN", "type": "string", "allOf": [ { "$ref": "#/components/schemas/FollowApprovalMode" } ] }, "groupPrimary": { "description": "true if this is primary group channel.", "type": "boolean", "nullable": true }, "groupAutoSubscribe": { "description": "true if this is auto-subscribe group channel.", "type": "boolean", "nullable": true }, "deleted": { "type": "boolean", "nullable": true }, "id": { "description": "internal id of this user", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "username": { "description": "unique user name", "type": "string", "example": "john_smith" }, "domain": { "description": "User's domain", "type": "string", "example": "wlsly1.net" }, "local": { "description": "Whether this user is local to this server", "type": "boolean" }, "displayName": { "description": "full name of the user", "type": "string", "example": "John Smith" }, "uri": { "format": "uri", "description": "URI of this user", "type": "string", "example": "https://wlsly1.net/users/john_smith" }, "createdAt": { "description": "User's creation time", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ] }, "avatar": { "description": "User's avatar", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Upload" } ], "nullable": true }, "relationship": { "description": "Relationship with this user", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Relationship" } ], "nullable": true } } }, "UserWithOwnedGroups": { "description": "User details along with groups owned by this user.", "required": [ "user", "ownedGroups" ], "type": "object", "properties": { "user": { "description": "User details", "type": "object", "allOf": [ { "$ref": "#/components/schemas/UserFull" } ] }, "ownedGroups": { "description": "Groups owned by this user", "type": "array", "items": { "$ref": "#/components/schemas/Group" } } } }, "UsernameHistories": { "required": [ "history", "maxRenames" ], "type": "object", "properties": { "history": { "type": "array", "items": { "$ref": "#/components/schemas/UsernameHistory" } }, "maxRenames": { "format": "int32", "type": "integer" } } }, "UsernameHistory": { "required": [ "username", "domain", "userId", "createdAt" ], "type": "object", "properties": { "username": { "type": "string" }, "domain": { "type": "string" }, "userId": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "createdAt": { "$ref": "#/components/schemas/Instant" } } }, "UsersList": { "required": [ "id", "userId", "name", "description", "icon", "private", "pinned", "createdAt", "updatedAt" ], "type": "object", "properties": { "id": { "description": "Internal list id", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "ul_01hz1f0kw36f82k9s4nzpc4s92n" }, "userId": { "description": "Owner of the list", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "example": "us_01hz1fkfg82hf89s2nzqwer02r" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "icon": { "type": "string", "nullable": true }, "private": { "type": "boolean" }, "pinned": { "type": "boolean" }, "createdAt": { "$ref": "#/components/schemas/Instant" }, "updatedAt": { "$ref": "#/components/schemas/Instant" }, "users": { "type": "array", "items": { "$ref": "#/components/schemas/User" } } } }, "VapidPublicKeyResponse": { "required": [ "publicKey" ], "type": "object", "properties": { "publicKey": { "description": "Base64url-encoded VAPID public key (uncompressed P-256 point)", "type": "string", "example": "BNxRG..." } } }, "WindowSize": { "description": "The size of a time window. Accepted format example: 'TEN_MINUTES' or '10m'", "enum": [ "TEN_MINUTES", "ONE_HOUR", "TWENTY_FOUR_HOURS" ], "type": "string" }, "AudioPolicy": { "type": "object", "properties": { "extensions": { "description": "Allowed audio file extensions", "type": "array", "items": { "description": "File extension", "type": "string", "example": "mp4" } }, "keepOriginal": { "description": "Whether to keep the original audio file", "type": "boolean" }, "maxSize": { "description": "Maximum allowed audio file size in bytes", "type": "integer" } } }, "CaptchaConfig": { "type": "object", "properties": { "secretKey": { "description": "hCaptcha Account secret key", "type": "string" }, "siteKey": { "description": "Sitekey if the same account is used on several sites", "type": "string" } } }, "CaptchaClientConfig": { "type": "object", "properties": { "siteKey": { "description": "Sitekey if the same account is used on several sites", "type": "string" } } }, "ConfirmationCodeConfigs": { "type": "object", "properties": { "codeExpirationMinutes": { "description": "Expiration time for confirmation code", "type": "integer" }, "counterExpirationMinutes": { "description": "Time duration after which the counter for unsuccessful attempts will be reset", "type": "integer" }, "limitCheckAttempts": { "description": "Maximum number of attempts to check confirmation code", "type": "integer" }, "limitStoreAttempts": { "description": "Maximum number of attempts to request confirmation code", "type": "integer" } } }, "DocPolicy": { "type": "object", "properties": { "extensions": { "description": "Allowed doc file extensions", "type": "array", "items": { "description": "File extension", "type": "string", "example": "mp4" } }, "maxSize": { "description": "Maximum allowed doc file size in bytes", "type": "integer" } } }, "EmbeddingModelConfig": { "type": "object", "properties": { "enabled": { "description": "Whether embeddings are enabled", "type": "boolean" }, "modelId": { "description": "Embedding model ID to use for content embeddings", "type": "string", "example": "mdl_01k..." }, "vectorDimensions": { "description": "Vector dimensions (set automatically from model)", "type": "integer" } } }, "EmojiPolicyConfig": { "type": "object", "properties": { "maxImageSize": { "description": "Maximum allowed single emoji image size in bytes", "type": "integer" }, "maxZipSize": { "description": "Maximum allowed ZIP size in bytes for emoji import", "type": "integer" } } }, "FaspRemoteAdminConfig": { "type": "object", "properties": { "adminToken": { "description": "Admin token for authenticating with the FASP server", "type": "string" }, "baseUrl": { "description": "Base URL of the FASP server", "type": "object", "properties": { "scheme": { "type": "string" }, "fragment": { "type": "string" }, "authority": { "type": "string" }, "userInfo": { "type": "string" }, "host": { "type": "string" }, "port": { "type": "integer" }, "path": { "type": "string" }, "query": { "type": "string" }, "schemeSpecificPart": { "type": "string" }, "hash": { "type": "integer" }, "decodedUserInfo": { "type": "string" }, "decodedAuthority": { "type": "string" }, "decodedPath": { "type": "string" }, "decodedQuery": { "type": "string" }, "decodedFragment": { "type": "string" }, "decodedSchemeSpecificPart": { "type": "string" }, "string": { "type": "string" } } }, "configuredAt": { "format": "date-time", "description": "Timestamp when this configuration was set", "type": "string" }, "isConfigured": { "type": "boolean" }, "serverName": { "description": "Friendly name for the FASP server", "type": "string" } } }, "FederationModeConfig": { "type": "object", "properties": { "mode": { "enum": [ "OPEN", "LIMITED", "CLOSED" ], "type": "string" } } }, "ImagePolicy": { "type": "object", "properties": { "extensions": { "description": "Allowed image file extensions", "type": "array", "items": { "description": "File extension", "type": "string", "example": "mp4" } }, "keepOriginal": { "description": "Whether to keep the original image file", "type": "boolean" }, "maxMatrix": { "description": "Maximum allowed image matrix resolution (width * height)", "type": "integer" }, "maxResolution": { "description": "Maximum allowed image resolution in pixels at the longest side", "type": "integer" }, "maxSize": { "description": "Maximum allowed image file size in bytes", "type": "integer" }, "resolutions": { "description": "List of resolutions to convert the image to", "type": "array", "items": { "type": "integer" } } } }, "InstanceAdmin": { "required": [ "email", "name", "username" ], "type": "object", "properties": { "email": { "description": "Email of the server admin", "type": "string" }, "name": { "description": "Name of the server admin", "type": "string" }, "username": { "description": "Username of the server admin", "type": "string" } } }, "InstanceLegal": { "required": [ "privacyPolicy", "termsOfUse" ], "type": "object", "properties": { "privacyPolicy": { "description": "Privacy policy text", "type": "string" }, "termsOfUse": { "description": "Terms of use text", "type": "string" } } }, "LanguageDetectionConfig": { "type": "object", "properties": { "key": { "description": "Language detection key, depends on type", "type": "string" }, "service": { "description": "Language detection service type", "enum": [ "internal", "detectlanguage", "languagelayer", "deepl" ], "type": "string" } } }, "MediaCacheConfig": { "type": "object", "properties": { "enabled": { "description": "Whether media cache is enabled or not", "type": "boolean" }, "limitPerRun": { "type": "integer" }, "maxFileSize": { "description": "Maximum size of a single cached media file in bytes", "type": "integer" }, "maxTotalSize": { "description": "Maximum total size of cached media in bytes", "type": "integer" }, "singleRun": { "type": "boolean" } } }, "PostsConfig": { "required": [ "max_characters", "max_media_attachments", "max_pins" ], "type": "object", "properties": { "default_markdown": { "description": "Whether posts are created in markdown format by default when not explicitly specified", "type": "boolean" }, "max_characters": { "description": "Maximum post size in characters", "type": "integer" }, "max_media_attachments": { "description": "Maximum number of attachments in post", "type": "integer" }, "max_pins": { "description": "Maximum number of pinned posts", "type": "integer" } } }, "RemoteLinkServiceConfig": { "type": "object", "properties": { "url": { "type": "object", "properties": { "scheme": { "type": "string" }, "fragment": { "type": "string" }, "authority": { "type": "string" }, "userInfo": { "type": "string" }, "host": { "type": "string" }, "port": { "type": "integer" }, "path": { "type": "string" }, "query": { "type": "string" }, "schemeSpecificPart": { "type": "string" }, "hash": { "type": "integer" }, "decodedUserInfo": { "type": "string" }, "decodedAuthority": { "type": "string" }, "decodedPath": { "type": "string" }, "decodedQuery": { "type": "string" }, "decodedFragment": { "type": "string" }, "decodedSchemeSpecificPart": { "type": "string" }, "string": { "type": "string" } } } } }, "SmsConfig": { "type": "object", "properties": { "countries": { "description": "List of supported countries", "type": "array", "items": { "type": "string" }, "example": "[US,CA]" }, "enabled": { "description": "Enable SMS service", "default": "false", "type": "boolean" }, "provider": { "description": "SMS service provider to use", "type": "string" } } }, "SmsConfigAwsSns": { "type": "object", "properties": { "accessKey": { "type": "string" }, "fromUS": { "type": "string" }, "region": { "type": "string" }, "secretKey": { "type": "string" }, "senderId": { "type": "string" } } }, "SmsConfigSinch": { "type": "object", "properties": { "accessKey": { "type": "string" }, "accessSecret": { "type": "string" }, "fromUS": { "type": "string" }, "projectId": { "type": "string" } } }, "SmsConfigTwilio": { "type": "object", "properties": { "accountSid": { "type": "string" }, "authToken": { "type": "string" }, "serviceSid": { "type": "string" } } }, "TranslationConfig": { "type": "object", "properties": { "enabled": { "description": "Whether translation is enabled on this server or not", "type": "boolean" } } }, "TranslationServiceConfig": { "type": "object", "properties": { "key": { "description": "Translation service key, depends on type", "type": "string" }, "service": { "description": "Translation service type", "enum": [ "none", "deepl" ], "type": "string" } } }, "ProviderConfig": { "type": "object", "properties": { "baseUrl": { "type": "object", "properties": { "scheme": { "type": "string" }, "fragment": { "type": "string" }, "authority": { "type": "string" }, "userInfo": { "type": "string" }, "host": { "type": "string" }, "port": { "type": "integer" }, "path": { "type": "string" }, "query": { "type": "string" }, "schemeSpecificPart": { "type": "string" }, "hash": { "type": "integer" }, "decodedUserInfo": { "type": "string" }, "decodedAuthority": { "type": "string" }, "decodedPath": { "type": "string" }, "decodedQuery": { "type": "string" }, "decodedFragment": { "type": "string" }, "decodedSchemeSpecificPart": { "type": "string" }, "string": { "type": "string" } } }, "cdn": { "type": "object", "properties": { "media": { "type": "string" }, "static": { "type": "string" } } }, "domain": { "type": "string" }, "local": { "type": "object", "properties": { "basePath": { "type": "string" } } }, "localBasePath": { "type": "object" }, "provider": { "type": "object" }, "s3": { "type": "object", "properties": { "accessKey": { "type": "string" }, "buckets": { "type": "object", "properties": { "media": { "type": "string" }, "static": { "type": "string" } } }, "endpoint": { "type": "string" }, "presignedUrlExpiration": { "type": "integer" }, "region": { "type": "string" }, "s3Region": { "type": "object", "properties": { "isGlobalRegion": { "type": "boolean" }, "id": { "type": "string" } } }, "secretKey": { "type": "string" } } }, "scheme": { "enum": [ "http", "https" ], "type": "string" }, "uploadsBasePath": { "type": "object" } } }, "UsernameReleaseConfig": { "type": "object", "properties": { "enabled": { "description": "Whether username release is enabled", "type": "boolean" }, "releasePeriodDays": { "description": "Days after which deleted local users are completely purged, releasing their usernames", "type": "integer" } } }, "VideoPolicy": { "type": "object", "properties": { "extensions": { "description": "Allowed video file extensions", "type": "array", "items": { "description": "File extension", "type": "string", "example": "mp4" } }, "keepOriginal": { "description": "Whether to keep the original video file", "type": "boolean" }, "maxDuration": { "description": "Maximum allowed video duration in seconds", "type": "integer" }, "maxMatrix": { "description": "Maximum allowed video matrix resolution (width * height)", "type": "integer" }, "maxResolution": { "description": "Maximum allowed video resolution in pixels at the longest side", "type": "integer" }, "maxSize": { "description": "Maximum allowed video file size in bytes", "type": "integer" }, "resolutions": { "description": "List of resolutions to convert the video to", "type": "array", "items": { "type": "integer" } }, "streamingThreshold": { "description": "Threshold in seconds to convert video to m3u8", "type": "integer" } } }, "PlatformSettings": { "type": "object", "properties": { "wellesley.access": { "$ref": "#/components/schemas/InstanceAccess" }, "wellesley.admin.ai.agents.budgets": { "$ref": "#/components/schemas/AIAgentBudgetLimits" }, "wellesley.uploads.policy.audio": { "$ref": "#/components/schemas/AudioPolicy" }, "wellesley.branding": { "$ref": "#/components/schemas/InstanceBranding" }, "wellesley.admin.captcha": { "$ref": "#/components/schemas/CaptchaConfig" }, "wellesley.captcha": { "$ref": "#/components/schemas/CaptchaClientConfig" }, "wellesley.confirmationCode": { "$ref": "#/components/schemas/ConfirmationCodeConfigs" }, "wellesley.uploads.policy.doc": { "$ref": "#/components/schemas/DocPolicy" }, "wellesley.instance.domainBlocks": { "$ref": "#/components/schemas/InstanceDomainBlocksPolicy" }, "wellesley.admin.embedding_model": { "$ref": "#/components/schemas/EmbeddingModelConfig" }, "wellesley.uploads.policy.emoji": { "$ref": "#/components/schemas/EmojiPolicyConfig" }, "wellesley.admin.fasp_remote": { "$ref": "#/components/schemas/FaspRemoteAdminConfig" }, "wellesley.admin.federation.mode": { "$ref": "#/components/schemas/FederationModeConfig" }, "wellesley.uploads.policy.image": { "$ref": "#/components/schemas/ImagePolicy" }, "wellesley.instance.admin": { "$ref": "#/components/schemas/InstanceAdmin" }, "wellesley.instance.contacts": { "$ref": "#/components/schemas/InstanceContacts" }, "wellesley.instance.legal": { "$ref": "#/components/schemas/InstanceLegal" }, "wellesley.admin.language": { "$ref": "#/components/schemas/LanguageDetectionConfig" }, "wellesley.admin.mediacache": { "$ref": "#/components/schemas/MediaCacheConfig" }, "wellesley.posts": { "$ref": "#/components/schemas/PostsConfig" }, "wellesley.registration": { "$ref": "#/components/schemas/InstanceRegistration" }, "wellesley.admin.link_service": { "$ref": "#/components/schemas/RemoteLinkServiceConfig" }, "wellesley.admin.sms": { "$ref": "#/components/schemas/SmsConfig" }, "wellesley.admin.sms.aws": { "$ref": "#/components/schemas/SmsConfigAwsSns" }, "wellesley.admin.sms.sinch": { "$ref": "#/components/schemas/SmsConfigSinch" }, "wellesley.admin.sms.twilio": { "$ref": "#/components/schemas/SmsConfigTwilio" }, "wellesley.translation": { "$ref": "#/components/schemas/TranslationConfig" }, "wellesley.admin.translation": { "$ref": "#/components/schemas/TranslationServiceConfig" }, "wellesley.admin.uploads": { "$ref": "#/components/schemas/ProviderConfig" }, "wellesley.username.release": { "$ref": "#/components/schemas/UsernameReleaseConfig" }, "wellesley.uploads.policy.video": { "$ref": "#/components/schemas/VideoPolicy" } } }, "UserDiscoverFeedConfig": { "type": "object", "properties": { "filter": { "enum": [ "ALL", "LOCAL", "REMOTE" ], "type": "string" } } }, "FollowConfig": { "type": "object", "properties": { "autoAccept": { "type": "boolean" } } }, "NotificationPolicy": { "type": "object", "properties": { "blockNewAccounts": { "type": "boolean" }, "blockNonFollowers": { "type": "boolean" }, "blockNonFollowing": { "type": "boolean" }, "blockNonFollowingMessages": { "type": "boolean" } } }, "NotificationPrefs": { "type": "object", "properties": { "email": { "type": "object", "properties": { "comment": { "type": "boolean" }, "eventCancel": { "type": "boolean" }, "eventInvite": { "type": "boolean" }, "eventJoin": { "type": "boolean" }, "eventUpdate": { "type": "boolean" }, "follow": { "type": "boolean" }, "followRequest": { "type": "boolean" }, "groupChannelPostCreate": { "type": "boolean" }, "groupInvite": { "type": "boolean" }, "like": { "type": "boolean" }, "listPostCreate": { "type": "boolean" }, "mention": { "type": "boolean" }, "mute": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "expiresAt": { "format": "date-time", "type": "string" } } }, "pollVote": { "type": "boolean" }, "postUpdate": { "type": "boolean" }, "postVote": { "type": "boolean" }, "repost": { "type": "boolean" } } }, "push": { "type": "object", "properties": { "comment": { "type": "boolean" }, "eventCancel": { "type": "boolean" }, "eventInvite": { "type": "boolean" }, "eventJoin": { "type": "boolean" }, "eventUpdate": { "type": "boolean" }, "follow": { "type": "boolean" }, "followRequest": { "type": "boolean" }, "groupChannelPostCreate": { "type": "boolean" }, "groupInvite": { "type": "boolean" }, "like": { "type": "boolean" }, "listPostCreate": { "type": "boolean" }, "mention": { "type": "boolean" }, "mute": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "expiresAt": { "format": "date-time", "type": "string" } } }, "pollVote": { "type": "boolean" }, "postUpdate": { "type": "boolean" }, "postVote": { "type": "boolean" }, "repost": { "type": "boolean" } } }, "subscribeOnComment": { "type": "boolean" }, "syncAcrossProfiles": { "type": "boolean" } } }, "PrivacyConfig": { "type": "object", "properties": { "discoverable": { "type": "boolean" }, "showFollowers": { "type": "boolean" }, "showGroups": { "type": "boolean" }, "showProfilePage": { "type": "boolean" }, "showPublicPosts": { "type": "boolean" } } }, "QuotePolicy": { "type": "object", "properties": { "canQuote": { "enum": [ "PUBLIC", "FOLLOWERS", "NOBODY" ], "type": "string" } } }, "UserTranslationConfig": { "type": "object", "properties": { "excludedLanguages": { "description": "List of languages not offered for translation", "type": "array", "items": { "type": "string" }, "example": "[\"DE\"]" }, "filter": { "description": "Filter posts to show only in those languages", "type": "array", "items": { "type": "string" }, "example": "[\"EN\", \"FR\"]" }, "preferredLanguage": { "description": "Language to translate posts to", "type": "string", "example": "EN" }, "primaryLanguage": { "description": "Language to use in UI", "type": "string", "example": "EN" } } }, "UserSettings": { "type": "object", "properties": { "user.discoverFeed": { "$ref": "#/components/schemas/UserDiscoverFeedConfig" }, "user.follow": { "$ref": "#/components/schemas/FollowConfig" }, "user.notifications.policy": { "$ref": "#/components/schemas/NotificationPolicy" }, "user.notifications.prefs": { "$ref": "#/components/schemas/NotificationPrefs" }, "user.privacy": { "$ref": "#/components/schemas/PrivacyConfig" }, "user.quotePolicy": { "$ref": "#/components/schemas/QuotePolicy" }, "user.translation": { "$ref": "#/components/schemas/UserTranslationConfig" } } }, "GroupJoinQuestions": { "type": "object", "properties": { "show": { "type": "boolean" } } }, "MembershipConfig": { "type": "object", "properties": { "allowMemberInvites": { "type": "boolean" }, "approveInvites": { "type": "boolean" }, "maxMembers": { "type": "integer" } } }, "ModerationConfig": { "type": "object", "properties": { "blockedWords": { "type": "array", "items": { "type": "string" } }, "dailyPostLimit": { "type": "integer" }, "moderateLinks": { "type": "boolean" }, "moderatePosts": { "type": "boolean" }, "slowModeEnabled": { "type": "boolean" }, "slowModeInterval": { "type": "integer" }, "spamFilter": { "type": "boolean" } } }, "GroupPrivacyConfig": { "type": "object", "properties": { "showMemberList": { "type": "boolean" }, "showStats": { "type": "boolean" } } }, "GroupSettings": { "type": "object", "properties": { "group.ai.agents.budgets": { "$ref": "#/components/schemas/AIAgentBudgetLimits" }, "group.join.questions": { "$ref": "#/components/schemas/GroupJoinQuestions" }, "group.membership": { "$ref": "#/components/schemas/MembershipConfig" }, "group.moderation": { "$ref": "#/components/schemas/ModerationConfig" }, "group.privacy": { "$ref": "#/components/schemas/GroupPrivacyConfig" } } }, "MemberDisplaySettings": { "type": "object", "properties": { "customDisplayName": { "type": "string" }, "showActivity": { "type": "boolean" }, "showInMemberList": { "type": "boolean" }, "showJoinDate": { "type": "boolean" } } }, "MemberPreferences": { "type": "object", "properties": { "emailNotifications": { "type": "boolean" }, "notificationFrequency": { "type": "string" }, "notifications": { "type": "boolean" } } }, "GroupMemberSettings": { "type": "object", "properties": { "group.member.display": { "$ref": "#/components/schemas/MemberDisplaySettings" }, "group.member.preferences": { "$ref": "#/components/schemas/MemberPreferences" } } }, "RootPageData": { "description": "Root page data", "type": "object" }, "UserPageData": { "description": "User profile page data", "type": "object", "properties": { "noindex": { "type": "boolean" }, "user": { "$ref": "#/components/schemas/UserFull" } } }, "UserEventPageData": { "description": "User event page data", "type": "object", "properties": { "event": { "$ref": "#/components/schemas/Event" }, "noindex": { "type": "boolean" }, "user": { "$ref": "#/components/schemas/UserFull" } } }, "UserPostPageData": { "description": "User post page data", "type": "object", "properties": { "noindex": { "type": "boolean" }, "post": { "$ref": "#/components/schemas/Post" }, "user": { "$ref": "#/components/schemas/UserFull" } } }, "AboutPageData": { "description": "About page data", "type": "object", "properties": { "brandingSettings": { "type": "object" } } }, "FeedPageData": { "description": "Main feed data", "type": "object", "properties": { "feed": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } } } }, "FeedDiscoverPageData": { "description": "Discover feed data", "type": "object", "properties": { "feed": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } } } }, "FeedFollowingPageData": { "description": "Following feed data", "type": "object", "properties": { "feed": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } } } }, "GroupPageData": { "description": "Group page data", "type": "object", "properties": { "currentUserGroupPermissions": { "type": "object" }, "group": { "$ref": "#/components/schemas/Group" }, "groupApps": { "type": "array", "items": { "$ref": "#/components/schemas/Application" } } } }, "GroupChannelPageData": { "description": "Group channel page data", "type": "object", "properties": { "channel": { "$ref": "#/components/schemas/UserView" }, "currentUserGroupPermissions": { "type": "object" }, "group": { "$ref": "#/components/schemas/Group" }, "groupApps": { "type": "array", "items": { "$ref": "#/components/schemas/Application" } } } }, "GroupChannelPostPageData": { "description": "Group channel post page data", "type": "object", "properties": { "channel": { "$ref": "#/components/schemas/UserView" }, "currentUserGroupPermissions": { "type": "object" }, "group": { "$ref": "#/components/schemas/Group" }, "groupApps": { "type": "array", "items": { "$ref": "#/components/schemas/Application" } }, "post": { "$ref": "#/components/schemas/Post" } } }, "GroupBotPageData": { "description": "Group bot page data", "type": "object", "properties": { "group": { "$ref": "#/components/schemas/Group" }, "user": { "$ref": "#/components/schemas/UserFull" } } }, "GroupEventPageData": { "description": "Group event page data", "type": "object", "properties": { "currentUserGroupPermissions": { "type": "object" }, "event": { "$ref": "#/components/schemas/Event" }, "group": { "$ref": "#/components/schemas/Group" }, "groupApps": { "type": "array", "items": { "$ref": "#/components/schemas/Application" } } } }, "PrivacyPageData": { "description": "Privacy policy page data", "type": "object", "properties": { "legalSettings": { "type": "object" } } }, "TermsPageData": { "description": "Terms of use page data", "type": "object", "properties": { "legalSettings": { "type": "object" } } }, "RbacResource": { "description": "Available RBAC resource types", "enum": [ "AIAgents", "AIModels", "AIProviders", "AdminSettings", "AppData", "Apps", "Audit", "Data", "Emojis", "Federation", "Group", "GroupAIAgents", "GroupAIModels", "GroupAIProviders", "GroupApps", "GroupChannels", "GroupData", "GroupMembers", "GroupQuestions", "GroupReports", "GroupRoles", "GroupSettings", "Integrations", "Jobs", "Reports", "Roles", "Rules", "Signups", "Uploads", "Users" ], "type": "string" }, "RbacAction": { "description": "Available RBAC action types", "enum": [ "Delete", "Impersonate", "Invite", "Manage", "Moderate", "Post", "PostAsChannel", "PostsRead", "Read", "UpdateStats" ], "type": "string" }, "ApiError": { "required": [ "errorCode", "message" ], "type": "object", "properties": { "errorCode": { "description": "Error code", "type": "string" }, "message": { "description": "Error message", "type": "string" }, "docUrl": { "description": "Link to documentation", "type": "string" } } }, "Duration": { "format": "double", "description": "Duration in seconds", "type": "number", "example": "3600" } }, "securitySchemes": { "header": { "type": "apiKey", "description": "Authentication token", "name": "Authorization", "in": "header" } } }, "openapi": "3.0.4", "tags": [ { "name": "AI Agents", "description": "The AI Agents API manages bot creation and configuration.\n Each bot is a user profile of type Service with a configuration profile that includes tools, triggers,\n and scope. Global bots operate in the global scope; group bots operate within a group scope." }, { "name": "AI Models", "description": "Endpoints for searching AI models and managing per-scope enablement. Models are catalog entries synced from models.dev. Use scope parameter with enable/disable endpoints to manage models per-scope." }, { "name": "AI Providers", "description": "Endpoints for viewing AI providers and configuring per-scope API keys. Providers are catalog entries synced from models.dev. Use scope='global' for platform-wide configuration (requires AIProviders permissions) or a group TypeId for group-specific configuration (requires GroupAIProviders permissions)." }, { "name": "Accounts", "description": "Account management and authentication endpoints. Handles user registration, login flows (email/phone), profile management, and account lifecycle operations. Supports multi-step signup with email/SMS verification, CAPTCHA, and optional admin approval." }, { "name": "Addresses", "description": "Endpoints for suggesting and validating physical addresses" }, { "name": "Admin Accounts", "description": "Administrative endpoints for account and user management. Provides comprehensive tools for managing user accounts, including creation, deletion, role assignment, password management, state changes, and user impersonation for bot accounts. Requires Users.Manage permission unless otherwise noted on individual endpoints." }, { "name": "Admin ActivityPub", "description": "Administrative endpoints for managing ActivityPub federation delivery. Provides tools to clear delivery error counters and restart delivery for specific remote domains. Requires Federation.Manage permission." }, { "name": "Admin Audit", "description": "Administrative endpoints for viewing and searching audit logs. Provides comprehensive logging of all security-relevant actions performed in the system, including account management, user changes, settings modifications, and moderation actions. Requires Audit.Read permission." }, { "name": "Admin Domain Blocks", "description": "Administrative APIs for managing domain blocks. Provides endpoints to block specific domains with different severity levels (SUSPEND, LIMIT, NOOP), update existing blocks, unblock domains, and list currently blocked domains. Domain blocks prevent or limit federation with specified domains. Write operations require Federation.Manage permission; read operations require Federation.Read or Federation.Manage permission." }, { "name": "Admin Domains Allow List", "description": "Administrative endpoints for managing domain allowlists. When domain allowlisting is enabled, only domains in this list can federate with the instance. Write operations require Federation.Manage permission; read operations require Federation.Read or Federation.Manage permission." }, { "name": "Admin Email Allow List", "description": "Administrative endpoints for managing the email domain allowlist used during user registration. When enabled, only email addresses from allowed domains can sign up. Write operations require AdminSettings.Manage permission; read operations require AdminSettings.Read or AdminSettings.Manage permission." }, { "name": "Admin Email Blocks", "description": "Administrative APIs for managing email blocks to prevent unwanted signups. Supports blocking specific email addresses and entire domains. Email blocks are automatically normalized and checked during user registration. Requires Users.Moderate permission." }, { "name": "Admin FASP", "description": "Administrative endpoints for managing FASP (Fediverse Auxiliary Service Provider) provider registrations and default capability assignments. Allows accepting, declining, and blocking providers, as well as configuring which provider is the default for each capability. Read operations require Federation.Read or Federation.Manage permission; write operations require Federation.Manage permission." }, { "name": "Admin FASP Remote", "description": "Administrative endpoints for managing a remote FASP server. Allows Wellesley admins to configure connection to a FASP server and manage Fediverse server registrations remotely." }, { "name": "Admin Federation Config", "description": "Administrative endpoints for managing federation mode and allowlist in a single operation." }, { "name": "Admin Federation Metrics", "description": "Administrative endpoints for monitoring and managing federation with other ActivityPub instances. Provides metrics on connected domains, user counts, post statistics, and federation health monitoring including sliding window performance metrics for inbox processing. Requires Federation.Read or Federation.Manage permission." }, { "name": "Admin Federation Mode", "description": "Manage the federation mode of the instance (OPEN, LIMITED, CLOSED)" }, { "name": "Admin Feeds", "description": "Administrative endpoints for managing user feed caches. Provides tools for regenerating, clearing, and diagnosing cached home feeds stored in Redis. Feed regeneration recomputes the feed from the database and updates the cache. Requires Jobs.Manage permission." }, { "name": "Admin Groups", "description": "Administrative endpoints for managing groups, channels, and events. Provides search and listing capabilities for all groups on the server regardless of privacy or visibility. Requires Users.Read or Users.Manage permission." }, { "name": "Admin Jobs", "description": "Administrative endpoints for monitoring and managing background job queues. Provides statistics, job listings, and queue monitoring for all asynchronous tasks such as federation delivery, media processing, and cleanup jobs. Requires Jobs.Read or Jobs.Manage permission." }, { "name": "Admin Posts", "description": "Administrative endpoints for managing posts. Provides moderation capabilities to delete posts that violate community guidelines or are part of reported content. Requires Reports.Manage permission." }, { "name": "Admin Remote Link Service", "description": "Administrative endpoints for configuring a remote link preview service provider. This service fetches rich link previews (title, description, image) for URLs shared in posts. The provider must support the 'link_preview' FASP capability. Requires AdminSettings.Manage permission." }, { "name": "Admin Signup Requests", "description": "Administrative endpoints for managing user signup requests. Provides tools for reviewing, approving, rejecting, and managing signup requests in the moderation queue. Supports workflow for manual account approval when enabled. Read operations require Signups.Read or Signups.Manage permission; write operations require Signups.Manage permission." }, { "name": "Admin Uploads", "description": "Administrative endpoints for managing file uploads and media storage. Provides tools for monitoring user storage usage, searching uploaded files, and managing upload processing jobs. Supports queue management for async upload processing workflows. Requires Uploads.Read permission." }, { "name": "Aliases", "description": "User alias management for account migration and identity linking. Aliases allow a user to declare previous identities on remote federated servers, which is required for ActivityPub account migration. All endpoints require authentication." }, { "name": "Application Data", "description": "Endpoints for managing application-specific data storage. Provides a flexible key-value storage system for applications to store custom data associated with users, groups, or the platform. Supports tagging, filtering, and ownership-based access control." }, { "name": "Applications", "description": "Endpoints for serving and routing platform applications to users" }, { "name": "Async Refreshes", "description": "Endpoints for polling the status of asynchronous background operations such as home feed regeneration and federated search" }, { "name": "Blocks", "description": "User blocking functionality for preventing interaction with specific users. Blocking a user prevents them from following you, seeing your posts, or interacting with your content. Block operations are federated to remote servers when blocking remote users." }, { "name": "Compatibility", "description": "Version-agnostic API compatibility endpoints" }, { "name": "Domain Blocks", "description": "Public API for listing domains blocked by this instance. Visibility and reason details are controlled by platform settings." }, { "name": "Domain-blocks", "description": "Manage user-level domain blocks to filter content from specific federated servers. All endpoints require authentication. Domain blocks hide posts and notifications from the blocked domain and remove followers from it." }, { "name": "Drafts", "description": "Endpoints for personal auto-saved drafts" }, { "name": "Email", "description": "Email address management for user accounts. Provides secure email change workflow with verification codes, password confirmation, and notification system. All email changes require authentication and are logged for security." }, { "name": "Embeddings Admin", "description": "Administrative endpoints for managing vector embeddings used in AI-powered features such as semantic search and content recommendations. Provides tools for enabling/disabling embeddings, configuring the embedding model, estimating costs, and managing batch recalculation jobs. Requires AdminSettings.Manage permission." }, { "name": "Emoji", "description": "Custom emoji management system for the platform. Supports creating, uploading, importing/exporting, searching, and deleting custom emojis. Emojis are automatically resized and optimized. Admin-only operations require Emojis.Manage permission." }, { "name": "Events", "description": "Endpoints for creating, retrieving, and managing events and attendees" }, { "name": "FASP", "description": "Administration endpoints for managing FASP (Fediverse Auxiliary Service Provider) registrations and capabilities. Handles the FASP registration workflow: providers register via POST, admins confirm registration, and capabilities are activated or deactivated. Also provides debug and backfill request tools. The registration endpoint is publicly accessible; all other endpoints require the Federation.Manage RBAC permission." }, { "name": "FASP Data Sharing", "description": "FASP (Fediverse Auxiliary Service Provider) data sharing endpoints implementing the FASP data sharing protocol v0. Allows FASP providers to subscribe to content lifecycle events and trends, request backfills of historical data, and manage their subscriptions. All requests are authenticated using FASP Ed25519 HTTP signature verification, not user authentication. Not intended to be called directly by client applications." }, { "name": "FASP Debug", "description": "Debug endpoints for FASP (Fediverse Auxiliary Service Provider) integration testing. Allows FASP providers to submit debug callback responses and administrators to view and manage callback logs. The POST endpoint uses FASP Ed25519 HTTP signature authentication; the GET and DELETE endpoints are currently unauthenticated and intended for admin use only." }, { "name": "Federation", "description": "Server-to-server endpoints for federated group access. Remote servers request tokens on behalf of their users by signing requests with the user's private key via HTTP Signatures. No standard authentication is required; requests are validated through cryptographic signatures." }, { "name": "Follow", "description": "User follow relationship management. Handles following/unfollowing users, managing follow requests, and querying follower/followee relationships. Supports both local and remote (federated) users with ActivityPub protocol integration." }, { "name": "Geo", "description": "Endpoints for geographic location lookup and timezone services" }, { "name": "Group Applications", "description": "Endpoints for managing applications available to groups. Applications are installable modules that extend group functionality. Group admins can add or remove applications from their groups. The global apps list shows all available applications at the GROUP entry point, while per-group lists show only applications installed for that specific group. Management operations require the GroupApps.Manage RBAC permission." }, { "name": "Group Blocks", "description": "Manage group-level user blocks" }, { "name": "Group Channels", "description": "API endpoints for managing channels within groups. Channels are specialized accounts that enable organized content distribution within groups. They support hierarchical organization with primary and auto-subscribe channels, privacy controls inherited from parent groups, and both scoped (group-specific) and global usernames for discovery. Group admins manage channels while members follow." }, { "name": "Group Invitations", "description": "API endpoints for managing group invitations. Group owners and admins can invite users to join their groups. Invitees can accept or reject invitations. Creating invitations requires the GroupMembers.Invite RBAC permission. Accepting, rejecting, and viewing personal invitations require standard authentication." }, { "name": "Group Join", "description": "API endpoints for group join workflows. Users can request to join a group, and group admins can approve or reject join requests. Join behavior depends on the group's join mode: OPEN (instant), APPROVAL (requires admin approval), or INVITE_ONLY (requires invitation). Groups may also have entry questions that must be answered before joining. Admin operations (listing, approving, rejecting requests) require the GroupMembers.Manage RBAC permission. All endpoints require authentication." }, { "name": "Group Member Settings", "description": "Endpoints for managing member-specific settings within groups. These settings are personal to each group member and affect their individual experience within the group. Members can only access and modify their own settings within groups they belong to." }, { "name": "Group Members", "description": "API endpoints for managing group membership. Provides functionality to add, update, and remove members from groups, as well as retrieve membership information. Supports both local and federated groups through ActivityPub protocol. Access control is enforced based on group privacy settings and user permissions." }, { "name": "Group Pins", "description": "API endpoints for managing pinned groups. Users can pin groups they are a member of to keep them easily accessible. Pinned groups support custom ordering via pin numbers and appear first in the user's group list. All endpoints require authentication." }, { "name": "Group Questions", "description": "API endpoints for managing group entry questions. Groups can require prospective members to answer questions before joining. Questions support multiple types (text, single choice, multiple choice) and are used to screen members when the group's join mode is set to QUESTIONS. Answers are validated and generate a token that can be used during the join process." }, { "name": "Group Rules", "description": "API endpoints for managing community rules within groups. Rules define the expected conduct and content policies that members must follow. Each rule consists of text (the rule itself), a hint (explanation or context), and an ordering value for display sequence. Rules are scoped to specific groups and can be managed by users with appropriate permissions." }, { "name": "Group Settings", "description": "Endpoints for managing group-specific settings and configuration options. These endpoints allow authorized group members to view, update, and delete settings that control group behavior, features, and customization options." }, { "name": "Groups", "description": "API endpoints for managing groups within the Wellesley platform. Groups are community spaces that can be public or private, support forums, and have their own membership and permission systems. Groups can be federated via ActivityPub for cross-instance communication." }, { "name": "Import", "description": "Endpoints for importing data from other platforms including followers, blocks, and mutes" }, { "name": "Instance", "description": "Server instance information and configuration. Provides metadata about the server, compatible domains, supported languages, timezones, and countries. All endpoints are publicly accessible without authentication." }, { "name": "Link Preview", "description": "Link preview generation service for extracting and caching URL metadata. Provides rich preview cards with title, description, image, and other metadata for embedding in posts and messages. Supports OpenGraph and Twitter Card protocols." }, { "name": "Lists", "description": "User list management for organizing and grouping followed accounts. Lists allow users to curate collections of accounts for easier content consumption. Lists can be public or private. Only the list owner can modify their lists. All endpoints require authentication." }, { "name": "Logins", "description": "Login method management for authenticated accounts. Allows adding or removing email/password and phone number as authentication methods. Adding a login method requires email or SMS verification. Removing a method is blocked if it is the last remaining login identifier. All changes are audited. All endpoints require authentication." }, { "name": "Markdown", "description": "Markdown-to-HTML rendering service for post and article previews. Supports autolinking of hashtags, @mentions, and custom emoji. Requires authentication." }, { "name": "Metrics", "description": "Endpoints for retrieving metrics and analytics data from the events stream" }, { "name": "Mutes", "description": "User muting functionality for hiding content from specific users without blocking them. Muting a user hides their posts from your timelines and notifications, but does not prevent them from following you or interacting with your content. Mutes can be temporary (with an expiration duration) or permanent. All endpoints require authentication." }, { "name": "Names", "description": "Unified API for validating name availability. Supports checking user/channel usernames and group names. Returns whether a name is reserved or already in use." }, { "name": "Notes", "description": "Manage personal notes about other users. Notes are private and only visible to the user who created them. All endpoints require authentication. Users cannot create notes about themselves." }, { "name": "Notifications", "description": "User notification management for retrieving, counting, and updating notification status. Notifications are generated by user interactions such as follows, mentions, reposts, and likes. Supports filtering by notification type and status (read/unread). All endpoints require authentication." }, { "name": "Passkeys", "description": "Passkey (WebAuthn) registration and authentication" }, { "name": "Password", "description": "Password management endpoints for changing and recovering account passwords. Supports two flows: authenticated password change (requires current password and email confirmation) and unauthenticated password recovery (sends reset code to account email). All password changes invalidate other active sessions for security." }, { "name": "Phone", "description": "Phone number change management for authenticated users. Implements a secure 4-step phone change flow: (1) request change and receive SMS code on current phone, (2) verify current phone ownership, (3) submit new phone number and receive SMS code, (4) verify new phone number. All endpoints require authentication." }, { "name": "Pins", "description": "Endpoints for managing `Pins` (top-level posts) and `Highlights` (pinned replies). Top-level pins are shown first in the profile scope and are limited by admin setting `Maximum number of pinned posts`. Replies can be pinned as highlights under their root post. Pin and unpin actions are federated via ActivityPub." }, { "name": "Platform Data", "description": "Endpoints for managing platform-wide and group-specific data storage. Unlike application data, this provides direct data management not tied to specific applications. Supports flexible ownership models including platform-level, group-level, and user-level data with appropriate access controls." }, { "name": "Platform Settings", "description": "Endpoints for managing platform-wide settings and configuration options. These endpoints control server-level settings that affect the entire platform, including features, limits, security policies, and default behaviors for all users and groups." }, { "name": "Polls", "description": "Endpoints for interacting with polls attached to posts, including voting and refreshing results from federated instances. Requires authentication. Polls are created as part of a post via the Posts API." }, { "name": "Posts", "description": "Endpoints for creating, reading, updating, and deleting posts, as well as managing comments, likes, bookmarks, reposts, subscriptions, and votes. Most endpoints require authentication; read-only feed and post endpoints are accessible to guests via @PermitAll. Post mutations are federated via ActivityPub." }, { "name": "RBAC", "description": "\n Endpoints for retrieving Role-Based Access Control (RBAC) configurations and managing roles,\n resources, permissions and role-to-user assignments.\n Scoped Role Definition (`RBACRole`):\n - Represents roles within the RBAC system.\n - Each role has a unique `roleId`, a `name`, an optional `description`, and a `scope`.\n - The `scope` defines the domain or area in which the role is valid.\n - The `scope` can be Global (hardcoded), currently the only one is \"global\"\n - The `scope` also can be dynamic, currently we use Group Ids, like \"gr_05hxcvk1hjexere4pvtrj0hggt\"\n - Roles come with assigned permissions (`RBACPermissions`) that define what actions the role can perform on system resources.\n - Metadata such as `createdAt` and `updatedAt` timestamps track the role's lifecycle events.\n\n Permissions (`RBACPermissions`):\n - Encapsulates resource-specific access controls.\n - Each permission object specifies the `resource` (e.g., \"user\", \"document\") and an associated list of allowed `RBACAccess` types.\n - `RBACAccess` enumerates the supported actions: `Read`, `Add`, `Modify`, `Delete`.\n\n Role Assignments to Actors (`RBACActorRole`):\n - Maps actors (e.g., users, services) to specific roles.\n - Tracks the association through `actorId` (representing the unique entity being assigned) and `roleId` (specific role ID).\n - Includes timestamps to record when the assignment was created or updated.\n " }, { "name": "Remote collections", "description": "API to retrieve followers and following collections for remote (federated) users. Fetches collection data from remote ActivityPub servers, resolves actor URIs to user profiles, and returns them in the local user format. Supports pagination via offset/limit parameters. All endpoints are publicly accessible (@PermitAll) and operate on remote users only -- local users are rejected." }, { "name": "Reports", "description": "Unified moderation endpoints for server and group reports. Pass scope= for group scope; omit scope for server scope." }, { "name": "Rules", "description": "Manage platform rules that govern user conduct and content policies. Retrieving rules is publicly accessible. Creating, updating, deleting, and reordering rules require authentication and the Rules.Manage RBAC permission. All write operations are logged in the audit trail." }, { "name": "Search", "description": "Endpoints for searching across users, posts, and tags with various filtering options" }, { "name": "Sessions", "description": "Authentication session management endpoints. Allows users to view active sessions across devices, revoke individual sessions or all other sessions, and permanently delete session records. Sessions are tracked in both the database and Redis for real-time state synchronization. All endpoints require authentication. The current session cannot be revoked or deleted." }, { "name": "SignupInviteLinks", "description": "Manage signup invite links for user registration. All endpoints require authentication. Invite links allow existing users to invite new members with configurable usage limits and expiration dates." }, { "name": "Suggestions", "description": "Personalized follow suggestions for the authenticated user based on FASP recommendations. Excludes users already followed or pending follow requests, and users blocked by either side." }, { "name": "Tags", "description": "Endpoints for managing hashtags, including following, featuring, and retrieving tag information" }, { "name": "Translation", "description": "Endpoints for translating text between languages" }, { "name": "Trends", "description": "Endpoints for retrieving trending content on the platform including trending tags, links, and posts. All endpoints are publicly accessible without authentication. Trend data is sourced from FASP (Federated Auxiliary Service Providers) where available." }, { "name": "Uploads", "description": "Endpoints for uploading, retrieving, and managing media files. The upload flow is two-step: first create an upload via POST to get an upload URL, then PUT the actual file content to that URL. Most endpoints require authentication. Class-level @RBACAuthorize requires authentication by default; public endpoints use @PermitAll." }, { "name": "User Devices", "description": "Manage user device registrations for Web Push notifications. Allows registering, listing, and removing push notification subscriptions. All endpoints except VAPID public key retrieval require authentication." }, { "name": "User Settings", "description": "Endpoints for managing user-specific settings and preferences. These endpoints allow authenticated users to view, update, and delete their personal settings that control their account behavior, interface preferences, privacy options, and feature customizations." }, { "name": "Users", "description": "User profile management endpoints. Handles user creation, retrieval by ID or username, profile updates, deletion, and social graph queries (followers/following). Supports both authenticated and guest access with varying levels of detail. Guest users receive basic profile data; authenticated users can access relationship statuses and full profiles." } ], "paths": { "/api/meta/compat": { "get": { "summary": "Get API compatibility information", "description": "\n Returns API compatibility information including the current breaking generation\n and minimum supported generation. This endpoint is version-agnostic (not under /api/v1),\n unauthenticated, and always available.\n\n Clients should embed COMPILED_BREAKING_GENERATION at build time and use this endpoint\n to determine compatibility:\n - If client_generation < min_supported_generation: block usage and force update\n - If client_generation < breaking_generation: optional update warning\n - Otherwise: proceed normally\n\n This endpoint must remain backward-compatible indefinitely.\n ", "tags": [ "Compatibility" ], "responses": { "200": { "description": "API compatibility information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatResponse" } } } } }, "security": [] } }, "/api/v1/accounts/add-reason": { "post": { "summary": "Signup - Step 4: Submit signup reason", "description": "Step 4 of signup (if required): collects reason for joining the platform. Used for manual approval workflows. Notifies admins of pending registration. Required when registration mode is set to approval-based.", "tags": [ "Accounts" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignupReasonParams" } } }, "required": true }, "responses": { "200": { "description": "Registration hash and next step", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistrationResponse" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "RegistrationWrongState", "message": "Wrong state" } } }, "description": "Wrong state" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AccountNotFound", "message": "Account not found" } } }, "description": "Account not found" } }, "security": [] } }, "/api/v1/accounts/authenticate/email": { "post": { "summary": "Email/username authentication", "description": "Authenticates using email address or username with password. Returns a session token for authenticated requests. The system automatically detects whether the login field is an email (contains @) or username. Updates last sign-in timestamp on successful authentication.", "tags": [ "Accounts" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthRequest" } } }, "required": true }, "responses": { "200": { "description": "Account, all account users and session key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Token" } } } }, "400": { "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "UserMissingCreds": { "description": "No credentials provided", "value": { "errorCode": "UserMissingCreds", "message": "No credentials provided" } }, "UserBadCreds": { "description": "Invalid user credentials provided", "value": { "errorCode": "UserBadCreds", "message": "Invalid user credentials provided" } } } } }, "description": "Unauthorized" }, "500": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserError", "message": "An unexpected user-related error" } } }, "description": "An unexpected user-related error" } }, "security": [] } }, "/api/v1/accounts/authenticate/phone": { "post": { "summary": "Phone number authentication", "description": "Two-step phone authentication process. First call sends SMS code to the phone number. Second call with the code completes authentication and returns session token. Phone number must be registered to an existing account.", "tags": [ "Accounts" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthPhoneRequest" } } }, "required": true }, "responses": { "200": { "description": "Session key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Token" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "VerificationCodeError": { "description": "Incorrect verification code", "value": { "errorCode": "VerificationCodeError", "message": "Incorrect verification code" } }, "VerificationCodeTooMany": { "description": "Too many attempts", "value": { "errorCode": "VerificationCodeTooMany", "message": "Too many attempts" } }, "SendSMSError": { "description": "Failed to send sms", "value": { "errorCode": "SendSMSError", "message": "Failed to send sms" } }, "InvalidPhoneNumber": { "description": "The provided phone number is invalid", "value": { "errorCode": "InvalidPhoneNumber", "message": "The provided phone number is invalid" } }, "SMSServiceDisabled": { "description": "SMS service is not enabled", "value": { "errorCode": "SMSServiceDisabled", "message": "SMS service is not enabled" } }, "SMSUnsupportedCountry": { "description": "SMS service is not available in this country", "value": { "errorCode": "SMSUnsupportedCountry", "message": "SMS service is not available in this country" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserMissingCreds", "message": "No credentials provided" } } }, "description": "No credentials provided" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AccountNotFound", "message": "Account not found" } } }, "description": "Account not found" } }, "security": [] } }, "/api/v1/accounts/change/name": { "put": { "summary": "Change user display name", "description": "Updates the display name for a specific user in the account. Can only change names for users belonging to the authenticated account. Specify user by either username or user ID. Changes are immediately reflected and streamed to connected clients.", "tags": [ "Accounts" ], "parameters": [ { "description": "id", "required": false, "name": "id", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "name", "required": true, "name": "name", "in": "query", "schema": { "type": "string" } }, { "description": "username", "required": false, "name": "username", "in": "query", "schema": { "type": "string", "nullable": true } }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountWithUser" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserIdOrUserNameMissing", "message": "The userId or userName must be provided" } } }, "description": "The userId or userName must be provided" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "CantChangeNameOtherUser", "message": "Cannot change the name of another user" } } }, "description": "Cannot change the name of another user" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserNotFound", "message": "User not found" } } }, "description": "User not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/accounts/check-captcha": { "post": { "summary": "Verify CAPTCHA challenge", "description": "Step 3 of signup (if enabled): validates CAPTCHA to prevent automated signups. Uses IP address for additional validation. Advances to next step on success. Skip if CAPTCHA is disabled in config.", "tags": [ "Accounts" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaptchaVerificationParams" } } }, "required": true }, "responses": { "200": { "description": "Registration hash and next step", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistrationResponse" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "CaptchaError": { "description": "Incorrect captcha", "value": { "errorCode": "CaptchaError", "message": "Incorrect captcha" } }, "RegistrationWrongState": { "description": "Wrong state", "value": { "errorCode": "RegistrationWrongState", "message": "Wrong state" } } } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AccountNotFound", "message": "Account not found" } } }, "description": "Account not found" } }, "security": [] } }, "/api/v1/accounts/confirm-email": { "post": { "summary": "Signup - Step 2: Verify email with code", "description": "Step 2 of email signup: validates the confirmation code sent to email. Advances registration to next step (CAPTCHA, reason, or account creation). Code expires after a set time and has limited retry attempts.", "tags": [ "Accounts" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeVerificationParams" } } }, "required": true }, "responses": { "200": { "description": "Registration hash and next step", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistrationResponse" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "RegistrationWrongState": { "description": "Wrong state", "value": { "errorCode": "RegistrationWrongState", "message": "Wrong state" } }, "VerificationCodeError": { "description": "Incorrect verification code", "value": { "errorCode": "VerificationCodeError", "message": "Incorrect verification code" } }, "VerificationCodeTooMany": { "description": "Too many attempts", "value": { "errorCode": "VerificationCodeTooMany", "message": "Too many attempts" } } } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AccountNotFound", "message": "Account not found" } } }, "description": "Account not found" } }, "security": [] } }, "/api/v1/accounts/confirm-phone": { "post": { "summary": "Signup - Step 2: Verify phone with code", "description": "Step 2 of phone signup: validates the SMS code sent to phone number. Advances registration to next step (CAPTCHA, reason, or account creation). Code expires after a set time and has limited retry attempts.", "tags": [ "Accounts" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeVerificationParams" } } }, "required": true }, "responses": { "200": { "description": "Registration hash and next step", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistrationResponse" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "RegistrationWrongState": { "description": "Wrong state", "value": { "errorCode": "RegistrationWrongState", "message": "Wrong state" } }, "VerificationCodeError": { "description": "Incorrect verification code", "value": { "errorCode": "VerificationCodeError", "message": "Incorrect verification code" } }, "VerificationCodeTooMany": { "description": "Too many attempts", "value": { "errorCode": "VerificationCodeTooMany", "message": "Too many attempts" } } } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AccountNotFound", "message": "Account not found" } } }, "description": "Account not found" } }, "security": [] } }, "/api/v1/accounts/delete": { "delete": { "summary": "Delete current account", "description": "Permanently deletes the authenticated account and all associated users. Sends deletion notifications to federated followers. Cannot delete if it's the last admin account on the server. This operation is irreversible - all data including posts, follows, and media will be removed.", "tags": [ "Accounts" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "CantRemoveLastAdmin", "message": "Cannot remove the last remaining admin user" } } }, "description": "Cannot remove the last remaining admin user" }, "500": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AccountIsNotRemoved", "message": "Failed to remove the account" } } }, "description": "Failed to remove the account" } }, "security": [ { "header": [] } ] } }, "/api/v1/accounts/email/change/confirm": { "post": { "summary": "Confirm and complete email change", "description": "Completes the email change process by verifying the confirmation code. Updates the account's email address upon successful verification. Sends confirmation to the new email address. Invalidates all existing tokens except the current session for security. The change is logged in the audit trail.", "tags": [ "Email" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationCodeRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "VerificationCodeError": { "description": "Incorrect verification code", "value": { "errorCode": "VerificationCodeError", "message": "Incorrect verification code" } }, "VerificationCodeTooMany": { "description": "Too many attempts", "value": { "errorCode": "VerificationCodeTooMany", "message": "Too many attempts" } }, "EmailChangeRequestNotFound": { "description": "Request to change email not found", "value": { "errorCode": "EmailChangeRequestNotFound", "message": "Request to change email not found" } }, "EmailNotUpdated": { "description": "Failed to update the email address", "value": { "errorCode": "EmailNotUpdated", "message": "Failed to update the email address" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EmailExists", "message": "The email address is already associated with an account" } } }, "description": "The email address is already associated with an account" } }, "security": [ { "header": [] } ] } }, "/api/v1/accounts/email/change/request": { "post": { "summary": "Request email address change", "description": "Initiates email change process for the authenticated account. Requires current password verification for security. Sends notification to current email and verification code to new email. The new email must not already be registered. Includes IP address and geolocation in notification for security awareness.", "tags": [ "Email" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailChangeRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "VerificationCodeTooMany", "message": "Too many attempts" } } }, "description": "Too many attempts" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserIncorrectPassword", "message": "Invalid password provided" } } }, "description": "Invalid password provided" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EmailExists", "message": "The email address is already associated with an account" } } }, "description": "The email address is already associated with an account" } }, "security": [ { "header": [] } ] } }, "/api/v1/accounts/email/change/resend-code": { "put": { "summary": "Resend email verification code", "description": "Resends the verification code to the new email address for a pending email change. Use when the initial code was not received or has expired. Rate limited to prevent abuse. Requires an active email change request.", "tags": [ "Email" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "VerificationCodeTooMany": { "description": "Too many attempts", "value": { "errorCode": "VerificationCodeTooMany", "message": "Too many attempts" } }, "EmailChangeRequestNotFound": { "description": "Request to change email not found", "value": { "errorCode": "EmailChangeRequestNotFound", "message": "Request to change email not found" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/accounts/finish-creating": { "post": { "summary": "Signup - Final Step: Complete account creation", "description": "Final step of signup: creates the account and user after all validations pass. Returns account details with authentication token for immediate login. Sends welcome email if applicable. Can optionally update username at this stage.", "tags": [ "Accounts" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinishCreatingAccountParams" } } }, "required": true }, "responses": { "200": { "description": "Account, users and session key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountWithUserAndToken" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "RegistrationApprovalRequired": { "description": "Registration approval required", "value": { "errorCode": "RegistrationApprovalRequired", "message": "Registration approval required" } }, "InvitesNotEnabled": { "description": "Invite links are not enabled", "value": { "errorCode": "InvitesNotEnabled", "message": "Invite links are not enabled" } }, "InvalidInviteCode": { "description": "Invalid or exhausted invite code", "value": { "errorCode": "InvalidInviteCode", "message": "Invalid or exhausted invite code" } } } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AccountNotFound", "message": "Account not found" } } }, "description": "Account not found" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "UserNameIsReserved": { "description": "The username is reserved and cannot be used", "value": { "errorCode": "UserNameIsReserved", "message": "The username is reserved and cannot be used" } }, "UserNameExists": { "description": "The username is already in use", "value": { "errorCode": "UserNameExists", "message": "The username is already in use" } }, "EmailExists": { "description": "The email address is already associated with an account", "value": { "errorCode": "EmailExists", "message": "The email address is already associated with an account" } }, "PhoneExists": { "description": "This phone number is already associated with an account", "value": { "errorCode": "PhoneExists", "message": "This phone number is already associated with an account" } } } } }, "description": "Conflict" }, "500": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AccountCreationError", "message": "Failed to create the account" } } }, "description": "Failed to create the account" } }, "security": [], "parameters": [ { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ] } }, "/api/v1/accounts/get-token/{hash}": { "put": { "summary": "Retrieve token for approved phone account", "description": "One-time token retrieval for phone-based accounts approved by admin. Used when admin manually approves a phone registration. The signup request is deleted after successful token generation. Only works for accounts in USER step of registration.", "tags": [ "Accounts" ], "parameters": [ { "name": "hash", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Session key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Token" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "RegistrationWrongState", "message": "Wrong state" } } }, "description": "Wrong state" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AccountNotFound", "message": "Account not found" } } }, "description": "Account not found" } }, "security": [] } }, "/api/v1/accounts/logins/add-email-password": { "post": { "summary": "Request to add email/password to account", "description": "Initiates the process of adding email and password authentication to an existing account. A confirmation code will be sent to the provided email address.", "tags": [ "Logins" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddEmailRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "EmailAlreadySet": { "description": "Email is already set for this account", "value": { "errorCode": "EmailAlreadySet", "message": "Email is already set for this account" } }, "VerificationCodeTooMany": { "description": "Too many attempts", "value": { "errorCode": "VerificationCodeTooMany", "message": "Too many attempts" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EmailExists", "message": "The email address is already associated with an account" } } }, "description": "The email address is already associated with an account" } }, "security": [ { "header": [] } ] } }, "/api/v1/accounts/logins/add-email-password/confirm": { "post": { "summary": "Confirm email/password addition", "description": "Confirms the addition of email/password authentication by verifying the confirmation code sent to the email. On success, sets the email and password on the account, sends a confirmation email, and logs the change in the audit trail. Requires authentication.", "tags": [ "Logins" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationCodeRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "VerificationCodeError": { "description": "Incorrect verification code", "value": { "errorCode": "VerificationCodeError", "message": "Incorrect verification code" } }, "VerificationCodeTooMany": { "description": "Too many attempts", "value": { "errorCode": "VerificationCodeTooMany", "message": "Too many attempts" } }, "EmailChangeRequestNotFound": { "description": "Request to change email not found", "value": { "errorCode": "EmailChangeRequestNotFound", "message": "Request to change email not found" } }, "EmailAlreadySet": { "description": "Email is already set for this account", "value": { "errorCode": "EmailAlreadySet", "message": "Email is already set for this account" } }, "EmailNotUpdated": { "description": "Failed to update the email address", "value": { "errorCode": "EmailNotUpdated", "message": "Failed to update the email address" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EmailExists", "message": "The email address is already associated with an account" } } }, "description": "The email address is already associated with an account" } }, "security": [ { "header": [] } ] } }, "/api/v1/accounts/logins/add-email-password/resend-code": { "put": { "summary": "Resend email confirmation code", "description": "Resends the confirmation code to the pending email address when adding email/password authentication.", "tags": [ "Logins" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "VerificationCodeTooMany", "message": "Too many attempts" } } }, "description": "Too many attempts" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ResourceNotFound", "message": "The requested resource not found" } } }, "description": "The requested resource not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/accounts/logins/add-phone": { "post": { "summary": "Add phone number to account", "description": "Adds phone number authentication to the account. If no code is provided, initiates SMS verification. If code is provided, confirms the phone number.", "tags": [ "Logins" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddPhoneRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "PhoneAlreadySet": { "description": "Phone number is already set for this account", "value": { "errorCode": "PhoneAlreadySet", "message": "Phone number is already set for this account" } }, "VerificationCodeTooMany": { "description": "Too many attempts", "value": { "errorCode": "VerificationCodeTooMany", "message": "Too many attempts" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PhoneExists", "message": "This phone number is already associated with an account" } } }, "description": "This phone number is already associated with an account" } }, "security": [ { "header": [] } ] } }, "/api/v1/accounts/logins/remove-email-password": { "delete": { "summary": "Remove email/password from account", "description": "Removes email and password authentication method from the account. Cannot be removed if it's the last remaining login method.", "tags": [ "Logins" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EmailNotSet", "message": "Email not set for this account" } } }, "description": "Email not set for this account" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "CantRemoveLastLogin", "message": "Cannot remove the last login option" } } }, "description": "Cannot remove the last login option" } }, "security": [ { "header": [] } ] } }, "/api/v1/accounts/logins/remove-phone": { "delete": { "summary": "Remove phone number from account", "description": "Removes phone number authentication from the account. Cannot be removed if it's the last remaining login method.", "tags": [ "Logins" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PhoneNotSet", "message": "Phone number not set for this account" } } }, "description": "Phone number not set for this account" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "CantRemoveLastLogin", "message": "Cannot remove the last login option" } } }, "description": "Cannot remove the last login option" } }, "security": [ { "header": [] } ] } }, "/api/v1/accounts/password/change/confirm": { "post": { "summary": "Confirm and apply password change", "description": "Step 2 of authenticated password change: verifies the email confirmation code and applies the new password. Sends a confirmation email and invalidates all other active sessions. Requires authentication.", "tags": [ "Password" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationCodeRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "VerificationCodeError": { "description": "Incorrect verification code", "value": { "errorCode": "VerificationCodeError", "message": "Incorrect verification code" } }, "VerificationCodeTooMany": { "description": "Too many attempts", "value": { "errorCode": "VerificationCodeTooMany", "message": "Too many attempts" } }, "PasswordNotUpdated": { "description": "Failed to change password", "value": { "errorCode": "PasswordNotUpdated", "message": "Failed to change password" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/accounts/password/change/request": { "post": { "summary": "Request password change", "description": "Step 1 of authenticated password change: validates the current password and stores the new password temporarily. Sends a confirmation code to the account email. Requires authentication and a valid current password.", "tags": [ "Password" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordChangeRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "VerificationCodeTooMany", "message": "Too many attempts" } } }, "description": "Too many attempts" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserIncorrectPassword", "message": "Invalid password provided" } } }, "description": "Invalid password provided" } }, "security": [ { "header": [] } ] } }, "/api/v1/accounts/password/change/resend-code": { "put": { "summary": "Resend password change confirmation code", "description": "Resends the confirmation code for an in-progress password change to the account email. Use when the original code was not received or expired. Requires authentication. Rate limited to prevent abuse.", "tags": [ "Password" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "VerificationCodeTooMany", "message": "Too many attempts" } } }, "description": "Too many attempts" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/accounts/password/recover": { "post": { "summary": "Request password recovery", "description": "Step 1 of password recovery for unauthenticated users: sends a recovery code to the account email. Accepts either email or username as the login identifier. Must NOT be authenticated - returns error if called with an active session. Rate limited to prevent abuse.", "tags": [ "Password" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordRecoveryRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthAuthorized": { "description": "User is authorized", "value": { "errorCode": "AuthAuthorized", "message": "User is authorized" } }, "VerificationCodeTooMany": { "description": "Too many attempts", "value": { "errorCode": "VerificationCodeTooMany", "message": "Too many attempts" } } } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AccountNotFound", "message": "Account not found" } } }, "description": "Account not found" } }, "security": [] } }, "/api/v1/accounts/password/recover/change": { "post": { "summary": "Set new password after recovery", "description": "Step 3 of password recovery: sets the new password for an unauthenticated user. Requires that the recovery code was previously validated via /recover/check-code. Sends a confirmation email and invalidates all existing sessions. Must NOT be authenticated - returns error if called with an active session.", "tags": [ "Password" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordRecoveryChange" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthAuthorized": { "description": "User is authorized", "value": { "errorCode": "AuthAuthorized", "message": "User is authorized" } }, "ConfirmationRequired": { "description": "Confirmation required", "value": { "errorCode": "ConfirmationRequired", "message": "Confirmation required" } }, "PasswordNotUpdated": { "description": "Failed to change password", "value": { "errorCode": "PasswordNotUpdated", "message": "Failed to change password" } } } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AccountNotFound", "message": "Account not found" } } }, "description": "Account not found" } }, "security": [] } }, "/api/v1/accounts/password/recover/check-code": { "post": { "summary": "Validate password recovery code", "description": "Step 2 of password recovery: validates the recovery code sent to email. On success, stores a temporary flag allowing the password to be changed in the next step. Must NOT be authenticated - returns error if called with an active session.", "tags": [ "Password" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordRecoveryCode" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthAuthorized": { "description": "User is authorized", "value": { "errorCode": "AuthAuthorized", "message": "User is authorized" } }, "VerificationCodeError": { "description": "Incorrect verification code", "value": { "errorCode": "VerificationCodeError", "message": "Incorrect verification code" } }, "VerificationCodeTooMany": { "description": "Too many attempts", "value": { "errorCode": "VerificationCodeTooMany", "message": "Too many attempts" } } } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AccountNotFound", "message": "Account not found" } } }, "description": "Account not found" } }, "security": [] } }, "/api/v1/accounts/phone/change/confirm/auth": { "post": { "summary": "Confirm authentication with phone number", "description": "Step 2. Validate the provided authentication code. After 3 failed attempts, the current user session will be invalidated.", "tags": [ "Phone" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationCodeRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "VerificationCodeError": { "description": "Incorrect verification code", "value": { "errorCode": "VerificationCodeError", "message": "Incorrect verification code" } }, "VerificationCodeTooMany": { "description": "Too many attempts", "value": { "errorCode": "VerificationCodeTooMany", "message": "Too many attempts" } }, "PhoneNotSet": { "description": "Phone number not set for this account", "value": { "errorCode": "PhoneNotSet", "message": "Phone number not set for this account" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/accounts/phone/change/confirm/new-phone": { "post": { "summary": "Change phone number for authenticated user", "description": "Step 4. Validate the new verification code. Upon successful verification, the user's phone number will be updated to the newly verified number. All other active sessions are invalidated for security. The change is logged in the audit trail.", "tags": [ "Phone" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationCodeRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "VerificationCodeError": { "description": "Incorrect verification code", "value": { "errorCode": "VerificationCodeError", "message": "Incorrect verification code" } }, "VerificationCodeTooMany": { "description": "Too many attempts", "value": { "errorCode": "VerificationCodeTooMany", "message": "Too many attempts" } }, "PhoneNotSet": { "description": "Phone number not set for this account", "value": { "errorCode": "PhoneNotSet", "message": "Phone number not set for this account" } }, "PhoneNotUpdated": { "description": "Failed to update the phone number", "value": { "errorCode": "PhoneNotUpdated", "message": "Failed to update the phone number" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ResourceNotFound", "message": "The requested resource not found" } } }, "description": "The requested resource not found" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PhoneExists", "message": "This phone number is already associated with an account" } } }, "description": "This phone number is already associated with an account" } }, "security": [ { "header": [] } ] } }, "/api/v1/accounts/phone/change/new-phone": { "post": { "summary": "Request a new phone number", "description": "Step 3. Request a new phone number from the user. Verification code will be sent via SMS to that number.", "tags": [ "Phone" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddPhoneRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "VerificationCodeError": { "description": "Incorrect verification code", "value": { "errorCode": "VerificationCodeError", "message": "Incorrect verification code" } }, "VerificationCodeTooMany": { "description": "Too many attempts", "value": { "errorCode": "VerificationCodeTooMany", "message": "Too many attempts" } }, "PhoneNotSet": { "description": "Phone number not set for this account", "value": { "errorCode": "PhoneNotSet", "message": "Phone number not set for this account" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/accounts/phone/change/request": { "put": { "summary": "Request phone number change for authenticated user", "description": "Step 1. Request an authentication code to be sent via SMS to the user's original phone number.", "tags": [ "Phone" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "VerificationCodeTooMany": { "description": "Too many attempts", "value": { "errorCode": "VerificationCodeTooMany", "message": "Too many attempts" } }, "PhoneNotSet": { "description": "Phone number not set for this account", "value": { "errorCode": "PhoneNotSet", "message": "Phone number not set for this account" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/accounts/phone/change/resend-code/auth": { "put": { "summary": "Resend code to check authentication with phone number", "description": "Resends the SMS verification code to the user's current phone number. Use when the original code was not received or expired. Requires authentication. Rate limited.", "tags": [ "Phone" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "VerificationCodeTooMany": { "description": "Too many attempts", "value": { "errorCode": "VerificationCodeTooMany", "message": "Too many attempts" } }, "PhoneNotSet": { "description": "Phone number not set for this account", "value": { "errorCode": "PhoneNotSet", "message": "Phone number not set for this account" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ResourceNotFound", "message": "The requested resource not found" } } }, "description": "The requested resource not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/accounts/phone/change/resend-code/new-phone": { "put": { "summary": "Resend code to confirm new phone number", "description": "Resends the SMS verification code to the new phone number submitted in step 3. Use when the original code was not received or expired. Requires authentication. Rate limited.", "tags": [ "Phone" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "VerificationCodeTooMany": { "description": "Too many attempts", "value": { "errorCode": "VerificationCodeTooMany", "message": "Too many attempts" } }, "PhoneNotSet": { "description": "Phone number not set for this account", "value": { "errorCode": "PhoneNotSet", "message": "Phone number not set for this account" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ResourceNotFound", "message": "The requested resource not found" } } }, "description": "The requested resource not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/accounts/profile": { "get": { "summary": "Get current account profile", "description": "Returns the authenticated account with all associated users. Most accounts have a single user, but the system supports multiple users per account. Requires authentication token.", "tags": [ "Accounts" ], "responses": { "200": { "description": "Account and users", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountWithUser" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ], "parameters": [ { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ] } }, "/api/v1/accounts/resend-code/{hash}": { "put": { "summary": "Resend verification code", "description": "Resends verification code via email or SMS based on registration type. Automatically detects whether to send email or SMS from the signup request. Rate limited to prevent abuse. Use when code was not received or expired.", "tags": [ "Accounts" ], "parameters": [ { "name": "hash", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "SendEmailError": { "description": "Failed to send email", "value": { "errorCode": "SendEmailError", "message": "Failed to send email" } }, "SendSMSError": { "description": "Failed to send sms", "value": { "errorCode": "SendSMSError", "message": "Failed to send sms" } }, "VerificationCodeTooMany": { "description": "Too many attempts", "value": { "errorCode": "VerificationCodeTooMany", "message": "Too many attempts" } } } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AccountNotFound", "message": "Account not found" } } }, "description": "Account not found" }, "500": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AccountCreationError", "message": "Failed to create the account" } } }, "description": "Failed to create the account" } }, "security": [] } }, "/api/v1/accounts/resend-email/{hash}": { "put": { "summary": "Resend confirmation email", "description": "Resends the email verification code for pending registrations. Use when the initial email was not received or code expired. Rate limited to prevent abuse. Deprecated - use /resend-code instead.", "tags": [ "Accounts" ], "parameters": [ { "name": "hash", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "EmailNotSet": { "description": "Email not set for this account", "value": { "errorCode": "EmailNotSet", "message": "Email not set for this account" } }, "SendEmailError": { "description": "Failed to send email", "value": { "errorCode": "SendEmailError", "message": "Failed to send email" } } } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AccountNotFound", "message": "Account not found" } } }, "description": "Account not found" } }, "security": [] } }, "/api/v1/accounts/signup": { "post": { "summary": "Signup - Step 1: Start email signup process", "description": "Initiates account registration with email verification. Step 1 of multi-step signup: validates input, checks availability, sends confirmation email. Returns registration hash for tracking signup progress. Username must not be reserved, email must be unique and not blocked.", "tags": [ "Accounts" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountCreate" } } }, "required": true }, "responses": { "200": { "description": "Registration hash and next step. Hash can be used to resend confirmation email", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistrationResponse" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "RegistrationClosed": { "description": "Registration closed", "value": { "errorCode": "RegistrationClosed", "message": "Registration closed" } }, "SendEmailError": { "description": "Failed to send email", "value": { "errorCode": "SendEmailError", "message": "Failed to send email" } }, "InvitesNotEnabled": { "description": "Invite links are not enabled", "value": { "errorCode": "InvitesNotEnabled", "message": "Invite links are not enabled" } }, "InvalidInviteCode": { "description": "Invalid or exhausted invite code", "value": { "errorCode": "InvalidInviteCode", "message": "Invalid or exhausted invite code" } } } } }, "description": "Bad Request" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EmailBlocked", "message": "The email address or domain is blocked from registration" } } }, "description": "The email address or domain is blocked from registration" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "UserNameIsReserved": { "description": "The username is reserved and cannot be used", "value": { "errorCode": "UserNameIsReserved", "message": "The username is reserved and cannot be used" } }, "UserNameExists": { "description": "The username is already in use", "value": { "errorCode": "UserNameExists", "message": "The username is already in use" } }, "EmailExists": { "description": "The email address is already associated with an account", "value": { "errorCode": "EmailExists", "message": "The email address is already associated with an account" } } } } }, "description": "Conflict" }, "500": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AccountCreationError", "message": "Failed to create the account" } } }, "description": "Failed to create the account" } }, "security": [] } }, "/api/v1/accounts/signup-phone": { "post": { "summary": "Signup - Step 1: Start phone signup process", "description": "Initiates account registration with phone verification. Step 1 of multi-step signup: validates input, checks availability, sends SMS code. Returns registration hash for tracking signup progress. Username must not be reserved, phone number must be unique.", "tags": [ "Accounts" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneSignup" } } }, "required": true }, "responses": { "200": { "description": "Registration hash and next step. Hash can be used to resend confirmation code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistrationResponse" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "RegistrationClosed": { "description": "Registration closed", "value": { "errorCode": "RegistrationClosed", "message": "Registration closed" } }, "InvalidPhoneNumber": { "description": "The provided phone number is invalid", "value": { "errorCode": "InvalidPhoneNumber", "message": "The provided phone number is invalid" } }, "SendSMSError": { "description": "Failed to send sms", "value": { "errorCode": "SendSMSError", "message": "Failed to send sms" } }, "SMSServiceDisabled": { "description": "SMS service is not enabled", "value": { "errorCode": "SMSServiceDisabled", "message": "SMS service is not enabled" } }, "SMSUnsupportedCountry": { "description": "SMS service is not available in this country", "value": { "errorCode": "SMSUnsupportedCountry", "message": "SMS service is not available in this country" } }, "InvitesNotEnabled": { "description": "Invite links are not enabled", "value": { "errorCode": "InvitesNotEnabled", "message": "Invite links are not enabled" } }, "InvalidInviteCode": { "description": "Invalid or exhausted invite code", "value": { "errorCode": "InvalidInviteCode", "message": "Invalid or exhausted invite code" } } } } }, "description": "Bad Request" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "UserNameIsReserved": { "description": "The username is reserved and cannot be used", "value": { "errorCode": "UserNameIsReserved", "message": "The username is reserved and cannot be used" } }, "UserNameExists": { "description": "The username is already in use", "value": { "errorCode": "UserNameExists", "message": "The username is already in use" } }, "PhoneExists": { "description": "This phone number is already associated with an account", "value": { "errorCode": "PhoneExists", "message": "This phone number is already associated with an account" } } } } }, "description": "Conflict" }, "500": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AccountCreationError", "message": "Failed to create the account" } } }, "description": "Failed to create the account" } }, "security": [] } }, "/api/v1/accounts/user/reselect-user": { "post": { "summary": "Switch between account users", "description": "Generates a new token for a different user within the same account. Useful for accounts with multiple users to switch active user context. Either userId or userName must be provided. Only users belonging to the authenticated account can be selected.", "tags": [ "Accounts" ], "parameters": [ { "description": "User id", "required": false, "name": "userId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "Username", "required": false, "name": "userName", "in": "query", "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "Session key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Token" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserIdOrUserNameMissing", "message": "The userId or userName must be provided" } } }, "description": "The userId or userName must be provided" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthUnauthorized": { "description": "A valid authentication token is required", "value": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } }, "UserBadCreds": { "description": "Invalid user credentials provided", "value": { "errorCode": "UserBadCreds", "message": "Invalid user credentials provided" } } } } }, "description": "Unauthorized" } }, "security": [ { "header": [] } ] } }, "/api/v1/accounts/users-owned-groups": { "get": { "summary": "Get account users with owned groups", "description": "Returns all users belonging to the authenticated account and, for each user, the list of groups they own. Useful for account-level management and confirmation workflows.", "tags": [ "Accounts" ], "responses": { "200": { "description": "Account users with owned groups", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountUsersWithOwnedGroups" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AccountNotFound", "message": "Account not found" } } }, "description": "Account not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/addresses/suggest": { "get": { "summary": "Suggest addresses for the given address part", "tags": [ "Addresses" ], "parameters": [ { "description": "Language to use for the completion", "required": false, "name": "lang", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Language" } ], "nullable": true } }, { "description": "Address to complete", "required": true, "name": "text", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of potential addresses matching the criteria", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AddressData" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "429": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AddressesRequestRateExceeded", "message": "The addresses API rate exceeded" } } }, "description": "The addresses API rate exceeded" }, "500": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AddressesError": { "description": "The addresses API %d error: %s", "value": { "errorCode": "AddressesError", "message": "The addresses API %d error: %s" } }, "AddressesAuthError": { "description": "The addresses API auth error", "value": { "errorCode": "AddressesAuthError", "message": "The addresses API auth error" } } } } }, "description": "Internal Server Error" } }, "security": [] } }, "/api/v1/admin/account/{accountId}": { "get": { "summary": "Retrieve account information by ID", "description": "Fetches comprehensive details about an account including its associated users. Returns account metadata (email, creation date) and all users linked to this account. Most accounts have a single user, but the system supports multiple users per account.\n\nRBAC: requires Users.Manage", "tags": [ "Admin Accounts" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ], "responses": { "200": { "description": "Account details with associated users", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountWithUser" } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AccountNotFound", "message": "Account not found" } } }, "description": "Account not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/audit_log": { "get": { "summary": "List audit log entries", "description": "Retrieves a paginated list of audit log entries with flexible filtering options. Returns security-relevant actions performed by users, accounts, or services within the platform.\n\nRBAC: requires Audit.Read", "tags": [ "Admin Audit" ], "parameters": [ { "description": "Filter by account ID (mutually exclusive with email parameter)", "example": "ac_01hxcvk1hjexere4pvtrj0ymqq", "schema": { "type": "string", "nullable": true }, "name": "accountId", "in": "query", "required": false }, { "description": "Filter by specific actions (e.g., CREATE, UPDATE, DELETE). Multiple values allowed.", "example": [ "CREATE", "UPDATE" ], "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AuditLogAction" }, "nullable": true }, "name": "action", "in": "query", "required": false }, { "description": "Filter by application ID", "example": "ap_01hxcvk1hjexere4pvtrj0ymqq", "schema": { "type": "string", "nullable": true }, "name": "appId", "in": "query", "required": false }, { "description": "Search for entries related to specific domains", "example": "example.com", "schema": { "type": "string", "nullable": true }, "name": "domainSearch", "in": "query", "required": false }, { "description": "Filter by email address (mutually exclusive with accountId parameter)", "example": "user@example.com", "schema": { "type": "string", "nullable": true }, "name": "email", "in": "query", "required": false }, { "description": "Filter by audit log groups (e.g., ACCOUNT, USER, APP). Multiple values allowed.", "example": [ "ACCOUNT", "USER" ], "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AuditLogGroup" }, "nullable": true }, "name": "group", "in": "query", "required": false }, { "description": "Filter by group ID", "example": "gr_01hxcvk1hjexere4pvtrj0ymqq", "schema": { "type": "string", "nullable": true }, "name": "groupId", "in": "query", "required": false }, { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "Filter by rule ID", "example": "ru_01hxcvk1hjexere4pvtrj0ymqq", "schema": { "type": "string", "nullable": true }, "name": "ruleId", "in": "query", "required": false }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "Filter by user ID (mutually exclusive with username parameter)", "example": "us_01hxcvk1hjexere4pvtrj0ymqq", "schema": { "type": "string", "nullable": true }, "name": "userId", "in": "query", "required": false }, { "description": "Filter by username with optional domain (e.g., 'john' or '@john@example.com'). Mutually exclusive with userId parameter.", "example": "@john@example.com", "schema": { "type": "string", "nullable": true }, "name": "username", "in": "query", "required": false } ], "responses": { "200": { "description": "Successfully retrieved audit log entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditLogResult" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ConstraintViolation", "message": "A request parameter constraint was violated" } } }, "description": "A request parameter constraint was violated" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/change/email": { "put": { "summary": "Change email address for an account", "description": "Administratively updates the email address for a user account. Can identify the user by username or user ID. The new email must be valid and unique in the system. This operation is logged for audit purposes and the change takes effect immediately.\n\nRBAC: requires Users.Manage", "tags": [ "Admin Accounts" ], "parameters": [ { "description": "New email address for the account. Must be a valid email format and unique in the system.", "required": true, "name": "email", "in": "query", "schema": { "type": "string" } }, { "description": "User ID whose email to change. Must be a valid USER type ID. Either username or id must be provided.", "required": false, "name": "id", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "Username of the user whose email to change. Case-insensitive. Either username or id must be provided.", "required": false, "name": "username", "in": "query", "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "Email address successfully changed", "content": { "text/plain": {} } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AdminNeedUsernameOrId", "message": "Either a username or user ID must be provided" } } }, "description": "Either a username or user ID must be provided" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AccountNotFound", "message": "Account not found" } } }, "description": "Account not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/change/password": { "put": { "summary": "Change password for an account", "description": "Administratively resets the password for a user account. Can identify the user by username or user ID. The new password should meet security requirements. This operation is logged for audit purposes and does not require knowing the current password.\n\nRBAC: requires Users.Manage", "tags": [ "Admin Accounts" ], "parameters": [ { "description": "User ID whose password to change. Must be a valid USER type ID. Either username or id must be provided.", "required": false, "name": "id", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "New password for the account. Should meet security requirements.", "required": true, "name": "password", "in": "query", "schema": { "type": "string" } }, { "description": "Username of the user whose password to change. Case-insensitive. Either username or id must be provided.", "required": false, "name": "username", "in": "query", "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "Password successfully changed", "content": { "text/plain": {} } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AdminNeedUsernameOrId", "message": "Either a username or user ID must be provided" } } }, "description": "Either a username or user ID must be provided" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AccountNotFound", "message": "Account not found" } } }, "description": "Account not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/change/role/assign": { "put": { "summary": "Assign role to a user", "description": "Assigns a server or group role to a user identified by username or user ID. Roles use the format 'Scope:RoleName' (e.g., 'System:ADMIN'). The change is audit-logged and streamed to the account's real-time channel. Requires Users.Manage permission.\n\nRBAC: requires Users.Manage", "tags": [ "Admin Accounts" ], "parameters": [ { "description": "User ID to assign the role to. Must be a valid USER type ID. Either username or id must be provided.", "required": false, "name": "id", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "Role ID to assign in format 'Scope:RoleName' (e.g., 'System:ADMIN', 'Group:MODERATOR'). Must be a valid role.", "required": true, "name": "role", "in": "query", "schema": { "$ref": "#/components/schemas/RoleId" } }, { "description": "Username of the user to assign the role to. Case-insensitive. Either username or id must be provided.", "required": false, "name": "username", "in": "query", "schema": { "type": "string", "nullable": true } }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountWithUser" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AdminNeedUsernameOrId", "message": "Either a username or user ID must be provided" } } }, "description": "Either a username or user ID must be provided" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "CantRemoveLastAdmin": { "description": "Cannot remove the last remaining admin user", "value": { "errorCode": "CantRemoveLastAdmin", "message": "Cannot remove the last remaining admin user" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AccountNotFound", "message": "Account not found" } } }, "description": "Account not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/change/role/revoke": { "put": { "summary": "Revoke role from a user", "description": "Revokes a role from a user identified by username or user ID. Cannot revoke the System:ADMIN role if it is the last remaining admin on the server. The change is audit-logged and streamed to the account's real-time channel. Requires Users.Manage permission.\n\nRBAC: requires Users.Manage", "tags": [ "Admin Accounts" ], "parameters": [ { "description": "User ID to revoke the role from. Must be a valid USER type ID. Either username or id must be provided.", "required": false, "name": "id", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "Role ID to revoke in format 'Scope:RoleName'. Must currently be assigned to the user.", "required": true, "name": "role", "in": "query", "schema": { "$ref": "#/components/schemas/RoleId" } }, { "description": "Username of the user to revoke the role from. Case-insensitive. Either username or id must be provided.", "required": false, "name": "username", "in": "query", "schema": { "type": "string", "nullable": true } }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountWithUser" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AdminNeedUsernameOrId", "message": "Either a username or user ID must be provided" } } }, "description": "Either a username or user ID must be provided" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "CantRemoveLastAdmin": { "description": "Cannot remove the last remaining admin user", "value": { "errorCode": "CantRemoveLastAdmin", "message": "Cannot remove the last remaining admin user" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AccountNotFound", "message": "Account not found" } } }, "description": "Account not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/clear-ap-errors": { "post": { "summary": "Clear ActivityPub delivery errors for a domain", "description": "Resets the failure counter for the specified remote domain. Use this after a remote server has resolved its issues to allow federation delivery to resume. Requires Federation.Manage permission.\n\nRBAC: requires Federation.Manage", "tags": [ "Admin ActivityPub" ], "parameters": [ { "description": "Remote domain to clear errors for", "example": "mastodon.social", "required": true, "name": "domain", "in": "query", "schema": { "pattern": "\\S", "type": "string" } } ], "responses": { "200": { "description": "Delivery errors cleared successfully", "content": { "application/json": { "schema": {} } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/create-account": { "post": { "summary": "Create a new account with initial user", "description": "Creates a new account with an initial user profile. The account will have a unique email and the user will have a unique username. This endpoint validates that the username is not reserved, the username doesn't already exist, and the email is not already registered. Returns the created account with its associated user information.\n\nRBAC: requires Users.Manage", "tags": [ "Admin Accounts" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountCreate" } } }, "required": true }, "responses": { "200": { "description": "Account successfully created with initial user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountWithUser" } } } }, "400": { "description": "Bad Request" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "UserNameIsReserved": { "description": "The username is reserved and cannot be used", "value": { "errorCode": "UserNameIsReserved", "message": "The username is reserved and cannot be used" } }, "UserNameExists": { "description": "The username is already in use", "value": { "errorCode": "UserNameExists", "message": "The username is already in use" } }, "EmailExists": { "description": "The email address is already associated with an account", "value": { "errorCode": "EmailExists", "message": "The email address is already associated with an account" } } } } }, "description": "Conflict" }, "500": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AccountCreationError", "message": "Failed to create the account" } } }, "description": "Failed to create the account" } }, "security": [ { "header": [] } ], "parameters": [ { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ] } }, "/api/v1/admin/create-user": { "post": { "summary": "Create a new user under an existing account", "description": "Creates a new user profile under an existing account. The user will have a unique username within the account's domain. This endpoint validates that the username is not reserved, the username doesn't already exist, and the associated account exists. Returns the created user information.\n\nRBAC: requires Users.Manage", "tags": [ "Admin Accounts" ], "parameters": [ { "description": "Account id to add user to", "required": false, "name": "account_id", "in": "query", "schema": { "$ref": "#/components/schemas/TypeId" } }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ], "requestBody": { "description": "JSON object with the user's data", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserCreate" } } } }, "responses": { "200": { "description": "User successfully created under existing account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserFull" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ConstraintViolation", "message": "A request parameter constraint was violated" } } }, "description": "A request parameter constraint was violated" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AccountNotFound", "message": "Account not found" } } }, "description": "Account not found" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "UserNameIsReserved": { "description": "The username is reserved and cannot be used", "value": { "errorCode": "UserNameIsReserved", "message": "The username is reserved and cannot be used" } }, "UserNameExists": { "description": "The username is already in use", "value": { "errorCode": "UserNameExists", "message": "The username is already in use" } } } } }, "description": "Conflict" }, "500": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserCreationError", "message": "Failed to create the user" } } }, "description": "Failed to create the user" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/delete": { "delete": { "summary": "Delete an account with all associated users", "description": "Permanently deletes an account and all its associated users. Can identify the account by email address, account ID, or username. This operation notifies followers on remote servers about the deletion and marks all associated content appropriately. This action is irreversible. Administrators cannot delete their own account through this endpoint.\n\nRBAC: requires Users.Manage", "tags": [ "Admin Accounts" ], "parameters": [ { "description": "Email of the account to delete", "required": false, "name": "email", "in": "query", "schema": { "type": "string", "nullable": true } }, { "description": "Id of the account to delete", "required": false, "name": "id", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "Username of the account to delete", "required": false, "name": "username", "in": "query", "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "Account and all associated users successfully deleted", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AdminNeedEmailAccIdUsername": { "description": "Either an email address, account ID, or username must be provided", "value": { "errorCode": "AdminNeedEmailAccIdUsername", "message": "Either an email address, account ID, or username must be provided" } }, "AdminDeleteAccWithSelf": { "description": "Cannot delete self", "value": { "errorCode": "AdminDeleteAccWithSelf", "message": "Cannot delete self" } } } } }, "description": "Bad Request" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AccountNotFound", "message": "Account not found" } } }, "description": "Account not found" }, "500": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AccountIsNotRemoved", "message": "Failed to remove the account" } } }, "description": "Failed to remove the account" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/delete-user": { "delete": { "summary": "Delete a user", "description": "Permanently deletes a user profile. Can identify the user by username or user ID. This operation notifies followers on remote servers about the deletion and marks all associated content appropriately. This action is irreversible. Administrators cannot delete their own user profile through this endpoint.\n\nRBAC: requires Users.Manage", "tags": [ "Admin Accounts" ], "parameters": [ { "description": "User ID to delete. Must be a valid USER type ID.", "required": false, "name": "id", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "Username of the user to delete. Case-insensitive.", "required": false, "name": "username", "in": "query", "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "User successfully deleted", "content": { "text/plain": {} } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AdminNeedUsernameOrId": { "description": "Either a username or user ID must be provided", "value": { "errorCode": "AdminNeedUsernameOrId", "message": "Either a username or user ID must be provided" } }, "AdminDeleteAccWithSelf": { "description": "Cannot delete self", "value": { "errorCode": "AdminDeleteAccWithSelf", "message": "Cannot delete self" } } } } }, "description": "Bad Request" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserNotFound", "message": "User not found" } } }, "description": "User not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/domain-allow": { "get": { "summary": "List allowed domains", "description": "Retrieves a paginated list of all domains in the federation allowlist. This list determines which external instances can federate with this server when allowlisting is enabled.\n\nRBAC:\n- requires ANY of Federation.Read, Federation.Manage", "tags": [ "Admin Domains Allow List" ], "parameters": [ { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } ], "responses": { "200": { "description": "Successfully retrieved list of allowed domains", "content": { "application/json": { "examples": { "Domain list": { "value": [ { "domain": "mastodon.social", "createdAt": "2024-01-15T10:30:00Z" }, { "domain": "example.com", "createdAt": "2024-01-16T14:20:00Z" } ] } }, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AllowedDomain" } } } } } }, "security": [] }, "post": { "summary": "Add domain to allowlist", "description": "Adds a domain to the federation allowlist. When domain allowlisting is enabled, only domains in this list can federate with the instance. Cannot add the instance's own domain.\n\nRBAC: requires Federation.Manage", "tags": [ "Admin Domains Allow List" ], "requestBody": { "description": "Domain to add to the allowlist", "content": { "application/json": { "examples": { "Add domain": { "value": { "domain": "example.com" } } }, "schema": { "$ref": "#/components/schemas/AllowedDomainReq" } } }, "required": true }, "responses": { "200": { "description": "Domain successfully added to allowlist", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "DomainAlreadyAllowed", "message": "The domain is already allowed" } } }, "description": "The domain is already allowed" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/domain-allow/{domain}": { "delete": { "summary": "Remove domain from allowlist", "description": "Removes a domain from the federation allowlist. This will trigger background jobs to unfederate with the domain and clean up any existing connections.\n\nRBAC: requires Federation.Manage", "tags": [ "Admin Domains Allow List" ], "parameters": [ { "description": "Domain name to remove from the allowlist", "example": "example.com", "required": true, "name": "domain", "in": "path", "schema": { "pattern": "\\S", "type": "string" } } ], "responses": { "200": { "description": "Domain successfully removed from allowlist", "content": { "application/json": { "schema": {} } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "DomainIsNotAllowed": { "description": "The domain is not allowed", "value": { "errorCode": "DomainIsNotAllowed", "message": "The domain is not allowed" } } } } }, "description": "Forbidden" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/domain-block": { "put": { "summary": "Update domain block", "description": "Modifies an existing domain block with new settings. Can change the block severity, media/report rejection settings, comments, and obfuscation. Triggers background jobs if the state changes.\n\nRBAC: requires Federation.Manage", "tags": [ "Admin Domain Blocks" ], "requestBody": { "description": "Updated domain block configuration", "content": { "application/json": { "examples": { "Upgrade to SUSPEND": { "value": { "domain": "spam.example", "publicComment": "Severe violations", "state": "SUSPEND" } } }, "schema": { "$ref": "#/components/schemas/BlockDomainReq" } } }, "required": true }, "responses": { "200": { "description": "Domain block successfully updated", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "DomainIsNotBlocked", "message": "The domain is not currently blocked" } } }, "description": "The domain is not currently blocked" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "DomainAlreadyBlocked", "message": "The domain is already blocked" } } }, "description": "The domain is already blocked" } }, "security": [ { "header": [] } ] }, "get": { "summary": "List blocked domains (Admin)", "description": "Retrieves the complete list of domains that are blocked, including all metadata such as private comments, exact domain names, and internal settings. This endpoint is for administrators only.\n\nRBAC:\n- requires ANY of Federation.Read, Federation.Manage", "tags": [ "Admin Domain Blocks" ], "parameters": [ { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } ], "responses": { "200": { "description": "Successfully retrieved list of blocked domains", "content": { "application/json": { "examples": { "Blocked domains list": { "value": [ { "domain": "spam.example", "publicComment": "Spam", "state": "SUSPEND", "rejectMedia": true, "rejectReports": true, "privateComment": "Severe spam issues", "obfuscate": false, "createdAt": "2024-01-15T10:30:00Z", "updatedAt": "2024-01-15T10:30:00Z" } ] } }, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BlockedDomain" } } } } } }, "security": [ { "header": [] } ] }, "post": { "summary": "Block a domain", "description": "Creates a new domain block that prevents or limits interactions with the specified domain. The block severity can be SUSPEND (removes all content), LIMIT (hides posts from non-followers), or NOOP (only rejects media/reports). Cannot block the instance's own domain.\n\nRBAC: requires Federation.Manage", "tags": [ "Admin Domain Blocks" ], "requestBody": { "description": "Domain block configuration", "content": { "application/json": { "examples": { "Block with LIMIT": { "value": { "domain": "spam.example", "publicComment": "Spam content", "state": "LIMIT", "rejectMedia": true } } }, "schema": { "$ref": "#/components/schemas/BlockDomainReq" } } }, "required": true }, "responses": { "200": { "description": "Domain successfully blocked", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "DomainAlreadyBlocked", "message": "The domain is already blocked" } } }, "description": "The domain is already blocked" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/domain-block/{domain}": { "delete": { "summary": "Unblock a domain", "description": "Removes a block from a domain to allow interactions with it again. This triggers background jobs to restore any suspended accounts and content from the domain.\n\nRBAC: requires Federation.Manage", "tags": [ "Admin Domain Blocks" ], "parameters": [ { "description": "Domain name to unblock", "example": "spam.example", "required": true, "name": "domain", "in": "path", "schema": { "pattern": "\\S", "type": "string" } } ], "responses": { "200": { "description": "Domain successfully unblocked", "content": { "application/json": { "schema": {} } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "DomainIsNotBlocked", "message": "The domain is not currently blocked" } } }, "description": "The domain is not currently blocked" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/email-allow": { "get": { "summary": "List email allowed domains", "description": "Retrieves a paginated list of all domains in the email allowlist.\n\nRBAC:\n- requires ALL of AdminSettings.Manage\n- requires ANY of AdminSettings.Read, AdminSettings.Manage", "tags": [ "Admin Email Allow List" ], "responses": { "200": { "description": "Successfully retrieved list of allowed domains", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AllowedDomain" } } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "RBACInsufficientPermissions", "message": "Insufficient permissions to perform this operation" } } }, "description": "Insufficient permissions to perform this operation" } }, "security": [ { "header": [] } ] }, "post": { "summary": "Add domain to email signup allowlist", "description": "Adds a domain to the email allowlist. Only emails from allowed domains can register when enabled.\n\nRBAC: requires AdminSettings.Manage", "tags": [ "Admin Email Allow List" ], "requestBody": { "description": "Domain to add to the email allowlist", "content": { "application/json": { "examples": { "Add domain": { "value": { "domain": "example.com" } } }, "schema": { "$ref": "#/components/schemas/AllowedDomainReq" } } }, "required": true }, "responses": { "200": { "description": "Domain successfully added to email allowlist", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "RBACInsufficientPermissions": { "description": "Insufficient permissions to perform this operation", "value": { "errorCode": "RBACInsufficientPermissions", "message": "Insufficient permissions to perform this operation" } }, "EmailBlocked": { "description": "The email address or domain is blocked from registration", "value": { "errorCode": "EmailBlocked", "message": "The email address or domain is blocked from registration" } } } } }, "description": "Forbidden" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EmailAlreadyAllowed", "message": "Email domain is already allowed for registration" } } }, "description": "Email domain is already allowed for registration" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/email-allow/{domain}": { "delete": { "summary": "Remove domain from email signup allowlist", "description": "Removes a domain from the email allowlist.\n\nRBAC: requires AdminSettings.Manage", "tags": [ "Admin Email Allow List" ], "parameters": [ { "description": "Domain name to remove from the allowlist", "example": "example.com", "required": true, "name": "domain", "in": "path", "schema": { "pattern": "\\S", "type": "string" } } ], "responses": { "200": { "description": "Domain successfully removed from email allowlist", "content": { "application/json": { "schema": {} } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "RBACInsufficientPermissions", "message": "Insufficient permissions to perform this operation" } } }, "description": "Insufficient permissions to perform this operation" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EmailAllowNotFound", "message": "Email domain allow entry not found" } } }, "description": "Email domain allow entry not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/email-block": { "get": { "summary": "List blocked email patterns", "description": "Retrieves the complete list of email patterns and domains that are blocked for signups. Includes the blocking reason and timestamps for each pattern. Patterns are shown in their normalized form.\n\nRBAC: requires Users.Moderate", "tags": [ "Admin Email Blocks" ], "responses": { "200": { "description": "Successfully retrieved list of blocked email patterns", "content": { "application/json": { "examples": { "Email blocks list": { "value": [ { "pattern": "spammer@example.com", "reason": "Known spam account", "createdAt": "2024-01-15T10:30:00Z" }, { "pattern": "spam-domain.com", "reason": "Spam domain", "createdAt": "2024-01-16T14:20:00Z" } ] } }, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EmailBlock" } } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "RBACInsufficientPermissions", "message": "Insufficient permissions to perform this operation" } } }, "description": "Insufficient permissions to perform this operation" } }, "security": [ { "header": [] } ] }, "post": { "summary": "Block email pattern", "description": "Creates a new email block that prevents signups from the specified email pattern. Supports blocking: specific emails (user@example.com) or domain patterns (example.com). Patterns are automatically normalized for consistency.\n\nRBAC: requires Users.Moderate", "tags": [ "Admin Email Blocks" ], "requestBody": { "description": "Email pattern and reason for blocking", "content": { "application/json": { "examples": { "Block specific email": { "value": { "pattern": "spammer@example.com", "reason": "Known spam account" } }, "Block domain": { "value": { "pattern": "spam-domain.com", "reason": "Spam domain" } } }, "schema": { "$ref": "#/components/schemas/BlockEmailRequest" } } }, "required": true }, "responses": { "200": { "description": "Email pattern successfully blocked", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "RBACInsufficientPermissions", "message": "Insufficient permissions to perform this operation" } } }, "description": "Insufficient permissions to perform this operation" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EmailAlreadyBlocked", "message": "The email pattern is already blocked" } } }, "description": "The email pattern is already blocked" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/email-block/{pattern}": { "delete": { "summary": "Unblock email pattern", "description": "Removes a block from an email pattern or domain to allow signups from it again. The pattern will be normalized before removal to match the stored format.\n\nRBAC: requires Users.Moderate", "tags": [ "Admin Email Blocks" ], "parameters": [ { "description": "Email pattern to unblock (will be normalized)", "examples": { "Specific email": { "value": "user@example.com" }, "Block domain": { "value": "example.com" } }, "required": true, "name": "pattern", "in": "path", "schema": { "pattern": "\\S", "type": "string" } } ], "responses": { "200": { "description": "Email pattern successfully unblocked", "content": { "application/json": { "schema": {} } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "RBACInsufficientPermissions", "message": "Insufficient permissions to perform this operation" } } }, "description": "Insufficient permissions to perform this operation" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EmailNotBlocked", "message": "The email pattern is not blocked" } } }, "description": "The email pattern is not blocked" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/embeddings/disable": { "put": { "summary": "Disable embeddings", "description": "Disables embedding generation while preserving the model configuration. Existing embeddings are kept. Re-enabling with the same model will only recalculate missing embeddings.\n\nRBAC: requires AdminSettings.Manage", "tags": [ "Embeddings Admin" ], "responses": { "200": { "description": "Embedding status after disabling", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingStatus" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/embeddings/enable": { "put": { "summary": "Enable embeddings", "description": "Enables embedding generation and starts recalculation. If no modelId is provided, uses the previously configured model. If modelId matches current model, only recalculates posts without embeddings. If modelId is different, clears all embeddings and recalculates all posts.\n\nRBAC: requires AdminSettings.Manage", "tags": [ "Embeddings Admin" ], "parameters": [ { "description": "Delay between batches in milliseconds (default: 100)", "name": "batchDelayMs", "in": "query", "schema": { "format": "int64", "type": "integer", "nullable": true }, "required": false }, { "description": "Model ID to use for embeddings. Uses current model if not provided.", "name": "modelId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "required": false } ], "responses": { "200": { "description": "Embedding status with recalculation info", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingStatus" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "EmbeddingModelNotEmbedding": { "description": "Model does not support embeddings", "value": { "errorCode": "EmbeddingModelNotEmbedding", "message": "Model does not support embeddings" } }, "EmbeddingModelDeprecated": { "description": "Embedding model is deprecated", "value": { "errorCode": "EmbeddingModelDeprecated", "message": "Embedding model is deprecated" } }, "EmbeddingModelRequired": { "description": "Model ID is required when enabling embeddings", "value": { "errorCode": "EmbeddingModelRequired", "message": "Model ID is required when enabling embeddings" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AIModelNotFound", "message": "AI model not found" } } }, "description": "AI model not found" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EmbeddingRecalculationInProgress", "message": "Embedding recalculation already in progress" } } }, "description": "Embedding recalculation already in progress" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/embeddings/estimate-cost": { "get": { "summary": "Estimate embedding cost", "description": "Estimates the cost of generating embeddings for posts. If no modelId is provided, uses the currently configured model. Returns whether this is a full recalculation (different model) or partial (only missing).\n\nRBAC: requires AdminSettings.Manage", "tags": [ "Embeddings Admin" ], "parameters": [ { "description": "Model ID to estimate cost for. Uses current model if not provided.", "name": "modelId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "required": false } ], "responses": { "200": { "description": "Cost estimate for embedding generation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingCostEstimate" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "EmbeddingNotConfigured": { "description": "Embeddings are not configured", "value": { "errorCode": "EmbeddingNotConfigured", "message": "Embeddings are not configured" } }, "EmbeddingModelNotEmbedding": { "description": "Model does not support embeddings", "value": { "errorCode": "EmbeddingModelNotEmbedding", "message": "Model does not support embeddings" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AIModelNotFound", "message": "AI model not found" } } }, "description": "AI model not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/embeddings/recalculation": { "delete": { "summary": "Cancel recalculation", "description": "Cancels any active embedding recalculation job. Returns the updated status showing the job as cancelled.\n\nRBAC: requires AdminSettings.Manage", "tags": [ "Embeddings Admin" ], "responses": { "200": { "description": "Embedding status after cancellation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingStatus" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/embeddings/status": { "get": { "summary": "Get embedding system status", "description": "Returns complete embedding system status including enabled state, model configuration, post statistics, and current recalculation progress if any.\n\nRBAC: requires AdminSettings.Manage", "tags": [ "Embeddings Admin" ], "responses": { "200": { "description": "Embedding system status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingStatus" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/fasp-remote/backfills": { "get": { "summary": "List FASP backfill requests", "description": "Lists all backfill requests on the FASP server.\n\nRBAC:\n- requires ANY of Federation.Read, Federation.Manage", "tags": [ "Admin FASP Remote" ], "responses": { "200": { "description": "Backfills retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaspBackfillsResponse" } } } } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/fasp-remote/blocklist": { "get": { "summary": "Get blocked domains", "description": "Retrieves the list of blocked domains from the FASP server.\n\nRBAC:\n- requires ANY of Federation.Read, Federation.Manage", "tags": [ "Admin FASP Remote" ], "responses": { "200": { "description": "Blocklist retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaspBlocklistResponse" } } } } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/fasp-remote/blocklist/{domain}": { "delete": { "summary": "Remove domain from blocklist", "description": "Removes a domain from the FASP blocklist. The action is audit-logged. Requires Federation.Manage permission.\n\nRBAC: requires Federation.Manage", "tags": [ "Admin FASP Remote" ], "parameters": [ { "description": "Domain to unblock", "required": true, "name": "domain", "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Domain removed from blocklist", "content": { "application/json": { "schema": {} } } } }, "security": [ { "header": [] } ] }, "post": { "summary": "Add domain to blocklist", "description": "Adds a domain to the FASP blocklist. Future content from this domain will be blocked. The action is audit-logged. Requires Federation.Manage permission.\n\nRBAC: requires Federation.Manage", "tags": [ "Admin FASP Remote" ], "parameters": [ { "description": "Domain to block", "required": true, "name": "domain", "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Domain added to blocklist", "content": { "application/json": { "schema": {} } } } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/fasp-remote/config": { "delete": { "summary": "Remove FASP remote configuration", "description": "Removes the FASP remote admin configuration, disconnecting from the remote FASP server. The operation is audit-logged. Requires Federation.Manage permission.\n\nRBAC: requires Federation.Manage", "tags": [ "Admin FASP Remote" ], "responses": { "200": { "description": "Configuration removed successfully", "content": { "application/json": { "schema": {} } } } }, "security": [ { "header": [] } ] }, "get": { "summary": "Get FASP remote configuration", "description": "Returns the current FASP remote admin configuration with masked token.\n\nRBAC:\n- requires ANY of Federation.Read, Federation.Manage", "tags": [ "Admin FASP Remote" ], "responses": { "200": { "description": "Configuration retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaspRemoteConfigResponse" } } } } }, "security": [ { "header": [] } ] }, "post": { "summary": "Configure FASP remote connection", "description": "Sets up the connection to a remote FASP server by providing the base URL and admin token. Validates the connection before saving the configuration. The base URL is normalized before storage. The operation is audit-logged. Requires Federation.Manage permission.\n\nRBAC: requires Federation.Manage", "tags": [ "Admin FASP Remote" ], "requestBody": { "description": "Configuration details", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigureFaspRemoteRequest" } } } }, "responses": { "200": { "description": "Configuration saved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaspRemoteConfigResponse" } } } }, "400": { "description": "Bad Request" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/fasp-remote/recover-state": { "post": { "summary": "Trigger global state recovery", "description": "Triggers global state recovery on the FASP server, rebuilding internal state from stored data. The action is audit-logged. Requires Federation.Manage permission.\n\nRBAC: requires Federation.Manage", "tags": [ "Admin FASP Remote" ], "responses": { "200": { "description": "State recovery triggered successfully", "content": { "application/json": { "schema": {} } } } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/fasp-remote/registrations": { "get": { "summary": "List server registrations", "description": "Lists server registrations on the FASP server with optional status filter.\n\nRBAC:\n- requires ANY of Federation.Read, Federation.Manage", "tags": [ "Admin FASP Remote" ], "parameters": [ { "description": "Sort field: createdAt, domain, email, status", "required": false, "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true } }, { "description": "Sort order: asc or desc", "required": false, "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true } }, { "description": "Filter by status (pending, approved, blocked)", "name": "status", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/FaspServerStatus" } ], "nullable": true }, "required": false } ], "responses": { "200": { "description": "Registrations retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaspRegistrationsResponse" } } } } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/fasp-remote/registrations/{serverId}/approve": { "post": { "summary": "Approve server registration", "description": "Approves a pending Fediverse server registration on the remote FASP server. The action is audit-logged with the server's domain. Requires Federation.Manage permission.\n\nRBAC: requires Federation.Manage", "tags": [ "Admin FASP Remote" ], "parameters": [ { "description": "Server ID to approve", "required": true, "name": "serverId", "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Server approved successfully", "content": { "application/json": { "schema": {} } } } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/fasp-remote/registrations/{serverId}/backfill": { "post": { "summary": "Trigger backfill for a server", "description": "Triggers a data backfill for a specific server registration on the FASP server. The action is audit-logged. Requires Federation.Manage permission.\n\nRBAC: requires Federation.Manage", "tags": [ "Admin FASP Remote" ], "parameters": [ { "description": "Server ID to backfill", "required": true, "name": "serverId", "in": "path", "schema": { "type": "string" } } ], "requestBody": { "description": "Backfill parameters", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackfillRequest1" } } } }, "responses": { "200": { "description": "Backfill triggered successfully", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/fasp-remote/registrations/{serverId}/block": { "post": { "summary": "Block server registration", "description": "Blocks a Fediverse server and its domain on the remote FASP server. Future registration attempts from this domain will be rejected. The action is audit-logged. Requires Federation.Manage permission.\n\nRBAC: requires Federation.Manage", "tags": [ "Admin FASP Remote" ], "parameters": [ { "description": "Server ID to block", "required": true, "name": "serverId", "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Server blocked successfully", "content": { "application/json": { "schema": {} } } } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/fasp-remote/registrations/{serverId}/decline": { "post": { "summary": "Decline server registration", "description": "Declines and permanently deletes a Fediverse server registration on the remote FASP server. The action is audit-logged. Requires Federation.Manage permission.\n\nRBAC: requires Federation.Manage", "tags": [ "Admin FASP Remote" ], "parameters": [ { "description": "Server ID to decline", "required": true, "name": "serverId", "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Server declined successfully", "content": { "application/json": { "schema": {} } } } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/fasp-remote/registrations/{serverId}/recover-state": { "post": { "summary": "Trigger state recovery for a server", "description": "Triggers state recovery for a specific server registration on the FASP server. The action is audit-logged. Requires Federation.Manage permission.\n\nRBAC: requires Federation.Manage", "tags": [ "Admin FASP Remote" ], "parameters": [ { "description": "Server ID to recover state for", "required": true, "name": "serverId", "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "State recovery triggered successfully", "content": { "application/json": { "schema": {} } } } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/fasp-remote/rotate-token/confirm": { "post": { "summary": "Confirm token rotation", "description": "Confirms token rotation with the verification code and updates the stored token.\n\nRBAC: requires Federation.Manage", "tags": [ "Admin FASP Remote" ], "requestBody": { "description": "Verification code", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenRotationConfirmRequest" } } } }, "responses": { "200": { "description": "Token rotated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenRotationConfirmResponse" } } } }, "400": { "description": "Bad Request" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/fasp-remote/rotate-token/request": { "post": { "summary": "Request admin token rotation", "description": "Requests a new admin token. A verification code will be sent to the configured admin email.\n\nRBAC: requires Federation.Manage", "tags": [ "Admin FASP Remote" ], "responses": { "200": { "description": "Rotation request sent successfully", "content": { "application/json": { "schema": {} } } } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/fasp-remote/stats": { "get": { "summary": "Get FASP server statistics", "description": "Retrieves statistics from the configured FASP server.\n\nRBAC:\n- requires ANY of Federation.Read, Federation.Manage", "tags": [ "Admin FASP Remote" ], "responses": { "200": { "description": "Statistics retrieved successfully", "content": { "application/json": { "schema": {} } } } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/fasp-remote/subscriptions": { "get": { "summary": "List FASP subscriptions", "description": "Lists all event subscriptions on the FASP server.\n\nRBAC:\n- requires ANY of Federation.Read, Federation.Manage", "tags": [ "Admin FASP Remote" ], "responses": { "200": { "description": "Subscriptions retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaspSubscriptionsResponse" } } } } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/fasp-remote/token/recover": { "post": { "summary": "Initiate admin token recovery", "description": "Initiates the admin token recovery flow by sending a verification code to the admin email. This proxies to the FASP server without the admin token (forgot-token flow). The action is audit-logged. Requires Federation.Manage permission.\n\nRBAC: requires Federation.Manage", "tags": [ "Admin FASP Remote" ], "requestBody": { "description": "Admin email for recovery", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenRecoverRequest" } } } }, "responses": { "200": { "description": "Recovery code sent to admin email", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/fasp-remote/token/recover/confirm": { "post": { "summary": "Confirm admin token recovery", "description": "Confirms admin token recovery with the verification code. This proxies to the FASP server without the admin token (forgot-token flow). The action is audit-logged. Requires Federation.Manage permission.\n\nRBAC: requires Federation.Manage", "tags": [ "Admin FASP Remote" ], "requestBody": { "description": "Email and verification code", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenRecoverConfirmRequest" } } } }, "responses": { "200": { "description": "Token recovery confirmed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenRotationConfirmResponse" } } } }, "400": { "description": "Bad Request" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/fasp-remote/update": { "get": { "summary": "Check for FASP server updates", "description": "Checks whether a newer version of the FASP server is available.\n\nRBAC:\n- requires ANY of Federation.Read, Federation.Manage", "tags": [ "Admin FASP Remote" ], "responses": { "200": { "description": "Update check completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaspUpdateCheckResponse" } } } } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/fasp/defaults": { "get": { "summary": "List default providers", "description": "Retrieves all default providers configured for each capability.\n\nRBAC:\n- requires ANY of Federation.Read, Federation.Manage", "tags": [ "Admin FASP" ], "responses": { "200": { "description": "Successfully retrieved default providers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaspDefaultsResponse" } } } } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/fasp/defaults/{capability}": { "put": { "summary": "Set default provider for capability", "description": "Sets the default FASP provider for a capability. The provider must be in ACCEPTED state and must support the specified capability. The change is audit-logged. Requires Federation.Manage permission.\n\nRBAC: requires Federation.Manage", "tags": [ "Admin FASP" ], "parameters": [ { "description": "Capability name", "required": true, "name": "capability", "in": "path", "schema": { "pattern": "\\S", "type": "string" } } ], "requestBody": { "description": "Provider ID to set as default", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetDefaultRequest" } } } }, "responses": { "200": { "description": "Default provider successfully set", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaspDefaultProviderView" } } } }, "400": { "description": "Bad Request" } }, "security": [ { "header": [] } ] }, "delete": { "summary": "Remove default provider for capability", "description": "Removes the default FASP provider assignment for a capability. After removal, no default provider will be used for this capability until a new one is set. The change is audit-logged. Requires Federation.Manage permission.\n\nRBAC: requires Federation.Manage", "tags": [ "Admin FASP" ], "parameters": [ { "description": "Capability name", "required": true, "name": "capability", "in": "path", "schema": { "pattern": "\\S", "type": "string" } } ], "responses": { "200": { "description": "Default provider successfully removed", "content": { "application/json": { "schema": {} } } } }, "security": [ { "header": [] } ] }, "get": { "summary": "Get default provider for capability", "description": "Retrieves the default provider for a specific capability.\n\nRBAC:\n- requires ANY of Federation.Read, Federation.Manage", "tags": [ "Admin FASP" ], "parameters": [ { "description": "Capability name", "required": true, "name": "capability", "in": "path", "schema": { "pattern": "\\S", "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved default provider", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaspDefaultProviderView" } } } } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/fasp/providers": { "get": { "summary": "List FASP providers", "description": "Retrieves a list of all FASP providers with optional state filtering.\n\nRBAC:\n- requires ANY of Federation.Read, Federation.Manage", "tags": [ "Admin FASP" ], "parameters": [ { "description": "Sort field: createdAt, name, state", "required": false, "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true } }, { "description": "Sort order: asc or desc", "required": false, "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true } }, { "description": "Filter by single state", "required": false, "name": "state", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/FaspProviderState" } ], "nullable": true } }, { "description": "Filter by multiple states", "required": false, "name": "states", "in": "query", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FaspProviderState" }, "nullable": true } } ], "responses": { "200": { "description": "Successfully retrieved list of FASP providers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaspProvidersResponse" } } } } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/fasp/providers/{faspId}": { "get": { "summary": "Get FASP provider by ID", "description": "Retrieves detailed information about a specific FASP provider.\n\nRBAC:\n- requires ANY of Federation.Read, Federation.Manage", "tags": [ "Admin FASP" ], "parameters": [ { "description": "FASP provider ID", "required": true, "name": "faspId", "in": "path", "schema": { "format": "int64", "type": "integer" } } ], "responses": { "200": { "description": "Successfully retrieved FASP provider", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaspProviderView" } } } } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/fasp/providers/{faspId}/accept": { "post": { "summary": "Accept FASP provider registration", "description": "Accepts a pending FASP provider registration, enabling it to provide capabilities to this instance. The state change is audit-logged. Requires Federation.Manage permission.\n\nRBAC: requires Federation.Manage", "tags": [ "Admin FASP" ], "parameters": [ { "description": "FASP provider ID", "required": true, "name": "faspId", "in": "path", "schema": { "format": "int64", "type": "integer" } } ], "responses": { "200": { "description": "Provider successfully accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaspProviderView" } } } } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/fasp/providers/{faspId}/backfill": { "post": { "summary": "Request backfill from FASP provider", "description": "Sends a backfill request to the specified FASP provider for the given content category. The remote provider will then deliver historical data back to this server. Requires Federation.Manage permission.\n\nRBAC: requires Federation.Manage", "tags": [ "Admin FASP" ], "parameters": [ { "description": "FASP provider ID", "required": true, "name": "faspId", "in": "path", "schema": { "format": "int64", "type": "integer" } } ], "requestBody": { "description": "Backfill request with category", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackfillRequest" } } } }, "responses": { "200": { "description": "Backfill request successfully sent", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/fasp/providers/{faspId}/block": { "post": { "summary": "Block FASP provider (stealth)", "description": "Blocks a FASP provider and removes it from default capability assignments. Future registration attempts from this provider will be silently ignored. The state change is audit-logged. Requires Federation.Manage permission.\n\nRBAC: requires Federation.Manage", "tags": [ "Admin FASP" ], "parameters": [ { "description": "FASP provider ID", "required": true, "name": "faspId", "in": "path", "schema": { "format": "int64", "type": "integer" } } ], "responses": { "200": { "description": "Provider successfully blocked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaspProviderView" } } } } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/fasp/providers/{faspId}/capabilities": { "post": { "summary": "Update FASP provider capabilities", "description": "Updates the capabilities of a FASP provider. Activates newly enabled capabilities on the remote provider and merges new capabilities with existing ones. Requires Federation.Manage permission.\n\nRBAC: requires Federation.Manage", "tags": [ "Admin FASP" ], "parameters": [ { "description": "FASP provider ID", "required": true, "name": "faspId", "in": "path", "schema": { "format": "int64", "type": "integer" } } ], "requestBody": { "description": "List of capabilities to update", "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Capability" } } } } }, "responses": { "200": { "description": "Capabilities successfully updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaspProviderView" } } } }, "400": { "description": "Bad Request" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/fasp/providers/{faspId}/decline": { "post": { "summary": "Decline FASP provider registration", "description": "Declines a FASP provider registration by permanently deleting the provider and all associated subscriptions, defaults, backfill requests, debug callbacks, and preview-card trends. The deletion is audit-logged. Requires Federation.Manage permission.\n\nRBAC: requires Federation.Manage", "tags": [ "Admin FASP" ], "parameters": [ { "description": "FASP provider ID", "required": true, "name": "faspId", "in": "path", "schema": { "format": "int64", "type": "integer" } } ], "responses": { "200": { "description": "Provider successfully declined and deleted", "content": { "application/json": { "schema": {} } } } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/federation": { "get": { "summary": "List federated domains", "description": "Retrieves a paginated list of all domains this instance is federated with, including user counts, availability status, and blocking state. Supports filtering by domain name, availability, and block status.", "tags": [ "Admin Federation Metrics" ], "parameters": [ { "description": "Filter by blocking state(s) - accepts single state or comma-separated list (LIMITED, SUSPENDED, NOOP)", "required": false, "name": "blockState", "in": "query", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DomainBlockState" }, "nullable": true } }, { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "Filter domains by name", "required": false, "name": "search", "in": "query", "schema": { "type": "string", "nullable": true } }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Filter only unavailable domains (7+ days not responding)", "required": false, "name": "unavailable", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "Filter only failing domains (1+ days not responding)", "required": false, "name": "warning", "in": "query", "schema": { "type": "boolean", "nullable": true } } ], "responses": { "200": { "description": "Successfully retrieved list of federated domains", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServersResult" } } } } }, "security": [] } }, "/api/v1/admin/federation/config": { "put": { "summary": "Update federation config", "description": "Atomically updates federation mode and allowlist. Optionally triggers a purge of all non-allowlisted content.\n\nRBAC: requires Federation.Manage", "tags": [ "Admin Federation Config" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FederationConfigRequest" } } }, "required": true }, "responses": { "200": { "description": "Federation config updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FederationConfigResponse" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ClientError", "message": "Invalid request from client" } } }, "description": "Invalid request from client" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] }, "get": { "summary": "Get federation config", "description": "Returns the current federation mode and the full allowlist.\n\nRBAC:\n- requires ANY of Federation.Read, Federation.Manage", "tags": [ "Admin Federation Config" ], "responses": { "200": { "description": "Federation config retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FederationConfigResponse" } } } } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/federation/metrics/operations": { "get": { "summary": "List tracked ActivityPub operations", "description": "Retrieves a list of all ActivityPub operations that have been tracked on this server. An operation combines the Activity type with the inner object type (if present). Examples: 'create-note' (Create activity with Note object), 'follow' (Follow activity), 'accept-follow' (Accept activity with Follow object), 'announce' (boost/reblog), 'undo-announce'.\n\nRBAC:\n- requires ANY of Federation.Read, Federation.Manage", "tags": [ "Admin Federation Metrics" ], "parameters": [ { "description": "Time window to check for operations (defaults to 24h)", "example": "ONE_HOUR", "required": false, "name": "window", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/WindowSize" } ], "nullable": true } } ], "responses": { "200": { "description": "Successfully retrieved list of tracked operations", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" }, "example": [ "follow", "accept-follow", "create-note", "announce", "undo-follow", "like", "undo-like" ] } } } } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/federation/metrics/running-average-single": { "get": { "summary": "Get metrics for specific operation", "description": "Returns sliding window metrics for a single ActivityPub operation, including count, average processing time, and percentiles. The metrics are calculated over the specified time window. Returns 404 if no data exists for the operation or the window has expired.\n\nRBAC:\n- requires ANY of Federation.Read, Federation.Manage", "tags": [ "Admin Federation Metrics" ], "parameters": [ { "description": "The ActivityPub operation to get metrics for", "example": "follow", "required": true, "name": "operation", "in": "query", "schema": { "type": "string" } }, { "description": "Time window for metric calculation (e.g., ONE_HOUR, SIX_HOURS, TWENTY_FOUR_HOURS)", "example": "ONE_HOUR", "required": true, "name": "window", "in": "query", "schema": { "$ref": "#/components/schemas/WindowSize" } } ], "responses": { "200": { "description": "Successfully retrieved operation metrics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlidingWindowMetrics" } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ResourceNotFound", "message": "The requested resource not found" } } }, "description": "The requested resource not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/federation/metrics/running-averages-all": { "get": { "summary": "Get metrics for multiple operations", "description": "Returns sliding window metrics for all ActivityPub operations or a filtered subset. Only includes operations that have active data within the specified time window. Each operation's metrics include count, average processing time, and percentiles.\n\nRBAC:\n- requires ANY of Federation.Read, Federation.Manage", "tags": [ "Admin Federation Metrics" ], "parameters": [ { "description": "Comma-separated list of specific operations to get metrics for. If omitted, returns all operations.", "example": "follow,create-note,announce", "required": false, "name": "operations", "in": "query", "schema": { "type": "array", "items": { "type": "string" }, "nullable": true } }, { "description": "Time window for metric calculation", "example": "TWENTY_FOUR_HOURS", "required": true, "name": "window", "in": "query", "schema": { "$ref": "#/components/schemas/WindowSize" } } ], "responses": { "200": { "description": "Map of operation names to their corresponding metrics", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/SlidingWindowMetrics" } } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/federation/mode": { "put": { "summary": "Change federation mode", "description": "Changes the federation mode. Switching to CLOSED purges all federated content. Switching from OPEN to LIMITED purges non-allowlisted content.\n\nRBAC: requires Federation.Manage", "tags": [ "Admin Federation Mode" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FederationModeRequest" } } }, "required": true }, "responses": { "200": { "description": "Federation mode changed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FederationModeResponse" } } } }, "400": { "description": "Bad Request" } }, "security": [ { "header": [] } ] }, "get": { "summary": "Get current federation mode", "description": "Returns the current federation mode of the instance\n\nRBAC:\n- requires ANY of Federation.Read, Federation.Manage", "tags": [ "Admin Federation Mode" ], "responses": { "200": { "description": "Current federation mode", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FederationModeResponse" } } } } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/federation/{domain}": { "get": { "summary": "Get domain federation details", "description": "Retrieves detailed federation statistics for a specific domain, including user counts, post counts, follower/following relationships, reports, availability status, and blocking information.\n\nRBAC:\n- requires ANY of Federation.Read, Federation.Manage", "tags": [ "Admin Federation Metrics" ], "parameters": [ { "description": "Domain name to get federation details for", "example": "mastodon.social", "required": true, "name": "domain", "in": "path", "schema": { "pattern": "\\S", "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved domain federation information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerInfo" } } } } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/feed/clear-user-feed": { "post": { "summary": "Clear user feed cache", "description": "Removes cached feed data from Redis for specified user(s). If no user is specified, clears all cached feeds. Use with caution as this will force feed regeneration on next access. Returns the number of Redis keys deleted.\n\nRBAC: requires Jobs.Manage", "tags": [ "Admin Feeds" ], "parameters": [ { "description": "User ID to clear feed cache for (default: all users)", "example": "us_01234567890abcdef", "required": false, "name": "userId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "Username to clear feed cache for (alternative to userId)", "example": "jane_doe", "required": false, "name": "username", "in": "query", "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "Number of Redis cache keys deleted", "content": { "application/json": { "schema": {} } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/feed/count-user-feed": { "get": { "summary": "Get exact cached post count for user feed", "description": "Returns the exact number of cached posts currently stored in Redis for a user's home feed. Requires exactly one of userId or username.\n\nRBAC: requires Jobs.Manage", "tags": [ "Admin Feeds" ], "parameters": [ { "description": "User ID to count cached feed posts for", "example": "us_01234567890abcdef", "required": false, "name": "userId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "Username to count cached feed posts for (alternative to userId)", "example": "john_doe", "required": false, "name": "username", "in": "query", "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "Exact cached post count for the selected user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserFeedCountResponse" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ConstraintViolation", "message": "A request parameter constraint was violated" } } }, "description": "A request parameter constraint was violated" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserNotFound", "message": "User not found" } } }, "description": "User not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/feed/diagnose": { "get": { "summary": "Diagnose user feed cache", "description": "Compares the Redis-cached home feed against the database-generated feed for one or all recently active users. Returns detailed comparison results including exact match status, order mismatches, and missing/extra post IDs. Use filters to skip exact matches or order mismatches for easier debugging. Requires Jobs.Manage permission.\n\nRBAC: requires Jobs.Manage", "tags": [ "Admin Feeds" ], "parameters": [ { "description": "Number of posts to compare from home feed against DB (default: 20)", "required": false, "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true } }, { "description": "Exclude feeds with exact match from results (default: true)", "required": false, "name": "skipExactMatch", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Omit full post ID lists from response to reduce payload size", "required": false, "name": "skipFull", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Exclude feeds with only order mismatches from results (default: true)", "required": false, "name": "skipOrderMismatch", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "User ID to diagnose feed for", "example": "us_01234567890abcdef", "required": false, "name": "userId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "Username to diagnose feed for (alternative to userId)", "example": "jane_doe", "required": false, "name": "username", "in": "query", "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "Map of userIds to their diagnosed results", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/FeedCompareResult" } } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/feed/metrics/global-all-operation": { "get": { "summary": "Get metrics across all operations", "description": "Retrieves global aggregated metrics across all feed operations within a time window.\n\nRBAC:\n- requires ANY of Jobs.Read, Jobs.Manage", "tags": [ "Admin Feeds" ], "parameters": [ { "description": "Time window for aggregation", "example": "24h", "required": true, "name": "window", "in": "query", "schema": { "$ref": "#/components/schemas/WindowSize" } } ], "responses": { "200": { "description": "List of global aggregated metrics for all operations", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GlobalAggregatedMetrics" } } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/feed/metrics/global-single": { "get": { "summary": "Get global aggregated metrics", "description": "Retrieves global aggregated feed performance metrics for a specific operation within a time window. Includes average times, total measurements, and user counts.\n\nRBAC:\n- requires ANY of Jobs.Read, Jobs.Manage", "tags": [ "Admin Feeds" ], "parameters": [ { "description": "Feed operation type (populate, merge, unmerge, redis, redisLex, cache, idsDb, db, add, remove)", "example": "populate", "required": true, "name": "operation", "in": "query", "schema": { "$ref": "#/components/schemas/FeedOperation" } }, { "description": "Time window for aggregation (TEN_MINUTES, ONE_HOUR, TWENTY_FOUR_HOURS or 10m, 1h, 24h)", "example": "ONE_HOUR", "required": true, "name": "window", "in": "query", "schema": { "$ref": "#/components/schemas/WindowSize" } } ], "responses": { "200": { "description": "Global aggregated metrics for the specified operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GlobalAggregatedMetrics" } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/feed/metrics/history": { "get": { "summary": "Get feed metrics history", "description": "Retrieves historical feed performance metrics for a specific operation and user. Returns a list of feed metrics ordered by timestamp.\n\nRBAC:\n- requires ANY of Jobs.Read, Jobs.Manage", "tags": [ "Admin Feeds" ], "parameters": [ { "description": "Maximum number of historical entries to return (default: 100)", "example": 100, "required": false, "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer" } }, { "description": "Feed operation type to filter metrics (e.g., populate, merge, redis, cache)", "example": "populate", "required": true, "name": "operation", "in": "query", "schema": { "$ref": "#/components/schemas/FeedOperation" } }, { "description": "User ID to retrieve metrics for", "example": "us_01234567890abcdef", "required": true, "name": "userId", "in": "query", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "Feed metrics history retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FeedMetrics" } } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/feed/metrics/history/all": { "get": { "summary": "Get comprehensive feed metrics", "description": "Retrieves complete feed metrics history for a user across all operations. Returns a map where keys are operation types and values are lists of feed metrics.\n\nRBAC:\n- requires ANY of Jobs.Read, Jobs.Manage", "tags": [ "Admin Feeds" ], "parameters": [ { "description": "Maximum number of historical entries per operation (default: 100)", "example": 100, "required": false, "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer" } }, { "description": "User ID to retrieve comprehensive metrics for", "example": "us_01234567890abcdef", "required": true, "name": "userId", "in": "query", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "Map of operation types to feed metrics lists", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/feed/metrics/running-average-single": { "get": { "summary": "Get user running average", "description": "Retrieves the running average performance metrics for a specific user and operation within a sliding time window.\n\nRBAC:\n- requires ANY of Jobs.Read, Jobs.Manage", "tags": [ "Admin Feeds" ], "parameters": [ { "description": "Feed operation to analyze", "example": "populate", "required": true, "name": "operation", "in": "query", "schema": { "$ref": "#/components/schemas/FeedOperation" } }, { "description": "User ID to analyze", "example": "us_01234567890abcdef", "required": true, "name": "userId", "in": "query", "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Sliding window size for averaging", "example": "1h", "required": true, "name": "window", "in": "query", "schema": { "$ref": "#/components/schemas/WindowSize" } } ], "responses": { "200": { "description": "Running average metrics for the specified operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlidingWindowMetrics" } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/feed/metrics/running-averages-all": { "get": { "summary": "Get all user running averages", "description": "Retrieves running average performance metrics for a specific user across all feed operations.\n\nRBAC:\n- requires ANY of Jobs.Read, Jobs.Manage", "tags": [ "Admin Feeds" ], "parameters": [ { "description": "User ID to analyze", "example": "us_01234567890abcdef", "required": true, "name": "userId", "in": "query", "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Sliding window size for averaging", "example": "10m", "required": true, "name": "window", "in": "query", "schema": { "$ref": "#/components/schemas/WindowSize" } } ], "responses": { "200": { "description": "Map of operations to running average metrics", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/feed/metrics/slowest-operations": { "get": { "summary": "Identify slowest feed operations", "description": "Analyzes and ranks feed operations by their average execution time across all users. Helps identify performance bottlenecks.\n\nRBAC:\n- requires ANY of Jobs.Read, Jobs.Manage", "tags": [ "Admin Feeds" ], "parameters": [ { "description": "Maximum number of operations to return (default: 10)", "example": 10, "required": false, "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer" } }, { "description": "Time window for analysis", "example": "1h", "required": true, "name": "window", "in": "query", "schema": { "$ref": "#/components/schemas/WindowSize" } } ], "responses": { "200": { "description": "Slowest operations data with analysis results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlowestOperationsResponse" } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/feed/metrics/slowest-users": { "get": { "summary": "Identify users with performance issues", "description": "Analyzes and identifies users experiencing the slowest feed operation times. Can analyze a specific operation or aggregate across all operations.\n\nRBAC:\n- requires ANY of Jobs.Read, Jobs.Manage", "tags": [ "Admin Feeds" ], "parameters": [ { "description": "Maximum number of users to return (default: 10)", "example": 10, "required": false, "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer" } }, { "description": "Optional specific operation to analyze", "example": "populate", "required": false, "name": "operation", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/FeedOperation" } ], "nullable": true } }, { "description": "Time window for analysis", "example": "1h", "required": true, "name": "window", "in": "query", "schema": { "$ref": "#/components/schemas/WindowSize" } } ], "responses": { "200": { "description": "Slowest users data with detailed performance analysis", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlowestUsersResponse" } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/feed/metrics/slowest-users-all": { "get": { "summary": "Get performance leaderboards for all operations", "description": "Retrieves performance leaderboards for all feed operations. Returns a map of operations to ranked user lists.\n\nRBAC:\n- requires ANY of Jobs.Read, Jobs.Manage", "tags": [ "Admin Feeds" ], "parameters": [ { "description": "Maximum number of users per operation (default: 10)", "example": 10, "required": false, "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer" } }, { "description": "Sort in descending order - true for fastest users first, false for slowest users first (default: true)", "example": true, "required": false, "name": "sortDesc", "in": "query", "schema": { "type": "boolean" } }, { "description": "Time window for performance analysis", "example": "24h", "required": true, "name": "window", "in": "query", "schema": { "$ref": "#/components/schemas/WindowSize" } } ], "responses": { "200": { "description": "Map of operations to lists of users ranked by performance", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/feed/metrics/slowest-users-single": { "get": { "summary": "Get performance leaderboard", "description": "Retrieves a ranked list of users by their feed operation performance for a specific operation. Can show either slowest or fastest users based on sort order.\n\nRBAC:\n- requires ANY of Jobs.Read, Jobs.Manage", "tags": [ "Admin Feeds" ], "parameters": [ { "description": "Maximum number of users to return (default: 10)", "example": 10, "required": false, "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer" } }, { "description": "Feed operation to analyze", "example": "redis", "required": true, "name": "operation", "in": "query", "schema": { "$ref": "#/components/schemas/FeedOperation" } }, { "description": "Sort in descending order - true for fastest users first, false for slowest users first (default: true)", "example": true, "required": false, "name": "sortDesc", "in": "query", "schema": { "type": "boolean" } }, { "description": "Time window for performance analysis", "example": "1h", "required": true, "name": "window", "in": "query", "schema": { "$ref": "#/components/schemas/WindowSize" } } ], "responses": { "200": { "description": "List of users ranked by performance metrics", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserPerformanceMetrics" } } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/feed/metrics/summary": { "get": { "summary": "Get comprehensive metrics summary", "description": "Generates a complete summary of feed performance metrics across all operations, including totals and averages.\n\nRBAC:\n- requires ANY of Jobs.Read, Jobs.Manage", "tags": [ "Admin Feeds" ], "parameters": [ { "description": "Include user counts in summary (may impact performance, default: false)", "example": false, "required": false, "name": "includeUserCounts", "in": "query", "schema": { "type": "boolean" } }, { "description": "Time window for metrics aggregation", "example": "1h", "required": true, "name": "window", "in": "query", "schema": { "$ref": "#/components/schemas/WindowSize" } } ], "responses": { "200": { "description": "Comprehensive metrics summary with operation metrics and totals", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricsSummary" } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/feed/metrics/user-count-all": { "get": { "summary": "Get comprehensive user counts", "description": "Returns user counts for all feed operations within the time window. Returns a map structure for comprehensive analysis.\n\nRBAC:\n- requires ANY of Jobs.Read, Jobs.Manage", "tags": [ "Admin Feeds" ], "parameters": [ { "description": "Time window to count active users within", "example": "24h", "required": true, "name": "window", "in": "query", "schema": { "$ref": "#/components/schemas/WindowSize" } } ], "responses": { "200": { "description": "Map of operations to user counts", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "format": "int64", "type": "integer" } } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/feed/metrics/user-count-single": { "get": { "summary": "Get active user count", "description": "Returns the count of unique users who performed a specific feed operation within the time window.\n\nRBAC:\n- requires ANY of Jobs.Read, Jobs.Manage", "tags": [ "Admin Feeds" ], "parameters": [ { "description": "Feed operation to count users for", "example": "populate", "required": true, "name": "operation", "in": "query", "schema": { "$ref": "#/components/schemas/FeedOperation" } }, { "description": "Time window to count active users within", "example": "1h", "required": true, "name": "window", "in": "query", "schema": { "$ref": "#/components/schemas/WindowSize" } } ], "responses": { "200": { "description": "User count data for the specified operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserCountResponse" } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/feed/regenerate-user-feed": { "post": { "summary": "Regenerate user feed cache", "description": "Forces regeneration of cached feed data for specified user(s). If no user is specified, regenerates feeds for all recently active users (signed in within the last period). Returns the number of feeds queued for regeneration.\n\nRBAC: requires Jobs.Manage", "tags": [ "Admin Feeds" ], "parameters": [ { "description": "Clear before", "required": false, "name": "clear", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "User ID to regenerate feed for", "example": "us_01234567890abcdef", "required": false, "name": "userId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "Username to regenerate feed for (alternative to userId)", "example": "john_doe", "required": false, "name": "username", "in": "query", "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "Number of user feeds queued for regeneration", "content": { "application/json": { "schema": {} } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserNotFound", "message": "User not found" } } }, "description": "User not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/groups/search": { "get": { "summary": "Search for groups", "description": "Administrative search for groups with multiple filter criteria. Filters include member user/account linkage, group name, domain, privacy, visibility, and join mode. Returns groups regardless of visibility/privacy.\n\nRBAC:\n- requires ANY of Users.Read, Users.Manage", "tags": [ "Admin Groups" ], "parameters": [ { "description": "Account ID of any group member", "required": false, "name": "accountId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "Display name of the group", "required": false, "name": "displayName", "in": "query", "schema": { "type": "string", "nullable": true } }, { "description": "Group domain (remote groups)", "required": false, "name": "domain", "in": "query", "schema": { "type": "string", "nullable": true } }, { "description": "Member account email", "required": false, "name": "email", "in": "query", "schema": { "type": "string", "nullable": true } }, { "description": "Group join mode", "required": false, "name": "joinMode", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/GroupJoinMode" } ], "nullable": true } }, { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "Group privacy", "required": false, "name": "privacy", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/GroupPrivacy" } ], "nullable": true } }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "User ID of any group member", "required": false, "name": "userId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "Group username (groupname)", "required": false, "name": "username", "in": "query", "schema": { "type": "string", "nullable": true } }, { "description": "Group visibility", "required": false, "name": "visibility", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/GroupVisibility" } ], "nullable": true } } ], "responses": { "200": { "description": "List of groups matching filters", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Group" } } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/groups/user/{userId}": { "get": { "summary": "Get groups by user roles", "description": "Retrieves all groups where the specified user holds at least one of the given roles (e.g., owner, admin, moderator). Requires Users.Read or Users.Manage permission.\n\nRBAC:\n- requires ANY of Users.Read, Users.Manage", "tags": [ "Admin Groups" ], "parameters": [ { "description": "The user ID to query groups for", "required": true, "name": "userId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "List of group roles to filter by", "required": true, "name": "roles", "in": "query", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } ], "responses": { "200": { "description": "List of groups with user's role information", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Group" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ResourceNotFound", "message": "The requested resource not found" } } }, "description": "The requested resource not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/groups/{accountId}": { "get": { "summary": "Get groups owned by an account", "description": "Retrieves all groups where any user belonging to the specified account is the owner. Supports pagination. Requires Users.Read or Users.Manage permission.\n\nRBAC:\n- requires ANY of Users.Read, Users.Manage", "tags": [ "Admin Groups" ], "parameters": [ { "description": "The account id", "required": true, "name": "accountId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Group" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ResourceNotFound", "message": "The requested resource not found" } } }, "description": "The requested resource not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/groups/{groupId}/channels": { "get": { "summary": "Get all channels for a group", "description": "Retrieves all channels belonging to a group. Channels are sub-users within a group that organize content into topics. Requires Users.Read or Users.Manage permission.\n\nRBAC:\n- requires ANY of Users.Read, Users.Manage", "tags": [ "Admin Groups" ], "parameters": [ { "description": "Group ID", "required": true, "name": "groupId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "List of group channels", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/User" } } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/groups/{groupId}/events": { "get": { "summary": "Get group events", "description": "Retrieves all events associated with a group, skipping visibility checks. Optionally includes translations. Requires Users.Read or Users.Manage permission.\n\nRBAC:\n- requires ANY of Users.Read, Users.Manage", "tags": [ "Admin Groups" ], "parameters": [ { "description": "Group ID", "required": true, "name": "groupId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "Include translation", "required": false, "name": "withTranslation", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Language" } ], "nullable": true } } ], "responses": { "200": { "description": "List of group-owned events", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/impersonate": { "get": { "summary": "Impersonate a user", "description": "Allows a service to impersonate a user by their username. This will return a token that can be used to act on behalf the user's account. Only bots can be impersonated, not regular users.\n\nRBAC:\n- requires ALL of Users.Manage, Users.Impersonate", "tags": [ "Admin Accounts" ], "parameters": [ { "description": "Username of the bot user to impersonate. Must be a bot account, not a regular user. Case-insensitive.", "required": true, "name": "username", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Session key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Token" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserIsNotBot", "message": "The user is not a bot" } } }, "description": "The user is not a bot" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserNotFound", "message": "User not found" } } }, "description": "User not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/link-service": { "get": { "summary": "Get current remote link preview service configuration", "description": "Returns the configured remote link preview service base URL if set; otherwise null. Requires AdminSettings.Manage permission.\n\nRBAC: requires AdminSettings.Manage", "tags": [ "Admin Remote Link Service" ], "responses": { "200": { "description": "Current configuration returned", "content": { "application/json": { "schema": {} } } } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/link-service/configure": { "post": { "summary": "Configure remote link preview service", "description": "Validates the provided base URL, checks provider capabilities at /provider_info endpoint, and saves the configuration if the provider supports 'link_preview' capability. Requires AdminSettings.Manage permission.\n\nRBAC: requires AdminSettings.Manage", "tags": [ "Admin Remote Link Service" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigureRequest" } } }, "required": true }, "responses": { "200": { "description": "Configuration saved successfully", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ClientError", "message": "Invalid request from client" } } }, "description": "Invalid request from client" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/posts/delete": { "post": { "summary": "Delete posts", "description": "Deletes posts for moderation purposes. Can delete a single post by its ID or all posts associated with a report. The deletion is permanent and includes creating audit logs and report notes. When deleting via reportId, all posts referenced in the report are deleted and the report is marked as actioned.\n\nRBAC: requires Reports.Manage", "tags": [ "Admin Posts" ], "requestBody": { "description": "Post deletion request. Must provide either postId (for single post) or reportId (for all posts in report). The reason is required and will be recorded in the audit log.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostDelete" } } }, "required": true }, "responses": { "200": { "description": "Post(s) successfully deleted and audit logged", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "PostNotFound": { "description": "The specified post not found", "value": { "errorCode": "PostNotFound", "message": "The specified post not found" } }, "ReportNotFound": { "description": "The specified report not found", "value": { "errorCode": "ReportNotFound", "message": "The specified report not found" } }, "ReportPostsNotFound": { "description": "No posts found in the specified report", "value": { "errorCode": "ReportPostsNotFound", "message": "No posts found in the specified report" } } } } }, "description": "Not Found" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/purge": { "delete": { "summary": "Permanently purge an account from the system", "description": "Force-deletes an account and all associated data, even if previously soft-deleted. This operation bypasses normal deletion safeguards and completely removes all traces of the account from the system. Use with extreme caution as this action is irreversible and cannot be recovered. Administrators cannot purge their own account.\n\nRBAC: requires Users.Manage", "tags": [ "Admin Accounts" ], "parameters": [ { "description": "Id of the account to purge", "required": true, "name": "id", "in": "query", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "Account successfully purged from the system", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AdminDeleteAccWithSelf", "message": "Cannot delete self" } } }, "description": "Cannot delete self" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AccountNotFound", "message": "Account not found" } } }, "description": "Account not found" }, "500": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AccountIsNotRemoved", "message": "Failed to remove the account" } } }, "description": "Failed to remove the account" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/regenerate-keys": { "post": { "summary": "Regenerate cryptographic keys for a user", "description": "Regenerates the Ed25519 cryptographic keys for a specified user. This is used for federation security and ActivityPub signatures. Can identify the user by username or user ID. The old keys are invalidated and new keys are generated immediately. Remote servers will be notified of the key change through federation protocols.\n\nRBAC: requires Users.Manage", "tags": [ "Admin Accounts" ], "parameters": [ { "description": "User ID whose cryptographic keys to regenerate. Must be a valid USER type ID. Either username or userId must be provided.", "required": false, "name": "userId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "Username of the user whose keys to regenerate. Case-insensitive. Either username or userId must be provided.", "required": false, "name": "username", "in": "query", "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "Keys successfully regenerated", "content": { "text/plain": {} } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AdminNeedUsernameOrId": { "description": "Either a username or user ID must be provided", "value": { "errorCode": "AdminNeedUsernameOrId", "message": "Either a username or user ID must be provided" } }, "ClientError": { "description": "Invalid request from client", "value": { "errorCode": "ClientError", "message": "Invalid request from client" } } } } }, "description": "Bad Request" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AccountNotFound", "message": "Account not found" } } }, "description": "Account not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/regenerate-keys-all": { "post": { "summary": "Regenerate cryptographic keys for all users", "description": "Initiates a background job to regenerate Ed25519 cryptographic keys for all users in the system. This is typically used for security updates or key rotation policies. The operation runs asynchronously and processes users in batches. Returns a job ID that can be used to track progress. Default batch size is used unless specified.\n\nRBAC: requires Users.Manage", "tags": [ "Admin Accounts" ], "parameters": [ { "name": "batch", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false } ], "responses": { "200": { "description": "Background job initiated, returns job UUID", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/UUID" } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/release-username": { "post": { "summary": "Release a username for reuse", "description": "Administratively releases a username, making it available for new user registrations. This is typically used after account deletions or username changes to free up desirable usernames. The operation immediately makes the username available in the system.\n\nRBAC: requires Users.Manage", "tags": [ "Admin Accounts" ], "parameters": [ { "description": "username", "required": true, "name": "username", "in": "query", "schema": { "pattern": "\\S", "type": "string" } } ], "responses": { "200": { "description": "Username successfully released", "content": { "text/plain": {} } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/reports/eligible-assignees": { "get": { "summary": "Get users eligible to be assigned reports", "description": "Returns a list of users who can be assigned to moderate reports. This includes users with report-management permissions who are not suspended or limited. Use this to populate assignment dropdowns in the moderation UI.\n\nRBAC:\n- requires ANY of Reports.Read, Reports.Manage, GroupReports.Read, GroupReports.Manage", "tags": [ "Reports" ], "parameters": [ { "description": "Group scope. Omit for server scope", "name": "scope", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "required": false } ], "responses": { "200": { "description": "List of eligible assignees", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/User" } } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/reports/list": { "get": { "summary": "List moderation reports with filtering", "description": "Retrieves a paginated list of moderation reports. Can filter by target ID, target type (post/user/group), or resolution status. Supports pagination for large result sets. Reports include details about the target content, assigned moderator, and any notes.\n\nRBAC:\n- requires ANY of Reports.Read, Reports.Manage, GroupReports.Read, GroupReports.Manage", "tags": [ "Reports" ], "parameters": [ { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "Filter by resolution status. true = open reports only, false = resolved reports only, omit = all reports. Note: This is a convenience filter - open=true includes 'OPEN' and 'UNDER_REVIEW' states, open=false includes 'DISMISSED' and 'RESOLVED' states.", "required": false, "name": "open", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Group scope. Omit for server scope", "name": "scope", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "required": false }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Filter by report state (OPEN, UNDER_REVIEW, DISMISSED, RESOLVED)", "required": false, "name": "state", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/ReportState" } ], "nullable": true } }, { "description": "Filter by specific target ID (post, user, or group)", "required": false, "name": "targetId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } ], "responses": { "200": { "description": "Paginated list of reports", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportsPaginatedResponse" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ConstraintViolation", "message": "A request parameter constraint was violated" } } }, "description": "A request parameter constraint was violated" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/reports/reported-groups": { "get": { "summary": "List reported groups with aggregated report data", "description": "Returns groups that have been reported, grouped by group with aggregate statistics. Each entry includes the group, a representative report, open/total counts, and latest dates. Group reports are always global scope (handled by server admins).\n\nRBAC:\n- requires ANY of Reports.Read, Reports.Manage", "tags": [ "Reports" ], "parameters": [ { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "Filter by resolution status. true = groups with open reports, false = groups with all reports resolved, omit = all reported groups", "required": false, "name": "open", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Sort by: TARGET_UPDATED (group update date), REPORTED_DATE (latest report), LAST_NOTE_DATE (latest admin note)", "required": false, "name": "sortBy", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/ReportSortBy" } ], "nullable": true } }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } ], "responses": { "200": { "description": "Paginated list of reported groups", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportedGroupsPaginatedResponse" } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/reports/reported-posts": { "get": { "summary": "List reported posts with aggregated report data", "description": "Returns posts that have been reported, grouped by post with aggregate statistics. Each entry includes the post, a representative report, open/total report counts, and latest dates. This view is designed for moderators to efficiently review reported content by post.\n\nRBAC:\n- requires ANY of Reports.Read, Reports.Manage, GroupReports.Read, GroupReports.Manage", "tags": [ "Reports" ], "parameters": [ { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "Filter by resolution status. true = posts with open reports, false = posts with all reports resolved, omit = all reported posts", "required": false, "name": "open", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Group scope. Omit for server scope", "name": "scope", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "required": false }, { "description": "Sort by: TARGET_UPDATED (post update date), REPORTED_DATE (latest report), LAST_NOTE_DATE (latest admin note)", "required": false, "name": "sortBy", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/ReportSortBy" } ], "nullable": true } }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ], "responses": { "200": { "description": "Paginated list of reported posts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportedPostsPaginatedResponse" } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/reports/reported-users": { "get": { "summary": "List reported users with aggregated report data", "description": "Returns users that have been reported directly (not via their posts), grouped by user with aggregate statistics. Each entry includes the user, a representative report, open/total counts, and latest dates. This view is designed for moderators to review user-level reports.\n\nRBAC:\n- requires ANY of Reports.Read, Reports.Manage, GroupReports.Read, GroupReports.Manage", "tags": [ "Reports" ], "parameters": [ { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "Filter by resolution status. true = users with open reports, false = users with all reports resolved, omit = all reported users", "required": false, "name": "open", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Group scope. Omit for server scope", "name": "scope", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "required": false }, { "description": "Sort by: TARGET_UPDATED (user update date), REPORTED_DATE (latest report), LAST_NOTE_DATE (latest admin note)", "required": false, "name": "sortBy", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/ReportSortBy" } ], "nullable": true } }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } ], "responses": { "200": { "description": "Paginated list of reported users", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportedUsersPaginatedResponse" } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/reports/{reportId}": { "get": { "summary": "Get specific report details", "description": "Retrieves complete details of a specific moderation report including the target content (post/user/group), assigned moderator, resolution status, comments from reporters, and all associated moderator notes. Use this to review a report before taking action.\n\nRBAC:\n- requires ANY of Reports.Read, Reports.Manage, GroupReports.Read, GroupReports.Manage", "tags": [ "Reports" ], "parameters": [ { "name": "reportId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Group scope. Omit for server scope", "name": "scope", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "required": false } ], "responses": { "200": { "description": "Report details successfully retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Report" } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ReportNotFound", "message": "The specified report not found" } } }, "description": "The specified report not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/reports/{reportId}/add-note": { "post": { "summary": "Add moderation note to report", "description": "Adds an internal moderation note to the report. Notes are used to document investigation findings, actions taken, or communication between moderators. Each note is timestamped and attributed to the adding moderator. Notes are visible only to moderators and not to reporters or reported users.\n\nRBAC:\n- requires ANY of Reports.Manage, GroupReports.Manage", "tags": [ "Reports" ], "parameters": [ { "name": "reportId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "name": "note", "in": "query", "schema": { "type": "string" }, "required": true }, { "description": "Group scope. Omit for server scope", "name": "scope", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "required": false } ], "responses": { "200": { "description": "Note successfully added to report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Report" } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ReportNotFound", "message": "The specified report not found" } } }, "description": "The specified report not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/reports/{reportId}/assign": { "post": { "summary": "Assign report to a moderator", "description": "Assigns the report to a specific moderator for handling. When a user is assigned, the report state changes to 'under_review'. Pass null userId to unassign (returns to 'open' state). This helps coordinate moderation efforts by showing who is actively investigating.\n\nRBAC:\n- requires ANY of Reports.Manage, GroupReports.Manage", "tags": [ "Reports" ], "parameters": [ { "name": "reportId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Group scope. Omit for server scope", "name": "scope", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "required": false }, { "name": "userId", "in": "query", "schema": { "$ref": "#/components/schemas/TypeId" }, "required": true } ], "responses": { "200": { "description": "Report successfully assigned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Report" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ConstraintViolation", "message": "A request parameter constraint was violated" } } }, "description": "A request parameter constraint was violated" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ReportNotFound", "message": "The specified report not found" } } }, "description": "The specified report not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/reports/{reportId}/delete": { "delete": { "summary": "Permanently delete a report", "description": "Permanently removes a report and all its comments from the system. This should only be used for invalid or spam reports. For legitimate reports that have been addressed, use resolve or dismiss instead to maintain moderation history. This action cannot be undone.\n\nRBAC:\n- requires ANY of Reports.Manage, GroupReports.Manage", "tags": [ "Reports" ], "parameters": [ { "name": "reportId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Group scope. Omit for server scope", "name": "scope", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "required": false } ], "responses": { "200": { "description": "Report successfully deleted from the system", "content": { "text/plain": {} } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ReportNotFound", "message": "The specified report not found" } } }, "description": "The specified report not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/reports/{reportId}/dismiss": { "post": { "summary": "Dismiss report without action", "description": "Dismisses a report, indicating that no action is warranted (e.g., false report, not against rules). The current user is recorded as having dismissed the report. This sets the state to 'dismissed' and records actionTakenAt timestamp.\n\nRBAC:\n- requires ANY of Reports.Manage, GroupReports.Manage", "tags": [ "Reports" ], "parameters": [ { "name": "reportId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Group scope. Omit for server scope", "name": "scope", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "required": false } ], "responses": { "200": { "description": "Report successfully dismissed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Report" } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ReportNotFound", "message": "The specified report not found" } } }, "description": "The specified report not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/reports/{reportId}/remove-note": { "post": { "summary": "Remove moderation note from report", "description": "Removes a specific moderation note from the report by its index position. Use this to correct mistakes or remove outdated information. Notes are zero-indexed, so the first note has index 0. Only valid indices are accepted.\n\nRBAC:\n- requires ANY of Reports.Manage, GroupReports.Manage", "tags": [ "Reports" ], "parameters": [ { "name": "reportId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "name": "index", "in": "query", "schema": { "format": "int32", "type": "integer" }, "required": true }, { "description": "Group scope. Omit for server scope", "name": "scope", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "required": false } ], "responses": { "200": { "description": "Note successfully removed from report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Report" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ConstraintViolation", "message": "A request parameter constraint was violated" } } }, "description": "A request parameter constraint was violated" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ReportNotFound", "message": "The specified report not found" } } }, "description": "The specified report not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/reports/{reportId}/reopen": { "post": { "summary": "Reopen a closed report", "description": "Reopens a previously resolved or dismissed report for further investigation. This sets the state back to 'open', clears assignment, and clears action taken fields. Useful when initial resolution was insufficient or new information becomes available.\n\nRBAC:\n- requires ANY of Reports.Manage, GroupReports.Manage", "tags": [ "Reports" ], "parameters": [ { "name": "reportId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Group scope. Omit for server scope", "name": "scope", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "required": false } ], "responses": { "200": { "description": "Report successfully reopened", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Report" } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ReportNotFound", "message": "The specified report not found" } } }, "description": "The specified report not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/reports/{reportId}/resolve": { "post": { "summary": "Mark report as resolved", "description": "Marks a report as resolved, indicating that action has been taken (e.g., content removed, user warned). The current user is recorded as the moderator who resolved the report. This sets the state to 'resolved' and records actionTakenAt timestamp.\n\nRBAC:\n- requires ANY of Reports.Manage, GroupReports.Manage", "tags": [ "Reports" ], "parameters": [ { "name": "reportId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Group scope. Omit for server scope", "name": "scope", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "required": false } ], "responses": { "200": { "description": "Report successfully resolved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Report" } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ReportNotFound", "message": "The specified report not found" } } }, "description": "The specified report not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/reports/{reportId}/unassign": { "post": { "summary": "Unassign report from any moderator", "description": "Removes the assignment of this report from any moderator, making it available for other moderators to claim. The report state returns to 'open' if it was 'under_review'. Use when unable to complete investigation or when transferring to another moderator.\n\nRBAC:\n- requires ANY of Reports.Manage, GroupReports.Manage", "tags": [ "Reports" ], "parameters": [ { "name": "reportId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Group scope. Omit for server scope", "name": "scope", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "required": false } ], "responses": { "200": { "description": "Report successfully unassigned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Report" } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ReportNotFound", "message": "The specified report not found" } } }, "description": "The specified report not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/restart-ap-delivery": { "post": { "summary": "Restart ActivityPub delivery for a domain", "description": "Marks the specified domain as available and restarts federation delivery. Use when a domain was previously marked unavailable due to repeated delivery failures and you want to force-resume communication. Requires Federation.Manage permission.\n\nRBAC: requires Federation.Manage", "tags": [ "Admin ActivityPub" ], "parameters": [ { "description": "Remote domain to restart delivery for", "example": "mastodon.social", "required": true, "name": "domain", "in": "query", "schema": { "pattern": "\\S", "type": "string" } } ], "responses": { "200": { "description": "Delivery restarted successfully", "content": { "application/json": { "schema": {} } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/search": { "get": { "summary": "Search for users", "description": "Performs an administrative search for users with multiple filter criteria. Can search by user ID, account ID, username, domain, display name, state, email, IP address, country, or role. Supports mixed search across username, display name, and email simultaneously. Results include detailed user information and support pagination and sorting. IP addresses are matched exactly, and country codes should use ISO 3166-1 alpha-2 format.\n\nRBAC: requires Users.Manage", "tags": [ "Admin Accounts" ], "parameters": [ { "description": "Account id", "required": false, "name": "accountId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "Country", "required": false, "name": "country", "in": "query", "schema": { "type": "string", "nullable": true } }, { "description": "Display name", "required": false, "name": "displayName", "in": "query", "schema": { "type": "string", "nullable": true } }, { "description": "Domain", "required": false, "name": "domain", "in": "query", "schema": { "type": "string", "nullable": true } }, { "description": "Email", "required": false, "name": "email", "in": "query", "schema": { "type": "string", "nullable": true } }, { "description": "Entity type to filter by (USER, BOT, APPLICATION, GROUP_CHANNEL). Defaults to USER.", "required": false, "name": "entityType", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/EntityType" } ], "nullable": true } }, { "description": "IP address", "required": false, "name": "ip", "in": "query", "schema": { "type": "string", "nullable": true } }, { "description": "Result kind: CHANNEL for only global channels, USER for only users, ALL for both. Default ALL", "required": false, "name": "kind", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Kind" } ], "nullable": true } }, { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "Role", "required": false, "name": "role", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/RoleId" } ], "nullable": true } }, { "description": "Mixed search across username, display name or email", "required": false, "name": "search", "in": "query", "schema": { "type": "string", "nullable": true } }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "State", "required": false, "name": "state", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/UserState" } ], "nullable": true } }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "userId", "required": false, "name": "userId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "Username", "required": false, "name": "username", "in": "query", "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "List of users, number of users found and total number of users on server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchDetails" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "SortingError", "message": "Sort field is not supported" } } }, "description": "Sort field is not supported" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/signup_requests/approve/{hash}": { "put": { "summary": "Approve a signup request", "description": "Approves a pending signup request and creates the user account. Sends a welcome email to the user upon successful account creation. If username conflicts occur, sends an alternative email prompting the user to choose a different username. If email/phone conflicts occur, the request is deleted as the user likely already has an account. The operation is logged for audit purposes.\n\nRBAC: requires Signups.Manage", "tags": [ "Admin Signup Requests" ], "parameters": [ { "name": "hash", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Signup request approved and account created successfully", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "SendEmailError", "message": "Failed to send email" } } }, "description": "Failed to send email" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AccountNotFound", "message": "Account not found" } } }, "description": "Account not found" }, "500": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AccountCreationError", "message": "Failed to create the account" } } }, "description": "Failed to create the account" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/signup_requests/delete/{hash}": { "delete": { "summary": "Delete a signup request", "description": "Permanently removes a signup request from the system without notifying the user. Use this for cleaning up invalid, duplicate, or spam requests. Unlike rejection, this does not send any notification to the applicant. The request cannot be recovered after deletion.\n\nRBAC: requires Signups.Manage", "tags": [ "Admin Signup Requests" ], "parameters": [ { "name": "hash", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Signup request successfully deleted", "content": { "application/json": { "schema": {} } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/signup_requests/list": { "get": { "summary": "List pending signup requests", "description": "Retrieves a paginated list of signup requests awaiting admin approval. Can filter by email address, request hash, or originating IP address. Results are sorted by creation date (newest first) by default. Only shows requests at the ADMIN approval step.\n\nRBAC:\n- requires ANY of Signups.Read, Signups.Manage", "tags": [ "Admin Signup Requests" ], "parameters": [ { "description": "Filter by email address. Returns requests with matching email.", "required": false, "name": "email", "in": "query", "schema": { "type": "string", "nullable": true } }, { "description": "Filter by request hash. Returns the specific request with this hash.", "required": false, "name": "hash", "in": "query", "schema": { "type": "string", "nullable": true } }, { "description": "Filter by IP address. Returns requests from this originating IP.", "required": false, "name": "ip", "in": "query", "schema": { "type": "string", "nullable": true } }, { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } ], "responses": { "200": { "description": "Paginated list of signup requests with total count", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignupRequestResult" } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/signup_requests/reject/{hash}": { "put": { "summary": "Reject a signup request", "description": "Rejects a pending signup request and permanently removes it from the queue. Sends a rejection email to the applicant with an optional reason for the rejection. This action is final and the user would need to submit a new signup request. The rejection is logged for audit purposes.\n\nRBAC: requires Signups.Manage", "tags": [ "Admin Signup Requests" ], "parameters": [ { "name": "hash", "in": "path", "required": true, "schema": { "type": "string" } }, { "description": "Optional reason for rejection to include in the notification email. Helps users understand why their request was denied.", "required": false, "name": "reason", "in": "query", "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "Signup request rejected and user notified", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "SendEmailError", "message": "Failed to send email" } } }, "description": "Failed to send email" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AccountNotFound", "message": "Account not found" } } }, "description": "Account not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/uploads/jobs/queue/{queueName}": { "get": { "summary": "List upload processing jobs in queue", "description": "Retrieves upload processing jobs from a specific queue (submitted, in_progress, or completed). Used to monitor the status of async upload processing tasks such as image resizing, video encoding, or thumbnail generation. Supports filtering by upload type and sorting by various fields like submission time or processing duration.\n\nRBAC: requires Uploads.Read", "tags": [ "Admin Uploads" ], "parameters": [ { "description": "Queue name to retrieve jobs from (submitted, in_progress, completed)", "required": true, "name": "queueName", "in": "path", "schema": { "type": "string" } }, { "description": "Maximum number of jobs to return. Default is 10.", "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer" } }, { "description": "Pagination offset for results. Default is 0.", "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to sort by (submission_time, processing_duration, etc.)", "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order direction. Values: 'asc' or 'desc'. Default is ascending.", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Filter by upload type (IMAGE, VIDEO, AUDIO, DOCUMENT)", "name": "uploadType", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false } ], "responses": { "200": { "description": "Upload jobs list retrieved successfully", "content": { "application/json": { "schema": { "description": "List of the upload jobs", "required": [ "list", "total", "totalJobs" ], "type": "object", "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/ProcessJob" } }, "total": { "format": "int32", "description": "Total number of jobs in the queue.", "type": "integer" }, "totalJobs": { "format": "int32", "description": "Total number of jobs in the queue with specified filter.", "type": "integer" } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "UploadJobsInvalidSortingFields": { "description": "Invalid sorting fields for upload jobs. Correct values are: SubmissionTime, TimeInQueue, FileSize", "value": { "errorCode": "UploadJobsInvalidSortingFields", "message": "Invalid sorting fields for upload jobs. Correct values are: SubmissionTime, TimeInQueue, FileSize" } }, "UploadJobsInvalidOffset": { "description": "Invalid offset for upload jobs. Must be greater or equal to 0", "value": { "errorCode": "UploadJobsInvalidOffset", "message": "Invalid offset for upload jobs. Must be greater or equal to 0" } } } } }, "description": "Bad Request" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/uploads/jobs/summary": { "get": { "summary": "Get upload job queue summaries", "description": "Retrieves summary statistics for all upload processing queues, showing counts of jobs in submitted, in-progress, and completed states. Provides a high-level overview of the upload processing system's current workload and performance. Useful for monitoring system health and identifying processing bottlenecks.\n\nRBAC: requires Uploads.Read", "tags": [ "Admin Uploads" ], "responses": { "200": { "description": "Queue summaries retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/QueueSummary" } } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/uploads/search": { "get": { "summary": "Search user uploads with filters", "description": "Searches and retrieves uploads for a specific user with optional filtering by upload type (IMAGE, VIDEO, AUDIO, DOCUMENT) and tags (Avatar, Header, Post, etc.). Supports pagination for large result sets. Returns upload metadata including file information, processing status, and associated tags.\n\nRBAC: requires Uploads.Read", "tags": [ "Admin Uploads" ], "parameters": [ { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Filter by upload tag (Avatar, Header, Post, etc.). Omit to include all tags.", "required": false, "name": "tag", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/UploadsTags" } ], "nullable": true } }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "Filter by upload type (IMAGE, VIDEO, AUDIO, DOCUMENT). Omit to include all types.", "required": false, "name": "uploadType", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/UploadType" } ], "nullable": true } }, { "description": "User ID whose uploads to search. Must be a valid USER type TypeId.", "required": true, "name": "userId", "in": "query", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "Upload search results retrieved successfully", "content": { "application/json": { "schema": { "description": "List uploads result", "required": [ "list", "total" ], "type": "object", "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/Upload" } }, "total": { "format": "int64", "type": "integer" } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "InvalidUploadListRequest", "message": "Invalid request to list uploads. Provide a valid userId, pagination, and a supported order field (createdAt or size)." } } }, "description": "Invalid request to list uploads. Provide a valid userId, pagination, and a supported order field (createdAt or size)." }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/uploads/storage/{userId}": { "get": { "summary": "Get user storage information", "description": "Retrieves detailed storage usage information for a specific user, including total storage used, file counts by type, and storage limits. Useful for monitoring user storage consumption and enforcing quotas.\n\nRBAC: requires Uploads.Read", "tags": [ "Admin Uploads" ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "User storage information retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserStorage" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/uploads/{uploadId}/logs": { "get": { "summary": "Get upload processing logs", "description": "Retrieves detailed processing logs for a specific upload, including workflow steps, timestamps, and any errors encountered during processing. Useful for debugging upload issues. Requires Uploads.Read permission.\n\nRBAC: requires Uploads.Read", "tags": [ "Admin Uploads" ], "parameters": [ { "description": "Upload ID. Must be a valid UPLOAD type TypeId.", "required": true, "name": "uploadId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "Upload logs retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UploadLog" } } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/user/change-state": { "post": { "summary": "Update user moderation state", "description": "Changes the moderation state of a user (e.g., ACTIVE, SUSPENDED, LIMITED). This affects what actions the user can perform on the platform. When suspending a user, their content may be hidden and followers on remote servers are notified. When unsuspending, the user's content is restored and remote servers are updated. Administrators cannot change their own state. Changes are logged for audit purposes and can be linked to moderation reports.\n\nRBAC: requires Users.Manage", "tags": [ "Admin Accounts" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeUserState" } } }, "required": true }, "responses": { "200": { "description": "User state successfully updated", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "UserCannotBlockSelf": { "description": "A user cannot block themselves", "value": { "errorCode": "UserCannotBlockSelf", "message": "A user cannot block themselves" } }, "UserNotUpdated": { "description": "Failed to update the user", "value": { "errorCode": "UserNotUpdated", "message": "Failed to update the user" } } } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserNotFound", "message": "User not found" } } }, "description": "User not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/user/change-state-bulk": { "post": { "summary": "Bulk update user moderation states", "description": "Changes the moderation state for multiple users in a single optimized operation. Performs one bulk DB update, submits jobs in batches for users transitioning to or from SUSPENDED, and distributes updates without per-user queries.\n\nRBAC: requires Users.Manage", "tags": [ "Admin Accounts" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeUserStateBulk" } } }, "required": true }, "responses": { "200": { "description": "Bulk user states updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeUsersStateResult" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserCannotBlockSelf", "message": "A user cannot block themselves" } } }, "description": "A user cannot block themselves" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ReportNotFound", "message": "The specified report not found" } } }, "description": "The specified report not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/admin/user/{userId}": { "get": { "summary": "Retrieve detailed user information by ID", "description": "Fetches comprehensive details about a specific user including their account association, profile information, roles, state, statistics, and activity data. Requires either Users.Read or Users.Manage permission.\n\nRBAC:\n- requires ALL of Users.Manage\n- requires ANY of Users.Read, Users.Manage", "tags": [ "Admin Accounts" ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "User details successfully retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserDetails" } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserNotFound", "message": "User not found" } } }, "description": "User not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/ai-agents": { "get": { "summary": "List bots", "description": "Returns bots within the specified scope.\n\nRBAC:\n- requires ANY of AIAgents.Read, AIAgents.Manage, GroupAIAgents.Read, GroupAIAgents.Manage", "tags": [ "AI Agents" ], "parameters": [ { "description": "Scope: 'global' or group TypeId", "required": true, "name": "scope", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Array of bots", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AIAgent" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "RBACInsufficientPermissions": { "description": "Insufficient permissions to perform this operation", "value": { "errorCode": "RBACInsufficientPermissions", "message": "Insufficient permissions to perform this operation" } }, "NotGroupMember": { "description": "The user must be a member of the group", "value": { "errorCode": "NotGroupMember", "message": "The user must be a member of the group" } } } } }, "description": "Forbidden" } }, "security": [ { "header": [] } ] }, "post": { "summary": "Create a bot", "description": "Creates a new bot along with its configuration profile.\n Use scope='global' for platform-wide bots (requires AIAgents.Manage) or a group TypeId for\n group-scoped bots (requires GroupAIAgents.Manage).\n\nRBAC:\n- requires ANY of AIAgents.Manage, GroupAIAgents.Manage", "tags": [ "AI Agents" ], "parameters": [ { "description": "Scope: 'global' or group TypeId", "required": true, "name": "scope", "in": "query", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIAgentCreate" } } }, "required": true }, "responses": { "200": { "description": "Created bot with profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIAgent" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ConstraintViolation", "message": "A request parameter constraint was violated" } } }, "description": "A request parameter constraint was violated" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "RBACInsufficientPermissions": { "description": "Insufficient permissions to perform this operation", "value": { "errorCode": "RBACInsufficientPermissions", "message": "Insufficient permissions to perform this operation" } }, "NotGroupMember": { "description": "The user must be a member of the group", "value": { "errorCode": "NotGroupMember", "message": "The user must be a member of the group" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "GroupChannelNotFound", "message": "The specified group channel not found" } } }, "description": "The specified group channel not found" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "UserNameIsReserved": { "description": "The username is reserved and cannot be used", "value": { "errorCode": "UserNameIsReserved", "message": "The username is reserved and cannot be used" } }, "UserNameExists": { "description": "The username is already in use", "value": { "errorCode": "UserNameExists", "message": "The username is already in use" } } } } }, "description": "Conflict" }, "500": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserCreationError", "message": "Failed to create the user" } } }, "description": "Failed to create the user" } }, "security": [ { "header": [] } ] } }, "/api/v1/ai-agents/jobs/results": { "post": { "summary": "Report AI agent job execution result", "description": "Service callback endpoint to report job status, usage counters, and token usage.\n\nRBAC: requires AIAgents.UpdateStats", "tags": [ "AI Agents" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIAgentJobResultCallback" } } }, "required": true }, "responses": { "200": { "description": "Result callback accepted", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "RBACInsufficientPermissions", "message": "Insufficient permissions to perform this operation" } } }, "description": "Insufficient permissions to perform this operation" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AIAgentProfileNotFound", "message": "AI agent profile not found" } } }, "description": "AI agent profile not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/ai-agents/posts": { "get": { "summary": "Retrieve posts for AI agents", "description": "Returns posts for AI agents. If ownerId is missing, retrieves posts from the global space (group_id is null) with PUBLIC visibility. Supports pagination and optional 'since' timestamp to fetch posts strictly newer than the given timestamp.\n\nRBAC: requires AIAgents.PostsRead", "tags": [ "AI Agents" ], "parameters": [ { "description": "Maximum number of items to return (page size). Defaults to 100.", "required": false, "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true } }, { "description": "Owner id. Accepts a group channel or user id", "required": false, "name": "ownerId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "Timestamp to retrieve posts strictly newer than this (by createdAt)", "required": false, "name": "since", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true } }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ], "responses": { "200": { "description": "Posts list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/ai-agents/{agentId}": { "get": { "summary": "Retrieve a bot", "description": "Returns a bot by id within the specified scope.\n\nRBAC:\n- requires ANY of AIAgents.Read, AIAgents.Manage, GroupAIAgents.Read, GroupAIAgents.Manage", "tags": [ "AI Agents" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Scope: 'global' or group TypeId", "required": true, "name": "scope", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Bot with profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIAgent" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "RBACInsufficientPermissions": { "description": "Insufficient permissions to perform this operation", "value": { "errorCode": "RBACInsufficientPermissions", "message": "Insufficient permissions to perform this operation" } }, "NotGroupMember": { "description": "The user must be a member of the group", "value": { "errorCode": "NotGroupMember", "message": "The user must be a member of the group" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AIAgentProfileNotFound", "message": "AI agent profile not found" } } }, "description": "AI agent profile not found" } }, "security": [ { "header": [] } ] }, "delete": { "summary": "Delete a bot", "description": "Deletes a bot and its profile within the specified scope. This operation is irreversible.\n\nRBAC:\n- requires ANY of AIAgents.Manage, GroupAIAgents.Manage", "tags": [ "AI Agents" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Scope: 'global' or group TypeId", "required": true, "name": "scope", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Bot deleted", "content": { "application/json": { "schema": {} } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "RBACInsufficientPermissions": { "description": "Insufficient permissions to perform this operation", "value": { "errorCode": "RBACInsufficientPermissions", "message": "Insufficient permissions to perform this operation" } }, "NotGroupMember": { "description": "The user must be a member of the group", "value": { "errorCode": "NotGroupMember", "message": "The user must be a member of the group" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AIAgentProfileNotFound", "message": "AI agent profile not found" } } }, "description": "AI agent profile not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/ai-agents/{agentId}/disable": { "put": { "summary": "Disable a bot", "description": "Disables an enabled bot within the specified scope.\n\nRBAC:\n- requires ANY of AIAgents.Manage, GroupAIAgents.Manage", "tags": [ "AI Agents" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Scope: 'global' or group TypeId", "required": true, "name": "scope", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Bot disabled", "content": { "application/json": { "schema": {} } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "RBACInsufficientPermissions": { "description": "Insufficient permissions to perform this operation", "value": { "errorCode": "RBACInsufficientPermissions", "message": "Insufficient permissions to perform this operation" } }, "NotGroupMember": { "description": "The user must be a member of the group", "value": { "errorCode": "NotGroupMember", "message": "The user must be a member of the group" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AIAgentProfileNotFound", "message": "AI agent profile not found" } } }, "description": "AI agent profile not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/ai-agents/{agentId}/enable": { "put": { "summary": "Enable a bot", "description": "Enables a bot within the specified scope. Optional version query parameter sets that version as current before enabling.\n\nRBAC:\n- requires ANY of AIAgents.Manage, GroupAIAgents.Manage", "tags": [ "AI Agents" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Scope: 'global' or group TypeId", "required": true, "name": "scope", "in": "query", "schema": { "type": "string" } }, { "description": "Optional profile version to set as current before enabling", "required": false, "name": "version", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true } } ], "responses": { "200": { "description": "Bot enabled", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AIAgentModelRequired": { "description": "Bot model is required before enabling the bot", "value": { "errorCode": "AIAgentModelRequired", "message": "Bot model is required before enabling the bot" } }, "AIAgentToolsRequired": { "description": "Bot tools are required before enabling the bot", "value": { "errorCode": "AIAgentToolsRequired", "message": "Bot tools are required before enabling the bot" } }, "AIAgentTriggersRequired": { "description": "Bot triggers are required before enabling the bot", "value": { "errorCode": "AIAgentTriggersRequired", "message": "Bot triggers are required before enabling the bot" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "RBACInsufficientPermissions": { "description": "Insufficient permissions to perform this operation", "value": { "errorCode": "RBACInsufficientPermissions", "message": "Insufficient permissions to perform this operation" } }, "NotGroupMember": { "description": "The user must be a member of the group", "value": { "errorCode": "NotGroupMember", "message": "The user must be a member of the group" } }, "AIModelNotEnabledInScope": { "description": "AI model is not enabled for this scope", "value": { "errorCode": "AIModelNotEnabledInScope", "message": "AI model is not enabled for this scope" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AIAgentProfileNotFound": { "description": "AI agent profile not found", "value": { "errorCode": "AIAgentProfileNotFound", "message": "AI agent profile not found" } }, "AIAgentVersionNotFound": { "description": "AI agent profile version not found", "value": { "errorCode": "AIAgentVersionNotFound", "message": "AI agent profile version not found" } } } } }, "description": "Not Found" } }, "security": [ { "header": [] } ] } }, "/api/v1/ai-agents/{agentId}/profile": { "put": { "summary": "Update AI agent profile", "description": "Creates or replaces AI agent configuration profile within the specified scope. Payload may reset modelId to null and tools/triggers to empty lists; uploadIds controls attached documents. Budgets/rate limits can be set to null to remove limits.\n\nRBAC:\n- requires ANY of AIAgents.Manage, GroupAIAgents.Manage", "tags": [ "AI Agents" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Scope: 'global' or group TypeId", "required": true, "name": "scope", "in": "query", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIAgentProfileUpdate" } } }, "required": true }, "responses": { "200": { "description": "Bot updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIAgentProfileVersionCreated" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ConstraintViolation", "message": "A request parameter constraint was violated" } } }, "description": "A request parameter constraint was violated" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "RBACInsufficientPermissions": { "description": "Insufficient permissions to perform this operation", "value": { "errorCode": "RBACInsufficientPermissions", "message": "Insufficient permissions to perform this operation" } }, "NotGroupMember": { "description": "The user must be a member of the group", "value": { "errorCode": "NotGroupMember", "message": "The user must be a member of the group" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AIAgentProfileNotFound": { "description": "AI agent profile not found", "value": { "errorCode": "AIAgentProfileNotFound", "message": "AI agent profile not found" } }, "GroupChannelNotFound": { "description": "The specified group channel not found", "value": { "errorCode": "GroupChannelNotFound", "message": "The specified group channel not found" } } } } }, "description": "Not Found" } }, "security": [ { "header": [] } ] } }, "/api/v1/ai-agents/{agentId}/user": { "put": { "summary": "Update AI agent user profile", "description": "Updates the bot user profile fields using the same update rules as UsersResource. Access is controlled by AI agents manage permissions and scope; agent self-auth is not required.\n\nRBAC:\n- requires ANY of AIAgents.Manage, GroupAIAgents.Manage", "tags": [ "AI Agents" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Scope: 'global' or group TypeId", "required": true, "name": "scope", "in": "query", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserUpdate" } } }, "required": true }, "responses": { "200": { "description": "Bot user profile updated", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "TimezoneCannotUpdate": { "description": "Failed to update the timezone", "value": { "errorCode": "TimezoneCannotUpdate", "message": "Failed to update the timezone" } }, "UserLocationAutoUpdateNeedGeo": { "description": "geo coding is required when autoUpdate is true", "value": { "errorCode": "UserLocationAutoUpdateNeedGeo", "message": "geo coding is required when autoUpdate is true" } }, "CantConvertUserToBot": { "description": "The user can't be converted to bot", "value": { "errorCode": "CantConvertUserToBot", "message": "The user can't be converted to bot" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "RBACInsufficientPermissions": { "description": "Insufficient permissions to perform this operation", "value": { "errorCode": "RBACInsufficientPermissions", "message": "Insufficient permissions to perform this operation" } }, "NotGroupMember": { "description": "The user must be a member of the group", "value": { "errorCode": "NotGroupMember", "message": "The user must be a member of the group" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AIAgentProfileNotFound", "message": "AI agent profile not found" } } }, "description": "AI agent profile not found" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserNameIsReserved", "message": "The username is reserved and cannot be used" } } }, "description": "The username is reserved and cannot be used" } }, "security": [ { "header": [] } ] } }, "/api/v1/ai-agents/{agentId}/versions": { "get": { "summary": "List AI agent profile versions", "description": "Returns immutable profile version history for an agent.\n\nRBAC:\n- requires ANY of AIAgents.Read, AIAgents.Manage, GroupAIAgents.Read, GroupAIAgents.Manage", "tags": [ "AI Agents" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Scope: 'global' or group TypeId", "required": true, "name": "scope", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Version history records", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AIAgentProfile" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "RBACInsufficientPermissions": { "description": "Insufficient permissions to perform this operation", "value": { "errorCode": "RBACInsufficientPermissions", "message": "Insufficient permissions to perform this operation" } }, "NotGroupMember": { "description": "The user must be a member of the group", "value": { "errorCode": "NotGroupMember", "message": "The user must be a member of the group" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AIAgentProfileNotFound", "message": "AI agent profile not found" } } }, "description": "AI agent profile not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/ai-agents/{agentId}/versions/{version}": { "get": { "summary": "Get AI agent version", "description": "Returns a full AI agent object with the requested immutable profile version.\n\nRBAC:\n- requires ANY of AIAgents.Read, AIAgents.Manage, GroupAIAgents.Read, GroupAIAgents.Manage", "tags": [ "AI Agents" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "name": "version", "in": "path", "required": true, "schema": { "format": "int32", "type": "integer" } }, { "description": "Scope: 'global' or group TypeId", "required": true, "name": "scope", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Bot with requested profile version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIAgent" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "RBACInsufficientPermissions": { "description": "Insufficient permissions to perform this operation", "value": { "errorCode": "RBACInsufficientPermissions", "message": "Insufficient permissions to perform this operation" } }, "NotGroupMember": { "description": "The user must be a member of the group", "value": { "errorCode": "NotGroupMember", "message": "The user must be a member of the group" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AIAgentProfileNotFound": { "description": "AI agent profile not found", "value": { "errorCode": "AIAgentProfileNotFound", "message": "AI agent profile not found" } }, "AIAgentVersionNotFound": { "description": "AI agent profile version not found", "value": { "errorCode": "AIAgentVersionNotFound", "message": "AI agent profile version not found" } } } } }, "description": "Not Found" } }, "security": [ { "header": [] } ] } }, "/api/v1/ai-models": { "get": { "summary": "Search AI models", "description": "Search and filter AI models with pagination. Returns models matching all specified criteria\nwith scoped enablement state.\n\n**Searching for embedding models with specific vector dimension:**\n\nFor embedding models, the `maxOutputTokens` field in the model limits represents the embedding vector dimension\n(e.g., 1536 for OpenAI ada-002, 3072 for text-embedding-3-large).\n\nTo find embedding models with a specific vector size, combine:\n- `capabilities=EMBEDDINGS` - filter to embedding models only\n- `minMaxOutputTokens` and `maxMaxOutputTokens` set to the desired dimension\n\nExample: To find embedding models with 1536-dimensional vectors:\n`?scope=global&capabilities=EMBEDDINGS&minMaxOutputTokens=1536&maxMaxOutputTokens=1536`\n\nRBAC:\n- requires ANY of AIModels.Read, GroupAIModels.Read", "tags": [ "AI Models" ], "parameters": [ { "description": "Supported sortBy values for this endpoint: model_name, provider_name, family, release_date, enabled", "in": "query", "name": "sortBy", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Filter by built-in tools (comma-separated: WEB_SEARCH,CODE_EXECUTION,etc)", "name": "builtInTools", "in": "query", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AIBuiltInTool" }, "nullable": true }, "required": false }, { "description": "Filter by capabilities (comma-separated: CHAT,TOOLS,VISION,etc)", "name": "capabilities", "in": "query", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AIModelCapabilityFilter" }, "nullable": true }, "required": false }, { "description": "Filter by deprecated status", "name": "deprecated", "in": "query", "schema": { "type": "boolean", "nullable": true }, "required": false }, { "description": "Filter by enablement state in the requested scope (true=enabled only, false=disabled/unconfigured, omit for all)", "name": "enabled", "in": "query", "schema": { "type": "boolean", "nullable": true }, "required": false }, { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "Maximum context window size", "name": "maxContextWindow", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "Maximum input price per 1M tokens (USD)", "name": "maxInputPrice", "in": "query", "schema": { "format": "double", "type": "number", "nullable": true }, "required": false }, { "description": "Maximum max output tokens (for embedding models, this is the vector dimension)", "name": "maxMaxOutputTokens", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "Maximum output price per 1M tokens (USD)", "name": "maxOutputPrice", "in": "query", "schema": { "format": "double", "type": "number", "nullable": true }, "required": false }, { "description": "Minimum context window size", "name": "minContextWindow", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "Minimum max output tokens (for embedding models, this is the vector dimension)", "name": "minMaxOutputTokens", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "Filter by modalities (comma-separated: TEXT,IMAGE,AUDIO,VIDEO,PDF)", "name": "modalities", "in": "query", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AIModality" }, "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "Filter by open weights status", "name": "openWeights", "in": "query", "schema": { "type": "boolean", "nullable": true }, "required": false }, { "description": "Filter by provider ID", "name": "providerId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "required": false }, { "description": "Scope: 'global' or group TypeId", "required": true, "name": "scope", "in": "query", "schema": { "type": "string" } }, { "description": "Search in name, family, and external ID (case-insensitive partial match)", "name": "search", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } ], "responses": { "200": { "description": "Paginated list of models with scoped state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIModelPagedResponse" } } } } }, "security": [ { "header": [] } ] } }, "/api/v1/ai-models/{modelId}": { "get": { "summary": "Get an AI model", "description": "Returns a single AI model by ID with scoped enablement state.\n\nRBAC:\n- requires ANY of AIModels.Read, GroupAIModels.Read", "tags": [ "AI Models" ], "parameters": [ { "name": "modelId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Scope: 'global' or group TypeId", "required": false, "name": "scope", "in": "query", "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "Model details with scoped state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIModel" } } } }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ResourceNotFound", "message": "The requested resource not found" } } }, "description": "The requested resource not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/ai-models/{modelId}/agents": { "get": { "summary": "List agents using scoped model configuration", "description": "Returns AI agents that currently reference this model's scoped configuration in the given scope.\n\nRBAC:\n- requires ANY of AIModels.Manage, GroupAIModels.Manage", "tags": [ "AI Models" ], "parameters": [ { "name": "modelId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Scope: 'global' or group TypeId", "required": true, "name": "scope", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of AI agents using this scoped model configuration", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AIAgent" } } } } } }, "security": [ { "header": [] } ] } }, "/api/v1/ai-models/{modelId}/configure": { "delete": { "summary": "Remove scoped model configuration", "description": "Removes scoped model enablement/configuration row for the model in the specified scope.\n\nRBAC:\n- requires ANY of AIModels.Manage, GroupAIModels.Manage", "tags": [ "AI Models" ], "parameters": [ { "name": "modelId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Scope: 'global' or group TypeId", "required": true, "name": "scope", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Scoped model configuration removed successfully", "content": { "application/json": { "schema": {} } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ResourceNotFound", "message": "The requested resource not found" } } }, "description": "The requested resource not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/ai-models/{modelId}/disable": { "put": { "summary": "Disable a model in a scope", "description": "Disables a model in the specified scope.\n\nRBAC:\n- requires ANY of AIModels.Manage, GroupAIModels.Manage", "tags": [ "AI Models" ], "parameters": [ { "name": "modelId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Scope: 'global' or group TypeId", "required": true, "name": "scope", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Model disabled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIModel" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AIModelNotFound", "message": "AI model not found" } } }, "description": "AI model not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/ai-models/{modelId}/enable": { "put": { "summary": "Enable a model in a scope", "description": "Enables a model for use in the specified scope. Requires the provider to be configured with a valid API key in that scope.\n\nRBAC:\n- requires ANY of AIModels.Manage, GroupAIModels.Manage", "tags": [ "AI Models" ], "parameters": [ { "name": "modelId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Scope: 'global' or group TypeId", "required": true, "name": "scope", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Model enabled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIModel" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AIProviderNotConfigured": { "description": "AI provider is not configured for this scope", "value": { "errorCode": "AIProviderNotConfigured", "message": "AI provider is not configured for this scope" } }, "AIProviderMissingApiKey": { "description": "AI provider API key is missing or invalid", "value": { "errorCode": "AIProviderMissingApiKey", "message": "AI provider API key is missing or invalid" } }, "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AIModelNotFound", "message": "AI model not found" } } }, "description": "AI model not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/ai-models/{modelId}/migration-path": { "get": { "summary": "Get model migration path", "description": "Returns the chain of models from the given model to the final active successor. Catalog-only, no scope needed.\n\nRBAC:\n- requires ANY of AIModels.Read, GroupAIModels.Read", "tags": [ "AI Models" ], "parameters": [ { "name": "modelId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "Migration path", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AIModel" } } } } } }, "security": [ { "header": [] } ] } }, "/api/v1/ai-models/{modelId}/resolve": { "get": { "summary": "Resolve an AI model", "description": "Resolves a model by following the successor chain if deprecated. Returns the active model that should be used. Catalog-only, no scope needed.\n\nRBAC:\n- requires ANY of AIModels.Read, GroupAIModels.Read", "tags": [ "AI Models" ], "parameters": [ { "name": "modelId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "Resolved model", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIModel" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AIModelDeprecatedNoSuccessor", "message": "AI model is deprecated with no successor" } } }, "description": "AI model is deprecated with no successor" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ResourceNotFound", "message": "The requested resource not found" } } }, "description": "The requested resource not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/ai-providers": { "get": { "summary": "List AI providers", "description": "Returns all catalog AI providers with scoped configuration state (configured, hasApiKey, etc.).\n\nRBAC:\n- requires ANY of AIProviders.Read, GroupAIProviders.Read", "tags": [ "AI Providers" ], "parameters": [ { "description": "Scope: 'global' or group TypeId", "required": true, "name": "scope", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of providers with scoped state", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AIProvider" } } } } } }, "security": [ { "header": [] } ] } }, "/api/v1/ai-providers/{providerId}": { "get": { "summary": "Get an AI provider", "description": "Returns a single AI provider by ID with scoped configuration state.\n\nRBAC:\n- requires ANY of AIProviders.Read, GroupAIProviders.Read", "tags": [ "AI Providers" ], "parameters": [ { "name": "providerId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Scope: 'global' or group TypeId", "required": true, "name": "scope", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Provider details with scoped state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIProvider" } } } }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ResourceNotFound", "message": "The requested resource not found" } } }, "description": "The requested resource not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/ai-providers/{providerId}/agents": { "get": { "summary": "List agents using scoped provider configuration", "description": "Returns AI agents that currently use scoped models linked to this provider in the given scope.\n\nRBAC:\n- requires ANY of AIProviders.Manage, GroupAIProviders.Manage", "tags": [ "AI Providers" ], "parameters": [ { "name": "providerId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Scope: 'global' or group TypeId", "required": true, "name": "scope", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of AI agents using this scoped provider configuration", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AIAgent" } } } } } }, "security": [ { "header": [] } ] } }, "/api/v1/ai-providers/{providerId}/configure": { "delete": { "summary": "Remove scoped configuration for a provider", "description": "Removes the scoped provider record and scoped model records for the scope. Agents that were using those models are automatically disabled.\n\nRBAC:\n- requires ANY of AIProviders.Manage, GroupAIProviders.Manage", "tags": [ "AI Providers" ], "parameters": [ { "name": "providerId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Scope: 'global' or group TypeId", "required": true, "name": "scope", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Configuration removed successfully", "content": { "application/json": { "schema": {} } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ResourceNotFound", "message": "The requested resource not found" } } }, "description": "The requested resource not found" } }, "security": [ { "header": [] } ] }, "put": { "summary": "Configure a provider for a scope", "description": "Sets or updates the API key and auth configuration for a provider in the given scope. Creates a scoped provider record if one doesn't exist.\n\nRBAC:\n- requires ANY of AIProviders.Manage, GroupAIProviders.Manage", "tags": [ "AI Providers" ], "parameters": [ { "name": "providerId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Scope: 'global' or group TypeId", "required": true, "name": "scope", "in": "query", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIScopedProviderConfigure" } } }, "required": true }, "responses": { "200": { "description": "Provider configured successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIProvider" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AIProviderInvalidApiKeyFormat", "message": "API key format does not match provider '%s'" } } }, "description": "API key format does not match provider '%s'" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AIProviderNotFound", "message": "AI provider not found" } } }, "description": "AI provider not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/ai-providers/{providerId}/models": { "get": { "summary": "List models for this provider", "description": "Returns all AI models for the specified provider with scoped enablement state.\n\nRBAC:\n- requires ANY of AIModels.Read, GroupAIModels.Read", "tags": [ "AI Providers" ], "parameters": [ { "name": "providerId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Filter by enablement state in the requested scope (true=enabled only, false=disabled/unconfigured, omit for all)", "name": "enabled", "in": "query", "schema": { "type": "boolean", "nullable": true }, "required": false }, { "description": "Include deprecated models", "name": "includeDeprecated", "in": "query", "schema": { "type": "boolean" } }, { "description": "Scope: 'global' or group TypeId", "required": true, "name": "scope", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of models with scoped state", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AIModel" } } } } } }, "security": [ { "header": [] } ] } }, "/api/v1/apps": { "post": { "summary": "Install a new application from ZIP file", "description": "Uploads and installs a new application from a ZIP archive. The application is created in a disabled state by default unless the 'enable' parameter is set to true. Requires authentication and the Apps.Manage RBAC permission. The installation is logged in the audit trail.\n\nRBAC: requires Apps.Manage", "tags": [ "Applications" ], "parameters": [ { "description": "Automatically enable the application after successful installation. Default is false.", "example": true, "required": false, "name": "enable", "in": "query", "schema": { "type": "boolean", "nullable": true } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "required": [ "file" ], "type": "object", "properties": { "file": { "format": "binary", "type": "string" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Application" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AppNoManifest": { "description": "No manifest was provided", "value": { "errorCode": "AppNoManifest", "message": "No manifest was provided" } }, "AppIncorrectYamlFile": { "description": "The provided manifest file is incorrect", "value": { "errorCode": "AppIncorrectYamlFile", "message": "The provided manifest file is incorrect" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AppNotFound", "message": "Application not found" } } }, "description": "Application not found" } }, "security": [ { "header": [] } ] }, "get": { "summary": "List globally available applications", "description": "Returns a list of applications available at the global entry point. These applications are accessible to all users.", "tags": [ "Applications" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Application" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [] } }, "/api/v1/apps/enabled": { "get": { "summary": "List all enabled applications", "description": "Returns a list of all currently enabled applications on the platform. Only applications in enabled state are returned. No authentication required.", "tags": [ "Applications" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Application" } } } } } }, "security": [] } }, "/api/v1/apps/installed": { "get": { "summary": "List all installed applications", "description": "Returns a list of all installed applications on the platform, including both enabled and disabled applications. No authentication required.", "tags": [ "Applications" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Application" } } } } } }, "security": [] } }, "/api/v1/apps/user": { "get": { "summary": "List user's available applications", "description": "Returns a list of applications available to the authenticated user, including both globally available and user-specific applications.", "tags": [ "Applications" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Application" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/apps/user/{appId}": { "delete": { "summary": "Remove application from user's list", "description": "Removes the specified application from the authenticated user's personal application list.", "tags": [ "Applications" ], "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ConstraintViolation", "message": "A request parameter constraint was violated" } } }, "description": "A request parameter constraint was violated" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AppNotFound", "message": "Application not found" } } }, "description": "Application not found" }, "500": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AppUpdateError", "message": "Failed to update the application" } } }, "description": "Failed to update the application" } }, "security": [ { "header": [] } ] }, "put": { "summary": "Add application to user's list", "description": "Adds the specified application to the authenticated user's personal application list, making it available in their user-specific context.", "tags": [ "Applications" ], "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "Returns app", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Application" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ConstraintViolation", "message": "A request parameter constraint was violated" } } }, "description": "A request parameter constraint was violated" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AppNotFound", "message": "Application not found" } } }, "description": "Application not found" }, "500": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AppUpdateError", "message": "Failed to update the application" } } }, "description": "Failed to update the application" } }, "security": [ { "header": [] } ] } }, "/api/v1/apps/{appId}": { "put": { "summary": "Update an existing application from ZIP file", "description": "Updates an existing application by uploading a new ZIP archive. The application manifest in the ZIP must match the existing application ID. Requires authentication and the Apps.Manage RBAC permission. The update is logged in the audit trail.\n\nRBAC: requires Apps.Manage", "tags": [ "Applications" ], "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Automatically enable the application after successful update. Default is false.", "example": false, "required": false, "name": "enable", "in": "query", "schema": { "type": "boolean", "nullable": true } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "required": [ "file" ], "type": "object", "properties": { "file": { "format": "binary", "type": "string" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Application" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AppNoManifest": { "description": "No manifest was provided", "value": { "errorCode": "AppNoManifest", "message": "No manifest was provided" } }, "AppIncorrectYamlFile": { "description": "The provided manifest file is incorrect", "value": { "errorCode": "AppIncorrectYamlFile", "message": "The provided manifest file is incorrect" } }, "ConstraintViolation": { "description": "A request parameter constraint was violated", "value": { "errorCode": "ConstraintViolation", "message": "A request parameter constraint was violated" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AppNotFound", "message": "Application not found" } } }, "description": "Application not found" } }, "security": [ { "header": [] } ] }, "get": { "summary": "Get application details by ID", "description": "Returns the complete application definition including manifest, routes, and configuration for the specified application ID.", "tags": [ "Applications" ], "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Application" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ConstraintViolation", "message": "A request parameter constraint was violated" } } }, "description": "A request parameter constraint was violated" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AppNotFound", "message": "Application not found" } } }, "description": "Application not found" } }, "security": [] }, "delete": { "summary": "Delete an application", "description": "Permanently deletes an application from the platform. The application cannot be deleted if it's set as default for any routes. This operation is irreversible. Requires authentication and the Apps.Manage RBAC permission.\n\nRBAC: requires Apps.Manage", "tags": [ "Applications" ], "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AppIsDefault": { "description": "The application is set as default", "value": { "errorCode": "AppIsDefault", "message": "The application is set as default" } }, "ConstraintViolation": { "description": "A request parameter constraint was violated", "value": { "errorCode": "ConstraintViolation", "message": "A request parameter constraint was violated" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AppNotFound", "message": "Application not found" } } }, "description": "Application not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/apps/{appId}/data": { "get": { "summary": "Query application data with filters", "description": "Retrieves application data entries based on filter criteria. Can filter by data type, tags (multiple tags are AND-ed), and owner. The user must have read permissions for the specified owner if filtering by owner. Returns all matching entries for the application. Without filters, returns all data the user has permission to access.", "tags": [ "Application Data" ], "parameters": [ { "description": "Application ID to query data for. Must be a valid APP type TypeId.", "required": true, "name": "appId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Filter by owner ID (user, group, user:group, or 'platform'). Requires read permission.", "required": false, "name": "owner", "in": "query", "schema": { "type": "string", "nullable": true } }, { "description": "Filter by tags. Comma-separated list. Returns entries that have ALL specified tags.", "required": false, "name": "tags", "in": "query", "schema": { "type": "array", "items": { "type": "string" } } }, { "description": "Filter by data type. Returns only entries with this exact type.", "required": false, "name": "type", "in": "query", "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "List of matching application data entries", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AppData" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "AppDataNoPermission": { "description": "No permission to access application data", "value": { "errorCode": "AppDataNoPermission", "message": "No permission to access application data" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AppDataNotFound", "message": "The specified application data not found" } } }, "description": "The specified application data not found" } }, "security": [ { "header": [] } ] }, "post": { "summary": "Create new application data entry", "description": "Creates a new data entry for the specified application. The data can be owned by a user, group, user within a group context, or the platform itself. Ownership determines access permissions. The data structure is flexible, supporting any JSON content with optional type categorization and tags for filtering.", "tags": [ "Application Data" ], "parameters": [ { "description": "Application ID that owns this data. Must be a valid APP type TypeId.", "required": true, "name": "appId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataCreate" } } }, "required": true }, "responses": { "200": { "description": "Application data successfully created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppData" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AppDataNotCreated", "message": "Failed to create application data" } } }, "description": "Failed to create application data" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "AppDataNoPermission": { "description": "No permission to access application data", "value": { "errorCode": "AppDataNoPermission", "message": "No permission to access application data" } } } } }, "description": "Forbidden" } }, "security": [ { "header": [] } ] } }, "/api/v1/apps/{appId}/data/{id}": { "put": { "summary": "Update existing application data", "description": "Updates an existing data entry for the application. The user must have manage permissions for the data owner (user/group). The ownership cannot be changed during update - the new ownerId must match the existing one. Updates the data content, type, and tags while preserving ownership.", "tags": [ "Application Data" ], "parameters": [ { "description": "Application ID that owns this data. Must match the data's application.", "required": true, "name": "appId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Data entry ID to update. Must be a valid APP_DATA type TypeId.", "required": true, "name": "id", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataCreate" } } }, "required": true }, "responses": { "200": { "description": "Application data successfully updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppData" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AppDataNotUpdated", "message": "Failed to update application data" } } }, "description": "Failed to update application data" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "AppDataNoPermission": { "description": "No permission to access application data", "value": { "errorCode": "AppDataNoPermission", "message": "No permission to access application data" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AppDataNotFound", "message": "The specified application data not found" } } }, "description": "The specified application data not found" } }, "security": [ { "header": [] } ] }, "delete": { "summary": "Delete application data entry", "description": "Permanently deletes a data entry from the application storage. The user must have manage permissions for the data owner. This operation cannot be undone. All associated metadata including tags and type information is also removed.", "tags": [ "Application Data" ], "parameters": [ { "description": "Application ID that owns this data. Must match the data's application.", "required": true, "name": "appId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Data entry ID to delete. Must be a valid APP_DATA type TypeId.", "required": true, "name": "id", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "Application data successfully deleted", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AppDataNotDeleted", "message": "Failed to delete application data" } } }, "description": "Failed to delete application data" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "AppDataNoPermission": { "description": "No permission to access application data", "value": { "errorCode": "AppDataNoPermission", "message": "No permission to access application data" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AppDataNotFound", "message": "The specified application data not found" } } }, "description": "The specified application data not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/apps/{appId}/default": { "put": { "summary": "Set application as platform default", "description": "Sets the specified application as the default handler for its declared routes at the platform level. This affects all users who haven't set their own defaults. Requires authentication and the Apps.Manage RBAC permission. Resets route caches after update.\n\nRBAC: requires Apps.Manage", "tags": [ "Applications" ], "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ConstraintViolation", "message": "A request parameter constraint was violated" } } }, "description": "A request parameter constraint was violated" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AppNotFound", "message": "Application not found" } } }, "description": "Application not found" }, "500": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AppUpdateError", "message": "Failed to update the application" } } }, "description": "Failed to update the application" } }, "security": [ { "header": [] } ] } }, "/api/v1/apps/{appId}/disable": { "put": { "summary": "Disable an application", "description": "Disables an enabled application, removing its routes and functionality from user access. The application cannot be disabled if it's set as default for any routes. Requires authentication and the Apps.Manage RBAC permission. Unregisters the application's routes upon disabling.\n\nRBAC: requires Apps.Manage", "tags": [ "Applications" ], "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AppIsDisabled": { "description": "The application is disabled", "value": { "errorCode": "AppIsDisabled", "message": "The application is disabled" } }, "AppIsDefault": { "description": "The application is set as default", "value": { "errorCode": "AppIsDefault", "message": "The application is set as default" } }, "ConstraintViolation": { "description": "A request parameter constraint was violated", "value": { "errorCode": "ConstraintViolation", "message": "A request parameter constraint was violated" } } } } }, "description": "Bad Request" }, "500": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AppUpdateError", "message": "Failed to update the application" } } }, "description": "Failed to update the application" } }, "security": [ { "header": [] } ] } }, "/api/v1/apps/{appId}/enable": { "put": { "summary": "Enable an application", "description": "Enables a disabled application, making its routes and functionality available to users. The application must not already be enabled. Requires authentication and the Apps.Manage RBAC permission. Registers the application's routes upon enabling.\n\nRBAC: requires Apps.Manage", "tags": [ "Applications" ], "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AppIsEnabled": { "description": "The application is enabled", "value": { "errorCode": "AppIsEnabled", "message": "The application is enabled" } }, "ConstraintViolation": { "description": "A request parameter constraint was violated", "value": { "errorCode": "ConstraintViolation", "message": "A request parameter constraint was violated" } } } } }, "description": "Bad Request" }, "500": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AppUpdateError", "message": "Failed to update the application" } } }, "description": "Failed to update the application" } }, "security": [ { "header": [] } ] } }, "/api/v1/apps/{appId}/stats": { "get": { "summary": "Get application with usage statistics", "description": "Returns the application definition along with usage statistics including install count, active users, and other metrics.", "tags": [ "Applications" ], "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationWithStats" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ConstraintViolation", "message": "A request parameter constraint was violated" } } }, "description": "A request parameter constraint was violated" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AppNotFound", "message": "Application not found" } } }, "description": "Application not found" } }, "security": [] } }, "/api/v1/apps/{appId}/user-default": { "put": { "summary": "Set application as user's default", "description": "Sets the specified application as the default handler for its declared routes for the authenticated user. This overrides platform-level defaults for this user.", "tags": [ "Applications" ], "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ConstraintViolation", "message": "A request parameter constraint was violated" } } }, "description": "A request parameter constraint was violated" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AppNotFound", "message": "Application not found" } } }, "description": "Application not found" }, "500": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AppUpdateError", "message": "Failed to update the application" } } }, "description": "Failed to update the application" } }, "security": [ { "header": [] } ] }, "delete": { "summary": "Remove user's default application", "description": "Removes the user's default application setting for the specified application's routes, reverting to platform defaults.", "tags": [ "Applications" ], "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ConstraintViolation", "message": "A request parameter constraint was violated" } } }, "description": "A request parameter constraint was violated" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AppNotFound", "message": "Application not found" } } }, "description": "Application not found" }, "500": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AppUpdateError", "message": "Failed to update the application" } } }, "description": "Failed to update the application" } }, "security": [ { "header": [] } ] } }, "/api/v1/async_refreshes/{id}": { "get": { "summary": "Get async refresh status", "description": "Returns the current status of an asynchronous background operation. Records expire after 10 minutes.", "tags": [ "Async Refreshes" ], "parameters": [ { "description": "Async refresh ID", "required": true, "name": "id", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "Async refresh status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncRefreshResponse" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AsyncRefreshNotFound", "message": "The specified async refresh not found or expired" } } }, "description": "The specified async refresh not found or expired" } }, "security": [ { "header": [] } ] } }, "/api/v1/block": { "get": { "summary": "List of blocked users", "description": "Returns a paginated list of all users that the authenticated user has blocked. Results are ordered by block date (most recent first) and include user profile information.", "tags": [ "Blocks" ], "parameters": [ { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/User" } } } } } }, "security": [ { "header": [] } ] } }, "/api/v1/block/by": { "get": { "summary": "List of users who blocked you", "description": "Returns a paginated list of users who have blocked the authenticated user. This information helps understand why certain interactions may be restricted. Results are ordered by block date and include basic user information.", "tags": [ "Blocks" ], "parameters": [ { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/User" } } } } } }, "security": [ { "header": [] } ] } }, "/api/v1/block/{userId}": { "delete": { "summary": "Unblock previously blocked user", "description": "Removes a block on a user, allowing interactions to resume. For remote users, sends an Undo Block activity via ActivityPub. The user must currently be blocked for this operation to succeed.", "tags": [ "Blocks" ], "parameters": [ { "description": "User ID to unblock. Must be a valid USER type TypeId that is currently blocked.", "name": "userId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "UserCannotBlockSelf": { "description": "A user cannot block themselves", "value": { "errorCode": "UserCannotBlockSelf", "message": "A user cannot block themselves" } }, "UserIsNotBlocked": { "description": "The specified user is not blocked", "value": { "errorCode": "UserIsNotBlocked", "message": "The specified user is not blocked" } } } } }, "description": "Bad Request" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserNotFound", "message": "User not found" } } }, "description": "User not found" } }, "security": [ { "header": [] } ] }, "post": { "summary": "Block specific user", "description": "Blocks a user, preventing all interactions between you and the blocked user. This action automatically unfollows both users from each other, removes any reposts, and removes any existing mute. For remote users, sends a Block activity via ActivityPub. Cannot block yourself.", "tags": [ "Blocks" ], "parameters": [ { "description": "User ID to block. Must be a valid USER type TypeId.", "name": "userId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "UserCannotBlockSelf": { "description": "A user cannot block themselves", "value": { "errorCode": "UserCannotBlockSelf", "message": "A user cannot block themselves" } }, "UserAlreadyBlocked": { "description": "The specified user is already blocked", "value": { "errorCode": "UserAlreadyBlocked", "message": "The specified user is already blocked" } } } } }, "description": "Bad Request" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserNotFound", "message": "User not found" } } }, "description": "User not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/custom_emojis": { "get": { "summary": "Get emojis by shortcodes or categories", "description": "Retrieves emojis by exact shortcodes and/or by exact categories from cache. Multiple values can be requested in a single call using comma separation. If both parameters are provided, the union of results is returned. Returns paginated response with items (current page results), total (count matching filter), and totalItems (total emojis in system).", "tags": [ "Emoji" ], "parameters": [ { "description": "Exact category name(s). Multiple values comma-separated", "example": "Cats,Dogs", "name": "category", "required": false, "in": "query", "schema": { "type": "array", "items": { "type": "string" }, "nullable": true } }, { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "Exact shortcode(s) of emoji. Multiple values comma-separated", "example": "aaaa,AAAAAA", "name": "shortcode", "required": false, "in": "query", "schema": { "type": "array", "items": { "type": "string" }, "nullable": true } }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } ], "responses": { "200": { "description": "Paginated emoji results", "content": { "application/json": { "example": { "items": [ { "shortcode": "aaaa", "url": "https://files.mastodon.social/custom_emojis/images/000/007/118/original/aaaa.png", "static_url": "https://files.mastodon.social/custom_emojis/images/000/007/118/static/aaaa.png", "visibleInPicker": true, "category": "Cats" }, { "shortcode": "AAAAAA", "url": "https://files.mastodon.social/custom_emojis/images/000/071/387/original/AAAAAA.png", "static_url": "https://files.mastodon.social/custom_emojis/images/000/071/387/static/AAAAAA.png", "visibleInPicker": true, "category": "Blobs" } ], "total": 2, "totalItems": 100 }, "schema": { "$ref": "#/components/schemas/EmojiPaginatedResponse" } } } } }, "security": [] }, "delete": { "summary": "Delete emojis", "description": "Deletes custom emojis by shortcode or category. Can delete multiple emojis at once using comma-separated values. Either shortcode or category must be provided. Returns the count of deleted emojis. Requires Emojis.Manage permission (admin only).\n\nRBAC: requires Emojis.Manage", "tags": [ "Emoji" ], "parameters": [ { "description": "You can provide multiple categories as comma-separated values", "example": "?category=Cats,Dogs", "name": "category", "required": false, "in": "query", "schema": { "type": "array", "items": { "type": "string" }, "nullable": true } }, { "description": "You can provide multiple shortcodes as comma-separated values", "example": "?shortcode=aaa,AAA", "name": "shortcode", "required": false, "in": "query", "schema": { "type": "array", "items": { "type": "string" }, "nullable": true } } ], "responses": { "200": { "description": "Number of deleted emojis", "content": { "plain/text": { "example": "3" } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] }, "post": { "summary": "Create emoji from URL", "description": "Creates a custom emoji by downloading from provided URLs. The emoji file is downloaded, processed, and stored locally. Supports overwriting existing emojis with the same shortcode. Can specify category, visibility, and domain for federated emojis. Requires Emojis.Manage permission (admin only).\n\nRBAC: requires Emojis.Manage", "tags": [ "Emoji" ], "parameters": [ { "description": "Should existing emojis be overwritten if shortcode matches", "name": "overwrite", "required": false, "schema": { "type": "boolean" }, "in": "query" } ], "requestBody": { "description": "Json object with the emoji data: shortcode, category, url, staticUrl, visibleInPicker", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Emoji" } } }, "required": true }, "responses": { "200": { "description": "json object with the emoji data", "content": { "application/json": { "example": "\n {\n \"shortcode\": \"aaaa\",\n \"url\": \"https://files.mastodon.social/custom_emojis/images/000/007/118/original/aaaa.png\",\n \"static_url\": \"https://files.mastodon.social/custom_emojis/images/000/007/118/static/aaaa.png\",\n \"visibleInPicker\": true\n \"category\": \"Cats\",\n \"domain\": \"mastodon.social\"\n }\n ]\n ", "schema": { "$ref": "#/components/schemas/Emoji" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "EmojiErrorProcessing": { "description": "An error occurred while processing the emoji file", "value": { "errorCode": "EmojiErrorProcessing", "message": "An error occurred while processing the emoji file" } }, "EmojiInvalidFormat": { "description": "The provided emoji file format is invalid", "value": { "errorCode": "EmojiInvalidFormat", "message": "The provided emoji file format is invalid" } }, "EmojiNoStreams": { "description": "Invalid file format: no streams found", "value": { "errorCode": "EmojiNoStreams", "message": "Invalid file format: no streams found" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "500": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EmojiErrorCreating", "message": "Failed to create the emoji" } } }, "description": "Failed to create the emoji" } }, "security": [ { "header": [] } ] } }, "/api/v1/custom_emojis/categories": { "get": { "summary": "List custom emoji categories", "description": "Returns distinct non-empty categories. Supports optional query and pagination.\n\nRBAC: requires Emojis.Manage", "tags": [ "Emoji" ], "parameters": [ { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "Filter categories by substring", "name": "q", "required": false, "in": "query", "schema": { "type": "string", "nullable": true } }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } ], "responses": { "200": { "description": "List of categories", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } } }, "security": [ { "header": [] } ] } }, "/api/v1/custom_emojis/export": { "get": { "summary": "Export emojis to ZIP", "description": "Exports emojis from a specific category as a ZIP archive. The ZIP contains all emoji files from the specified category. Useful for backup or migration purposes. Returns 404 if no emojis found in the category. Requires Emojis.Manage permission (admin only).\n\nRBAC: requires Emojis.Manage", "tags": [ "Emoji" ], "parameters": [ { "description": "Category of the emojis to export", "name": "category", "required": false, "schema": { "type": "string" }, "in": "query" } ], "responses": { "200": { "description": "Zip file with the emojis", "content": { "application/octet-stream": {} } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EmojiNotFound", "message": "The specified emoji not found" } } }, "description": "The specified emoji not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/custom_emojis/import": { "post": { "summary": "Bulk import emojis from ZIP", "description": "Imports multiple emojis from a ZIP archive. Filenames (without extension) become emoji shortcodes. All imported emojis share the same category and visibility settings. Images are automatically resized to 128x128 if larger. Animated GIFs are preserved with static versions generated. Supports batch overwriting of existing emojis. Requires Emojis.Manage permission (admin only).\n\nRBAC: requires Emojis.Manage", "tags": [ "Emoji" ], "parameters": [ { "description": "Category of the imported emojis", "name": "category", "required": true, "schema": { "type": "string" }, "in": "query" }, { "name": "domain", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Should existing emojis be overwritten if any of the shortcodes match", "name": "overwrite", "required": false, "schema": { "type": "boolean" }, "in": "query" }, { "description": "Whether the imported emojis should be visible in the picker", "name": "visible", "required": true, "in": "query", "schema": { "type": "boolean" } } ], "requestBody": { "description": "Zip file with the emojis.", "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "file" ], "type": "object", "properties": { "file": { "format": "binary", "type": "string" } } } } } }, "responses": { "200": { "description": "Array of json objects with the emoji data", "content": { "application/json": { "example": [ { "shortcode": "aaaa", "url": "https://files.mastodon.social/custom_emojis/images/000/007/118/original/aaaa.png", "static_url": "https://files.mastodon.social/custom_emojis/images/000/007/118/static/aaaa.png", "visibleInPicker": true, "category": "Cats" }, { "shortcode": "AAAAAA", "url": "https://files.mastodon.social/custom_emojis/images/000/071/387/original/AAAAAA.png", "static_url": "https://files.mastodon.social/custom_emojis/images/000/071/387/static/AAAAAA.png", "visibleInPicker": true, "category": "Blobs" } ], "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Emoji" } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "EmojiErrorProcessing": { "description": "An error occurred while processing the emoji file", "value": { "errorCode": "EmojiErrorProcessing", "message": "An error occurred while processing the emoji file" } }, "EmojiInvalidFormat": { "description": "The provided emoji file format is invalid", "value": { "errorCode": "EmojiInvalidFormat", "message": "The provided emoji file format is invalid" } }, "EmojiNoStreams": { "description": "Invalid file format: no streams found", "value": { "errorCode": "EmojiNoStreams", "message": "Invalid file format: no streams found" } }, "EmojiImportingError": { "description": "An error occurred while importing the emoji", "value": { "errorCode": "EmojiImportingError", "message": "An error occurred while importing the emoji" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/custom_emojis/import/upload": { "post": { "summary": "Bulk import emojis from ZIP upload", "description": "Imports multiple emojis from a ZIP archive that was previously uploaded via /uploads. Filenames (without extension) become emoji shortcodes. All imported emojis share the same category and visibility settings. Images are automatically resized to 128x128 if larger. Animated GIFs are preserved with static versions generated. Supports batch overwriting of existing emojis.\n\nRBAC: requires Emojis.Manage", "tags": [ "Emoji" ], "parameters": [ { "description": "Category of the imported emojis", "name": "category", "required": true, "schema": { "type": "string" }, "in": "query" }, { "name": "domain", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Should existing emojis be overwritten if any of the shortcodes match", "name": "overwrite", "required": false, "schema": { "type": "boolean" }, "in": "query" }, { "description": "ID of the previously created upload containing the ZIP archive", "name": "uploadId", "required": true, "in": "query", "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Whether the imported emojis should be visible in the picker", "name": "visible", "required": true, "schema": { "type": "boolean" }, "in": "query" } ], "responses": { "200": { "description": "Array of json objects with the emoji data", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Emoji" } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "EmojiErrorProcessing": { "description": "An error occurred while processing the emoji file", "value": { "errorCode": "EmojiErrorProcessing", "message": "An error occurred while processing the emoji file" } }, "EmojiInvalidFormat": { "description": "The provided emoji file format is invalid", "value": { "errorCode": "EmojiInvalidFormat", "message": "The provided emoji file format is invalid" } }, "EmojiNoStreams": { "description": "Invalid file format: no streams found", "value": { "errorCode": "EmojiNoStreams", "message": "Invalid file format: no streams found" } }, "EmojiImportingError": { "description": "An error occurred while importing the emoji", "value": { "errorCode": "EmojiImportingError", "message": "An error occurred while importing the emoji" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/custom_emojis/search": { "get": { "summary": "Search emojis by partial shortcode or category", "description": "Searches for emojis whose shortcodes or categories contain provided substrings. Useful for autocomplete functionality. Multiple searches can be performed in one request by passing comma-separated values. If no parameters provided, returns all emojis from cache. Returns paginated response with items (current page results), total (count matching filter), and totalItems (total emojis in system).", "tags": [ "Emoji" ], "parameters": [ { "description": "Category substring(s) to search. Comma-separated", "example": "Cat,Blob", "name": "category", "required": false, "in": "query", "schema": { "type": "array", "items": { "type": "string" }, "nullable": true } }, { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "Shortcode substring(s) to search. Comma-separated", "example": "aaa,AAA", "name": "shortcode", "required": false, "in": "query", "schema": { "type": "array", "items": { "type": "string" }, "nullable": true } }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } ], "responses": { "200": { "description": "Paginated emoji search results", "content": { "application/json": { "example": { "items": [ { "shortcode": "aaaa", "url": "https://files.mastodon.social/custom_emojis/images/000/007/118/original/aaaa.png", "static_url": "https://files.mastodon.social/custom_emojis/images/000/007/118/static/aaaa.png", "visibleInPicker": true, "category": "Cats" }, { "shortcode": "AAAAAA", "url": "https://files.mastodon.social/custom_emojis/images/000/071/387/original/AAAAAA.png", "static_url": "https://files.mastodon.social/custom_emojis/images/000/071/387/static/AAAAAA.png", "visibleInPicker": true, "category": "Blobs" } ], "total": 15, "totalItems": 100 }, "schema": { "$ref": "#/components/schemas/EmojiPaginatedResponse" } } } } }, "security": [] } }, "/api/v1/custom_emojis/upload": { "post": { "summary": "Upload emoji from existing upload", "description": "Processes an existing upload (created via /uploads) as a custom emoji. Clients must first create an upload and PUT the file to the returned URL, then call this endpoint with the uploadId.\n\nRBAC: requires Emojis.Manage", "tags": [ "Emoji" ], "parameters": [ { "description": "Category of the emoji", "name": "category", "required": true, "schema": { "type": "string" }, "in": "query" }, { "name": "domain", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Should existing emojis be overwritten if shortcode matches", "name": "overwrite", "required": false, "schema": { "type": "boolean" }, "in": "query" }, { "description": "Shortcode of the emoji", "name": "shortcode", "required": true, "schema": { "type": "string" }, "in": "query" }, { "description": "ID of the previously created upload containing the emoji file", "name": "uploadId", "required": true, "in": "query", "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Whether the emoji should be visible in the picker", "name": "visible", "required": true, "schema": { "type": "boolean" }, "in": "query" } ], "responses": { "200": { "description": "json object with the emoji data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Emoji" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "EmojiErrorProcessing": { "description": "An error occurred while processing the emoji file", "value": { "errorCode": "EmojiErrorProcessing", "message": "An error occurred while processing the emoji file" } }, "EmojiInvalidFormat": { "description": "The provided emoji file format is invalid", "value": { "errorCode": "EmojiInvalidFormat", "message": "The provided emoji file format is invalid" } }, "EmojiNoStreams": { "description": "Invalid file format: no streams found", "value": { "errorCode": "EmojiNoStreams", "message": "Invalid file format: no streams found" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/custom_emojis/{shortcode}": { "patch": { "summary": "Partially update emoji metadata", "description": "Updates emoji metadata fields without requiring file upload. Supports updating category, visibility and domain. Requires Emojis.Manage permission.\n\nRBAC: requires Emojis.Manage", "tags": [ "Emoji" ], "parameters": [ { "description": "Emoji shortcode", "name": "shortcode", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmojiPatchRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated emoji", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Emoji" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EmojiNotFound", "message": "The specified emoji not found" } } }, "description": "The specified emoji not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/data": { "get": { "summary": "Query platform data with filters", "description": "Retrieves platform-level data entries based on filter criteria. Can filter by type, tags (multiple tags are AND-ed), and owner. When filtering by owner, requires Data.Manage permission for that owner. Returns all matching entries not tied to any specific application. Without filters, returns all platform data the user has permission to access.", "tags": [ "Platform Data" ], "parameters": [ { "description": "Filter by owner ID (user, group, user:group, or 'platform'). Requires manage permission.", "required": false, "name": "owner", "in": "query", "schema": { "type": "string", "nullable": true } }, { "description": "Filter by tags. Comma-separated list. Returns entries that have ALL specified tags.", "required": false, "name": "tags", "in": "query", "schema": { "type": "array", "items": { "type": "string" } } }, { "description": "Filter by data type. Returns only entries with this exact type.", "required": false, "name": "type", "in": "query", "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "List of matching platform data entries", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AppData" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "AppDataNoPermission": { "description": "No permission to access application data", "value": { "errorCode": "AppDataNoPermission", "message": "No permission to access application data" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AppDataNotFound", "message": "The specified application data not found" } } }, "description": "The specified application data not found" } }, "security": [ { "header": [] } ] }, "post": { "summary": "Create new platform data entry", "description": "Creates a new data entry at the platform level, not associated with any specific application. The data can be owned by users, groups, or the platform itself. Requires Data.Manage permission for the specified owner. Supports flexible JSON content with optional type categorization and tags.", "tags": [ "Platform Data" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataCreate" } } }, "required": true }, "responses": { "200": { "description": "Data entry successfully created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppData" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AppDataNotCreated", "message": "Failed to create application data" } } }, "description": "Failed to create application data" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "AppDataNoPermission": { "description": "No permission to access application data", "value": { "errorCode": "AppDataNoPermission", "message": "No permission to access application data" } } } } }, "description": "Forbidden" } }, "security": [ { "header": [] } ] } }, "/api/v1/data/{id}": { "put": { "summary": "Update existing platform data", "description": "Updates an existing platform-level data entry. Requires Data.Manage permission for the data owner. The ownership cannot be changed - the new ownerId must match the existing one. Updates the content, type, and tags while preserving the original ownership.", "tags": [ "Platform Data" ], "parameters": [ { "description": "Data entry ID to update. Must be a valid APP_DATA type TypeId.", "required": true, "name": "id", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataCreate" } } }, "required": true }, "responses": { "200": { "description": "Data entry successfully updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppData" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AppDataNotUpdated", "message": "Failed to update application data" } } }, "description": "Failed to update application data" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "AppDataNoPermission": { "description": "No permission to access application data", "value": { "errorCode": "AppDataNoPermission", "message": "No permission to access application data" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AppDataNotFound", "message": "The specified application data not found" } } }, "description": "The specified application data not found" } }, "security": [ { "header": [] } ] }, "delete": { "summary": "Delete platform data entry", "description": "Permanently deletes a platform-level data entry. Requires Data.Manage permission for the data owner. This operation is irreversible and removes all associated metadata including type and tags. Use with caution as deleted data cannot be recovered.", "tags": [ "Platform Data" ], "parameters": [ { "description": "Data entry ID to delete. Must be a valid APP_DATA type TypeId.", "required": true, "name": "id", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "Data entry successfully deleted", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AppDataNotDeleted", "message": "Failed to delete application data" } } }, "description": "Failed to delete application data" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "AppDataNoPermission": { "description": "No permission to access application data", "value": { "errorCode": "AppDataNoPermission", "message": "No permission to access application data" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AppDataNotFound", "message": "The specified application data not found" } } }, "description": "The specified application data not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/devices": { "put": { "summary": "Register or update a device for push notifications", "description": "Registers a new device subscription or updates an existing one for push notifications. The request must include a valid Web Push subscription with endpoint, keys, and device metadata. Requires authentication. If a device with the same endpoint already exists, it is updated.", "tags": [ "User Devices" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceRegistrationRequest" } } }, "required": true }, "responses": { "200": { "description": "Device stored", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ConstraintViolation", "message": "A request parameter constraint was violated" } } }, "description": "A request parameter constraint was violated" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] }, "get": { "summary": "Get all registered devices for the current user", "description": "Returns a list of all devices registered for push notifications by the authenticated user. Each device entry includes the subscription endpoint, device metadata, and registration timestamp. Requires authentication.", "tags": [ "User Devices" ], "responses": { "200": { "description": "List of devices", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserDevice" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/devices/all": { "delete": { "summary": "Delete all registered devices for the current user", "description": "Removes all device registrations for the authenticated user, effectively disabling push notifications on all devices. Requires authentication. Useful when a user wants to reset their push notification setup.", "tags": [ "User Devices" ], "responses": { "204": { "description": "Devices deleted" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/devices/vapid-public-key": { "get": { "summary": "Get VAPID public key for browser push subscriptions", "description": "Returns the server's VAPID (Voluntary Application Server Identification) public key needed by clients to create Web Push subscriptions. This endpoint is publicly accessible without authentication so clients can subscribe before or after login.", "tags": [ "User Devices" ], "responses": { "200": { "description": "VAPID public key returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VapidPublicKeyResponse" } } } } }, "security": [] } }, "/api/v1/devices/{deviceId}": { "delete": { "summary": "Delete a registered device for the current user", "description": "Removes a specific device registration identified by its device ID, stopping push notifications to that device. Requires authentication. Only the authenticated user's own devices can be deleted.", "tags": [ "User Devices" ], "parameters": [ { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Device deleted" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/domain-block": { "get": { "summary": "List blocked domains (Public)", "description": "Returns the list of domains blocked by this instance with sensitive fields removed. Visibility depends on platform settings: access may be restricted to NONE (hidden), USER (authenticated users only), or ALL (everyone). Reason text visibility is controlled separately by a similar access setting. Obfuscated domains are partially masked for privacy.", "tags": [ "Domain Blocks" ], "parameters": [ { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } ], "responses": { "200": { "description": "Successfully retrieved public list of blocked domains", "content": { "application/json": { "examples": { "Public blocked domains": { "value": [ { "domain": "sp**.e*****e", "publicComment": "", "state": "SUSPEND", "rejectMedia": true, "rejectReports": true, "privateComment": "", "obfuscate": true, "createdAt": "2024-01-15T10:30:00Z", "updatedAt": "2024-01-15T10:30:00Z" } ] } }, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BlockedDomain" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [] } }, "/api/v1/drafts": { "post": { "summary": "Upsert a draft by owner", "tags": [ "Drafts" ], "parameters": [ { "description": "Draft owner context", "required": true, "name": "ownerId", "in": "query", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertDraftRequest" } } } }, "responses": { "200": { "description": "Created or updated draft", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Draft" } } } }, "400": { "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] }, "get": { "summary": "Get all drafts for current user", "tags": [ "Drafts" ], "responses": { "200": { "description": "List of drafts", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Draft" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/drafts/{ownerId}": { "get": { "summary": "Get draft by owner", "tags": [ "Drafts" ], "parameters": [ { "name": "ownerId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "Draft", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Draft" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "DraftNotFound", "message": "The specified draft not found" } } }, "description": "The specified draft not found" } }, "security": [ { "header": [] } ] }, "delete": { "summary": "Delete draft by owner", "tags": [ "Drafts" ], "parameters": [ { "name": "ownerId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": {} } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "DraftNotFound", "message": "The specified draft not found" } } }, "description": "The specified draft not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/drafts/{ownerId}/publish": { "post": { "summary": "Publish draft by owner", "tags": [ "Drafts" ], "parameters": [ { "name": "ownerId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ], "responses": { "200": { "description": "Published posts", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "DraftNotFound", "message": "The specified draft not found" } } }, "description": "The specified draft not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/events": { "get": { "summary": "Get public events or user-specific events", "description": "Returns public events for unauthenticated users, or events for a specific user/owner for authenticated users. Supports filtering by organizer or owner.", "tags": [ "Events" ], "parameters": [ { "description": "List specific group's events", "required": false, "name": "groupId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "Show no more than the given number of events", "required": false, "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true } }, { "description": "An offset to show events starting from", "required": false, "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true } }, { "description": "List specific user's events", "required": false, "name": "organizerId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "List specific user's events", "required": false, "name": "username", "in": "query", "schema": { "type": "string", "nullable": true } }, { "description": "Include translation", "required": false, "name": "withTranslation", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Language" } ], "nullable": true } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserIdOrUserNameMissing", "message": "The userId or userName must be provided" } } }, "description": "The userId or userName must be provided" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserNotFound", "message": "User not found" } } }, "description": "User not found" } }, "security": [] }, "post": { "summary": "Create a new event", "description": "Creates a new event with specified details including title, description, date/time, location, and privacy settings. The authenticated user becomes the event organizer.", "tags": [ "Events" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEvent" } } }, "required": true }, "responses": { "200": { "description": "Event object just created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EventInvalidPrivacy", "message": "Only PUBLIC, UNLISTED or DIRECT privacy is allowed" } } }, "description": "Only PUBLIC, UNLISTED or DIRECT privacy is allowed" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "NotGroupMember", "message": "The user must be a member of the group" } } }, "description": "The user must be a member of the group" } }, "security": [ { "header": [] } ] } }, "/api/v1/events/calendar/g/{groupname}.ics": { "get": { "summary": "Export group's public calendar", "description": "Exports a group's non invite-only events as an ICS (iCalendar) file. Only available if the group has enabled public calendar export in their settings.", "tags": [ "Events" ], "parameters": [ { "description": "Group name of the group of public calendar", "required": true, "name": "groupname", "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Calendar in ICS format", "content": { "text/calendar": { "schema": { "format": "binary", "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ResourceNotFound", "message": "The requested resource not found" } } }, "description": "The requested resource not found" } }, "security": [] } }, "/api/v1/events/calendar/p/{id}.ics": { "get": { "summary": "Export private calendar", "description": "Exports a user's or group's private calendar using a unique private ID. Events visibility is configured in calendar settings.", "tags": [ "Events" ], "parameters": [ { "description": "Private calendar id", "required": true, "name": "id", "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Calendar in ICS format", "content": { "text/calendar": { "schema": { "format": "binary", "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ResourceNotFound", "message": "The requested resource not found" } } }, "description": "The requested resource not found" } }, "security": [] } }, "/api/v1/events/calendar/u/{username}.ics": { "get": { "summary": "Export user's public calendar", "description": "Exports a user's all non invite-only events as an ICS (iCalendar) file. Only available if the user has enabled public calendar export in their settings.", "tags": [ "Events" ], "parameters": [ { "description": "Public calendar user's username", "required": true, "name": "username", "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Calendar in ICS format", "content": { "text/calendar": { "schema": { "format": "binary", "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ResourceNotFound", "message": "The requested resource not found" } } }, "description": "The requested resource not found" } }, "security": [] } }, "/api/v1/events/my": { "get": { "summary": "Get authenticated user's events", "description": "Returns events for the authenticated user with various filtering options including past events, organized events, and events pending response.", "tags": [ "Events" ], "parameters": [ { "description": "Show no more than the given number of events", "required": false, "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true } }, { "description": "List not yet responded events only", "required": false, "name": "notRespondedOnly", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "An offset to show events starting from", "required": false, "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true } }, { "description": "List events current user has organized", "required": false, "name": "organizedOnly", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "List current user's past events only", "required": false, "name": "past", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Include translation", "required": false, "name": "withTranslation", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Language" } ], "nullable": true } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/events/search": { "get": { "summary": "Search events", "description": "Searches events by mode: following, local, or federated (FASP). For local/fasp modes at least one of query, date range, or location filter must be provided. If groupId is not provided search is not restricted by group.", "tags": [ "Events" ], "parameters": [ { "description": "Include cancelled events in results", "required": false, "name": "cancelled", "in": "query", "schema": { "default": false, "type": "boolean" } }, { "description": "Geo search radius in meters (requires latitude and longitude)", "example": 5000, "required": false, "name": "distanceMeters", "in": "query", "schema": { "format": "double", "type": "number", "nullable": true } }, { "description": "End of event start-time range (inclusive), ISO-8601", "required": false, "name": "endTime", "in": "query", "schema": { "type": "string", "nullable": true } }, { "description": "For mode=fasp, request hydrated events from providers", "required": false, "name": "faspHydrate", "in": "query", "schema": { "default": false, "type": "boolean" } }, { "description": "Filter by group. If absent includes events from all scopes", "required": false, "name": "groupId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "Latitude for geo search (requires longitude and distanceMeters)", "example": 42.3601, "required": false, "name": "latitude", "in": "query", "schema": { "format": "double", "type": "number", "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "Longitude for geo search (requires latitude and distanceMeters)", "example": -71.0589, "required": false, "name": "longitude", "in": "query", "schema": { "format": "double", "type": "number", "nullable": true } }, { "description": "Search mode: following, local, fasp", "required": true, "name": "mode", "in": "query", "schema": { "$ref": "#/components/schemas/EventSearchMode" } }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "Sort order by event start time: ASC or DESC", "required": false, "name": "order", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/SortOrder" } ], "nullable": true } }, { "description": "Search query", "required": false, "name": "q", "in": "query", "schema": { "type": "string", "nullable": true } }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Start of event start-time range (inclusive), ISO-8601. If both startTime and endTime are omitted, default is upcoming events (from now).", "required": false, "name": "startTime", "in": "query", "schema": { "type": "string", "nullable": true } }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ClientError", "message": "Invalid request from client" } } }, "description": "Invalid request from client" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "GroupNotFound", "message": "Group not found" } } }, "description": "Group not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/events/settings": { "get": { "summary": "Get event calendar settings", "description": "Retrieves calendar export settings for the authenticated user or a specified group, including public/private calendar visibility and export options.", "tags": [ "Events" ], "parameters": [ { "description": "Group ID for groups", "required": false, "name": "ownerId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventsSettings" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/events/settings/regeneratePrivateId": { "post": { "summary": "Regenerate private calendar ID", "description": "Generates a new unique ID for the private calendar URL. This invalidates the previous private calendar link.", "tags": [ "Events" ], "parameters": [ { "description": "Group ID for groups", "required": false, "name": "ownerId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } ], "responses": { "200": { "description": "Newly generated unique ID for private calendar", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/events/settings/update": { "post": { "summary": "Update event calendar settings", "description": "Updates calendar export settings including public/private calendar visibility, detail level, and export scope.", "tags": [ "Events" ], "parameters": [ { "description": "Group ID for groups", "required": false, "name": "ownerId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEventsSettings" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventsSettings" } } } }, "400": { "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EventsSettingsInvalidExportValue", "message": "Invalid exportEvents value" } } }, "description": "Invalid exportEvents value" } }, "security": [ { "header": [] } ] } }, "/api/v1/events/{eventId}": { "put": { "summary": "Update event details", "description": "Updates an existing event's information including title, description, date/time, location, and privacy settings. Only the event organizer can update the event.", "tags": [ "Events" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEvent" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "400": { "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "NotGroupMember", "message": "The user must be a member of the group" } } }, "description": "The user must be a member of the group" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EventNotFound", "message": "The specified event not found" } } }, "description": "The specified event not found" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EventConflictingUpdate", "message": "Conflicting event update" } } }, "description": "Conflicting event update" }, "500": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EventUpdateError", "message": "Unable to update the event" } } }, "description": "Unable to update the event" } }, "security": [ { "header": [] } ] }, "get": { "summary": "Get event details by ID", "description": "Retrieves detailed information about a specific event including attendee status, statistics, and optional translations.", "tags": [ "Events" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Include translation", "required": false, "name": "withTranslation", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Language" } ], "nullable": true } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EventNotFound", "message": "The specified event not found" } } }, "description": "The specified event not found" } }, "security": [] }, "delete": { "summary": "Delete an event", "description": "Soft deletes an event, marking it as cancelled. The event is not permanently removed and can still be viewed as deleted. Only the event organizer can delete the event.", "tags": [ "Events" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "Event has been deleted successfully", "content": { "application/json": { "schema": {} } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EventNotFound", "message": "The specified event not found" } } }, "description": "The specified event not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/events/{eventId}.ics": { "get": { "summary": "Export event as ICS file", "description": "Exports a single event in ICS (iCalendar) format for import into calendar applications.", "tags": [ "Events" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "Calendar in ICS format", "content": { "text/calendar": { "schema": { "format": "binary", "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ResourceNotFound", "message": "The requested resource not found" } } }, "description": "The requested resource not found" } }, "security": [] } }, "/api/v1/events/{eventId}/accept": { "post": { "summary": "Accept an invite-only event invitation", "description": "Accepts an invitation to the invite-only event, confirming attendance. Only invited users can accept.", "tags": [ "Events" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EventActionNotAllowed", "message": "Event action is not allowed" } } }, "description": "Event action is not allowed" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EventNotFound", "message": "The specified event not found" } } }, "description": "The specified event not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/events/{eventId}/attendees": { "get": { "summary": "Get invite-only event attendees", "description": "Returns the list of attendees for an invite-only event along with their response statuses (accepted, tentative, rejected, pending).", "tags": [ "Events" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Show no more than the given number of attendees", "required": false, "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true } }, { "description": "An offset to show attendees starting from", "required": false, "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EventAttendee" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EventNotFound", "message": "The specified event not found" } } }, "description": "The specified event not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/events/{eventId}/attendees/{userId}": { "delete": { "summary": "Remove user from invite-only event", "description": "Revokes a user's invitation or removes them from an invite-only event. Only the event organizer can remove attendees.", "tags": [ "Events" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "name": "userId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "EventNotFound": { "description": "The specified event not found", "value": { "errorCode": "EventNotFound", "message": "The specified event not found" } }, "UserNotFound": { "description": "User not found", "value": { "errorCode": "UserNotFound", "message": "User not found" } } } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EventNotJoined", "message": "The event has not been joined" } } }, "description": "The event has not been joined" } }, "security": [ { "header": [] } ] }, "post": { "summary": "Invite user to an invite-only event", "description": "Sends an invitation to a specific user for an invite-only event. Only the event organizer can invite attendees.", "tags": [ "Events" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "name": "userId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "EventNotFound": { "description": "The specified event not found", "value": { "errorCode": "EventNotFound", "message": "The specified event not found" } }, "UserNotFound": { "description": "User not found", "value": { "errorCode": "UserNotFound", "message": "User not found" } } } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EventAlreadyJoined", "message": "The event has already been joined" } } }, "description": "The event has already been joined" } }, "security": [ { "header": [] } ] } }, "/api/v1/events/{eventId}/cancel": { "post": { "summary": "Cancel a scheduled event", "description": "Cancels a scheduled event, notifying all attendees. The event remains visible but marked as cancelled. Only the event organizer can cancel.", "tags": [ "Events" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EventNotFound", "message": "The specified event not found" } } }, "description": "The specified event not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/events/{eventId}/interested": { "post": { "summary": "Express interest in an event", "description": "Marks the authenticated user as interested in a public event. Cannot be used for invite-only events. Returns updated event statistics.", "tags": [ "Events" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventStats" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EventNotFound", "message": "The specified event not found" } } }, "description": "The specified event not found" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EventAlreadyInterested", "message": "The interest in event has been already shown" } } }, "description": "The interest in event has been already shown" } }, "security": [ { "header": [] } ] } }, "/api/v1/events/{eventId}/join": { "post": { "summary": "Join a public event", "description": "Confirms attendance for a public event. Cannot be used for invite-only events which require invitations. Returns updated event statistics.", "tags": [ "Events" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventStats" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EventNotFound", "message": "The specified event not found" } } }, "description": "The specified event not found" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EventAlreadyJoined", "message": "The event has already been joined" } } }, "description": "The event has already been joined" } }, "security": [ { "header": [] } ] } }, "/api/v1/events/{eventId}/joinOrInterested": { "delete": { "summary": "Leave or revoke interest in event", "description": "Removes the authenticated user's interest or participation in a public event. Cannot be used for invite-only events. Returns updated event statistics.", "tags": [ "Events" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventStats" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EventNotFound", "message": "The specified event not found" } } }, "description": "The specified event not found" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EventNotJoinedNorInterestedIn", "message": "The event has not been joined nor interested in" } } }, "description": "The event has not been joined nor interested in" } }, "security": [ { "header": [] } ] } }, "/api/v1/events/{eventId}/maybe": { "post": { "summary": "Tentatively accept invite-only event", "description": "Responds 'maybe' to the invite-only event invitation, indicating tentative attendance. Only invited users can respond.", "tags": [ "Events" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EventActionNotAllowed", "message": "Event action is not allowed" } } }, "description": "Event action is not allowed" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EventNotFound", "message": "The specified event not found" } } }, "description": "The specified event not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/events/{eventId}/mutual": { "get": { "summary": "Get mutual event attendees", "description": "Returns a list of users who are both attending the specified public event and are followed by the authenticated user.", "tags": [ "Events" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Show no more than the given number of items", "required": false, "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true } }, { "description": "An offset to show items starting from", "required": false, "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/User" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/events/{eventId}/reject": { "post": { "summary": "Reject invite-only event invitation", "description": "Declines an invitation to the invite-only event. Only invited users can reject invitations.", "tags": [ "Events" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EventActionNotAllowed", "message": "Event action is not allowed" } } }, "description": "Event action is not allowed" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EventNotFound", "message": "The specified event not found" } } }, "description": "The specified event not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/events/{eventId}/translate": { "post": { "summary": "Translate event content", "description": "Translates event title and description to the specified language. Translation is cached for future requests.", "tags": [ "Events" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "name": "lang", "in": "query", "schema": { "$ref": "#/components/schemas/Language" }, "required": true } ], "responses": { "200": { "description": "Event translation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventTranslation" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EventNotFound", "message": "The specified event not found" } } }, "description": "The specified event not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/fasp/clear": { "post": { "summary": "Clear all FASP providers", "description": "Truncates all FASP provider data including subscriptions and backfill requests. This is a destructive operation that cannot be undone. Requires Federation.Manage RBAC permission.\n\nRBAC: requires Federation.Manage", "tags": [ "FASP" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } } }, "security": [ { "header": [] } ] } }, "/api/v1/fasp/registration": { "post": { "summary": "Register a FASP provider", "description": "Initiates the FASP registration workflow. A FASP provider submits its name, base URL, server ID, and Ed25519 public key. The server generates a key pair, stores the provider, and returns the FASP ID, server public key, and a registration completion URI for admin confirmation. Blocked base URLs receive a fake success response (stealth block). No authentication required.\n\nRBAC: requires Federation.Manage", "tags": [ "FASP" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistrationRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request" } }, "security": [] } }, "/api/v1/fasp/{providerId}/capabilities": { "post": { "summary": "Update FASP provider capabilities", "description": "Updates the capabilities of a registered FASP provider. Merges new capabilities with existing ones and activates newly enabled capabilities on the remote provider by calling their activation endpoint. Requires Federation.Manage RBAC permission.\n\nRBAC: requires Federation.Manage", "tags": [ "FASP" ], "parameters": [ { "description": "ID of the FASP provider", "required": true, "name": "providerId", "in": "path", "schema": { "format": "int64", "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Capability" } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request" } }, "security": [ { "header": [] } ] } }, "/api/v1/fasp/{providerId}/debug-call": { "post": { "summary": "Send debug call to FASP provider", "description": "Sends a debug callback request to the specified FASP provider's debug endpoint. Used for testing connectivity and signature verification with the provider. Requires Federation.Manage RBAC permission.\n\nRBAC: requires Federation.Manage", "tags": [ "FASP" ], "parameters": [ { "description": "ID of the FASP provider", "required": true, "name": "providerId", "in": "path", "schema": { "format": "int64", "type": "integer" } } ], "requestBody": { "content": { "text/plain": { "schema": { "type": "string", "nullable": true } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } } }, "security": [ { "header": [] } ] } }, "/api/v1/fasp/{providerId}/request_backfill": { "post": { "summary": "Request backfill from FASP provider", "description": "Sends a backfill request to the specified FASP provider for the given content category. The remote provider will then deliver historical data back to this server. Requires Federation.Manage RBAC permission.\n\nRBAC: requires Federation.Manage", "tags": [ "FASP" ], "parameters": [ { "description": "ID of the FASP provider", "required": true, "name": "providerId", "in": "path", "schema": { "format": "int64", "type": "integer" } }, { "description": "Content category to backfill (content, account, or group)", "required": true, "name": "category", "in": "query", "schema": { "$ref": "#/components/schemas/Category" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } } }, "security": [ { "header": [] } ] } }, "/api/v1/federation/tokens": { "post": { "summary": "Issue a group federation token (server-to-server)", "description": "Issues a short-lived token for a remote user to access a specific group. The request must be signed with the user's private key using HTTP Signatures (ActivityPub). The user must be a member of the requested group. This is a server-to-server endpoint and does not require standard authentication; it relies on cryptographic HTTP signature verification.", "tags": [ "Federation" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupFederationTokenRequest" } }, "application/activity+json": { "schema": { "$ref": "#/components/schemas/GroupFederationTokenRequest" } } }, "required": true }, "responses": { "200": { "description": "Token issued successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Token" } }, "application/activity+json": { "schema": { "$ref": "#/components/schemas/Token" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "FaspIncorrectRequest", "message": "Missing signature headers" } } }, "description": "Missing signature headers" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "NotGroupMember", "message": "The user must be a member of the group" } } }, "description": "The user must be a member of the group" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "GroupNotFound", "message": "Group not found" } } }, "description": "Group not found" } }, "security": [] } }, "/api/v1/geo": { "get": { "summary": "Get address from coordinates", "description": "Performs reverse geocoding to convert latitude and longitude coordinates into a human-readable address. Requires authentication.", "tags": [ "Geo" ], "parameters": [ { "description": "Latitude coordinate in decimal degrees", "example": 40.7128, "required": true, "name": "latitude", "in": "query", "schema": { "format": "double", "type": "number" } }, { "description": "Longitude coordinate in decimal degrees", "example": -74.006, "required": true, "name": "longitude", "in": "query", "schema": { "format": "double", "type": "number" } } ], "responses": { "200": { "description": "The formatted address string corresponding to the provided coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressFromCoordinatesResponse" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "GeoCodingError", "message": "An error occurred while geocoding the address" } } }, "description": "An error occurred while geocoding the address" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/groups": { "get": { "summary": "Get current user's group memberships", "description": "Retrieves all groups that the currently authenticated user is a member of. Returns both public and private groups since the user is requesting their own memberships. Returns full Group objects with complete group details. Results are paginated. This is a convenience endpoint equivalent to calling /groups/member/{userId}/groups with your own user ID.", "tags": [ "Group Members" ], "parameters": [ { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } ], "responses": { "200": { "description": "List of groups the current user is a member of", "content": { "application/json": { "schema": { "description": "Array of Group objects for all groups the user belongs to", "type": "array", "items": { "$ref": "#/components/schemas/Group" } } } } } }, "security": [ { "header": [] } ] }, "post": { "summary": "Create a new group", "description": "Creates a new group owned by the currently authenticated user. The user becomes the group owner with full administrative privileges. The group name must be unique across the platform. A default channel is automatically created for the group.", "tags": [ "Groups" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupCreate" } } }, "required": true }, "responses": { "200": { "description": "Successfully created the new group", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group" } } } }, "400": { "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserNameIsReserved", "message": "The username is reserved and cannot be used" } } }, "description": "The username is reserved and cannot be used" } }, "security": [ { "header": [] } ] } }, "/api/v1/groups/apps": { "get": { "summary": "List all available group applications", "description": "Returns a list of all applications available at the GROUP entry point. These are the applications that any group can install. Does not require a specific group context.", "tags": [ "Group Applications" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Application" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [] } }, "/api/v1/groups/invites": { "get": { "summary": "List current user's group invitations", "description": "Returns a paginated list of all group invitations addressed to the authenticated user, optionally filtered by status. Authentication is required.", "tags": [ "Group Invitations" ], "parameters": [ { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Filter invitations by status. If omitted, returns all.", "required": false, "name": "status", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/GroupInviteStatus" } ], "nullable": true } }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } ], "responses": { "200": { "description": "List of user's group invitations", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GroupInvite" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/groups/member/{userId}": { "get": { "summary": "Get group memberships for a specific user", "description": "Retrieves all group memberships for the specified user. Privacy rules apply: requesting your own memberships returns all groups (public and private), while requesting another user's memberships returns only their public group memberships. Results are paginated.", "tags": [ "Group Members" ], "parameters": [ { "description": "The ID of the user whose memberships to retrieve", "required": true, "name": "userId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } ], "responses": { "200": { "description": "List of group memberships for the user", "content": { "application/json": { "schema": { "description": "Array of GroupMember objects containing membership details", "type": "array", "items": { "$ref": "#/components/schemas/GroupMember" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/groups/member/{userId}/groups": { "get": { "summary": "Get groups that a user is a member of", "description": "Retrieves all groups where the specified user is a member. Privacy rules apply: requesting your own groups returns all groups (public and private), while requesting another user's groups returns public groups and private groups where the viewer is also a member. Returns full Group objects rather than membership records. Results are paginated.", "tags": [ "Group Members" ], "parameters": [ { "description": "The ID of the user whose groups to retrieve", "required": true, "name": "userId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } ], "responses": { "200": { "description": "List of groups the user is a member of", "content": { "application/json": { "schema": { "description": "Array of Group objects with full group details", "type": "array", "items": { "$ref": "#/components/schemas/Group" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/groups/my-groups": { "get": { "summary": "Get all user's groups with comprehensive sorting", "description": "\n Returns user's groups in order:\n 1) pinned by pin number,\n 2) owned unpinned by creation date,\n 3) member unpinned by creation date.\n Each group includes viewer context: isMember (always true), pin (if pinned), and canManage.\n ", "tags": [ "Groups" ], "parameters": [ { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } ], "responses": { "200": { "description": "List of user's groups with sorting information and viewer context", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Group" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/groups/name/{groupname}": { "get": { "summary": "Get group by name", "description": "Retrieves a group using its unique name (slug). The group name is case-insensitive and must follow username validation rules (alphanumeric, underscores, hyphens). This endpoint is publicly accessible (@PermitAll) and is useful for human-readable URLs. Stats visibility is controlled by group settings.", "tags": [ "Groups" ], "parameters": [ { "description": "The unique group name (slug)", "example": "wine-lovers", "required": true, "name": "groupname", "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Group details retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ResourceNotFound", "message": "The requested resource not found" } } }, "description": "The requested resource not found" } }, "security": [] } }, "/api/v1/groups/owned": { "get": { "summary": "Get groups owned by current user", "description": "Retrieves all groups that were created by the currently authenticated user account. This returns groups where the user is the owner, not just a member. A single user account can own and manage multiple groups. Returns full Group objects with complete group details including private groups owned by the user. Results are paginated.", "tags": [ "Group Members" ], "parameters": [ { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } ], "responses": { "200": { "description": "List of groups owned by the current user", "content": { "application/json": { "schema": { "description": "Array of Group objects for groups owned by the current user", "type": "array", "items": { "$ref": "#/components/schemas/Group" } } } } } }, "security": [ { "header": [] } ] } }, "/api/v1/groups/pinned": { "get": { "summary": "Get user's pinned groups", "description": "Retrieve all groups pinned by the current user, ordered by pin number. Each group includes viewer context: isMember (always true), pin, and canManage.", "tags": [ "Group Pins" ], "parameters": [ { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } ], "responses": { "200": { "description": "List of pinned groups with full group details", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Group" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/groups/search": { "get": { "summary": "Search groups by name", "description": "Searches for groups whose names contain the specified substring. The search is case-insensitive. If no substring is provided or it's empty, returns all visible groups. Results respect visibility and membership: returns VISIBLE groups (public or private) and any groups the user is a member of if UNLISTED (HIDDEN groups never appear in search or listings). This endpoint is publicly accessible (@PermitAll). Results are paginated.", "tags": [ "Groups" ], "parameters": [ { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Substring to search for in group names. Case-insensitive partial match.", "example": "tech", "required": false, "name": "substring", "in": "query", "schema": { "type": "string", "nullable": true } }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } ], "responses": { "200": { "description": "List of matching groups", "content": { "application/json": { "schema": { "description": "Array of Group objects matching the search criteria", "type": "array", "items": { "$ref": "#/components/schemas/Group" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [] } }, "/api/v1/groups/users/{userId}/mutual": { "get": { "summary": "Get mutual groups with another user", "description": "Retrieves groups that both the current user and the specified user are members of. Only returns groups where both users have active memberships (MEMBER status). Useful for finding common communities and shared interests between users.", "tags": [ "Groups" ], "parameters": [ { "description": "The unique identifier of the user to find mutual groups with", "example": "us_01hz1f0kw36f82k9s4nzpc4s92n", "required": true, "name": "userId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "List of groups both users belong to", "content": { "application/json": { "schema": { "description": "Array of Group objects representing mutual memberships", "type": "array", "items": { "$ref": "#/components/schemas/Group" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ResourceNotFound", "message": "The requested resource not found" } } }, "description": "The requested resource not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/groups/{groupId}": { "put": { "summary": "Update group information", "description": "Updates the group's basic information including name, display name, description, and privacy settings. Requires GroupData.Manage permission. The group owner and administrators can perform this operation. Changes to privacy settings may affect member access and visibility.\n\nRBAC: requires GroupData.Manage", "tags": [ "Groups" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupUpdate" } } }, "required": true }, "responses": { "200": { "description": "Successfully updated the group", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ValidationError", "message": "Invalid parameters" } } }, "description": "Invalid parameters" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "ResourceNotFound": { "description": "The requested resource not found", "value": { "errorCode": "ResourceNotFound", "message": "The requested resource not found" } }, "GroupNotFound": { "description": "Group not found", "value": { "errorCode": "GroupNotFound", "message": "Group not found" } } } } }, "description": "Not Found" } }, "security": [ { "header": [] } ], "parameters": [ { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ] }, "get": { "summary": "Get group by ID", "description": "Retrieves detailed information about a specific group including metadata, settings, and upload references. Accessible for public groups without membership. Hidden groups return 404 for non-members to maintain privacy. Includes real-time statistics. Stats visibility is controlled by group settings.", "tags": [ "Groups" ], "responses": { "200": { "description": "Group details retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "GroupContextIsEmpty", "message": "Group context is not present" } } }, "description": "Group context is not present" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "ResourceNotFound": { "description": "The requested resource not found", "value": { "errorCode": "ResourceNotFound", "message": "The requested resource not found" } }, "GroupNotFound": { "description": "Group not found", "value": { "errorCode": "GroupNotFound", "message": "Group not found" } } } } }, "description": "Not Found" } }, "security": [ { "header": [] } ], "parameters": [ { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ] }, "delete": { "summary": "Delete a group", "description": "Permanently deletes a group and all associated data including memberships, roles, and channel content. This operation is irreversible. Requires the Group.Delete RBAC permission (typically group owner). The deletion is federated via ActivityPub to notify remote instances.\n\nRBAC: requires Group.Delete", "tags": [ "Groups" ], "responses": { "200": { "description": "Group successfully deleted", "content": { "application/json": { "schema": { "type": "boolean", "example": true } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "ResourceNotFound": { "description": "The requested resource not found", "value": { "errorCode": "ResourceNotFound", "message": "The requested resource not found" } }, "GroupNotFound": { "description": "Group not found", "value": { "errorCode": "GroupNotFound", "message": "Group not found" } } } } }, "description": "Not Found" } }, "security": [ { "header": [] } ], "parameters": [ { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ] } }, "/api/v1/groups/{groupId}/apps": { "get": { "summary": "List applications installed for a specific group", "description": "Returns a list of applications installed and available for the specified group. Accessible according to group visibility settings (public groups allow unauthenticated access).", "tags": [ "Group Applications" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Application" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [], "parameters": [ { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ] } }, "/api/v1/groups/{groupId}/apps/{appId}": { "delete": { "summary": "Remove application from group", "description": "Uninstalls an application from the specified group. Requires the GroupApps.Manage RBAC permission (group admin).", "tags": [ "Group Applications" ], "parameters": [ { "description": "The unique identifier of the application to remove", "required": true, "name": "appId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } }, { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ConstraintViolation", "message": "A request parameter constraint was violated" } } }, "description": "A request parameter constraint was violated" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AppNotFound", "message": "Application not found" } } }, "description": "Application not found" }, "500": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AppUpdateError", "message": "Failed to update the application" } } }, "description": "Failed to update the application" } }, "security": [] }, "put": { "summary": "Add application to group", "description": "Installs an application to the specified group, making it available for group members. Requires the GroupApps.Manage RBAC permission (group admin).", "tags": [ "Group Applications" ], "parameters": [ { "description": "The unique identifier of the application to install", "required": true, "name": "appId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } }, { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "Returns app", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Application" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ConstraintViolation", "message": "A request parameter constraint was violated" } } }, "description": "A request parameter constraint was violated" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AppNotFound", "message": "Application not found" } } }, "description": "Application not found" }, "500": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AppUpdateError", "message": "Failed to update the application" } } }, "description": "Failed to update the application" } }, "security": [] } }, "/api/v1/groups/{groupId}/blocks": { "get": { "summary": "List all blocks for a group", "tags": [ "Group Blocks" ], "parameters": [ { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "List of blocks", "content": { "application/json": {} } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "GroupNotFound", "message": "Group not found" } } }, "description": "Group not found" } }, "security": [ { "header": [] } ], "description": "RBAC: requires GroupMembers.Manage" }, "delete": { "summary": "Remove a block from a group", "tags": [ "Group Blocks" ], "parameters": [ { "description": "Block type (URI, EMAIL, DOMAIN, USERNAME, USERID)", "required": true, "name": "type", "in": "query", "schema": { "$ref": "#/components/schemas/GroupBlockType" } }, { "description": "Block value", "required": true, "name": "value", "in": "query", "schema": { "type": "string" } }, { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "Block removed successfully", "content": { "application/json": {} } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ClientError", "message": "Invalid request from client" } } }, "description": "Invalid request from client" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "GroupBlockNotFound": { "description": "Block not found", "value": { "errorCode": "GroupBlockNotFound", "message": "Block not found" } }, "GroupNotFound": { "description": "Group not found", "value": { "errorCode": "GroupNotFound", "message": "Group not found" } } } } }, "description": "Not Found" } }, "security": [ { "header": [] } ], "description": "RBAC: requires GroupMembers.Manage" }, "post": { "summary": "Block a user from joining the group", "tags": [ "Group Blocks" ], "requestBody": { "description": "Block creation request with exactly one block type specified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupBlockCreateRequest" } } }, "required": true }, "responses": { "200": { "description": "Block created successfully", "content": { "application/json": {} } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ClientError", "message": "Invalid request from client" } } }, "description": "Invalid request from client" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "GroupNotFound", "message": "Group not found" } } }, "description": "Group not found" } }, "security": [ { "header": [] } ], "description": "RBAC: requires GroupMembers.Manage", "parameters": [ { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ] } }, "/api/v1/groups/{groupId}/branding": { "put": { "summary": "Update group branding", "description": "Updates the visual branding elements of a group including color theme, banner image, and avatar. Color must be in HEX format. Banner and avatar are references to previously uploaded media. Setting banner or avatar to null removes them. Requires the GroupSettings.Manage RBAC permission (group admin).\n\nRBAC: requires GroupSettings.Manage", "tags": [ "Groups" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupBrandingUpdate" } } }, "required": true }, "responses": { "200": { "description": "Successfully updated group branding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ValidationError", "message": "Invalid parameters" } } }, "description": "Invalid parameters" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "ResourceNotFound": { "description": "The requested resource not found", "value": { "errorCode": "ResourceNotFound", "message": "The requested resource not found" } }, "GroupNotFound": { "description": "Group not found", "value": { "errorCode": "GroupNotFound", "message": "Group not found" } } } } }, "description": "Not Found" } }, "security": [ { "header": [] } ], "parameters": [ { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ] } }, "/api/v1/groups/{groupId}/channels": { "get": { "summary": "List all group channels", "description": "Retrieves a complete list of all channels within the specified group. Requires group membership to access. Returns both public and private channels visible to the authenticated user. The response includes channel metadata such as privacy settings, auto-subscribe status, and whether each channel is designated as the primary channel. Channels are returned in creation order.\n\nRBAC: requires GroupChannels.Read", "tags": [ "Group Channels" ], "parameters": [ { "description": "Filter to channels that have this app_meta namespace key (e.g. 'wellesley.group.forum')", "name": "appMetaHas", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Filter to channels that do NOT have this app_meta namespace key", "name": "appMetaLacks", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "If true return also summary, stats, header and fields. Default false.", "name": "full", "in": "query", "schema": { "type": "boolean", "nullable": true }, "required": false }, { "description": "Filter by channel kind: 'channel' for regular channels, 'category' for forum categories", "name": "kind", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/GroupChannelKind" } ], "nullable": true }, "required": false }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} }, { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "Complete list of group channels successfully retrieved", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserFull" } } } } } }, "security": [ { "header": [] } ] }, "post": { "summary": "Create a new group channel", "description": "Creates a new channel within the specified group. Requires group administrator privileges. The channel's privacy is constrained by the parent group's privacy settings (private groups can only have private channels). The first channel created is automatically designated as both primary and auto-subscribe. Channels can have both scoped usernames (group-specific) and optional global usernames (platform-wide). Note: Avatar and header images must be set via the update endpoint after creation.\n\nRBAC: requires GroupChannels.Manage", "tags": [ "Group Channels" ], "requestBody": { "content": { "application/json": { "schema": { "description": "Channel configuration including username, display name, privacy, and role settings", "allOf": [ { "$ref": "#/components/schemas/GroupChannelCreateRequest" } ] } } }, "required": true }, "responses": { "200": { "description": "Channel created successfully with all configured properties", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserFull" } } } }, "400": { "description": "Bad Request" } }, "security": [ { "header": [] } ], "parameters": [ { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} }, { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ] } }, "/api/v1/groups/{groupId}/channels/auto-subscribe": { "get": { "summary": "List auto-subscribe channels", "description": "Retrieves all channels designated as auto-subscribe for the specified group. Auto-subscribe channels are automatically followed by new members upon joining. Requires group membership to access. Returns an empty array if no auto-subscribe channels are configured. The response includes full channel information including privacy settings and follow status.\n\nRBAC: requires GroupChannels.Read", "tags": [ "Group Channels" ], "responses": { "200": { "description": "List of auto-subscribe channels successfully retrieved", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/User" } } } } } }, "security": [ { "header": [] } ], "parameters": [ { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ] } }, "/api/v1/groups/{groupId}/channels/lookup": { "get": { "summary": "Get group channel by scoped username", "description": "Retrieves a channel using its group-scoped username (slug). Useful for accessing channels without global usernames. Private channels and channels inside private groups require membership and otherwise return 404.", "tags": [ "Group Channels" ], "parameters": [ { "description": "If true return also summary, stats, header and fields. Default false.", "required": false, "name": "full", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "name": "username", "in": "query", "schema": { "description": "Channel slug unique within the group (e.g. \"news\").", "pattern": "\\S", "type": "string" }, "required": true }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} }, { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "Channel information successfully retrieved", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/User" }, { "$ref": "#/components/schemas/UserFull" } ] } } } } }, "security": [] } }, "/api/v1/groups/{groupId}/channels/primary": { "get": { "summary": "Retrieve primary channel", "description": "Retrieves the designated primary channel for the specified group. Access control is based on both group and channel privacy settings. Public groups with public primary channels are accessible to everyone. Private groups or private channels require group membership. Returns 404 if no primary channel is designated or if access is denied due to privacy settings.", "tags": [ "Group Channels" ], "responses": { "200": { "description": "Primary channel information successfully retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserFull" } } } } }, "security": [], "parameters": [ { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} }, { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ] } }, "/api/v1/groups/{groupId}/channels/public": { "get": { "summary": "List public channels", "description": "Retrieves all public channels from a public group. This endpoint is accessible to everyone, including non-members and unauthenticated users, but only works for public groups. Private groups will return an error regardless of their channels' privacy settings. Useful for discovery and browsing group content before joining. Channels with global usernames are included with their platform-wide identifiers.", "tags": [ "Group Channels" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/User" } } } } } }, "security": [], "parameters": [ { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ] } }, "/api/v1/groups/{groupId}/channels/{channelId}": { "put": { "summary": "Update an existing group channel", "description": "Modifies properties of an existing channel. Requires group administrator privileges. Only included fields are updated; null fields preserve existing values. Privacy changes are constrained by the parent group's privacy (cannot make a channel public in a private group). Changes to auto-subscribe status affect auto-follow behavior for new members.\n\nRBAC: requires GroupChannels.Manage", "tags": [ "Group Channels" ], "parameters": [ { "description": "The unique identifier of the channel to update", "required": true, "name": "channelId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} }, { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Fields to modify. Omit fields to preserve current values.", "allOf": [ { "$ref": "#/components/schemas/GroupChannelUpdateRequest" } ] } } }, "required": true }, "responses": { "200": { "description": "Channel properties updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserFull" } } } }, "400": { "description": "Bad Request" } }, "security": [ { "header": [] } ] }, "get": { "summary": "Get group channel by id", "description": "Retrieves a channel within the current group by its identifier. Access to private channels (or channels in private groups) is restricted to group members; outsiders receive a 404.", "tags": [ "Group Channels" ], "parameters": [ { "description": "The unique identifier of the channel to retrieve", "required": true, "name": "channelId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "If true return also summary, stats, header and fields. Default false.", "name": "full", "in": "query", "schema": { "type": "boolean", "nullable": true }, "required": false }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} }, { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "Channel information successfully retrieved", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/User" }, { "$ref": "#/components/schemas/UserFull" } ] } } } } }, "security": [] }, "delete": { "summary": "Delete a group channel", "description": "Removes the specified channel from the group. Requires group administrator privileges. The channel is marked as deleted immediately and background workers handle cleanup of posts, media, and follower relationships.\n\nRBAC: requires GroupChannels.Manage", "tags": [ "Group Channels" ], "parameters": [ { "description": "The unique identifier of the channel to delete", "required": true, "name": "channelId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } }, { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } } }, "security": [ { "header": [] } ] } }, "/api/v1/groups/{groupId}/channels/{channelId}/auto-subscribe": { "put": { "summary": "Update channel auto-subscribe status", "description": "Toggles whether a channel is designated as an auto-subscribe channel. Requires group admin privileges. Auto-subscribe channels are automatically followed by new group members upon joining. Multiple channels can be marked as auto-subscribe. This setting helps onboard new members by ensuring they receive content from essential channels immediately.\n\nRBAC: requires GroupChannels.Manage", "tags": [ "Group Channels" ], "parameters": [ { "name": "channelId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "name": "isAutoSubscribe", "in": "query", "schema": { "description": "Whether to mark as auto-subscribe (true) or remove status (false)", "default": true, "type": "boolean", "nullable": true }, "required": false }, { "name": "subscribeExistingMembers", "in": "query", "schema": { "description": "Subscribe existing members when enabling auto-subscribe", "default": true, "type": "boolean", "nullable": true }, "required": false }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} }, { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "Auto-subscribe channel status successfully updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserFull" } } } } }, "security": [ { "header": [] } ] } }, "/api/v1/groups/{groupId}/channels/{channelId}/primary": { "put": { "summary": "Designate channel as primary", "description": "Sets the specified channel as the primary channel for the group. Requires group administrator privileges. Only one channel can be designated as primary per group. The primary channel serves as the main communication channel and is prominently displayed in group interfaces. Any existing primary channel designation is automatically removed.\n\nRBAC: requires GroupChannels.Manage", "tags": [ "Group Channels" ], "parameters": [ { "description": "The unique identifier of the channel to designate as primary", "required": true, "name": "channelId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} }, { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "Channel successfully designated as primary, previous primary channel designation removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserFull" } } } } }, "security": [ { "header": [] } ] } }, "/api/v1/groups/{groupId}/channels/{channelId}/username": { "put": { "summary": "Assign or update global username", "description": "Assigns, updates, or removes a global username for a public channel. Requires group administrator privileges. Global usernames provide platform-wide discovery and must be unique across the entire system. Only public channels in public groups can have global usernames. Setting the username to null removes any existing global username assignment.\n\nRBAC: requires GroupChannels.Manage", "tags": [ "Group Channels" ], "parameters": [ { "description": "The unique identifier of the channel", "required": true, "name": "channelId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} }, { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "global username to assign or null to remove", "allOf": [ { "$ref": "#/components/schemas/AssignGlobalUsernameRequest" } ] } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserFull" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "GroupContextIsEmpty": { "description": "Group context is not present", "value": { "errorCode": "GroupContextIsEmpty", "message": "Group context is not present" } }, "InvalidActorType": { "description": "Invalid actor type for a user or channel", "value": { "errorCode": "InvalidActorType", "message": "Invalid actor type for a user or channel" } } } } }, "description": "Bad Request" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "Forbidden", "message": "No access to the resource" } } }, "description": "No access to the resource" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "GroupNotFound": { "description": "Group not found", "value": { "errorCode": "GroupNotFound", "message": "Group not found" } }, "UserNotFound": { "description": "User not found", "value": { "errorCode": "UserNotFound", "message": "User not found" } } } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserNameExists", "message": "The username is already in use" } } }, "description": "The username is already in use" }, "500": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ServerError", "message": "An unexpected server error occurred" } } }, "description": "An unexpected server error occurred" } }, "security": [ { "header": [] } ] } }, "/api/v1/groups/{groupId}/details": { "get": { "summary": "Get group details with membership info", "description": "\n Retrieves group details combined with the viewer's membership information.\n For remote (federated) groups, refreshes data from the remote server if stale.\n\n The response includes:\n - Full group information (same as GET /groups/{groupId})\n - Viewer's membership state (MEMBER, PENDING_JOIN, PENDING_INVITE, or NONE)\n - Related objects (membership details, join request, or pending invite)\n\n This endpoint is useful for displaying group pages where the viewer's\n relationship to the group is relevant, such as showing Accept/Reject\n buttons for pending invites.\n ", "tags": [ "Groups" ], "responses": { "200": { "description": "Group details with membership info retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupWithMembership" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "NotGroupMember": { "description": "The user must be a member of the group", "value": { "errorCode": "NotGroupMember", "message": "The user must be a member of the group" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "GroupNotFound", "message": "Group not found" } } }, "description": "Group not found" } }, "security": [ { "header": [] } ], "parameters": [ { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ] } }, "/api/v1/groups/{groupId}/federation-token": { "post": { "summary": "Request a federation token for a remote group", "description": "Proxies a federation token request to a remote group server. The server signs the request on behalf of the authenticated user using HTTP Signatures. Returns a short-lived token that can be used for direct API calls to the remote group server. Only works for remote (federated) groups; local groups return an error. The user must be a member of the target group. Authentication is required.", "tags": [ "Federation" ], "responses": { "200": { "description": "Token issued successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Token" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "GroupIsLocal", "message": "Cannot proxy token request for local group - use regular authentication" } } }, "description": "Cannot proxy token request for local group - use regular authentication" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "NotGroupMember", "message": "The user must be a member of the group" } } }, "description": "The user must be a member of the group" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "GroupNotFound", "message": "Group not found" } } }, "description": "Group not found" }, "502": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "RemoteServerError", "message": "Remote server returned an error" } } }, "description": "Remote server returned an error" } }, "security": [ { "header": [] } ], "parameters": [ { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ] } }, "/api/v1/groups/{groupId}/feed": { "get": { "summary": "Get group feed", "description": "Returns a merged feed of posts across channels in the group. Members with channel subscriptions see posts from subscribed channels only. Non-members or members without subscriptions see posts from all public channels. Use allChannels=true to bypass subscription gating and show all accessible channels. Post visibility otherwise follows the standard post privacy rules.", "tags": [ "Groups" ], "parameters": [ { "description": "When true, show posts from all accessible channels instead of only subscribed ones. Members see all channels (public + private); non-members still see only public channels.", "name": "allChannels", "in": "query", "schema": { "type": "boolean", "nullable": true }, "required": false }, { "description": "Include bookmark field", "name": "includeBookmarkStatus", "in": "query", "schema": { "type": "boolean", "nullable": true }, "required": false }, { "description": "Include comments in feed", "name": "includeComments", "in": "query", "schema": { "type": "boolean", "nullable": true }, "required": false }, { "description": "Include follow status", "name": "includeFollowStatus", "in": "query", "schema": { "type": "boolean", "nullable": true }, "required": false }, { "description": "Include publisher context", "name": "includePublisher", "in": "query", "schema": { "type": "boolean", "nullable": true }, "required": false }, { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "Only include posts from channels that have this app_meta namespace key (e.g. 'wellesley.group.forum' for forum categories)", "name": "ownerAppMetaHas", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Exclude posts from channels that have this app_meta namespace key", "name": "ownerAppMetaLacks", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Filter by channel kind: 'channel' for regular channels, 'category' for forum categories. Preferred over ownerAppMetaHas/ownerAppMetaLacks for kind-based filtering.", "name": "ownerChannelKind", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/GroupChannelKind" } ], "nullable": true }, "required": false }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "Include repostedBy", "name": "withRepostedBy", "in": "query", "schema": { "type": "boolean", "nullable": true }, "required": false }, { "description": "Include translation", "name": "withTranslation", "in": "query", "schema": { "type": "boolean", "nullable": true }, "required": false }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} }, { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "GroupNotFound", "message": "Group not found" } } }, "description": "Group not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/groups/{groupId}/invite": { "get": { "summary": "Get current user's invitation for a group", "description": "Retrieves the invitation for the authenticated user in the specified group, regardless of status. Returns 404 if no invitation exists. Authentication is required.", "tags": [ "Group Invitations" ], "responses": { "200": { "description": "The group invitation details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupInvite" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "GroupNotFound": { "description": "Group not found", "value": { "errorCode": "GroupNotFound", "message": "Group not found" } }, "GroupInviteNotFound": { "description": "Group invite not found", "value": { "errorCode": "GroupInviteNotFound", "message": "Group invite not found" } } } } }, "description": "Not Found" } }, "security": [ { "header": [] } ], "parameters": [ { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ] } }, "/api/v1/groups/{groupId}/invites": { "get": { "summary": "List invitations for a group", "description": "Returns a paginated list of invitations for the specified group, optionally filtered by status. Requires the GroupMembers.Invite RBAC permission (group admin/owner). Authentication is required.\n\nRBAC: requires GroupMembers.Invite", "tags": [ "Group Invitations" ], "parameters": [ { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Filters invitations by status. If omitted, returns all.", "required": false, "name": "status", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/GroupInviteStatus" } ], "nullable": true } }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "List of group invitations", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GroupInvite" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "RBACInsufficientPermissions": { "description": "Insufficient permissions to perform this operation", "value": { "errorCode": "RBACInsufficientPermissions", "message": "Insufficient permissions to perform this operation" } }, "NotGroupMember": { "description": "The user must be a member of the group", "value": { "errorCode": "NotGroupMember", "message": "The user must be a member of the group" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "GroupNotFound", "message": "Group not found" } } }, "description": "Group not found" } }, "security": [ { "header": [] } ] }, "post": { "summary": "Invite a user to join a group", "description": "\n Creates an invitation for a user to join the group. Only group owners and admins can create invitations.\n The invitee must not already be a member of the group or have a pending invitation.\n Exactly one of inviteeId or inviteeEmail must be provided.\n\n The response contains the created invite and an emailSent flag indicating whether\n an invitation email was sent from this server (false for remote users, whose home server sends the email).\n\nRBAC: requires GroupMembers.Invite", "tags": [ "Group Invitations" ], "requestBody": { "description": "Invitation details", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupInviteCreate" } } } }, "responses": { "200": { "description": "Invitation created successfully or email sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupInviteCreateResult" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "GroupInviteInvalidRequest", "message": "Provide exactly one of: inviteeId or inviteeEmail" } } }, "description": "Provide exactly one of: inviteeId or inviteeEmail" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "RBACInsufficientPermissions": { "description": "Insufficient permissions to perform this operation", "value": { "errorCode": "RBACInsufficientPermissions", "message": "Insufficient permissions to perform this operation" } }, "NotGroupMember": { "description": "The user must be a member of the group", "value": { "errorCode": "NotGroupMember", "message": "The user must be a member of the group" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "GroupNotFound": { "description": "Group not found", "value": { "errorCode": "GroupNotFound", "message": "Group not found" } }, "UserNotFound": { "description": "User not found", "value": { "errorCode": "UserNotFound", "message": "User not found" } } } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "GroupAlreadyMember": { "description": "User is already a member of this group", "value": { "errorCode": "GroupAlreadyMember", "message": "User is already a member of this group" } }, "GroupInviteAlreadyExists": { "description": "User already has a pending invite to this group", "value": { "errorCode": "GroupInviteAlreadyExists", "message": "User already has a pending invite to this group" } } } } }, "description": "Conflict" } }, "security": [ { "header": [] } ], "parameters": [ { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ] } }, "/api/v1/groups/{groupId}/invites/accept": { "post": { "summary": "Accept invitation to a group", "description": "\n Accepts an invitation to join a local group. The user becomes a member with the VIEWER role.\n The pending invite is looked up by (groupId, authenticated user).\n\n Note: This endpoint is for local groups only. For remote (federated) groups, invite records\n are not stored locally - the client should call the remote server directly with a GroupFederationToken.\n ", "tags": [ "Group Invitations" ], "responses": { "200": { "description": "Invitation accepted, user is now a group member", "content": { "application/json": { "schema": { "description": "The newly created membership record", "required": [ "groupName", "groupDisplayName", "username", "displayName", "groupId", "memberId" ], "type": "object", "properties": { "groupName": { "description": "Group name", "type": "string" }, "groupDisplayName": { "description": "Group display name", "type": "string" }, "username": { "description": "User name (username)", "type": "string" }, "displayName": { "description": "User display name", "type": "string" }, "domain": { "description": "User domain", "type": "string", "nullable": true }, "local": { "description": "Whether the user is local or not", "type": "boolean" }, "groupAvatar": { "description": "Group avatar upload object", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Upload" } ], "nullable": true }, "userAvatar": { "description": "User avatar upload object", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Upload" } ], "nullable": true }, "groupId": { "description": "Group ID", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "memberId": { "description": "User who is a member of the group", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "roles": { "description": "\n All role identifiers for this member in the group.\n Includes both predefined roles (owner, admin, moderator, member, viewer)\n and custom roles.\n ", "type": "array", "items": { "type": "string" } }, "meta": { "description": "Additional metadata about this membership", "type": "object", "allOf": [ { "$ref": "#/components/schemas/GroupMemberMeta" } ], "nullable": true }, "createdAt": { "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true }, "updatedAt": { "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "GroupIsRemote", "message": "Operation is not available for remote groups - use the group's home server directly" } } }, "description": "Operation is not available for remote groups - use the group's home server directly" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "GroupInviteNotFound", "message": "Group invite not found" } } }, "description": "Group invite not found" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "GroupInviteNotPending", "message": "Group invite is not in pending status" } } }, "description": "Group invite is not in pending status" } }, "security": [ { "header": [] } ], "parameters": [ { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ] } }, "/api/v1/groups/{groupId}/invites/reject": { "post": { "summary": "Reject invitation to a group", "description": "\n Rejects an invitation to join a local group. The invitation status will be updated to REJECTED.\n The pending invite is looked up by (groupId, authenticated user).\n\n Note: This endpoint is for local groups only. For remote (federated) groups, invite records\n are not stored locally - the client should call the remote server directly with a GroupFederationToken.\n ", "tags": [ "Group Invitations" ], "responses": { "200": { "description": "Invitation rejected successfully", "content": { "application/json": { "schema": { "description": "True when invitation is successfully rejected", "type": "boolean" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "GroupIsRemote", "message": "Operation is not available for remote groups - use the group's home server directly" } } }, "description": "Operation is not available for remote groups - use the group's home server directly" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "GroupInviteNotFound", "message": "Group invite not found" } } }, "description": "Group invite not found" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "GroupInviteNotPending", "message": "Group invite is not in pending status" } } }, "description": "Group invite is not in pending status" } }, "security": [ { "header": [] } ], "parameters": [ { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ] } }, "/api/v1/groups/{groupId}/invites/{groupInviteId}": { "delete": { "summary": "Cancel a group invitation", "description": "Requires GroupMembers.Invite permission (group owner/admin). The invitation must be in PENDING status.\n\nRBAC: requires GroupMembers.Invite", "tags": [ "Group Invitations" ], "parameters": [ { "description": "The unique identifier of the group invitation", "required": true, "name": "groupInviteId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } }, { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "Invitation cancelled successfully", "content": { "application/json": { "schema": { "type": "boolean" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "RBACInsufficientPermissions": { "description": "Insufficient permissions to perform this operation", "value": { "errorCode": "RBACInsufficientPermissions", "message": "Insufficient permissions to perform this operation" } }, "NotGroupMember": { "description": "The user must be a member of the group", "value": { "errorCode": "NotGroupMember", "message": "The user must be a member of the group" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "GroupNotFound": { "description": "Group not found", "value": { "errorCode": "GroupNotFound", "message": "Group not found" } }, "GroupInviteNotFound": { "description": "Group invite not found", "value": { "errorCode": "GroupInviteNotFound", "message": "Group invite not found" } } } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "GroupInviteNotPending", "message": "Group invite is not in pending status" } } }, "description": "Group invite is not in pending status" } }, "security": [ { "header": [] } ] } }, "/api/v1/groups/{groupId}/join": { "post": { "summary": "Join a group", "description": "\n Request to join a group. The behavior depends on the group's join mode:\n OPEN groups accept members immediately with MEMBER role, APPROVAL groups create a PENDING join request\n requiring admin approval, and INVITE_ONLY groups require an invitation. Groups may also have\n entry questions that require a valid answerToken from completing the group's questionnaire.\n Users cannot join a group they're already a member of.\n ", "tags": [ "Group Join" ], "parameters": [ { "description": "\n Token received after successfully answering group entry questions.\n Required only for groups with entry questions when joinQuestions.show is true.\n ", "example": "tk_abc123def456", "required": false, "name": "answerToken", "in": "query", "schema": { "type": "string", "nullable": true } }, { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "Successfully joined the group (OPEN mode) or join request submitted (APPROVAL mode)", "content": { "application/json": { "schema": { "description": "MembershipInfo with state=MEMBER for OPEN mode, state=PENDING_JOIN for APPROVAL mode", "required": [ "state" ], "type": "object", "properties": { "state": { "description": "The current state of the user's relationship with the group", "type": "string", "allOf": [ { "$ref": "#/components/schemas/MembershipState" } ] }, "member": { "description": "The membership object, present if state is MEMBER", "type": "object", "allOf": [ { "$ref": "#/components/schemas/GroupMember" } ], "nullable": true }, "joinRequest": { "description": "The join request object, present if state is PENDING_JOIN", "type": "object", "allOf": [ { "$ref": "#/components/schemas/GroupJoinRequest" } ], "nullable": true }, "invite": { "description": "The invite object, present if state is PENDING_INVITE", "type": "object", "allOf": [ { "$ref": "#/components/schemas/GroupInvite" } ], "nullable": true } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "ClientError": { "description": "Invalid request from client", "value": { "errorCode": "ClientError", "message": "Invalid request from client" } }, "InvalidQuestion": { "description": "Invalid question provided", "value": { "errorCode": "InvalidQuestion", "message": "Invalid question provided" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "ResourceNotFound": { "description": "The requested resource not found", "value": { "errorCode": "ResourceNotFound", "message": "The requested resource not found" } }, "GroupNotFound": { "description": "Group not found", "value": { "errorCode": "GroupNotFound", "message": "Group not found" } } } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "GroupMembershipLimitExceeded": { "description": "Group has reached its maximum member limit", "value": { "errorCode": "GroupMembershipLimitExceeded", "message": "Group has reached its maximum member limit" } }, "GroupAlreadyMember": { "description": "User is already a member of this group", "value": { "errorCode": "GroupAlreadyMember", "message": "User is already a member of this group" } }, "GroupInviteOnlyMode": { "description": "This group is invite-only and requires an invitation to join", "value": { "errorCode": "GroupInviteOnlyMode", "message": "This group is invite-only and requires an invitation to join" } } } } }, "description": "Conflict" } }, "security": [ { "header": [] } ] }, "delete": { "summary": "Cancel group join request", "description": "\n Cancel a join request for a group. This allows users to withdraw their request\n to join a group that requires approval. Only the user who made\n the original join request can cancel it.\n ", "tags": [ "Group Join" ], "responses": { "200": { "description": "Successfully canceled join request", "content": { "application/json": { "schema": { "description": "Always returns true when join request is successfully canceled", "type": "boolean", "example": true } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "ResourceNotFound": { "description": "The requested resource not found", "value": { "errorCode": "ResourceNotFound", "message": "The requested resource not found" } }, "GroupNotFound": { "description": "Group not found", "value": { "errorCode": "GroupNotFound", "message": "Group not found" } } } } }, "description": "Not Found" } }, "security": [ { "header": [] } ], "parameters": [ { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ] } }, "/api/v1/groups/{groupId}/join-requests": { "get": { "summary": "List join requests for a group", "description": "\n Get a list of join requests for a group with optional filtering by status, username, and date range.\n Only group admins can access this endpoint\n\nRBAC: requires GroupMembers.Manage", "tags": [ "Group Join" ], "parameters": [ { "description": "Filter by creation date (start, like: 2025-01-01), inclusive", "required": false, "name": "createdFrom", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/LocalDate" } ], "nullable": true } }, { "description": "Filter by creation date (end, like: 2025-01-01), inclusive", "required": false, "name": "createdTo", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/LocalDate" } ], "nullable": true } }, { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Filter requests by status. If omitted, returns all requests.", "required": false, "name": "status", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/GroupJoinRequestStatus" } ], "nullable": true } }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "Filter by username (case-insensitive exact match)", "required": false, "name": "username", "in": "query", "schema": { "type": "string", "nullable": true } }, { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "description": "Response with items array, grandTotal (unfiltered), and total (filtered) counts", "required": [ "requests", "grandTotal", "total" ], "type": "object", "properties": { "requests": { "description": "Array of group join request objects", "type": "array", "items": { "$ref": "#/components/schemas/GroupJoinRequest" } }, "grandTotal": { "format": "int32", "description": "Total number of join requests for the specified group (no filters applied)", "type": "integer" }, "total": { "format": "int32", "description": "Total number of join requests matching the applied filters", "type": "integer" } } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "GroupNotFound", "message": "Group not found" } } }, "description": "Group not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/groups/{groupId}/join-requests/{groupJoinRequestId}": { "delete": { "summary": "Reject or delete a join request", "description": "\n Reject a user's join request for a group. By default, this marks the request as REJECTED.\n If purge=true is passed, the request is permanently deleted from the database.\n Only group admins can reject/delete join requests.\n\nRBAC: requires GroupMembers.Manage", "tags": [ "Group Join" ], "parameters": [ { "description": "The unique identifier of the join request to reject", "required": true, "name": "groupJoinRequestId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "If true, permanently delete the request", "required": false, "name": "purge", "in": "query", "schema": { "type": "boolean" } }, { "description": "Optional reason for rejecting the request", "required": false, "name": "reason", "in": "query", "schema": { "type": "string", "nullable": true } }, { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "Successfully rejected or deleted join request", "content": { "application/json": { "schema": { "description": "True if the request was successfully rejected or deleted", "type": "boolean", "example": true } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ClientError", "message": "Invalid request from client" } } }, "description": "Invalid request from client" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "ResourceNotFound": { "description": "The requested resource not found", "value": { "errorCode": "ResourceNotFound", "message": "The requested resource not found" } }, "GroupJoinRequestNotFound": { "description": "Group join request not found", "value": { "errorCode": "GroupJoinRequestNotFound", "message": "Group join request not found" } } } } }, "description": "Not Found" } }, "security": [ { "header": [] } ] }, "put": { "summary": "Approve a join request", "description": "\n Approve a join request for a group. This converts the request\n into an active group membership with MEMBER role. Only group admins can approve join requests.\n\nRBAC: requires GroupMembers.Manage", "tags": [ "Group Join" ], "parameters": [ { "description": "The unique identifier of the join request to approve", "required": true, "name": "groupJoinRequestId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Optional reason for approving the request", "required": false, "name": "reason", "in": "query", "schema": { "type": "string", "nullable": true } }, { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "Successfully approved join request", "content": { "application/json": { "schema": { "description": "The approved membership record with MEMBER role and active status", "required": [ "groupName", "groupDisplayName", "username", "displayName", "groupId", "memberId" ], "type": "object", "properties": { "groupName": { "description": "Group name", "type": "string" }, "groupDisplayName": { "description": "Group display name", "type": "string" }, "username": { "description": "User name (username)", "type": "string" }, "displayName": { "description": "User display name", "type": "string" }, "domain": { "description": "User domain", "type": "string", "nullable": true }, "local": { "description": "Whether the user is local or not", "type": "boolean" }, "groupAvatar": { "description": "Group avatar upload object", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Upload" } ], "nullable": true }, "userAvatar": { "description": "User avatar upload object", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Upload" } ], "nullable": true }, "groupId": { "description": "Group ID", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "memberId": { "description": "User who is a member of the group", "type": "string", "allOf": [ { "$ref": "#/components/schemas/TypeId" } ] }, "roles": { "description": "\n All role identifiers for this member in the group.\n Includes both predefined roles (owner, admin, moderator, member, viewer)\n and custom roles.\n ", "type": "array", "items": { "type": "string" } }, "meta": { "description": "Additional metadata about this membership", "type": "object", "allOf": [ { "$ref": "#/components/schemas/GroupMemberMeta" } ], "nullable": true }, "createdAt": { "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true }, "updatedAt": { "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ClientError", "message": "Invalid request from client" } } }, "description": "Invalid request from client" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ResourceNotFound", "message": "The requested resource not found" } } }, "description": "The requested resource not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/groups/{groupId}/member-settings": { "put": { "summary": "Update member's personal settings for a group", "description": "Updates one or more of the current member's personal settings within the specified group. Multiple settings can be updated in a single request. Complete setting objects must be provided - partial updates of individual settings are not supported. Members can only update their own settings and must be active members of the group. Changes take effect immediately.", "tags": [ "Group Member Settings" ], "requestBody": { "description": "settings objects to be updated. complete objects must be provided - partial updates are not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupMemberSettings" } } }, "required": true }, "responses": { "200": { "description": "Update confirmation with count of successfully updated settings", "content": { "application/json": { "example": { "updated": 3 } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "SettingsInvalidKeyProvided": { "description": "Unknown settings key(s) %s", "value": { "errorCode": "SettingsInvalidKeyProvided", "message": "Unknown settings key(s) %s" } }, "SettingsKeyNotProvided": { "description": "No settings keys were provided", "value": { "errorCode": "SettingsKeyNotProvided", "message": "No settings keys were provided" } }, "SettingsValuesNotProvided": { "description": "No settings values were provided", "value": { "errorCode": "SettingsValuesNotProvided", "message": "No settings values were provided" } }, "SettingsPartialUpdateNotAllowed": { "description": "Partial updates are not allowed: %s", "value": { "errorCode": "SettingsPartialUpdateNotAllowed", "message": "Partial updates are not allowed: %s" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "SettingsForbidden", "message": "Access denied for settings" } } }, "description": "Access denied for settings" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "GroupNotFound", "message": "Group not found" } } }, "description": "Group not found" }, "500": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "SettingsNotUpdated", "message": "Failed to update settings" } } }, "description": "Failed to update settings" } }, "security": [ { "header": [] } ], "parameters": [ { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ] }, "get": { "summary": "Get member's personal settings for a group", "description": "Retrieves the current member's personal settings within the specified group. Returns a JSON object with setting keys mapped to their values. Members can only access their own settings and must be active members of the group. Settings control member-specific preferences like notification preferences, display options, and personal configurations within the group context.", "tags": [ "Group Member Settings" ], "parameters": [ { "description": "Comma-separated list of setting keys to retrieve. Keys must be valid group member setting identifiers.\n\nAvailable keys are:\n\n```group.member.display```\n\n```group.member.preferences```", "name": "keys", "required": true, "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "example": "group.member.display,group.member.preferences" }, { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/GroupMemberSettings" } ] } } }, "description": "Response GroupMemberSettings" }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "SettingsInvalidKeyProvided": { "description": "Unknown settings key(s) %s", "value": { "errorCode": "SettingsInvalidKeyProvided", "message": "Unknown settings key(s) %s" } }, "SettingsKeyNotProvided": { "description": "No settings keys were provided", "value": { "errorCode": "SettingsKeyNotProvided", "message": "No settings keys were provided" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "SettingsForbidden", "message": "Access denied for settings" } } }, "description": "Access denied for settings" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "GroupNotFound", "message": "Group not found" } } }, "description": "Group not found" } }, "security": [ { "header": [] } ] }, "delete": { "summary": "Delete member's personal settings for a group", "description": "Deletes one or more of the current member's personal settings within the specified group, reverting them to default values. Multiple settings can be deleted in a single request. Members can only delete their own settings and must be active members of the group. After deletion, the settings will use system or group defaults.", "tags": [ "Group Member Settings" ], "parameters": [ { "description": "Comma-separated list of setting keys to delete. Keys must be valid group member setting identifiers.\n\nAvailable keys are:\n\n```group.member.display```\n\n```group.member.preferences```", "name": "keys", "required": true, "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "example": "group.member.display,group.member.preferences" }, { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "Deletion confirmation with count of successfully deleted settings", "content": { "application/json": { "example": { "deleted": 3 } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "SettingsKeyNotProvided": { "description": "No settings keys were provided", "value": { "errorCode": "SettingsKeyNotProvided", "message": "No settings keys were provided" } }, "SettingsInvalidKeyProvided": { "description": "Unknown settings key(s) %s", "value": { "errorCode": "SettingsInvalidKeyProvided", "message": "Unknown settings key(s) %s" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "SettingsForbidden", "message": "Access denied for settings" } } }, "description": "Access denied for settings" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "GroupNotFound", "message": "Group not found" } } }, "description": "Group not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/groups/{groupId}/members": { "get": { "summary": "Get all members of a group", "description": "\n Retrieves the list of all members in the specified group as GroupMember objects.\n Public groups are accessible to all authenticated users, Private groups accessible to members only.\n Supports sorting by join time, posts, relationship to current user, domain, displayName, username, createdAfter, or entityType.\n Supports filtering by role, domain, displayName, username, createdAfter, and entityType.\n Supports pagination. If no filter parameters are provided, returns all members.\n ", "tags": [ "Group Members" ], "parameters": [ { "description": "Filter members who joined after this date", "required": false, "name": "createdAfter", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true } }, { "description": "Display name to filter by (contains match)", "required": false, "name": "displayName", "in": "query", "schema": { "type": "string", "nullable": true } }, { "description": "Domain to filter by (contains match)", "required": false, "name": "domain", "in": "query", "schema": { "type": "string", "nullable": true } }, { "description": "Entity type to filter by (USER, BOT, APPLICATION, GROUP_CHANNEL)", "required": false, "name": "entityType", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/EntityType" } ], "nullable": true } }, { "description": "Maximum number of members to return. Defaults to 100.", "required": false, "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true } }, { "description": "Number of members to skip (for pagination). Defaults to 0.", "required": false, "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true } }, { "description": "Sort order (case-insensitive)", "required": false, "name": "order", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/SortOrder" } ], "nullable": true } }, { "description": "Role filter (case-insensitive)", "required": false, "name": "role", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/GroupMemberRoleFilter" } ], "nullable": true } }, { "description": "Sort field (case-insensitive)", "required": false, "name": "sort", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/GroupMembersSortBy" } ], "nullable": true } }, { "description": "Username to filter by (contains match)", "required": false, "name": "username", "in": "query", "schema": { "type": "string", "nullable": true } }, { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "List of group members with their membership details", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GroupMember" } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "GroupContextIsEmpty", "message": "Group context is not present" } } }, "description": "Group context is not present" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "GroupNoPublicAccess": { "description": "The group must be public or the requesting user must be a member of the group", "value": { "errorCode": "GroupNoPublicAccess", "message": "The group must be public or the requesting user must be a member of the group" } }, "NotGroupMember": { "description": "The user must be a member of the group", "value": { "errorCode": "NotGroupMember", "message": "The user must be a member of the group" } }, "GroupMemberListNotPublic": { "description": "Group member list is not visible to non-members", "value": { "errorCode": "GroupMemberListNotPublic", "message": "Group member list is not visible to non-members" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "GroupNotFound", "message": "Group not found" } } }, "description": "Group not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/groups/{groupId}/members/search": { "get": { "summary": "Admin-level search for group members", "description": "\n Performs an administrative search for group members with multiple filter criteria.\n Requires GroupMembers.Moderate permission. Can search by roles, actor type, status, country,\n domain, display name, username, IP address, or join date. Supports sorting by join time,\n display name, username, number of posts, or country. Results include detailed member\n information including statistics, last activity, and location data.\n\nRBAC: requires GroupMembers.Moderate", "tags": [ "Group Members" ], "parameters": [ { "description": "Country code to filter by (ISO 3166-1 alpha-2)", "required": false, "name": "country", "in": "query", "schema": { "type": "string", "nullable": true } }, { "description": "Filter members who joined after this date", "required": false, "name": "createdAfter", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true } }, { "description": "Display name to filter by (contains match)", "required": false, "name": "displayName", "in": "query", "schema": { "type": "string", "nullable": true } }, { "description": "Domain to filter by (contains match)", "required": false, "name": "domain", "in": "query", "schema": { "type": "string", "nullable": true } }, { "description": "Entity type to filter by (USER, BOT, APPLICATION, GROUP_CHANNEL)", "required": false, "name": "entityType", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/EntityType" } ], "nullable": true } }, { "description": "IP address to filter by", "required": false, "name": "ip", "in": "query", "schema": { "type": "string", "nullable": true } }, { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "Role filter: ADMIN for admin roles, MEMBER for regular members", "required": false, "name": "role", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/GroupMemberRoleFilter" } ], "nullable": true } }, { "description": "List of roles to filter by (comma-separated)", "required": false, "name": "roles", "in": "query", "schema": { "type": "array", "items": { "type": "string" }, "nullable": true } }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "Username to filter by (contains match)", "required": false, "name": "username", "in": "query", "schema": { "type": "string", "nullable": true } }, { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "Paginated list of group member search results with total count", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupMemberSearchDetails" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "GroupContextIsEmpty": { "description": "Group context is not present", "value": { "errorCode": "GroupContextIsEmpty", "message": "Group context is not present" } }, "SortingError": { "description": "Sort field is not supported", "value": { "errorCode": "SortingError", "message": "Sort field is not supported" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "GroupNotFound", "message": "Group not found" } } }, "description": "Group not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/groups/{groupId}/members/{memberId}": { "put": { "summary": "Update an existing group member", "description": "Updates the role, status, or metadata of an existing group member. For local groups, the update is applied immediately. For federated groups, an ActivityPub message is sent to the remote server to request the update. Requires GroupMembers.Manage permission for the target group.\n\nRBAC: requires GroupMembers.Manage", "tags": [ "Group Members" ], "parameters": [ { "description": "The ID of the user whose membership is being updated", "required": true, "name": "memberId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } }, { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupMemberUpdate" } } }, "required": true }, "responses": { "200": { "description": "Successfully updated the group member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupMember" } } } }, "400": { "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "ResourceNotFound": { "description": "The requested resource not found", "value": { "errorCode": "ResourceNotFound", "message": "The requested resource not found" } }, "GroupNotFound": { "description": "Group not found", "value": { "errorCode": "GroupNotFound", "message": "Group not found" } } } } }, "description": "Not Found" } }, "security": [ { "header": [] } ] }, "delete": { "summary": "Remove a member from a group", "description": "Removes the specified user from the group. For local groups, the membership is deleted immediately. For federated groups, an ActivityPub message is sent to request removal. Requires GroupMembers.Manage permission. An optional reason can be provided for audit logging.\n\nRBAC: requires GroupMembers.Manage", "tags": [ "Group Members" ], "parameters": [ { "description": "The ID of the user to remove from the group", "required": true, "name": "memberId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Optional reason for removing the member. This will be recorded in the audit log for accountability and compliance purposes.", "example": "Violation of community guidelines", "required": false, "name": "reason", "in": "query", "schema": { "type": "string", "nullable": true } }, { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "Member successfully removed from the group", "content": { "application/json": { "schema": { "type": "boolean", "example": true } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "ResourceNotFound": { "description": "The requested resource not found", "value": { "errorCode": "ResourceNotFound", "message": "The requested resource not found" } }, "GroupNotFound": { "description": "Group not found", "value": { "errorCode": "GroupNotFound", "message": "Group not found" } } } } }, "description": "Not Found" } }, "security": [ { "header": [] } ] } }, "/api/v1/groups/{groupId}/members/{newOwnerId}/transfer-ownership": { "post": { "summary": "Transfer group ownership", "description": "Transfers the ownership of the group to another existing member. The current owner is demoted to admin and the target member becomes the new owner. Can be called by the current owner, or by a system admin if the current owner is suspended.", "tags": [ "Group Members" ], "parameters": [ { "description": "The ID of the member to transfer ownership to", "required": true, "name": "newOwnerId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } }, { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "Ownership transferred successfully. Returns the new owner's membership.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupMember" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "NotGroupMember": { "description": "The user must be a member of the group", "value": { "errorCode": "NotGroupMember", "message": "The user must be a member of the group" } }, "GroupCannotAssignOwnerRole": { "description": "Owner role cannot be assigned directly. Use ownership transfer.", "value": { "errorCode": "GroupCannotAssignOwnerRole", "message": "Owner role cannot be assigned directly. Use ownership transfer." } }, "GroupOwnerNotSuspended": { "description": "Admin ownership transfer is only allowed when the current owner is suspended.", "value": { "errorCode": "GroupOwnerNotSuspended", "message": "Admin ownership transfer is only allowed when the current owner is suspended." } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "ResourceNotFound": { "description": "The requested resource not found", "value": { "errorCode": "ResourceNotFound", "message": "The requested resource not found" } }, "GroupNotFound": { "description": "Group not found", "value": { "errorCode": "GroupNotFound", "message": "Group not found" } } } } }, "description": "Not Found" } }, "security": [ { "header": [] } ] } }, "/api/v1/groups/{groupId}/membership": { "delete": { "summary": "Leave a group", "description": "Removes the authenticated user from the group. The user's posts and comments remain but permissions are revoked. The user can rejoin later with fresh membership. Cannot leave if the user is the last admin of the group. Authentication is required.", "tags": [ "Group Members" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "boolean" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "GroupContextIsEmpty", "message": "Group context is not present" } } }, "description": "Group context is not present" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "CantRemoveLastAdmin", "message": "Cannot remove the last remaining admin user" } } }, "description": "Cannot remove the last remaining admin user" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ResourceNotFound", "message": "The requested resource not found" } } }, "description": "The requested resource not found" } }, "security": [ { "header": [] } ], "parameters": [ { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ] }, "get": { "summary": "Get current user's membership in a group", "description": "Returns the membership information for the authenticated user in the specified group. Returns a MembershipInfo object with state indicating: MEMBER (active member), PENDING_JOIN (has pending join request), PENDING_INVITE (has pending invite), or NONE (no relationship). Authentication is required.", "tags": [ "Group Members" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MembershipInfo" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "GroupContextIsEmpty", "message": "Group context is not present" } } }, "description": "Group context is not present" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ], "parameters": [ { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ] } }, "/api/v1/groups/{groupId}/pin": { "delete": { "summary": "Unpin a group", "description": "Removes a group from the user's pinned list. The user must be a member of the group. Authentication is required.", "tags": [ "Group Pins" ], "responses": { "200": { "description": "Group successfully unpinned", "content": { "application/json": { "schema": { "type": "boolean", "example": true } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "NotGroupMember": { "description": "The user must be a member of the group", "value": { "errorCode": "NotGroupMember", "message": "The user must be a member of the group" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ResourceNotFound", "message": "The requested resource not found" } } }, "description": "The requested resource not found" } }, "security": [ { "header": [] } ], "parameters": [ { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ] }, "put": { "summary": "Pin a group", "description": "Pins a group to the user's pinned list with an optional order number. The user must be a member of the group. If no pin number is provided, the next available number is assigned automatically. Authentication is required.", "tags": [ "Group Pins" ], "parameters": [ { "description": "Pin order number. If not provided, next available number will be used", "example": 1, "name": "pin", "required": false, "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true } }, { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "Group successfully pinned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupPin" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "NotGroupMember": { "description": "The user must be a member of the group", "value": { "errorCode": "NotGroupMember", "message": "The user must be a member of the group" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ResourceNotFound", "message": "The requested resource not found" } } }, "description": "The requested resource not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/groups/{groupId}/questions": { "get": { "summary": "Get all questions for a group", "description": "Retrieves the complete list of questions that prospective members must answer when joining the group. Questions are returned in order based on their ordering value (lowest first). This endpoint is not accessible for groups with INVITE_ONLY join mode. Authentication is required to prevent question harvesting.", "tags": [ "Group Questions" ], "parameters": [ { "description": "The identifier of the group whose questions to retrieve", "required": true, "name": "groupId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "List of group questions sorted by ordering", "content": { "application/json": { "schema": { "description": "Array of Question objects with text, type, choices, and ordering", "type": "array", "items": { "$ref": "#/components/schemas/Question" } } } } } }, "security": [ { "header": [] } ] }, "post": { "summary": "Create a new group question", "description": "Adds a new question that prospective members must answer when joining the group. Requires GroupQuestions.Manage permission. Questions can be of type TEXT (free-form answer), SINGLE_CHOICE (one option), or MULTIPLE_CHOICE (multiple options). For choice questions, provide the available options in the choices array. The creation is tracked in the audit log.\n\nRBAC: requires GroupQuestions.Manage", "tags": [ "Group Questions" ], "parameters": [ { "description": "The unique identifier of the group to add the question to", "example": "gr_01hz1f0kw36f82k9s4nzpc4s92n", "required": true, "name": "groupId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionCreate" } } }, "required": true }, "responses": { "200": { "description": "Successfully created the new question", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Question" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ValidationError", "message": "Invalid parameters" } } }, "description": "Invalid parameters" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/groups/{groupId}/questions/answers": { "post": { "summary": "Submit answers to group entry questions", "description": "Submits answers to all required group questions as part of the join process. Returns a token that must be provided when calling the join endpoint. The group must have questions enabled (joinQuestions.show = true) and the user must not already be a member. Answers are validated against the current questions and stored for review by group administrators. The token expires after a configured period.", "tags": [ "Group Questions" ], "parameters": [ { "description": "The unique identifier of the group to submit answers for", "example": "gr_01hz1f0kw36f82k9s4nzpc4s92n", "required": true, "name": "groupId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionAnswerCreate" } } }, "required": true }, "responses": { "200": { "description": "Answer token generated successfully", "content": { "application/json": { "schema": { "description": "Response containing the answer token and submission timestamp", "required": [ "answerToken", "submittedAt" ], "type": "object", "properties": { "answerToken": { "description": "Authentication token to be used with the group join endpoint. Has a limited validity period.", "type": "string", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }, "submittedAt": { "description": "ISO 8601 timestamp indicating when the answers were submitted", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "example": "2024-01-15T10:30:00Z" } } } } } }, "400": { "description": "Bad Request" } }, "security": [ { "header": [] } ] } }, "/api/v1/groups/{groupId}/questions/{questionId}": { "put": { "summary": "Update an existing group question", "description": "Modifies an existing question's text, type, choices, or ordering. Requires GroupQuestions.Manage permission. When changing question type, ensure the choices array is appropriate (empty for TEXT, populated for SINGLE_CHOICE/MULTIPLE_CHOICE). All fields must be provided in the update. Changes are tracked in the audit log for compliance.\n\nRBAC: requires GroupQuestions.Manage", "tags": [ "Group Questions" ], "parameters": [ { "description": "The unique identifier of the group containing the question", "example": "gr_01hz1f0kw36f82k9s4nzpc4s92n", "required": true, "name": "groupId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "The unique identifier of the question to update", "example": "qu_01hz1f0gs9fe4a37jzvzn9m96k", "required": true, "name": "questionId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionUpdate" } } }, "required": true }, "responses": { "200": { "description": "Successfully updated the question", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Question" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ValidationError", "message": "Invalid parameters" } } }, "description": "Invalid parameters" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ResourceNotFound", "message": "The requested resource not found" } } }, "description": "The requested resource not found" } }, "security": [ { "header": [] } ] }, "delete": { "summary": "Delete a group question", "description": "Permanently removes a question from the group's entry requirements. Requires GroupQuestions.Manage permission. This action cannot be undone. Any existing answers to this question are preserved for audit purposes but will not be evaluated for new join requests. The deletion is recorded in the audit log.\n\nRBAC: requires GroupQuestions.Manage", "tags": [ "Group Questions" ], "parameters": [ { "description": "The unique identifier of the group containing the question", "example": "gr_01hz1f0kw36f82k9s4nzpc4s92n", "required": true, "name": "groupId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "The unique identifier of the question to delete", "example": "qu_01hz1f0gs9fe4a37jzvzn9m96k", "required": true, "name": "questionId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "Question successfully deleted", "content": { "application/json": { "schema": {} } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ResourceNotFound", "message": "The requested resource not found" } } }, "description": "The requested resource not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/groups/{groupId}/rules": { "get": { "summary": "Get all rules for a group", "description": "Retrieves the complete list of rules for a specific group. Rules are returned in order based on their ordering value (lowest first). This endpoint is publicly accessible as group rules should be visible to potential members before joining. Each rule includes its text content, explanatory hint, and display ordering.", "tags": [ "Group Rules" ], "parameters": [ { "description": "The unique identifier of the group whose rules to retrieve", "example": "gr_01hz1f0kw36f82k9s4nzpc4s92n", "required": true, "name": "groupId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "List of all group rules sorted by ordering value", "content": { "application/json": { "example": [ { "id": "rl_01hz1f0gs9fe4a37jzvzn9m96k", "text": "Be respectful to all members", "hint": "Treat all group members with respect and kindness", "ordering": 1000 } ], "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Rule" } } } } } }, "security": [] }, "post": { "summary": "Create a new group rule", "description": "Creates a new rule for the specified group. Requires GroupSettings.Manage permission. The rule will be assigned a unique ID and added to the group's rule list. Rules are used to establish community guidelines and expected behavior. An audit log entry is created for this action.\n\nRBAC: requires GroupSettings.Manage", "tags": [ "Group Rules" ], "parameters": [ { "description": "The unique identifier of the group to add the rule to", "example": "gr_01hz1f0kw36f82k9s4nzpc4s92n", "required": true, "name": "groupId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Additional explanation or context for the rule (max 500 characters)", "example": "This includes no personal attacks, harassment, or discriminatory language", "required": true, "name": "hint", "in": "query", "schema": { "type": "string" } }, { "description": "Display order for the rule (lower values appear first)", "example": 1000, "required": true, "name": "ordering", "in": "query", "schema": { "format": "int32", "minimum": 0, "type": "integer" } }, { "description": "The rule text that members must follow (max 500 characters)", "example": "Be respectful to all members", "required": true, "name": "text", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully created the new rule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Rule" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ValidationError", "message": "Invalid parameters" } } }, "description": "Invalid parameters" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/groups/{groupId}/rules/reorder": { "post": { "summary": "Reorder multiple group rules", "description": "Batch updates the display ordering of multiple rules within a group. This endpoint allows efficient reordering of rules without individual API calls. Requires GroupSettings.Manage permission. Each reordering operation is tracked in the audit log. Rules not included in the request maintain their current ordering. Returns all group rules with updated ordering values.\n\nRBAC: requires GroupSettings.Manage", "tags": [ "Group Rules" ], "parameters": [ { "description": "The unique identifier of the group whose rules to reorder", "example": "gr_01hz1f0kw36f82k9s4nzpc4s92n", "required": true, "name": "groupId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RuleOrderingRequest" } } } }, "required": true }, "responses": { "200": { "description": "All group rules with updated ordering", "content": { "application/json": { "schema": { "description": "Complete list of group rules reflecting the new ordering", "type": "array", "items": { "$ref": "#/components/schemas/Rule" } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ValidationError", "message": "Invalid parameters" } } }, "description": "Invalid parameters" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/groups/{groupId}/rules/{id}": { "delete": { "summary": "Delete a group rule", "description": "Permanently removes a rule from the group. Requires GroupSettings.Manage permission. This action cannot be undone. The deletion is recorded in the audit log. Returns 404 if the rule doesn't exist or doesn't belong to the specified group.\n\nRBAC: requires GroupSettings.Manage", "tags": [ "Group Rules" ], "parameters": [ { "description": "The unique identifier of the group containing the rule", "example": "gr_01hz1f0kw36f82k9s4nzpc4s92n", "required": true, "name": "groupId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "The unique identifier of the rule to delete", "example": "rl_01hz1f0gs9fe4a37jzvzn9m96k", "required": true, "name": "id", "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Rule successfully deleted", "content": { "application/json": { "schema": {} } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ResourceNotFound", "message": "The requested resource not found" } } }, "description": "The requested resource not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/groups/{groupId}/rules/{ruleId}": { "put": { "summary": "Update an existing group rule", "description": "Modifies an existing rule's text, hint, or ordering. Requires GroupSettings.Manage permission. The entire rule content must be provided in the update request. Changes are tracked in the audit log for compliance and moderation purposes. Returns 404 if the rule doesn't exist.\n\nRBAC: requires GroupSettings.Manage", "tags": [ "Group Rules" ], "parameters": [ { "description": "The unique identifier of the group containing the rule", "example": "gr_01hz1f0kw36f82k9s4nzpc4s92n", "required": true, "name": "groupId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "The unique identifier of the rule to update", "example": "rl_01hz1f0gs9fe4a37jzvzn9m96k", "required": true, "name": "ruleId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuleUpdate" } } }, "required": true }, "responses": { "200": { "description": "Successfully updated the rule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Rule" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ValidationError", "message": "Invalid parameters" } } }, "description": "Invalid parameters" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ResourceNotFound", "message": "The requested resource not found" } } }, "description": "The requested resource not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/groups/{groupId}/settings": { "put": { "summary": "Update group settings", "description": "Update multiple group settings in a single operation. Each setting must be provided as a complete object with all required fields. Partial updates are not supported to ensure data consistency and prevent configuration errors. Requires authentication and the GroupSettings.Manage RBAC permission within the group.\n\nRBAC: requires GroupSettings.Manage", "tags": [ "Group Settings" ], "requestBody": { "description": "settings objects to be updated. complete objects must be provided - partial updates are not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupSettings" } } }, "required": true }, "responses": { "200": { "description": "number of updated settings", "content": { "application/json": { "example": { "updated": 3 } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "SettingsInvalidKeyProvided": { "description": "Unknown settings key(s) %s", "value": { "errorCode": "SettingsInvalidKeyProvided", "message": "Unknown settings key(s) %s" } }, "SettingsKeyNotProvided": { "description": "No settings keys were provided", "value": { "errorCode": "SettingsKeyNotProvided", "message": "No settings keys were provided" } }, "SettingsValuesNotProvided": { "description": "No settings values were provided", "value": { "errorCode": "SettingsValuesNotProvided", "message": "No settings values were provided" } }, "SettingsPartialUpdateNotAllowed": { "description": "Partial updates are not allowed: %s", "value": { "errorCode": "SettingsPartialUpdateNotAllowed", "message": "Partial updates are not allowed: %s" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "SettingsForbidden", "message": "Access denied for settings" } } }, "description": "Access denied for settings" }, "500": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "SettingsNotUpdated", "message": "Failed to update settings" } } }, "description": "Failed to update settings" } }, "security": [ { "header": [] } ], "parameters": [ { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ] }, "get": { "summary": "Get group settings", "description": "Retrieve specific group settings by their keys. Returns a JSON object mapping setting names to their configured values. Only settings that the authenticated user has permission to read will be included in the response. Requires authentication and group membership.", "tags": [ "Group Settings" ], "parameters": [ { "description": "Comma-separated list of setting keys to retrieve. Each key must correspond to a valid group setting definition registered in the system.\n\nAvailable keys are:\n\n```group.ai.agents.budgets```\n\n```group.join.questions```\n\n```group.membership```\n\n```group.moderation```\n\n```group.privacy```", "name": "keys", "required": true, "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "example": "group.ai.agents.budgets,group.join.questions" }, { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/GroupSettings" } ] } } }, "description": "Response GroupSettings" }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "SettingsInvalidKeyProvided": { "description": "Unknown settings key(s) %s", "value": { "errorCode": "SettingsInvalidKeyProvided", "message": "Unknown settings key(s) %s" } }, "SettingsKeyNotProvided": { "description": "No settings keys were provided", "value": { "errorCode": "SettingsKeyNotProvided", "message": "No settings keys were provided" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "SettingsForbidden", "message": "Access denied for settings" } } }, "description": "Access denied for settings" } }, "security": [ { "header": [] } ] }, "delete": { "summary": "Delete group settings", "description": "Remove specific group settings by their keys. This operation will permanently delete the specified settings and revert them to their default values. Use with caution as deleted settings cannot be recovered. Requires authentication and the GroupSettings.Manage RBAC permission within the group.\n\nRBAC: requires GroupSettings.Manage", "tags": [ "Group Settings" ], "parameters": [ { "description": "Comma-separated list of setting keys to delete. Each key must correspond to a valid group setting that exists for this group.\n\nAvailable keys are:\n\n```group.ai.agents.budgets```\n\n```group.join.questions```\n\n```group.membership```\n\n```group.moderation```\n\n```group.privacy```", "name": "keys", "required": true, "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "example": "group.ai.agents.budgets,group.join.questions" }, { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "number of deleted settings", "content": { "application/json": { "example": { "deleted": 3 } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "SettingsKeyNotProvided": { "description": "No settings keys were provided", "value": { "errorCode": "SettingsKeyNotProvided", "message": "No settings keys were provided" } }, "SettingsInvalidKeyProvided": { "description": "Unknown settings key(s) %s", "value": { "errorCode": "SettingsInvalidKeyProvided", "message": "Unknown settings key(s) %s" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "SettingsForbidden", "message": "Access denied for settings" } } }, "description": "Access denied for settings" } }, "security": [ { "header": [] } ] } }, "/api/v1/groups/{groupId}/users": { "get": { "summary": "Get group members as User objects", "description": "\n Retrieves the list of all members in the specified group.\n Public groups are accessible to all authenticated users, Private groups accessible to members only.\n Supports sorting by join time, posts, or relationship to current user.\n Supports role filtering and pagination.\n ", "tags": [ "Group Members" ], "parameters": [ { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "Sort order (case-insensitive)", "required": false, "name": "order", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/SortOrder" } ], "nullable": true } }, { "description": "Role filter (case-insensitive)", "required": false, "name": "role", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/GroupMemberRoleFilter" } ], "nullable": true } }, { "description": "Sort field (case-insensitive)", "required": false, "name": "sort", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/GroupMembersSortBy" } ], "nullable": true } }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "groupId", "description": "The unique identifier of the group", "required": true, "example": "gr_01hz1f0kw36f82k9s4nzpc4s33n", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "List of users who are members of the group", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/User" } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "GroupContextIsEmpty", "message": "Group context is not present" } } }, "description": "Group context is not present" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "GroupNoPublicAccess": { "description": "The group must be public or the requesting user must be a member of the group", "value": { "errorCode": "GroupNoPublicAccess", "message": "The group must be public or the requesting user must be a member of the group" } }, "NotGroupMember": { "description": "The user must be a member of the group", "value": { "errorCode": "NotGroupMember", "message": "The user must be a member of the group" } }, "GroupMemberListNotPublic": { "description": "Group member list is not visible to non-members", "value": { "errorCode": "GroupMemberListNotPublic", "message": "Group member list is not visible to non-members" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "GroupNotFound", "message": "Group not found" } } }, "description": "Group not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/import": { "get": { "summary": "List user's import jobs", "description": "Returns a list of all import jobs created by the authenticated user, including their current status and results.", "tags": [ "Import" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BulkImport" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] }, "post": { "summary": "Import data from CSV file", "description": "Uploads and processes a CSV file for bulk import of data such as followers, blocks, or mutes from other platforms. The import is processed asynchronously after upload.", "tags": [ "Import" ], "parameters": [ { "description": "Whether to overwrite existing data. If true, replaces current data with imported data", "required": false, "name": "overwrite", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Type of data being imported (e.g., followers, blocks, mutes)", "required": true, "name": "type", "in": "query", "schema": { "$ref": "#/components/schemas/BulkImportType" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "required": [ "file" ], "type": "object", "properties": { "file": { "format": "binary", "maxLength": 20971520, "minLength": 1, "type": "string" } } } } }, "required": true }, "responses": { "200": { "description": "The ID of the created import job", "content": { "text/plain": { "schema": { "type": "integer" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ClientError", "message": "Invalid request from client" } } }, "description": "Invalid request from client" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/import/start/{id}": { "post": { "summary": "Start import processing", "description": "Begins processing a previously uploaded import job. The import must be in PENDING state to be started.", "tags": [ "Import" ], "parameters": [ { "description": "Import job ID returned from the upload step", "required": true, "name": "id", "in": "path", "schema": { "format": "int64", "type": "integer" } } ], "responses": { "200": { "description": "Import job started successfully", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ClientError", "message": "Invalid request from client" } } }, "description": "Invalid request from client" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "Forbidden", "message": "No access to the resource" } } }, "description": "No access to the resource" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ResourceNotFound", "message": "The requested resource not found" } } }, "description": "The requested resource not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/import/{id}": { "get": { "summary": "Get import job details", "description": "Retrieves the current status and details of a specific import job, including processing progress and any errors.", "tags": [ "Import" ], "parameters": [ { "description": "Import job ID", "required": true, "name": "id", "in": "path", "schema": { "format": "int64", "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkImport" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "Forbidden", "message": "No access to the resource" } } }, "description": "No access to the resource" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ResourceNotFound", "message": "The requested resource not found" } } }, "description": "The requested resource not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/instance": { "get": { "summary": "Get instance information", "description": "Returns comprehensive server instance metadata including domain, version, build information, registration configuration, and server rules. Useful for clients to understand server capabilities and requirements.", "tags": [ "Instance" ], "responses": { "200": { "description": "Instance info", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Instance" } } } } }, "security": [] } }, "/api/v1/instance/countries": { "get": { "summary": "Get country information", "description": "Returns country data including names (common/official/native), flags, and phone codes. Data is cached in Redis with 7-day TTL and fetched from external API if not cached. Falls back to local file if API is unavailable. Used for country selection in user profiles and phone number validation.", "tags": [ "Instance" ], "responses": { "200": { "description": "List of countries info about name, phone number and flag", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CountryInfo" } } } } } }, "security": [] } }, "/api/v1/instance/domains": { "get": { "summary": "Search compatible federated domains", "description": "Returns a list of federated server domains compatible with specified software. Filters domains by prefix matching for autocomplete functionality. Useful for discovering servers running specific ActivityPub software (Mastodon, Pleroma, etc.). Results are cached for performance.", "tags": [ "Instance" ], "parameters": [ { "description": "Domain prefix to search for (autocomplete-style matching)", "required": false, "name": "domain", "in": "query", "schema": { "maxLength": 64, "minLength": 1, "pattern": "\\S", "type": "string", "nullable": true } }, { "description": "Maximum number of results to return. If omitted, all matching domains are returned.", "required": false, "name": "limit", "in": "query", "schema": { "format": "int64", "minimum": 0, "exclusiveMinimum": true, "type": "integer", "nullable": true } }, { "description": "Software name to filter by (e.g. 'mastodon', 'pleroma')", "required": false, "name": "software", "in": "query", "schema": { "pattern": "\\S", "type": "string", "nullable": true } } ], "responses": { "200": { "description": "Domains list", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } } }, "security": [] } }, "/api/v1/instance/extended_description": { "get": { "summary": "Get extended server description", "description": "Returns detailed 'about' information for this server instance. Includes formatted HTML content describing the server's purpose and policies. Content is admin-configurable (feature pending implementation).", "tags": [ "Instance" ], "responses": { "200": { "description": "Extended Instance info", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Instance" } } } } }, "security": [] } }, "/api/v1/instance/supported_languages": { "get": { "summary": "Get supported languages", "description": "Returns all languages supported by the platform for content and UI translation. Each language includes its ISO code and native name. Used for language selection in user preferences and content language detection. Languages are used by the translation API for multi-language support.", "tags": [ "Instance" ], "responses": { "200": { "description": "List of supported languages", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SupportedLanguage" } } } } } }, "security": [] } }, "/api/v1/instance/timezones": { "get": { "summary": "Get supported timezones", "description": "Returns a comprehensive list of all supported timezones with metadata. Includes timezone abbreviations, UTC offsets, DST information, and display text. Used for user timezone selection in profile settings.", "tags": [ "Instance" ], "responses": { "200": { "description": "List of timezones", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TimezoneInfo" } } } } } }, "security": [] } }, "/api/v1/jobs/clear": { "delete": { "summary": "Clear all jobs for a status", "description": "Removes all jobs from the specified list. Cannot clear active jobs (would orphan coroutines). Requires Jobs.Manage permission.\n\nRBAC:\n- requires ALL of Jobs.Manage\n- requires ANY of Jobs.Read, Jobs.Manage", "tags": [ "Admin Jobs" ], "parameters": [ { "description": "Job list kind: submitted, finished, failed, or dlq", "required": true, "name": "listKind", "in": "query", "schema": { "pattern": "\\S", "type": "string" } }, { "description": "Queue name (required for submitted/finished/failed)", "required": false, "name": "queue", "in": "query", "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "Jobs cleared", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "JobsInvalidKind", "message": "The specified job kind is incorrect" } } }, "description": "The specified job kind is incorrect" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "JobsQueueNotFound", "message": "The specified queue does not exist" } } }, "description": "The specified queue does not exist" } }, "security": [ { "header": [] } ] } }, "/api/v1/jobs/dlq": { "get": { "summary": "List dead letter queue jobs", "description": "Returns a paginated list of jobs in the dead letter queue (DLQ). These are jobs that failed deserialization and were moved out of normal processing.\n\nRBAC:\n- requires ANY of Jobs.Read, Jobs.Manage", "tags": [ "Admin Jobs" ], "parameters": [ { "description": "Maximum number of jobs to return", "required": false, "name": "limit", "in": "query", "schema": { "format": "int64", "type": "integer", "nullable": true } }, { "description": "Number of items to skip for pagination", "required": false, "name": "offset", "in": "query", "schema": { "format": "int64", "type": "integer", "nullable": true } } ], "responses": { "200": { "description": "Paginated DLQ listing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedisJobsResult" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/jobs/job": { "delete": { "summary": "Delete a specific job", "description": "Deletes a job from the specified list (submitted, finished, failed, retries, schedule, dlq). Cannot delete active jobs. Requires Jobs.Manage permission.\n\nRBAC:\n- requires ALL of Jobs.Manage\n- requires ANY of Jobs.Read, Jobs.Manage", "tags": [ "Admin Jobs" ], "parameters": [ { "description": "Job hash UUID", "required": true, "name": "jobHash", "in": "query", "schema": { "pattern": "\\S", "type": "string" } }, { "description": "Job list kind: submitted, finished, failed, retries, schedule, or dlq", "required": true, "name": "listKind", "in": "query", "schema": { "pattern": "\\S", "type": "string" } }, { "description": "Queue name (required for submitted/finished/failed)", "required": false, "name": "queue", "in": "query", "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "Job deleted successfully", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "JobsInvalidKind", "message": "The specified job kind is incorrect" } } }, "description": "The specified job kind is incorrect" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "JobsJobNotFound", "message": "The specified job was not found" } } }, "description": "The specified job was not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/jobs/list-jobs": { "get": { "summary": "List all job types", "description": "Returns a list of all available job types in the system. Supports pagination.\n\nRBAC:\n- requires ANY of Jobs.Read, Jobs.Manage", "tags": [ "Admin Jobs" ], "parameters": [ { "description": "Maximum number of job types to return", "required": false, "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true } }, { "description": "Number of items to skip for pagination", "required": false, "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true } } ], "responses": { "200": { "description": "Paginated list of job types", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobListResult" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/jobs/list-stats": { "get": { "summary": "Get statistics for a specific queue", "description": "Returns detailed statistics for a specific job queue including counts of finished, failed, active, submitted, and retry jobs.\n\nRBAC:\n- requires ANY of Jobs.Read, Jobs.Manage", "tags": [ "Admin Jobs" ], "parameters": [ { "description": "Queue name to retrieve statistics for", "required": true, "name": "queue", "in": "query", "schema": { "pattern": "\\S", "type": "string" } } ], "responses": { "200": { "description": "Queue statistics with job counts by status", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/jobs/list-stats-all": { "get": { "summary": "Get statistics for all queues", "description": "Returns aggregated statistics across all job queues including counts of finished, failed, active, submitted, scheduled, and retry jobs.\n\nRBAC:\n- requires ANY of Jobs.Read, Jobs.Manage", "tags": [ "Admin Jobs" ], "responses": { "200": { "description": "Aggregated statistics for all queues", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/jobs/lists": { "get": { "summary": "List jobs by status in a queue", "description": "Returns a paginated list of jobs with a specific status (finished, failed, active, submitted, retries, schedule, dlq) from a specific queue.\n\nRBAC:\n- requires ANY of Jobs.Read, Jobs.Manage", "tags": [ "Admin Jobs" ], "parameters": [ { "description": "Maximum number of jobs to return", "required": false, "name": "limit", "in": "query", "schema": { "format": "int64", "type": "integer", "nullable": true } }, { "description": "Job status category: finished, failed, active, submitted, retries, schedule, or dlq", "required": true, "name": "listKind", "in": "query", "schema": { "pattern": "\\S", "type": "string" } }, { "description": "Number of items to skip for pagination", "required": false, "name": "offset", "in": "query", "schema": { "format": "int64", "type": "integer", "nullable": true } }, { "description": "Queue name to list jobs from (not required for dlq)", "required": false, "name": "queue", "in": "query", "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "List of jobs with the specified status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedisJobsResult" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "JobsInvalidKind", "message": "The specified job kind is incorrect" } } }, "description": "The specified job kind is incorrect" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/jobs/processes": { "get": { "summary": "List active job processor instances", "description": "Returns all active job processor instances with their hostname, PID, and last heartbeat time.\n\nRBAC:\n- requires ANY of Jobs.Read, Jobs.Manage", "tags": [ "Admin Jobs" ], "responses": { "200": { "description": "List of active process instances", "content": { "application/json": {} } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/jobs/redis-info": { "get": { "summary": "Get Redis server info", "description": "Returns basic Redis server information including version, memory usage, and connected clients.\n\nRBAC:\n- requires ANY of Jobs.Read, Jobs.Manage", "tags": [ "Admin Jobs" ], "responses": { "200": { "description": "Redis server information", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/jobs/retry": { "post": { "summary": "Retry a single failed job", "description": "Moves a failed job back to the submitted queue with tries reset to 0. Requires Jobs.Manage permission.\n\nRBAC:\n- requires ALL of Jobs.Manage\n- requires ANY of Jobs.Read, Jobs.Manage", "tags": [ "Admin Jobs" ], "parameters": [ { "description": "Job hash UUID", "required": true, "name": "jobHash", "in": "query", "schema": { "pattern": "\\S", "type": "string" } }, { "description": "Queue name", "required": true, "name": "queue", "in": "query", "schema": { "pattern": "\\S", "type": "string" } } ], "responses": { "200": { "description": "Job retried successfully", "content": { "application/json": { "schema": {} } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "JobsJobNotFound": { "description": "The specified job was not found", "value": { "errorCode": "JobsJobNotFound", "message": "The specified job was not found" } }, "JobsQueueNotFound": { "description": "The specified queue does not exist", "value": { "errorCode": "JobsQueueNotFound", "message": "The specified queue does not exist" } } } } }, "description": "Not Found" } }, "security": [ { "header": [] } ] } }, "/api/v1/jobs/retry-all": { "post": { "summary": "Retry all failed jobs in a queue", "description": "Moves all failed jobs in the specified queue back to submitted with tries reset. Requires Jobs.Manage permission.\n\nRBAC:\n- requires ALL of Jobs.Manage\n- requires ANY of Jobs.Read, Jobs.Manage", "tags": [ "Admin Jobs" ], "parameters": [ { "description": "Queue name", "required": true, "name": "queue", "in": "query", "schema": { "pattern": "\\S", "type": "string" } } ], "responses": { "200": { "description": "All failed jobs retried", "content": { "application/json": { "schema": {} } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "JobsQueueNotFound", "message": "The specified queue does not exist" } } }, "description": "The specified queue does not exist" } }, "security": [ { "header": [] } ] } }, "/api/v1/jobs/stats": { "get": { "summary": "Get overall job statistics", "description": "Returns aggregated statistics for all finished and failed jobs across all queues. Requires Jobs.Read or Jobs.Manage permission.\n\nRBAC:\n- requires ANY of Jobs.Read, Jobs.Manage", "tags": [ "Admin Jobs" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OverallStats" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/jobs/stats-per-day": { "get": { "summary": "Get daily job statistics", "description": "Returns job statistics broken down by day for the specified number of past days. Can be filtered by queue or aggregated across all queues.\n\nRBAC:\n- requires ANY of Jobs.Read, Jobs.Manage", "tags": [ "Admin Jobs" ], "parameters": [ { "description": "Number of past days to include (1-100)", "required": true, "name": "lastDays", "in": "query", "schema": { "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Optional queue name to filter by. If omitted, aggregates across all queues.", "required": false, "name": "queue", "in": "query", "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "Daily statistics for finished and failed jobs", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ConstraintViolation", "message": "A request parameter constraint was violated" } } }, "description": "A request parameter constraint was violated" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/jobs/summary": { "get": { "summary": "Get combined per-queue summary", "description": "Returns a combined summary for all queues including job counts, latency, and worker configuration. Single call replaces multiple stats calls.\n\nRBAC:\n- requires ANY of Jobs.Read, Jobs.Manage", "tags": [ "Admin Jobs" ], "responses": { "200": { "description": "List of queue summaries with counts, latency and config", "content": { "application/json": {} } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/jobs/workers": { "get": { "summary": "Get worker configuration", "description": "Returns static configuration for all registered workers including queue name, description, max retries, concurrency, and enabled status.\n\nRBAC:\n- requires ANY of Jobs.Read, Jobs.Manage", "tags": [ "Admin Jobs" ], "responses": { "200": { "description": "List of worker configurations", "content": { "application/json": {} } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/links": { "get": { "summary": "Generate link preview", "description": "Fetches and returns metadata for a given URL to create a rich preview card. Extracts title, description, image, author, and other OpenGraph/Twitter Card metadata. Results are cached for performance. Returns error if URL is unreachable or has no metadata. The URL must be properly formatted and accessible.", "tags": [ "Link Preview" ], "parameters": [ { "description": "The fully qualified URL to fetch metadata from", "required": true, "name": "url", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Link preview card with extracted metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Card" } } } }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "LinkPreviewNotAvailable", "message": "Link preview not available" } } }, "description": "Link preview not available" } }, "security": [] } }, "/api/v1/lists": { "get": { "summary": "Get authenticated user's lists", "description": "Returns all lists created by the authenticated user for organizing followed accounts.", "tags": [ "Lists" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UsersList" } } } } } }, "security": [ { "header": [] } ] }, "post": { "summary": "Create a new list", "description": "Creates a new list for organizing followed accounts. Lists can be public or private.", "tags": [ "Lists" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserListCreate" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsersList" } } } }, "400": { "description": "Bad Request" } }, "security": [ { "header": [] } ] } }, "/api/v1/lists/{listId}": { "put": { "summary": "Update list properties", "description": "Updates the name, privacy setting, or other properties of an existing list. Only the list owner can update it.", "tags": [ "Lists" ], "parameters": [ { "description": "ID of the list to update. Must be a valid USER_LIST type TypeId.", "required": true, "name": "listId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserListCreate" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsersList" } } } }, "400": { "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserListNotFound", "message": "The user list could not be found" } } }, "description": "The user list could not be found" } }, "security": [ { "header": [] } ] }, "get": { "summary": "Get list details by ID", "description": "Retrieves details of a specific list including its name, privacy setting, and metadata. Private lists can only be accessed by their owner.", "tags": [ "Lists" ], "parameters": [ { "description": "ID of the list to retrieve. Must be a valid USER_LIST type TypeId.", "required": true, "name": "listId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsersList" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserListNotFound", "message": "The user list could not be found" } } }, "description": "The user list could not be found" } }, "security": [ { "header": [] } ] }, "delete": { "summary": "Delete a list", "description": "Permanently deletes a list and removes all user associations. Only the list owner can delete it.", "tags": [ "Lists" ], "parameters": [ { "description": "ID of the list to delete. Must be a valid USER_LIST type TypeId.", "required": true, "name": "listId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserListCantDeleteOthers", "message": "Cannot delete a list belonging to another user" } } }, "description": "Cannot delete a list belonging to another user" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserListNotFound", "message": "The user list could not be found" } } }, "description": "The user list could not be found" } }, "security": [ { "header": [] } ] } }, "/api/v1/lists/{listId}/users": { "get": { "summary": "Get users in a list", "description": "Returns all users that have been added to a specific list. Private lists can only be accessed by their owner.", "tags": [ "Lists" ], "parameters": [ { "description": "ID of the list to retrieve users from. Must be a valid USER_LIST type TypeId.", "required": true, "name": "listId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/User" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserListNotFound", "message": "The user list could not be found" } } }, "description": "The user list could not be found" } }, "security": [ { "header": [] } ] } }, "/api/v1/lists/{listId}/users/{userId}": { "delete": { "summary": "Remove user from list", "description": "Removes a user from a list. Only the list owner can remove users.", "tags": [ "Lists" ], "parameters": [ { "description": "ID of the list to remove the user from. Must be a valid USER_LIST type TypeId.", "required": true, "name": "listId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "ID of the user to remove from the list. Must be a valid USER type TypeId.", "required": true, "name": "userId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsersList" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserListCantAdd", "message": "Failed to add the user to the list" } } }, "description": "Failed to add the user to the list" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "UserListCantChangeOthers": { "description": "Cannot update a list belonging to another user", "value": { "errorCode": "UserListCantChangeOthers", "message": "Cannot update a list belonging to another user" } }, "UserListCantDeleteOthers": { "description": "Cannot delete a list belonging to another user", "value": { "errorCode": "UserListCantDeleteOthers", "message": "Cannot delete a list belonging to another user" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "UserListNotFound": { "description": "The user list could not be found", "value": { "errorCode": "UserListNotFound", "message": "The user list could not be found" } }, "UserListUserNotFound": { "description": "The specified user not found in the list", "value": { "errorCode": "UserListUserNotFound", "message": "The specified user not found in the list" } } } } }, "description": "Not Found" } }, "security": [ { "header": [] } ] }, "post": { "summary": "Add user to list", "description": "Adds a user to a list for organization and filtering purposes. Only followed users can be added to lists. Only the list owner can add users.", "tags": [ "Lists" ], "parameters": [ { "description": "ID of the list to add the user to. Must be a valid USER_LIST type TypeId.", "required": true, "name": "listId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "ID of the user to add to the list. Must be a valid USER type TypeId.", "required": true, "name": "userId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsersList" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserListCantAdd", "message": "Failed to add the user to the list" } } }, "description": "Failed to add the user to the list" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserListCantChangeOthers", "message": "Cannot update a list belonging to another user" } } }, "description": "Cannot update a list belonging to another user" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserListNotFound", "message": "The user list could not be found" } } }, "description": "The user list could not be found" } }, "security": [ { "header": [] } ] } }, "/api/v1/markdown": { "put": { "summary": "Convert markdown to HTML", "description": "Converts markdown formatted text to HTML for preview purposes. By default, processes hashtags into linked tags, @mentions into profile links, and custom emoji shortcodes into images. Use ?skipAutolink=true to get a plain markdown-to-HTML conversion without autolinking. Requires authentication.", "tags": [ "Markdown" ], "parameters": [ { "description": "Allows to skip formatting of tags, mentions and emojis if needed.", "required": false, "name": "skipAutolink", "in": "query", "schema": { "type": "boolean", "nullable": true } } ], "requestBody": { "content": { "text/plain": { "schema": { "maxLength": 50000, "pattern": "\\S", "type": "string" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "text/html": { "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/metrics": { "get": { "summary": "Get metrics for a specified time period", "description": "Retrieves metrics data for the events stream within a specified time period. Supports both predefined periods (last day/week/month) and custom date ranges.\n\nRBAC:\n- requires ANY of Federation.Read, Federation.Manage", "tags": [ "Metrics" ], "parameters": [ { "description": "Start time for custom date range (ISO 8601 format). Use with 'to' parameter.", "required": false, "name": "from", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true } }, { "description": "Predefined time period. Options: LAST_DAY, LAST_WEEK, LAST_MONTH", "required": false, "name": "period", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/MetricsPeriod" } ], "nullable": true } }, { "description": "End time for custom date range (ISO 8601 format). Use with 'from' parameter.", "required": false, "name": "to", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Instant" } ], "nullable": true } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MetricsData" } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ConstraintViolation", "message": "A request parameter constraint was violated" } } }, "description": "A request parameter constraint was violated" } }, "security": [ { "header": [] } ] } }, "/api/v1/metrics/totals": { "get": { "summary": "Get current server totals", "description": "Returns the current total counts of users and posts on the server.\n\nRBAC:\n- requires ANY of Federation.Read, Federation.Manage", "tags": [ "Metrics" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerTotals" } } } } }, "security": [ { "header": [] } ] } }, "/api/v1/mute": { "get": { "summary": "List all muted users", "description": "Returns a paginated list of all users currently muted by the authenticated user. Includes both permanently and temporarily muted users. Requires authentication.", "tags": [ "Mutes" ], "parameters": [ { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/User" } } } } } }, "security": [ { "header": [] } ] } }, "/api/v1/mute/{userId}": { "delete": { "summary": "Unmute a previously muted user", "description": "Removes the mute on a specific user, allowing their content to appear again in timelines and notifications. Cancels any scheduled automatic unmute. If you follow the unmuted user, their posts are restored to your home feed. Requires authentication.", "tags": [ "Mutes" ], "parameters": [ { "description": "ID of the user to unmute. Must be a valid USER type TypeId.", "required": true, "name": "userId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "MuteNotMuted", "message": "The user is not muted" } } }, "description": "The user is not muted" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserNotFound", "message": "User not found" } } }, "description": "User not found" } }, "security": [ { "header": [] } ] }, "post": { "summary": "Mute a specific user", "description": "Hides all content from a specific user. Can optionally set an expiration time for the mute. Muted users' posts will not appear in timelines or notifications. If the target user is already blocked, returns an error instead. Removes the muted user's posts from your home feed if you follow them. Requires authentication.", "tags": [ "Mutes" ], "parameters": [ { "description": "ID of the user to mute. Must be a valid USER type TypeId.", "required": true, "name": "userId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Seconds after which mute should expire", "required": false, "name": "duration", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "MuteSelf", "message": "A user cannot mute themselves" } } }, "description": "A user cannot mute themselves" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserNotFound", "message": "User not found" } } }, "description": "User not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/names/check": { "get": { "summary": "Check if a name is available", "description": "Unified endpoint for checking name availability. For USER scope: checks global user/channel namespace if no scope (groupId) provided, or checks channel username within a specific group if scope is provided. For GROUP scope: checks group name availability (scope not allowed).", "tags": [ "Names" ], "parameters": [ { "description": "The name to check for availability", "example": "my-username", "required": true, "name": "name", "in": "query", "schema": { "pattern": "\\S", "type": "string" } }, { "description": "The scope of the name check: USER for users and channels, GROUP for groups", "example": "USER", "required": true, "schema": { "$ref": "#/components/schemas/NameScope" }, "name": "nameScope", "in": "query" }, { "description": "Group ID for checking channel username within a group. Optional for USER (if omitted, checks global namespace). Not allowed for GROUP scope.", "example": "gr_01234567890123456789012", "required": false, "name": "scope", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } ], "responses": { "200": { "description": "Name availability check result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NameCheckResult" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ClientError", "message": "Invalid request from client" } } }, "description": "Invalid request from client" } }, "security": [] } }, "/api/v1/notes": { "put": { "summary": "Set or update note for a user", "description": "Creates or updates a personal note about another user. These notes are private and only visible to the authenticated user who created them.", "tags": [ "Notes" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteUpdate" } } }, "required": true }, "responses": { "200": { "description": "Note has been updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserNote" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "NoteForSelf", "message": "Cannot create a note for oneself" } } }, "description": "Cannot create a note for oneself" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserNotFound", "message": "User not found" } } }, "description": "User not found" }, "500": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "DBError", "message": "An unexpected database error" } } }, "description": "An unexpected database error" } }, "security": [ { "header": [] } ] }, "get": { "summary": "Get notes for multiple users", "description": "Retrieves personal notes the authenticated user has created about specified users. Returns notes for multiple users in a single request.", "tags": [ "Notes" ], "parameters": [ { "description": "Comma-separated list of user IDs to retrieve notes for", "examples": {}, "name": "userIds", "required": true, "in": "query", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypeId" } } } ], "responses": { "200": { "description": "Notes have been fetched successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserNote" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/notes/{userId}": { "delete": { "summary": "Delete note for a user", "description": "Permanently deletes a personal note about a specific user.", "tags": [ "Notes" ], "parameters": [ { "description": "The user ID whose note should be deleted", "required": true, "name": "userId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "Note has been deleted successfully", "content": { "application/json": { "schema": {} } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserNotFound", "message": "User not found" } } }, "description": "User not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/notifications": { "get": { "summary": "List user's notifications", "description": "Retrieves a paginated list of the authenticated user's notifications. Supports filtering by specific notification types (include or exclude) and by read/unread status. Results are ordered by creation date, most recent first. Requires authentication.", "tags": [ "Notifications" ], "parameters": [ { "description": "Exclude these notification types from results. Comma-separated values are supported. Applied after 'types' filter.", "required": false, "name": "excludeTypes", "in": "query", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationType" }, "nullable": true } }, { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Filter by notification status: READ or UNREAD. If omitted, returns all statuses.", "required": false, "name": "status", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/NotificationStatus" } ], "nullable": true } }, { "description": "Include only these notification types. Comma-separated values are supported. If omitted, all types are included.", "required": false, "name": "types", "in": "query", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationType" }, "nullable": true } }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ], "responses": { "200": { "description": "Notifications", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Notification" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/notifications/count": { "get": { "summary": "Get notifications count", "description": "Returns the total count of the authenticated user's notifications matching the given filters. Supports the same type and status filters as the list endpoint. Useful for displaying unread badge counts. Requires authentication.", "tags": [ "Notifications" ], "parameters": [ { "description": "Exclude these notification types from the count. Comma-separated values are supported.", "required": false, "name": "excludeTypes", "in": "query", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationType" }, "nullable": true } }, { "description": "Filter by notification status: READ or UNREAD. If omitted, counts all statuses.", "required": false, "name": "status", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/NotificationStatus" } ], "nullable": true } }, { "description": "Include only these notification types in the count. Comma-separated values are supported. If omitted, all types are counted.", "required": false, "name": "types", "in": "query", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationType" }, "nullable": true } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "integer" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/notifications/mark-all": { "post": { "summary": "Mark all notifications as read or unread", "description": "Bulk-updates the read/unread status of all notifications for the authenticated user. Returns the number of notifications that were changed. Requires authentication.", "tags": [ "Notifications" ], "parameters": [ { "description": "New status for all notifications: READ or UNREAD", "required": true, "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/NotificationStatus" } }, { "description": "Only mark notifications of this type. If omitted, marks all notifications.", "required": false, "name": "type", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/NotificationType" } ], "nullable": true } } ], "responses": { "200": { "description": "Number of notifications changed", "content": { "application/json": { "schema": { "type": "integer" } } } } }, "security": [ { "header": [] } ] } }, "/api/v1/notifications/{id}": { "get": { "summary": "Get notification by ID", "description": "Retrieves a specific notification by its ID. Only returns the notification if it belongs to the authenticated user. Requires authentication.", "tags": [ "Notifications" ], "parameters": [ { "description": "Notification id", "required": true, "name": "id", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ], "responses": { "200": { "description": "Notification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Notification" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "NotificationNotFound", "message": "The specified notification not found" } } }, "description": "The specified notification not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/notifications/{id}/mark": { "post": { "summary": "Mark notification as read or unread", "description": "Updates the read/unread status of a specific notification. Only the notification owner can change its status. Requires authentication.", "tags": [ "Notifications" ], "parameters": [ { "description": "Notification ID to mark. Must be a valid NOTIFICATION type TypeId.", "required": true, "name": "id", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "New status for the notification: READ or UNREAD", "required": true, "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/NotificationStatus" } }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ], "responses": { "200": { "description": "Notification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Notification" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "NotificationNotFound", "message": "The specified notification not found" } } }, "description": "The specified notification not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/passkeys": { "get": { "summary": "List registered passkeys", "description": "Returns passkey credentials for current selected user", "tags": [ "Passkeys" ], "responses": { "200": { "description": "List of credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Passkey" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/passkeys/begin-auth": { "get": { "summary": "Begin passkey authentication", "description": "Generates and returns WebAuthn assertion (request) options. The server will set cookies to maintain the authentication challenge context. Optionally restrict by username.", "tags": [ "Passkeys" ], "parameters": [ { "name": "username", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false } ], "responses": { "200": { "description": "Request options", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicKeyCredentialRequestOptions" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ClientError", "message": "Invalid request from client" } } }, "description": "Invalid request from client" } }, "security": [] } }, "/api/v1/passkeys/begin-register": { "get": { "summary": "Begin passkey registration", "description": "Generates and returns WebAuthn creation options for the current user. The server will set cookies to maintain the registration challenge context.", "tags": [ "Passkeys" ], "responses": { "200": { "description": "Creation options", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicKeyCredentialCreationOptions" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ClientError", "message": "Invalid request from client" } } }, "description": "Invalid request from client" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/passkeys/finish-auth": { "post": { "summary": "Finish passkey authentication", "description": "Verifies the authenticator assertion against the stored challenge and returns a session token on success.", "tags": [ "Passkeys" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonObject" } } }, "required": true }, "responses": { "200": { "description": "Session key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Token" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ClientError", "message": "Invalid request from client" } } }, "description": "Invalid request from client" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "UserBadCreds": { "description": "Invalid user credentials provided", "value": { "errorCode": "UserBadCreds", "message": "Invalid user credentials provided" } }, "UserMissingCreds": { "description": "No credentials provided", "value": { "errorCode": "UserMissingCreds", "message": "No credentials provided" } } } } }, "description": "Unauthorized" } }, "security": [] } }, "/api/v1/passkeys/finish-register": { "post": { "summary": "Finish passkey registration", "description": "Validates the authenticator attestation response against the stored challenge and persists the new credential.", "tags": [ "Passkeys" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonObject" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Passkey" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ClientError", "message": "Invalid request from client" } } }, "description": "Invalid request from client" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/passkeys/{credentialId}": { "delete": { "summary": "Remove a registered passkey", "description": "Deletes a credential by id. Cannot remove last remaining login method.", "tags": [ "Passkeys" ], "parameters": [ { "name": "credentialId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "CantRemoveLastLogin": { "description": "Cannot remove the last login option", "value": { "errorCode": "CantRemoveLastLogin", "message": "Cannot remove the last login option" } }, "PasskeyNoAccess": { "description": "No access to the passkey", "value": { "errorCode": "PasskeyNoAccess", "message": "No access to the passkey" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PasskeyNotFound", "message": "Passkey not found" } } }, "description": "Passkey not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/polls/{pollId}/refresh": { "post": { "summary": "Refresh poll results", "description": "Refreshes poll results from the remote server if the poll is from a federated instance and the results may be stale. Returns the updated poll with current vote counts.", "tags": [ "Polls" ], "parameters": [ { "name": "pollId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Poll" } } } } }, "security": [ { "header": [] } ] } }, "/api/v1/polls/{pollId}/vote": { "post": { "summary": "Vote in a poll", "description": "Submit vote(s) for a poll. Multiple choices can be selected if the poll allows it. Users cannot vote in their own polls or vote multiple times.", "tags": [ "Polls" ], "parameters": [ { "name": "pollId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "requestBody": { "description": "List of zero-based option indices to vote for", "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "format": "int32", "type": "integer" } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "PollExpired": { "description": "The poll has already ended", "value": { "errorCode": "PollExpired", "message": "The poll has already ended" } }, "PollSelfVote": { "description": "You cannot vote in your own polls", "value": { "errorCode": "PollSelfVote", "message": "You cannot vote in your own polls" } }, "PollAlreadyVoted": { "description": "You have already voted on this poll", "value": { "errorCode": "PollAlreadyVoted", "message": "You have already voted on this poll" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "PostNotFound": { "description": "The specified post not found", "value": { "errorCode": "PostNotFound", "message": "The specified post not found" } }, "PollNotFound": { "description": "The specified poll not found", "value": { "errorCode": "PollNotFound", "message": "The specified poll not found" } } } } }, "description": "Not Found" } }, "security": [ { "header": [] } ] } }, "/api/v1/posts": { "get": { "summary": "Get posts feed", "description": "Returns posts based on various filters. For authenticated users, shows their personalized feed. For unauthenticated users, shows public posts only. Supports filtering by user, owner, tags, lists, bookmarks, and more. Can include comments, translations, and various metadata.", "tags": [ "Posts" ], "parameters": [ { "description": "Return results across all scopes when using bookmarkedOnly", "required": false, "name": "all", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Return bookmarked posts only. Posts that are no longer visible under current privacy/visibility rules are excluded.", "required": false, "name": "bookmarkedOnly", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Include bookmark field", "required": false, "name": "includeBookmarkStatus", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Include comments", "required": false, "name": "includeComments", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Include follow status", "required": false, "name": "includeFollowStatus", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Include pinned status", "required": false, "name": "includePinnedStatus", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Include direct reply if present", "required": false, "name": "includeReply", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "Limit first level comment paging count", "required": false, "name": "limitFirstLevelComments", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true } }, { "description": "Limit comments per level (applies to each parent). Overrides level-specific limits.", "required": false, "name": "limitPerLevelComments", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true } }, { "description": "Limit second level comment paging count", "required": false, "name": "limitSecondLevelComments", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true } }, { "description": "List posts by a user list", "required": false, "name": "listId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "Max comment level depth", "required": false, "name": "maxLevel", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true } }, { "description": "Min comment level depth", "required": false, "name": "minLevel", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true } }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "List specific owner's posts", "required": false, "name": "ownerId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "Filter by pinned status. Applied only if ?userId is present", "name": "pinned", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/PinnedParam" } ], "nullable": true }, "required": false }, { "description": "Filter by repost kind", "name": "repostKind", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/RepostParam" } ], "nullable": true }, "required": false }, { "description": "List only reposts of specified post", "required": false, "name": "repostOf", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "Return reposts only", "required": false, "name": "repostsOnly", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Search posts by text", "required": false, "name": "search", "in": "query", "schema": { "type": "string", "nullable": true } }, { "description": "If false - force showing reposts non-aggregated", "required": false, "name": "skipReposts", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Search posts by a tag", "required": false, "name": "tag", "in": "query", "schema": { "type": "string", "nullable": true } }, { "description": "Filter posts by multiple tags (comma-separated, AND logic - posts must have ALL tags)", "required": false, "name": "tags", "in": "query", "schema": { "type": "array", "items": { "type": "string" }, "nullable": true } }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "List specific user's posts. Used for User/Profile feed", "required": false, "name": "userId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "List specific user's posts", "required": false, "name": "username", "in": "query", "schema": { "type": "string", "nullable": true } }, { "description": "Include repostedBy. Default true", "name": "withRepostedBy", "in": "query", "schema": { "type": "boolean", "nullable": true }, "required": false }, { "description": "Include translation", "required": false, "name": "withTranslation", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Include trends", "name": "withTrends", "in": "query", "schema": { "type": "boolean", "nullable": true }, "required": false }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "PostsNoOwnerType": { "description": "An ownerType must be provided", "value": { "errorCode": "PostsNoOwnerType", "message": "An ownerType must be provided" } }, "PostsPinnedRequiresUserId": { "description": "The pinned parameter requires a userId", "value": { "errorCode": "PostsPinnedRequiresUserId", "message": "The pinned parameter requires a userId" } } } } }, "description": "Bad Request" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "GroupNoPublicAccess": { "description": "The group must be public or the requesting user must be a member of the group", "value": { "errorCode": "GroupNoPublicAccess", "message": "The group must be public or the requesting user must be a member of the group" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "EventNotFound": { "description": "The specified event not found", "value": { "errorCode": "EventNotFound", "message": "The specified event not found" } }, "PostsListNotFound": { "description": "The specified list not found", "value": { "errorCode": "PostsListNotFound", "message": "The specified list not found" } } } } }, "description": "Not Found" } }, "security": [] }, "post": { "summary": "Create a new post", "description": "Creates a new post with text content. Can be a regular post, article, or other post type. Posts can be public, unlisted, followers-only, or direct messages. Sensitive content requires a content warning. The post is automatically distributed to followers and federated instances.", "tags": [ "Posts" ], "parameters": [ { "description": "Scope owner to resolve the post context", "required": false, "name": "ownerId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePost" } } }, "required": true }, "responses": { "200": { "description": "Post object just created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PostsSensitiveContentWarning", "message": "The sensitive flag must be set together with a content warning" } } }, "description": "The sensitive flag must be set together with a content warning" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/posts/bookmarked": { "get": { "summary": "Get bookmarked posts", "description": "Returns posts that the currently authenticated user has bookmarked and can still access under current privacy/visibility rules. Use my=true to return only the user's own bookmarked posts.", "tags": [ "Posts" ], "parameters": [ { "description": "Include comments. Default true", "required": false, "name": "includeComments", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Include publisher context with group info (avatar, name, slug)", "required": false, "name": "includePublisher", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Include reply-to post in originalPost field. Default true", "required": false, "name": "includeReply", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "Return only the user's own bookmarked posts", "required": false, "name": "my", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "Scope owner to resolve the post context", "required": false, "name": "ownerId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "Search posts by text", "required": false, "name": "search", "in": "query", "schema": { "type": "string", "nullable": true } }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "GroupNoPublicAccess": { "description": "The group must be public or the requesting user must be a member of the group", "value": { "errorCode": "GroupNoPublicAccess", "message": "The group must be public or the requesting user must be a member of the group" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EventNotFound", "message": "The specified event not found" } } }, "description": "The specified event not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/posts/feeds/following": { "get": { "summary": "Get home feed", "description": "Returns the home feed showing posts from accounts the current user follows. This is the main timeline feed. Supports caching for performance, with fallback to database if cache is empty or regenerating. Can include follow status, bookmarks, and translations.", "tags": [ "Posts" ], "parameters": [ { "description": "Load from database", "required": false, "name": "ignoreCache", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Include bookmark field", "name": "includeBookmarkStatus", "in": "query", "schema": { "type": "boolean", "nullable": true }, "required": false }, { "description": "Include follow status", "name": "includeFollowStatus", "in": "query", "schema": { "type": "boolean", "nullable": true }, "required": false }, { "description": "Include publisher context with group info (avatar, name, slug)", "name": "includePublisher", "in": "query", "schema": { "type": "boolean", "nullable": true }, "required": false }, { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "Include repostedBy. Default true", "name": "withRepostedBy", "in": "query", "schema": { "type": "boolean", "nullable": true }, "required": false }, { "description": "Include translation", "name": "withTranslation", "in": "query", "schema": { "type": "boolean", "nullable": true }, "required": false }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/posts/feeds/public": { "get": { "summary": "Get public posts feed", "description": "Returns a feed of public posts visible to everyone. Can be filtered by owner type, local vs federated posts, and whether to include reposts. Supports various metadata inclusions like follow status, bookmarks, translations, and trends. Also called Discover Feed.", "tags": [ "Posts" ], "parameters": [ { "description": "Include bookmark field", "name": "includeBookmarkStatus", "in": "query", "schema": { "type": "boolean", "nullable": true }, "required": false }, { "description": "Include follow status", "name": "includeFollowStatus", "in": "query", "schema": { "type": "boolean", "nullable": true }, "required": false }, { "description": "Include publisher context with group info (avatar, name, slug)", "name": "includePublisher", "in": "query", "schema": { "type": "boolean", "nullable": true }, "required": false }, { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "List only local posts (if true). Remote only if false. Any if null", "name": "local", "in": "query", "schema": { "type": "boolean", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "If false - force showing reposts", "name": "skipReposts", "in": "query", "schema": { "type": "boolean", "nullable": true }, "required": false }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "Include repostedBy. Default true", "name": "withRepostedBy", "in": "query", "schema": { "type": "boolean", "nullable": true }, "required": false }, { "description": "Include translation", "name": "withTranslation", "in": "query", "schema": { "type": "boolean", "nullable": true }, "required": false }, { "description": "Include trends", "name": "withTrends", "in": "query", "schema": { "type": "boolean", "nullable": true }, "required": false }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PostsNoOwnerType", "message": "An ownerType must be provided" } } }, "description": "An ownerType must be provided" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "GroupNoPublicAccess": { "description": "The group must be public or the requesting user must be a member of the group", "value": { "errorCode": "GroupNoPublicAccess", "message": "The group must be public or the requesting user must be a member of the group" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EventNotFound", "message": "The specified event not found" } } }, "description": "The specified event not found" } }, "security": [] } }, "/api/v1/posts/liked": { "get": { "summary": "Get liked posts", "description": "Returns all posts that the currently authenticated user has liked. Can be filtered by owner type to show only posts from users, groups, categories, or events.", "tags": [ "Posts" ], "parameters": [ { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "Scope owner to resolve the post context", "required": false, "name": "ownerId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "GroupNoPublicAccess": { "description": "The group must be public or the requesting user must be a member of the group", "value": { "errorCode": "GroupNoPublicAccess", "message": "The group must be public or the requesting user must be a member of the group" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EventNotFound", "message": "The specified event not found" } } }, "description": "The specified event not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/posts/mentioned": { "get": { "summary": "Get posts with mentions", "description": "Returns all posts where the currently authenticated user was mentioned. Can be filtered by owner type and privacy level (e.g., to show only direct messages where mentioned).", "tags": [ "Posts" ], "parameters": [ { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "Scope owner to resolve the post context", "required": false, "name": "ownerId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "Filter posts by DIRECT only", "required": false, "name": "private", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "GroupNoPublicAccess": { "description": "The group must be public or the requesting user must be a member of the group", "value": { "errorCode": "GroupNoPublicAccess", "message": "The group must be public or the requesting user must be a member of the group" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EventNotFound", "message": "The specified event not found" } } }, "description": "The specified event not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/posts/my": { "get": { "summary": "Get current user's posts", "description": "Returns all posts created by the currently authenticated user. Can filter for reposts only or bookmarked posts only. Optionally includes comments and bookmark status.", "tags": [ "Posts" ], "parameters": [ { "description": "Return bookmarked only", "required": false, "name": "bookmarkedOnly", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Include bookmark field", "required": false, "name": "includeBookmarkStatus", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Include comments", "required": false, "name": "includeComments", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "Scope owner to resolve the post context", "required": false, "name": "ownerId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "Return reposts only", "required": false, "name": "repostsOnly", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "GroupNoPublicAccess": { "description": "The group must be public or the requesting user must be a member of the group", "value": { "errorCode": "GroupNoPublicAccess", "message": "The group must be public or the requesting user must be a member of the group" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EventNotFound", "message": "The specified event not found" } } }, "description": "The specified event not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/posts/pins": { "get": { "summary": "List pins and highlights", "description": "Returns pinned post IDs ordered by pin time (newest first). By default returns only top-level `Pins` (`postOnly=true`). Set `postOnly=false` to include reply `Highlights` as well. When `ownerId` is provided, returns pins for that scope owner after access checks.", "tags": [ "Pins" ], "parameters": [ { "description": "Optional scope owner ID used to list pins in a specific scope (supported: USER, EVENT).", "required": false, "name": "ownerId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "If true (default), return only top-level pins. If false, return both top-level pins and reply highlights.", "required": false, "name": "postOnly", "in": "query", "schema": { "type": "boolean", "nullable": true } } ], "responses": { "200": { "description": "List of pinned posts ids", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypeId" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "GroupNoPublicAccess": { "description": "The group must be public or the requesting user must be a member of the group", "value": { "errorCode": "GroupNoPublicAccess", "message": "The group must be public or the requesting user must be a member of the group" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EventNotFound", "message": "The specified event not found" } } }, "description": "The specified event not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/posts/pins/{postId}": { "delete": { "summary": "Unpin post or remove highlight", "description": "Removes a previously pinned post. For root posts, removes a top-level `Pin`; for replies, removes a `Highlight`. In personal scope, only the root post author can manage pins/highlights; in groups, owner/admin roles can manage them. The action is federated via ActivityPub `Remove`.", "tags": [ "Pins" ], "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "PostNotFound": { "description": "The specified post not found", "value": { "errorCode": "PostNotFound", "message": "The specified post not found" } }, "PostWasNotPinned": { "description": "The post was not pinned", "value": { "errorCode": "PostWasNotPinned", "message": "The post was not pinned" } } } } }, "description": "Not Found" } }, "security": [ { "header": [] } ] }, "post": { "summary": "Pin post or highlight reply", "description": "Pins the specified post. For a root post, this creates a top-level `Pin` in the profile/scope. For a reply, this creates a `Highlight` under the root post. In personal scope, only the root post author can manage pins/highlights; in groups, owner/admin roles can manage them. Reposts and direct posts cannot be pinned. Top-level pin count is limited by admin settings (`Maximum number of pinned posts`). The action is federated via ActivityPub `Add`.", "tags": [ "Pins" ], "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "HiddenCantPin", "message": "Hidden posts can't be pinned" } } }, "description": "Hidden posts can't be pinned" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "RepostCantPin": { "description": "A repost cannot be pinned", "value": { "errorCode": "RepostCantPin", "message": "A repost cannot be pinned" } }, "OnlyOwnCanPin": { "description": "Only your own posts can be pinned", "value": { "errorCode": "OnlyOwnCanPin", "message": "Only your own posts can be pinned" } }, "DirectCantPin": { "description": "Direct posts can't be pinned", "value": { "errorCode": "DirectCantPin", "message": "Direct posts can't be pinned" } }, "PostPinLimit": { "description": "You have already pinned the maximum number of posts", "value": { "errorCode": "PostPinLimit", "message": "You have already pinned the maximum number of posts" } }, "NotGroupMember": { "description": "The user must be a member of the group", "value": { "errorCode": "NotGroupMember", "message": "The user must be a member of the group" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PostNotFound", "message": "The specified post not found" } } }, "description": "The specified post not found" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PostAlreadyPinned", "message": "The post has already been pinned" } } }, "description": "The post has already been pinned" } }, "security": [ { "header": [] } ] } }, "/api/v1/posts/replies": { "get": { "summary": "Get user's replies", "description": "Returns posts that a user has replied to, along with their replies. Shows the original post as the parent with the user's reply nested within it. Useful for viewing a user's conversation participation.", "tags": [ "Posts" ], "parameters": [ { "description": "When true, show posts from all accessible channels instead of only subscribed ones. Members see all channels (public + private); non-members still see only public channels.", "name": "allChannels", "in": "query", "schema": { "type": "boolean", "nullable": true }, "required": false }, { "description": "Scope replies to all channels within a group. Mutually exclusive with ownerId.", "name": "groupId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true }, "required": false }, { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "Only include posts from channels that have this app_meta namespace key (e.g. 'wellesley.group.forum' for forum categories)", "name": "ownerAppMetaHas", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Exclude posts from channels that have this app_meta namespace key", "name": "ownerAppMetaLacks", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Filter by channel kind: 'channel' for regular channels, 'category' for forum categories. Preferred over ownerAppMetaHas/ownerAppMetaLacks for kind-based filtering.", "name": "ownerChannelKind", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/GroupChannelKind" } ], "nullable": true }, "required": false }, { "description": "Scope owner to resolve the post context", "required": false, "name": "ownerId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "List specific user's posts", "required": false, "name": "userId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "List specific user's posts", "required": false, "name": "username", "in": "query", "schema": { "type": "string", "nullable": true } }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "PostsRepliesAbsentParams": { "description": "The userId or username must be provided", "value": { "errorCode": "PostsRepliesAbsentParams", "message": "The userId or username must be provided" } }, "PostsRepliesOwnerIdAndGroupIdMutuallyExclusive": { "description": "ownerId and groupId are mutually exclusive", "value": { "errorCode": "PostsRepliesOwnerIdAndGroupIdMutuallyExclusive", "message": "ownerId and groupId are mutually exclusive" } }, "PostsRepliesGroupParamsRequireGroupId": { "description": "ownerChannelKind, ownerAppMetaHas, ownerAppMetaLacks and allChannels require groupId", "value": { "errorCode": "PostsRepliesGroupParamsRequireGroupId", "message": "ownerChannelKind, ownerAppMetaHas, ownerAppMetaLacks and allChannels require groupId" } }, "PostsRepliesAppMetaConflict": { "description": "ownerAppMetaHas and ownerAppMetaLacks cannot be the same value", "value": { "errorCode": "PostsRepliesAppMetaConflict", "message": "ownerAppMetaHas and ownerAppMetaLacks cannot be the same value" } } } } }, "description": "Bad Request" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "GroupNoPublicAccess": { "description": "The group must be public or the requesting user must be a member of the group", "value": { "errorCode": "GroupNoPublicAccess", "message": "The group must be public or the requesting user must be a member of the group" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "EventNotFound": { "description": "The specified event not found", "value": { "errorCode": "EventNotFound", "message": "The specified event not found" } }, "GroupNotFound": { "description": "Group not found", "value": { "errorCode": "GroupNotFound", "message": "Group not found" } } } } }, "description": "Not Found" } }, "security": [] } }, "/api/v1/posts/subscriptions": { "get": { "summary": "Get subscribed posts", "description": "Returns all posts the authenticated user is subscribed to for notifications. Can be filtered by scope owner or return all subscriptions across scopes with ?all=true. Requires authentication.", "tags": [ "Posts" ], "parameters": [ { "description": "Return all subscriptions", "required": false, "name": "all", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Scope owner to resolve the post context", "required": false, "name": "ownerId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "GroupNoPublicAccess": { "description": "The group must be public or the requesting user must be a member of the group", "value": { "errorCode": "GroupNoPublicAccess", "message": "The group must be public or the requesting user must be a member of the group" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "EventNotFound", "message": "The specified event not found" } } }, "description": "The specified event not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/posts/{postId}": { "put": { "summary": "Update post content", "description": "Updates an existing post's content, privacy settings, or metadata. Only the post author can update their own posts. Cannot update comments through this endpoint. Sensitive content must include a content warning.", "tags": [ "Posts" ], "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePost" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PostsSensitiveContentWarning", "message": "The sensitive flag must be set together with a content warning" } } }, "description": "The sensitive flag must be set together with a content warning" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PostsCantChangeOthersPost", "message": "Cannot update another user's post" } } }, "description": "Cannot update another user's post" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PostNotFound", "message": "The specified post not found" } } }, "description": "The specified post not found" } }, "security": [ { "header": [] } ] }, "get": { "summary": "Get post by ID", "description": "Retrieves a specific post by its ID. Can optionally include comments with configurable depth levels, parent posts for comments, bookmarks, translations, trends, and repost information. Supports building comment trees with specified depth limits.", "tags": [ "Posts" ], "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Include bookmark field", "required": false, "name": "includeBookmarkStatus", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Include publisher context with group info (avatar, name, slug)", "name": "includePublisher", "in": "query", "schema": { "type": "boolean", "nullable": true }, "required": false }, { "description": "Limit first level comment paging count", "required": false, "name": "limitFirstLevelComments", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true } }, { "description": "Limit comments per level (applies to each parent). Overrides level-specific limits.", "required": false, "name": "limitPerLevelComments", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true } }, { "description": "Limit second level comment paging count", "required": false, "name": "limitSecondLevelComments", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true } }, { "description": "Max comment level depth", "required": false, "name": "maxLevel", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true } }, { "description": "Min comment level depth", "required": false, "name": "minLevel", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true } }, { "description": "Load post with comments", "required": false, "name": "withComments", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "If comment, load it with parents.\n In such a case returns root with request `postId` comment inside replies", "required": false, "name": "withParents", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Include repostedBy. Default true", "name": "withRepostedBy", "in": "query", "schema": { "type": "boolean", "nullable": true }, "required": false }, { "description": "If comment, load it with root parent.\n In such a case returns root with request `postId` comment inside replies", "required": false, "name": "withRootParent", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Include translation", "required": false, "name": "withTranslation", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Include trends", "name": "withTrends", "in": "query", "schema": { "type": "boolean", "nullable": true }, "required": false }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "GroupNoPublicAccess": { "description": "The group must be public or the requesting user must be a member of the group", "value": { "errorCode": "GroupNoPublicAccess", "message": "The group must be public or the requesting user must be a member of the group" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PostNotFound", "message": "The specified post not found" } } }, "description": "The specified post not found" } }, "security": [] }, "delete": { "summary": "Delete a post", "description": "Permanently deletes a post. Only the post author can delete their own posts. This action removes the post from all timelines and sends deletion notifications to federated instances.", "tags": [ "Posts" ], "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "Post has been deleted successfully", "content": { "application/json": { "schema": {} } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PostsCantChangeOthersPost", "message": "Cannot update another user's post" } } }, "description": "Cannot update another user's post" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PostNotFound", "message": "The specified post not found" } } }, "description": "The specified post not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/posts/{postId}/active-users": { "get": { "summary": "Get active users in conversation", "description": "Returns users who have posted in this conversation thread, including their avatars, reply counts, and last post time. Works for any post type (personal, group channel, event). Includes both current and former group members for group contexts. Excludes blocked/muted users, deleted posts, and suspended users.", "tags": [ "Posts" ], "parameters": [ { "description": "Post ID in the conversation (navigates to thread root automatically)", "required": true, "name": "postId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "Sort order: REPLY_COUNT (by number of replies) or LAST_POST (by most recent post)", "required": false, "name": "sortBy", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/ConversationActiveUserSortBy" } ], "nullable": true } }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationActiveUsersResult" } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "GroupNoPublicAccess": { "description": "The group must be public or the requesting user must be a member of the group", "value": { "errorCode": "GroupNoPublicAccess", "message": "The group must be public or the requesting user must be a member of the group" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PostNotFound", "message": "The specified post not found" } } }, "description": "The specified post not found" } }, "security": [] } }, "/api/v1/posts/{postId}/bookmark": { "delete": { "summary": "Remove bookmark", "description": "Removes a post from the authenticated user's bookmarks. Fails if the post was not previously bookmarked. This action is private and does not notify the post author.", "tags": [ "Posts" ], "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "PostNotFound": { "description": "The specified post not found", "value": { "errorCode": "PostNotFound", "message": "The specified post not found" } }, "PostWasNotBookmarked": { "description": "The bookmark record not found", "value": { "errorCode": "PostWasNotBookmarked", "message": "The bookmark record not found" } } } } }, "description": "Not Found" } }, "security": [ { "header": [] } ] }, "post": { "summary": "Bookmark a post", "description": "Adds a post to the authenticated user's bookmarks for later reading. Bookmarks are private and not visible to other users or the post author. Each post can only be bookmarked once per user.", "tags": [ "Posts" ], "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "GroupNoPublicAccess": { "description": "The group must be public or the requesting user must be a member of the group", "value": { "errorCode": "GroupNoPublicAccess", "message": "The group must be public or the requesting user must be a member of the group" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PostNotFound", "message": "The specified post not found" } } }, "description": "The specified post not found" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PostAlreadyBookmarked", "message": "The post has already been bookmarked" } } }, "description": "The post has already been bookmarked" } }, "security": [ { "header": [] } ] } }, "/api/v1/posts/{postId}/commenters": { "get": { "summary": "Get post commenters", "description": "Returns a list of unique users who have commented on a specific post. Includes follow relationship status and supports deduplication of multiple comments by the same user.", "tags": [ "Posts" ], "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Include followed status", "required": false, "name": "includeFollowedStatus", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Include following status", "required": false, "name": "includeFollowingStatus", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "Deduplicate comments by same user (default: true)", "required": false, "name": "skipDuplicates", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostActivity" } } } } } }, "security": [] } }, "/api/v1/posts/{postId}/comments": { "get": { "summary": "Get post comments", "description": "Retrieves all comments for a specific post. Supports pagination and configurable comment depth levels. Returns an empty list if comments are disabled for the post. Comments are organized in a tree structure based on their reply relationships.", "tags": [ "Posts" ], "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "Limit for direct replies (first level). For root posts: limits all first-level comments. For comments: limits direct replies only. Returns X-Total-Count header with total.", "required": false, "name": "limitFirstLevelComments", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true } }, { "description": "Limit for nested comments (per parent). For root posts: same as limitFirstLevelComments if not set. For comments: limits deeper nested levels (not direct replies).", "required": false, "name": "limitPerLevelComments", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true } }, { "name": "maxLevel", "in": "query", "schema": { "format": "int32", "maximum": 100, "minimum": 0, "type": "integer", "nullable": true }, "required": false }, { "name": "minLevel", "in": "query", "schema": { "format": "int32", "maximum": 100, "minimum": 0, "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "Filter by pinned status: ONLY (pinned only), SKIP (exclude pinned), ALL (both)", "required": false, "name": "pinned", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/PinnedParam" } ], "nullable": true } }, { "description": "If true, return only the first comment per unique user", "required": false, "name": "skipDuplicates", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "GroupNoPublicAccess": { "description": "The group must be public or the requesting user must be a member of the group", "value": { "errorCode": "GroupNoPublicAccess", "message": "The group must be public or the requesting user must be a member of the group" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PostNotFound", "message": "The specified post not found" } } }, "description": "The specified post not found" } }, "security": [] }, "post": { "summary": "Create a comment", "description": "Creates a new comment on a post. Comments can be nested replies to other comments. The authenticated user becomes the comment author. Comments inherit visibility from their parent post.", "tags": [ "Posts" ], "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePost" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } }, "400": { "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "GroupNoPublicAccess": { "description": "The group must be public or the requesting user must be a member of the group", "value": { "errorCode": "GroupNoPublicAccess", "message": "The group must be public or the requesting user must be a member of the group" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PostNotFound", "message": "The specified post not found" } } }, "description": "The specified post not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/posts/{postId}/comments/{commentId}": { "put": { "summary": "Update a comment", "description": "Updates an existing comment's content. Only the comment author can update their own comments. The comment must belong to the specified post. Maintains the comment's position in the thread hierarchy.", "tags": [ "Posts" ], "parameters": [ { "name": "commentId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "name": "postId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePost" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } }, "400": { "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "PostsCantChangeOthersComment": { "description": "Cannot update another user's comment", "value": { "errorCode": "PostsCantChangeOthersComment", "message": "Cannot update another user's comment" } }, "PostsCommentForWrongPost": { "description": "The comment does not belong to the specified post", "value": { "errorCode": "PostsCommentForWrongPost", "message": "The comment does not belong to the specified post" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "PostNotFound": { "description": "The specified post not found", "value": { "errorCode": "PostNotFound", "message": "The specified post not found" } }, "PostCommentNotFound": { "description": "The specified post comment not found", "value": { "errorCode": "PostCommentNotFound", "message": "The specified post comment not found" } } } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PostCommentNoUpdated", "message": "Failed to update the post comment" } } }, "description": "Failed to update the post comment" } }, "security": [ { "header": [] } ] }, "delete": { "summary": "Delete a comment", "description": "Permanently deletes a comment from a post. Only the comment author can delete their own comments. The comment must belong to the specified post. Child comments may be affected depending on the platform's threading model.", "tags": [ "Posts" ], "parameters": [ { "name": "commentId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "name": "postId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "Comment has been deleted successfully", "content": { "application/json": { "schema": {} } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PostsCommentForWrongPost", "message": "The comment does not belong to the specified post" } } }, "description": "The comment does not belong to the specified post" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "PostNotFound": { "description": "The specified post not found", "value": { "errorCode": "PostNotFound", "message": "The specified post not found" } }, "PostCommentNotFound": { "description": "The specified post comment not found", "value": { "errorCode": "PostCommentNotFound", "message": "The specified post comment not found" } } } } }, "description": "Not Found" } }, "security": [ { "header": [] } ] } }, "/api/v1/posts/{postId}/detach": { "post": { "summary": "Detach repost from original", "description": "Allows the original post author to detach a repost or quote from their post. This breaks the connection between the repost and the original, typically used when the repost violates the author's wishes or contains inappropriate commentary.", "tags": [ "Posts" ], "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PostsCannotDetach", "message": "Cannot detach post. Please detach a repost or a quote" } } }, "description": "Cannot detach post. Please detach a repost or a quote" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PostsCantChangeOthersPost", "message": "Cannot update another user's post" } } }, "description": "Cannot update another user's post" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PostNotFound", "message": "The specified post not found" } } }, "description": "The specified post not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/posts/{postId}/downvote": { "post": { "summary": "Downvote a post", "description": "Adds a negative vote to a post from the authenticated user. If the user previously upvoted, the vote is changed to a downvote. Users cannot vote on their own posts. Returns the updated vote summary.", "tags": [ "Posts" ], "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ], "responses": { "200": { "description": "A summary of votes for the post", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostVotesSummary" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "GroupNoPublicAccess": { "description": "The group must be public or the requesting user must be a member of the group", "value": { "errorCode": "GroupNoPublicAccess", "message": "The group must be public or the requesting user must be a member of the group" } }, "NoVotingOnOwnPost": { "description": "Voting on own post is not allowed", "value": { "errorCode": "NoVotingOnOwnPost", "message": "Voting on own post is not allowed" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PostNotFound", "message": "The specified post not found" } } }, "description": "The specified post not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/posts/{postId}/edits": { "get": { "summary": "View edit history of a post", "description": "Retrieves the complete edit history of a post, showing all versions from creation to current state. Each edit includes the text, media, mentions, and timestamp of the change. Useful for transparency and tracking post modifications over time.", "tags": [ "Posts" ], "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostEdit" } } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "GroupNoPublicAccess": { "description": "The group must be public or the requesting user must be a member of the group", "value": { "errorCode": "GroupNoPublicAccess", "message": "The group must be public or the requesting user must be a member of the group" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PostNotFound", "message": "The specified post not found" } } }, "description": "The specified post not found" } }, "security": [] } }, "/api/v1/posts/{postId}/interaction-policy": { "put": { "summary": "Update the quote approval policy on a post", "description": "Sets the per-post quote approval policy. Only the post author can update this. Values: PUBLIC (anyone can quote), FOLLOWERS (only followers), NOBODY (all quotes require approval).", "tags": [ "Posts" ], "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateInteractionPolicy" } } }, "required": true }, "responses": { "200": { "description": "Updated post", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } }, "400": { "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PostsCantChangeOthersPost", "message": "Cannot update another user's post" } } }, "description": "Cannot update another user's post" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PostNotFound", "message": "The specified post not found" } } }, "description": "The specified post not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/posts/{postId}/likes": { "get": { "summary": "Get post likes", "description": "Returns a list of users who have liked a specific post. Can include follow relationship status between the viewer and the liking users. Supports pagination for posts with many likes.", "tags": [ "Posts" ], "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Include followed status", "required": false, "name": "includeFollowedStatus", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Include following status", "required": false, "name": "includeFollowingStatus", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostActivity" } } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "GroupNoPublicAccess": { "description": "The group must be public or the requesting user must be a member of the group", "value": { "errorCode": "GroupNoPublicAccess", "message": "The group must be public or the requesting user must be a member of the group" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PostNotFound", "message": "The specified post not found" } } }, "description": "The specified post not found" } }, "security": [] }, "delete": { "summary": "Unlike a post", "description": "Removes the authenticated user's like from a post. Returns the new total number of likes. Sends unlike notifications and federates the activity. Fails if the post was not previously liked.", "tags": [ "Posts" ], "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "New number of likes", "content": { "application/json": { "schema": { "type": "integer" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "PostNotFound": { "description": "The specified post not found", "value": { "errorCode": "PostNotFound", "message": "The specified post not found" } }, "PostWasNotLiked": { "description": "The like record not found", "value": { "errorCode": "PostWasNotLiked", "message": "The like record not found" } } } } }, "description": "Not Found" } }, "security": [ { "header": [] } ] }, "post": { "summary": "Like a post", "description": "Adds a like to a post from the authenticated user. Each user can only like a post once. Returns the new total number of likes. Sends like notifications to the post author and federates the activity.", "tags": [ "Posts" ], "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "New number of likes", "content": { "application/json": { "schema": { "type": "integer" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "GroupNoPublicAccess": { "description": "The group must be public or the requesting user must be a member of the group", "value": { "errorCode": "GroupNoPublicAccess", "message": "The group must be public or the requesting user must be a member of the group" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PostNotFound", "message": "The specified post not found" } } }, "description": "The specified post not found" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PostAlreadyLiked", "message": "The post has already been liked" } } }, "description": "The post has already been liked" } }, "security": [ { "header": [] } ] } }, "/api/v1/posts/{postId}/mute": { "post": { "summary": "Mute a conversation", "description": "Mutes the conversation that the specified post belongs to. When a conversation is muted, notifications for activity in that thread are suppressed. Posts still appear in feeds and streams.", "tags": [ "Posts" ], "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "GroupNoPublicAccess": { "description": "The group must be public or the requesting user must be a member of the group", "value": { "errorCode": "GroupNoPublicAccess", "message": "The group must be public or the requesting user must be a member of the group" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PostNotFound", "message": "The specified post not found" } } }, "description": "The specified post not found" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ConversationAlreadyMuted", "message": "The conversation is already muted" } } }, "description": "The conversation is already muted" } }, "security": [ { "header": [] } ] } }, "/api/v1/posts/{postId}/quotes": { "get": { "summary": "List accepted quotes of a post", "description": "Returns a paginated list of posts that quote the specified post and have been accepted.", "tags": [ "Posts" ], "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "maximum": 40, "minimum": 1, "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "minimum": 0, "type": "integer", "nullable": true }, "required": false }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ], "responses": { "200": { "description": "List of quoting posts", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } } } } }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PostNotFound", "message": "The specified post not found" } } }, "description": "The specified post not found" } }, "security": [] } }, "/api/v1/posts/{postId}/quotes/{quoteAuthId}/revoke": { "post": { "summary": "Revoke a quote authorization", "description": "Revokes an accepted quote authorization. Only the quoted post's author can revoke. The quoting post will no longer be listed as an accepted quote.", "tags": [ "Posts" ], "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "name": "quoteAuthId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PostsCantChangeOthersPost", "message": "Cannot update another user's post" } } }, "description": "Cannot update another user's post" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "PostNotFound": { "description": "The specified post not found", "value": { "errorCode": "PostNotFound", "message": "The specified post not found" } }, "QuoteAuthNotFound": { "description": "Quote authorization not found", "value": { "errorCode": "QuoteAuthNotFound", "message": "Quote authorization not found" } } } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "QuoteAlreadyRevoked", "message": "Quote authorization has already been revoked" } } }, "description": "Quote authorization has already been revoked" } }, "security": [ { "header": [] } ] } }, "/api/v1/posts/{postId}/refresh-card": { "post": { "summary": "Refresh the preview card for a post", "description": "Regenerates the link preview card for a post that contains URLs. Only the post author can refresh the card. This is useful when the linked content has changed and you want to update the preview information.", "tags": [ "Posts" ], "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "Updated card data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Card" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "GroupNoPublicAccess": { "description": "The group must be public or the requesting user must be a member of the group", "value": { "errorCode": "GroupNoPublicAccess", "message": "The group must be public or the requesting user must be a member of the group" } }, "PostsCantChangeOthersPost": { "description": "Cannot update another user's post", "value": { "errorCode": "PostsCantChangeOthersPost", "message": "Cannot update another user's post" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "PostNotFound": { "description": "The specified post not found", "value": { "errorCode": "PostNotFound", "message": "The specified post not found" } }, "LinkPreviewNotAvailable": { "description": "Link preview not available", "value": { "errorCode": "LinkPreviewNotAvailable", "message": "Link preview not available" } } } } }, "description": "Not Found" } }, "security": [ { "header": [] } ] } }, "/api/v1/posts/{postId}/repost": { "delete": { "summary": "Undo a repost", "description": "Removes your repost or quote of a specific post. This deletes the repost from your timeline and notifies the original author. Only your own reposts can be undone.", "tags": [ "Posts" ], "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PostsCantChangeOthersPost", "message": "Cannot update another user's post" } } }, "description": "Cannot update another user's post" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PostNotFound", "message": "The specified post not found" } } }, "description": "The specified post not found" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PostNotReposted", "message": "The post has not been reposted" } } }, "description": "The post has not been reposted" } }, "security": [ { "header": [] } ] }, "post": { "summary": "Repost or quote another post", "description": "Creates a repost (boost) or quote post of someone else's content. Regular reposts simply share the original post, while quotes add your own commentary. Only public posts and public follow-posts can be reposted. You cannot repost a repost.", "tags": [ "Posts" ], "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ], "requestBody": { "description": "Optional param, omit for repost or specify with 'text' to create a quote", "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePost" } } } }, "responses": { "200": { "description": "Post object just created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PostsCannotRepostRepost", "message": "Cannot repost a repost. Please repost the original" } } }, "description": "Cannot repost a repost. Please repost the original" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PostsRepostPublicOnly", "message": "Only public posts can be reposted" } } }, "description": "Only public posts can be reposted" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PostNotFound", "message": "The specified post not found" } } }, "description": "The specified post not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/posts/{postId}/reposts": { "get": { "summary": "Get post reposts", "description": "Returns a list of users who have reposted or quoted a specific post. Can filter by repost type (regular repost vs quote). Includes follow relationship status and supports deduplication of multiple reposts by the same user.", "tags": [ "Posts" ], "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Include followed status", "required": false, "name": "includeFollowedStatus", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Include following status", "required": false, "name": "includeFollowingStatus", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Filter by repost type: REPOST, QUOTE, or ALL", "required": false, "name": "kind", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/RepostParam" } ], "nullable": true } }, { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "If true, deduplicate multiple reposts by the same user", "required": false, "name": "skipDuplicates", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PostActivity" } } } } } }, "security": [] } }, "/api/v1/posts/{postId}/subscription": { "put": { "summary": "Subscribe to post notifications", "description": "Subscribes the authenticated user to receive notifications for new activity on a post (new comments, edits, etc.). Users cannot subscribe to their own posts as they already receive notifications by default. For remote posts, sends a Follow(post) ActivityPub activity.", "tags": [ "Posts" ], "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "GroupNoPublicAccess": { "description": "The group must be public or the requesting user must be a member of the group", "value": { "errorCode": "GroupNoPublicAccess", "message": "The group must be public or the requesting user must be a member of the group" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PostNotFound", "message": "The specified post not found" } } }, "description": "The specified post not found" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "PostAlreadySubscribed": { "description": "The post has already been subscribed to", "value": { "errorCode": "PostAlreadySubscribed", "message": "The post has already been subscribed to" } }, "SubscribeSelf": { "description": "Cannot subscribe to your own post", "value": { "errorCode": "SubscribeSelf", "message": "Cannot subscribe to your own post" } } } } }, "description": "Conflict" } }, "security": [ { "header": [] } ] }, "get": { "summary": "Get subscription status for a post", "description": "Returns 200 if the authenticated user is subscribed to this post's notifications, or 404 if not subscribed.", "tags": [ "Posts" ], "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "User is subscribed to this post", "content": { "application/json": { "schema": {} } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "GroupNoPublicAccess": { "description": "The group must be public or the requesting user must be a member of the group", "value": { "errorCode": "GroupNoPublicAccess", "message": "The group must be public or the requesting user must be a member of the group" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "EventNotFound": { "description": "The specified event not found", "value": { "errorCode": "EventNotFound", "message": "The specified event not found" } }, "PostNotFound": { "description": "The specified post not found", "value": { "errorCode": "PostNotFound", "message": "The specified post not found" } }, "PostWasNotSubscribed": { "description": "The subscription to post not found", "value": { "errorCode": "PostWasNotSubscribed", "message": "The subscription to post not found" } } } } }, "description": "Not Found" } }, "security": [ { "header": [] } ] }, "delete": { "summary": "Unsubscribe from post", "description": "Removes the subscription for post notifications. The user will no longer receive notifications about new activity on this post. For remote posts, sends an Undo(Follow(post)) ActivityPub activity.", "tags": [ "Posts" ], "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "PostNotFound": { "description": "The specified post not found", "value": { "errorCode": "PostNotFound", "message": "The specified post not found" } }, "PostWasNotSubscribed": { "description": "The subscription to post not found", "value": { "errorCode": "PostWasNotSubscribed", "message": "The subscription to post not found" } } } } }, "description": "Not Found" } }, "security": [ { "header": [] } ] } }, "/api/v1/posts/{postId}/track-view": { "post": { "summary": "Track post view", "description": "Records that a user has viewed this post. Used for analytics and engagement metrics. Works for both authenticated and unauthenticated users.", "tags": [ "Posts" ], "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "GroupNoPublicAccess": { "description": "The group must be public or the requesting user must be a member of the group", "value": { "errorCode": "GroupNoPublicAccess", "message": "The group must be public or the requesting user must be a member of the group" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PostNotFound", "message": "The specified post not found" } } }, "description": "The specified post not found" } }, "security": [] } }, "/api/v1/posts/{postId}/translate": { "post": { "summary": "Translate post content", "description": "Translates the text content of a post to the specified target language. Can return either plain text or HTML formatted translation. Uses automatic translation services to provide the translation.", "tags": [ "Posts" ], "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "If true, returns HTML-formatted translation instead of plain text", "required": false, "name": "htmlContent", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Target language code for translation", "required": true, "name": "lang", "in": "query", "schema": { "$ref": "#/components/schemas/Language" } } ], "responses": { "200": { "description": "Post translation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostTranslation" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "GroupNoPublicAccess": { "description": "The group must be public or the requesting user must be a member of the group", "value": { "errorCode": "GroupNoPublicAccess", "message": "The group must be public or the requesting user must be a member of the group" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PostNotFound", "message": "The specified post not found" } } }, "description": "The specified post not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/posts/{postId}/unmute": { "post": { "summary": "Unmute a conversation", "description": "Unmutes the conversation that the specified post belongs to. Notifications for activity in that thread will resume.", "tags": [ "Posts" ], "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "PostNotFound": { "description": "The specified post not found", "value": { "errorCode": "PostNotFound", "message": "The specified post not found" } }, "ConversationNotMuted": { "description": "The conversation is not muted", "value": { "errorCode": "ConversationNotMuted", "message": "The conversation is not muted" } } } } }, "description": "Not Found" } }, "security": [ { "header": [] } ] } }, "/api/v1/posts/{postId}/upvote": { "post": { "summary": "Upvote a post", "description": "Adds a positive vote to a post from the authenticated user. If the user previously downvoted, the vote is changed to an upvote. Users cannot vote on their own posts. Returns the updated vote summary.", "tags": [ "Posts" ], "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ], "responses": { "200": { "description": "A summary of votes for the post", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostVotesSummary" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "GroupNoPublicAccess": { "description": "The group must be public or the requesting user must be a member of the group", "value": { "errorCode": "GroupNoPublicAccess", "message": "The group must be public or the requesting user must be a member of the group" } }, "NoVotingOnOwnPost": { "description": "Voting on own post is not allowed", "value": { "errorCode": "NoVotingOnOwnPost", "message": "Voting on own post is not allowed" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PostNotFound", "message": "The specified post not found" } } }, "description": "The specified post not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/posts/{postId}/votes": { "get": { "summary": "Get post votes", "description": "Returns a summary of upvotes and downvotes for a post, including the authenticated user's own vote direction. Requires authentication.", "tags": [ "Posts" ], "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostVotesSummary" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PostNotFound", "message": "The specified post not found" } } }, "description": "The specified post not found" } }, "security": [] } }, "/api/v1/rbac": { "get": { "summary": "Retrieves all RBAC-guarded resources and their access lists", "description": "Returns the complete list of RBAC-protected resources along with their supported access types (Read, Add, Modify, Delete, etc.). Use this to understand what resources exist in the system and what permissions can be assigned to them. No authentication required.", "tags": [ "RBAC" ], "responses": { "200": { "description": "List of all RBAC-guarded resources and their access lists", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ResourceModel" } } } } } }, "security": [ { "header": [] } ] } }, "/api/v1/rbac/actors/{actorId}/permissions": { "get": { "summary": "Retrieves permissions for the specified actor within a scope", "description": "\n Retrieves all permissions assigned to an actor within a specified scope.\n If no scope is provided, assumes GlobalScope\n ", "tags": [ "RBAC" ], "parameters": [ { "description": "ID of the actor", "example": "us_01jvvsnzd8fzhbct9dfzmgn9nn", "required": true, "name": "actorId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Optional scope to filter permissions, if ommitted assumes GlobalScope", "example": "global or gr_05hxcvk1hjexere4pvtrj0hggt", "required": false, "name": "scope", "in": "query", "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "Actor's permissions within the specified scope", "content": { "application/json": { "example": { "AdminSettings": [ "Read", "Manage" ], "AppData": [ "Read", "Manage" ], "Data": [ "Read", "Manage" ], "Roles": [ "Read", "Manage" ], "Users": [ "Read", "Manage", "Moderate", "Impersonate" ] }, "schema": { "type": "object", "additionalProperties": { "type": "object" } } } } } }, "security": [ { "header": [] } ] } }, "/api/v1/rbac/actors/{actorId}/roles": { "get": { "summary": "Retrieves roles for the specified actor within the specified scope", "description": "\n Retrieves all roles assigned to the specified actor within the specified scope.\n If no scope is specified, assumes the GlobalScope\n\nRBAC:\n- requires ANY of GroupRoles.Read, Roles.Read", "tags": [ "RBAC" ], "parameters": [ { "description": "ID of the actor", "example": "us_01jvvsnzd8fzhbct9dfzmgn9nn", "required": true, "name": "actorId", "in": "path", "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Optional scope to filter roles, defaults to GlobalScope ('System') if omitted", "example": "global or gr_05hxcvk1hjexere4pvtrj0hggt", "required": false, "name": "scope", "in": "query", "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "Actor's roles within the specified scope", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RBACRole" } } } } } }, "security": [ { "header": [] } ] } }, "/api/v1/rbac/roles": { "get": { "summary": "Retrieves all roles in the specified scope", "description": "Returns all roles that exist within the specified scope. The scope can be 'global' for global roles or a group ID for group-scoped roles.\n\nRBAC:\n- requires ANY of Roles.Read, GroupRoles.Read", "tags": [ "RBAC" ], "parameters": [ { "description": "Scope: 'System' for global roles, or a group ID.", "example": "global or gr_05hxcvk1hjexere4pvtrj0hggt", "required": true, "name": "scope", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved scope roles", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RBACRole" } } } } } }, "security": [ { "header": [] } ] }, "post": { "summary": "Create a new role in the specified scope", "description": "Creates a new role with specified permissions within the specified scope. The scope can be 'global' for global roles or a group ID for group-scoped roles. The scope value in the request body is ignored — the scope query parameter is authoritative. Group-scoped roles cannot include restricted permissions (GroupRoles.Manage, Group.Delete).\n\nRBAC:\n- requires ANY of Roles.Manage, GroupRoles.Manage", "tags": [ "RBAC" ], "parameters": [ { "description": "Scope: 'System' for global roles, or a group ID.", "example": "global or gr_05hxcvk1hjexere4pvtrj0hggt", "required": true, "name": "scope", "in": "query", "schema": { "type": "string" } } ], "requestBody": { "description": "Role details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RBACRoleTemplate" } } }, "required": true }, "responses": { "200": { "description": "The created role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RBACRole" } } } }, "400": { "description": "Bad Request" } }, "security": [ { "header": [] } ] } }, "/api/v1/rbac/roles/{roleId}": { "put": { "summary": "Update the specified role", "description": "Updates the name, description, and/or permissions of an existing role identified by its role ID within the specified scope. The role's scope cannot be changed. Group-scoped roles cannot include restricted permissions (GroupRoles.Manage, Group.Delete).\n\nRBAC:\n- requires ANY of Roles.Manage, GroupRoles.Manage", "tags": [ "RBAC" ], "parameters": [ { "description": "ID of the role to update", "required": true, "name": "roleId", "in": "path", "schema": { "type": "string" } }, { "description": "Scope: 'System' for global roles, or a group ID.", "example": "global or gr_05hxcvk1hjexere4pvtrj0hggt", "required": true, "name": "scope", "in": "query", "schema": { "type": "string" } } ], "requestBody": { "description": "Updated role details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RBACRoleTemplate" } } }, "required": true }, "responses": { "200": { "description": "Successfully updated role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RBACRole" } } } }, "400": { "description": "Bad Request" } }, "security": [ { "header": [] } ] } }, "/api/v1/rbac/roles/{roleName}": { "delete": { "summary": "Delete the specified role", "description": "Permanently deletes a role by name within the specified scope. All actor-to-role assignments for this role will also be removed. This operation cannot be undone.\n\nRBAC:\n- requires ANY of Roles.Manage, GroupRoles.Manage", "tags": [ "RBAC" ], "parameters": [ { "description": "The role's name to delete", "example": "BOT", "required": true, "name": "roleName", "in": "path", "schema": { "type": "string" } }, { "description": "Scope: 'System' for global roles, or a group ID.", "example": "global or gr_05hxcvk1hjexere4pvtrj0hggt", "required": true, "name": "scope", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully deleted role", "content": { "application/json": { "schema": {} } } } }, "security": [ { "header": [] } ] } }, "/api/v1/rbac/{resource}": { "get": { "summary": "Retrieves the description and the access list for the specified resource", "description": "Returns the resource model including its name, description, and supported access types for a specific RBAC-guarded resource. Use the resource name as it appears in the full resource list (e.g., 'GroupMembers', 'Users', 'Roles'). Returns ResourceNotFound if the resource does not exist. No authentication required.", "tags": [ "RBAC" ], "parameters": [ { "description": "The resource of interest", "example": "GroupMembers", "required": true, "name": "resource", "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The description and the access list for the specified resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceModel" } } } }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ResourceNotFound", "message": "The requested resource not found" } } }, "description": "The requested resource not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/reports": { "post": { "summary": "Report a post, user, or group to moderators", "description": "Creates a new report targeting a user, a post, or a group. If a report already exists for the same target, the new report is merged as a comment on the existing report instead of creating a duplicate. When 'forward' is true and the target is remote, sends a Flag activity via ActivityPub to the target's home instance (not applicable for group reports). For group reports: non-secret groups can be reported by anyone, secret groups can only be reported by members. Requires authentication.", "tags": [ "Reports" ], "requestBody": { "description": "Report details including target (post, user, or group), comment, type, and whether to forward to the remote instance", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateReport" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Report" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ConstraintViolation", "message": "A request parameter constraint was violated" } } }, "description": "A request parameter constraint was violated" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "GroupNoPublicAccess", "message": "The group must be public or the requesting user must be a member of the group" } } }, "description": "The group must be public or the requesting user must be a member of the group" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "GroupNotFound", "message": "Group not found" } } }, "description": "Group not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/reports/{reportId}/edit-comment": { "post": { "summary": "Edit your existing comment on a report", "description": "Updates the authenticated user's existing report comment for the specified report.", "tags": [ "Reports" ], "parameters": [ { "name": "reportId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "requestBody": { "description": "Updated report comment details", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditReportComment" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Report" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ConstraintViolation", "message": "A request parameter constraint was violated" } } }, "description": "A request parameter constraint was violated" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/rules": { "put": { "summary": "Update existing rule", "description": "Modifies an existing platform rule with updated text, hint, or ordering. Requires authentication and the Rules.Manage RBAC permission. Returns 404 if the rule does not exist. The update is logged in the audit trail.\n\nRBAC: requires Rules.Manage", "tags": [ "Rules" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Rule" } } }, "required": true }, "responses": { "200": { "description": "Updated Rule object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Rule" } } } }, "400": { "description": "Bad Request" } }, "security": [ { "header": [] } ] }, "get": { "summary": "Get all rules", "description": "Retrieves the complete list of platform rules that users must follow. Publicly accessible without authentication. Rules are returned ordered by their display position.", "tags": [ "Rules" ], "responses": { "200": { "description": "List of all rules", "content": { "application/json": { "example": [ { "text": "Mark any media with explicit sexual or violent content as sensitive or incl...", "hint": "This applies to provocative content even if specific body parts aren't show...", "order": 1000 } ], "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Rule" } } } } } }, "security": [] }, "post": { "summary": "Create a rule", "description": "Creates a new platform rule with text content, optional hint explanation, and ordering priority. Requires authentication and the Rules.Manage RBAC permission. The creation is logged in the audit trail.\n\nRBAC: requires Rules.Manage", "tags": [ "Rules" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuleCreate" } } }, "required": true }, "responses": { "200": { "description": "Created Rule object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Rule" } } } }, "400": { "description": "Bad Request" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/rules/reorder": { "post": { "summary": "Reorder rules", "description": "Updates the display ordering of multiple rules at once by providing new ordering values. Requires authentication and the Rules.Manage RBAC permission. Each reorder operation is logged individually in the audit trail. Returns the complete updated list of rules after reordering.\n\nRBAC: requires Rules.Manage", "tags": [ "Rules" ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RuleOrderingRequest" } } } }, "required": true }, "responses": { "200": { "description": "List of updated rules", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Rule" } } } } }, "400": { "description": "Bad Request" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/rules/{id}": { "delete": { "summary": "Delete existing rule", "description": "Permanently removes a platform rule by its ID. Requires authentication and the Rules.Manage RBAC permission. The deletion is logged in the audit trail.\n\nRBAC: requires Rules.Manage", "tags": [ "Rules" ], "parameters": [ { "description": "The unique identifier of the rule to delete", "required": true, "name": "id", "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } } }, "security": [ { "header": [] } ] } }, "/api/v1/search": { "get": { "summary": "Search across public post, users, tags. No auth required", "description": "Performs a search query across different content types with support for URL resolution, username lookups, and various filtering options. Authenticated requests include relationship data (following/followed) in user results unless includeRelations=false. Group results include VISIBLE groups; UNLISTED/HIDDEN groups are included only for members.", "tags": [ "Search" ], "parameters": [ { "deprecated": true, "description": "Deprecated: use entityType instead. Actor type: Person or Service.", "required": false, "name": "actorType", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/ActorType" } ], "nullable": true } }, { "description": "Entity type: USER or BOT. If not provided, searches for both", "required": false, "name": "entityType", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/EntityType" } ], "nullable": true } }, { "description": "Search only in fasp providers", "required": false, "name": "fasp", "in": "query", "schema": { "type": "boolean" } }, { "description": "Search only in fasp providers, returning hydrated results", "required": false, "name": "faspHydrated", "in": "query", "schema": { "type": "boolean" } }, { "description": "Only include specific types of results. Like posts, users, tags", "required": false, "name": "filter", "in": "query", "schema": { "uniqueItems": true, "type": "array", "items": { "$ref": "#/components/schemas/SearchFilter" }, "nullable": true } }, { "description": "following/follower status. Default ACCEPTED", "required": false, "name": "followStatus", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/FollowingStatus" }, { "default": "ACCEPTED" } ] } }, { "description": "Only include accounts that follows the user", "required": false, "name": "followers", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Only include accounts that the user is following", "required": false, "name": "following", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Filter results by groupId", "required": false, "name": "groupId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "Filter group members by role. MEMBER returns regular members, ADMIN returns admins and moderators. Only applies when groupId is provided and filter=users", "required": false, "name": "groupMemberRole", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/GroupMemberRoleFilter" } ], "nullable": true } }, { "description": "Include relationship data (following/followed) for user results. Default true.", "required": false, "name": "includeRelations", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "Filter results by ownerId", "required": false, "name": "ownerId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "Search query", "required": false, "name": "q", "in": "query", "schema": { "type": "string", "nullable": true } }, { "description": "Attempt to resolve remote users (WebFinger lookup)", "required": false, "name": "resolve", "in": "query", "schema": { "default": true, "type": "boolean" } }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "Load post with comments. Default false", "required": false, "name": "withComments", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "If comment, load it with direct parent (in originalPost field)", "required": false, "name": "withParent", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "If comment, load it with root parent (top-level post of the thread)", "required": false, "name": "withRootParent", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ], "responses": { "200": { "description": "Search result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResult" } } } } }, "security": [] } }, "/api/v1/sessions/all": { "delete": { "summary": "Delete all sessions except current", "description": "Permanently deletes all session records for the account except the current one. Unlike revoke-all, this removes session records from the database entirely. All other session tokens are removed from Redis. Requires authentication.", "tags": [ "Sessions" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "SessionDeleteFail", "message": "Failed to delete session" } } }, "description": "Failed to delete session" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/sessions/list": { "get": { "summary": "List all sessions", "description": "Returns all sessions for the authenticated account, sorted by most recently used. Session state is synchronized with Redis to reflect real-time activity. Sessions not found in Redis are marked as EXPIRED. Requires authentication.", "tags": [ "Sessions" ], "responses": { "200": { "description": "Sessions", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SessionInfo" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/sessions/revoke/all": { "put": { "summary": "Revoke all sessions except current", "description": "Expires all sessions for the account except the current one. Useful for securing the account after a suspected compromise. All other session tokens are removed from Redis. Requires authentication.", "tags": [ "Sessions" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "SessionDeleteFail", "message": "Failed to delete session" } } }, "description": "Failed to delete session" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/sessions/revoke/{sessionKey}": { "put": { "summary": "Revoke a session", "description": "Expires a specific session by its session key, making it inactive but retaining the record. The session token is removed from Redis. Cannot revoke the current session - use logout instead. Requires authentication.", "tags": [ "Sessions" ], "parameters": [ { "description": "Session key of the session to revoke", "name": "sessionKey", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "SessionRevokeCurrent": { "description": "Can't revoke current session", "value": { "errorCode": "SessionRevokeCurrent", "message": "Can't revoke current session" } }, "SessionRevokeFail": { "description": "Failed to revoke session", "value": { "errorCode": "SessionRevokeFail", "message": "Failed to revoke session" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/sessions/{sessionKey}": { "delete": { "summary": "Delete a session", "description": "Permanently deletes a specific session record by its session key. Unlike revoke, this removes the session from the database entirely. The session token is also removed from Redis. Cannot delete the current session. Requires authentication.", "tags": [ "Sessions" ], "parameters": [ { "description": "Session key of the session to delete", "name": "sessionKey", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "SessionDeleteFail", "message": "Failed to delete session" } } }, "description": "Failed to delete session" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/settings": { "put": { "summary": "Update platform settings", "description": "Update multiple platform-wide settings in a single operation. Each setting must be provided as a complete object with all required fields. Partial updates are not supported to ensure system stability and prevent configuration errors. Requires authentication. Write access is checked per setting: ADMIN settings require the AdminSettings.Manage RBAC permission.", "tags": [ "Platform Settings" ], "requestBody": { "description": "settings objects to be updated. complete objects must be provided - partial updates are not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformSettings" } } }, "required": true }, "responses": { "200": { "description": "number of updated settings", "content": { "application/json": { "example": { "updated": 3 } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "SettingsInvalidKeyProvided": { "description": "Unknown settings key(s) %s", "value": { "errorCode": "SettingsInvalidKeyProvided", "message": "Unknown settings key(s) %s" } }, "SettingsKeyNotProvided": { "description": "No settings keys were provided", "value": { "errorCode": "SettingsKeyNotProvided", "message": "No settings keys were provided" } }, "SettingsValuesNotProvided": { "description": "No settings values were provided", "value": { "errorCode": "SettingsValuesNotProvided", "message": "No settings values were provided" } }, "SettingsPartialUpdateNotAllowed": { "description": "Partial updates are not allowed: %s", "value": { "errorCode": "SettingsPartialUpdateNotAllowed", "message": "Partial updates are not allowed: %s" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "SettingsForbidden", "message": "Access denied for settings" } } }, "description": "Access denied for settings" }, "500": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "SettingsNotUpdated", "message": "Failed to update settings" } } }, "description": "Failed to update settings" } }, "security": [] }, "get": { "summary": "Get platform settings", "description": "Retrieve specific platform-wide settings by their keys. Returns a JSON object mapping setting names to their configured values. Access depends on each setting's read permission: GUEST settings are publicly accessible without authentication, USER settings require an authenticated user, and ADMIN settings require the AdminSettings.Read RBAC permission.", "tags": [ "Platform Settings" ], "parameters": [ { "description": "Comma-separated list of platform setting keys to retrieve. Each key must correspond to a valid platform setting definition registered in the system.\n\nAvailable keys are:\n\n```wellesley.access```\n\n```wellesley.admin.ai.agents.budgets```\n\n```wellesley.uploads.policy.audio```\n\n```wellesley.branding```\n\n```wellesley.admin.captcha```\n\n```wellesley.captcha```\n\n```wellesley.confirmationCode```\n\n```wellesley.uploads.policy.doc```\n\n```wellesley.instance.domainBlocks```\n\n```wellesley.admin.embedding_model```\n\n```wellesley.uploads.policy.emoji```\n\n```wellesley.admin.fasp_remote```\n\n```wellesley.admin.federation.mode```\n\n```wellesley.uploads.policy.image```\n\n```wellesley.instance.admin```\n\n```wellesley.instance.contacts```\n\n```wellesley.instance.legal```\n\n```wellesley.admin.language```\n\n```wellesley.admin.mediacache```\n\n```wellesley.posts```\n\n```wellesley.registration```\n\n```wellesley.admin.link_service```\n\n```wellesley.admin.sms```\n\n```wellesley.admin.sms.aws```\n\n```wellesley.admin.sms.sinch```\n\n```wellesley.admin.sms.twilio```\n\n```wellesley.translation```\n\n```wellesley.admin.translation```\n\n```wellesley.admin.uploads```\n\n```wellesley.username.release```\n\n```wellesley.uploads.policy.video```", "name": "keys", "required": true, "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "example": "wellesley.access,wellesley.admin.ai.agents.budgets" } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/PlatformSettings" } ] } } }, "description": "Response PlatformSettings" }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "SettingsInvalidKeyProvided": { "description": "Unknown settings key(s) %s", "value": { "errorCode": "SettingsInvalidKeyProvided", "message": "Unknown settings key(s) %s" } }, "SettingsKeyNotProvided": { "description": "No settings keys were provided", "value": { "errorCode": "SettingsKeyNotProvided", "message": "No settings keys were provided" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "SettingsForbidden", "message": "Access denied for settings" } } }, "description": "Access denied for settings" } }, "security": [] }, "delete": { "summary": "Delete platform settings", "description": "Remove specific platform settings by their keys. This operation will permanently delete the specified settings and revert them to their system default values. Use extreme caution as this affects the entire platform. Requires authentication. Write access is checked per setting: ADMIN settings require the AdminSettings.Manage RBAC permission.", "tags": [ "Platform Settings" ], "parameters": [ { "description": "Comma-separated list of platform setting keys to delete. Each key must correspond to a valid platform setting that exists and can be safely removed.\n\nAvailable keys are:\n\n```wellesley.access```\n\n```wellesley.admin.ai.agents.budgets```\n\n```wellesley.uploads.policy.audio```\n\n```wellesley.branding```\n\n```wellesley.admin.captcha```\n\n```wellesley.captcha```\n\n```wellesley.confirmationCode```\n\n```wellesley.uploads.policy.doc```\n\n```wellesley.instance.domainBlocks```\n\n```wellesley.admin.embedding_model```\n\n```wellesley.uploads.policy.emoji```\n\n```wellesley.admin.fasp_remote```\n\n```wellesley.admin.federation.mode```\n\n```wellesley.uploads.policy.image```\n\n```wellesley.instance.admin```\n\n```wellesley.instance.contacts```\n\n```wellesley.instance.legal```\n\n```wellesley.admin.language```\n\n```wellesley.admin.mediacache```\n\n```wellesley.posts```\n\n```wellesley.registration```\n\n```wellesley.admin.link_service```\n\n```wellesley.admin.sms```\n\n```wellesley.admin.sms.aws```\n\n```wellesley.admin.sms.sinch```\n\n```wellesley.admin.sms.twilio```\n\n```wellesley.translation```\n\n```wellesley.admin.translation```\n\n```wellesley.admin.uploads```\n\n```wellesley.username.release```\n\n```wellesley.uploads.policy.video```", "name": "keys", "required": true, "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "example": "wellesley.access,wellesley.admin.ai.agents.budgets" } ], "responses": { "200": { "description": "number of deleted settings", "content": { "application/json": { "example": { "deleted": 3 } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "SettingsKeyNotProvided": { "description": "No settings keys were provided", "value": { "errorCode": "SettingsKeyNotProvided", "message": "No settings keys were provided" } }, "SettingsInvalidKeyProvided": { "description": "Unknown settings key(s) %s", "value": { "errorCode": "SettingsInvalidKeyProvided", "message": "Unknown settings key(s) %s" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "SettingsForbidden", "message": "Access denied for settings" } } }, "description": "Access denied for settings" } }, "security": [] } }, "/api/v1/settings/names": { "get": { "summary": "List setting keys", "description": "Return a list of fully-qualified setting key names for the requested settings type.", "tags": [ "Platform Settings" ], "parameters": [ { "description": "Namespace to list keys for. One of: Platform, User, Group, GroupMember.", "name": "type", "required": true, "in": "query", "schema": { "$ref": "#/components/schemas/Namespace" } } ], "responses": { "200": { "description": "Array of setting key names", "content": { "application/json": { "schema": {} } } } }, "security": [] } }, "/api/v1/settings/user": { "put": { "summary": "Update user settings", "description": "Update multiple user settings in a single operation for the authenticated user. Each setting must be provided as a complete object with all required fields. Partial updates are not supported to ensure data consistency and prevent preference corruption. Side effect: if notification preferences are updated with syncAcrossProfiles enabled, the preferences are propagated to all other profiles on the same account.", "tags": [ "User Settings" ], "requestBody": { "description": "settings objects to be updated. complete objects must be provided - partial updates are not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserSettings" } } }, "required": true }, "responses": { "200": { "description": "number of updated settings", "content": { "application/json": { "example": { "updated": 3 } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "SettingsInvalidKeyProvided": { "description": "Unknown settings key(s) %s", "value": { "errorCode": "SettingsInvalidKeyProvided", "message": "Unknown settings key(s) %s" } }, "SettingsKeyNotProvided": { "description": "No settings keys were provided", "value": { "errorCode": "SettingsKeyNotProvided", "message": "No settings keys were provided" } }, "SettingsValuesNotProvided": { "description": "No settings values were provided", "value": { "errorCode": "SettingsValuesNotProvided", "message": "No settings values were provided" } }, "SettingsPartialUpdateNotAllowed": { "description": "Partial updates are not allowed: %s", "value": { "errorCode": "SettingsPartialUpdateNotAllowed", "message": "Partial updates are not allowed: %s" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "SettingsForbidden", "message": "Access denied for settings" } } }, "description": "Access denied for settings" }, "500": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "SettingsNotUpdated", "message": "Failed to update settings" } } }, "description": "Failed to update settings" } }, "security": [ { "header": [] } ] }, "get": { "summary": "Get user settings", "description": "Retrieve specific user settings by their keys for the authenticated user. Returns a JSON object mapping setting names to their configured values. Only settings belonging to the current user are accessible through this endpoint.", "tags": [ "User Settings" ], "parameters": [ { "description": "Comma-separated list of user setting keys to retrieve. Each key must correspond to a valid user setting definition registered in the system.\n\nAvailable keys are:\n\n```user.discoverFeed```\n\n```user.follow```\n\n```user.notifications.policy```\n\n```user.notifications.prefs```\n\n```user.privacy```\n\n```user.quotePolicy```\n\n```user.translation```", "name": "keys", "required": true, "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "example": "user.discoverFeed,user.follow" } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/UserSettings" } ] } } }, "description": "Response UserSettings" }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "SettingsInvalidKeyProvided": { "description": "Unknown settings key(s) %s", "value": { "errorCode": "SettingsInvalidKeyProvided", "message": "Unknown settings key(s) %s" } }, "SettingsKeyNotProvided": { "description": "No settings keys were provided", "value": { "errorCode": "SettingsKeyNotProvided", "message": "No settings keys were provided" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "SettingsForbidden", "message": "Access denied for settings" } } }, "description": "Access denied for settings" } }, "security": [ { "header": [] } ] }, "delete": { "summary": "Delete user settings", "description": "Remove specific user settings by their keys for the authenticated user. This operation will permanently delete the specified settings and revert them to their default values. Deleted preferences cannot be recovered.", "tags": [ "User Settings" ], "parameters": [ { "description": "Comma-separated list of user setting keys to delete. Each key must correspond to a valid user setting that exists for the authenticated user.\n\nAvailable keys are:\n\n```user.discoverFeed```\n\n```user.follow```\n\n```user.notifications.policy```\n\n```user.notifications.prefs```\n\n```user.privacy```\n\n```user.quotePolicy```\n\n```user.translation```", "name": "keys", "required": true, "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "example": "user.discoverFeed,user.follow" } ], "responses": { "200": { "description": "number of deleted settings", "content": { "application/json": { "example": { "deleted": 3 } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "SettingsKeyNotProvided": { "description": "No settings keys were provided", "value": { "errorCode": "SettingsKeyNotProvided", "message": "No settings keys were provided" } }, "SettingsInvalidKeyProvided": { "description": "Unknown settings key(s) %s", "value": { "errorCode": "SettingsInvalidKeyProvided", "message": "Unknown settings key(s) %s" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "SettingsForbidden", "message": "Access denied for settings" } } }, "description": "Access denied for settings" } }, "security": [ { "header": [] } ] } }, "/api/v1/suggestions": { "get": { "summary": "Get follow suggestions", "description": "Returns recommended users for the authenticated account. Results are fetched from FASP providers, resolved to users, and filtered to remove already-followed users, pending follow requests, and blocked relationships.", "tags": [ "Suggestions" ], "parameters": [ { "description": "Preferred language hint for recommendation providers (for example: en, fr).", "required": false, "name": "language", "in": "query", "schema": { "type": "string", "nullable": true } }, { "description": "Maximum number of suggestions to return after filtering. Values below 0 are clamped to 0.", "required": false, "name": "limit", "in": "query", "schema": { "format": "int32", "default": 40, "type": "integer" } } ], "responses": { "200": { "description": "Suggested users", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/User" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/tags/featured": { "get": { "summary": "Get list of featured tags", "description": "Returns the featured (pinned) tags for the authenticated user or a specified user. For remote users, featured tags may be refreshed from their origin server if stale. Tags blocked by scope policy are filtered out. Requires authentication.", "tags": [ "Tags" ], "parameters": [ { "description": "Scope id: 'global' or TypeId", "required": true, "name": "scope", "in": "query", "schema": { "type": "string" } }, { "description": "List specific user's featured tags", "required": false, "name": "userId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/tags/featured/{name}": { "delete": { "summary": "Remove from featured tags by name", "description": "Removes a tag from the authenticated user's featured (pinned) tags and notifies followers via ActivityPub. Requires authentication.", "tags": [ "Tags" ], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "description": "Scope id: 'global' or TypeId", "required": true, "name": "scope", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "TagNotFound", "message": "The specified tag not found" } } }, "description": "The specified tag not found" } }, "security": [ { "header": [] } ] }, "post": { "summary": "Feature tag by name", "description": "Adds a tag to the authenticated user's featured (pinned) tags and notifies followers via ActivityPub. Tags blocked by scope policy cannot be featured. Requires authentication.", "tags": [ "Tags" ], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "description": "Scope id: 'global' or TypeId", "required": true, "name": "scope", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "TagFeaturingError", "message": "Failed to feature the specified tag" } } }, "description": "Failed to feature the specified tag" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/tags/follow/{name}": { "post": { "summary": "Follow tag by name", "description": "Subscribes the authenticated user to a tag within the specified scope, so posts with this tag appear in their feed. Tags blocked by scope policy cannot be followed. Requires authentication.", "tags": [ "Tags" ], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "description": "Scope id: 'global' or TypeId", "required": true, "name": "scope", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "TagFollowingError", "message": "Failed to follow the specified tag" } } }, "description": "Failed to follow the specified tag" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "TagNotFound", "message": "The specified tag not found" } } }, "description": "The specified tag not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/tags/followed": { "get": { "summary": "Get list of followed tags", "description": "Returns all tags the authenticated user is following within the specified scope. Tags blocked by scope policy are filtered out. Requires authentication.", "tags": [ "Tags" ], "parameters": [ { "description": "Scope id: 'global' or TypeId", "required": true, "name": "scope", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } } } } } }, "security": [ { "header": [] } ] } }, "/api/v1/tags/list": { "put": { "summary": "Overwrite black/whitelist", "description": "Bulk overwrite list entries for a scope\n\nRBAC:\n- requires ANY of Data.Manage, GroupData.Manage", "tags": [ "Tags" ], "parameters": [ { "description": "Scope id", "required": true, "name": "scope", "in": "query", "schema": { "type": "string" } }, { "description": "Soft flag (blacklist only)", "required": false, "name": "soft", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "List type", "required": true, "name": "type", "in": "query", "schema": { "$ref": "#/components/schemas/TagPolicyMode" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request" } }, "security": [ { "header": [] } ] }, "patch": { "summary": "Add to black/whitelist", "description": "Add entries. For blacklist, soft flag toggles hard/soft.\n\nRBAC:\n- requires ANY of Data.Manage, GroupData.Manage", "tags": [ "Tags" ], "parameters": [ { "description": "Scope id", "required": true, "name": "scope", "in": "query", "schema": { "type": "string" } }, { "description": "Soft flag (blacklist only)", "required": false, "name": "soft", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "List type", "required": true, "name": "type", "in": "query", "schema": { "$ref": "#/components/schemas/TagPolicyMode" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } } }, "security": [ { "header": [] } ] }, "get": { "summary": "Get black/whitelist for a scope", "description": "Returns array of tag names in black/whitelist. 'soft' applies only to blacklist.\n\nRBAC:\n- requires ANY of Data.Read, GroupData.Manage", "tags": [ "Tags" ], "parameters": [ { "description": "Scope id", "required": true, "name": "scope", "in": "query", "schema": { "type": "string" } }, { "description": "Soft flag (blacklist only)", "required": false, "name": "soft", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "List type", "required": true, "name": "type", "in": "query", "schema": { "$ref": "#/components/schemas/TagPolicyMode" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } } }, "security": [ { "header": [] } ] }, "delete": { "summary": "Remove from black/whitelist", "description": "Remove entries. For blacklist, soft must be specified to remove from that list.\n\nRBAC:\n- requires ANY of Data.Manage, GroupData.Manage", "tags": [ "Tags" ], "parameters": [ { "description": "Scope id", "required": true, "name": "scope", "in": "query", "schema": { "type": "string" } }, { "description": "Soft flag (blacklist only)", "required": false, "name": "soft", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "List type", "required": true, "name": "type", "in": "query", "schema": { "$ref": "#/components/schemas/TagPolicyMode" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } } }, "security": [ { "header": [] } ] } }, "/api/v1/tags/policy": { "put": { "summary": "Set policy mode", "description": "Set scope policy to 'whitelist' or 'blacklist'.\n\nRBAC:\n- requires ANY of Data.Manage, GroupData.Manage", "tags": [ "Tags" ], "parameters": [ { "description": "Scope id", "required": true, "name": "scope", "in": "query", "schema": { "type": "string" } } ], "requestBody": { "description": "Policy mode request", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetTagPolicyRequest" } } } }, "responses": { "200": { "description": "Policy mode set successfully", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] }, "get": { "summary": "Get policy mode", "description": "Returns 'whitelist' or 'blacklist' for scope. Defaults to 'blacklist' if unset.\n\nRBAC:\n- requires ANY of Data.Read, GroupData.Manage", "tags": [ "Tags" ], "parameters": [ { "name": "scope", "in": "query", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagPolicyMode" } } } } }, "security": [ { "header": [] } ] } }, "/api/v1/tags/report": { "post": { "summary": "Report a tag", "description": "Creates a tag report in a scope. The tag name is normalized before storing. Requires authentication.", "tags": [ "Tags" ], "parameters": [ { "description": "Canonical tag name", "required": true, "name": "name", "in": "query", "schema": { "type": "string" } }, { "description": "Scope id", "required": true, "name": "scope", "in": "query", "schema": { "type": "string" } } ], "requestBody": { "description": "Tag report request", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTagReportRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ClientError", "message": "Invalid request from client" } } }, "description": "Invalid request from client" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/tags/reports": { "get": { "summary": "List tag reports in a scope", "description": "Returns all tag reports for the given scope. Requires Data.Read or GroupData.Manage permission.\n\nRBAC:\n- requires ANY of Data.Read, GroupData.Manage", "tags": [ "Tags" ], "parameters": [ { "name": "scope", "in": "query", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": {} } } }, "security": [ { "header": [] } ] } }, "/api/v1/tags/search": { "get": { "summary": "Search tags by prefix", "description": "Returns tag names matching partial name. Scope is optional.", "tags": [ "Tags" ], "parameters": [ { "description": "Max results", "required": false, "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true } }, { "description": "Partial tag name", "required": false, "name": "name", "in": "query", "schema": { "type": "string", "nullable": true } }, { "description": "Offset", "required": false, "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true } }, { "description": "Scope id: 'global' or TypeId", "required": false, "name": "scope", "in": "query", "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } } }, "security": [] } }, "/api/v1/tags/trending": { "get": { "summary": "Get trending tags for a scope", "description": "Returns trending tags within the specified scope with optional sorting and pagination. Tags blocked by scope policy are filtered out. No authentication required.", "tags": [ "Tags" ], "parameters": [ { "description": "Max results", "required": false, "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true } }, { "description": "Offset for pagination", "required": false, "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true } }, { "description": "Scope id: 'global' or TypeId", "required": true, "name": "scope", "in": "query", "schema": { "type": "string" } }, { "description": "Sort by field: 'uses' (default) or 'date' (tag created_at)", "required": false, "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true } }, { "description": "Sort order: ASC or DESC", "required": false, "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } } } } } }, "security": [] } }, "/api/v1/tags/unfollow/{name}": { "post": { "summary": "Unfollow tag by name", "description": "Unsubscribes the authenticated user from a tag within the specified scope. Requires authentication.", "tags": [ "Tags" ], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "description": "Scope id: 'global' or TypeId", "required": true, "name": "scope", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "TagUnFollowingError", "message": "Failed to unfollow the specified tag" } } }, "description": "Failed to unfollow the specified tag" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "TagNotFound", "message": "The specified tag not found" } } }, "description": "The specified tag not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/tags/{name}": { "get": { "summary": "Get tag by name", "description": "Retrieves tag details including usage history. Tags blocked by scope policy (blacklist/whitelist) are not returned. No authentication required.", "tags": [ "Tags" ], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "description": "Filter history since. 2 weeks by default", "required": false, "name": "historySince", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/LocalDate" } ], "nullable": true } }, { "description": "Scope id: 'global' or TypeId", "required": true, "name": "scope", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tag" } } } }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "TagNotFound", "message": "The specified tag not found" } } }, "description": "The specified tag not found" } }, "security": [] } }, "/api/v1/translate/text": { "post": { "summary": "Translate text to a target language", "description": "Translates the provided text into the specified target language. Supports both plain text and HTML content (set isHtml=true for HTML). Requires authentication.", "tags": [ "Translation" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationResponse" } } } }, "400": { "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/trends/events": { "get": { "summary": "Get trending events", "description": "Returns a list of currently trending events. Event trends are sourced from FASP providers and resolved to full event objects from the local database. No authentication required.", "tags": [ "Trends" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } } } } } }, "security": [] } }, "/api/v1/trends/links": { "get": { "summary": "Get trending links", "description": "Returns a list of currently trending links with their preview card metadata (title, description, image). Link trends are sourced from FASP providers. No authentication required.", "tags": [ "Trends" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Card" } } } } } }, "security": [] } }, "/api/v1/trends/posts": { "get": { "summary": "Get trending posts", "description": "Returns a list of currently trending posts. Post trends are sourced from FASP providers and resolved to full post objects from the local database. No authentication required.", "tags": [ "Trends" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } } } } } }, "security": [], "parameters": [ { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ] } }, "/api/v1/trends/tags": { "get": { "summary": "Get trending tags", "description": "Returns a list of currently trending hashtags. Results can be scoped to a specific context (e.g., a group) using the scope parameter. Tags that violate tag policy (blacklist/whitelist) for the scope are filtered out. No authentication required.", "tags": [ "Trends" ], "parameters": [ { "description": "Scope id: 'global' or TypeId", "required": false, "name": "scope", "in": "query", "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } } } } } }, "security": [] } }, "/api/v1/uploads": { "post": { "summary": "Create a new upload entry", "description": "Creates a new upload record and returns an upload URL where the file content should be PUT. This is the first step of the two-step upload flow. Requires authentication.", "tags": [ "Uploads" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUpload" } } }, "required": true }, "responses": { "200": { "description": "Upload successfully created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUploadResult" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "IncorrectFileType": { "description": "Incorrect file type for this operation", "value": { "errorCode": "IncorrectFileType", "message": "Incorrect file type for this operation" } }, "InvalidFileExtension": { "description": "Invalid file extension", "value": { "errorCode": "InvalidFileExtension", "message": "Invalid file extension" } }, "InvalidPrivacyForAllowedUsers": { "description": "Allowed users are supported only for DIRECT privacy", "value": { "errorCode": "InvalidPrivacyForAllowedUsers", "message": "Allowed users are supported only for DIRECT privacy" } }, "UploadCreationError": { "description": "Cannot create upload", "value": { "errorCode": "UploadCreationError", "message": "Cannot create upload" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [] } }, "/api/v1/uploads/attached/{entityId}": { "get": { "summary": "List uploads attached to an entity", "description": "Returns all uploads attached to the specified entity (post, event, etc.). Requires authentication.", "tags": [ "Uploads" ], "parameters": [ { "name": "entityId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } ], "responses": { "200": { "description": "Operation is successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListUploadsResult" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "UploadOwnerAccessDenied": { "description": "No permission to create uploads for this owner", "value": { "errorCode": "UploadOwnerAccessDenied", "message": "No permission to create uploads for this owner" } } } } }, "description": "Forbidden" } }, "security": [ { "header": [] } ] } }, "/api/v1/uploads/batch": { "post": { "summary": "Batch delete multiple uploads", "description": "Deletes multiple uploads at once. All uploads must belong to the authenticated user and the batch size must be between 1 and 20. Requires authentication.", "tags": [ "Uploads" ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypeId" } } } }, "required": true }, "responses": { "200": { "description": "Delete multiple upload is successful", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypeId" } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ClientError", "message": "Invalid request from client" } } }, "description": "Invalid request from client" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UploadNotFound", "message": "Upload not found" } } }, "description": "Upload not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/uploads/list": { "post": { "summary": "List uploads by tags", "description": "Returns uploads matching the specified tag criteria from the request body. Only the authenticated user's uploads are returned. Requires authentication.", "tags": [ "Uploads" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadList" } } }, "required": true }, "responses": { "200": { "description": "Operation is successful", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Upload" } } } } }, "400": { "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/uploads/owner/{ownerId}": { "get": { "summary": "List all uploads by owner", "description": "Returns all uploads (standalone and attached) owned by the specified entity. Requires authentication.", "tags": [ "Uploads" ], "parameters": [ { "name": "ownerId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } ], "responses": { "200": { "description": "Operation is successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListUploadsResult" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "UploadOwnerAccessDenied": { "description": "No permission to create uploads for this owner", "value": { "errorCode": "UploadOwnerAccessDenied", "message": "No permission to create uploads for this owner" } } } } }, "description": "Forbidden" } }, "security": [ { "header": [] } ] } }, "/api/v1/uploads/owner/{ownerId}/standalone": { "get": { "summary": "List standalone uploads by owner", "description": "Returns uploads owned by the specified entity that are not attached to any entity. Requires authentication.", "tags": [ "Uploads" ], "parameters": [ { "name": "ownerId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } ], "responses": { "200": { "description": "Operation is successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListUploadsResult" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "UploadOwnerAccessDenied": { "description": "No permission to create uploads for this owner", "value": { "errorCode": "UploadOwnerAccessDenied", "message": "No permission to create uploads for this owner" } } } } }, "description": "Forbidden" } }, "security": [ { "header": [] } ] } }, "/api/v1/uploads/search": { "get": { "summary": "Search uploads", "description": "Searches the authenticated user's uploads with optional filtering by upload type (image, video, etc.) and tag (Post, Avatar, Header, etc.). Returns paginated results. Requires authentication.", "tags": [ "Uploads" ], "parameters": [ { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Search uploads by a tag", "required": false, "name": "tag", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/UploadsTags" } ], "nullable": true } }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "description": "Search uploads by upload type", "required": false, "name": "uploadType", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/UploadType" } ], "nullable": true } } ], "responses": { "200": { "description": "Operation is successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListUploadsResult" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "InvalidUploadListRequest", "message": "Invalid request to list uploads. Provide a valid userId, pagination, and a supported order field (createdAt or size)." } } }, "description": "Invalid request to list uploads. Provide a valid userId, pagination, and a supported order field (createdAt or size)." }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [ { "header": [] } ] } }, "/api/v1/uploads/usages": { "get": { "summary": "Find usages of uploads", "description": "Returns where the specified uploads are used, including posts, avatars, and headers. Accepts a comma-separated list of upload IDs. Requires authentication.", "tags": [ "Uploads" ], "parameters": [ { "description": "Comma-separated list of upload IDs to find usages for", "required": false, "name": "ids", "in": "query", "schema": { "type": "array", "items": { "type": "string" }, "nullable": true } } ], "responses": { "200": { "description": "Json with usages for specified upload ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadUsages" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ValidationError", "message": "Invalid parameters" } } }, "description": "Invalid parameters" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" } }, "security": [] } }, "/api/v1/uploads/{id}": { "get": { "summary": "Get upload by ID", "description": "Retrieves upload metadata and file information for a specific upload. Only the upload owner can access their uploads. Requires authentication.", "tags": [ "Uploads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "Gets upload data with file info", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Upload" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "PrivacyError", "message": "Current user is not allowed to see this upload" } } }, "description": "Current user is not allowed to see this upload" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UploadNotFound", "message": "Upload not found" } } }, "description": "Upload not found" } }, "security": [ { "header": [] } ] }, "delete": { "summary": "Delete upload by ID", "description": "Permanently deletes an upload and its associated files. Only the upload owner can delete their uploads. Requires authentication.", "tags": [ "Uploads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "Delete upload is successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteUploadResponse" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UploadNotFound", "message": "Upload not found" } } }, "description": "Upload not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/uploads/{id}/meta": { "post": { "summary": "Replace upload metadata", "description": "Completely replaces the upload's metadata with the provided data, removing any existing metadata not included in the request. Only the upload owner can modify metadata. Requires authentication.", "tags": [ "Uploads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } }, "required": true }, "responses": { "200": { "description": "Operation is successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Upload" } } } }, "400": { "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UploadNotFound", "message": "Upload not found" } } }, "description": "Upload not found" } }, "security": [ { "header": [] } ] }, "put": { "summary": "Partially update upload metadata", "description": "Merges the provided metadata fields into the upload's existing metadata, preserving fields not included in the request. Only the upload owner can modify metadata. Requires authentication.", "tags": [ "Uploads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } }, "required": true }, "responses": { "200": { "description": "Operation is successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Upload" } } } }, "400": { "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UploadNotFound", "message": "Upload not found" } } }, "description": "Upload not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/uploads/{id}/privacy": { "post": { "summary": "Update upload privacy settings", "description": "Sets the privacy level and allowed users for an upload. This replaces the existing privacy settings entirely. Only the upload owner can modify privacy. Requires authentication.", "tags": [ "Uploads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUploadPrivacy" } } }, "required": true }, "responses": { "200": { "description": "Operation is successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Upload" } } } }, "400": { "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UploadNotFound", "message": "Upload not found" } } }, "description": "Upload not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/uploads/{id}/tags": { "post": { "summary": "Replace upload tags", "description": "Completely replaces the upload's tags with the provided set, removing any existing tags not in the request. Tags categorize uploads (e.g., Post, Avatar, Header, Emoji). Only the upload owner can modify tags. Requires authentication.", "tags": [ "Uploads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UploadsTags" } } } }, "required": true }, "responses": { "200": { "description": "Operation is successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Upload" } } } }, "400": { "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UploadNotFound", "message": "Upload not found" } } }, "description": "Upload not found" } }, "security": [ { "header": [] } ] }, "put": { "summary": "Add tags to upload", "description": "Adds the provided tags to the upload's existing tag set without removing any existing tags. Only the upload owner can modify tags. Requires authentication.", "tags": [ "Uploads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UploadsTags" } } } }, "required": true }, "responses": { "200": { "description": "Operation is successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Upload" } } } }, "400": { "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UploadNotFound", "message": "Upload not found" } } }, "description": "Upload not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/uploads/{id}/thumbnail": { "post": { "summary": "Change video thumbnail", "description": "Updates the thumbnail/preview image for a video upload by extracting a frame at the specified timestamp (in seconds). Only applicable to video uploads. Only the upload owner can change thumbnails. Requires authentication.", "tags": [ "Uploads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeVideoThumbnail" } } }, "required": true }, "responses": { "200": { "description": "Operation is successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Upload" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "IncorrectUploadType", "message": "Incorrect upload type for this operation" } } }, "description": "Incorrect upload type for this operation" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UploadNotFound", "message": "Upload not found" } } }, "description": "Upload not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/uploads/{uploadId}/owner": { "put": { "summary": "Update standalone upload owner", "description": "Change the owner of a standalone upload. Only works for uploads not yet attached to any entity. Requires authentication.", "tags": [ "Uploads" ], "parameters": [ { "name": "uploadId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUploadOwner" } } }, "required": true }, "responses": { "200": { "description": "Owner updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Upload" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UploadCannotChangeOwner", "message": "Cannot change owner of an attached upload" } } }, "description": "Cannot change owner of an attached upload" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "UploadOwnerAccessDenied": { "description": "No permission to create uploads for this owner", "value": { "errorCode": "UploadOwnerAccessDenied", "message": "No permission to create uploads for this owner" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UploadNotFound", "message": "Upload not found" } } }, "description": "Upload not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/user-alias": { "get": { "summary": "List of aliases", "description": "Returns all aliases registered for the authenticated user as a list of ActivityPub URIs. Requires authentication.", "tags": [ "Aliases" ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "type": "array", "items": { "type": "string" } } } } } }, "security": [ { "header": [] } ] }, "delete": { "summary": "Remove alias", "description": "Removes an existing alias from the authenticated user by its ActivityPub URI. Requires authentication.", "tags": [ "Aliases" ], "parameters": [ { "description": "ActivityPub URI of the alias to remove", "name": "uri", "in": "query", "schema": { "pattern": "\\S", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "UserNotFound": { "description": "User not found", "value": { "errorCode": "UserNotFound", "message": "User not found" } }, "AliasNotFound": { "description": "Alias not found", "value": { "errorCode": "AliasNotFound", "message": "Alias not found" } } } } }, "description": "Not Found" } }, "security": [ { "header": [] } ] }, "post": { "summary": "Create alias", "description": "Adds a remote account alias for the authenticated user. The acct parameter must include a domain (e.g., 'user@remote.social'). The remote actor is fetched and verified via ActivityPub before the alias is saved. Used to declare a previous identity for account migration. Requires authentication.", "tags": [ "Aliases" ], "parameters": [ { "description": "Remote account address in user@domain format", "name": "acct", "in": "query", "schema": { "pattern": "\\S", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } } }, "description": "Admin privileges are required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserNotFound", "message": "User not found" } } }, "description": "User not found" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AliasAlreadyExists", "message": "Alias already exists" } } }, "description": "Alias already exists" } }, "security": [ { "header": [] } ] } }, "/api/v1/user-domain-block": { "get": { "summary": "List of blocked domains for the user", "description": "Returns the list of all domains currently blocked by the authenticated user. Each entry is a domain string (e.g. 'example.com').", "tags": [ "Domain-blocks" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/user-domain-block/{domain}": { "delete": { "summary": "Unblock previously blocked domain", "description": "Removes a domain block for the authenticated user, restoring content visibility from that domain. Returns an error if the domain is not currently blocked.", "tags": [ "Domain-blocks" ], "parameters": [ { "description": "The domain to unblock", "required": true, "name": "domain", "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "DomainIsNotBlocked", "message": "The domain is not currently blocked" } } }, "description": "The domain is not currently blocked" } }, "security": [ { "header": [] } ] }, "post": { "summary": "Block specific domain", "description": "\n Block a domain to:\n * hide all public posts from it\n * hide all notifications from it\n * remove all followers from it\n * prevent following new users from it (but does not remove existing follows)\n ", "tags": [ "Domain-blocks" ], "parameters": [ { "description": "The domain to block (e.g. 'example.com')", "required": true, "name": "domain", "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "DomainRequired", "message": "A domain must be provided" } } }, "description": "A domain must be provided" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "DomainAlreadyBlocked", "message": "The domain is already blocked" } } }, "description": "The domain is already blocked" } }, "security": [ { "header": [] } ] } }, "/api/v1/users": { "delete": { "summary": "Delete user", "description": "Deletes a user profile by ID. Requires authentication. Only users belonging to the authenticated account can be deleted. The deletion is audited.", "tags": [ "Users" ], "parameters": [ { "description": "User ID to delete.", "name": "id", "in": "query", "schema": { "$ref": "#/components/schemas/TypeId" }, "required": true } ], "responses": { "200": { "description": "User deleted", "content": { "application/json": { "schema": {} } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "CantDeleteOtherUser", "message": "Cannot delete a user from another account" } } }, "description": "Cannot delete a user from another account" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserNotFound", "message": "User not found" } } }, "description": "User not found" } }, "security": [ { "header": [] } ] }, "post": { "summary": "Create new user for the account", "description": "Creates a new user profile under the authenticated account. Requires authentication. Required fields: username, displayName, applicationId. Reserved usernames and duplicates are rejected. Only admins can create admin users. Bot/Service actor types cannot be assigned during creation.", "tags": [ "Users" ], "requestBody": { "description": "Json object with the users data", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserCreate" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/UserFull" } ] } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "CantConvertUserToBot", "message": "The user can't be converted to bot" } } }, "description": "The user can't be converted to bot" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "AuthForbidden": { "description": "Admin privileges are required", "value": { "errorCode": "AuthForbidden", "message": "Admin privileges are required" } }, "CantAddOtherUser": { "description": "Cannot add a user to another account", "value": { "errorCode": "CantAddOtherUser", "message": "Cannot add a user to another account" } }, "OnlyAdminsCreateAdmin": { "description": "Only administrators can create admin users", "value": { "errorCode": "OnlyAdminsCreateAdmin", "message": "Only administrators can create admin users" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AccountNotFound", "message": "Account not found" } } }, "description": "Account not found" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "UserNameExists": { "description": "The username is already in use", "value": { "errorCode": "UserNameExists", "message": "The username is already in use" } }, "UserNameIsReserved": { "description": "The username is reserved and cannot be used", "value": { "errorCode": "UserNameIsReserved", "message": "The username is reserved and cannot be used" } } } } }, "description": "Conflict" }, "500": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserCreationError", "message": "Failed to create the user" } } }, "description": "Failed to create the user" } }, "security": [ { "header": [] } ], "parameters": [ { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ] }, "get": { "summary": "Get user by username", "description": "Retrieves a user profile by username. Supports both local usernames and federated usernames (user@domain format). Accessible to both authenticated and guest users. If the username was recently changed, returns a 302 redirect to the new username. Use the 'full' parameter to include extended profile data. Authenticated users can request relationship statuses.", "tags": [ "Users" ], "parameters": [ { "description": "If true return also summary, stats, header and fields. Default false.", "required": false, "name": "full", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Include blocked_by status (target blocked viewer)", "required": false, "name": "includeBlockedByStatus", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Include blocked status (viewer blocked target)", "required": false, "name": "includeBlockedStatus", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Include followed status", "required": false, "name": "includeFollowedStatus", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Include following status", "required": false, "name": "includeFollowingStatus", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Include muted status", "required": false, "name": "includeMutedStatus", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Include all relationship statuses (following, followed, blocked, blocked_by, muted)", "required": false, "name": "relations", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Username to look up. Supports local ('alice') or federated ('alice@remote.social') format.", "name": "username", "in": "query", "schema": { "pattern": "\\S", "type": "string" }, "required": true }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/User" }, { "$ref": "#/components/schemas/UserFull" } ] } } } }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserNotFound", "message": "User not found" } } }, "description": "User not found" } }, "security": [] } }, "/api/v1/users/connections": { "get": { "summary": "List mutual connections", "description": "Returns users who have a mutual (bidirectional) follow relationship with the authenticated user. Both users follow each other. Can filter by connection status. By default returns only ACCEPTED mutual connections. Useful for finding close connections or friends.", "tags": [ "Follow" ], "parameters": [ { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "The target Follow status like: ACCEPTED/REJECTED/PENDING", "required": false, "name": "status", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/FollowingStatus" }, { "default": "ACCEPTED" } ] } }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/User" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/users/follow/{username}": { "post": { "summary": "Follow a user", "description": "Initiates a follow relationship with a local or remote user. For remote users, specify the domain parameter or include it in the username (user@domain). Supports mutual follows (bidirectional connections) when mutual=true. Checks for blocks and self-follows. Remote follows are sent via ActivityPub. Local follows may auto-accept based on user settings.", "tags": [ "Follow" ], "parameters": [ { "description": "Username of the followee", "required": true, "name": "username", "in": "path", "schema": { "type": "string" } }, { "description": "Followee's domain. If omitted assumed to be local", "required": false, "name": "domain", "in": "query", "schema": { "type": "string", "nullable": true } }, { "description": "'false' for regular Follow, 'true' for bidirectional Connect", "required": false, "name": "mutual", "in": "query", "schema": { "default": false, "type": "boolean" } }, { "description": "http vs. https. For testing ONLY", "required": false, "name": "scheme", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/AppScheme" }, { "default": "https" } ] } } ], "responses": { "200": { "description": "Follow result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowResult" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "FollowersCantFollowSelf", "message": "A user cannot follow themselves" } } }, "description": "A user cannot follow themselves" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "DomainBlocked": { "description": "The domain is blocked", "value": { "errorCode": "DomainBlocked", "message": "The domain is blocked" } }, "FolloweeBlockFollower": { "description": "The followee has blocked the follower", "value": { "errorCode": "FolloweeBlockFollower", "message": "The followee has blocked the follower" } }, "FollowerBlockFollowee": { "description": "The follower has blocked the followee", "value": { "errorCode": "FollowerBlockFollowee", "message": "The follower has blocked the followee" } }, "FollowerBlockFolloweeDomain": { "description": "The follower has blocked the followee's domain", "value": { "errorCode": "FollowerBlockFolloweeDomain", "message": "The follower has blocked the followee's domain" } }, "FolloweeBlockFollowerDomain": { "description": "The followee has blocked the follower's domain", "value": { "errorCode": "FolloweeBlockFollowerDomain", "message": "The followee has blocked the follower's domain" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "FolloweeNotFound", "message": "The followee could not be found" } } }, "description": "The followee could not be found" }, "409": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "FollowersConflict", "message": "A conflict occurred with the followers" } } }, "description": "A conflict occurred with the followers" } }, "security": [ { "header": [] } ] } }, "/api/v1/users/follow/{username}/accept": { "post": { "summary": "Accept follow request", "description": "Accepts a pending follow request from another user. Changes follow status from PENDING to ACCEPTED. Checks for blocks before accepting. Sends Accept activity to remote followers via ActivityPub. Only the followee can accept their own follow requests.", "tags": [ "Follow" ], "parameters": [ { "description": "The URI of the prospective follower", "required": true, "name": "username", "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "FollowWrongStatus", "message": "The target status is invalid" } } }, "description": "The target status is invalid" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "FolloweeBlockFollower": { "description": "The followee has blocked the follower", "value": { "errorCode": "FolloweeBlockFollower", "message": "The followee has blocked the follower" } }, "FollowerBlockFollowee": { "description": "The follower has blocked the followee", "value": { "errorCode": "FollowerBlockFollowee", "message": "The follower has blocked the followee" } }, "FolloweeBlockFollowerDomain": { "description": "The followee has blocked the follower's domain", "value": { "errorCode": "FolloweeBlockFollowerDomain", "message": "The followee has blocked the follower's domain" } }, "FollowerBlockFolloweeDomain": { "description": "The follower has blocked the followee's domain", "value": { "errorCode": "FollowerBlockFolloweeDomain", "message": "The follower has blocked the followee's domain" } } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "FollowerNotFound", "message": "The follower could not be found" } } }, "description": "The follower could not be found" } }, "security": [ { "header": [] } ] } }, "/api/v1/users/follow/{username}/pend": { "post": { "summary": "Reset follow request to pending", "description": "Resets a previously accepted or rejected follow request back to PENDING status. Useful when reconsidering a follow decision. The request can then be accepted or rejected again. Only affects the local follow status, not remote ActivityPub state.", "tags": [ "Follow" ], "parameters": [ { "description": "The URI of the prospective follower", "required": true, "name": "username", "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "FollowWrongStatus", "message": "The target status is invalid" } } }, "description": "The target status is invalid" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "FollowerNotFound", "message": "The follower could not be found" } } }, "description": "The follower could not be found" } }, "security": [ { "header": [] } ] } }, "/api/v1/users/follow/{username}/reject": { "post": { "summary": "Reject follow request", "description": "Rejects a pending follow request from another user. Changes follow status from PENDING to REJECTED. Sends Reject activity to remote followers via ActivityPub. The follower can retry following after rejection. Only the followee can reject their own follow requests.", "tags": [ "Follow" ], "parameters": [ { "description": "The URI of the prospective follower", "required": true, "name": "username", "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "FollowWrongStatus", "message": "The target status is invalid" } } }, "description": "The target status is invalid" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "FollowerNotFound", "message": "The follower could not be found" } } }, "description": "The follower could not be found" } }, "security": [ { "header": [] } ] } }, "/api/v1/users/follow/{username}/undo": { "post": { "summary": "Unfollow a user", "description": "Removes a follow relationship with a local or remote user. For remote users, specify the domain parameter or include it in the username. If mutual=true, removes bidirectional connection. Sends Undo Follow activity to remote users via ActivityPub. Returns error if no follow relationship exists.", "tags": [ "Follow" ], "parameters": [ { "description": "Username of the followee", "required": true, "name": "username", "in": "path", "schema": { "type": "string" } }, { "description": "Followee's domain. If omitted assumed to be local", "required": false, "name": "domain", "in": "query", "schema": { "type": "string", "nullable": true } }, { "description": "'false' for regular Follow, 'true' for bidirectional Connect", "required": false, "name": "mutual", "in": "query", "schema": { "default": false, "type": "boolean" } }, { "description": "http vs. https. For testing ONLY", "required": false, "name": "scheme", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/AppScheme" }, { "default": "https" } ] } } ], "responses": { "200": { "description": "Follow result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowResult" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "FollowRecordNotFound": { "description": "The specified follow record not found", "value": { "errorCode": "FollowRecordNotFound", "message": "The specified follow record not found" } }, "FolloweeNotFound": { "description": "The followee could not be found", "value": { "errorCode": "FolloweeNotFound", "message": "The followee could not be found" } } } } }, "description": "Not Found" } }, "security": [ { "header": [] } ] } }, "/api/v1/users/followees": { "get": { "summary": "List users you follow", "description": "Returns a paginated list of users that the authenticated user follows. Can filter by follow status (ACCEPTED, PENDING, REJECTED) or return all statuses. By default returns only ACCEPTED followees. Supports search with q. Includes both local and remote users.", "tags": [ "Follow" ], "parameters": [ { "description": "When true, returns followees in all statuses regardless of the 'status' parameter", "required": false, "name": "anyStatus", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "Search followees by username/display name/domain. Example: q=alice", "example": "alice", "required": false, "name": "q", "in": "query", "schema": { "type": "string", "nullable": true } }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "The target Follow status like: ACCEPTED/REJECTED/PENDING", "required": false, "name": "status", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/FollowingStatus" }, { "default": "ACCEPTED" } ] } }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/User" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/users/followers": { "get": { "summary": "List followers", "description": "Returns a paginated list of users who follow the authenticated user. Can filter by follow status (ACCEPTED, PENDING, REJECTED) or return all statuses. By default returns only ACCEPTED followers. Supports search with q. Includes both local and remote followers.", "tags": [ "Follow" ], "parameters": [ { "description": "When true, returns followers in all statuses regardless of the 'status' parameter", "required": false, "name": "anyStatus", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "Search followers by username/display name/domain. Example: q=alice", "example": "alice", "required": false, "name": "q", "in": "query", "schema": { "type": "string", "nullable": true } }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "The target Follow status like: ACCEPTED/REJECTED/PENDING", "required": false, "name": "status", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/FollowingStatus" }, { "default": "ACCEPTED" } ] } }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/User" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/users/invite-links": { "get": { "summary": "List invite links for current user", "description": "Returns a paginated list of invite links created by the authenticated user. Optionally filter by active/inactive status. Each link includes usage count, maximum uses, expiration date, and creation timestamp.", "tags": [ "SignupInviteLinks" ], "parameters": [ { "description": "Filter by active state", "required": false, "name": "active", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignupInviteLinkList" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] }, "post": { "summary": "Create a new signup invite link", "description": "Creates a new invite link with an auto-generated unique code. The invite can optionally have a maximum use count and expiration date. Requires authentication. Fails if invites are not enabled on the platform or if the user has exceeded the maximum number of invite links.", "tags": [ "SignupInviteLinks" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignupInviteLinkCreate" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignupInviteLink" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "InvitesNotEnabled": { "description": "Invite links are not enabled", "value": { "errorCode": "InvitesNotEnabled", "message": "Invite links are not enabled" } }, "TooManyInviteLinks": { "description": "Maximum number of active invite links reached", "value": { "errorCode": "TooManyInviteLinks", "message": "Maximum number of active invite links reached" } }, "ConstraintViolation": { "description": "A request parameter constraint was violated", "value": { "errorCode": "ConstraintViolation", "message": "A request parameter constraint was violated" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/users/invite-links/deactivate/{code}": { "put": { "summary": "Deactivate an invite link", "description": "Deactivates an existing invite link by its code, preventing further use. Only the owner of the invite link can deactivate it. Returns 404 if the invite link is not found or does not belong to the authenticated user.", "tags": [ "SignupInviteLinks" ], "parameters": [ { "description": "Invite code", "required": true, "name": "code", "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "ResourceNotFound", "message": "The requested resource not found" } } }, "description": "The requested resource not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/users/profile": { "get": { "summary": "Get current user profile", "description": "Returns the full profile of the currently authenticated user, including summary, stats, fields, avatar, header, and all extended profile data. Requires authentication.", "tags": [ "Users" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserFull" } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ], "parameters": [ { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ] } }, "/api/v1/users/relationships": { "get": { "summary": "Get relationships with users", "description": "Returns relationship status between the authenticated user and specified target users. Shows following/followed status and optionally blocked/muted/notes. Returns a map of user IDs to relationship objects. If no relationship exists for a user ID, it's omitted from the response. Useful for bulk checking relationship status.", "tags": [ "Follow" ], "parameters": [ { "description": "Include additional relationships, like following/followed/blocked/blocked_by/muted/note.\n If no 'filter' is provided, following and followed are enabled", "required": false, "name": "filter", "in": "query", "schema": { "uniqueItems": true, "type": "array", "items": { "type": "string" }, "nullable": true } }, { "description": "Target users to get relationship with", "required": true, "name": "targets", "in": "query", "schema": { "minItems": 1, "uniqueItems": true, "type": "array", "items": { "$ref": "#/components/schemas/TypeId" } } } ], "responses": { "200": { "description": "If userId is missing from response, no relationships found, no one follows anyone", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/Relationship" } } } } }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" } }, "security": [ { "header": [] } ] } }, "/api/v1/users/remote/{userNameFull}/followers": { "get": { "summary": "Get remote user's followers", "description": "Retrieves the follower collection of a remote federated user. Fetches the followers from the remote server using ActivityPub protocol. Supports pagination through offset and limit parameters. Only works for remote users, not local users.", "tags": [ "Remote collections" ], "parameters": [ { "description": "Username with the domain", "example": "user@dust.allroads.social", "required": true, "name": "userNameFull", "in": "path", "schema": { "type": "string" } }, { "description": "Show no more than the given number of users", "required": false, "name": "limit", "in": "query", "schema": { "format": "int32", "default": 20, "type": "integer" } }, { "description": "An offset to show users starting from", "required": false, "name": "offset", "in": "query", "schema": { "format": "int32", "default": 0, "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/User" } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "RemoteCollectionsNotRemote", "message": "User is not a remote user" } } }, "description": "User is not a remote user" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "RemoteCollectionsCannotFindUser", "message": "Cannot find remote user" } } }, "description": "Cannot find remote user" }, "500": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "RemoteCollectionsFailedFetch", "message": "Failed to fetch remote collections" } } }, "description": "Failed to fetch remote collections" } }, "security": [] } }, "/api/v1/users/remote/{userNameFull}/following": { "get": { "summary": "Get remote user's following", "description": "Retrieves the following collection of a remote federated user. Fetches the list of accounts that the remote user follows from their home server using ActivityPub protocol. Supports pagination through offset and limit parameters. Only works for remote users, not local users.", "tags": [ "Remote collections" ], "parameters": [ { "description": "Username with the domain", "example": "user@dust.allroads.social", "required": true, "name": "userNameFull", "in": "path", "schema": { "type": "string" } }, { "description": "Show no more than the given number of users", "required": false, "name": "limit", "in": "query", "schema": { "format": "int32", "default": 20, "type": "integer" } }, { "description": "An offset to show users starting from", "required": false, "name": "offset", "in": "query", "schema": { "format": "int32", "default": 0, "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/User" } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "RemoteCollectionsNotRemote", "message": "User is not a remote user" } } }, "description": "User is not a remote user" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "RemoteCollectionsCannotFindUser", "message": "Cannot find remote user" } } }, "description": "Cannot find remote user" }, "500": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "RemoteCollectionsFailedFetch", "message": "Failed to fetch remote collections" } } }, "description": "Failed to fetch remote collections" } }, "security": [] } }, "/api/v1/users/rename-history": { "get": { "summary": "Get list of username changes", "description": "Returns the username change history for the currently authenticated user, along with the maximum number of renames allowed. Requires authentication.", "tags": [ "Users" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsernameHistories" } } } }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserNotFound", "message": "User not found" } } }, "description": "User not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/users/{userId}": { "put": { "summary": "Update user's profile", "description": "Updates the profile of the specified user. Requires authentication and the user must belong to the authenticated account. Updatable fields include: displayName, username, summary, avatarId, headerId, timezone, location, birthday, and channel settings. Username changes are audited and subject to a maximum rename limit. Cannot convert a regular user to a bot/Service actor type.", "tags": [ "Users" ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserUpdate" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserFull" } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "TimezoneCannotUpdate": { "description": "Failed to update the timezone", "value": { "errorCode": "TimezoneCannotUpdate", "message": "Failed to update the timezone" } }, "UserLocationAutoUpdateNeedGeo": { "description": "geo coding is required when autoUpdate is true", "value": { "errorCode": "UserLocationAutoUpdateNeedGeo", "message": "geo coding is required when autoUpdate is true" } }, "CantConvertUserToBot": { "description": "The user can't be converted to bot", "value": { "errorCode": "CantConvertUserToBot", "message": "The user can't be converted to bot" } } } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserNotFound", "message": "User not found" } } }, "description": "User not found" } }, "security": [ { "header": [] } ] }, "get": { "summary": "Get user by userId", "description": "Retrieves a user profile by their unique user ID. Accessible to both authenticated and guest users. Use 'full' parameter to include extended profile data (summary, stats, header, fields). Authenticated users can request relationship statuses (following, blocked, muted) between themselves and the target user. Returns 302 redirect if the user has been renamed.", "tags": [ "Users" ], "parameters": [ { "description": "The unique user ID", "name": "userId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "If true return also summary, stats, header and fields. Default false.", "required": false, "name": "full", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Include blocked_by status (target blocked viewer)", "required": false, "name": "includeBlockedByStatus", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Include blocked status (viewer blocked target)", "required": false, "name": "includeBlockedStatus", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Include followed status", "required": false, "name": "includeFollowedStatus", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Include following status", "required": false, "name": "includeFollowingStatus", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Include muted status", "required": false, "name": "includeMutedStatus", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "description": "Include all relationship statuses (following, followed, blocked, blocked_by, muted)", "required": false, "name": "relations", "in": "query", "schema": { "type": "boolean", "nullable": true } }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/User" }, { "$ref": "#/components/schemas/UserFull" } ] } } } }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserNotFound", "message": "User not found" } } }, "description": "User not found" } }, "security": [] } }, "/api/v1/users/{userId}/deep-sync": { "post": { "summary": "Trigger deep sync for a remote user", "description": "Triggers a deep sync of a remote user's outbox. Fetches all posts paginated from the user's outbox and saves them locally. Only works for remote users that the caller follows. Returns the current sync state.", "tags": [ "Users" ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } } ], "responses": { "200": { "description": "Deep sync submitted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeepSyncResponse" } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "Forbidden", "message": "No access to the resource" } } }, "description": "No access to the resource" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserNotFound", "message": "User not found" } } }, "description": "User not found" } }, "security": [ { "header": [] } ] } }, "/api/v1/users/{userId}/followers": { "get": { "summary": "Users which follow the given account", "description": "Returns a paginated list of users who follow the specified user. Accessible to both authenticated and guest users. The list may be hidden if the user's privacy settings disable follower visibility, or if the viewer is blocked by the target user. The owner of the profile can always see their own followers. Supports search filtering by username, display name, or domain.", "tags": [ "Users" ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "Search followers by username/display name/domain. Example: q=alice", "example": "alice", "required": false, "name": "q", "in": "query", "schema": { "type": "string", "nullable": true } }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } ], "responses": { "200": { "description": "List of followers as User objects", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/User" } } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "FollowersListHidden", "message": "The user has hidden their followers list" } } }, "description": "The user has hidden their followers list" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserNotFound", "message": "User not found" } } }, "description": "User not found" } }, "security": [] } }, "/api/v1/users/{userId}/following": { "get": { "summary": "Users which the given account follows", "description": "Returns a paginated list of users that the specified user follows. Accessible to both authenticated and guest users. The list may be hidden if the user's privacy settings disable follower visibility, or if the viewer is blocked by the target user. The owner of the profile can always see their own following list. Supports search filtering by username, display name, or domain.", "tags": [ "Users" ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "description": "Get older records (records with IDs less than this value) Alias maxId/max_id", "example": "?lastId=${data.last().id}", "required": false, "name": "lastId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } }, { "name": "limit", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "name": "offset", "in": "query", "schema": { "format": "int32", "type": "integer", "nullable": true }, "required": false }, { "description": "Search followees by username/display name/domain. Example: q=alice", "example": "alice", "required": false, "name": "q", "in": "query", "schema": { "type": "string", "nullable": true } }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Sort order. Supported values: ASC or DESC", "name": "sortOrder", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false }, { "description": "Get newer records (records with IDs greater than this value) Alias minId/min_id", "example": "?untilId=${data.first().id}", "required": false, "name": "untilId", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/TypeId" } ], "nullable": true } } ], "responses": { "200": { "description": "List of following as User objects", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/User" } } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "FollowingListHidden", "message": "The user has hidden their following list" } } }, "description": "The user has hidden their following list" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserNotFound", "message": "User not found" } } }, "description": "User not found" } }, "security": [] } }, "/api/v1/users/{userId}/media": { "put": { "summary": "Update user avatar and header", "description": "Updates the avatar and/or header images for the specified user. Requires authentication and the user must belong to the authenticated account. Pass upload IDs for the new avatar or header.", "tags": [ "Users" ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TypeId" } }, { "name": "htmlContent", "in": "query", "description": "Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.", "required": false, "schema": {} } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserUpdateMedia" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserFull" } } } }, "400": { "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "AuthUnauthorized", "message": "A valid authentication token is required" } } }, "description": "A valid authentication token is required" }, "404": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "example": { "errorCode": "UserNotFound", "message": "User not found" } } }, "description": "User not found" } }, "security": [ { "header": [] } ] } }, "/authorize_interaction": { "get": { "parameters": [ { "name": "uri", "in": "query", "schema": { "type": "string", "nullable": true }, "required": false } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {} } } } }, "summary": "Authorize Interaction", "tags": [ "Authorize Interaction Resource" ], "security": [] } }, "/": { "get": { "operationId": "getRoot", "summary": "Root page", "tags": [ "Platform routes" ], "security": [ { "header": [] } ], "responses": { "200": { "description": "Page data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RootPageData" } } } }, "404": { "description": "Not found" } }, "parameters": [ { "name": "format", "in": "query", "description": "Response format. Set to 'json' to get JSON response (HTML is returned by default)", "required": true, "schema": { "type": "string" }, "example": "json" } ] } }, "/@{username}": { "get": { "operationId": "getUser", "summary": "User profile page", "tags": [ "Platform routes" ], "security": [ { "header": [] } ], "responses": { "200": { "description": "Page data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserPageData" } } } }, "404": { "description": "Not found" } }, "parameters": [ { "name": "username", "in": "path", "description": "Username", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "Response format. Set to 'json' to get JSON response (HTML is returned by default)", "required": true, "schema": { "type": "string" }, "example": "json" } ] } }, "/@{username}/events/{eventId}": { "get": { "operationId": "getUserEvent", "summary": "User event page", "tags": [ "Platform routes" ], "security": [ { "header": [] } ], "responses": { "200": { "description": "Page data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserEventPageData" } } } }, "404": { "description": "Not found" } }, "parameters": [ { "name": "username", "in": "path", "description": "Username", "required": true, "schema": { "type": "string" } }, { "name": "eventId", "in": "path", "description": "Event ID", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "Response format. Set to 'json' to get JSON response (HTML is returned by default)", "required": true, "schema": { "type": "string" }, "example": "json" } ] } }, "/@{username}/posts/{postId}": { "get": { "operationId": "getUserPost", "summary": "User post page", "tags": [ "Platform routes" ], "security": [ { "header": [] } ], "responses": { "200": { "description": "Page data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserPostPageData" } } } }, "404": { "description": "Not found" } }, "parameters": [ { "name": "username", "in": "path", "description": "Username", "required": true, "schema": { "type": "string" } }, { "name": "postId", "in": "path", "description": "Post ID", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "Response format. Set to 'json' to get JSON response (HTML is returned by default)", "required": true, "schema": { "type": "string" }, "example": "json" } ] } }, "/about": { "get": { "operationId": "getAbout", "summary": "About page", "tags": [ "Platform routes" ], "security": [ { "header": [] } ], "responses": { "200": { "description": "Page data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AboutPageData" } } } }, "404": { "description": "Not found" } }, "parameters": [ { "name": "format", "in": "query", "description": "Response format. Set to 'json' to get JSON response (HTML is returned by default)", "required": true, "schema": { "type": "string" }, "example": "json" } ] } }, "/feed": { "get": { "operationId": "getFeed", "summary": "Main feed", "tags": [ "Platform routes" ], "security": [ { "header": [] } ], "responses": { "200": { "description": "Page data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedPageData" } } } }, "404": { "description": "Not found" } }, "parameters": [ { "name": "format", "in": "query", "description": "Response format. Set to 'json' to get JSON response (HTML is returned by default)", "required": true, "schema": { "type": "string" }, "example": "json" } ] } }, "/feed/discover": { "get": { "operationId": "getFeedDiscover", "summary": "Discover feed", "tags": [ "Platform routes" ], "security": [ { "header": [] } ], "responses": { "200": { "description": "Page data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedDiscoverPageData" } } } }, "404": { "description": "Not found" } }, "parameters": [ { "name": "format", "in": "query", "description": "Response format. Set to 'json' to get JSON response (HTML is returned by default)", "required": true, "schema": { "type": "string" }, "example": "json" } ] } }, "/feed/following": { "get": { "operationId": "getFeedFollowing", "summary": "Following feed", "tags": [ "Platform routes" ], "security": [ { "header": [] } ], "responses": { "200": { "description": "Page data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedFollowingPageData" } } } }, "404": { "description": "Not found" } }, "parameters": [ { "name": "format", "in": "query", "description": "Response format. Set to 'json' to get JSON response (HTML is returned by default)", "required": true, "schema": { "type": "string" }, "example": "json" } ] } }, "/g/{groupName}": { "get": { "operationId": "getGroup", "summary": "Group page", "tags": [ "Platform routes" ], "security": [ { "header": [] } ], "responses": { "200": { "description": "Page data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupPageData" } } } }, "404": { "description": "Not found" } }, "parameters": [ { "name": "groupName", "in": "path", "description": "Group name", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "Response format. Set to 'json' to get JSON response (HTML is returned by default)", "required": true, "schema": { "type": "string" }, "example": "json" } ] } }, "/g/{groupName}/@{channelName}": { "get": { "operationId": "getGroupChannel", "summary": "Group channel page", "tags": [ "Platform routes" ], "security": [ { "header": [] } ], "responses": { "200": { "description": "Page data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupChannelPageData" } } } }, "404": { "description": "Not found" } }, "parameters": [ { "name": "groupName", "in": "path", "description": "Group name", "required": true, "schema": { "type": "string" } }, { "name": "channelName", "in": "path", "description": "Channel name", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "Response format. Set to 'json' to get JSON response (HTML is returned by default)", "required": true, "schema": { "type": "string" }, "example": "json" } ] } }, "/g/{groupName}/@{channelName}/posts/{postId}": { "get": { "operationId": "getGroupChannelPost", "summary": "Group channel post page", "tags": [ "Platform routes" ], "security": [ { "header": [] } ], "responses": { "200": { "description": "Page data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupChannelPostPageData" } } } }, "404": { "description": "Not found" } }, "parameters": [ { "name": "groupName", "in": "path", "description": "Group name", "required": true, "schema": { "type": "string" } }, { "name": "channelName", "in": "path", "description": "Channel name", "required": true, "schema": { "type": "string" } }, { "name": "postId", "in": "path", "description": "Post ID", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "Response format. Set to 'json' to get JSON response (HTML is returned by default)", "required": true, "schema": { "type": "string" }, "example": "json" } ] } }, "/g/{groupName}/bots/@{botName}": { "get": { "operationId": "getGroupBot", "summary": "Group bot page", "tags": [ "Platform routes" ], "security": [ { "header": [] } ], "responses": { "200": { "description": "Page data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupBotPageData" } } } }, "404": { "description": "Not found" } }, "parameters": [ { "name": "groupName", "in": "path", "description": "Group name", "required": true, "schema": { "type": "string" } }, { "name": "botName", "in": "path", "description": "Bot name", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "Response format. Set to 'json' to get JSON response (HTML is returned by default)", "required": true, "schema": { "type": "string" }, "example": "json" } ] } }, "/g/{groupName}/events/{eventId}": { "get": { "operationId": "getGroupEvent", "summary": "Group event page", "tags": [ "Platform routes" ], "security": [ { "header": [] } ], "responses": { "200": { "description": "Page data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupEventPageData" } } } }, "404": { "description": "Not found" } }, "parameters": [ { "name": "groupName", "in": "path", "description": "Group name", "required": true, "schema": { "type": "string" } }, { "name": "eventId", "in": "path", "description": "Event ID", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "Response format. Set to 'json' to get JSON response (HTML is returned by default)", "required": true, "schema": { "type": "string" }, "example": "json" } ] } }, "/privacy": { "get": { "operationId": "getPrivacy", "summary": "Privacy policy page", "tags": [ "Platform routes" ], "security": [ { "header": [] } ], "responses": { "200": { "description": "Page data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivacyPageData" } } } }, "404": { "description": "Not found" } }, "parameters": [ { "name": "format", "in": "query", "description": "Response format. Set to 'json' to get JSON response (HTML is returned by default)", "required": true, "schema": { "type": "string" }, "example": "json" } ] } }, "/terms": { "get": { "operationId": "getTerms", "summary": "Terms of use page", "tags": [ "Platform routes" ], "security": [ { "header": [] } ], "responses": { "200": { "description": "Page data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TermsPageData" } } } }, "404": { "description": "Not found" } }, "parameters": [ { "name": "format", "in": "query", "description": "Response format. Set to 'json' to get JSON response (HTML is returned by default)", "required": true, "schema": { "type": "string" }, "example": "json" } ] } } }, "info": { "title": "Wellesley Platform API", "version": "1.0", "description": "Wellesley is a decentralized social platform built on top of ActivityPub. It operates as a federation\nof independent servers that exchange data using standard ActivityPub messages alongside custom\nextensions. The platform strives for Mastodon compatibility while introducing additional\ncapabilities such as Groups, rich media, AI agents, and fine-grained access control.\n\nThis API provides full access to the platform's functionality including user and account management,\nposting and feeds, group creation and moderation, notifications, real-time streaming, search,\nfederated content delivery, AI agent configuration, and platform administration. Most endpoints\naccept and return JSON. Pagination follows cursor-based patterns using Link headers.\n\n**Authentication:** Endpoints that require authentication expect an `Authorization` header with\na valid access token. Unauthenticated requests to protected endpoints will receive a 401 response.\n\n**RBAC (Role-Based Access Control):** Some endpoints are protected by RBAC permissions. When an\nendpoint description mentions \"RBAC: requires ...\", the caller must hold the listed permission(s)\nin addition to being authenticated. Requests that lack the required permissions will receive a\n403 response. RBAC permissions are scoped to resources (e.g., Group, Post, User) and actions\n(e.g., Read, Write, Moderate), and are assigned through roles." }, "servers": [ { "url": "https://dust.allroads.social", "description": "Simple setup, all in one. Digital Ocean" }, { "url": "https://meteor.allroads.social", "description": "Simple setup, db is separate. Digital Ocean" } ], "security": [ { "header": [] } ] }