@agentuity/core 1.0.41 → 1.0.42

package/src/services/task/api-reference.ts

@@ -0,0 +1,830 @@
+import {
+	BatchDeleteTasksParamsSchema,
+	BatchDeleteTasksResultSchema,
+	CreateAttachmentParamsSchema,
+	CreateTaskParamsSchema,
+	ListAttachmentsResultSchema,
+	ListCommentsResultSchema,
+	ListProjectsResultSchema,
+	ListTasksResultSchema,
+	ListUsersResultSchema,
+	PresignDownloadResponseSchema,
+	PresignUploadResponseSchema,
+	TaskActivityResultSchema,
+	TaskChangelogResultSchema,
+	UpdateTaskParamsSchema,
+} from './service.ts';
+import {
+	CreateCommentRequestSchema,
+	CreateTagRequestSchema,
+	CreateTaskProjectRequestSchema,
+	CreateTaskUserRequestSchema,
+	UpdateCommentRequestSchema,
+	UpdateTagRequestSchema,
+} from './types.ts';
+import type { Service } from '../api-reference.ts';
+
+const service: Service = {
+	name: 'Tasks',
+	slug: 'tasks',
+	description:
+		'Full-featured task management with epics, features, bugs, comments, tags, attachments, and activity tracking',
+	endpoints: [
+		// ── Task Management ──────────────────────────────────────────────
+		{
+			id: 'create-task',
+			title: 'Create Task',
+			sectionTitle: 'Task Management',
+			method: 'POST',
+			path: '/task',
+			description: 'Create a new task within the organization.',
+			pathParams: [],
+			queryParams: [],
+			requestBody: {
+				description: 'Task creation payload.',
+				fields: { schema: CreateTaskParamsSchema },
+			},
+			responseDescription: 'Returns the created task.',
+			statuses: [
+				{ code: 201, description: 'Task created' },
+				{ code: 401, description: 'Unauthorized — invalid or missing API key' },
+			],
+			examplePath: '/task',
+			exampleBody: {
+				title: 'Implement auth flow',
+				type: 'feature',
+				created_id: 'usr_abc123',
+				priority: 'high',
+			},
+		},
+		{
+			id: 'get-task',
+			title: 'Get Task',
+			sectionTitle: 'Task Management',
+			method: 'GET',
+			path: '/task/{id}',
+			description: 'Retrieve a specific task by ID.',
+			pathParams: [{ name: 'id', type: 'string', description: 'Task ID', required: true }],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Returns the task object.',
+			statuses: [
+				{ code: 200, description: 'Task returned' },
+				{ code: 401, description: 'Unauthorized — invalid or missing API key' },
+				{ code: 404, description: 'Task not found' },
+			],
+			examplePath: '/task/tsk_abc123',
+		},
+		{
+			id: 'list-tasks',
+			title: 'List Tasks',
+			sectionTitle: 'Task Management',
+			method: 'GET',
+			path: '/task',
+			description: 'List tasks with optional filtering, sorting, and pagination.',
+			pathParams: [],
+			queryParams: [
+				{ name: 'status', type: 'string', description: 'Filter by status', required: false },
+				{ name: 'type', type: 'string', description: 'Filter by type', required: false },
+				{
+					name: 'priority',
+					type: 'string',
+					description: 'Filter by priority',
+					required: false,
+				},
+				{
+					name: 'assigned_id',
+					type: 'string',
+					description: 'Filter by assigned user',
+					required: false,
+				},
+				{
+					name: 'created_id',
+					type: 'string',
+					description: 'Filter by creator',
+					required: false,
+				},
+				{
+					name: 'parent_id',
+					type: 'string',
+					description: 'Filter by parent task',
+					required: false,
+				},
+				{
+					name: 'project_id',
+					type: 'string',
+					description: 'Filter by project',
+					required: false,
+				},
+				{ name: 'tag_id', type: 'string', description: 'Filter by tag', required: false },
+				{
+					name: 'deleted',
+					type: 'boolean',
+					description: 'Include soft-deleted tasks',
+					required: false,
+				},
+				{
+					name: 'sort',
+					type: 'string',
+					description: "Field to sort by — prefix with '-' for descending",
+					required: false,
+				},
+				{ name: 'order', type: 'string', description: "'asc' or 'desc'", required: false },
+				{
+					name: 'limit',
+					type: 'number',
+					description: 'Maximum results to return',
+					required: false,
+				},
+				{ name: 'offset', type: 'number', description: 'Pagination offset', required: false },
+			],
+			requestBody: null,
+			responseDescription: 'Returns paginated list of tasks.',
+			responseFields: { schema: ListTasksResultSchema },
+			statuses: [
+				{ code: 200, description: 'Tasks returned' },
+				{ code: 401, description: 'Unauthorized — invalid or missing API key' },
+			],
+			examplePath: '/task',
+		},
+		{
+			id: 'update-task',
+			title: 'Update Task',
+			sectionTitle: 'Task Management',
+			method: 'PATCH',
+			path: '/task/{id}',
+			description: 'Update one or more fields on an existing task.',
+			pathParams: [{ name: 'id', type: 'string', description: 'Task ID', required: true }],
+			queryParams: [],
+			requestBody: {
+				description: 'Task update payload. All fields are optional.',
+				fields: { schema: UpdateTaskParamsSchema },
+			},
+			responseDescription: 'Returns the updated task.',
+			statuses: [
+				{ code: 200, description: 'Task updated' },
+				{ code: 401, description: 'Unauthorized — invalid or missing API key' },
+				{ code: 404, description: 'Task not found' },
+			],
+			examplePath: '/task/tsk_abc123',
+			exampleBody: { status: 'in_progress', priority: 'high' },
+		},
+		{
+			id: 'close-task',
+			title: 'Close Task',
+			sectionTitle: 'Task Management',
+			method: 'DELETE',
+			path: '/task/{id}',
+			description:
+				"Sets the task status to 'done' and records the closed date. This does NOT permanently delete the task.",
+			pathParams: [{ name: 'id', type: 'string', description: 'Task ID', required: true }],
+			queryParams: [],
+			requestBody: null,
+			responseDescription:
+				"Sets the task status to 'done' and records the closed date. This does NOT permanently delete the task.",
+			statuses: [
+				{ code: 200, description: 'Task closed' },
+				{ code: 401, description: 'Unauthorized — invalid or missing API key' },
+				{ code: 404, description: 'Task not found' },
+			],
+			examplePath: '/task/tsk_abc123',
+		},
+		{
+			id: 'soft-delete-task',
+			title: 'Soft Delete Task',
+			sectionTitle: 'Task Management',
+			method: 'POST',
+			path: '/task/delete/{id}',
+			description: 'Marks the task as deleted without permanent removal.',
+			pathParams: [{ name: 'id', type: 'string', description: 'Task ID', required: true }],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Marks the task as deleted without permanent removal.',
+			statuses: [
+				{ code: 200, description: 'Task soft-deleted' },
+				{ code: 401, description: 'Unauthorized — invalid or missing API key' },
+				{ code: 404, description: 'Task not found' },
+			],
+			examplePath: '/task/delete/tsk_abc123',
+		},
+		{
+			id: 'batch-delete-tasks',
+			title: 'Batch Delete Tasks',
+			sectionTitle: 'Task Management',
+			method: 'POST',
+			path: '/task/delete/batch',
+			description: 'Soft-delete multiple tasks matching filter criteria.',
+			pathParams: [],
+			queryParams: [],
+			requestBody: {
+				description: 'Batch delete filter payload.',
+				fields: { schema: BatchDeleteTasksParamsSchema },
+			},
+			responseDescription: 'Returns the list of deleted tasks and count.',
+			responseFields: { schema: BatchDeleteTasksResultSchema },
+			statuses: [
+				{ code: 200, description: 'Tasks deleted' },
+				{ code: 401, description: 'Unauthorized — invalid or missing API key' },
+			],
+			examplePath: '/task/delete/batch',
+			exampleBody: { status: 'cancelled', older_than: '30d', limit: 50 },
+		},
+		{
+			id: 'get-changelog',
+			title: 'Get Changelog',
+			sectionTitle: 'Task Management',
+			method: 'GET',
+			path: '/task/changelog/{id}',
+			description: 'Get the change history for a specific task.',
+			pathParams: [{ name: 'id', type: 'string', description: 'Task ID', required: true }],
+			queryParams: [
+				{
+					name: 'limit',
+					type: 'number',
+					description: 'Maximum results to return',
+					required: false,
+				},
+				{ name: 'offset', type: 'number', description: 'Pagination offset', required: false },
+			],
+			requestBody: null,
+			responseDescription: 'Returns the changelog entries for the task.',
+			responseFields: { schema: TaskChangelogResultSchema },
+			statuses: [
+				{ code: 200, description: 'Changelog returned' },
+				{ code: 401, description: 'Unauthorized — invalid or missing API key' },
+				{ code: 404, description: 'Task not found' },
+			],
+			examplePath: '/task/changelog/tsk_abc123',
+		},
+		// ── Comments ─────────────────────────────────────────────────────
+		{
+			id: 'create-comment',
+			title: 'Create Comment',
+			sectionTitle: 'Comments',
+			method: 'POST',
+			path: '/task/comments/create/{taskId}',
+			description: 'Add a comment to a task.',
+			pathParams: [{ name: 'taskId', type: 'string', description: 'Task ID', required: true }],
+			queryParams: [],
+			requestBody: {
+				description: 'Comment creation payload.',
+				fields: { schema: CreateCommentRequestSchema },
+			},
+			responseDescription: 'Returns the created comment.',
+			statuses: [
+				{ code: 201, description: 'Comment created' },
+				{ code: 401, description: 'Unauthorized — invalid or missing API key' },
+				{ code: 404, description: 'Task not found' },
+			],
+			examplePath: '/task/comments/create/tsk_abc123',
+			exampleBody: { body: 'Looks good, ready for review', user_id: 'usr_abc123' },
+		},
+		{
+			id: 'get-comment',
+			title: 'Get Comment',
+			sectionTitle: 'Comments',
+			method: 'GET',
+			path: '/task/comments/get/{commentId}',
+			description: 'Retrieve a specific comment by ID.',
+			pathParams: [
+				{ name: 'commentId', type: 'string', description: 'Comment ID', required: true },
+			],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Returns the comment object.',
+			statuses: [
+				{ code: 200, description: 'Comment returned' },
+				{ code: 401, description: 'Unauthorized — invalid or missing API key' },
+				{ code: 404, description: 'Comment not found' },
+			],
+			examplePath: '/task/comments/get/cmt_abc123',
+		},
+		{
+			id: 'update-comment',
+			title: 'Update Comment',
+			sectionTitle: 'Comments',
+			method: 'PATCH',
+			path: '/task/comments/update/{commentId}',
+			description: 'Update the body of an existing comment.',
+			pathParams: [
+				{ name: 'commentId', type: 'string', description: 'Comment ID', required: true },
+			],
+			queryParams: [],
+			requestBody: {
+				description: 'Comment update payload.',
+				fields: { schema: UpdateCommentRequestSchema },
+			},
+			responseDescription: 'Returns the updated comment.',
+			statuses: [
+				{ code: 200, description: 'Comment updated' },
+				{ code: 401, description: 'Unauthorized — invalid or missing API key' },
+				{ code: 404, description: 'Comment not found' },
+			],
+			examplePath: '/task/comments/update/cmt_abc123',
+			exampleBody: { body: 'Updated comment text' },
+		},
+		{
+			id: 'delete-comment',
+			title: 'Delete Comment',
+			sectionTitle: 'Comments',
+			method: 'DELETE',
+			path: '/task/comments/delete/{commentId}',
+			description: 'Delete a comment.',
+			pathParams: [
+				{ name: 'commentId', type: 'string', description: 'Comment ID', required: true },
+			],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Empty response on success.',
+			statuses: [
+				{ code: 204, description: 'Comment deleted' },
+				{ code: 401, description: 'Unauthorized — invalid or missing API key' },
+				{ code: 404, description: 'Comment not found' },
+			],
+			examplePath: '/task/comments/delete/cmt_abc123',
+		},
+		{
+			id: 'list-comments',
+			title: 'List Comments',
+			sectionTitle: 'Comments',
+			method: 'GET',
+			path: '/task/comments/list/{taskId}',
+			description: 'List all comments on a task.',
+			pathParams: [{ name: 'taskId', type: 'string', description: 'Task ID', required: true }],
+			queryParams: [
+				{
+					name: 'limit',
+					type: 'number',
+					description: 'Maximum results to return',
+					required: false,
+				},
+				{ name: 'offset', type: 'number', description: 'Pagination offset', required: false },
+			],
+			requestBody: null,
+			responseDescription: 'Returns paginated list of comments.',
+			responseFields: { schema: ListCommentsResultSchema },
+			statuses: [
+				{ code: 200, description: 'Comments returned' },
+				{ code: 401, description: 'Unauthorized — invalid or missing API key' },
+				{ code: 404, description: 'Task not found' },
+			],
+			examplePath: '/task/comments/list/tsk_abc123',
+		},
+		// ── Tags ─────────────────────────────────────────────────────────
+		{
+			id: 'create-tag',
+			title: 'Create Tag',
+			sectionTitle: 'Tags',
+			method: 'POST',
+			path: '/task/tags/create',
+			description: 'Create a new tag for organizing tasks.',
+			pathParams: [],
+			queryParams: [],
+			requestBody: {
+				description: 'Tag creation payload.',
+				fields: { schema: CreateTagRequestSchema },
+			},
+			responseDescription: 'Returns the created tag.',
+			statuses: [
+				{ code: 201, description: 'Tag created' },
+				{ code: 401, description: 'Unauthorized — invalid or missing API key' },
+			],
+			examplePath: '/task/tags/create',
+			exampleBody: { name: 'urgent', color: '#ff0000' },
+		},
+		{
+			id: 'get-tag',
+			title: 'Get Tag',
+			sectionTitle: 'Tags',
+			method: 'GET',
+			path: '/task/tags/get/{tagId}',
+			description: 'Retrieve a specific tag by ID.',
+			pathParams: [{ name: 'tagId', type: 'string', description: 'Tag ID', required: true }],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Returns the tag object.',
+			statuses: [
+				{ code: 200, description: 'Tag returned' },
+				{ code: 401, description: 'Unauthorized — invalid or missing API key' },
+				{ code: 404, description: 'Tag not found' },
+			],
+			examplePath: '/task/tags/get/tag_abc123',
+		},
+		{
+			id: 'update-tag',
+			title: 'Update Tag',
+			sectionTitle: 'Tags',
+			method: 'PATCH',
+			path: '/task/tags/update/{tagId}',
+			description: "Update a tag's name or color.",
+			pathParams: [{ name: 'tagId', type: 'string', description: 'Tag ID', required: true }],
+			queryParams: [],
+			requestBody: {
+				description: 'Tag update payload.',
+				fields: { schema: UpdateTagRequestSchema },
+			},
+			responseDescription: 'Returns the updated tag.',
+			statuses: [
+				{ code: 200, description: 'Tag updated' },
+				{ code: 401, description: 'Unauthorized — invalid or missing API key' },
+				{ code: 404, description: 'Tag not found' },
+			],
+			examplePath: '/task/tags/update/tag_abc123',
+			exampleBody: { name: 'critical', color: '#cc0000' },
+		},
+		{
+			id: 'delete-tag',
+			title: 'Delete Tag',
+			sectionTitle: 'Tags',
+			method: 'DELETE',
+			path: '/task/tags/delete/{tagId}',
+			description: 'Delete a tag.',
+			pathParams: [{ name: 'tagId', type: 'string', description: 'Tag ID', required: true }],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Empty response on success.',
+			statuses: [
+				{ code: 204, description: 'Tag deleted' },
+				{ code: 401, description: 'Unauthorized — invalid or missing API key' },
+				{ code: 404, description: 'Tag not found' },
+			],
+			examplePath: '/task/tags/delete/tag_abc123',
+		},
+		{
+			id: 'list-tags',
+			title: 'List Tags',
+			sectionTitle: 'Tags',
+			method: 'GET',
+			path: '/task/tags/list',
+			description: 'List all tags in the organization.',
+			pathParams: [],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Returns list of tags.',
+			statuses: [
+				{ code: 200, description: 'Tags returned' },
+				{ code: 401, description: 'Unauthorized — invalid or missing API key' },
+			],
+			examplePath: '/task/tags/list',
+		},
+		{
+			id: 'add-tag-to-task',
+			title: 'Add Tag to Task',
+			sectionTitle: 'Tags',
+			method: 'POST',
+			path: '/task/tags/add/{taskId}/{tagId}',
+			description: 'Associate a tag with a task.',
+			pathParams: [
+				{ name: 'taskId', type: 'string', description: 'Task ID', required: true },
+				{ name: 'tagId', type: 'string', description: 'Tag ID', required: true },
+			],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Returns confirmation of the association.',
+			statuses: [
+				{ code: 200, description: 'Tag added to task' },
+				{ code: 401, description: 'Unauthorized — invalid or missing API key' },
+				{ code: 404, description: 'Task or tag not found' },
+			],
+			examplePath: '/task/tags/add/tsk_abc123/tag_def456',
+		},
+		{
+			id: 'remove-tag-from-task',
+			title: 'Remove Tag from Task',
+			sectionTitle: 'Tags',
+			method: 'DELETE',
+			path: '/task/tags/remove/{taskId}/{tagId}',
+			description: 'Remove a tag association from a task.',
+			pathParams: [
+				{ name: 'taskId', type: 'string', description: 'Task ID', required: true },
+				{ name: 'tagId', type: 'string', description: 'Tag ID', required: true },
+			],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Empty response on success.',
+			statuses: [
+				{ code: 204, description: 'Tag removed from task' },
+				{ code: 401, description: 'Unauthorized — invalid or missing API key' },
+				{ code: 404, description: 'Task or tag not found' },
+			],
+			examplePath: '/task/tags/remove/tsk_abc123/tag_def456',
+		},
+		{
+			id: 'list-task-tags',
+			title: 'List Task Tags',
+			sectionTitle: 'Tags',
+			method: 'GET',
+			path: '/task/tags/task/{taskId}',
+			description: 'List all tags associated with a specific task.',
+			pathParams: [{ name: 'taskId', type: 'string', description: 'Task ID', required: true }],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Returns list of tags for the task.',
+			statuses: [
+				{ code: 200, description: 'Tags returned' },
+				{ code: 401, description: 'Unauthorized — invalid or missing API key' },
+				{ code: 404, description: 'Task not found' },
+			],
+			examplePath: '/task/tags/task/tsk_abc123',
+		},
+		// ── Attachments ──────────────────────────────────────────────────
+		{
+			id: 'request-upload-url',
+			title: 'Request Upload URL',
+			sectionTitle: 'Attachments',
+			method: 'POST',
+			path: '/task/attachments/presign-upload/{taskId}',
+			description: 'Request a presigned URL for uploading an attachment to a task.',
+			pathParams: [{ name: 'taskId', type: 'string', description: 'Task ID', required: true }],
+			queryParams: [],
+			requestBody: {
+				description: 'Upload request payload.',
+				fields: { schema: CreateAttachmentParamsSchema },
+			},
+			responseDescription:
+				'Returns a presigned upload URL. Upload the file via PUT to the URL, then call confirm.',
+			responseFields: { schema: PresignUploadResponseSchema },
+			statuses: [
+				{ code: 200, description: 'Presigned URL returned' },
+				{ code: 401, description: 'Unauthorized — invalid or missing API key' },
+				{ code: 404, description: 'Task not found' },
+			],
+			examplePath: '/task/attachments/presign-upload/tsk_abc123',
+			exampleBody: { filename: 'screenshot.png', content_type: 'image/png' },
+		},
+		{
+			id: 'confirm-upload',
+			title: 'Confirm Upload',
+			sectionTitle: 'Attachments',
+			method: 'POST',
+			path: '/task/attachments/confirm/{attachmentId}',
+			description: 'Confirm that a file was uploaded successfully to the presigned URL.',
+			pathParams: [
+				{ name: 'attachmentId', type: 'string', description: 'Attachment ID', required: true },
+			],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Confirms the file was uploaded successfully.',
+			statuses: [
+				{ code: 200, description: 'Upload confirmed' },
+				{ code: 401, description: 'Unauthorized — invalid or missing API key' },
+				{ code: 404, description: 'Attachment not found' },
+			],
+			examplePath: '/task/attachments/confirm/att_abc123',
+		},
+		{
+			id: 'request-download-url',
+			title: 'Request Download URL',
+			sectionTitle: 'Attachments',
+			method: 'POST',
+			path: '/task/attachments/presign-download/{attachmentId}',
+			description: 'Request a presigned URL for downloading an attachment.',
+			pathParams: [
+				{ name: 'attachmentId', type: 'string', description: 'Attachment ID', required: true },
+			],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Returns a presigned download URL.',
+			responseFields: { schema: PresignDownloadResponseSchema },
+			statuses: [
+				{ code: 200, description: 'Presigned URL returned' },
+				{ code: 401, description: 'Unauthorized — invalid or missing API key' },
+				{ code: 404, description: 'Attachment not found' },
+			],
+			examplePath: '/task/attachments/presign-download/att_abc123',
+		},
+		{
+			id: 'list-attachments',
+			title: 'List Attachments',
+			sectionTitle: 'Attachments',
+			method: 'GET',
+			path: '/task/attachments/list/{taskId}',
+			description: 'List all attachments on a task.',
+			pathParams: [{ name: 'taskId', type: 'string', description: 'Task ID', required: true }],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Returns list of attachments.',
+			responseFields: { schema: ListAttachmentsResultSchema },
+			statuses: [
+				{ code: 200, description: 'Attachments returned' },
+				{ code: 401, description: 'Unauthorized — invalid or missing API key' },
+				{ code: 404, description: 'Task not found' },
+			],
+			examplePath: '/task/attachments/list/tsk_abc123',
+		},
+		{
+			id: 'delete-attachment',
+			title: 'Delete Attachment',
+			sectionTitle: 'Attachments',
+			method: 'DELETE',
+			path: '/task/attachments/delete/{attachmentId}',
+			description: 'Delete an attachment.',
+			pathParams: [
+				{ name: 'attachmentId', type: 'string', description: 'Attachment ID', required: true },
+			],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Empty response on success.',
+			statuses: [
+				{ code: 204, description: 'Attachment deleted' },
+				{ code: 401, description: 'Unauthorized — invalid or missing API key' },
+				{ code: 404, description: 'Attachment not found' },
+			],
+			examplePath: '/task/attachments/delete/att_abc123',
+		},
+		// ── Users & Projects ─────────────────────────────────────────────
+		{
+			id: 'list-task-users',
+			title: 'List Task Users',
+			sectionTitle: 'Users & Projects',
+			method: 'GET',
+			path: '/task/users',
+			description: 'List all user entities available for task assignment.',
+			pathParams: [],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Returns list of user entities.',
+			responseFields: { schema: ListUsersResultSchema },
+			statuses: [
+				{ code: 200, description: 'Users returned' },
+				{ code: 401, description: 'Unauthorized — invalid or missing API key' },
+			],
+			examplePath: '/task/users',
+		},
+		{
+			id: 'create-task-user',
+			title: 'Create User Entity',
+			sectionTitle: 'Users & Projects',
+			method: 'POST',
+			path: '/task/users/create',
+			description: 'Create a new user entity for task assignment.',
+			pathParams: [],
+			queryParams: [],
+			requestBody: {
+				description: 'User entity creation payload.',
+				fields: { schema: CreateTaskUserRequestSchema },
+			},
+			responseDescription: 'Returns the created user entity.',
+			statuses: [
+				{ code: 201, description: 'User entity created' },
+				{ code: 401, description: 'Unauthorized — invalid or missing API key' },
+			],
+			examplePath: '/task/users/create',
+			exampleBody: { name: 'Alice', type: 'human' },
+		},
+		{
+			id: 'get-task-user',
+			title: 'Get User Entity',
+			sectionTitle: 'Users & Projects',
+			method: 'GET',
+			path: '/task/users/get/{userId}',
+			description: 'Retrieve a specific user entity by ID.',
+			pathParams: [
+				{ name: 'userId', type: 'string', description: 'User entity ID', required: true },
+			],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Returns the user entity object.',
+			statuses: [
+				{ code: 200, description: 'User entity returned' },
+				{ code: 401, description: 'Unauthorized — invalid or missing API key' },
+				{ code: 404, description: 'User entity not found' },
+			],
+			examplePath: '/task/users/get/usr_abc123',
+		},
+		{
+			id: 'delete-task-user',
+			title: 'Delete User Entity',
+			sectionTitle: 'Users & Projects',
+			method: 'DELETE',
+			path: '/task/users/delete/{userId}',
+			description: 'Delete a user entity.',
+			pathParams: [
+				{ name: 'userId', type: 'string', description: 'User entity ID', required: true },
+			],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Empty response on success.',
+			statuses: [
+				{ code: 204, description: 'User entity deleted' },
+				{ code: 401, description: 'Unauthorized — invalid or missing API key' },
+				{ code: 404, description: 'User entity not found' },
+			],
+			examplePath: '/task/users/delete/usr_abc123',
+		},
+		{
+			id: 'list-task-projects',
+			title: 'List Task Projects',
+			sectionTitle: 'Users & Projects',
+			method: 'GET',
+			path: '/task/projects',
+			description: 'List all project entities available for task organization.',
+			pathParams: [],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Returns list of project entities.',
+			responseFields: { schema: ListProjectsResultSchema },
+			statuses: [
+				{ code: 200, description: 'Projects returned' },
+				{ code: 401, description: 'Unauthorized — invalid or missing API key' },
+			],
+			examplePath: '/task/projects',
+		},
+		{
+			id: 'create-task-project',
+			title: 'Create Project Entity',
+			sectionTitle: 'Users & Projects',
+			method: 'POST',
+			path: '/task/projects/create',
+			description: 'Create a new project entity for task organization.',
+			pathParams: [],
+			queryParams: [],
+			requestBody: {
+				description: 'Project entity creation payload.',
+				fields: { schema: CreateTaskProjectRequestSchema },
+			},
+			responseDescription: 'Returns the created project entity.',
+			statuses: [
+				{ code: 201, description: 'Project entity created' },
+				{ code: 401, description: 'Unauthorized — invalid or missing API key' },
+			],
+			examplePath: '/task/projects/create',
+			exampleBody: { name: 'Backend Rewrite' },
+		},
+		{
+			id: 'get-task-project',
+			title: 'Get Project Entity',
+			sectionTitle: 'Users & Projects',
+			method: 'GET',
+			path: '/task/projects/get/{projectId}',
+			description: 'Retrieve a specific project entity by ID.',
+			pathParams: [
+				{ name: 'projectId', type: 'string', description: 'Project entity ID', required: true },
+			],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Returns the project entity object.',
+			statuses: [
+				{ code: 200, description: 'Project entity returned' },
+				{ code: 401, description: 'Unauthorized — invalid or missing API key' },
+				{ code: 404, description: 'Project entity not found' },
+			],
+			examplePath: '/task/projects/get/tprj_abc123',
+		},
+		{
+			id: 'delete-task-project',
+			title: 'Delete Project Entity',
+			sectionTitle: 'Users & Projects',
+			method: 'DELETE',
+			path: '/task/projects/delete/{projectId}',
+			description: 'Delete a project entity.',
+			pathParams: [
+				{ name: 'projectId', type: 'string', description: 'Project entity ID', required: true },
+			],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Empty response on success.',
+			statuses: [
+				{ code: 204, description: 'Project entity deleted' },
+				{ code: 401, description: 'Unauthorized — invalid or missing API key' },
+				{ code: 404, description: 'Project entity not found' },
+			],
+			examplePath: '/task/projects/delete/tprj_abc123',
+		},
+		// ── Activity ─────────────────────────────────────────────────────
+		{
+			id: 'get-activity-timeline',
+			title: 'Get Activity Timeline',
+			sectionTitle: 'Activity',
+			method: 'GET',
+			path: '/task/activity/{date}',
+			description: 'Get daily activity counts grouped by status over a configurable time range.',
+			pathParams: [
+				{
+					name: 'date',
+					type: 'string',
+					description: 'Date for activity lookup (YYYY-MM-DD format)',
+					required: true,
+				},
+			],
+			queryParams: [
+				{
+					name: 'days',
+					type: 'number',
+					description: 'Number of days (min 7, max 365, default 90)',
+					required: false,
+				},
+			],
+			requestBody: null,
+			responseDescription: 'Returns daily activity counts grouped by status.',
+			responseFields: { schema: TaskActivityResultSchema },
+			statuses: [
+				{ code: 200, description: 'Activity timeline returned' },
+				{ code: 401, description: 'Unauthorized — invalid or missing API key' },
+			],
+			examplePath: '/task/activity/2026-02-28',
+		},
+	],
+};
+
+export default service;