Reviews API

Reviews API v1 Complete document review and approval workflow system.

This API manages the entire review lifecycle from creation to final approval, enabling collaborative document review processes for teams.

Core functionality:

• Document review creation and management

• Multi-stage review workflows with status tracking

• Reviewer assignment and notification system

• Comment and feedback management

• Review approval and rejection workflows

• Review history and audit trails Workflow states:

• Draft: Initial review creation

• In Review: Active review process with assigned reviewers

• Ready: Review completed and ready for final approval

• Approved: Review approved and document published

• Rejected: Review rejected with feedback for revision All review operations maintain team-based access control and audit logging.

Endpoints

List reviews

List document reviews

Retrieve a paginated list of document reviews for the authenticated team. Supports filtering by review status.

Endpoint: GET /api/v1/reviews

Examples:

curl -X GET "https://simplistica.co/api/v1/reviews?limit=20&page=1" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json"

Query Parameters:

• limit (integer) Optional (default: 20) - Number of items to return
• page (integer) Optional (default: 1) - Page number for pagination (starts from 1)

Response Schema:

Example Response:

{
  "path": "/api/v1/reviews",
  "version": "v1",
  "timestamp": "2025-01-27T10:30:00.000Z",
  "data": {
    "data": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "title": "example_title",
        "type": "document",
        "reviewStatus": "draft",
        "createdAt": "2025-01-27T10:30:00.000Z",
        "updatedAt": "2025-01-27T10:30:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "hasNextPage": true,
      "prevPage": null,
      "nextPage": "https://simplistica.co/api/v1/documents?limit=20&page=2"
    }
  }
}

Responses:

• 200: Success
• 400: Bad Request
• 401: Unauthorized
• 500: Internal Server Error

Get review by ID

Retrieve a specific document review with all details including reviewers and comments.

Endpoint: GET /api/v1/reviews/{id}

Examples:

curl -X GET "https://simplistica.co/api/v1/reviews/{id}?limit=20&page=1" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json"

Parameters:

Path Parameters:

• id (string) Required - The id of the resource

Query Parameters:

• limit (integer) Optional (default: 20) - Number of items to return
• page (integer) Optional (default: 1) - Page number for pagination (starts from 1)

Response Schema:

Example Response:

{
  "path": "/api/v1/reviews/{id}",
  "version": "v1",
  "timestamp": "2025-01-27T10:30:00.000Z",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "title": "example_title",
    "content": "example_content",
    "type": "document",
    "reviewStatus": "draft",
    "createdAt": "2025-01-27T10:30:00.000Z",
    "updatedAt": "2025-01-27T10:30:00.000Z",
    "owner": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "example_name",
      "email": "user@example.com"
    },
    "ownerTeam": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "example_name"
    }
  }
}

Responses:

• 200: Success
• 400: Bad Request
• 401: Unauthorized
• 404: Not Found
• 500: Internal Server Error

Create review

Create a new document review

Create a new document review and assign reviewers. The document’s review status will be automatically updated to ‘in_review’.

Endpoint: POST /api/v1/reviews

Examples:

curl -X POST "https://simplistica.co/api/v1/reviews" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "documentId": "123e4567-e89b-12d3-a456-426614174000",
       "title": "example_title",
       "description": "example_description",
       "dueDate": "example_dueDate",
       "reviewerIds": []
     }'

Request Body Schema:

Response Schema:

Example Response:

{
  "path": "/api/v1/reviews",
  "version": "v1",
  "timestamp": "2025-01-27T10:30:00.000Z",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "title": "example_title",
    "content": "example_content",
    "type": "document",
    "reviewStatus": "draft",
    "createdAt": "2025-01-27T10:30:00.000Z",
    "updatedAt": "2025-01-27T10:30:00.000Z"
  }
}

Responses:

• 200: Success
• 400: Bad Request
• 401: Unauthorized
• 500: Internal Server Error

Add comment to review

Add a comment to a document review.

Creates a new comment thread and adds the first comment to the specified review. The comment will be associated with the authenticated user as the author.

Endpoint: POST /api/v1/reviews/{id}

Examples:

curl -X POST "https://simplistica.co/api/v1/reviews/{id}" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "content": "example_content"
     }'

Path Parameters:

• id (string) Required - The id of the resource

Request Body Schema:

Response Schema:

Example Response:

{
  "path": "/api/v1/reviews/{id}",
  "version": "v1",
  "timestamp": "2025-01-27T10:30:00.000Z",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "title": "example_title",
    "content": "example_content",
    "type": "document",
    "reviewStatus": "draft",
    "createdAt": "2025-01-27T10:30:00.000Z",
    "updatedAt": "2025-01-27T10:30:00.000Z"
  }
}

Responses:

• 200: Success
• 400: Bad Request
• 401: Unauthorized
• 500: Internal Server Error

Approve review

POST operation for reviews

Endpoint: POST /api/v1/reviews/{id}/approve

Examples:

curl -X POST "https://simplistica.co/api/v1/reviews/{id}/approve" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "reviewerId": "123e4567-e89b-12d3-a456-426614174000"
     }'

Path Parameters:

• id (string) Required - The id of the resource

Request Body Schema:

Response Schema:

Example Response:

{
  "path": "/api/v1/reviews/{id}/approve",
  "version": "v1",
  "timestamp": "2025-01-27T10:30:00.000Z",
  "data": {
    "message": "example_message",
    "success": true
  }
}

Responses:

• 200: Success
• 400: Bad Request
• 401: Unauthorized
• 500: Internal Server Error

Submit review

POST operation for reviews

Endpoint: POST /api/v1/reviews/{id}/submit

Examples:

curl -X POST "https://simplistica.co/api/v1/reviews/{id}/submit" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "reviewerId": "123e4567-e89b-12d3-a456-426614174000"
     }'

Path Parameters:

• id (string) Required - The id of the resource

Request Body Schema:

Response Schema:

Example Response:

{
  "path": "/api/v1/reviews/{id}/submit",
  "version": "v1",
  "timestamp": "2025-01-27T10:30:00.000Z",
  "data": {
    "message": "example_message",
    "success": true
  }
}

Responses:

• 200: Success
• 400: Bad Request
• 401: Unauthorized
• 500: Internal Server Error

Reject review

POST operation for reviews

Endpoint: POST /api/v1/reviews/{id}/reject

Examples:

curl -X POST "https://simplistica.co/api/v1/reviews/{id}/reject" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "reviewerId": "123e4567-e89b-12d3-a456-426614174000"
     }'

Path Parameters:

• id (string) Required - The id of the resource

Request Body Schema:

Response Schema:

Example Response:

{
  "path": "/api/v1/reviews/{id}/reject",
  "version": "v1",
  "timestamp": "2025-01-27T10:30:00.000Z",
  "data": {
    "message": "example_message",
    "success": true
  }
}

Responses:

• 200: Success
• 400: Bad Request
• 401: Unauthorized
• 500: Internal Server Error

Update review

Update review metadata including title, description, and due date.

Endpoint: PUT /api/v1/reviews/{id}

Examples:

curl -X PUT "https://simplistica.co/api/v1/reviews/{id}" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "title": "example_title",
       "description": "example_description",
       "dueDate": "example_dueDate"
     }'

Path Parameters:

• id (string) Required - The id of the resource

Request Body Schema:

Response Schema:

Example Response:

{
  "path": "/api/v1/reviews/{id}",
  "version": "v1",
  "timestamp": "2025-01-27T10:30:00.000Z",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "title": "example_title",
    "content": "example_content",
    "type": "document",
    "reviewStatus": "draft",
    "createdAt": "2025-01-27T10:30:00.000Z",
    "updatedAt": "2025-01-27T10:30:00.000Z"
  }
}

Responses:

• 200: Success
• 400: Bad Request
• 401: Unauthorized
• 500: Internal Server Error

Response Examples

Success Response

{
  "path": "/api/v1/reviews",
  "version": "v1",
  "timestamp": "2025-01-27T10:30:00.000Z",
  "data": null,
  "message": "Operation completed successfully"
}

Error Response

{
  "path": "/api/v1/reviews",
  "version": "v1",
  "timestamp": "2025-01-27T10:30:00.000Z",
  "error": "Validation Error",
  "message": "Required field 'email' is missing"
}

Common HTTP Status Codes

• 200: Success
• 201: Created
• 400: Bad Request (validation error)
• 401: Unauthorized (invalid or missing token)
• 404: Not Found (resource doesn’t exist)
• 429: Too Many Requests (rate limit exceeded)
• 500: Internal Server Error